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 MapMessage 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.

XLA 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	This is the name of the field in a message that contains a commit.
COMMIT_ONLY	Indicates that a commit has occurred.
CONTEXT_FIELD	This is the name 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	This is 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	This is the name of the field in a message that contains type information.
MVER_FIELD	This is the name of the field in a message that contains the transaction log file number of the XLA record.
NULLS_FIELD	This is the name of the field in a message that contains the list of fields that have null values.
REPL_FIELD	This is the name of the field in a message that contains the flag that indicates that the update was applied by replication.
TBLNAME_FIELD	This is the name of the field in a message that contains the table name.
TBLOWNER_FIELD	This is the name of the field in a message that specifies the table owner.
TRUNCATE	Indicates that a table has been truncated.
TYPE_FIELD	This is the name of the field in a message that specifies the message type.
UPDATE	Indicates that a row has been updated.
UPDATE_DESCRIPTOR_FIELD	This is the name of the field that returns a ttXlaUpdateDesc_t structure as a byte array.
UPDATED_COLUMNS_FIELD	This is the name of the field in a message that contains the list of updated columns.

XLA 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. This is 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. This is 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. This is in the MapMessage if TT_UPDREPL is on. The XlaConstants constant REPL_FIELD represents this flag.	TT_UPDREPL
__UPDCOLS	This is only used for UPDATETUP records, indicating that the XLA update descriptor contains a list of columns that were actually modified by the operation. It is specified as a string that contains a semicolon-delimited list of column names and is in the MapMessage only 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_UPDCOMMIT 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
   ...
}

DML 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 in the __CONTEXT name and value pair in the MapMessage. If no context information is provided, the __CONTEXT value is not in the MapMessage.

DDL 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 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 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_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 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 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 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 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 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 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 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 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 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 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 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 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 indicating whether the synonym is public
IS_REPLACE	Boolean value indicating whether the synonym was created using CREATE OR REPLACE

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 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 indicating whether the synonym was public

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 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.

Data 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	getString() Can be converted to BigDecimal or to Double by the application.
FLOAT	getString() Can be converted to BigDecimal or to Double by the application.
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()
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()
BLOB	getBytes() Note: Information about the LOB value itself is unavailable. LOB fields contain zero-length data or null data (if the value is actually NULL).
CLOB, NCLOB	getString() Note: Information about the LOB value itself is unavailable. LOB fields contain zero-length data or null data (if the value is actually NULL).

Data types character 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

The following JMS classes are available for JMS/XLA applications. Note that the JMS/XLA API supports only publish/subscribe messaging.

• Message (parent class only)

• TopicConnectionFactory

• Topic

• TopicSubscriber

• Connection

• Session

• ConnectionMetaData

• MapMessage

• TopicConnection

• TopicSession

• ConnectionFactory

• Destination

• MessageConsumer

• ExceptionListener

See the following Java EE locations (the first for Java 6, the second for Java 5.0) for documentation of these classes:

http://docs.oracle.com/javaee/6/api/
http://docs.oracle.com/javaee/5/api/

JMS/XLA 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 defines 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.

JMS 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	Transaction log file number of the XLA record
JMSType	String representation of the __TYPE field