Apama 10.15.0 | Connecting Apama Applications to External Components | Standard IAF Plug-ins | The Database Connector IAF Adapter (ADBC) | Configuring the Apama database connector | Configuring an ADBC adapter
 
Configuring an ADBC adapter
 
Manually editing a configuration file
Configuring ADBC localization
Configuring ADBC Automatic Database Close
In Software AG Designer, an adapter's configuration file is opened in Apama's adapter editor. By default, the file is displayed in the editor's graphical view, which is accessed by clicking the Settings tab. The editor's other tabs are:
*Event Mapping — Displays the Visual Event Mapper where you can quickly map Apama event fields to columns in a database table.
*XML Source — Displays the configuration file's raw XML code.
*Advanced — Provides access to other configuration files associated with the adapter instance. These other files specify, for example, the instance's mapping rules, generated monitors and events responsible for storing events in a database, and named queries.
*To configure an instance of an ADBC adapter
1. In the Project Explorer, expand the project's Adapters node and open the adapter folder (ODBC Adapter, JDBC Adapter, or Sim File Adapter).
2. Double-click the entry for the adapter instance you want to configure. The configuration file opens in the adapter editor.
The Settings tab of the editor's graphical display presents configuration information. For an instance of the ADBC-JDBC adapter, the following tabs are shown:
*General Properties
*Advanced Properties
*Variables
For an instance of the ADBC-ODBC adapter, the display is similar but with fewer items in the above sections. For an instance of the ADBC-Sim file adapter, the display only shows the Variables section.
3. In the General Properties section, add or edit the following:
*Database type — This drop-down list allows you to select one of the database types from the list of certified vendors.
*Database URL — This specifies the complete URL of the database. By default, it uses the value of the DATABASE_LOCATION variable; for more information on this variable, see the description of the Variables section below.
*Driver — For the ADBC-JDBC adapter, this specifies the class name of the vendor's JDBC driver. By default, it uses the value of the JDBC_DRIVER_NAME variable; for more information on this variable, see the description of the Variables section below.
*Driver classpath — For the ADBC-JDBC adapter, this specifies the classpath for the vendor's driver jar file. By default, it uses the value of the JDBC_DRIVER_JARFILE variable; for more information on this variable, see the description of the Variables section below.
*Store batch size — This defines the number of events (rows) to persist using the ODBC/JDBC batch insert API. The use of this setting will significantly increase store performance, but it is not supported by all drivers. A value of 100 is appropriate and will provide good performance in most cases.
If store performance is critical, testing is required to find the optimal value for the data and driver being used. The default is 0 which disables the use of batch inserts.
*Store commit interval — This defines the interval in seconds before the ADBC adapter will automatically perform a commit for any uncommitted SQL command or store operations. The default value is 0.0, which disables the use of the timed commits.
*Auto commit — This controls the use of the ODBC/JDBC driver autocommit flag. The default value is false.
*Login timeout — This is a JDBC-specific property that allows you to change the default login timeout when com.apama.database.Connection.OpenDatabase or com.apama.database.Connection.OpenDatabaseShared are called.
*Query timeout — This is a JDBC-specific property that allows you to set the timeout for queries. The default value is 0. Keep in mind that different database vendors define a query timeout differently; see the documentation for these databases for more information.
Note: 
For more information on the interaction of the Auto commit, Store commit interval and Store batch size properties, see Committing database changes.
4. In the Advanced Properties section, add or edit information for the following:
*Transaction isolation level — This specifies what data is visible to statements within a transaction. The Default level uses the default level defined by the database server vender. To change this setting, enter the appropriate value. For JDBC and ODBC, the values can be READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, or SERIALIZABLE.
*Alternate discovery query — In most situations, an entry here is not required and the ADBC Discovery method lists the database available based on the DATABASE_LOCATION variable. In some cases, you may need to use a server vendor-specific SQL query statement to list the available databases, such as MySQL's SHOW DATABASES.
*Log inbound events — A boolean that specifies whether or not the application logs inbound ADBC API events with information such as the exact query or command being executed. Logging these events is used for diagnostic purposes and eliminates the need to turn on IAF debug logging. The default is false; do not log incoming events.
*Log outbound events — The same as Log inbound events except for outbound ADBC API events.
*Log commands — This property specifies whether or not the starts and completions of commands are written to the IAF log file. A value of true (the default) logs this information; a value of false turns logging off. This is useful in cases where logging the start and completion of a high rate of commands (many hundreds or thousands per second) does not add usable information to the log file.
*Log queries — This property behaves identically to the Log commands property except that it specifies whether or not to log the start and completion of queries.
*Flow control low water — This defines a threshold for the number of query responses not acknowledged by the ADBC flow control monitor before a query paused by Flow control high water is resumed. This is used by the ADBC query flow control system to ensure the correlator does not get overwhelmed, especially when performing a fast as possible playback. The default value is 6000.
*Flow control high water — This defines a maximum threshold for the number of query responses that have not been acknowledged by the ADBC flow control monitor. If this value is reached, the query will be paused until the number of outstanding acknowledgments decreases to the Flow control low water value. This is used by the ADBC query flow control system to ensure the correlator does not get overwhelmed, especially when performing a fast as possible playback. The default value is 15000.
*Query template config file — This specifies the file containing the query templates that are available to the application. By default, this uses a default template file created for the individual Apama project.
You can add or edit values of the following additional advanced properties by clicking the XML Source tab and modifying the text of the configuration file:
*NumericSeparatorLocale — This allows the numeric separator used in the adapter to be changed, if necessary, to match the one used by the correlator. See Configuring ADBC localization.
*CloseDatabaseIfDisconnected — This controls automatic closing of databases whose connection is found to be invalid. See Configuring ADBC Automatic Database Close.
*FixedSizeInsertBuffers — This is an ODBC-specific property that allows you to change the default buffer size used when the StoreData and StoreEvent actions perform batch inserts. Apama uses the FixedSizeInsertBuffers property along with the StoreBatchSize property to determine how large the insert buffers should be. The value specified by StoreBatchSize determines how many rows need to be buffered; the value specified by FixedSizeInsertBuffers controls the size of the buffers for the columns. The default true uses a fixed buffer size of 10K bytes for each column. If the value is changed to false, the size of the column buffers is determined dynamically by examining the database table into which the data will be inserted. Allowing the buffer size to be set dynamically can significantly reduce memory usage when performing batch inserts to database tables that contain hundreds of columns or when using a very large StoreBatchSize.
5. In the Variables section, add or edit the appropriate values for the following tokens:
*ADAPTER_CONFIG_DIR — JDBC and ODBC adapters only. This specifies the directory where the adapter's configuration files are located. This is automatically set by default.
*ADAPTER_INSTANCE_ID — This refers to the instance ID that is given to the adapter by Software AG Designer.
*ADAPTER_INSTANCE_NAME — This refers to the adapter name that is displayed in Software AG Designer.
*ADAPTERS_DIR — JDBC and ODBC adapters only. Specifies the directory where the adapter will look for the adapter files. By default, this is the Apama installation's adapters directory.
*ADAPTERS_JARDIR — JDBC adapter only. This specifies the directory where the Apama adapter jar files are located. By default, this is the Apama installation's adapters\lib directory.
*APAMA_HOME — This refers to the location of the Apama installation directory.
*APAMA_MSG_ENABLED — Apama elements can be enabled to define how IAF connects to the Apama correlator(s). The enabled attribute has valid values as true or false. This is based on the launch configuration.
*BUNDLE_DIR — Sim file adapter only. This specifies the directory where the adapter bundle is located.
*BUNDLE_DISPLAY_NAME — This refers to the adapter bundle name that is displayed in Software AG Designer.
*BUNDLE_INSTANCES — Sim file adapter only. This refers to the bundle instances files that Software AG Designer has copied to the project.
*CORRELATOR_HOST — This specifies the name of the host machine where the project's default correlator runs. This is automatically set by default.
*CORRELATOR_PORT — This specifies the port used by the correlator. This is automatically set by default.
*DATABASE_LOCATION — This specifies the location of the database for use with the ADBC Discovery API, for example, jdbc:mysql://localhost/trades.
*JDBC_DRIVER_JARFILE — JDBC adapter only. This specifies the name of the data source driver file, for example, a MySQL version X driver path might be specified at C:/Program Files/MySQL/mysql-connector-java-X/mysql-connector-java-X.jar.
*JDBC_DRIVER_NAME — JDBC adapter only. This specifies the class name of the driver, such as com.mysql.jdbc.Driver.
*MAPPING_INSTANCE_FILE — JDBC and ODBC adapters only. This refers to the file name for the adapter's mapping configurations when configured through Software AG Designer.
*UM_CONFIGURATION_FILE — This refers to the configuration file that is used when configuring the IAF to communicate via Universal Messaging. See also Configuring IAF adapters to use Universal Messaging.
Note: 
Use of Universal Messaging from the IAF is deprecated and will be removed in a future release.
*UM_MSG_ENABLED — This refers to the flag that indicates whether the IAF is configured to use Universal Messaging.
Note: 
Use of Universal Messaging from the IAF is deprecated and will be removed in a future release.
6. Specify the event mapping rules of the configuration that are specific to your application using the adapter editor's Visual Event Mapper, available on the Event Mapping tab. For more information on specifying mapping rules, see The Visual Event Mapper.