Develop and packaging JPA applications for a Java SE environment

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

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, define a persistence unit and configure the appropriate properties in the persistence.xml file to verify 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 will need to specify the com.ibm.ws.jpa.thinclient_7.0.0.jar standalone Java archive  (JAR) file in the 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_ROOT}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar

 

1. Generate the entities classes. Depending upon the development model, we 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 we use this approach, we are most likely concerned with creating the architecture of the object model and then writing the entity classes. These entity classes would eventually drive the creation of the database model. For 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 the data model, which are the database schemas, and then you work upwards to the entity classes. The wsreversemapping tool would help with this approach.

   • Meet in the middle mapping: probably the most common development model. we 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 appserver 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. 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: [AIX] [HP-UX] [Linux] [Solaris]

     ${app_client_root}/bin/wsenhancer.sh [parameters][arguments]
     

     
     

     (Windows)

     ${app_client_root}\bin\wsenhancer.bat [parameters][arguments]
     

   • We 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.abc.Main  
     

3. If not using the development model for bottom-up mapping, generate or update the database tables automatically or by using the wsmapping tool.

   • By default, the object-relational mapping does not occur automatically, but we can configure the appserver 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 the persistent classes must be listed in the Java .class file, mapping file, and JAR file elements in XML format.

   • To manually update or generate the database tables, run the JPA mapping tool for the appserver from the command line to create the tables in the database. For example: [AIX] [HP-UX] [Linux] [Solaris]

     ${APP_ROOT}/bin/wsmapping.sh [parameters][arguments]
     

     
     

     (Windows)

     ${app_client_root}\bin\wsmapping.bat [parameters][arguments]
     

4. If using DB2 and want to use static 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 the persistence.xml file is located. If we have multiple persistence units, wsdb2gen command must be run for each persistence unit. To use the wsdb2gen tool, type the following at a command prompt: [AIX] [HP-UX] [Linux] [Solaris]

   ${APP_ROOT}/bin/wsdb2gen.sh [parameters]
   

   
   

   (Windows)

   ${APP_ROOT}\bin\wsdb2gen.bat [parameters]
   

5. For 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 the 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 example, type the following at a prompt: [AIX] [HP-UX] [Linux] [Solaris]

   ${app_client_root}/bin/wsappid.sh [parameters][arguments]
   

   
   

   (Windows)

   ${app_client_root}\bin\wsappid.bat [parameters][arguments]
   

6. Set the properties of the persistence unit in the persistence.xml file that will be used in the JPA application.

   1. Specify the 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 will be treated as a data source not JTA compliant.

   2. Select com.ibm.websphere.persistence.PersistenceProviderImpl as the persistence provider.

      Avoid trouble: Include the persistence provider in the classpath if we run the JPA application as a standalone application.

   3. Specify the database configuration options. If we are using pureQuery, configure the data source to use pureQuery, ensure the pdq.jar and pdqmgmt.jar files are included on the JDBC provider classpath.

      See topic "Set 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.

   Package the persistence units in separate JAR files to make them more accessible and reusable. If we 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 we 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.

   If we 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 the persistence.xml file is located.

   To package the application:

   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 the standalone application, specify the com.ibm.ws.jpa.thinclient_7.0.0.jar standalone JAR file in the class path when executing the application.

   For example, use the following Java call to run the com.abc.Main standalone application:

   java -classpath ${app_client_root}/runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar other_jar_file.jar com.abc.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>

        <exclude-unlisted-classes>true</exclude-unlisted-classes>

        <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>

 

Next steps

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

 

Related tasks

Task overview: Storing and retrieving persistent data with the Java Persistence API (JPA)
Associating persistence units and data sources
Task overview: Data Studio pureQuery
Set to use pureQuery in a Java EE environment
Set pureQuery to use multiple package collections

 

Related

wsappid
wsenhancer
wsjpaversion
wsmapping
wsreversemapping
wsschema