This section describes the use of the JDBCJournalSchemaGenerator class.

The JDBCJournalSchemaGenerator class uses its own connection to the database. So, before this class is used but after creating a new instance, a connect() method must be run, using as an argument the database URL where the journal tables are to be created. The following is an example of requesting a connection to the database:

This method sets the databaseConnection static attribute of the Schema Generator. The Schema Generator does not use the connection pooling facilities.

After the connection to the database has been set, the application can then generate the tables by invoking one of the following methods:

The application can specify the schema name, either by setting the schemaName attribute of the JDBCJournalSchemaGenerator instance (and then using the first method to generate the tables) or by passing the attribute as an argument to the generateSchema method (using the second method). If the application does not provide the schema name, the method uses the default value of DSESCHEM. If the schema does not have to be explicitly created in the database, the application must set the createSchema attribute to false before calling the generateSchema method (as when using DB2 UDB for OS/390 as the DBMS). In this situation, the JDBCJournalSchemaGenerator expects the schema identified by the schemaName attribute to be defined and accessible in the database.

If the journal tables are created in the default schema associated with a database user (in most DBMS such as DB2 and Oracle, when the DBMS creates a user, it assigns the user a default schema that has a name matching the user identification), the application must set the userDefaultSchema attribute to true before calling the generateSchema method This automatically sets the schemaName to the user name.

The first argument for both methods is a collection of strings with the names of the desired entities. The Vector of entities is mandatory, even if the journal is working with a unique entity. The second argument is the desired number of journal generations to be kept in the database. The third argument is a string with the SQL definition of the journal tables (without the record number DSERECN primary key, which is automatically added to the table definition).

The following is an example:

This sample creates 18 tables for the schema DSESCHEM with columns BRANCHNUMBER, AGREEMENTNUMBER, and DUEDATE, plus the extra column DSERECN. In addition, it creates the control table.

If you are using DB2 UDB for OS/390, you must specify the database name where the journal tables are created, because the database URL refers to a location where different databases can be defined; you can do this by using the setDatabaseName method. If the databaseName attribute is not null and not blank, the JDBCJournalSchemaGenerator creates the tables in the database specified by the databaseName attribute value within the location set in the database URL specification.

In addition, in a DB2 UDB for OS/390 environment, the JDBCJournalSchemaGenerator must explicitly create the indexes on the table's primary keys after it has created the tables. To do this, set the createIndex attribute to true.

As a subclass of the Service class, the JDBCJournal class has an externalizer that allows it to define any journal object attributes in an definitions file (these attribute values are used when the journal object is instantiated), and it inherits all Service attributes, as, for instance, the name attribute that allows it to request a specific journal service instance in the hierarchy of contexts.

After a journal service is instantiated by using the toolkit services externalizer and the context hierarchy, a name and a schema are assigned to the journal. The application must then set the entity name for that journal instance, request a database connection, and send the open() message to activate the current journal generation for that specific entity. After that, a current journal exists and is ready to be worked with.

When the application is done, the close() message can be sent to the journal. This operation sets the instance to inactive. This call is needed if at any time the same journal instance is requested to work with a different entity: for instance, if the entity is a user identification, and different users can work from the same workstation by changing the user and without closing the application. In that case, the journal instance must be closed and the entity name changed to the new value. The journal instance then needs to be opened again to continue working. You can query the current state of a journal object at any time by calling the isActive() method.

While a journal object is active, an application can add, retrieve, and update records. Transactions can be handled automatically by setting the autoCommit attribute to true, in which case every add or update is followed automatically by a commit.

The entity assigned to an active journal, the name of the journal service, the database connection, and the database connection properties (database URL, JDBCDriver, poolName, dataSourceName, and sharedConnection attributes) cannot be changed while the journal is active. Therefore, a close() message needs to be sent before any of these attributes can be changed.

To add a record to the Electronic Journal, call an addRecord method on an active journal object. The format of the record is defined at customization time and is implementation-dependent. The formatting facilities of the toolkit can be used, so the record can be built from different data fields located in different areas of the operation context. Each concrete journal implementation provides a HashtableFormat external definition that describes which data fields the Journal must record and how they must be formatted before the journal record is constructed. A record is obtained by sending the format(Context aContext) message to the specific HashtableFormat object.

The Journal service will accept as addRecord() arguments either the data already formatted, or a context and a format name, or a context and a format object. In the last two cases, the service will call the format() method of the format object to build the journal record.

The last record number is maintained by the journal object in a private instance variable. It is initialized in the open() method and increased by one after each successful add operation. The addMethod() returns this last record number, which can then be used to update or retrieve the last record for the current journal, meaning the last record added to the journal table that has been assigned for the current journaling date to a specific entity. Note that an entity can group a number of applications working with the same journal service instance and then access one journal table. In this case, the record number specific to an application will not correspond with the last record in the current journal but with the last record this application has added.

Several methods are available for retrieving records from the Electronic Journal. The returned records can be unformatted by sending the unformat(Hashtable aDataHashtable, Context aContext) message to the format object, which updates the data elements specified in the format definition within the operation context. The Journal service allows the application to do the following:

These methods return, by default, all the columns defined in the database table for the retrieved records. An additional argument can be passed to all the methods to specify which columns are to be retrieved.

Several methods are available for updating records in the Electronic Journal. All of them accept a formatted record or a context instance and a format name, and work the same way as the addRecord methods. The Journal service allows the application to do the following:

These methods, by default, update all the columns defined in the database table for the selected records, and they expect values for all the columns to be found either in the data hash table as new values or in the operation context. An additional argument can be passed to all the methods to specify which columns are to be updated.