As a subclass of the JDBCService class, the JDBCTable class has an external definition that allows any attribute of the JDBCTable object to be defined in the services definition file. All attributes of the JDBCTable class are defined externally, including those inherited from the JDBCService class, which in turn inherits from the Service class. A JDBCTable object is usually instantiated by providing the name of the service to the ServiceExternalizer. The ServiceExternalizer creates an instance of the class, identified by the name (in this case, a JDBCTable), and sets its attributes to the values read from the toolkit services definition file.
After instantiation of a JDBCTable service, a name and a tableName (which includes the schema name and the catalog name, if necessary) are assigned to the JDBCTable instance. The autoCommit attribute (set to false by default), the databaseURL attribute, and the autoConnect attribute are also set. The following connection attributes are also set: poolName, dataSourceName, JDBCDriver, and sharedConnection.
Before an application can work with the JDBCTable service, a connection to the database must be created. The connection is stored in the JDBCTable attribute databaseConnection. When access to the database table is requested by the application from the JDBCTable service, the service checks if a connection to the database already exists. If no connection has been previously established and the autoConnect attribute of the JDBCTable instance has been set to false, an exception is thrown. If the autoConnect attribute has been set to true, then a new connection to the database (located at the databaseURL attribute value of the JDBCTable instance) is automatically created.
If no automatic connection to the database is requested from the JDBCTable service, then the connection can be created in either of two ways:
▪ By calling one of the JDBCTable instance connect methods, as described in the Database Services documentation. This is the recommended way.
▪ By using the standard JDBC DriverManager interface to create the connection, and setting the databaseConnection attribute to the returned Connection instance. If this way is used, the application will not be able to use connection pooling or share the database connection between different database services instances. It is always suggested to use the service interface.
By default, a connection created by the JDBCTable instance connect method has its autoCommit attribute set to false, so that the application must commit or roll back the database transactions (using the provided commit() and rollback() methods). If this attribute is set to true, will be automatically done by the JDBCTable service, and each transaction will consist of one operation.
The following table describes the JDBCTable service behavior according to the attribute settings.
JDBCTable attribute settings
autoConnect
autoCommit
Service behavior
false
false
The application must request a database connection by calling the connect method, take care of committing and rolling back transactions, and explicitly close the connection by calling the disconnect() method.
false
true
The application must request a database connection by calling the connect() method and close the connection by calling the disconnect() method, but any changes to the database will be automatically committed or rolled back each time a database operation is requested.
true
false
The service definition must include the information needed to set the database connection automatically when the first operation on the database is requested (databaseURL and, optionally, userid, password, connection pooling information, and connection alias). The connection is created, and the databaseConnection attribute is set with this information. The application must commit and roll back all the changes made to the database through this connection, and when done must close the connection by calling the disconnect() method.
true
true
The service definition must include the information needed to set the database connection automatically when the first operation to the database is requested (databaseURL and, optionally, userid, password, connection pooling information, and connection alias). The connection is created, and the databaseConnection attribute is set with this information. In addition, after any operation, the changes are committed or rolled back automatically by the service, and the connection is closed. The application just must call the appropriate database access methods. In this environment, the JDBC drivers are expected to be loaded before any database operation is attempted.
Note This service is working with existing database tables, so the application must set the primary key column value for any record to be inserted in the table, define this column as part of the JDBCTable service format definition, and add the name mapping between the data field that will contain this primary key and the table column into the service definition if this is needed.