IMPORTANT PRE-REQUISITES
1. Set up environment to compile and run the sample application
The following script must be run for each of the terminal session:
Windows: > quickstart/ttquickstartenv.bat Unix/Linux: $ . quickstart/ttquickstartenv.sh OR
$ source quickstart/ttquickstartenv.csh2. Set up sample database, user accounts and the TPTBM table
The following command should be run once to set up the sample database, user accounts and the TPTBM table.
Windows or Unix/Linux: > cd quickstart/sample_code/j2ee_orm
> ttIsql -connStr "DSN=sampledb_1122" -f tptbm.sql3. If necessary, install the Apache Ant build tool.
For each application server, an Ant build script is provided to configure, build and execute the application based on the properties of the applicaton server installation. The Apache Ant build tool has to be installed if not present.
After installation, make sure the Operating System environment variable PATH includes the path to the 'ant' executable.
The Ant build scripts have been tested with Apache Ant version 1.9.2.
CONFIGURE AND RUN
1. install WebSphere Application Server and configure build.properties
Install WebSphere Application Server 8.5 and then set the following properties in file quickstart/sample_code/j2ee_orm/build.properties:
websphere.home.dir -- set this to the home (WAS_HOME) installation directory of the local WebSphere server installation websphere.profile.dir -- set this to the profile directory for the WebSphere server that will deploy the Tptbm EJB websphere.cell -- set this to the the name of the WebSphere cell that will run the Tptbm EJB websphere.host -- the name of the host machine running the WebSphere application server websphere.port -- the RMI port number used by clients to communicate with the server, the default port number is 2809Each Ant build script reads values from file quickstart/sample_code/j2ee_orm/build.properties. This file specifies the locations of build dependencies including the location of the application server installation. This file also specifies the common benchmark execution parameters.2. TimesTen Data Source
Before the application can be deployed or executed, a TimesTen data source with the JNDI name of jdbc/TbtbmDS must be configured on the server. This can be done from a web browser by configuring a JDBC Provider resource for TimesTen within the WebSphere Administrative Console. Follow these steps to configure the TimesTen data source:
- Login to the WebSphere Administrative Console from a web browser. The default URL for this is 'http://localhost:9060/ibm/console'.
- Select Resources->JDBC->JDBC Providers from the left hand panel.
- Select a scope from the drop down list box.
- Click the New button to create a new JDBC Provider. In the 'Database type' list box select 'User-defined'.
In the 'Implementation class name' field specify 'com.timesten.jdbc.ObservableConnectionDS'.
In the 'Name' field type 'TimesTen JDBC Provider'.
Click the Next button.
- In the 'Class path' field specify the complete path to the TimesTen JDBC driver jar file, for example: 'C:\TimesTen\tt1122_64\lib\ttjdbc6.jar'.
Click the Next button and then click the Finish button at the summary screen.
- Click the name of the TimesTen JDBC provider that was just created. In the 'Native library path' field specify the directory where the TimesTen shared libraries are located, for example: 'C:\TimesTen\tt1122_64\bin'.
Click the Apply button.
Click the Save link to save the configuration.
- Select Resources->JDBC->Data sources from the left hand panel.
- Select a scope from the drop down list box.
- Click the New button to create a new data source.
In the 'Data source name' field type 'TptbmDS'.
In the 'JNDI name' field type 'jdbc/TptbmDS'.
Click Next.
Click the 'Select an existing JDBC provider' check box and then select the name of the TimesTen JDBC provider.
Click Next. Make sure that the 'Use this Data Source in container managed persistence' check box is checked. In the 'Data store helper class name' field 'com.ibm.websphere.rsadapter.GenericDataStoreHelper' should be specified.
Click the Next button.
Click the next button again on the 'Setup security aliases' step.
Click the Finish button at the summary screen.
- Click on the 'TptbmDS' data source link.
Click on the 'Custom properties' link.
Click on the 'url' property link. In the 'Value' field type 'jdbc:timesten:direct:sampledb_1122'. Click the OK button.
Click on the 'user' property link. In the 'Value' field type 'SCOTT'. Click the OK button.
Click on the 'password' property link. In the 'Value' field type 'tiger'. Click the OK button.
Click on the 'webSphereDefaultIsolationLevel' property link. In the 'Value' field type '2' for READ_COMMITTED. Click the Apply button.
- At the top of the page click on the link called 'Save' to save the server's configuration for this data source.
At this point the jdbc/TptbmDS data source has been configured.
3. build the sample application
After the server has been configured to use the jdbc/TbtbmDS data source and restarted, the application can be built, through Ant script build-websphere8.xml, with this sequence of Ant tasks under directory quickstart/sample_code/j2ee_orm:
ant -f build-websphere8.xml clean ant -f build-websphere8.xml packageThese steps will result in a deployable archive file located in the dist directory called tptbmas-ejb3.jar.
Note: To avoid Java class version conflicts build the TptbmAS packages using the same JVM used by the application server. This can be done by setting the JAVA_HOME environment variable to the location of the JDK used by the application server in the shell where the application ant scripts are executed.
4. deploy the sample application
To deploy the archive to the server login to the WebSphere Administrative Console and follow these steps:
- Select Applications->New Application from the left hand panel.
- Click on the 'New Enterprise Application' link.
- Click the 'Local file system' option and then click the Choose File button. Navigate to the dist directory where the tptbmas-ejb3.jar file was created in step 3 above. Select the JAR file and click Open. Click Next.
- At the 'Preparing for the application installation' step select the 'Fast Path' option. Click on the 'Choose to generate default bindings...' label and then check the 'Generate Default Bindings' option. Click Next.
- At the 'Select installation options' step click Next.
- At the 'Map modules to servers' step click Next.
- At the 'Metadata for modules' step click Next.
- In the 'Summary' step click the Finish button to install the Tptbm EJB. When the installation process completes click the 'Save' link at the bottom of the page to save the configuration.
- Select Applications->Application Types->WebSphere enterprise applications from the left hand panel.
- Click on the check box next to the 'tptbmas-ejb3_jar' application. Click the Start button.
5. run the sample application
To run the client execute this command:
ant -f build-websphere8.xml run
Note that this application has been tested with WebSphere Application Server 8.5.
TROUBLESHOOTING
Various problems may occur when using TimesTen with WebSphere. The list below describes possible solutions for common problems.
- 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
- 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 database. These troubleshooting steps are recommended:
- 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.
- 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.
- Try decreasing the size of the TimesTen data store by recreating the data store with lower values for the PermSize and TempSize connection attributes.
- Terminate any unnecessary processes on the system to make more memory available.
- Try a client/server TimesTen JDBC connection instead of a direct connection for the WebSphere data source.
- If possible try a 64-bit version of TimesTen and WebSphere.
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.
For more information on Java programming with Oracle TimesTen, refer to the Oracle TimesTen In-Memory Database Java Developer's Guide.