Implementing build time JPA enhancement with WebSphere Application Server

This article presents a process for setting up build time JPA enhancement in IBM® Rational® development products, using only the libraries provided by IBM WebSphere® Application Server. Build time enhancement can reduce startup times and provide seemless support for transferring JPA entities between JPA applications and non-JPA clients.. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Randall Hollman (rhollman@us.ibm.com), Advisory Software Engineer, IBM

Randall Hollman is an Advisory Software Engineer with IBM Corporation. He has been developing Java web applications running on WebSphere Application Server for 14 years.



26 February 2014

Also available in Chinese

Introduction

JPA enhancement is the process of modifying entity classes to add the ability to monitor them for changes and then to persist those changes. When using OpenJPA provided with IBM WebSphere Application Server, this enhancement process uses a technique called byte-code weaving. Normally with WebSphere Application Server, the enhancement of JPA (Java™ Persistence API) entities occurs during the initialization of the Java EE application.

While the use of build time enhancement is not required, it does provide some advantages:

  • Since the enhancement does not need to be done during each server startup, it reduces the startup time of the server.
  • If JPA entities are being passed outside the Java EE application, build time enhancement ensures the serialized or externalized entity classes are compatible with those defined in the client.

While JPA generally serializes the entity when passing it to a client application, some settings in the JPA persistence.xml file, such as using the loaded(DetachedStateField=true) value of the openjpa.DetachState property, cause JPA to "externalize" the entity rather than serialize it. When using run time enhancement, these entities could only be used by clients that are also implementing run time enhancement. This means the clients must include a persistence.xml file, support the same JPA runtime, and run in an environment supporting run time enhancement. Using build time enhancement is a better solution.

The information here is based on exercises using Rational Application Developer V8 and WebSphere Application Server V8, although the steps will be similar for other Rational development products and versions, as well as other versions of WebSphere Application Server.

This article explains the steps you need to perform to configure JPA build time enhancement when using IBM Rational Application Developer and IBM WebSphere Application Server. While other tutorials are available for setting up build time JPA enhancement, most or all of them seem to download additional OpenJPA libraries to perform the function. This could lead to possible problems if the two versions of OpenJPA are not at the same level. The steps described here use only the libraries supplied with WebSphere Application Server, so you know they will always be compatible.


Configuring build time enhancement

Setting up build time enhancement can be easily achieved in three major steps, described in the sections that follow.

1. Create a reference to the WebSphere Application Server installation

The first step is to create a classpath variable that defines the installation directory of WebSphere Application Server.

  1. In Rational Application Developer navigate to Windows > Preferences from the menu bar.
  2. In the Preferences panel, select Java > Build Path > Classpath Variables.
  3. Click the New button. For the Name field, enter WAS_HOME. Use the Folder... button to browse to the WebSphere Application Server installation directory and click OK. (The WebSphere Application Server installation directory normally ends with "AppServer.") Now click OK in the New Variable Entry panel (Figure 1).
    Figure 1. New Variable Entry
    New Variable Entry

2. Create the build.xml file

The build.xml file defines the procedure and references needed to enhance the JPA entities.

  1. Right click on the src folder in the JPA project and select New > Other...
  2. Under the General folder in the New panel, select File and click Next (Figure 2).
    Figure 2. Select a wizard
    Select a wizard
  3. Enter build.xml for the File name and then click Finish (Figure 3).
    Figure 3. Create a new file resource
    Create a new file resource
  4. Insert the code shown in Listing 1 into the build.xml file to use as a starting point.
    Listing 1. build.xml
    <project  name="MyProject" default="defaultBuild">
       <!-- set global properties for this build -->
       <property  name="src" location="src"/> 
          <!-- Location of JPA entity .java files in relation to project -->
       <property  name="bin" location="src"/> 
          <!-- Location of JPA entity .class files in relation to project -->
    
       <target  name="enhance">
          <path  id="enhance.classpath">
             <pathelement  location="${was.home}/dev/JavaEE/j2ee.jar"/>
             <pathelement  location="${was.home}/plugins/com.ibm.ws.jpa.jar"/>
             <pathelement  location="${was.home}/plugins/com.ibm.ws.prereq.commons-collections.jar"/>
             <pathelement  location="${bin}"/>
                 <!-- Where the entity .class files are -->
             <pathelement  location="${src}/../../<project>/"/> 
                <!-- Use for reference to class outside this project if needed -->
          </path>
          <property  name="cp" refid="enhance.classpath"/>
          <echo  message="Classpath: ${cp}"/>
          <echo  message="Source:    ${src}"/>
          <echo  message="Bin:       ${bin}"/>
          <java  classname="org.apache.openjpa.enhance.PCEnhancer" 
                logError="true" failonerror="false" fork="true">
             <classpath  refid="enhance.classpath"/>
             <arg  value="-properties" />
             <arg  value="${src}/META-INF/persistence.xml" />
          </java>
       </target>
    
       <target  name="defaultBuild" depends="enhance"/>
    
    </project>
  5. While the above contents for the build.xml file should match most JPA projects, you may need to adjust a few items. For example:
    • The src property location value should point to the directory in the project containing the Java source files. This is usually the src folder.
    • The bin property location value should point to the directory in the project where the class files are to be stored. In this example, they are stored in the src directory along with the Java source files. If you store your class files in a separate directory, you will likely need to set the location to bin.
    • If you reference classes outside your JPA project from within your entities, you will need to include a pathelement for each project reference. In the next step, you will see a provided entry that you can just replace <project> with the project you are referencing. You might need to append an additional directory, such as bin/ depending on the location of the class files in that project. If you have no references outside the JPA project, just remove that pathelement line.
  6. Save the file.

3. Create the Ant builder

The Ant builder is the task invoked by Rational Application Developer that will utilize the information in the build.xml file to enhance the JPA entities.

  1. Select Project > Properties from the menu bar.
  2. In the Properties panel, select Builders.
  3. Click the New... button. In the Choose configuration type dialog, select Ant Builder and click OK.
  4. Update the following fields in the Main tab of the Edit Configuration panel (Figure 4). (The JPA project in the screen captures is called "TutorialJPA.")
    • Provide a Name, such as AntBuilder or any name you prefer.
    • For Buildfile, click Browse Workspace... to navigate to the build.xml file you created in step 2. Select the build.xml file and click OK.
    • For Base Directory, click Browse Workspace... to select the JPA project. Click OK.
    • In the Arguments field, enter "-Dwas.home=${WAS_HOME}" including the quotes. This connects the was.home variable used in the build.xml file with the classpath variable called WAS_HOME.
    • Do not click OK yet.
    Figure 4. Create Ant build configuration
    Create Ant build configuration
  5. Select the Targets tab and update these fields (Figure 5):
    • In the After a "Clean" section, click on Set Targets.... Uncheck the DefaultBuild [default] target and click OK on the Set Targets panel.
    • In the Manual Build section, the default target should already be selected. If not, click on Set Targets.... Check the DefaultBuild [default] target and click OK on the Set Targets panel.
    • In the Auto Build section, click on Set Targets.... Check the DefaultBuild [default] target and click OK on the Set Targets panel.
    • In the During a "Clean" section, the builder should already be set not to run.
    Figure 5. Target configuration parameters
    Target configuration parameters
  6. Click OK to save the new builder.
  7. Now click OK on the Properties panel.

Your build time enhancement setup should now be complete. You should see the messages shown in Listing 2 in the console window as the Ant Builder enhancement is automatically run.

Listing 2. Ant builder messages
Buildfile: C:\MyWorkspace\TutorialJPA\src\build.xml
Trying to override old definition of datatype description
Trying to override old definition of datatype artifact

enhance:
        [echo] Classpath: C:\Progra~2\IBM\WebSphere\AppServer\dev\JavaEE\j2ee.jar;C:
\Progra~2\IBM\WebSphere\AppServer\plugins\com.ibm.ws.jpa.jar;C:\Progra~2\IBM\WebSphere
\AppServer\plugins\com.ibm.ws.prereq.commons-collections.jar;C:\MyWorkspace\TutorialJPA.
\src;C:\MyWorkspace\ReferencedProject
        [echo] Source:    C:\MyWorkspace\TutorialJPA\src
        [echo] Bin:       C:\MyWorkspace\TutorialJPA\src
        [java] 62  testJpa  INFO   [main] openjpa.Tool - No targets were given.  Running 
on all classes in your persistent classes list, or all metadata files in classpath 
directories if you have not listed your persistent classes.  Use -help to display tool 
usage information.

defaultBuild:
BUILD SUCCESSFUL
Total time: 7 seconds

Conclusion

By completing the procedure described in this article, you can set up your JPA project to enhance the entities when you build your project. Once completed, WebSphere Application Server will no longer need to perform this action during startup. In addition, any references to the JPA entities will automatically refer to the enhancement versions for complete compatibility.

Resources

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, Rational
ArticleID=964134
ArticleTitle=Implementing build time JPA enhancement with WebSphere Application Server
publish-date=02262014