ADBCHelper API overview

The ADBCHelper API is defined in the file apama_dir\adapters\monitors\ADBCHelper.mon. The API is implemented with the following events:

com.apama.database.DBUtil

com.apama.database.DBAcknowledge

The DBUtil event defines the actions that Apama applications call in order to interact with databases. The DBAcknowledge event is used by the ADBCHelper API to specify the success or failure for database actions that request an acknowledgment. Note if you specify the following lines in your code, you do not need to use the fully qualified name for DBUtil or DBAcknowledge.

using com.apama.database.DBUtil;
using com.apama.database.DBAcknowledge;

The basic steps for using the ADBCHelper API are described below.

To use the ADBCHelper API

1. Create an instance for the DBUtil event in your application code, for example:

com.apama.database.DBUtil db;

2. Call the setAdapterInstanceName action of DBUtil to identify the adapter instance, for example:

db.setAdapterInstanceName("JDBCAdapter1")

For more information, see Specifying the adapter instance.

3. Check whether the database is already open or is in the process of being opened. This step is optional, but it is good programming practice to check for these situations before calling an open event action by calling the isOpen action of DBUtil. This returns a boolean that specifies if the database is already open or in the process of being opened. For more information, see Checking to see if a database is open.

4. Call one of the DBUtil open actions to open the database. For more information on open actions, see Opening databases.

5. Call one or more DBUtil event actions, depending on the database task you want to implement:

Call a SQL query event action to retrieve data from the database, in either a result set or in Apama event format. For more information on query actions, see Issuing and stopping SQL queries.

Call a SQL command event action to add, update, or delete data in the database. For more information on SQL command actions, see Issuing SQL commands.

Optionally, if the autoCommit setting has been turned off, call a commit event action to commit database changes, or call a rollback event action to rollback uncommitted changes.

For more information on commit actions see Committing database changes.

For more information on rollback actions, see Performing rollback operations.

6. Create actions as required to handle returned result sets. If the query returns events, create listeners for events returned by the query. For more information on handling query results, see Handling query results for row data.

7. For action calls that request an acknowledgment, your application needs to do the following:

a. Create an instance of the com.apama.database.DBAcknowledge event.

Note, if your code contains the following line, you do not need to use the fully qualified name for DBAcknowledge.

using com.apama.database.DBAcknowledge;

b. Create a listener for the DBAcknowledge event that indicates when the DBUtil event action call is complete.

For more information, see Handling acknowledgments.

8. Create an action that handles errors that could occur during execution of a DBUtil event action call. For more information, see Handling errors.

9. Call the DBUtil event's close action to close the database. For information, see Closing databases.