wsenhancer command

The entity enhancer tool for Java Persistence API (JPA) applications in the appserver inserts bytecode into an entity class file that allows the JPA provider to manage the state of an entity.

JPA with the appserver requires that all entity classes be enhanced to manage their state. In a container-managed environment, automated enhancement is provided by the containers. In a Java SE environment, though, there are no containers to manage persistence and we might use this command frequently before packaging application files for testing. After we have created the JPA entities, we can run the wsenhancer tool to inject bytecode into the entities before packaging the JAR file into the EAR file for the application.

 

Syntax

Before running the command,  have a copy of persistence.xml on the classpath, or specify  it as a properties file through the -p [path_to_persistence.xml] argument. Issue the  command from the bin subdirectory of the app_install_root directory.

The command syntax is as follows:
[AIX] [HP-UX] [Linux] [Solaris]

wsenhancer.sh [parameters][arguments]

(Windows)

wsenhancer.bat [parameters][arguments]

 

Parameters

The enhancer accepts the standard set of command-line arguments defined by the configuration framework along with the following:

• -directory/-d <output directory>: specifies the path to the output directory. If the directory does not match the enhanced class's package, the package structure will be created beneath the directory. By default, the enhancer overwrites the original .class file.

• -enforcePropertyRestrictions/-epr <true/t | false/f>: specifies whether to generate an exception when it appears that a property access entity is not obeying the restrictions that are placed on property access. The default is set to false.

• -addDefaultConstructor/-adc <true/t | false/f>: specifies that all of the persistent classes define a no-argument constructor. This flag informs the enhancer if it should add a protected no-arg constructor to any persistent classes in which the constructor is not already present.

• -tmpClassLoader/-tcl <true/t | false/f>: specifies whether the enhancer should load persistent classes with a temporary class loader. This function allows other code to load the enhanced version of the class afterwards within the same JVM. The default is set to true.

  If encountering class loading problems when running the enhancer, we can set this flag to false as a debugging step.

• For class name, specify one of the following:

  • The full name of a class.

  • The .java name for a class.

  • The .class file of a class.

If we do not supply any arguments to the enhancer, it will run on the classes in the persistent class list.

 

Usage

In order to use the wsenhancer tool we need entities defined to JPA specifications, and the entities need to be compiled. Run the wsenhancer tool against the entities before packaging them into a JAR file. If the entities are already packaged, extract the entity class files, run the enhancer, and recreate the JAR file. To enhance your entities:

• Verify that the entities are in the class path, if they are not, add them.

• Run the wsenhancer command. It is found in ${APP_ROOT}/bin directory.

Messages and errors are logged to the console as specified in the log settings. After invoking the wsenhancer command, the files are enhanced.

 

Examples

To enhance all entities on the classpath: [AIX] [HP-UX] [Linux] [Solaris]

$ cd build
/home/user/myproject/build $ ${APP_ROOT}/bin/wsenhancer.sh

(Windows)

C:\myproject\cd build C:\myproject\build>%APP_ROOT%\bin\wsenhancer.bat 

All entities in myproject will be enhanced.

To enhance a specific entity when we have the source files:
[AIX] [HP-UX] [Linux] [Solaris]

$ cd build
/home/user/myproject/build $ ${APP_ROOT}/bin/wsenhancer.sh Magazine.java

(Windows)

C:\myproject\cd build C:\myproject\build>%APP_ROOT%\bin\wsenhancer.bat Magazine.java

To enhance a specific entity when we have the compiled class files:
[AIX] [HP-UX] [Linux] [Solaris]

$ export CLASSPATH=target/classes
$ ${APP_ROOT}/bin/wsenhancer.sh /bin/wsenhancer.sh target/classes/jpa/example/MyEntity.class

(Windows)

C:> cd build C:\build> SET CLASSPATH=target\classes C:\build>%APP_ROOT%\bin\wsenhancer.bat \bin\wsenhancer.bat target\classes\jpa\example\Magazine.class

The entity, Magazine.java, located in myproject will be enhanced.

 

Additional information

See about enhancement tools, refer to the section on persistent classes in the Apache OpenJPA reference documentation.

---

 

Related tasks

Develop and packaging JPA applications for a Java EE environment
Develop and packaging JPA applications for a Java SE environment