Using JDO in Maven and Eclipse

See also the screencast describing how to import an application into Eclipse

By leveraging the JDO/Datanucleus ORM, Isis' JDO objectstore is very powerful. However, with such power comes a little bit of complexity to the development environment: all domain objects must be enhanced through the JDO enhancer. So the enhancer must, in one way or another, be integrated into your development environment.

If working from the Maven command line, JDO enhancement is done using the maven-datanucleus-plugin.

If working in Eclipse, then JDO enhancement is done by installing DataNucleus' plugin. This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.

There are two distinct sets of problems you may encounter:

if you are running on Windows (either in Maven or Eclipse), then there's a good chance you'll hit the maximum path length limit. Fortunately, there is a workaround.
if you are developing in Eclipse and a new version of DataNucleus is released to Maven central repo, then this can cause classpath issues. Again, there is a workaround.

In other words:

	Maven	Eclipse
Unix	use workaround when new DN version	no known issues
Windows	use workaround for path limit use workaround when new DN versions	use workaround for path limits

In addition, Eclipse's enhancer needs some special care over the classpath.

For Eclipse: configuring the enhancer

for the domain object model project, first add DataNucleus support:

Then turn on Auto-Enhancement:

For Eclipse: classpath considerations

Update domain object model's classpath to reference DataNucleus JARs:

<dependencies>
    <dependency>
        <groupId>org.apache.isis.core</groupId>
        <artifactId>isis-core-applib</artifactId>
    </dependency>

    <dependency>
        <groupId>org.apache.isis.objectstore</groupId>
        <artifactId>isis-objectstore-jdo-applib</artifactId>
    </dependency>

    <!-- DataNucleus (horrid, but needed to run the enhancer)-->
    <dependency>
        <groupId>javax.jdo</groupId>
        <artifactId>jdo-api</artifactId>
    </dependency>
    <dependency>
        <groupId>org.datanucleus</groupId>
        <artifactId>datanucleus-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.datanucleus</groupId>
        <artifactId>datanucleus-enhancer</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.ow2.asm</groupId>
                <artifactId>asm</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.datanucleus</groupId>
        <artifactId>datanucleus-api-jdo</artifactId>
        </dependency>
</dependencies>

And tell DataNucleus to use the project classpath:

When the enhancer runs, it will print out to the console:

Workaround for path limits: using `persistence.xml`

Create `persistence.xml`

in src/main/java/META-INF of the domain project:

Ensure the persistence-unit is as specified in the project properties:

<?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"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">

    <persistence-unit name="quickstart">
    </persistence-unit>
</persistence>

Then specify the persistence-unit in the project properties:

Workaround for DN versions: using a profile

Every so often there will be a new release of DataNucleus plugins to the Maven central repo. For better or for worse, the Maven DataNucleus plugin defines a range dependency: it will always use the latest version of the DN modules available.

The Eclipse DataNucleus plugin on the other hand is configured to use the project classpath, and so it will remain compatible with the version referenced by Isis' own JDO objectstore.

Unfortunately, if the enhancer is run referencing two different versions of the org.datanucleus:dataducleus-core jar, then it will fail:

[INFO] Example Claims .................................... SUCCESS [0.017s]
[INFO] Example Claims App DOM ............................ FAILURE [1.532s]
[INFO] Example Claims App Repositories (for ObjectStore Default)  SKIPPED
[INFO] Example Claims App Fixtures ....................... SKIPPED
[INFO] Example Claims App Repositories (for JDO ObjectStore)  SKIPPED
...
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5:49.374s
[INFO] Finished at: Thu Dec 06 15:54:44 GMT 2012
[INFO] Final Memory: 113M/883M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.datanucleus:maven-datanucleus-plugin:3.1.1:en
hance (default) on project claims-dom: Error executing DataNucleus tool org.data
nucleus.enhancer.DataNucleusEnhancer: InvocationTargetException: Plugin (Bundle)
 "org.datanucleus" is already registered. Ensure you dont have multiple JAR vers
ions of the same plugin in the classpath. The URL "file:/C:/MVN/.m2/repository/o
rg/datanucleus/datanucleus-core/3.1.3/datanucleus-core-3.1.3.jar" is already reg
istered, and you are trying to register an identical plugin located at URL "file
:/C:/MVN/.m2/repository/org/datanucleus/datanucleus-core/3.1.2/datanucleus-core-
3.1.2.jar." -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e swit
ch.

The fix is to use a Maven profile:

    <profiles>
        <profile>
            <id>not-m2e</id>
            <activation>
                <property>
                    <name>!m2e.version</name>
                </property>
            </activation>
            <dependencies>
                <dependency>
                    <groupId>org.datanucleus</groupId>
                    <artifactId>datanucleus-core</artifactId>
                    <version>(3.0.99, 3.1.99)</version>
                    <scope>runtime</scope>
                </dependency>
                <dependency>
                    <groupId>org.datanucleus</groupId>
                    <artifactId>datanucleus-enhancer</artifactId>
                    <version>(3.0.99, 3.1.99)</version>
                    <scope>runtime</scope>
                </dependency>
            </dependencies>
        </profile>
    </profiles>

This says that when not run within Eclipse (the ${m2e.version} property is not set), then to use the latest version of the DataNucleus dependency can be referenced. You can maintain the <version> to keep track with the latest-n-greatest available in the Maven repo.

For Eclipse: If the enhancer fails

On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's Debug view:

At any rate, you'll know you've encountered this error if you see the following in the console:

The best solution is to remove DataNucleus support and then to re-add it:

Using JDO in Maven and Eclipse

For Eclipse: configuring the enhancer

For Eclipse: classpath considerations

Workaround for path limits: using persistence.xml

Create persistence.xml

Workaround for DN versions: using a profile

For Eclipse: If the enhancer fails

Thank you for contributing to the documention!

Any help with the documentation is greatly appreciated.

Workaround for path limits: using `persistence.xml`

Create `persistence.xml`