JMS/XLA Concepts and Features

JMS/XLA Concepts

You can use the TimesTen JMS/XLA API, supported by TimesTen Classic, to monitor TimesTen for changes to specified tables in a local database and to receive real-time notification of these changes. The primary purpose of JMS/XLA is as a high-performance, asynchronous alternative to triggers.

TimesTen JMS/XLA support includes two JMS providers: one based on the Jakarta Messaging API version 1.1 and another based Java Message Service API version 1.1. The Jakarta Messaging API version 1.1 is functionally equivalent to the Java Message Service API version 1.1 except for using the namespace jakarta.jms instead of javax.jms.

JMS/XLA implements JMS interfaces to make the functionality of the TimesTen Transaction Log API (XLA) available to Java applications. JMS/XLA API is a wrapper for XLA, which obtains update records directly from the transaction log buffer or transaction log files, so the records are available until they are read. XLA also allows multiple readers to access transaction log updates simultaneously. See XLA and TimesTen Event Management in Oracle TimesTen In-Memory Database C Developer's Guide.

JMS/XLA uses the JMS publish-subscribe interface to provide access to XLA updates. Subscribe to updates by establishing a JMS Session instance that provides a connection to XLA and then creating a durable subscriber (TopicSubscriber). You can receive and process messages synchronously through the subscriber, or you can implement a listener (MessageListener) to process the updates asynchronously.

JMS/XLA is designed for applications that want to monitor a local database. TimesTen and the application receiving the notifications must reside on the same system.

Note:

In the unlikely event that the TimesTen replication solutions described in Overview of TimesTen Replication in the Oracle TimesTen In-Memory Database Replication Guide do not meet your needs, it is possible to use JMS/XLA to build a custom data replication solution.

How XLA Reads Records from the Transaction Log

As applications modify a database, TimesTen generates transaction log records that describe the changes made to the data and other events such as transaction commits.

New transaction log records are always written to the end of the transaction log buffer as they are generated. Transaction log records are periodically flushed in batches from the log buffer in memory to transaction log files on the file system.

Applications can use XLA to monitor the transaction log for changes to the database. XLA reads through the transaction log, filters the log records, and delivers XLA applications with a list of transaction records that contain the changes to the tables and columns of interest.

XLA sorts the records into discrete transactions. If multiple applications are updating the database simultaneously, transaction log records from the different applications are interleaved in the transaction log.

XLA transparently extracts all transaction log records associated with a particular transaction and delivers them in a contiguous list to the application.

Only the records for committed transactions are returned. They are returned in the order in which their final commit record appears in the transaction log. XLA filters out records associated with changes to the database that have not yet committed.

If a change is made but then rolled back, XLA does not deliver the records for the rolled back transaction to the application.

Consider the transaction log illustrated in Figure 3-1 and the example that follows, illustrating most of these XLA concepts.

Figure 3-1 Records Extracted from the Transaction Log

Description of "Figure 3-1 Records Extracted from the Transaction Log"

In this example, the transaction log contains the following records:

CT1 - Application C updates row 1 of table W with value 7.7.
BT1 - Application B updates row 3 of table X with value 2.
CT2 - Application C updates row 9 of table W with value 5.6.
BT2 - Application B updates row 2 of table Y with value "XYZ".
AT1 - Application A updates row 1 of table Z with value 3.
AT2 - Application A updates row 3 of table Z with value 4.
BT3 - Application B commits its transaction.
AT3 - Application A rolls back its transaction.
CT3 - Application C commits its transaction.

An XLA application that is set up to detect changes to tables W, Y, and Z would see the following:

BT2 and BT3 - Update row 2 of table Y with value "XYZ" and commit.
CT1 - Update row 1 of table W with value 7.7.
CT2 and CT3 - Update row 9 of table W with value 5.6 and commit.

This example demonstrates the following:

Transaction records for application B and application C all appear.
Though the records for application C begin to appear in the transaction log before those for application B, the commit for application B (BT3) appears in the transaction log before the commit for application C (CT3). As a result, the records for application B are returned to the XLA application ahead of those for application C.
The application B update to table X (BT1) is not presented because XLA is not set up to detect changes to table X.
The application A updates to table Z (AT1 and AT2) are never presented because it did not commit and was rolled back (AT3).

XLA and Materialized Views

You can use XLA to track changes to both tables and materialized views.

A materialized view provides a single source from which you can track changes to selected rows and columns in multiple detail tables. Without a materialized view, the XLA application would have to monitor and filter the update records from all of the detail tables, including records reflecting updates to rows and columns of no interest to the application.

In general, there are no operational differences between the XLA mechanisms used to track changes to a table or a materialized view.

For more information about materialized views, see the following:

CREATE MATERIALIZED VIEW in Oracle TimesTen In-Memory Database SQL Reference
Understanding Materialized Views in Oracle TimesTen In-Memory Database Operations Guide

XLA Bookmarks

This section describes XLA bookmarks.

How Bookmarks Work

An XLA bookmark marks the read position of an XLA subscriber application in the transaction log. Bookmarks facilitate durable subscriptions, enabling an application to disconnect from a topic and then reconnect to continue receiving updates where it left off.

When you create a message consumer for XLA, you always use a durable TopicSubscriber. The subscription identifier you specify when you create the subscriber is used as the XLA bookmark name. When you use the ttXlaSubscribe and ttXlaUnsubscribe built-in procedures through JDBC to start and stop the XLA subscription for a table, you explicitly specify the name of the bookmark to be used.

Bookmarks are reset to the last read position whenever an acknowledgment is received. For more information about how update messages are acknowledged, see the XLA Update Acknowledgments.

You can remove a durable subscription by calling unsubscribe() on the JMS Session object. This deletes the corresponding XLA bookmark and forces a new subscription to be created when you reconnect. For more information see "Delete Bookmarks".

A bookmark subscription cannot be altered when it is in use. To alter a subscription, you must close the message consumer, alter the subscription using ttXlaSubscribe and ttXlaUnsubscribe, and open the message consumer.

Note:

You can also use the ttXlaBookmarkCreate TimesTen built-in procedure to create bookmarks. See ttXlaBookmarkCreate in Oracle TimesTen In-Memory Database Reference.

Replicated Bookmarks

If you are using an active standby pair replication scheme, you have the option of using replicated bookmarks, according to the replicatedBookmark attribute of the <topic> element in the jmsxla.xml file.

See JMS/XLA Configuration File and Topics.

For a replicated bookmark, operations on the bookmark are replicated to the standby database as appropriate, assuming there is suitable write privilege for the standby. This enables more efficient recovery of your bookmark positions if a failover occurs.

When you use replicated bookmarks, steps must be taken in the following order:

Create the active standby pair replication scheme. (This is accomplished by the create active standby pair operation, or by the ttCWAdmin -create command in a Clusterware-managed environment.)
Create the bookmarks.
Subscribe the bookmarks.
Start the active standby pair, at which time duplication to the standby occurs and replication begins. (This is accomplished by the ttRepAdmin -duplicate command, or by the ttCWAdmin -start command in a Clusterware-managed environment.)

Note:

Alternatively, if you use ttXlaBookmarkCreate to create a bookmark, that function has a parameter for specifying a replicated bookmark.
If you specify replicated bookmarks in the JMS/XLA configuration file, JMS/XLA will create and subscribe to the bookmarks when the application is started. (Also see JMS/XLA Configuration File and Topics.)

Be aware of the following usage notes:

The position of the bookmark in the standby database is very close to that of the bookmark in the active database; however, because the replication of acknowledge operations is asynchronous, you may see a small window of duplicate updates when there is a failover, depending on how often acknowledge operations are performed.
It is permissible to drop the active standby pair scheme while replicated bookmarks exist. The bookmarks of course cease to be replicated at that point, but are not deleted. If you subsequently re-enable the active standby pair scheme, these bookmarks are automatically added to the scheme.
You cannot delete replicated bookmarks while the replication agent is running.
You can only read and acknowledge a replicated bookmark in the active database. Each time you acknowledge a replicated bookmark, the acknowledge operation is asynchronously replicated to the standby database.

XLA Bookmarks and Transaction Log Holds

You should be aware that when XLA is in use, there is a hold on TimesTen transaction log files until the XLA bookmark advances.

The hold prevents transaction log files from being purged until XLA can confirm it no longer needs them. If a bookmark becomes stuck, which can occur if an XLA application terminates unexpectedly or disconnects without first deleting its bookmark or disabling change tracking, the log hold persists and there may be an excessive accumulation of transaction log files. This accumulation may result in file system space being filled.

See Monitoring Accumulation of Transaction Log Files in Oracle TimesTen In-Memory Database Operations Guide.

JMS/XLA Configuration File and Topics

To connect to XLA, establish a connection to a JMS Topic object that corresponds to a particular database. The JMS/XLA configuration file provides the mapping between topic names and databases.

You can specify a replicated bookmark by setting replicatedBookmark="yes" in the <topic> element when you specify the topic. The default setting is "no". Also see XLA Bookmarks.

By default, JMS/XLA looks for a configuration file named jmsxla.xml in the current working directory. If you want to use another name or location for the file, you must specify it as part of the environment variable in the InitialContext class and add the location to the classpath.

The following code specifies the configuration file as part of the environment variable in the InitialContext class.

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,
  "com.timesten.dataserver.jmsxla.SimpleInitialContextFactory");
env.put(XlaConstants.CONFIG_FILE_NAME, "/newlocation.xml");
InitialContext ic = new InitialContext(env);

The JMS/XLA API uses the class loader to locate the JMS/XLA configuration file if XlaConstants.CONFIG_FILE_NAME is set. In this example, the JMS/XLA API searches for the newlocation.xml file in the top directory in both the location specified in the CLASSPATH environment variable and in the JAR files specified in the CLASSPATH variable.

The JMS/XLA configuration file can also be located in subdirectories, as follows:

env.put(XlaConstants.CONFIG_FILE_NAME,
"/com/mycompany/myapplication/deepinside.xml");

In this case, the JMS/XLA API searches for the deepinside.xml file in the com/mycompany/myapplication subdirectory in both the location specified in the CLASSPATH environment variable and in the JAR files specified in the CLASSPATH variable.

The JMS/XLA API uses the first configuration file that it finds.

A topic definition in the configuration file consists of a name, a connection string, and a prefetch value that specifies how many updates to retrieve at a time. For example, this configuration maps the DemoDataStore topic to the TestDB DSN:

<xlaconfig>
  <topics>
    <topic name="DemoDataStore"
      connectionString="DSN=TestDB"
      xlaPrefetch="100" />
  </topics>
</xlaconfig>

A topic definition can also specify whether a replicated bookmark should be used. The following repeats the preceding example, but with a replicated bookmark.

<xlaconfig>
  <topics>
    <topic name="DemoDataStore"
      connectionString="DSN=TestDB"
      xlaPrefetch="100" replicatedBookmark="yes" />
  </topics>
</xlaconfig>

XLA Updates

Applications receive XLA updates as JMS MapMessage objects. A MapMessage object contains a set of typed name and value pairs that correspond to the fields in an XLA update header.

You can access the message fields using the MapMessage getter methods. The getMapNames() method returns an Enumeration object that contains the names of all of the fields in the message. You can retrieve individual fields from the message by name. All reserved field names begin with two underscores, for example __TYPE.

All update messages have a __TYPE field that indicates what type of update the message contains. The types are specified as integer values. As a convenience, you can use the constants defined in com.timesten.dataserver.jmsxla.XlaConstants to compare against the integer types. The supported types are described in Table 3-1.

Table 3-1 XLA Update Types

Update type	Description
`INSERT`	A row has been added.
`UPDATE`	A row has been modified.
`DELETE`	A row has been removed.
`COMMIT_ONLY`	A transaction has been committed.
`CREATE_TABLE`	A table has been created.
`DROP_TABLE`	A table has been dropped.
`CREATE_INDEX`	An index has been created.
`DROP_INDEX`	An index has been dropped.
`ADD_COLUMNS`	New columns have been added to the table.
`DROP_COLUMNS`	Columns have been removed from the table.
`CREATE_VIEW`	A materialized view has been created.
`DROP_VIEW`	A materialized view has been dropped.
`CREATE_SEQ`	A sequence has been created.
`DROP_SEQ`	A sequence has been dropped.
`CREATE_SYNONYM`	A synonym has been created.
`DROP_SYNONYM`	A synonym has been dropped.
`TRUNCATE`	All rows in the table have been deleted.

For more information about the contents of an XLA update message, see "JMS/XLA MapMessage Contents".

XLA Update Acknowledgments

This section discusses acknowledgment of updates in JMS/XLA.

XLA Acknowledgment Mechanism

The XLA acknowledgment mechanism is designed to ensure that an application has not only received a message, but has successfully processed it.

Acknowledging an update permanently resets the application XLA bookmark to the last record that was read. This prevents previously returned records from being reread, ensuring that an application receives only new batches of records if the bookmark is reused when an application reconnects to XLA.

JMS/XLA can automatically acknowledge XLA update messages, or applications can choose to acknowledge messages explicitly. You specify how updates are to be acknowledged when you create the Session object.

XLA Acknowledgment Modes

JMS/XLA supports three acknowledgment modes.

AUTO_ACKNOWLEDGE: In this mode, updates are automatically acknowledged as you receive them. Each message is delivered only once. Duplicate messages are not sent, so messages might be lost if there is an application failure. Messages are always delivered and acknowledged individually, so JMS/XLA does not prefetch multiple records. The xlaprefetch attribute in the topic is ignored.
DUPS_OK_ACKNOWLEDGE: In this mode, updates are automatically acknowledged, but duplicate messages might be delivered when there is an application failure. JMS/XLA prefetches records according to the xlaprefetch attribute specified for the topic and sends an acknowledgment when the last record in a prefetched block is read. If the application fails before reading all of the prefetched records, all of the records in the block are presented to the application it restarts.

See JMS/XLA Configuration File and Topics for examples setting xlaprefetch.
CLIENT_ACKNOWLEDGE: In this mode, applications are responsible for acknowledging receipt of update messages by calling acknowledge() on the MapMessage instance. JMS/XLA prefetches records according to the xlaprefetch attribute specified for the topic.

The following example sets the acknowledgment mode:

Session session = connection.createSession (false, Session.CLIENT_ACKNOWLEDGE);

Also see Reduce Frequency of Update Acknowledgments.

Prefetching Updates

Prefetching multiple update records at a time is more efficient than obtaining each update record from XLA individually.

Because updates are not prefetched when you use AUTO_ACKNOWLEDGE mode, it can be slower than the other modes. If possible, you should design your application to tolerate duplicate updates so you can use DUPS_OK_ACKNOWLEDGE, or explicitly acknowledge updates. Explicitly acknowledging updates usually yields the best performance, if you can avoid acknowledging each message individually.

Acknowledging Updates

To explicitly acknowledge an XLA update, call acknowledge() on the update message.

Acknowledging a message implicitly acknowledges all previous messages. Typically, you receive and process multiple update messages between acknowledgments. If you are using the CLIENT_ACKNOWLEDGE mode and intend to reuse a durable subscription in the future, you should call acknowledge() to reset the bookmark to the last-read position before exiting.

XLA System Privilege

An XLA user must have the XLA system privilege.

Any XLA functionality requires the system privilege XLA. This includes connecting to TimesTen (which also requires the CREATE SESSION privilege) as an XLA reader and executing the TimesTen XLA built-in procedures ttXlaBookmarkCreate, ttXlaBookmarkDelete, ttXlaSubscribe, and ttXlaUnsubscribe, all of which are documented in Built-In Procedures in Oracle TimesTen In-Memory Database Reference.
A user with the XLA privilege has capabilities equivalent to the SELECT ANY TABLE, SELECT ANY VIEW, and SELECT ANY SEQUENCE system privileges.

XLA Limitations

Be aware of XLA limitations when you use TimesTen JMS/XLA.

JMS/XLA is available on all platforms supported by TimesTen. However, XLA does not support data transfer between different platforms.
JMS/XLA support for LOBs is limited. See Monitoring Tables for Updates.
JMS/XLA does not support applications linked with a driver manager library or the client/server library.
An XLA reader cannot subscribe to a table that uses in-memory column-based compression.
For autorefresh cache groups, the change-tracking trigger on Oracle Database does not have column-level resolution. (To have that would be very expensive.) Therefore the autorefresh feature updates all the columns in the row, and XLA can only report that all the columns have changed, even if data did not actually change in all columns.

JMS/XLA and Oracle GDK Dependency

The JMS/XLA API uses orai18n.jar, part of the Oracle Globalization Development Kit (GDK) for translating from the database character set specified by the DatabaseCharacterSet attribute to UTF-16 encoding.

The JMS/XLA API supports a specific version of the GDK with each TimesTen release. If JMS/XLA finds other versions of the GDK loaded in the JVM, it displays a severe warning and continues processing. You can find out the GDK version supported by JMS/XLA by entering the following commands:

$ cd timesten_home/install/lib
$ java -cp ./orai18n.jar oracle.i18n.util.GDKOracleMetaData -version

Also see Setting the Classpath for Java Development.

Note:

The path timesten_home/install is a symbolic link to installation_dir.