Page History

...

Once you have installed the OpenJPA Eclipse tooling, here is how to add the Bytecode Enhancement builder Builder to a Java project:

1. right-click on Project, click "Add/Remove Bytecode Enhancer"
2. in the Enable OpenJPA dialog which will be shown: (TBD: Attach screenshot here, once ugly OPENJPA-1521 is resolved?)
   1. choose if OpenJPA libraries should be added to project, this will copy the OpenJPA JARs from the Eclipse plug-in into a lib directory of the Java project, and add them as Referenced Libraries. (In a normal existing project you'll already have them via Maven or otherwise, but for test projects this is convenient.)
   2. choose enhancement options, if you need any. These are the same options as the CLI PCEnhancer supports
3. menu Project > Properties (or right-click on Project > Properties) should now show the "OpenJPA PC-Enhancer Project Builder" added after the usual "Java Builder"
4. when Eclipse builds (compiles) the project, classes will now be byte-code enhanced

...

• If the Builder has trouble during enhancement, it often normally logs useful messages / exception stack traces to the Eclipse Error Log. Use menu Window > Show View > Error Log to display it. If you don't have the Error Log view, this could be because you have an Eclipse with the PDE (Plug-in Development Environment), get that. The Eclipse Error Log can also be exported from this view, e.g. to send it to the mailing list. Further debugging & informational log messages can be enabled via the .project file, see below.

• If your Eclipse dies due to "java.lang.OutOfMemoryError: Java heap space" / "java.lang.OutOfMemoryError: PermGen space" issues, you may need to add e.g. "-XX:PermSize=64m -XX:MaxPermSize=256m -Xms128m -Xmx512m" to your eclipse.ini (each option on a separate line) for the enhancement builder

Options

• More verbose logging for the Builder can be enabled via a configuration option in .project. This option is only intended for troubleshooting & debugging, because it seems to significantly slow down the builder, and something goes wrong with the Progress view (Monitor stuff) causing it to not update correctly anymore, and appear to keep running (although it's not).

<projectDescription>
...
    <buildSpec>
...
        <buildCommand>
            <name>org.apache.openjpa.eclipse.OpenJPAEnhancerBuilder</name>
            <arguments>
                <dictionary>
                    <key>debugLogs</key>
                    <value>true</value>
                </dictionary>

The debugLogs = true will lead to message such as these to be shown in the Error Log (the order sometimes appears to get messed up) :

OpenJPA Enhancement (Full Build, collecting resources) took 0ms, found 3 classes potentially needing enhancement
OpenJPA Enhancer ran on but did not have to bytecode enhance /test-project/bin/ch.vorburger.jpa/SomeEntityTest.class
OpenJPA Enhancer ran on and actually bytecode enhanced /test-project/bin/ch.vorburger.jpa/SomeEntity.class
OpenJPA Enhancer ran on but did not have to bytecode enhance /test-again/bin/ch.vorburger.jpa/NotToEnhance.class
OpenJPA Enhancement (Full Build) took 47ms, for 3 potential classes, of which 1 were actually enhanced

• The builder has been written with efficiency in mind and profiledunderwent some profiling & optimization, e.g. it correctly does only Incremental Builds if when possible. However, for projects with a lot of classes, this Builder may slow down the project. This is because it still has to byte-code inspect (load and analyze) each .class to determine if it needs enhancement. If the JPA entities in your project follow some naming convention (e.g. all ending in *Entity, or all in a certain package), then the builder can be configured to "match" only certain classes using Ant-like patterns, by manually adding the following to the existing .project file of the Eclipse Java project:

<projectDescription>
...
    <buildSpec>
...
        <buildCommand>
            <name>org.apache.openjpa.eclipse.OpenJPAEnhancerBuilder</name>
            <arguments>
                <dictionary>
                    <key>debugLogs</key>
                    <value>false</value>
                </dictionary>
                <dictionary>
                    <key>include1</key>
                    <value>**/*Entity.class</value>
                </dictionary>
                <dictionary>
                    <key>include2</key>
                    <value>**/*EntityRef.class</value>
                </dictionary>

• More verbose logging can ..The above two options can be mixed by adding several <dictionary> inside the <arguments>.