Skip Headers
Oracle® TimesTen In-Memory Database Java Developer's Guide
Release 11.2.1

Part Number E13068-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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


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

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

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

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

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:

See the following location for documentation of these classes:

http://java.sun.com/javaee/5/docs/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 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.

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