Implementing build-time JPA enhancement with WebSphere Application Server


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 that is called byte-code weaving. Normally with WebSphere Application Server, the enhancement of Java™ Persistence API (JPA) entities occurs during the initialization of the Java EE application.

Although using build-time enhancement is not required, it does provide some advantages:

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

Although 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 runtime enhancement, only clients that are also implementing runtime enhancement can use these entities. That is, clients must include a persistence.xml file, support the same JPA runtime, and run in an environment that supports runtime enhancement. Using build-time enhancement is a better solution.

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. Although 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, which can lead to problems if the two OpenJPA versions are not at the same level. The steps described here use only the libraries that are supplied with WebSphere Application Server, so you know they will always be compatible.

Configuring build-time enhancement

You can set up build-time enhancement easily in three major steps, as described in the following sections.


Create a reference to the WebSphere Application Server installation

To begin, you create a classpath variable that defines the installation directory of WebSphere Application Server:

Editor's note: The options in steps 2 and 3 and the New String Substitution Variable panel in this section were updated on 15 September 2016.

  1. In Rational Application Developer, select Windows > Preferences from the menu bar.
  2. In the Preferences panel, select Run/Debug > String Substitution.
  3. Click the New button. For the Name field, enter WAS_HOME. Click the Browse button to locate 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 String Substitution Variable panel. New Variable Entry
    New Variable Entry

Create the build.xml file

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

  1. Right-click 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. Select a wizard
    Select a wizard
  3. Enter build.xml for the File name, and then click Finish. Create a new file resource
    Create a new file resource
  4. Insert the code shown in the following listing into the build.xml file to use as a starting point.
    <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/"/>
             <pathelement  location="${was.home}/plugins/"/>
             <pathelement  location="${bin}"/>
                 <!-- Where the entity .class files are -->
             <pathelement  location="${src}/../../<project>/"/> 
                <!-- Use for reference to class outside this project if needed -->
          <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" />
       <target  name="defaultBuild" depends="enhance"/>
  5. The contents for the build.xml file should match most JPA projects, but you might need to adjust a few items:
    • The src property location value should point to the directory in the project that contains the Java source files, which 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 are likely to 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, remove that pathelement line.
  6. Save the file.

Create the Ant builder

The Ant builder is the task that is invoked by Rational Application Developer that will use 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 on the Main tab of the Edit Configuration panel (following figure). (The JPA project in the screen captures is called "TutorialJPA.")
    1. Provide a Name, such as AntBuilder or any name you prefer.
    2. 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.
    3. For Base Directory, click Browse Workspace to select the JPA project. Click OK.
    4. 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.
    5. Do not click OK yet.
    Create Ant build configuration
    Create Ant build configuration
  5. Select the Targets tab and update these fields:
    1. In the After a "Clean" section, click Set Targets. Clear the DefaultBuild [default] target, and click OK on the Set Targets panel.
    2. In the Manual Build section, the default target is already selected. If not, click Set Targets. Check the DefaultBuild [default] target, and click OK on the Set Targets panel.
    3. In the Auto Build section, click Set Targets. Check the DefaultBuild [default] target and click OK on the Set Targets panel.
    4. In the During a "Clean" section, the builder is already set not to run.
    Target configuration parameters
    Target configuration parameters
  6. Click OK to save the new builder.
  7. Click OK on the Properties panel.

Your build-time enhancement setup is now complete. You see the following messages in the console window when the Ant Builder enhancement is automatically run.

Buildfile: C:\MyWorkspace\TutorialJPA\src\build.xml
Trying to override old definition of datatype description
Trying to override old definition of datatype artifact

        [echo] Classpath: C:\Progra~2\IBM\WebSphere\AppServer\dev\JavaEE\j2ee.jar;C:
        [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.

Total time: 7 seconds


By completing the procedure described in this article, you can set up your JPA project to enhance the entities when you build your project. Then, 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.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Middleware, WebSphere, Rational
ArticleTitle=Implementing build-time JPA enhancement with WebSphere Application Server