6 JMS/XLA Reference

This chapter provides reference information for the JMS/XLA API. It includes the following topics:

JMS/XLA MapMessage contents
DML event data formats
DDL event data formats
Data type support
JMS classes for event handling
JMS/XLA replication API
JMS message header fields

Note:

"Access control impact on XLA" introduces the effects of TimesTen access control features on XLA functionality.

JMS/XLA Map Message contents

A javax.jms.MapMessage contains a set of typed name and value pairs that correspond to the fields in an XLA update header, which is published as the C structure ttXlaUpdateDesc_t. The fields contained in a MapMessage instance depend on what type of update it is.

XL A update types

Each MapMessage returned by the JMS/XLA API contains at least one name and value pair, __TYPE (with 2 underscores), that identifies the type of update described in the message as an integer value. 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. Table 6-1 shows the supported types.

Table 6-1 XLA update types

Type	Description
`ADD_COLUMNS`	Indicates that columns have been added.
`COMMIT_FIELD`	The name of the field in a message that contains a commit.
`COMMIT_ONLY`	Indicates that a commit has occurred.
`CONTEXT_FIELD`	The n ame of the field in a message that contains the context value passed to the `ttApplicationContext` procedure as a byte array.
`CREATE_INDEX`	Indicates that an index has been created.
`CREATE_SEQ`	Indicates that a sequence has been created.
`CREATE_SYNONYM`	Indicates that a synonym has been created.
`CREATE_TABLE`	Indicates that a table has been created.
`CREATE_VIEW`	Indicates that a view has been created.
`DELETE`	Indicates that a row has been deleted.
`DROP_COLUMNS`	Indicates that columns have been dropped.
`DROP_INDEX`	Indicates that an index has been dropped.
`DROP_SEQ`	Indicates that a sequence has been dropped.
`DROP_SYNONYM`	Indicates that a synonym has been dropped.
`DROP_TABLE`	Indicates that a table has been dropped.
`DROP_VIEW`	Indicates that a view has been dropped.
`FIRST_FIELD`	The name of the field that contains the flag that indicates the first record in a transaction.
`INSERT`	Indicates that a row has been inserted.
`MTYP_FIELD`	The name of the field in a message that contains type information.
`MVER_FIELD`	The name of the field in a message that contains the transaction log file number of the XLA record.
`NULLS_FIELD`	The name of the field in a message that contains the list of fields that have null values.
`REPL_FIELD`	The name of the field in a message that contains the flag that indicates that the update was applied by replication.
`TBLNAME_FIELD`	The name of the field in a message that contains the table name.
`TBLOWNER_FIELD`	The name of the field in a message that specifies the table owner.
`TRUNCATE`	Indicates that a table has been truncated.
`TYPE_FIELD`	The name of the field in a message that specifies the message type.
`UPDATE`	Indicates that a row has been updated.
`UPDATE_DESCRIPTOR_FIELD`	The name of the field that returns a `ttXlaUpdateDesc_t` structure as a byte array.
`UPDATED_COLUMNS_FIELD`	The name of the field in a message that contains the list of updated columns.

XL A flags

For all update types, the MapMessage contains name and value pairs that indicate the following.

Whether this is the first record of a transaction
Whether this is the last record of a transaction
Whether the update was performed by replication
Which table was updated
The owner of the updated table

The name and value pairs that contain these XLA flags are described in Table 6-2. Each name is preceded by two underscores.

Table 6-2 JMS/XLA flags

Name	Description	Corresponding ttXlaUpdateDesc_t flag
`__AGING_DELETE`	Indicates that a delete was due to aging. The flag is present only if the XLA update record is due to an aging delete. The `XlaConstants` constant `AGING_DELETE_FIELD` represents this flag.	`TT_AGING`
`__CASCADING_DELETE`	Indicates that a delete was due to a cascading delete. The flag is present only if the XLA update record is due to a cascading delete. The `XlaConstants` constant `CASCADING_DELETE_FIELD` represents this flag.	`TT_CASCDEL`
`__COMMIT`	Indicates that this is the last record in a transaction and that a commit was performed after this operation. Only included in the `MapMessage` if `TT_UPDCOMMIT` is on. The `XlaConstants` constant `COMMIT_FIELD` represents this flag.	`TT_UPDCOMMIT`
`__FIRST`	Indicates that this is the first record in a new transaction. Only included in the `MapMessage` if `TT_UPDFIRST` is on. The `XlaConstants` constant `FIRST_FIELD` represents this flag.	`TT_UPDFIRST`
`__REPL`	Indicates that this change was applied to the database through replication. Only included in the `MapMessage` if `TT_UPDREPL` is on. The `XlaConstants` constant `REPL_FIELD` represents this flag.	`TT_UPDREPL`
`__UPDCOLS`	Only used for `UPDATETUP` records, this flag indicates that the XLA update descriptor contains a list of columns that were actually modified by the operation. Specified as a string that contains a semicolon-delimited list of column names. Only included in the `MapMessage` if `TT_UPDCOLS` is on. The `XlaConstants` constant `UPDATE_COLUMNS_FIELD` represents this flag.	`TT_UPDCOLS`

Note:

The XlaConstants interface is in the com.timesten.dataserver.jmsxla package.

Applications can use the MapMessage method itemExists() to determine whether a flag is present, and getBoolean() to determine whether a flag is set. As input, specify the XlaConstants constant that corresponds to the flag, such as XlaConstants.AGING_DELETE_FIELD.

Example 6-1 Check for commit

Equivalent to using TT_UPCOMMIT in XLA, you can use the following test in JMS/XLA to see whether this is the last record in a transaction and that a commit was performed after the operation.

if (MapMessage.getBoolean(XlaConstants.COMMIT_FIELD) ) { // Field is set
   ...
}

DM L event data formats

Many DML operations generate XLA updates that can be monitored by XLA event handlers. This section describes the contents of the MapMessage objects that are generated for these operations.

Table data

For INSERT, UPDATE and DELETE operations, MapMessage contains two name and value pairs, __TBLOWNER and __TBLNAME. These fields describe the name and owner of the table that is being updated. For example, for a table SCOTT.EMPLOYEES, any related MapMessage contains a field __TBLOWNER with the string value "SCOTT" and a field __TBLNAME with the string value "EMPLOYEES".

Row data

For INSERT and DELETE operations, a complete image of the inserted or deleted row is included in the message and all column values are available.

For UPDATE operations, the complete "before" and "after" images of the row are available, along with a list of column numbers indicating which columns were modified. Access the column values using the names of the columns. The column names in the "before" image all begin with a single underscore. For example, columnname contains the new value and _columnname contains the old value.

If the value of a column is NULL, it is omitted from the column list. The __NULLS name and value pair contains a semicolon-delimited list of the columns that contain NULL values.

Context information

If the ttApplicationContext built-in procedure was used to encode context information in an XLA record, that information is included in the __CONTEXT name and value pair in the MapMessage. If no context information is provided, the __CONTEXT value is not included in the MapMessage.

DD L event data formats

Many data definition language (DDL) operations generate XLA updates that can be monitored by XLA event handlers. This section describes the contents of the MapMessage objects that are generated for these operations.

CREATE_TABLE

Messages with __TYPE=1 (XlaConstants.CREATE_TABLE) indicate that a table has been created. Table 6-3 shows the name and value pairs that are included in a MapMessage generated for a CREATE_TABLE operation.

Table 6-3 CREATE_TABLE data provided in update messages

Name	Value
`OWNER`	String value of the owner of the created table.
`NAME`	String value of the name of the created table.
`PK_COLUMNS`	String value containing the names of the columns in the primary key for this table. If the table has no primary key, the `PK_COLUMNS` value is not specified. Format: <col1name>[;<col2name> [;<col3name>[;...]]]
`COLUMNS`	String value containing the names of the columns in the table. Format: <col1name>[;<col2name> [;<col3name>[;...]]] Note: For each column in the table, additional name and value pairs that describe the column are included in `MapMessage`.
`_column_name_TYPE`	Integer value representing the data type of this column. From `java.sql.Types`.
`_column_name_PRECISION`	Integer value containing the precision of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SCALE`	Integer value containing the scale of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SIZE`	Integer value indicating the maximum size of this column (for `CHAR`, `VARCHAR`, `BINARY`, or `VARBINARY`).
`_column_name_NULLABLE`	Boolean value indicating whether this column can have a `NULL` value.
`_column_name_OUTOFLINE`	Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple.
`_column_name_INPRIMARYKEY`	Boolean value indicating whether this column is part of the primary key of the table.

DROP_TABLE

Messages with __TYPE=2 (XlaConstants.DROP_TABLE) indicate that a table has been dropped. Table 6-4 shows the name and value pairs that are included in a MapMessage generated for a DROP_TABLE operation.

Table 6-4 DROP_TABLE data provided in update messages

Name	Value
`OWNER`	String value of the owner of the sequence.
`NAME`	String value of the name of the dropped sequence.

CREATE_INDEX

Messages with __TYPE=3 (XlaConstants.CREATE_INDEX) indicate that an index has been created. Table 6-5 shows the name and value pairs that are included in a MapMessage generated for a CREATE_INDEX operation.

Table 6-5 CREATE_INDEX data provided in update messages

Name	Value
`TBLOWNER`	String value of the owner of the table on which the index was created.
`TBLNAME`	String value of the name of the table on which the index was created.
`IXNAME`	String value of the name of the created index.
`INDEX_TYPE`	String value representing the index type: "P" (primary key), "F" (foreign key), or "R" (regular).
`INDEX_METHOD`	String value representing the index method: "H" (hash), "T" (range), or "B" (bit map).
`UNIQUE`	Boolean value indicating whether the index is unique.
`HASH_PAGES`	Integer value representing the number of pages in a hash index (not specified for range indexes).
`COLUMNS`	String value describing the columns in the index. Format: <col1name>[;<col2name> [;<col3name>[;...]]]

DROP_INDEX

Messages with __TYPE=4 (XlaConstants.DROP_INDEX) indicate that an index has been dropped. Table 6-6 shows the name and value pairs that are included in a MapMessage generated for a DROP_INDEX operation.

Table 6-6 DROP_INDEX data provided In update messages

Name	Value
`OWNER`	String value of the owner of the table on which the index was dropped.
`TABLE_NAME`	String value of the name of the table on which the index was dropped.
`INDEX_NAME`	String value of the name of the dropped index.

ADD_COLUMNS

Messages with __TYPE=5 (XlaConstants.ADD_COLUMNS) indicate that a table has been altered by adding new columns. Table 6-7 shows the name and value pairs that are included in a MapMessage generated for a ADD_COLUMNS operation.

Table 6-7 ADD_COLUMNS data provided in update messages

Name	Value
`OWNER`	String value of the owner of the altered table.
`NAME`	String value of the name of the altered table.
`PK_COLUMNS`	String value containing the names of the columns in the primary key for this table. If the table has no primary key, the `PK_COLUMNS` value is not specified. Format: <col1name>[;<col2name> [;<col3name>[;...]]]
`COLUMNS`	String value containing the names of the columns added to the table. Format: <col1name>[;<col2name> [;<col3name>[;...]]] Note: For each added column, additional name and value pairs that describe the column are included in the `MapMessage`.
`_column_name_TYPE`	Integer value representing the data type of this column. From `java.sql.Types`.
`_column_name_PRECISION`	Integer value containing the precision of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SCALE`	Integer value containing the scale of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SIZE`	Integer value indicating the maximum size of this column (for `CHAR`, `VARCHAR`, `BINARY`, or `VARBINARY`).
`_column_name_NULLABLE`	Boolean value indicating whether this column can have a `NULL` value.
`_column_name_OUTOFLINE`	Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple.
`_column_name_INPRIMARYKEY`	Boolean value indicating whether this column is part of the primary key of the table.

DROP_COLUMNS

Messages with __TYPE=6 (XlaConstants.DROP_COLUMNS) indicate that a table has been altered by dropping existing columns. Table 6-8 shows the name and value pairs that are included in a MapMessage generated for a DROP_COLUMNS operation.

Table 6-8 DROP_COLUMNS data provided in update message

Name	Value
`OWNER`	String value of the owner of the altered table.
`NAME`	String value of the name of the altered table.
`COLUMNS`	String value containing the names of the columns dropped from the table. Format: <col1name>[;<col2name> [;<col3name>[;...]]] Note: For each dropped column, additional name and value pairs that describe the column are included in the `MapMessage`.
`_column_name_TYPE`	Integer value representing the data type of this column. From `java.sql.Types`.
`_column_name_PRECISION`	Integer value containing the precision of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SCALE`	Integer value containing the scale of this column (for `NUMERIC` or `DECIMAL`).
`_column_name_SIZE`	Integer value indicating the maximum size of this column (for `CHAR`, `VARCHAR`, `BINARY`, or `VARBINARY`).
`_column_name_NULLABLE`	Boolean value indicating whether this column can have a `NULL` value.
`_column_name_OUTOFLINE`	Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple.
`_column_name_INPRIMARYKEY`	Boolean value indicating whether this column is part of the primary key of the table.

CREATE_VIEW

Messages with __TYPE=14 (XlaConstants.CREATE_VIEW) indicate that a materialized view has been created. Table 6-9 shows the name and value pairs that are included in a MapMessage generated for a CREATE_VIEW operation.

Table 6-9 CREATE_VIEW data provided in update messages

Name	Value
`OWNER`	String value of the owner of the created view.
`NAME`	String value of the name of the created view.

DROP_VIEW

Messages with __TYPE=15 (XlaConstants.DROP_VIEW) indicate that a materialized view has been dropped. Table 6-10 shows the name and value pairs that are included in a MapMessage generated for a DROP_VIEW operation.

Table 6-10 DROP_VIEW data provided in update messages

Name	Value
`OWNER`	String value of the owner of the dropped view.
`NAME`	String value of the name of the dropped view.

CREATE_SEQ

Messages with __TYPE=16 (XlaConstants.CREATE_SEQ) indicate that a sequence has been created. Table 6-11 shows the name and value pairs that are included in a MapMessage generated for a CREATE_SEQ operation.

Table 6-11 CREATE_SEQ data provided in update messages

Name	Value
`OWNER`	String value of the owner of the created sequence.
`NAME`	String value of the name of the created sequence.
`CYCLE`	Boolean value indicating whether the `CYCLE` option was specified on the new sequence.
`INCREMENT`	A `long` value indicating the `INCREMENT BY` option specified for the new sequence.
`MIN_VALUE`	A `long` value indicating the `MINVALUE` option specified for the new sequence.
`MAX_VALUE`	A `long` value indicating the `MAXVALUE` option specified for the new sequence.

DROP_SEQ

Messages with __TYPE=17 (XlaConstants.DROP_SEQ) indicate that a sequence has been dropped. Table 6-12 shows the name and value pairs that are included in a MapMessage generated for a DROP_SEQ operation.

Table 6-12 DROP_SEQ data provided in update messages

Name	Value
`OWNER`	String value of the owner of the dropped table.
`NAME`	String value of the name of the dropped table.

CREATE_SYNONYM

Messages with __TYPE=19 (XlaConstants.CREATE_SYNONYM) indicate that a synonym has been created. Table 6-13 shows the name and value pairs that are included in a MapMessage generated for a CREATE_SYNONYM operation.

Table 6-13 CREATE_SYNONYM data provided in update messages

Name	Value
`OWNER`	String value of the owner of the created synonym.
`NAME`	String value of the name of the created synonym.
`OBJECT_OWNER`	String value of the schema of the object for which you are creating a synonym.
`OBJECT_NAME`	String value of the name of the object for which you are creating a synonym.
`IS_PUBLIC`	Boolean value that is `TRUE` if the synonym is public, or `FALSE` if not.
`IS_REPLACE`	Boolean value that is `TRUE` if the synonym was created using `CREATE OR REPLACE`, or `FALSE` otherwise.

DROP_SYNONYM

Messages with __TYPE=20 (XlaConstants.DROP_SYNONYM) indicate that a synonym has been dropped. Table 6-14 shows the name and value pairs that are included in a MapMessage generated for a DROP_SYNONYM operation.

Table 6-14 DROP_SYNONYM data provided in update messages

Name	Value
`OWNER`	String value of the owner of the dropped synonym.
`NAME`	String value of the name of the dropped synonym.
`IS_PUBLIC`	Boolean value that is `TRUE` if the synonym was public, or `FALSE` if not.

TRUNCATE

Messages with __TYPE=18 (XlaConstants.TRUNCATE) indicate that a table has been truncated. All rows in the table have been deleted. Table 6-15 shows the name and value pairs that are included in a MapMessage generated for a TRUNCATE operation.

Table 6-15 TRUNCATE data provided in update messages

Name	Value
`OWNER`	String value of the owner of the truncated table.
`NAME`	String value of the name of the truncated table.

Data type support

This section covers data type considerations for JMS/XLA.

Da ta type mapping

Table 6-16 lists access methods for the data types supported by TimesTen. For more information about data types, see "Data Types" in Oracle TimesTen In-Memory Database SQL Reference.

Table 6-16 Data Type Mapping

TimesTen column type	Read with MapMessage method...
CHAR(n)	`getString()`
VARCHAR(n)	`getString()`
NCHAR(n)	`getString()`
NVARCHAR(n)	`getString()`
NVARCHAR2(n)	`getString()`
DOUBLE	`getDouble()`
FLOAT	`getFloat()`
DECIMAL(p,s)	`getString()` Can be converted to `BigDecimal` or to `Double` by the application.
NUMERIC(p,s)	`getString()` Can be converted to `BigDecimal` or to `Double` by the application.
INTEGER	`getInt()`
SMALLINT	`getShort()`
TINYINT	`getShort()`
BIGINT	`getLong()`
BINARY(n)	`getBytes()`
VARBINARY(n)	`getBytes()`
DATE	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970). Can be converted to `Date` or `Calendar` by the application.
TIME	`getString()` Can be converted to `Date` or `Calendar` by the application.
TIMESTAMP	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970). It truncates nanoseconds. Use `getString()` if you require nanosecond precision. Can be converted to `Date` or `Calendar` by the application.
TT_CHAR	`getString()`
TT_VARCHAR	`getString()`
TT_NCHAR	`getString()`
TT_NVARCHAR	`getString()`
ORA_CHAR	`getString()`
ORA_VARCHAR2	`getString()`
ORA_NCHAR	`getString()`
ORA_NVARCHAR2	`getString()`
VARCHAR2	`getString()`
TT_TINYINT	`getShort()`
TT_SMALLINT	`getShort()`
TT_INTEGER	`getInt()`
TT_BIGINT	`getLong()`
BINARY_FLOAT	`getFloat()`
BINARY_DOUBLE	`getDouble()`
REAL	`getFloat()`
NUMBER	`getString()`
ORA_NUMBER	`getString()`
TT_DECIMAL	`getString()`
TT_TIME	`getString()`
TT_DATE	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970).
TT_TIMESTAMP	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970).
ORA_DATE	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970).
ORA_TIMESTAMP	`getLong()`, `getString()` The `getLong()` method returns microseconds since epoch (00:00:00 UTC, January 1, 1970). It truncates nanoseconds. Use `getString()` if you require nanosecond precision.
TT_BINARY	`getBytes()`
TT_VARBINARY	`getBytes()`
ROWID	`getBytes()`, `getString()`

Data types ch aracter set

JMS/XLA uses a UTF-16 character set for the following data types:

TT_CHAR
TT_VARCHAR
ORA_CHAR
ORA_VARCHAR2
TT_NCHAR
TT_NVARCHAR
ORA_NCHAR
ORA_NVARCHAR2
NCHAR
NVARCHAR
NVARCHAR2

JMS classes for event handling

You can use JMS classes when programming to the JMS/XLA API. The JMS/XLA API supports only publish/subscribe messaging. JMS classes include the following:

Message (parent class only)
TopicConnectionFactory
Topic
TopicSubscriber
Connection
Session
ConnectionMetaData
MapMessage
TopicConnection
TopicSession
ConnectionFactory
Destination
MessageConsumer
ExceptionListener

See the following location for documentation of these classes:

http://download.oracle.com/javaee/5/api/

JMS/X LA replication API

The TimesTen com.timesten.dataserver.jmsxla package includes the TargetDataStore interface and the TargetDataStoreImpl class.

See Oracle TimesTen In-Memory Database JMS/XLA Java API Reference for information.

TargetDataStore interface

This interface is used to apply XLA update records from a source database to a target database. The source and target database schema must be identical for the affected tables.

This interface includes the methods shown in Table 6-17.

Table 6-17 TargetDataStore methods

Method	Description
`apply()`	Applies XLA update descriptor to the target database.
`close()`	Closes the connections to the database and releases the resources.
`commit()`	Performs a manual commit.
`getAutoCommitFlag()`	Returns the value of the autocommit flag.
`getConnectString()`	Returns the database connection string.
`getUpdateConflictCheckFlag()`	Returns the value of the flag for checking update conflicts.
`isClosed()`	Checks whether the object is closed.
`isDataStoreValid()`	Checks whether the database is valid.
`rollback()`	Rolls back the last transaction.
`setAutoCommitFlag()`	Sets the flag for autocommit during apply.
`setUpdateConflictCheckFlag()`	Sets the flag for checking update conflicts during apply.

TargetDataStoreImpl class

This class creates connections and XLA handles for a target database. It implements the TargetDataStore interface.

JM S message header fields

Table 6-18 shows the JMS message header fields provided by JMS/XLA.

Table 6-18 JMS/XLA header fields

Header	Contents
`JMSMessageId`	The transaction log file number of the XLA record.
`JMSType`	The string representation of the `__TYPE` field.