ADBCHelper API Overview

Deploying and Managing Apama Applications > Using the Apama Database Connector > The ADBCHelper Application Programming Interface > 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 acknowledgement. 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:

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

com.apama.database.DBUtil db;

2. Call the DBUtil setAdapterInstanceName action to identify the adapter instance. This step is only required if the adapter instance name is not the default, INSTANCE_1. This action is necessary, for example, if the project uses multiple adapter instances.

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 DBUtil isOpen action. 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 acknowledgement, your application needs to do the following:

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

Note, if your code contains the line using com.apama.database.DBAcknowledge;, you do not need to use the fully qualified name for DBAcknowledge.

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

For more information on handling acknowledgments, see Handling acknowledgments.

8. Create an action that handles errors that could occur during execution of a DBUtil event action call.

For more information on handling errors, see Handling errors.

9. Call the DBUtil event's close action to close the database.

For information on closing databases, see Closing databases.

Copyright © 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.