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. |
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.
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
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 |
|---|---|---|
|
|
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 |
|
|
|
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 |
|
|
|
Indicates that this is the last record in a transaction and that a commit was performed after this operation. This is in the |
|
|
|
Indicates that this is the first record in a new transaction. This is in the |
|
|
|
Indicates that this change was applied to the database through replication. This is in the |
|
|
|
This is only used for |
|
|
Note: TheXlaConstants 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.
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.
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".
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.
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.
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 |
|---|---|
|
|
String value of the owner of the created table |
|
|
String value of the name of the created table |
|
|
String value containing the names of the columns in the primary key for this table If the table has no primary key, the Format: <col1name>[;<col2name> [;<col3name>[;...]]] |
|
|
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 |
|
|
Integer value representing the data type of this column (from |
|
|
Integer value containing the precision of this column (for |
|
|
Integer value containing the scale of this column (for |
|
|
Integer value indicating the maximum size of this column (for |
|
|
Boolean value indicating whether this column can have a |
|
|
Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple |
|
|
Boolean value indicating whether this column is part of the primary key of the 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.
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 |
|---|---|
|
|
String value of the owner of the table on which the index was created |
|
|
String value of the name of the table on which the index was created |
|
|
String value of the name of the created index |
|
|
String value representing the index type: "P" (primary key), "F" (foreign key), or "R" (regular) |
|
|
String value representing the index method: "H" (hash), "T" (range), or "B" (bit map) |
|
|
Boolean value indicating whether the index is unique |
|
|
Integer value representing the number of pages in a hash index (not specified for range indexes) |
|
|
String value describing the columns in the index Format: <col1name>[;<col2name> [;<col3name>[;...]]] |
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.
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 |
|---|---|
|
|
String value of the owner of the altered table |
|
|
String value of the name of the altered table |
|
|
String value containing the names of the columns in the primary key for this table If the table has no primary key, the Format: <col1name>[;<col2name> [;<col3name>[;...]]] |
|
|
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 |
|
|
Integer value representing the data type of this column (from |
|
|
Integer value containing the precision of this column (for |
|
|
Integer value containing the scale of this column (for |
|
|
Integer value indicating the maximum size of this column (for |
|
|
Boolean value indicating whether this column can have a |
|
|
Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple |
|
|
Boolean value indicating whether this column is part of the primary key of the table |
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 |
|---|---|
|
|
String value of the owner of the altered table |
|
|
String value of the name of the altered table |
|
|
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 |
|
|
Integer value representing the data type of this column (from |
|
|
Integer value containing the precision of this column (for |
|
|
Integer value containing the scale of this column (for |
|
|
Integer value indicating the maximum size of this column (for |
|
|
Boolean value indicating whether this column can have a |
|
|
Boolean value indicating whether this column is stored in the inline or out-of-line part of the tuple |
|
|
Boolean value indicating whether this column is part of the primary key of the table |
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.
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.
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 |
|---|---|
|
|
String value of the owner of the created sequence |
|
|
String value of the name of the created sequence |
|
|
Boolean value indicating whether the |
|
|
A |
|
|
A |
|
|
A |
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.
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 |
|---|---|
|
|
String value of the owner of the created synonym |
|
|
String value of the name of the created synonym |
|
|
String value of the schema of the object for which you are creating a synonym |
|
|
String value of the name of the object for which you are creating a synonym |
|
|
Boolean value indicating whether the synonym is public |
|
|
Boolean value indicating whether the synonym was created using |
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.
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.
This section covers data type considerations for JMS/XLA.
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)
|
|
VARCHAR(n)
|
|
NCHAR(n)
|
|
NVARCHAR(n)
|
|
NVARCHAR2(n)
|
|
DOUBLE |
Can be converted to |
FLOAT |
Can be converted to |
DECIMAL(p,s)
|
Can be converted to |
NUMERIC(p,s)
|
Can be converted to |
INTEGER |
|
SMALLINT |
|
TINYINT |
|
BINARY(n)
|
|
VARBINARY(n)
|
|
DATE |
The Can be converted to |
TIME |
Can be converted to |
TIMESTAMP |
The Can be converted to |
TT_CHAR |
|
TT_VARCHAR |
|
TT_NCHAR |
|
TT_NVARCHAR |
|
ORA_CHAR |
|
ORA_VARCHAR2 |
|
ORA_NCHAR |
|
ORA_NVARCHAR2 |
|
VARCHAR2 |
|
TT_TINYINT |
|
TT_SMALLINT |
|
TT_INTEGER |
|
TT_BIGINT |
|
BINARY_FLOAT |
|
BINARY_DOUBLE |
|
REAL |
|
NUMBER |
|
ORA_NUMBER |
|
TT_DECIMAL |
|
TT_TIME |
|
TT_DATE |
The |
TT_TIMESTAMP |
The |
ORA_DATE |
The |
ORA_TIMESTAMP |
The |
TT_BINARY |
|
TT_VARBINARY |
|
ROWID |
|
|
|
Note: Information about the LOB value itself is unavailable. LOB fields will contain zero-length data or null data (if the value is actually |
|
|
Note: Information about the LOB value itself is unavailable. LOB fields will contain zero-length data or null data (if the value is actually |
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) for documentation of these classes:
http://docs.oracle.com/javaee/6/api/http://docs.oracle.com/javaee/5/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.
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 |
|---|---|
|
|
Applies XLA update descriptor to the target database. |
|
|
Closes the connections to the database and releases the resources. |
|
|
Performs a manual commit. |
|
|
Returns the value of the autocommit flag. |
|
|
Returns the database connection string. |
|
|
Returns the value of the flag for checking update conflicts. |
|
|
Checks whether the object is closed. |
|
|
Checks whether the database is valid. |
|
|
Rolls back the last transaction. |
|
|
Sets the flag for autocommit during apply. |
|
|
Sets the flag for checking update conflicts during apply. |
Table 6-18 shows the JMS message header fields provided by JMS/XLA.
This section summarizes the new features and functionality of Oracle TimesTen In-Memory Database 11g Release 2 (11.2.2) that are documented in this guide, providing links into the guide for more information.
LOB support
TimesTen supports LOBs (large objects). This includes CLOBs (character LOBs), NCLOBs (national character LOBs), and BLOBs (binary LOBs).
For details of support in JDBC, refer to "Working with LOBs".
Associative array binding
TimesTen JDBC supports associative arrays, formerly known as index-by tables or PL/SQL tables, as IN, OUT, or IN OUT bind parameters to TimesTen PL/SQL. Associative arrays enable arrays of data to be passed efficiently between an application and the database.
Java Developer's Guide
11g Release 2 (11.2.2)
E21638-04
September 2012
Oracle TimesTen In-Memory Database Java Developer's Guide, 11g Release 2 (11.2.2)
E21638-04
Copyright © 1996, 2012, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Oracle TimesTen In-Memory Database is a memory-optimized relational database. Deployed in the application tier, TimesTen operates on databases that fit entirely in physical memory using standard SQL interfaces. High availability for the in-memory database is provided through real-time transactional replication.
TimesTen supports a variety of programming interfaces, including PL/SQL (Oracle procedural language extension for SQL), ODBC (Open Database Connectivity), JDBC (Java Database Connectivity), OCI (Oracle Call Interface), Pro*C/C++ (Oracle precompiler for embedded SQL and PL/SQL instructions in C or C++ code), TTClasses (TimesTen C++ Interface Classes), and ODP.NET (Oracle Data Provider for .NET).
This document covers TimesTen support for JDBC.
The following topics are discussed in the preface:
This guide is for anyone developing or supporting applications that use TimesTen through JDBC.
In addition to familiarity with JDBC, you should be familiar with TimesTen, SQL (Structured Query Language), and database operations.
TimesTen documentation is available on the product distribution media and on the Oracle Technology Network:
http://www.oracle.com/technetwork/products/timesten/documentation/
Javadoc for standard JDBC (Java SE) classes and interfaces is available at the following locations (the first for Java 6, the second for Java 5):
http://docs.oracle.com/javase/6/docs/api/http://docs.oracle.com/javase/1.5.0/docs/api/
Javadoc for standard Java EE classes and interfaces is available at the following locations (the first for Java 6, the second for Java 5):
http://docs.oracle.com/javaee/6/api/http://docs.oracle.com/javaee/5/api/
Oracle documentation is also available on the Oracle Technology network. This may be especially useful for Oracle features that TimesTen supports but does not attempt to fully document:
http://www.oracle.com/technetwork/database/enterprise-edition/documentation/
In particular, the following Oracle documents may be of interest.
Oracle Database SQL Language Reference
Oracle Database JDBC Developer's Guide
TimesTen supports multiple platforms. Unless otherwise indicated, the information in this guide applies to all supported platforms. The term Windows applies to all supported Windows platforms. The term UNIX applies to all supported UNIX and Linux platforms. Refer to the "Platforms" section in Oracle TimesTen In-Memory Database Release Notes for specific platform versions supported by TimesTen.
|
Note: In TimesTen documentation, the terms "data store" and "database" are equivalent. Both terms refer to the TimesTen database unless otherwise noted. |
This document uses the following text conventions:
| Convention | Meaning |
|---|---|
| italic | Italic type indicates terms defined in text, book titles, or emphasis. |
monospace | Monospace type indicates code, commands, URLs, class names, interface names, method names, function names, attribute names, directory names, file names, text that appears on the screen, or text that you enter. |
italic monospace | Italic monospace type indicates a placeholder or a variable in a code example for which you specify or use a particular value. For example:
Replace |
| [ ] | Square brackets indicate that an item in a command line is optional. |
| { } | Curly braces indicated that you must choose one of the items separated by a vertical bar ( | ) in a command line. |
| | | A vertical bar (or pipe) separates alternative arguments. |
| . . . | An ellipsis (. . .) after an argument indicates that you may use more than one argument on a single command line. An ellipsis in a code example indicates that what is shown is only a partial example. |
| % | The percent sign indicates the UNIX shell prompt. |
TimesTen documentation uses the following variables to identify path, file and user names:
| Convention | Meaning |
|---|---|
install_dir | The path that represents the directory where TimesTen is installed. |
TTinstance | The instance name for your specific installation of TimesTen. Each installation of TimesTen must be identified at install time with a unique instance name. This name appears in the install path. |
bits or bb | Two digits, either 32 or 64, that represent either the 32-bit or 64-bit operating system. |
release or rr | The first three parts in a release number, with or without dots. The first three parts of a release number represent a major TimesTen release. For example, 1122 or 11.2.2 represents TimesTen 11g Release 2 (11.2.2). |
jdk_version | One or two digits that represent the version number of a major JDK release. For example, 14 is for JDK 1.4 and 5 is for JDK 5. |
DSN | TimesTen data source name (for the TimesTen database). |
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
This figure shows the following:
An application communicating global transactions to a transaction manager through the TX or a proprietary transaction interface.
The transaction manager and resource managers communicating transaction services through XA or JTA.
Resource managers and the application communicating through a native interface (ODBC or JDBC).
End of description.
PK|mo j PK *A ! OEBPS/img_text/transactionlog.htmRefer to the text for the "Reading transaction log records" example that follows.
As discussed in the example, this figure shows the transaction log records CT1 (oldest), BT1, CT2, BT2, AT1, AT2, BT3, AT3, and CT3 (newest); and it shows the records the XLA application would see: BT2, BT3, CT1, CT2, and CT3. A pointer is shown to CT3 in the transaction log.
End of description.
PKij PK *A OEBPS/env_setup.htm#9This chapter provides information about the Java development environment and related considerations. It includes the following topics:
Install and configure TimesTen for your environment, as described in Oracle TimesTen In-Memory Database Installation Guide, and the Java JDK, as described in your Java installation documentation. As you set up a Java development environment, the topics of particular interest in Oracle TimesTen In-Memory Database Installation Guide include the following:
After you have installed and configured TimesTen, create a database DSN as described in "Managing TimesTen Databases" in Oracle TimesTen In-Memory Database Operations Guide. The topics of particular interest include the following:
Before you begin developing Java applications for TimesTen, you must set your environment appropriately. This includes setting the environment variables appropriately. See "Java environment variables" in Oracle TimesTen In-Memory Database Installation Guide for more information about environment variables for Java, including discussion of the PATH, CLASSPATH, THREAD_FLAGS, and shared library path environment variables.
Use the appropriate ttenv script to set up environment variables and runtime access to the Instant Client.
On UNIX platforms, use one of the following scripts.
install_dir/bin/ttenv.sh install_dir/bin/ttenv.csh
On Windows, use the following:
install_dir\bin\ttenv.bat
"Java environment variables" in Oracle TimesTen In-Memory Database Installation Guide discusses the CLASSPATH setting for compiling Java applications in TimesTen.
Compiling any Java application requires the JAR file appropriate for your JDK to be in your classpath. In TimesTen, the following are for JDK 5.0 and JDK 6.0, respectively:
install_dir/lib/ttjdbc5.jar install_dir/lib/ttjdbc6.jar
In addition, compiling any JMS/XLA application requires the following to be in your classpath:
install_dir/lib/timestenjmsxla.jar install_dir/3rdparty/jms1.1/lib/jms.jar install_dir/lib/orai18n.jar
After you have configured your Java environment, you can confirm that everything is set up correctly by compiling and running the TimesTen Quick Start demo applications. Refer to the Quick Start welcome page at install_dir/quickstart.html, especially the links under SAMPLE PROGRAMS, for information about the following:
Demo schema and setup: The build_sampledb script (.sh or UNIX or .bat on Windows) creates a sample database and demo schema. You must use this before you start using the demos.
Demo environment and setup: The ttquickstartenv script (.sh or .csh on UNIX or .bat on Windows), a superset of the ttenv script generally used for TimesTen setup, sets up the demo environment. You must use this each time you enter a session where you want to compile or run any of the demos.
Demos and setup: TimesTen provides demos for JDBC and JMS/XLA under the quickstart/sample_code directory. For instructions on compiling and running the demos, see the README file or files in the subdirectories.
What the demos do: A synopsis of each demo is provided when you click JDBC (Java) under SAMPLE PROGRAMS. The TimesTen basic Java demos are named level1, level2, level3, and level4. Data files for the level demos are in the jdbc/datfiles directory.
|
Note: All of thelevel demos support both direct and client/server connections to the database. |
You can use the TimesTen JMS/XLA API (JMS/XLA) to monitor TimesTen for changes to specified tables in a local database and receive real-time notification of these changes. The primary purpose of JMS/XLA is as a high-performance, asynchronous alternative to triggers.
JMS/XLA implements Java Message Service (JMS) interfaces to make the functionality of the TimesTen Transaction Log API (XLA) available to Java applications. JMS information and resources are available at the following location:
http://java.sun.com/products/jms/docs.html
In addition, the standard JMS API documentation is installed with the TimesTen at the following location:
install_dir/3rdparty/jms1.1/doc/api/index.html
For information about tuning TimesTen JMS/XLA applications for improved performance, see "Tuning JMS/XLA applications".
|
Note: In the unlikely event that the TimesTen replication solutions described in Oracle TimesTen In-Memory Database Replication Guide do not meet your needs, it is possible to use JMS/XLA to build a custom data replication solution. |
This chapter includes the following topics:
Java applications can use the JMS/XLA API to receive event notifications from TimesTen. JMS/XLA uses the JMS publish-subscribe interface to provide access to XLA updates.
Subscribe to updates by establishing a JMS Session instance that provides a connection to XLA and then creating a durable subscriber (TopicSubscriber). You can receive and process messages synchronously through the subscriber, or you can implement a listener (MessageListener) to process the updates asynchronously.
JMS/XLA is designed for applications that want to monitor a local database. TimesTen and the application receiving the notifications must reside on the same system.
|
Note: The JMS/XLA API is a wrapper for XLA. XLA obtains update records directly from the transaction log buffer or transaction log files, so the records are available until they are read. XLA also allows multiple readers to access transaction log updates simultaneously.See "XLA and TimesTen Event Management" in Oracle TimesTen In-Memory Database C Developer's Guide for information about XLA. |
This section includes the following topics:
As applications modify a database, TimesTen generates transaction log records that describe the changes made to the data and other events such as transaction commits.
New transaction log records are always written to the end of the transaction log buffer as they are generated. Transaction log records are periodically flushed in batches from the log buffer in memory to transaction log files on disk.
Applications can use XLA to monitor the transaction log for changes to the database. XLA reads through the transaction log, filters the log records, and delivers XLA applications with a list of transaction records that contain the changes to the tables and columns of interest.
XLA sorts the records into discrete transactions. If multiple applications are updating the database simultaneously, transaction log records from the different applications will be interleaved in the transaction log.
XLA transparently extracts all transaction log records associated with a particular transaction and delivers them in a contiguous list to the application.
Only the records for committed transactions are returned. They are returned in the order in which their final commit record appears in the transaction log. XLA filters out records associated with changes to the database that have not yet committed.
If a change is made but then rolled back, XLA does not deliver the records for the aborted transaction to the application.
Consider the example transaction log illustrated in Figure 3-1 and Example 3-1 that follow, which illustrate most of these basic XLA concepts.
Figure 3-1 Records extracted from the transaction log
Example 3-1 Reading transaction log records
In this example, the transaction log contains the following records:
CT1 - Application C updates row 1 of table W with value 7.7.BT1 - Application B updates row 3 of table X with value 2.CT2 - Application C updates row 9 of table W with value 5.6.BT2 - Application B updates row 2 of table Y with value "XYZ".AT1 - Application A updates row 1 of table Z with value 3.AT2 - Application A updates row 3 of table Z with value 4.BT3 - Application B commits its transaction.AT3 - Application A rolls back its transaction.CT3 - Application C commits its transaction.An XLA application that is set up to detect changes to tables W, Y, and Z would see the following:
BT2 and BT3 - Update row 2 of table Y with value "XYZ" and commit.CT1 - Update row 1 of table W with value 7.7.CT2 and CT3 - Update row 9 of table W with value 5.6 and commit.This example demonstrates the following:
Transaction records for application B and application C all appear.
Though the records for application C begin to appear in the transaction log before those for application B, the commit for application B (BT3) appears in the transaction log before the commit for application C (CT3). As a result, the records for application B are returned to the XLA application ahead of those for application C.
The application B update to table X (BT1) is not presented because XLA is not set up to detect changes to table X.
The application A updates to table Z (AT1 and AT2) are never presented because it did not commit and was rolled back (AT3).
You can use XLA to track changes to both tables and materialized views. A materialized view provides a single source from which you can track changes to selected rows and columns in multiple detail tables. Without a materialized view, the XLA application would have to monitor and filter the update records from all of the detail tables, including records reflecting updates to rows and columns of no interest to the application.
In general, there are no operational differences between the XLA mechanisms used to track changes to a table or a materialized view. However, for asynchronous materialized views, be aware that the order of XLA notifications for an asynchronous view is not necessarily the same as it would be for the associated detail tables, or the same as it would be for a synchronous view. For example, if there are two inserts to a detail table, they may be done in the opposite order in the asynchronous materialized view. Furthermore, updates may be reported by XLA as a delete followed by an insert, and multiple operations (such as multiple inserts or multiple deletes) may be combined into a single operation. Applications that depend on precise ordering should not use asynchronous materialized views.
For more information about materialized views, see the following:
"CREATE MATERIALIZED VIEW" in Oracle TimesTen In-Memory Database SQL Reference
"Understanding materialized views" in Oracle TimesTen In-Memory Database Operations Guide
An XLA bookmark marks the read position of an XLA subscriber application in the transaction log. Bookmarks facilitate durable subscriptions, enabling an application to disconnect from a topic and then reconnect to continue receiving updates where it left off.
The rest of this section covers the following:
When you create a message consumer for XLA, you always use a durable TopicSubscriber. The subscription identifier you specify when you create the subscriber is used as the XLA bookmark name. When you use the ttXlaSubscribe and ttXlaUnsubscribe built-in procedures through JDBC to start and stop the XLA subscription for a table, you explicitly specify the name of the bookmark to be used.
Bookmarks are reset to the last read position whenever an acknowledgment is received. For more information about how update messages are acknowledged, see the "XLA acknowledgment modes".
You can remove a durable subscription by calling unsubscribe() on the JMS Session object. This deletes the corresponding XLA bookmark and forces a new subscription to be created when you reconnect. For more information see "Deleting bookmarks".
A bookmark subscription cannot be altered when it is in use. To alter a subscription, you must close the message consumer, alter the subscription using ttXlaSubscribe and ttXlaUnsubscribe, and open the message consumer.
|
Note: You can also use thettXlaBookmarkCreate TimesTen built-in procedure to create bookmarks. See "ttXlaBookmarkCreate" in Oracle TimesTen In-Memory Database Reference for information about that function. |
If you are using an active standby pair replication scheme, you have the option of using replicated bookmarks, according to the replicatedBookmark attribute of the <topic> element in the jmsxla.xml file as discussed in "JMS/XLA configuration file and topics", which follows shortly. For a replicated bookmark, operations on the bookmark are replicated to the standby database as appropriate, assuming there is suitable write privilege for the standby. This allows more efficient recovery of your bookmark positions if a failover occurs.
You can only read and acknowledge a replicated bookmark in the active database. Each time you acknowledge a replicated bookmark, the acknowledge operation is asynchronously replicated to the standby database.
|
Note: Alternatively, if you usettXlaBookmarkCreate to create a bookmark, that function has a parameter for specifying a replicated bookmark. |
Be aware of the following usage notes:
The position of the bookmark in the standby database will be very close to that of the bookmark in the active database; however, because the replication of acknowledge operations is asynchronous, you may see a small window of duplicate updates when there is a failover, depending on how often acknowledge operations are performed.
If replicated bookmarks exist at the time you enable the active standby pair scheme, the bookmarks will automatically be added to the replication scheme.
It is permissible to drop the active standby pair scheme while replicated bookmarks exist. The bookmarks will cease to be replicated at that point.
You cannot delete replicated bookmarks while the replication agent is running.
You should be aware that when XLA is in use, there is a hold on TimesTen transaction log files until the XLA bookmark advances. The hold prevents transaction log files from being purged until XLA can confirm it no longer needs them. If a bookmark becomes stuck, which can occur if an XLA application terminates unexpectedly or disconnects without first deleting its bookmark or disabling change tracking, the log hold will persist and there may be an excessive accumulation of transaction log files. This accumulation may result in disk space being filled.
For information about monitoring and addressing this situation, see "Monitoring accumulation of transaction log files" in Oracle TimesTen In-Memory Database Operations Guide.
To connect to XLA, you establish a connection to a JMS Topic object that corresponds to a particular database. The JMS/XLA configuration file provides the mapping between topic names and databases.
You can specify a replicated bookmark by setting replicatedBookmark="yes" in the <topic> element when you specify the topic. The default setting is "no". Also see "XLA bookmarks".
By default, JMS/XLA looks for a configuration file named jmsxla.xml in the current working directory. If you want to use another name or location for the file, you must specify it as part of the environment variable in the InitialContext class and add the location to the classpath.
Example 3-2 Specifying the JMS/XLA configuration file
The following code specifies the configuration file as part of the environment variable in the InitialContext class.
Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.timesten.dataserver.jmsxla.SimpleInitialContextFactory"); env.put(XlaConstants.CONFIG_FILE_NAME, "/newlocation.xml"); InitialContext ic = new InitialContext(env);
The JMS/XLA API uses the class loader to locate the JMS/XLA configuration file if XlaConstants.CONFIG_FILE_NAME is set. In this example, the JMS/XLA API searches for the newlocation.xml file in the top directory in both the location specified in the CLASSPATH environment variable and in the JAR files specified in the CLASSPATH variable.
The JMS/XLA configuration file can also be located in subdirectories, as follows:
env.put(XlaConstants.CONFIG_FILE_NAME, "/com/mycompany/myapplication/deepinside.xml");
In this case, the JMS/XLA API searches for the deepinside.xml file in the com/mycompany/myapplication subdirectory in both the location specified in the CLASSPATH environment variable and in the JAR files specified in the CLASSPATH variable.
The JMS/XLA API uses the first configuration file that it finds.
Example 3-3 Defining a topic in the configuration file
A topic definition in the configuration file consists of a name, a connection string, and a prefetch value that specifies how many updates to retrieve at a time.
For example, the configuration file shown here maps the DemoDataStore topic to the TestDB DSN:
<xlaconfig>
<topics>
<topic name="DemoDataStore"
connectionString="DSN=TestDB"
xlaPrefetch="100" />
</topics>
</xlaconfig>
Example 3-4 Defining a topic to use replicated bookmarks
A topic definition can also specify whether a replicated bookmark should be used. The following repeats the preceding example, but with a replicated bookmark.
<xlaconfig>
<topics>
<topic name="DemoDataStore"
connectionString="DSN=TestDB"
xlaPrefetch="100" replicatedBookmark="yes" />
</topics>
</xlaconfig>
Applications receive XLA updates as JMS MapMessage objects. A MapMessage object contains a set of typed name and value pairs that correspond to the fields in an XLA update header.
You can access the message fields using the MapMessage getter methods. The getMapNames() method returns an Enumeration object that contains the names of all of the fields in the message. You can retrieve individual fields from the message by name. All reserved field names begin with two underscores, for example __TYPE.
All update messages have a __TYPE field that indicates what type of update the message contains. 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. The supported types are described in Table 3-1.
Table 3-1 XLA update types
| Update type | Description |
|---|---|
|
|
A row has been added. |
|
|
A row has been modified. |
|
|
A row has been removed. |
|
|
A transaction has been committed. |
|
|
A table has been created. |
|
|
A table has been dropped. |
|
|
An index has been created. |
|
|
An index has been dropped. |
|
|
New columns have been added to the table. |
|
|
Columns have been removed from the table. |
|
|
A materialized view has been created. |
|
|
A materialized view has been dropped. |
|
|
A sequence has been created. |
|
|
A sequence has been dropped. |
|
|
A synonym has been created. |
|
|
A synonym has been dropped. |
|
|
All rows in the table have been deleted. |
For more information about the contents of an XLA update message, see "JMS/XLA MapMessage contents".
The XLA acknowledgment mechanism is designed to ensure that an application has not only received a message, but has successfully processed it. Acknowledging an update permanently resets the application XLA bookmark to the last record that was read. This prevents previously returned records from being reread, ensuring that an application receives only new batches of records if the bookmark is reused when an application reconnects to XLA.
JMS/XLA can automatically acknowledge XLA update messages, or applications can choose to acknowledge messages explicitly. You specify how updates are to be acknowledged when you create the Session object.
JMS/XLA supports three acknowledgment modes:
AUTO_ACKNOWLEDGE: In this mode, updates are automatically acknowledged as you receive them. Each message is delivered only once. Duplicate messages will not be sent, so messages might be lost if there is an application failure. Messages are always delivered and acknowledged individually, so JMS/XLA does not prefetch multiple records. The xlaprefetch attribute in the topic is ignored.
DUPS_OK_ACKNOWLEDGE: In this mode, updates are automatically acknowledged, but duplicate messages might be delivered when there is an application failure. JMS/XLA prefetches records according to the xlaprefetch attribute specified for the topic and sends an acknowledgment when the last record in a prefetched block is read. If the application fails before reading all of the prefetched records, all of the records in the block are presented to the application it restarts.
See "JMS/XLA configuration file and topics" for examples setting xlaprefetch.
CLIENT_ACKNOWLEDGE: In this mode, applications are responsible for acknowledging receipt of update messages by calling acknowledge() on the MapMessage instance. JMS/XLA prefetches records according to the xlaprefetch attribute specified for the topic.
The following example sets the acknowledgment mode:
Session session = connection.createSession (false, Session.CLIENT_ACKNOWLEDGE);
Also see "Reduce frequency of update acknowledgments".
Prefetching multiple update records at a time is more efficient than obtaining each update record from XLA individually. Because updates are not prefetched when you use AUTO_ACKNOWLEDGE mode, it can be slower than the other modes. If possible, you should design your application to tolerate duplicate updates so you can use DUPS_OK_ACKNOWLEDGE, or explicitly acknowledge updates. Explicitly acknowledging updates usually yields the best performance, as long as you can avoid acknowledging each message individually.
To explicitly acknowledge an XLA update, call acknowledge() on the update message. Acknowledging a message implicitly acknowledges all previous messages. Typically, you receive and process multiple update messages between acknowledgments. If you are using the CLIENT_ACKNOWLEDGE mode and intend to reuse a durable subscription in the future, you should call acknowledge() to reset the bookmark to the last-read position before exiting.
"Considering TimesTen features for access control" provides a brief overview of how TimesTen access control affects operations in the database. Access control impacts XLA, as follows:
Any XLA functionality requires the system privilege XLA. This includes connecting to TimesTen (which also requires the CREATE SESSION privilege) as an XLA reader and executing the TimesTen XLA built-in procedures ttXlaBookmarkCreate, ttXlaBookmarkDelete, ttXlaSubscribe, and ttXlaUnsubscribe, all of which are documented in "Built-In Procedures" in Oracle TimesTen In-Memory Database Reference.
A user with the XLA privilege has capabilities equivalent to the SELECT ANY TABLE, SELECT ANY VIEW, and SELECT ANY SEQUENCE system privileges.
Be aware of the following XLA limitations when you use TimesTen JMS/XLA:
JMS/XLA is available on all platforms supported by TimesTen. However, XLA does not support data transfer between different platforms or between 32-bit and 64-bit versions of the same platform.
JMS/XLA support for LOBs is limited. See "Monitoring tables for updates" for information.
JMS/XLA does not support applications linked with a driver manager library or the client/server library.
An XLA reader cannot subscribe to a table that uses in-memory columnar compression.
For autorefresh cache groups, the change-tracking trigger on Oracle Database does not have column-level resolution. (To have that would be very expensive.) Therefore the autorefresh feature will update all the columns in the row, and XLA can only report that all the columns have changed, even if data did not actually change in all columns.
The JMS/XLA API uses orai18n.jar, part of the Oracle Globalization Development Kit (GDK) for translating from the database character set specified by the DatabaseCharacterSet attribute to UTF-16 encoding. The JMS/XLA API supports a specific version of the GDK with each TimesTen release. If JMS/XLA finds other versions of the GDK loaded in the JVM, it displays a severe warning and continues processing. You can find out the GDK version supported by JMS/XLA by entering the following commands:
$ cd install_dir/lib
$ java -cp ./orai18n.jar oracle.i18n.util.GDKOracleMetaData -version
Also see "Compiling Java applications".
To connect to XLA so you can receive updates, use a JMS connection factory to create a connection. Then use the connection to establish a session. When you are ready to start processing updates, call start() on the connection to enable message dispatching. This is shown in Example 3-5 that follows, from the syncJMS Quick Start demo.
Example 3-5 Connecting to XLA
/* JMS connection */
private javax.jms.TopicConnection connection;
/* JMS session */
private TopicSession session;
...
// get Connection
Context messaging = new InitialContext();
TopicConnectionFactory connectionFactory =
(TopicConnectionFactory)messaging.lookup("TopicConnectionFactory");
connection = connectionFactory.createTopicConnection();
connection.start();
...
// get Session
session = connection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
Before you can start receiving updates, you must inform XLA which tables you want to monitor for changes.
To subscribe to changes and turn on XLA publishing for a table, call the ttXlaSubscribe built-in procedure through JDBC.
When you use ttXlaSubscribe to enable XLA publishing for a table, you must specify parameters for the name of the table and the name of the bookmark that will be used to track the table:
ttXlaSubscribe(user.table, mybookmark)
For example, call ttXlaSubscribe by the JDBC CallableStatement interface:
Connection con;
CallableStatement cStmt;
...
cStmt = con.prepareCall("{call ttXlaSubscribe(user.table, mybookmark)}");
cStmt.execute();
Use ttXlaUnsubscribe to unsubscribe from the table during shutdown. For more information, see "Unsubscribing from a table".
The application can verify table subscriptions by checking the SYS.XLASUBSCRIPTIONS system table.
For more information about using TimesTen built-in procedures in a Java application, see "Using CALL to execute procedures and functions".
LOB support in JMS/XLA is limited, as follows:
See the next section, "Receiving and processing updates", for additional notes. |
You can receive XLA updates either synchronously or asynchronously.
To receive and process updates for a topic synchronously, perform the following tasks.
Create a durable TopicSubscriber instance to subscribe to a topic.
Call receive() or receiveNoWait() on your subscriber to get the next available update.
Process the returned MapMessage instance.
To receive and process updates for a topic asynchronously, perform the following tasks.
Create a MessageListener instance to process the updates.
Create a durable TopicSubscriber instance to subscribe to a topic.
Register the MessageListener with the TopicSubscriber.
Start the connection.
|
Note: You may miss messages if you do not register theMessageListener before you start the connection. If the connection is already started, stop the connection, register the MessageListener, then start the connection. |
Wait for messages to arrive. You can call the Object method wait() to wait for messages if your application does not have to do anything else in its main thread.
When an update is published, the MessageListener method onMessage() is called and the message is passed in as a MapMessage instance.
The application can verify table subscriptions by checking the SYS.XLASUBSCRIPTIONS system table.
Example 3-6, from the asyncJMS Quick Start demo, uses a listener to process updates asynchronously.
Example 3-6 Using a listener to process updates asynchronously
MyListener myListener = new MyListener(outStream);
outStream.println("Creating consumer for topic " + topic);
Topic xlaTopic = session.createTopic(topic);
bookmark = "bookmark";
TopicSubscriber subscriber = session.createDurableSubscriber(xlaTopic, bookmark);
// After setMessageListener() has been called, myListener's onMessage
// method will be called for each message received.
subscriber.setMessageListener(myListener);
Note that bookmark must already exist. You can use JDBC and the ttXlaBookmarkCreate built-in procedure to create a bookmark. Also, the TopicSubscriber must be a durable subscriber. XLA connections are designed to be durable. XLA bookmarks make it possible to disconnect from a topic and then reconnect to start receiving updates where you left off. The string you pass in as the subscription identifier when you create a durable subscriber is used as the XLA bookmark name.
You can call unsubscribe() on the JMS TopicSession to delete the XLA bookmark used by the subscriber when the application shuts down. This causes a new bookmark to be created when the application is restarted.
When you receive an update, you can use the MapMessage getter methods to extract information from the message and then perform whatever processing your application requires. The TimesTen XlaConstants class defines constants for the update types and special message fields for use in processing XLA update messages.
The first step is typically to determine what type of update the message contains. You can use the MapMessage method getInt() to get the contents of the __TYPE field, and compare the value against the numeric constants defined in the XlaConstants class.
In Example 3-7, from the asyncJMS Quick Start demo, the method onMessage() extracts the update type from the MapMessage object and displays the action that the update signifies.
Example 3-7 Determining the update type
public void onMessage(Message message)
{
MapMessage mapMessage = (MapMessage)message;
String messageType = null;
/* Standard output stream */
private static PrintStream outStream = System.out;
if (message == null)
{
errStream.println("MyListener: update message is null");
return ;
}
try
{
outStream.println();
outStream.println("onMessage: got a " + mapMessage.getJMSType() + " message");
// Get the type of event (insert, update, delete, drop table, etc.).
int type = mapMessage.getInt(XlaConstants.TYPE_FIELD);
if (type == XlaConstants.INSERT)
{
outStream.println("A row was inserted.");
}
else if (type == XlaConstants.UPDATE)
{
outStream.println("A row was updated.");
}
else if (type == XlaConstants.DELETE)
{
outStream.println("A row was deleted.");
}
else
{
// Messages are also received for DDL events such as CREATE TABLE.
// This program processes INSERT, UPDATE, and DELETE events,
// and ignores the DDL events.
return ;
}
...
}
...
}
When you know what type of message you have received, you can process the message according to the application's needs. To get a list of all of the fields in a message, you can call the MapMessage method getMapNames(). You can retrieve individual fields from the message by name.
Example 3-8, from the asyncJMS Quick Start demo, extracts the column values from insert, update, and delete messages using the column names.
Example 3-8 Extracting column values
/* Standard output stream */
private static PrintStream outStream = System.out;
...
if (type == XlaConstants.INSERT
|| type == XlaConstants.UPDATE
|| type == XlaConstants.DELETE)
{
// Get the column values from the message.
int cust_num = mapMessage.getInt("cust_num");
String region = mapMessage.getString("region");
String name = mapMessage.getString("name");
String address = mapMessage.getString("address");
outStream.println("New Column Values:");
outStream.println("cust_num=" + cust_num);
outStream.println("region=" + region);
outStream.println("name=" + name);
outStream.println("address=" + address);
}
For detailed information about the contents of XLA update messages, see "JMS/XLA MapMessage contents". For information about how TimesTen column types map to JMS data types and the getter methods used to retrieve the column values, see "Data type support".
When the XLA application has finished reading from the transaction log, it should gracefully exit by closing the XLA connection, deleting any unneeded bookmarks, and unsubscribing from any tables to which you explicitly subscribed.
To close the connection to XLA, call close() on the Connection object.
After a connection has been closed, any attempt to use it, its sessions, or its subscribers will throw an IllegalStateException. You can continue to use messages received through the connection, but you cannot call the acknowledge() method on the received message after the connection is closed.
Deleting XLA bookmarks during shutdown is optional. Deleting a bookmark enables the disk space associated with any unread update records in the transaction log to be freed.
If you do not delete the bookmark, it can be reused by a durable subscriber. If the bookmark is available when a durable subscriber reconnects, the subscriber will receive all unacknowledged updates published since the previous connection was terminated. Keep in mind that when a bookmark exists with no application reading from it, the transaction log will continue to grow and the amount of disk space consumed by your database will increase.
To delete a bookmark, you can simply call unsubscribe() on the JMS Session, which invokes the ttXlaBookmarkDelete built-in procedure to remove the XLA bookmark.
|
Note: You cannot delete replicated bookmarks while the replication agent is running. |
To turn off XLA publishing for a table, use the ttXlaUnsubscribe built-in procedure. If you use ttXlaSubscribe to enable XLA publishing for a table, use ttXlaUnsubscribe to unsubscribe from the table when shutting down your application.
When you unsubscribe from a table, specify the name of the table and the name of the bookmark used to track the table:
ttXlaUnsubscribe(user.table, mybookmark)
The following example calls ttXlaUnSubscribe through a CallableStatement object.
Example 3-9 Unsubscribing from a table
Connection con;
CallableStatement cStmt;
...
cStmt = con.prepareCall("{call ttXlaUnSubscribe(user.table, mybookmark)}");
cStmt.execute();
For more information about using TimesTen built-in procedures in a Java application, see "Using CALL to execute procedures and functions".
TimesTen replication as described in Oracle TimesTen In-Memory Database Replication Guide is sufficient for most customer needs; however, it is also possible to use JMS/XLA to replicate updates from one database to another. Implementing your own replication scheme on top of JMS/XLA in this way is fairly complicated, but can be considered if TimesTen replication is not feasible for some reason.
The source database generates JMS/XLA messages. To apply the messages to a target database, you must extract the XLA descriptor from them. Use the MapMessage interface to extract the update descriptor:
MapMessage message;
/*
*...other code
*/
try {
byte[]updateMessage=
mapMessage.getBytes(XlaConstants.UPDATE_DESCRIPTOR_FIELD);
}
catch (JMSException jex){
/*
*...other code
*/
}
The target database may reside on a different system from the source database. The update descriptor is returned as a byte array and can be serialized for network transmission.
You must create a target database object that represents the target database so you can apply the objects from the source database. You can create a target database object named myTargetDataStore as an instance of the TargetDataStoreImpl class. For example:
TargetDataStore myTargetDataStore=
new TargetDataStoreImpl("DSN=sampleDSN");
Apply messages to myTargetDataStore by using the TargetDataStore method apply(). For example:
myTargetDataStore.apply(updateDescriptor);
By default, TimesTen checks for conflicts on the target database before applying the update. If the target database has information that is later than the update, TargetDataStore throws an exception. If you do not want TimesTen to check for conflicts, use the TargetDataStore method setUpdateConflictCheckFlag() to change the behavior.
By default, TimesTen commits the update to the database based on commit flags and transaction boundaries contained in the update descriptor. If you want the application to perform manual commits instead, use the setAutoCommitFlag() method to change the autocommit flag. To perform a manual commit on myTargetDataStore, use the following command:
myTargetDataStore.commit();
You can perform a rollback if errors occur during the application of the update. Use the following command for myTargetDataStore:
myTargetDataStore.rollback();
Close myTargetDataStore by using the following command:
myTargetDataStore.close();
See "JMS/XLA replication API" for more information about the TargetDataStore interface.
Invoking TargetDataStore can yield transient and permanent errors.
TargetDataStore methods return a nonzero value when transient errors occur. The application can retry the operation and is responsible for monitoring update descriptors that must be reapplied. For more information about transient XLA errors, see "Handling XLA errors" in Oracle TimesTen In-Memory Database C Developer's Guide.
TargetDataStore methods return a JMSException object for permanent errors. If the application receives a permanent error, it should verify that the database is valid. If the database is invalid, the target database object should be closed and a new one should be created. Other types of permanent errors may require manual intervention.
The following example shows how to recover errors from a TargetDataStore object.
Example 3-10 Recovering errors
TargetDataStore theTargetDataStore;
byte[] updateDescriptor;
int rc;
// Other code
try {
...
if ( (rc = theTargetDataStore.apply(updateDescriptor) ) == 0 ) {
// Apply successful.
}
else {
// Transient error. Retry later.
}
}
catch (JMSException jex) {
if (theTargetDataStore.isDataStoreValid() ) {
// Database valid; permanent error that may need Administrator intervention.
}
else {
try {
theTargetDataStore.close();
}
catch (JMSException closeEx) {
// Close errors are not usual. This may need Administrator intervention.
}
}
This chapter provides tips on how to tune a Java application to run optimally on a TimesTen database. See "TimesTen Database Performance Tuning" in Oracle TimesTen In-Memory Database Operations Guide for more general tuning tips.
This chapter is organized as follows:
This section describes general principles to consider when tuning JDBC applications for TimesTen. It includes the following topics:
|
Note: Also see "Working with TimesTen result sets: hints and restrictions" and the notes in "Binding parameters and executing statements". |
TimesTen supports prepared statement pooling for pooled connections, as discussed in the JDBC 3.0 specification, through the TimesTen ObservableConnectionDS class. This is the TimesTen implementation of ConnectionPoolDataSource. Note that statement pooling is transparent to an application. Use of the PreparedStatement object, including preparing and closing the statement, is no different.
Enable prepared statement pooling and specify the maximum number of statements in the pool by calling the ObservableConnectionDS method setMaxStatements(). A value of 0, the default, disables prepared statement pooling. Any integer value greater than 0 enables prepared statement pooling with the value taken as the maximum number of statements. Once set, this value should not be changed.
Prepared statements or callable statements will be pooled at the time of creation if the pool has not reached its capacity. In Java 6, you can remove a prepared statement or callable statement from the pool by calling setPoolable(false) on the statement object. After the statement is closed, it will be removed from the pool.
|
Important: With prepared statement pooling, JDBC considers two statements to be identical if their SQL (including comments) is identical, regardless of other considerations such as optimizer settings. Do not use prepared statement pooling in a scenario where different optimizer hints may be applied to statements that are otherwise identical. In this scenario, a statement execution may result in the use of an identical statement from the pool with an unpredictable optimizer setting. |
You can improve performance by using groups, referred to as batches, of statement executions, calling the addBatch() and executeBatch() methods for Statement or PreparedStatement objects.
A batch can consist of a set of INSERT, UPDATE, DELETE, or MERGE statements. Statements that return result sets, such as SELECT statements, are not allowed in a batch. A SQL statement is added to a batch by calling addBatch() on the statement object. The set of SQL statements associated with a batch are executed through the executeBatch() method.
For PreparedStatement objects, the batch consists of repeated executions of a statement using different input parameter values. For each set of input values, create the batch by using appropriate setXXX() calls followed by the addBatch() call. The batch is executed by the executeBatch() method.
TimesTen recommends the following batch sizes for TimesTen 11g Release 2 (11.2.2):
256 for INSERT statements
31 for UPDATE statements
31 for DELETE statements
31 for MERGE statements
Example 5-1 Batching statements
// turn off autocommit
conn.setAutoCommit(false);
Statement stmt = conn.createStatement();
stmt.addBatch("INSERT INTO employees VALUES (1000, 'Joe Jones')");
stmt.addBatch("INSERT INTO departments VALUES (260, 'Shoe')");
stmt.addBatch("INSERT INTO emp_dept VALUES (1000, 260)");
// submit a batch of update commands for execution
int[] updateCounts = stmt.executeBatch();
conn.commit ();
Example 5-2 Batching prepared statements
// turn off autocommit
conn.setAutoCommit(false);
// prepare the statement
PreparedStatement stmt = conn.prepareStatement
("INSERT INTO employees VALUES (?, ?)");
// first set of parameters
stmt.setInt(1, 2000);
stmt.setString(2, "Kelly Kaufmann");
stmt.addBatch();
// second set of parameters
stmt.setInt(1, 3000);
stmt.setString(2, "Bill Barnes");
stmt.addBatch();
// submit the batch for execution. Check update counts
int[] updateCounts = stmt.executeBatch();
conn.commit ();
For either a Statement or PreparedStatement object, the executeBatch() method returns an array of update counts (updateCounts[] in Example 5-1 and Example 5-2 above), with one element in the array for each statement execution. The value of each element can be any of the following:
A number indicating how many rows in the database were affected by the corresponding statement execution
SUCCESS_NO_INFO, indicating the corresponding statement execution was successful, but the number of affected rows is unknown
EXECUTE_FAILED, indicating the corresponding statement execution failed
Once there is a statement execution with EXECUTE_FAILED status, no further statement executions will be attempted.
For more information about using the JDBC batch update facility, refer to the Javadoc for the java.sql.Statement interface, particularly information about the executeBatch() method, at the following locations (the first for Java 6, the second for Java 5):
http://docs.oracle.com/javase/6/docs/api/http://docs.oracle.com/javase/1.5.0/docs/api/
|
Note: Associative array parameters are not supported with JDBC batch execution. (See "Binding associative arrays".) |
TimesTen provides an extension that allows an application to fetch multiple rows of data. For applications that retrieve large amounts of TimesTen data, fetching multiple rows can increase performance greatly. However, when using Read Committed isolation level, locks are held on all rows being retrieved until the application has received all the data, decreasing concurrency. For more information on this feature, see "Fetching multiple rows of data".
Because Java strings are immutable, the ResultSet method getString() must allocate space for a new string in addition to translating the underlying C string to a Unicode string, making it a costly call.
In addition, you should not call getString() on primitive numeric types, like byte or int, unless it is absolutely necessary. It is much faster to call getInt() on an integer column, for example.
TimesTen instruction paths are so short that even small delays due to data conversion can cause a relatively large percentage increase in transaction time.
Use the appropriate getXXX() method on a ResultSet object for the data type of the data in the underlying database. For example, if the data type of the data is DOUBLE, to avoid data conversion in the JDBC driver you should call getDouble(). Similarly, use the appropriate setXXX() method on the PreparedStatement object for the input parameter in an SQL statement. For example, if you are inserting data into a CHAR column using a PreparedStatement, you should use setString().
For better performance, always close JDBC objects such as connection, statement, and result set instances when finished using them. Example 5-3 shows typical usage.
Example 5-3 Closing connection, statement, and result set
Connection conn = null;
Statement stmt = null;
ResultSet rs = null;
try {
// create connections, execute statements, etc.
// Handle any errors
} catch (SQLException ex) {
// See "Handling errors".
}
finally {
// Close JDBC objects such as connections, statements, result sets, etc.
if (rs != null) {
try {
rs.close();
}
catch(SQLException finalex) {
// See "Handling errors".
}
}
if (stmt != null) {
try {
stmt.close();
}
catch(SQLException finalex) {
// See "Handling errors".
}
}
// Always, close the connection to TimesTen
if (conn != null) {
try {
conn.close();
}
catch(SQLException finalex) {
// See "Handling errors".
}
}
This section contains specific performance tuning tips for applications that use the JMS/XLA API. JMS/XLA has some overhead that makes it slower than using the C XLA API. In the C API, records are returned to the user in a batch. In the JMS model an object is instantiated and each record is presented one at a time in a callback to the MessageListener method onMessage(). High performance applications can use some tuning to overcome some of this overhead.
This section includes the following topics:
The code underlying the JMS layer that reads the transaction log is more efficient if it can fetch as many rows as possible before presenting the object/rows to the user. The amount of prefetching is controlled in the jmsxla.xml configuration file with the xlaPrefetch parameter. Set the prefetch count to a large value like 100 or 1000.
In JMS/XLA, acknowledging updates moves the bookmark and results in updates to system tables. You can typically improve application performance by waiting until several updates have been detected before issuing the acknowledgment. You can control the acknowledgment frequency in either of the following modes. (See "XLA acknowledgment modes" for related information.)
DUPS_OK_ACKNOWLEDGE, where JMS/XLA prefetches records according to the xlaprefetch setting, and an acknowledgment is automatically sent when the last record in the prefetched block is read.
CLIENT_ACKNOWLEDGE, where you manually call the acknowledge() method on the MapMessage instance as desired.
The appropriate choice for acknowledgment frequency depends on your application logic. Acknowledging after every 100 updates, for example, has been used successfully. Be aware, however, that there is a tradeoff. Acknowledgments affect XLA log holds, and acknowledging too infrequently may result in undesirable log file accumulation. (Also see "XLA bookmarks and transaction log holds".)
|
Note: InDUPS_OK_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE mode, the reader application must have some tolerance for seeing the same set of records more than once. |
The synchronous interface is suitable only for applications with low event rates and for which AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE acknowledgment modes are acceptable. Applications that require CLIENT_ACKNOWLEDGE acknowledgment mode and applications with high event rates should use the asynchronous interface for receiving updates. They should acknowledge the messages on the callback thread itself if they are using CLIENT_ACKNOWLEDGE as acknowledgment mode. See "Receiving and processing updates".
