The JDBCStoreSchemaGenerator is normally used by a database administration application, which will create and modify the STORE table needed by the applications using the store. The database administration application calls the JDBCStoreSchemaGenerator class, which provides the methods to perform this kind of administrative task. The JDBCStoreSchemaGenerator can therefore be considered independent from the application that is requesting the store services. The application must take care, before requesting the database connection, to register and load the specific JDBC driver needed to work with the database.
The following lines are column definitions for a sample database administration application.
ACCOUNT_NUMBER CHAR(14)
AMOUNT INTEGER
DESCRIPTION VARCHAR(50)
THE_DATE DATE
The following is the code for the runnable class StoreTableManagement, which builds a table using these column definitions:
public class StoreTableManagement { /** * This class creates a store table that will later on be used by the applications requesting the store services */
// 2) Connect to Database... try { ssg.loadDriver("COM.ibm.db2.jdbc.net.DB2Driver"); ssg.connect("jdbc:db2://myhs:8888/mydb","MYUSER","MYPASS"); } catch (Exception e ) { e.printStackTrace(); return; }
// 3) Create the store table String tableDefinition = "ACCOUNT_NUMBER CHAR(14), AMOUNTINTEGER, DESCRIPTION VARCHAR(50), THE_DATE DATE"; String tableName = "StoreTable"; try { // Generating Database Table... ssg.generateTable(tableName, tableDefinition);> // Close the database connection ssg.disconnect(); } // End try catch (Exception e ) { e.printStackTrace(); } }
JDBCStore code example
Once the STORE table is created, as shown in the example using JDBCStoreSchemaGenerator (see the JDBCStoreSchemaGenerator code example), any applications that request the store services to access the database table can be started. Before requesting the database connection, all of these applications must register and load the specific JDBC driver needed to work with the database, which varies according to your database environment. Remember that the registration and loading of the appropriate JDBC driver can be done by calling a store service instance method.
The following is a sample of an application working with the Store service provided by the toolkit, and of the XML files needed to run it. The sample is implemented for a local environment, but it can be easily adapted to a client/server environment by implementing the toolkit client operation, which will start the server operation calling for the Store service.
The following application uses the Store service to retain information about an operation that could not be executed, and to later retrieve this operation information and start a forwarding process:
public class StoreApplication { public static void main(String args[]) throws java.io.IOException, DSEObjectNotFoundException { Context storeContext; HashtableFormat storeFormat= null; StoreService store = null;
// Setting the toolkit environment if not previously done if(!InitManager.isInitialized()){ InitManager.reset("file:///c:\\btt\\btt.xml"); } try { storeContext = ContextFactory.createContext("myStoreContext"); System.out.println(">>> Creating a Store Instance..."); store = (StoreService)Service.readObject("myStoreName");
// Connect to the database
store.loadDriver(); store.connect("jdbc:db2://myhostname:8888/mydb", "MYUSER","MYPASSWORD"); if (store.isActive() == false) { store.open(); } int nbrOfRecords = 3;
// Filling the Store Table with 3 records... for (int i = 1; i <= nbrOfRecords ; i++) { storeContext.setValueAt("account_number", "0007000" + i); storeContext.setValueAt("amount",new Integer(200000 + i)); storeContext.setValueAt("date", new java.sql.Date(98,4, 16)); storeContext.setValueAt("DESCRIPTION", "Adding record " + i + " in Store instance 1..."); storeFormat = (HashtableFormat) FormatElement.readObject("storeFormatName");
// Call the format method with argument the operation context Hashtable dataTable = new Hashtable(); dataTable = (Hashtable) storeFormat.format(storeContext);
// Adding a record to the Store..."); store.addRecord(dataTable); } // End for
public class ForwarderApplication { public static void main(String args[]) throws java.io.IOException, DSEObjectNotFoundException { Context storeContext; HashtableFormat storeFormat= null; StoreService store = null;
// Setting the toolkit environment if not previously done if(!InitManager.isInitialized()){ InitManager.reset("file:///c:\\btt\\btt.xml"); } try { storeContext = ContextFactory.createContext ("myStoreOperationContext"); System.out.println(">>> Creating a Store Instance..."); store = (StoreService)Service.readObject("myStoreName"); storeFormat = (HashtableFormat) FormatElement.readObject("storeFormatName"); // Connect to the database
store.loadDriver(); store.connect("jdbc:db2://myhostname:8888/mydbe", "MYUSER","MYPASSWORD"); if (store.isActive() == false) { store.open(); } aDataHashtable = store.retrieveFirstRecordForForwarding(); // here the forwarder application will send the pending // operation to be executed. The application will wait // for the operation execution result; if the operation was // successfully executed, then it will commit the changes in the database store.commit(); // if the operation was not successfully executed, then it // is the forwarder's responsibility to keep this operation // information and retry later or, if it is because the session // with the host is down again, the application can roll back // the database changes // store.rollback(); // the process will be repeated until the last database record // is retrieved while ( (aDataHashtable=store.retrieveNextRecordForForwarding()) != null) { //do the same as for the first record } // End while store.deleteAllRetrievedForForwarding(); store.commit(); // Disconnecting JDBCStore instance from Database store.disconnect(); store.close(); } // End try catch (Exception e ) {System.out.println(e.getMessage()); try { store.disconnect(); store.close(); } catch (Exception ex) { System.out.println(ex.getMessage()); } return } } }
Store exceptions
The Store service throws the following exceptions:
DSEInvalidRequestException
The current state of the object is not valid for the method being called.
Action: Check for the store state and set it to "active" before requesting any database operation.
DSEInternalErrorException
Internal data is inconsistent.
Action: Report the error through the standard reporting channels to the toolkit support.
DSEInvalidArgumentException
One of the arguments in the called method is invalid: it is an instance of an unexpected class or it is outside the expected range.
Action: Check the value of the arguments.
DSEObjectNotFoundException
An exception occurred when accessing the database.
Action: Refer to the SQL documentation to take the appropriate action for the specific error number and message.
DSEException
An exception has been returned when requesting or releasing a connection from a pool of connections or when trying to share a connection.
Action: Verify that the connection pooling is available. Check the maximum number of connections defined and the connection timeout, and consider setting new values that can avoid this exception in future.
Store external definitions
The Store service has the following data externalized in the Services file:
JDBCStore tag attributes
id
Name of the JDBCStore attribute.
autoCommit
Specifies whether automatic commit is performed after each store write/update. Possible values are:
true
false (default)
catalog
Name of the database catalog in which the table is created (if it applies to the DBMS being used). It may be case-sensitive based on the DBMS specifications.
schema
Name of the table schema in the database (if it applies to the DBMS being used). It may be case-sensitive based on the DBMS specifications.
table
Name of the table used by the store object. It may be case-sensitive based on the DBMS specifications.
JDBCDriver
Name of the JDBC Driver that the service will use to request the connection to the database and to execute the SQL statements.
poolName
Name of the connection manager pool containing the connection type you want. Consult the WebSphere administrator for the pool name.
dataSourceName
The DataSource object name to be used by all requests to get a connection. This should be specified when working with the connection pooling provided by WebSphere Application Server or with any other JDBC implementation of the connection pooling. This name requires a context part and a logical name part, since it will be used to do a lookup in the naming context. A typical string might look something like "jdbc/sample," where the context is "jdbc" and the logical name is "sample." This information can be supplied by the WebSphere administrator, and it identifies the DataSource object placed in the naming service.
sharedConnection
Alias of the connection the service wants to share with other JDBC services instances.
singleTable
Determines whether the JDBCStore instance being instantiated and initialized uses the same table as other JDBCStore instances. The attribute's value can be true or false (default). Set this value to true if the application uses a generic pool when requesting a Store service instance.
statementPoolSize
Defines the dimension of the statements pool. The default value is 32. Increase the value of the attribute to improve system performance or reduce the value to prevent exhausting system resources.
column tag attributes
id
Name of table column.
dataName
Name of context data field or name of the key that keeps the data field value.
The tag column is used to map a specific data field in the operation context to a column in the database table in cases where the data field and the column do not have the same name, or where the data field is not located in the first level of the operation context. The dataName tag attribute can directly hold the data field name or a key name if a KeyedObject format is being used inside the Hashtable format definition.