Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks
An Oracle White Paper April 2008
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks
Introduction ...... 3 TimesTen for Oracle Application Server 10g...... 3 Configuring the TimesTen JDBC driver...... 3 Configuring connection pools and data sources...... 4 TimesTen for JBoss 4 ...... 12 Configuring the TimesTen JDBC driver...... 12 Configuring CMP type mappings for TimesTen ...... 13 Configuring TimesTen data sources ...... 15 TimesTen for WebLogic Server 9...... 18 Configuring the TimesTen JDBC driver...... 18 Configuring TimesTen data sources ...... 19 TimesTen for Sun Java System Application Server 9 ...... 24 Configuring the TimesTen JDBC driver...... 25 Configuring TimesTen connections ...... 25 Configuring a TimesTen JDBC connection pool ...... 26 Configuring a TimesTen JDBC resource...... 28 TimesTen for WebSphere Application Server 6...... 29 Configuring TimesTen connections ...... 29 Configuring a TimesTen JDBC provider...... 30 Configuring TimesTen data sources ...... 33 TimesTen for Oracle TopLink 10g ...... 35 Configuring the TimesTen JDBC driver for TopLink Workbench....36 Configuring a TimesTen database login from TopLink Workbench .36 JDBC settings for the database login...... 37 TimesTen for Hibernate 3.2 ...... 38 Configuring the TimesTen JDBC driver for Hibernate...... 38 Hibernate configuration properties for TimesTen ...... 39
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 2 Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks
INTRODUCTION This whitepaper is for application developers who use and administer Oracle TimesTen JDBC and for system administrators who configure and manage the TimesTen database. It provides information about configuring your application server and object–relational mapping framework for use with Oracle TimesTen 7.0.
TIMESTEN FOR ORACLE APPLICATION SERVER 10G This section provides descriptions and examples of configuring the TimesTen Configuring Oracle Application Server JDBC driver for use with Oracle Application Server 10g Release 3. This document and TimesTen assumes that Oracle TimesTen and Oracle Application Server have been successfully installed on the same host machine and that both instances are running.
Configuring the TimesTen JDBC driver Before you can use Oracle Application Server (AS) to access TimesTen databases, the Oracle AS environment must have access to the TimesTen JDBC driver jar file and the native TimesTen libraries. 1. Copy one of the TimesTen JDBC driver jar files from install_dir /lib to Oracle_install_dir /j2ee/home/applib . If Oracle AS is using JDK 1.4, copy the install_dir /lib/ttjdbc14.jar file. If Oracle AS is using JDK 5, copy the install_dir /lib/ttjdbc5.jar file.
Where install_dir is the directory in which you installed Oracle TimesTen, and Oracle_install_dir is the directory in which you installed Oracle Application Server. 2. Set the LD_LIBRARY_PATH environment variable (or the equivalent variable for your OS) to include the install_dir /lib directory. On Windows, the PATH environment variable should be set to the install_dir /bin directory where TimesTen DLLs are located. This variable must be set for the environment where Oracle AS runs.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 3 3. If you use OPMN (Oracle Process Manager and Notification Service) to start the application server, the OPMN configuration file requires modification to include the location of the TimesTen shared libraries. The OPMN configuration file is located at Oracle_install_dir /opmn/conf/opmn.conf .
Open this file and add an entry for the LD_LIBRARY_PATH environment variable (or the equivalent variable for your OS) under the ias-component element associated with the application server. For example, an Oracle Application Server called 'OC4J' uses the TimesTen JDBC driver on the Windows platform. The opmn.conf configuration would look similar to this:
Configuring connection pools and data sources The TimesTen JDBC driver supports four different types of connections to TimesTen databases. • Direct access with local transactions only – This configuration provides the fastest database performance. The TimesTen database must reside on the same machine as TimesTen and Oracle AS. • Direct access with XA distributed transaction support - The driver supports both local and distributed transactions. The TimesTen database must reside on the same machine as TimesTen and Oracle AS. • Client/server access with local transactions only - The TimesTen database may reside on a remote machine that is running the TimesTen server. • Client/server access with XA distributed transaction support - The driver supports both local and distributed transactions. The TimesTen database may reside on a remote machine that is running the TimesTen server. Each type of TimesTen JDBC driver connection requires a unique connection pool configuration in the Oracle Application Server. One or more data source objects may be associated with each connection pool. Example connection pool and data source configurations are described below for each of the four types of TimesTen connections. The examples below reference a TimesTen direct access DSN named RunData_tt70 and a client/server access DSN named RunDataCS_tt70 . These TimesTen DSNs must be configured in the .odbc.ini or sys.odbc.ini file or Windows Data Source Administrator before the examples can work.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 4 Direct access connection pool (local transactions only) TimesTen Class: com.timesten.jdbc.TimesTenDriver Example URL: jdbc:timesten:direct:RunData_tt70
Figure 1.1 Example of the OM configuration page for Direct Access Connection Pool – local transactions only
Example Oracle_install_dir/j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 5 Direct access data source (local transactions only)
Figure 1.2 Example of the OM configuration page for direct access data source – local transactions only
Example Oracle_install_dir /j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 6 Example URL: jdbc:timesten:direct:RunData_tt70
Figure 1.3 Example of the OM configuration page for direct access connection pool – local and distributed XA transactions
Example Oracle_install_dir /j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 7 Direct access data source (local & distributed XA transactions)
Figure 1.4 Example of the OM configuration page for direct access data source – local and distributed XA transactions
Example Oracle_install_dir /j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 8 Example URL: jdbc:timesten:client:RunDataCS_tt70
Figure 1.5 Example of the OM configuration page for Client/Server access connection pool – local transactions only
Example Oracle_install_dir/j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 9 Client/server Access Data Source (Local Transactions Only)
Figure 1.6 Example of the OM configuration page for Client/Server access data source – local transactions only
Example Oracle_install_dir/j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 10
Figure 1.7 Example of the OM configuration page for Client/Server access connection pool – local & distributed XA transactions
Example Oracle_install_dir/j2ee/home/config/data- sources.xml entry:
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 11 Client/server access data source (local & distributed XA transactions)
Figure 1.8 Example of the OM configuration page for Client/Server access data source – local & distributed XA transactions
Example Oracle_install_dir/j2ee/home/config/data- sources.xml entry:
TIMESTEN FOR JBOSS 4 This section provides descriptions and examples of configuring the TimesTen Configuring JBoss Application Server JDBC driver for use with JBoss 4 Application Server. This document assumes that and TimesTen Oracle TimesTen and JBoss Application Server have been successfully installed on the same host machine and that both instances are running.
Configuring the TimesTen JDBC driver Before you can use JBoss to access TimesTen databases the JBoss environment must have access to the TimesTen JDBC driver jar file and the TimesTen shared libraries. 1. Copy one of the TimesTen JDBC driver jar files from install_dir /lib to JBOSS_install_dir /server/default/lib . If JBoss is using JDK 1.4, copy the install_dir /lib/ttjdbc14.jar file. If JBoss is using JDK 1.5, copy the install_dir /lib/ttjdbc5 .jar file.
Where install_dir is the directory in which you installed Oracle TimesTen, and JBOSS _install_dir is the directory in which you installed JBoss Application Server. 2. Set the LD_LIBRARY_PATH environment variable (or the equivalent variable for your OS) to include the install_dir /lib directory. On
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 12 Windows, set the PATH environment variable to the install_dir /bin directory where the TimesTen DLLs are located. This variable must be set for the environment where JBoss runs. 3. Restart the JBoss server for the changes to take effect.
Configuring CMP type mappings for TimesTen
In order for TimesTen to work with various features of Container Managed Persistence (CMP) in JBoss, a JDBC to SQL type mapping definition is used. An example type mapping definition for TimesTen 7.0 can be downloaded from http://www.oracle.com/technology/products/timesten/sample_code
Example 2.1 Example of the type mapping descriptor for TimesTen
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 13
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 14
TimesTen 7.0 operates in two distinct SQL type modes: Oracle type mode and TimesTen type mode. The example type mapping definition operates in either mode. However, it may be appropriate to modify the mappings to completely conform to one of the two modes or to improve performance for a particular application.
To configure the JBoss server to access the example TimesTen type mapping definition, copy the complete definition into the
Configuring TimesTen data sources The TimesTen JDBC driver supports four different types of connections to TimesTen databases. • Direct access with local transactions only - This configuration provides the fastest database performance. The TimesTen database must reside on the same machine as TimesTen and JBoss. • Direct access with XA distributed transaction support - The driver supports XA distributed transactions. The TimesTen database must reside on the same machine as TimesTen and JBoss. • Client/server access with local transactions only - The TimesTen database may reside on a remote machine that is running the TimesTen server. • Client/server access with XA distributed transaction support - The driver supports XA distributed transactions. The TimesTen database may reside on a remote machine that is running the TimesTen server. Each type of TimesTen JDBC driver connection requires a unique data source configuration in JBoss. A data source deployment descriptor file is named using a *-ds.xml pattern and is placed in the deploy directory of the JBoss server.
A sample deployment descriptor file called timesten-ds.xml can be downloaded from http://www.oracle.com/technology/products/timesten/sample_code . This file defines all four types of TimesTen data sources. The file references a TimesTen direct access DSN named RunData_tt70 and a client/server access DSN named RunDataCS_tt70 . These TimesTen DSNs must be configured in the .odbc.ini or sys.odbc.ini file or in the Windows Data Source Administrator before the examples can work. Place the file in the JBOSS _install_dir /server/default/deploy directory and restart the JBoss server to allow applications to connect to TimesTen.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 15 Example 2.2 Example of the deployment descriptor file, it includes 4 distinct types of connections that can be configured for TimesTen
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 17
TIMESTEN FOR WEBLOGIC SERVER 9 This section provides descriptions and examples of configuring the TimesTen Configuring BEA WebLogic Server JDBC driver for use with BEA WebLogic Server 9.2 MP1. This document assumes and TimesTen that Oracle TimesTen and WebLogic Server have been successfully installed on the same host machine and that both instances are running.
Configuring the TimesTen JDBC driver Before you can use WebLogic Server to access TimesTen databases, the server environment must have access to the TimesTen JDBC driver jar file and the native TimesTen libraries. 1. Edit the WL_install_dir /common/bin/commEnv.sh script on UNIX or the WL_install_dir /common/bin/commEnv.cmd script on Windows. Append the path to the TimesTen JDBC driver jar file to the WEBLOGIC_CLASSPATH variable defined in the file. If WebLogic Sever is running JDK 5, use the TimesTen driver jar file at install_dir /lib/ttjdbc5.jar. Otherwise use the JDK 1.4 jar file at install_dir /lib/ttjdbc14.jar .
Where WL_install_dir is the directory in which you installed WebLogic Server, and install_dir is the directory in which you installed Oracle TimesTen. 2. You must also modify the LD_LIBRARY_PATH (or equivalent variable for you OS) to locate the TimesTen shared libraries. Append the install_dir /lib path to the LD_LIBRARY_PATH (or equivalent)
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 18 variable in the WL_install_dir /common/bin/commEnv.sh file. On Windows platforms, append the PATH environment variable with the install_dir /bin directory where TimesTen DLLs are located. 3. After completing these steps you must restart the WebLogic Server for the changes to take effect.
Configuring TimesTen data sources The TimesTen JDBC driver supports four different types of connections to TimesTen databases. • Direct access with non-XA local transactions only - This configuration provides the fastest database performance. The TimesTen database must reside on the same machine as TimesTen and WebLogic. • Direct access with TimesTen XA distributed transaction support - The driver supports distributed transactions. The TimesTen database must reside on the same machine as TimesTen and WebLogic. • Client/server access with non-XA local transactions only - The TimesTen database may reside on a remote machine that is running the TimesTen server. • Client/server access with TimesTen XA distributed transaction support - The driver supports distributed transactions. The TimesTen database may reside on a remote machine that is running the TimesTen server. Each type of TimesTen JDBC driver connection requires a unique data source configuration. The examples below reference a TimesTen direct access DSN named RunData_tt70 and a client/server access DSN named RunDataCS_tt70 . These TimesTen DSNs must be configured in the .odbc.ini or sys.odbc.ini file or the Windows Data Source Administrator before the examples can work. A data source is usually configured using the WebLogic console. Below is an example procedure for configuring a TimesTen data source with the console. 1. Connect to the WebLogic Server Administration Console and click Data Sources . 2. Click Lock & Edit and then click New . 3. At the JDBC Data Source Properties screen type a name and a JNDI name for the data source. In the Database Type and the Database Driver drop down list boxes select Other . The screen should look similar to figure 3.1.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 19 Figure 3.1 JDBC Data source properties screen
Click Next . 4. At the Transaction Options screen, make sure that the Supports Global Transactions check box is checked. If you desire a non-XA TimesTen connection, select one of the three transaction protocol options. The screen should look similar to figure 3.2.
Figure 3.2 Transaction Options screen
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 20
Click Next . (Note: If you desire a TimesTen XA connection, the transaction protocol options on this screen are ignored. Instead, WebLogic uses the TimesTen implementation of XAResource to control transactions.) 5. At the Connection Properties screen enter a database name, host name and port. These attributes are required by WebLogic but are not used by the TimesTen JDBC driver. The screen should look similar to figure 3.3.
Figure 3.3 Connection Properties screen
Click Next . 6. At the Test Database Connection screen enter the name of the TimesTen JDBC driver. If you desire a non-XA connection, specify the com.timesten.jdbc.TimesTenDriver class. If you desire a TimesTen XA connection, specify the com.timesten.jdbc.xa.TimesTenXADataSource class. Enter a TimesTen JDBC URL for the TimesTen DSN that the data source should connect to. A TimesTen URL takes the form: jdbc:timesten:[direct|client]: DSN . For a direct DSN named RunData_tt70 the screen should look similar to figure 3.4.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 21 Figure 3.4 Test Database Connection screen
Click Next . 7. At the Select Targets screen, select which WebLogic servers should be associated with the data source. Click Finish . 8. Click Activate Changes to complete the configuration. When a data source is configured in the WebLogic console an XML file with the name pattern of *-jdbc.xml is created in the WL_domain_dir /config/jdbc directory, where WL_domain_dir is the directory containing the WebLogic Server domain. Sample configuration files for the four different types of TimesTen connections are listed below. To use these configuration files, download them from http://www.oracle.com/technology/products/timesten/sample_code and then copy them to the WL_domain_dir /config /jdbc directory. The WL_domain_dir /config/config.xml file must also be edited to include a reference to the data source configuration file. For example if you use the RunDataDirectDS-jdbc.xml file, the WL_domain_dir /config/config.xml includes an entry like this in the
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 22 Direct access data source (non-XA local transactions) TimesTen Class: com.timesten.jdbc.TimesTenDriver Example URL: jdbc:timesten:direct:RunData_tt70 Example Data Source Configuration File: RunDataDirectDS-jdbc.xml
Figure 3.5 Example data source configuration file -
Direct access data source (timesten XA transactions) TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL: jdbc:timesten:direct:RunData_tt70 Example Data Source Configuration File: RunDataDirectXADS-jdbc.xml
Figure 3.6 Example data source configuration file -
Client/Server access data source (non-XA local transactions) TimesTen Class: com.timesten.jdbc.TimesTenDriver Example URL: jdbc:timesten:client:RunDataCS_tt70
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 23 Example Data Source Configuration File: RunDataClientDS-jdbc.xml
Figure 3.7 Example data source configuration file -
Client/Server access data source (timesten XA transactions) TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL: jdbc:timesten:client:RunDataCS_tt70 Example Data Source Configuration File: RunDataClientXADS-jdbc.xml
Figure 3.8 Example data source configuration file -
TIMESTEN FOR SUN JAVA SYSTEM APPLICATION SERVER 9 This section provides descriptions and examples of configuring the TimesTen Configuring Sun Java System Application JDBC driver for use with Sun Java System Application Server 9.0_01. This Server and TimesTen document assumes that Oracle TimesTen and Sun Java System Application Server have been successfully installed on the same host machine and that both instances are running.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 24 Configuring the TimesTen JDBC driver Before you can use Sun Java System Application Server (Sun AS) to access TimesTen databases, the server environment must have access to the TimesTen JDBC driver jar file and the native TimesTen libraries. 1. Copy one of the TimesTen JDBC driver jar files from install_dir/lib to the SunAS_install_dir /lib/ext directory. If Sun AS is using JDK 1.4, copy the install_dir /lib/ttjdbc14.jar file. If Sun AS is using JDK 1.5, copy the install_dir /lib/ttjdbc5.jar file.
Where install_dir is the directory in which you installed Oracle TimesTen, and SunAS_install_dir is the location of the domain directory for Sun AS 2. Set the LD_LIBRARY_PATH environment variable (or the equivalent variable for your OS) to include the install_dir /lib directory. On Windows platforms, set the PATH environment variable to the install_dir /bin directory where TimesTen DLLs are located. This variable must be set for the environment where Sun AS runs. 3. Restart Sun AS for the changes to take effect.
Configuring TimesTen connections
The TimesTen JDBC driver supports four different types of database connections. • Direct access with local transactions only – This configuration provides the fastest database performance. The TimesTen data store must reside on the same machine as TimesTen and Sun AS. • Direct access with XA distributed transaction support - The driver supports distributed transactions. The TimesTen data store must reside on the same machine as TimesTen and Sun AS. • Client/server access with local transactions only - The TimesTen data store may reside on a remote machine that is running the TimesTen server. • Client/server access with XA distributed transaction support - The driver supports distributed transactions. The TimesTen data store may reside on a remote machine that is running the TimesTen server.
Properties of TimesTen connections When configuring TimesTen connections in Sun AS use the following settings. Direct access with local transactions only: TimesTen Class: com.timesten.jdbc.ObservableConnectionDS
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 25 Example URL Property: jdbc:timesten:direct:RunData_tt70 Direct access with XA distributed transaction support: TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL Property: jdbc:timesten:direct:RunData_tt70 Client/server access with local transactions only: TimesTen Class: com.timesten.jdbc.ObservableConnectionDS Example URL Property: jdbc:timesten:client:RunDataCS_tt70 Client/server access with XA distributed transaction support: TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL Property: jdbc:timesten:client:RunDataCS_tt70
Configuring a TimesTen JDBC connection pool To configure a TimesTen JDBC connection pool in Sun AS follow these steps. 1. Connect to the Sun AS administration console . 2. Select Resources->JDBC->Connection Pools from the left hand pane. 3. Click New . 4. At the New Connection Pool (Step 1 of 2) screen enter a name for the new pool in the Name field. In the Database Vendor field select Oracle . In the Resource Type drop down list box select javax.sql.ConnectionPoolDataSource if the application requires only local transactions. If the application requires XA distributed transactions, select javax.sql.XADataSource instead. The screen should look similar to figure 4.1.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 26 Figure 4.1 New Connection Pool Screen
Click Next . 5. At the New Connection Pool (Step 2 of 2) screen enter com.timesten.jdbc.ObservableConnectionDS in the Datasource Classname field for local transactions. Enter com.timesten.jdbc.xa.TimesTenXADataSource if XA distributed transactions are required. 6. Scroll down to the Properties section at the bottom of the screen. Click Add . A new row will appear in the Properties section of the screen. Click the check box in the new row. Type 'url' in the Name column. In the Value column enter the TimesTen URL for the data store to which this pool should connect. A TimesTen URL takes the form: jdbc:timesten:[direct|client]: DSN . For a direct DSN named RunData_tt70 the screen should look similar to figure 4.2.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 27 Figure 4.2 Properties screen
Click Finish .
Configuring a TimesTen JDBC resource In order for applications to access the TimesTen connection pool a JDBC resource must be created and associated with the pool. Follow these steps. 1. Connect to the Sun AS administration console . 2. Select Resources->JDBC->JDBC Resources from the left hand pane. 3. Click New . 4. At the New JDBC Resource screen enter a JNDI name for the resource. In the Pool Name field select the name of the TimesTen connection pool. The screen should look similar to figure 4.3.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 28 Figure 4.3 JDBC Resources screen
Click OK .
TIMESTEN FOR WEBSPHERE APPLICATION SERVER 6 This section provides descriptions and examples of configuring the TimesTen Configuring IBM WebSphere Application JDBC driver for use with IBM WebSphere Application Server 6.1.0.3. This Server and TimesTen document assumes that Oracle TimesTen and IBM WebSphere Application Server have been successfully installed on the same host machine and that both instances are running.
Configuring TimesTen connections
The TimesTen JDBC driver supports four different types of database connections. • Direct access with local transactions only - This configuration provides the fastest database performance. The TimesTen data store must reside on the same machine as TimesTen and WebSphere. • Direct access with XA distributed transaction support - The driver supports distributed transactions. The TimesTen data store must reside on the same machine as TimesTen and WebSphere. • Client/server access with local transactions only - The TimesTen data store may reside on a remote machine that is running the TimesTen server.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 29 • Client/server access with XA distributed transaction support - The driver supports distributed transactions. The TimesTen data store may reside on a remote machine that is running the TimesTen server. Properties of TimesTen connections When configuring TimesTen connections in WebSphere use the following settings. Direct access with local transactions only: TimesTen Class: com.timesten.jdbc.ObservableConnectionDS Example URL Property: jdbc:timesten:direct:RunData_tt70 Direct access with XA distributed transaction support: TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL Property: jdbc:timesten:direct:RunData_tt70 Client/server access with local transactions only: TimesTen Class: com.timesten.jdbc.ObservableConnectionDS Example URL Property: jdbc:timesten:client:RunDataCS_tt70 Client/server access with XA distributed transaction support: TimesTen Class: com.timesten.jdbc.xa.TimesTenXADataSource Example URL Property: jdbc:timesten:client:RunDataCS_tt70
Configuring a TimesTen JDBC provider Before you can use WebSphere to access TimesTen data stores the server environment must have access to the TimesTen JDBC driver jar file and the native libraries. In WebSphere this can be done by configuring a JDBC provider in the WebSphere administration console. Follow these steps. 1. Connect to the D. 2. Select Resources->JDBC->JDBC Providers . 3. Select a scope from the drop down list box. 4. Click New . 5. At the Create new JDBC provider screen select ‘User-defined’ for Database type . To create an XA capable TimesTen connection, enter the com.timesten.jdbc.xa.TimesTenXADataSource class name in the Implementation class name field. For a TimesTen connection supporting only local transactions, enter the com.timesten.jdbc.ObservableConnectionDS class name in this field. Enter a name for the configuration in the Name field. The screen should look similar to figure 5.1.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 30 Figure 5.1 Create new JDBC provider screen
Click Next . 6. At the Enter database class path information screen enter the path to the TimesTen JDBC driver. If WebSphere is running JDK 5, use the TimesTen driver jar file at install_dir /lib/ttjdbc5.jar . Otherwise use the JDK 1.4 jar file at install_dir /lib/ttjdbc14.jar , where install_dir is the directory in which you installed Oracle TimesTen. The screen should look similar to figure 5.2.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 31 Figure 5.2 Enter database class path information screen
Click Next . 7. On the summary screen click Finish . 8. At the JDBC providers screen click the provider name that you just created. 9. At the General properties screen enter the path to the TimesTen shared libraries in the Native library path field. On UNIX platforms the path is install_dir /lib . On Windows platforms the path is install_dir /bin . The screen should look similar to figure 5.3.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 32 Figure 5.3 General properties screen
Click Apply . 10. Click Save to save the new configuration.
Configuring TimesTen data sources Data sources are associated with specific JDBC providers defined in the previous section. Follow these steps to configure TimesTen data sources from the WebSphere administration console. 1. Connect to the WebSphere administration console . 2. Select Resources->JDBC->Data sources . 3. Select a scope from the drop down list box. 4. Click the New button. 5. At the Enter basic data source information screen enter a name and a JNDI name for the data source. Click Next . 6. At the Select JDBC provider screen select the TimesTen JDBC Provider created in the previous section. Click Next . 7. At the Enter database specific properties for the data source screen use com.ibm.websphere.rsadapter.GenericDataStoreHelp er for the Data store helper class name field. Make sure that the Use this data store in container managed persistence check box is checked. Click Next .
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 33 8. On the following summary screen click Finish . 9. At the Data sources screen click on the name of the TimesTen data source that you just created. 10. Click Custom properties . 11. Click url property . 12. In the value field enter the TimesTen JDBC URL for the DSN that this data source should connect to. A TimesTen URL takes the form: jdbc:timesten:
Figure 5.4 Data Sources screen
Click Apply . 13. Click Save to save the new configuration. 14. Restart the server before attempting to make connections to the new TimesTen data source.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 34 Troubleshooting TimesTen connections Various problems may occur when using TimesTen with WebSphere. The list below describes possible solutions for common problems. 1. When clicking on Test Connection for a TimesTen data source on the Data sources screen of the administration console, TimesTen throws a java.lang.IllegalAccessError exception. This problem can occur if you have configured a new TimesTen data source but have not restarted the server. Try restarting the server to solve the problem. 2. When attempting to establish a connection to a TimesTen data source from within WebSphere, TimesTen throws the exception “TT0837: Cannot attach data store shared-memory segment.” This problem is likely to occur on 32-bit platforms when the system is unable to allocate or map enough contiguous shared memory to hold the TimesTen data store. For detailed instructions on how to resolve this and other connection problems see the Oracle TimesTen In-Memory Database Troubleshooting Procedures Guide and the Oracle TimesTen In-Memory Database Installation Guide . These troubleshooting steps are recommended. a. Verify that it is possible to connect to the TimesTen data store outside of the WebSphere JVM. You can use the ttIsql utility for this purpose. b. Try increasing the maximum amount of shared memory available to the system. See the Oracle TimesTen In-Memory Database Installation Guide for platform specific details. c. Try decreasing the size of the TimesTen data store by recreating the data store with lower values for the PermSize and TempSize connection attributes. d. Terminate any unnecessary processes on the system to make more memory available. e. Try a client/server TimesTen JDBC connection instead of a direct connection for the WebSphere data source. f. If possible try a 64-bit version of TimesTen and WebSphere.
TIMESTEN FOR ORACLE TOPLINK 10G This section provides descriptions and examples of configuring the TimesTen Configuring Oracle TopLink 10g and JDBC driver for use with Oracle TopLink 10g (10.1.3.1.0). This document assumes TimesTen that Oracle TimesTen and the standalone version of TopLink (including TopLink Workbench) have been installed on the same machine.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 35 Configuring the TimesTen JDBC driver for TopLink Workbench
1. Open the Oracle_install_dir /toplink/bin/setenv.cmd file on Windows or the Oracle_install_dir /toplink/bin/setenv.sh file on UNIX platforms for editing, where Oracle_install_dir is the directory in which you installed Oracle TopLink. 2. Set the JAVA_HOME variable in the file to a supported JDK. 3. Include the path to the TimesTen JDBC driver jar file for the definition of the DRIVER_CLASSPATH variable in the file. If JAVA_HOME is set to a JDK 1.4 installation, use the install_dir /lib/ttjdbc14.jar file. If JAVA_HOME is set to a JDK 5 installation, use the install_dir /lib/ttjdbc5.jar file, where install_dir is the directory in which you installed Oracle TimesTen 4. Add an LD_LIBRARY_PATH entry (or equivalent variable for your OS) to the file. You must set this variable to the path of the TimesTen shared libraries at install_dir /lib . On Windows platforms, set the PATH environment variable to the install_dir /bin directory where TimesTen DLLs are located. For example on UNIX if install_dir is /opt/TimesTen/tt70 , the setenv.sh file variables might look like this:
DRIVER_CLASSPATH=/opt/TimesTen/tt70/lib/ttjdbc5.jar; export DRIVER_CLASSPATH LD_LIBRARY_PATH=/opt/TimesTen/tt70/lib; export LD_LIBRARY_PATH JAVA_HOME=/usr/java/jdk1.5.0_09; export JAVA_HOME
Configuring a TimesTen database login from TopLink Workbench In order to connect to a TimesTen data store from within a TopLink Workbench project a database login configuration is required. When configuring a database login use the settings: Database Platform: TimesTen Driver Class: com.timesten.jdbc.TimesTenDriver A URL for the TimesTen data store is also required. When connecting in direct access mode the URL takes the form of jdbc:timesten:direct:
An example of a TimesTen database login configuration from within TopLink Workbench is shown in figure 6.1.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 36 Figure 6.1 Database Login screen
JDBC settings for the database login A TopLink database login configuration may also contain JDBC settings that can dramatically improve performance of TimesTen. When configuring a TopLink database login be sure to set the following JDBC options as follows: • Set the bind-all-parameters property to true. • Set the cache-all-statements property to true • Set the batch-writing and jdbc-batch-writing properties to true These JDBC properties can be set within TopLink WorkBench when configuring a database session. An example is shown in figure 6.2.
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 37 Figure 6.2 JDBC Options for Database Login
These properties may also be set manually within the sessions.xml or in the toplink-ejb-jar.xml configuration files as shown below.
TIMESTEN FOR HIBERNATE 3.2 This section provides descriptions and examples of configuring the TimesTen Configuring Hibernate and TimesTen JDBC driver for use with Hibernate 3.2. This document assumes that Oracle TimesTen and Hibernate have been successfully installed on the same machine.
Configuring the TimesTen JDBC driver for Hibernate When accessing a TimesTen database from a Hibernate application, you must set the CLASSPATH environment variable to include the TimesTen JDBC driver jar
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 38 file. When using JDK 1.4 add install_dir /lib/ttjdbc14.jar to the CLASSPATH. When using JDK 5 add the install_dir /lib/ttjdbc5.jar file to the CLASSPATH, where install_dir is the directory in which you installed Oracle TimesTen. Set the LD_LIBRARY_PATH (or equivalent for your OS) environment variable to include the path to the TimesTen shared libraries located at install_dir /lib . On Windows platforms the PATH environment variable should be set to the install_dir /bin directory where TimesTen DLLs are located. A new Hibernate dialect class called org.hibernate.dialect.TimesTen7Dialect has been developed for use with TimesTen version 7. This dialect is optimized for the latest SQL features of TimesTen and it is the recommended Hibernate dialect for TimesTen 7 applications. This dialect is not included in current versions of the Hibernate distribution. It is included in the TimesTen installation as of TimesTen version 7.0.5. The java source code for the dialect is located in the install_dir /demo/appserver/config/hibernate3 directory of the TimesTen installation. For an example of how to build and package this dialect class using the Ant build tool see the install_dir /demo/appserver/build-hibernate3.xml build file in the TimesTen 7.0.5 or greater installation.
Hibernate configuration properties for TimesTen Hibernate uses properties defined in a hibernate.properties file or a hibernate.cfg.xml configuration file to determine which JDBC driver and and which SQL dialect to use for a session. When using TimesTen with Hibernate, set the following property values: hibernate.dialect=org.hibernate.dialect.TimesTen7Dialect hibernate.connection.driver_class=com.timesten.jdbc.TimesTenDriver hibernate.connection.url=jdbc:timesten:
The following property values are recommended when using TimesTen with Hibernate: hibernate.connection.isolation=2 hibernate.jdbc.use_get_generated_keys=false hibernate.jdbc.use_scrollable_resultset=false hibernate.jdbc.batch_size=256
An example hibernate.cfg.xml configuration file is shown below for a TimesTen DSN called RunData_tt70 :
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 39
Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks Page 40 Configuring Oracle TimesTen 7.0 for Application Servers and Object-Relational Mapping Frameworks April 2008
Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A.
Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com
Copyright © 2007, Oracle. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.