Introduction

The Java Persistence API (JPA) was introduced as part of the EJB 3.0 specification (JSR220) to get the entire Java community behind a single, standard persistence API. JPA draws upon the best ideas from Hibernate, TopLink, Java Data Objects (JDO), and the Container Managed Persistence (EJB-CMP) 2.1 specification.

JPA is usable in both Java Standard Edition (Java SE) and Java Enterprise Edition (Java EE) environments because it represents entities as Plain Old Java Objects (POJOs) that can be managed by a JPA persistence provider, such as Apache OpenJPA. Metadata about the entity's object-relational mapping is specified using Java 5 annotations or in XML descriptors. Entities are used to persist Java objects to the database.

There are several JPA persistence providers. IBM's JPA solution is based upon the Apache OpenJPA project. With the release of these JPA persistence providers, you can now code to a standard API and do not have to decide between incompatible non-standard persistence frameworks, like Hibernate or JDO.

IBM solidDB is an in-memory database that can perform at speeds of up to 10 times faster than a conventional database. The combination of this speed with high availability and failover features makes solidDB a natural choice as the data management component for many performance critical applications.

solidDB can be deployed as a standalone in-memory database for direct use by applications. It can also be deployed as a cache to speed up conventional databases like IBM DB2®, Oracle, and SQL Server. solidDB supports the standard Java Database Connectivity (JDBC) 2.0 specification. The solidDB JDBC Driver is a type 4 driver (meaning that it is a 100% Pure Java™ implementation of the JDBC 2.0 standard) that is usable in all Java environments that support JDK 1.4.2 and above. Because solidDB supports JDBC, using JPA with solidDB is also a possibility. This means that Java programmers writing applications that require exceptional performance have the option of using JDBC, JPA, or both with solidDB.

Other articles have described how to use JDBC with solidDB, and how to use solidDB as a cache for conventional databases. (See Resources) This article shows you how to use OpenJPA with solidDB as a standalone in-memory database. First, you will define a sample application (included with this article) that you will use to demonstrate the use of OpenJPA with solidDB. The sample application is implemented as a Java EE application that runs on IBM WebSphere Application Server 7.0. (The application could also have been implemented as a Java SE application -- without the stateless session beans -- to run on the standalone OpenJPA persistence provider.) After defining the application, you will be guided through the steps of installing and configuring the basic components you need for building a performance critical application with OpenJPA and solidDB on WebSphere Application Server. Finally, you will see how Java applications, written to the JPA specification, can connect to solidDB through OpenJPA.

Back to top

The sample application

Many Java applications can benefit from the use of an in-memory database like solidDB. For example, there are e-commerce sites that consolidate information from several backend applications, financial services companies that provide real time alerts to traders, and communication carriers that monitor cell phone usage and calling plans for billing purposes.

For the purpose of this article, the sample application you will use here is a computer telephony integration (CTI) application. Consider that the CTI application handles inbound calls by routing callers to the most qualified agent to handle each type of call. The application establishes a connection to the agent’s telephone and populates the caller’s account data (account number, name, and so on) on the agent’s workstation. These interactions are among the major design elements of the sample application illustrated in Figure 1.

In this application:

1. Message Façade receives asynchronous messages from the PBX/ACD (private branch exchange/automated call distributor). It creates the Value Object from the message payload and dispatches the message to the Session Façade to fulfill the request asynchronously. Message driven beans (MDBs) implement Message Facade.
2. Session Façade provides operations to create, retrieve, update, and delete Value Objects from the database. For example, it has operations to createCaller, updateAgent, and deleteCaller. It uses the Data Access Object to store and retrieve the Value Objects from the solidDB database. Stateless Session Beans (SLSBs) implement the Session Façade.
3. Value Object holds the attribute values for the Agent and the Caller. It is implemented as a POJO with methods to get and set the attribute values. It also provides a method to create a Value Object from an XML string (valueOf) and a method to convert a Value Object to an XML string (toString). These POJOs are created by the Message Façade and passed as parameters to the Session Façade and Data Access Object.
4. Data Access Object encapsulates all access to the persistence technology (JDBC, JPA, and so on) that is used to save the Value Objects (POJOs) in the database. In this application, JPA APIs are used to persist Value Objects in solidDB.

A key to being able to intelligently route incoming callers to the best available agents is the ability to keep a copy of the caller’s state and agent’s state in the CTI application consistent with the PBX. To do that, the CTI application is notified of state changes from the PBX/ACD via JMS messages, and the CTI application uses solidDB to cache the agent’s state and the caller’s state in memory.

Back to top

Setting up the development environment

The archive file included with this article contains a Project Interchange file that contains all of the source for this sample. The instructions below outline how to import and utilize this Project Interchange file.

1. Start IBM Rational® Application Developer V7.5. You can use a licensed version of Rational Application Developer, obtain and install a trial version, or you can use the version of Rational Application Developer that is bundled with WebSphere Application Server V7.0.
2. Navigate to Project => Build Automatically and uncheck the option to build automatically.
3. From the menu bar, navigate to File => Import => Other => Project Interchange and press the Next button. The Import Projects dialog will display (Figure 2).
4. Browse to the project interchange file, select all of the projects listed and click the Finish button.
   
   Figure 2. Import projects
   
   
   
5. Set the WAS_HOME classpath variable in Rational Application Developer by selecting Window => Preferences => Java. Add a new Classpath variable named WAS_HOME containing the value of your WAS_Home directory name (Figure 3); for example, d:\IBM\SDP75\runtimes\base_v7.
   
   Figure 3. Classpath variables
   
   
   
6. Set WAS_HOME string substitution in Rational Application Developer by selecting Window => Preferences => Run/Debug => String Substitution. Add a new string substitution variable named WAS_HOME with the value again pointing to your WAS_HOME directory (Figure 4).
   
   Figure 4. String substitution
   
   
   
7. Set was.home value in the build.properties file. Expand the CTIServices project, double click on the build.properties file, and set the was.home property to your WAS_HOME directory (Figure 5).
   
   Figure 5. Build properties
   
   
   
8. You are now ready to build all of the projects in your Rational Application Developer workspace. Select Project => Clean.... and be sure to check Clean all projects and Start a build immediately. When the build is done, you should only see warnings (Figure 6). If you see any errors, fix them before proceeding.
   
   Figure 6. Build projects
   
   
   

Back to top

Setup the solidDB standalone database

1. Obtain and install the binary distribution of solidDB according to the download instructions. At the time of this writing, the current release is Version 6.3. When installed, the server files will be unzipped into a folder called, for example, d:\IBM\SolidDB.
2. Create the solidDB database. Open a command window and run this command from the directory where you installed solidDB:

   .\bin\solid -c eval_kit\standalone

   When prompted, enter values for system catalog name, username, and password; for this example, you can use "dba" for all values.
3. Create the tables using the script provided in the download file included with this article. Open a shell and run this command:

   .\bin\solsql "tcp localhost 1315" dba dba <WS>\CTIEntities\dml\createTablesSolid.ddl

   where <WS> is the Rational Application Developer workspace location; for example, d:\workspaces\usingjpawithsoliddb.
4. Populate the tables with sample data by running this command from the solidDB installation directory:

   .\bin\solsql "tcp localhost 1315" dba dba <WS>\CTIEntities/dml/createDataSolid.sql

   where <WS> is again the Rational Application Developer workspace location.

Back to top

Set up the WebSphere Application Server test environment

1. Start Rational Application Developer, if it is not already started.
2. Open the server view by selecting Window => Show View => Servers. Open the Server tab, right click in the server panel, and select New => Server. Select WebSphere Application Server V7.0 and press the Finish button. The server has been added to Rational Application Developer.
3. Make sure that the server starts without any errors. To do that, right click on the server and select Start. If there are any errors, fix them before proceeding.
4. The test program included with this article is a standalone Java application that accesses the CTI services (SLSBs) running on WebSphere Application Server. To access those SLSBs, the test program must specify the implementation specific location (port number) of the JNDI naming service. To find that address, open the admin console by selecting Administration => Run administrative console => Application servers => server1 => Ports and note the port number of the Bootstrap Address.
5. A jndi.properties file is included with the source code for the sample application. Specify the port number you found in step 4 inside the properties file so that the test program can find the JNDI naming service (Figure 7). To do that, expand CTIServices => ejbModule, open the jndi.properties file, and change "2815" to your Bootstrap Address (if in fact it is different).
   
   Figure 7. JNDI naming service
   
   
   

Back to top

Run the sample application

1. In the Server view, right click on WebSphere Application Server V7.0 and select Add and Remove Projects. This will open the Add and Remove Projects panel.
2. Select the CTIApplication from the Available projects panel, select Add to move it to the Configured projects panel, and press the Finish button.
3. Monitoring the console, you should see something like this:

   WSVR0037I: Starting EJB jar: CTIServices.jar CNTR0167I: The server is binding ... WSVR0057I: EJB jar started: CTIServices.jar WSVR0221I: Application started: CTIApplication

   
   
4. When you see Application started, you are ready to run the sample application. From the Package Explorer panel, select the StateManagerTest.java file, which contains the main routine that you want to test. To do that, expand CTIServices => ejbModule => com.ibm.issw.service.statemanager, right click on the StateManagerTest.java file, and select Run As => Run Configurations. This will open the Run Configurations panel.
5. In the Run Configurations panel, right click on JUnit and select New. In the Test tab, enter the Name, Project, and Test class, as shown in Figure 8. (These values might already be filled in for you.)
   
   Figure 8. Create JUnit test
   
   
   
6. Select the Classpath tab and make sure that the classpath is set as shown in Figure 9. You will need to add the client stubs JAR file so this standalone client can invoke the remote EJB. To do that, click on User Entries, press the Add JARs... button, and then select the CTIServices_withStubs.jar file.
   
   Figure 9. Set classpath
   
   
   
7. When you have completed this configuration, press Run. If successful, you should see three test cases have run successfully in the JUnit view (Figure 10).
   
   Figure 10. Test results
   
   
   

Back to top

Persistence parameters

Finally, let’s look at some of the details of the configuration parameters in the persistence.xml file that were required to use OpenJPA with solidDB. Recall that the persistence.xml file must be placed in the META-INF folder on the classpath. (You can find a copy of it in the download file.) This file defines the database connections, mapping locations, logging levels, and so on. These configuration parameters were required to use OpenJPA with solidDB:

• openjpa.ConnectionDriverName
• openjpa.ConnectionURL
• openjpa.ConnectionUserName
• openjpa.ConnectionPassword

In addition, the openjpa.jdbc.DBDictionary is another important parameter for establishing a database connection. This property masks the persistence provider from having to deal with vendor specific SQL differences. This parameter is optional because OpenJPA can usually determine the vendor specific dictionary to use via the URL and DriverName parameters (see listing below).

<persistence ...>
   <persistence-unit name="CTIPU">
      <properties>
         <property 
            name="openjpa.ConnectionDriverName"
            value="solid.jdbc.SolidDriver">
         </property>
         <property 
            name="openjpa.ConnectionURL"   
            value="jdbc:solid://localhost:2315/dba/dba">
         </property>
         <property 
            name="openjpa.ConnectionUserName" 
            value="dba">
         </property>
	   <property 
            name="openjpa.ConnectionPassword" 
            value="dba">
         </property> 
      </properties>
   </persistence-unit>
</persistence>

However, because solidDB is not supported via a vendor specific dictionary, OpenJPA cannot determine the vendor, so it reverted to using a generic JDBC dictionary for solidDB. Although this might result in limited functionality, we did not experience any problems in our tests of this sample CTI application.

Back to top

Conclusion

This article showed you how to install and configure the necessary components to use OpenJPA with solidDB 6.3 on WebSphere Application Server V7.0. It also showed you how to take advantage of the performance benefits of the solidDB in-memory database with the design, deployment, and running of a sample Java application on WebSphere Application Server.

In conclusion, formal support of IBM solidDB has been registered as a requirement for OpenJPA. We strongly encourage a contribution to the OpenJPA project of a real, standalone dictionary for solidDB. In the meantime, this article will help you use JPA with solidDB on WebSphere Application right now.

Back to top

Download

Information about download methods

Resources

Learn

• Using the SolidDB JDBC Driver
  
  
• Accelerate access to critical data using IBM solidDB Universal Cache
  
  
• Getting started with SolidDB Universal Cache 6.3.
  
  
• IBM Message Service Client for C++ (XMS)
  
  
• IBM Client for JMS on Java SE with WebSphere Application Server
  
  
• Leveraging OpenJPA with WebSphere Application Server V6.1
  
  
• OpenJPA DBDictionary Information
  
  
• Migrating legacy Hibernate applications to OpenJPA and EJB 3.0
  
  
• Wikipedia: Computer telephony integration
  
  
• Wikipedia: Automatic call distributor
  
  
• Wikipedia: Private branch exchange
  
  

Get products and technologies

• Download: IBM WebSphere Application Server V7.0 trial version
  
  
• Download: IBM solidDB 6.1 trial version
  
  
• Download: IBM Rational Application Developer 7.5 trial version
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• The sample application
• Setting up the development environment
• Setup the solidDB standalone database
• Set up the WebSphere Application Server test environment
• Run the sample application
• Persistence parameters
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers