6 JMS/XLA Reference

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

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