Using OpenJPA with IBM solidDB V6.3 on WebSphere Application Server V7

The Java™ Persistence API (JPA) is part of the Enterprise JavaBean™ (EJB) 3.0 specification. JPA can be used by both Java Standard Edition (Java SE) and Java Enterprise Edition (Java EE) applications. IBM® solidDB® is an in-memory relational database with speeds up to 10 times faster than conventional databases. solidDB supports the Java Database Connectivity (JDBC) 2.0 specification. Many Java SE and Java EE applications can leverage the performance benefits of an in-memory database using JDBC. This article shows how you can leverage those benefits using OpenJPA with solidDB V6.3 on IBM WebSphere® Application Server V7.0. This content is part of the IBM WebSphere Developer Technical Journal.

Donald Vines (dhvines@us.ibm.com), Executive IT Architect, IBM

Donald Vines is currently an Executive IT Architect at IBM responsible for the WebSphere migration practice within North America.


developerWorks Contributing author
        level

Kevin Sutter, Senior Software Engineer, IBM

Kevin Sutter is a Senior Software Engineer in the WebSphere Application Server development group. He is currently the lead architect for the Java Persistence API solution for WebSphere Application Server. Kevin is also a committer and a member of the PMC for the Apache OpenJPA project. Kevin's past roles include leading and architecting the WebSphere solutions for J2EE Connector Architecture (JCA) and WebSphere eXtremeScale (caching framework).



24 June 2009

Also available in Chinese

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.


The sample application

Although the sample application utilizes concepts from the Computer Telephony Integration (CTI) and Automated Call Distribution (ACD) technologies, a complete understanding of these technologies is not needed to appreciate the OpenJPA and solidDB integration demonstrated by this example. The basic principles introduced by this sample are broadly applicable to any Web application. Additional information on CTI and ACD can be found in Resources.

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.

Figure 1. CTI design model
Figure 1. CTI design model

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.


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
    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
    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
    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
    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
    Figure 6. Build projects

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.

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
    Figure 7. JNDI naming service

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
    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
    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
    Figure 10. Test results

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.


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.


Download

DescriptionNameSize
Code sampleusingjpawithsoliddb.zip3.5 MB

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Information Management
ArticleID=398764
ArticleTitle=Using OpenJPA with IBM solidDB V6.3 on WebSphere Application Server V7
publish-date=06242009