Developing and packaging JPA applications for a Java SE environment

Prepare and package persistence applications to test outside of the application server container in a Java™ SE environment.

About this task

Java Persistence API (JPA) applications require different configuration techniques from applications that use container-managed persistence (CMP) or bean-managed persistence (BMP). They do not follow the typical deployment techniques that are associated with applications that implement CMP or BMP. In JPA applications, you must define a persistence unit and configure the appropriate properties in the persistence.xml file to ensure that the applications can run in a Java SE environment.

There are some considerations for running JPA applications in a Java SE environment:
  • Resource injection is not available. You must configure these services specifically or programmatically.
  • The life cycle of the EntityManagerFactory and EntityManager are managed by the application. Applications control the creation, manipulation, and deletion of these constructs programmatically.

For this task, you need to specify the com.ibm.ws.jpa.thinclient_7.0.0.jar standalone Java archive (JAR) file in your class path. This standalone JAR file is available from the client and server install images. The location of this file on the client install image is ${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar. The location of this file on the server install image is ${app_server_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar

Procedure

  1. Generate your entities classes. These are Plain Old Java Object (POJO) entities. Depending upon your development model, you might use some or all of the JPA tools:
    • Top-down mapping: You start from scratch with the entity definitions and the object-relational mappings, and then you derive the database schemas from that data. If you use this approach, you are most likely concerned with creating the architecture of your object model and then writing your entity classes. These entity classes would eventually drive the creation of your database model. If you are using a top-down mapping of the object model to the relational model, develop the entity classes and then use OpenJPA functionality to generate the database tables that are based on the entity classes. The wsmapping tool would help with this approach.
    • Bottom-up mapping: You start with your data model, which are the database schemas, and then you work upwards to your entity classes. The wsreversemapping tool would help with this approach.
    • Meet in the middle mapping: probably the most common development model. You have a combination of the data model and the object model partially complete. Depending on the goals and requirements, you will need to negotiate the relationships to resolve any differences. Both the wsmapping tool and the wsreversemapping tool would help with this approach.
    The JPA solution for the application server provides several tools that help with developing JPA applications. Combining these tools with IBM® Rational® Application Developer provides a solid development environment for either Java EE or Java SE applications. Rational Application Developer includes GUI tools to insert annotations, a customized persistence.xml file editor, a database explorer, and other features. Another alternative is the Eclipse Dali project. More information on Rational Application Developer or the Eclipse Dali plugin can be found at their respective web sites.
  2. Optional: Enhance the entity classes using the JPA enhancer tool, or specify the Java agent to perform dynamic enhancement at run time.
    • Use the wsenhancer tool. The enhancer post-processes the bytecode that is generated by the Java compiler and adds the fields and methods that are necessary to implement the persistence features. For example examples on how to use the wsenhancer tool, see the topic, wsenhancer command.
    • You can specify the Java agent mechanism to perform the dynamic enhancement at run time. For example, type the following at the command prompt:
      java -javaagent:${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar com.xyz.Main  
  3. Optional: If you are not using the development model for bottom-up mapping, generate or update your database tables automatically or by using the wsmapping tool.
    • By default, the object-relational mapping does not occur automatically, but you can configure the application server to provide that mapping with the openjpa.jdbc.SynchronizeMappings property. This property can accelerate development by automatically ensuring that the database tables match the object model. To enable automatic mapping, include the following line in the persistence.xml file:
      <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
      Avoid trouble: To enable automatic object-relational mapping at run time, all of your persistent classes must be listed in the Java .class file, mapping file, and Java archive (JAR) file elements in XML format.gotcha
    • To manually update or generate your database tables, run the JPA mapping tool for the application server from the command line to create the tables in the database. For examples on how to run the wsmapping tool, see the topic, wsmapping command.
  4. Optional: If you are using DB2® and want to use static Structured Query Language (SQL), run the wsdb2gen command. In order to use the wsdb2gen tool, pureQuery runtime must be installed. The wsdb2gen tool creates persistence_unit_name.pdqxml file under the same META-INF directory where your persistence.xml file is located. If you have multiple persistence units, the wsdb2gen command must be run for each persistence unit.
    Avoid trouble: Applications that implement the JPA and are configured to run static SQL can experience various exceptions. These exceptions might occur with the wsdb2gen command, which you can use to prepare the application, or when the application is running and calls a JPA method. To resolve this problem, complete the following:
    1. Install the program temporary fixes (PTF) for the iSeries® JDBC Driver V5R4. Install PTF numbers SI32561 and SI32562. You can find the PTFs through the IBM System i® Support: PTF Cover Letters Web site.
    2. If you use DB2 Universal Database™ for iSeries V6R1 or V5R3, visit the fix web site for the appropriate release.
    3. Install the required level of PureQuery, which is Version 1.3.100 or later. For more information, see the IBM Data Studio pureQuery Runtime Web site. Install the latest JCC drivers, which is Version 3.52.95 or later, with the fix for APAR PK65069. The latest JCC drivers are part of the IBM DB2 software package.
    4. For DB2 on a z/OS® server, install PTF UK39204 for the V8 alternate driver or PTF UK39205 for V9, and install the fix for APAR PK67706.
    gotcha

    For examples on how to run this command, see the topic, wsdb2gen command.

  5. Optional: If you are using application-managed identity, generate an application-managed identity class with the wsappid tool. When you use an application-managed identity, one or more of the fields must be an identity field. Use an identity class if your entity has multiple identity fields and at least one of the fields is related to another entity. The application-managed identity tool generates Java code that uses the identity class for any persistent type that implements application-managed identity.

    For examples on how to use the wsappid tool, see the topic wsappid command.

  6. Configure the properties of the persistence unit in the persistence.xml file that will be used in the JPA application.
    1. Specify your data source. Use the openjpa.Connection property to obtain a connection to the database. When you run a JPA application in a Java SE environment, a JTA data source is treated as a data source that is not JTA compliant.
    2. Select com.ibm.websphere.persistence.PersistenceProviderImpl as the persistence provider.
      Avoid trouble: Include the persistence provider in the classpath if you run the JPA application as a standalone application.gotcha
    3. Specify your database configuration options. If you are using pureQuery, configure your data source to use pureQuery, ensure the pdq.jar and pdqmgmt.jar files are included on the JDBC provider classpath. For more information, see topic Configuring a data source to use pureQuery. Indicate the database type and method of connection in the persistence.xml file.
      <property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver" />
      <property name="openjpa.ConnectionURL" value="jdbc:derby:target/database/jpa-test-database;create=true"/>
    4. Specify the transaction type to RESOURCE_LOCAL. For example, the following entry should be in the persistence.xml file:
      <persistence-unit name="persistence_unit" transaction-type="RESOURCE_LOCAL">
    5. Include the location of the object relationship mapping file, orm.xml, and any additional mapping files. For example, the following entry should be in the persistence.xml file:
      <mapping-file>META-INF/JPAorm.xml</mapping-file>
    6. Add any vendor specific properties to the persistence unit.
  7. Package the application.
    Note: Package the persistence units in separate JAR files to make them more accessible and reusable. If you package the persistence units this way, they can be tested outside the container both with and without the occurrence of database persistence. The persistence units can be included in standalone applications or they can be packaged into EAR files as persistence archive files. If you package the persistence unit into a persistence archive file, all of the application components must be able to access the persistence archive. The application that uses the persistence units must declare a dependency on the persistence archive using the MANIFEST.MF Class-Path: declaration.
    Note: If you are using pureQuery, add the persistence_unit_name.pdqxml files created previous or the or persistence_unit_name.pdqxml files created in the above Step 4 to the JPA application JAR file. The files are located in same META-INF directory where your persistence.xml file is located.
    To package the application use the following command:
    jar -cvf ${jar_Name} ${entity_Path}
    where ${jar_Name} represents the name of the JAR file to create, and ${entityPath} represents the root location where the entities reside, which is where you compiled them.
  8. When you run your standalone application, specify the JAR files in your classpath when executing your application. The JAR files include, the com.ibm.ws.jpa.thinclient_7.0.0.jar standalone JAR file in your class path when executing your application. The JAR file to execute is the stand-alone JAR file, com.ibm.ws.jpa.thinclient_7.0.0.jar. For example, use the following Java call to run the com.xyz.Main standalone application:
    java -classpath ${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar other_jar_file.jar com.xyz.Main  

Example

The following is a sample persistence.xml file for the Java SE Environment:
<?xml version="1.0" encoding="UTF-8"?> 
<persistence xmlns="http://java.sun.com/xml/ns/persistence" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" 
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
                 http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
 	  
    <persistence-unit name="TheWildZooPU" transaction-type="RESOURCE_LOCAL">
    
        <!-- additional Mapping file, in addition to orm.xml>
        <mapping-file>META-INF/JPAorm.xml</mapping-file>

        <class>com.company.bean.jpa.PersistebleObjectImpl</class>
        <class>com.company.bean.jpa.Animal</class>
        <class>com.company.bean.jpa.Dog</class>
        <class>com.company.bean.jpa.Cat</class>

       

        <properties>
            <property name="openjpa.ConnectionDriverName" 
                      value="org.apache.derby.jdbc.EmbeddedDriver" />
            <property name="openjpa.ConnectionURL"
                      value="jdbc:derby:target/database/jpa-test-database;create=true" />
            <property name="openjpa.Log"
                      value="DefaultLevel=INFO,SQL=TRACE,File=./dist/jpaEnhancerLog.log,Runtime=INFO,Tool=INFO" />
            <property name="openjpa.ConnectionFactoryProperties" 
                      value="PrettyPrint=true, PrettyPrintLineLength=72" />
            <property name="openjpa.jdbc.SynchronizeMappings" 
                      value="buildSchema(ForeignKeys=true)" />
            <property name="openjpa.ConnectionUserName" 
                      value="user" />
            <property name="openjpa.ConnectionPassword" 
                      value="password"/>
        </properties>

     </persistence-unit>
     
</persistence>

What to do next

For more information on any of the commands, classes or other OpenJPA information discussed here, refer to the Apache OpenJPA User's Guide.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Oct 20, 2010 11:50:58 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-base-iseries&topic=tejb_jpadevse
File name: tejb_jpadevse.html