Runtime components : Service components : Database services : Electronic Journal : Tasks
  
Tasks
See also
Using the Electronic Journal Schema Generator
Using journal objects
Using the Electronic Journal Schema Generator
This section describes the use of the JDBCJournalSchemaGenerator class.
Connecting to the database
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:
JDBCJournalSchemaGenerator jsg=new JDBCJournalSchemaGenerator();
jsg.connect(aDatabaseURL, aUser, aPassword)
This method sets the databaseConnection static attribute of the Schema Generator. The Schema Generator does not use the connection pooling facilities.
Creating the schema
After the connection to the database has been set, the application can then generate the tables by invoking one of the following methods:
void generateSchema(Vector entities, int numberOfGenerations,
String journalTableDefinition)
void generateSchema(Vector entities, int numberOfGenerations,
String journalTableDefinition, String aSchemaName)
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:
Vector entities= new Vector(3);
entities.addElement("User1");
entities.addElement("User2");
entities.addElement("User3");
jsg = new JDBCJournalSchemaGenerator;
String tableDefinition = "BRANCHNUMBER CHAR(4), AGREEMENTNUMBER
INTEGER, DUEDATE DATE";
jsg.generateSchema(entities, 6, tableDefinition);
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.
JDBCJournalSchemaGenerator arguments
schemaName
Contains the name of the journal schema. If you do not set this attribute, either explicitly or as an argument of the generateSchema method, the method uses the default value of DSESCHEM. If the userDefaultSchema attribute is set to true, the schemaName attribute is set to the name of the user creating the tables.
Default value: DSESCHEM
createSchema
Indicates whether the schema identified by schemaName must be explicitly created before the tables are created. If you set this attribute to false, the schema identified by schemaName must be already available in the database.
When the DBMS is Oracle or SQLServer 2000, always set this attribute to false, as the schemas are automatically created when a new database user is defined and no other schemas can be created.
When the DBMS is DB2 UDB for OS/390, set this attribute to false.
Default value: true
createIndex
Indicates whether the indexes for the journal tables must be explicitly created after creating the tables. DB2 for NT /AIX and Oracle automatically create indexes on the table primary keys when the table is created. DB2 for OS/390 requires an explicit creation of the indexes after it creates the tables so you must set this attribute to true for this environment.
Default value: false
userDefaultSchema
Indicates whether the journal tables are going to be created in the default schema of the database user that is connected to the database. If you set this attribute to true, the value of the schemaName attribute value is not used.
When the DBMS is Oracle, you can either set this attribute to true, in which case the DBMS creates the tables in the schema associated to the user executing the CREATE TABLE statement (the schema name matches the user name), or you can keep this attribute as false, in which case you must set the schemaName attribute to the schema of another user and set the createSchema attribute to false.
Default value: false
databaseName
Keeps the database name when working with DB2 UDB in OS/390. In this environment the database URL as set in the database connection has the following format: jdbc:db2os390:<location>. The <location> is the name of a shared database subsystem with different databases and storage groups defined in it. The databaseName attribute indicates which database contains the table. If you do not specify a value, the DBMS creates the journal tables in the default database within this location.
Using journal objects
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.
Adding records
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.
Retrieving records
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:
retrieveLastRecord - This method returns the last record, or null if the table is empty.
retrieveLastRecords - This method returns a Vector with the last n records in descending order of record number (n is passed to the method as an argument).
retrieveRecords - This method returns a Vector with all records that match the specified search string (passed as a method argument) in descending order of record number. This method can also accept as arguments a context and a Hashtable indexed collection format, and in this case this method unformats the retrieved records into the operation context as an indexed collection of keyed collections.
retrieveRecord - This method returns the record with the record number specified as an argument, or null if the record does not exist.
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.
Updating records
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:
updateLastRecord - This method updates the last record with the data provided as arguments. An exception is raised if there are no records in the journal table.
updateRecords - This method updates all records that match the specified search string with the data provided. Nothing is done if no records match the condition.
updateRecord - This method updates the record identified by the given record number. A DSEInvalidArgumentException is raised if the record does not exist.
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.
Go up to
Electronic Journal