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/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/value pair called __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_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_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 `ttXlaUpdateDesc_t` 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/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/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 ttXLATblDesc_t field
`__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 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 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 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 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.

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/value pairs called __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 called __TBLOWNER with a value that is the string "SCOTT" and a field called __TBLNAME with a value that is the string "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" image of the row is available, as well as a list of column numbers indicating which columns were actually modified. You 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/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/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/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/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 "in line" 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/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/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/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/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/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 "in line" 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/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/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 "in line" 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/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/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/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`	Long value indicating the INCREMENT BY option specified for the new sequence.
`MIN_VALUE`	Long value indicating the MINVALUE option specified for the new sequence.
`MAX_VALUE`	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/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.

TRUNCATE

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

Table 6-13 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-14 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-14 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://java.sun.com/javaee/5/docs/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 data store to a target data store. The source and target data store schema must be identical for the affected tables.

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

Table 6-15 TargetDataStore methods

Method	Description
`apply()`	Applies XLA update descriptor to the target data store.
`close()`	Closes the connections to the data store and releases the resources.
`commit()`	Performs a manual commit.
`getAutoCommitFlag()`	Returns the value of the autocommit flag.
`getConnectString()`	Returns the data store connection string.
`getUpdateConflictCheckFlag()`	Returns the value of the flag for checking update conflicts.
`isClosed()`	Checks whether the object is closed.
`isDataStoreValid()`	Checks whether the data store 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 data store. It implements the TargetDataStore interface.

JM S message header fields

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

Table 6-16 JMS/XLA header fields

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