Running JPA tests, part 2

(This is part 2.  Have a look at part 1 before you continue, or this won’t make much sense.)

Now it turns out that all of the JPA providers except Hibernate (this is going to sound familiar after a while) really really really really want you to enhance or instrument or weave your entity classes.

First we’ll cover what this is, and then mention the different ways you might go about it.  Then I’ll pick one particular way and show you how to do it.

JPA entities need to be enhanced to enable things like lazy loading and other JPA-provider-specific tests.  The JPA provider might, for example, need to know when a particular property of your entity has changed.  Unless the specification were to have mandated things like PropertyChangeListeners on all properties (which, thankfully, it didn’t), there isn’t any way for the provider to jump in and be notified when a given property changes.

Enter weaving or enhancement (I’ll call it weaving, following EclipseLink’s term).  Weaving is the process where–either at build time or runtime–the JPA provider gets into your classes, roots around, and transforms them using a bytecode processor like Javassist or CGLIB.  Effectively, the JPA provider rewrites some of your code in bytecode so that the end result is a class that can now magically inform the JPA provider when certain things happen to its properties.

Weaving can be done at build time, as I said, or at runtime.

Now, if you’re like most Java EE developers, the reason you’ve never had to deal with weaving is that the Java EE specification requires all JPA providers in a Java EE container to do weaving silently in the background during deployment (if it hasn’t been done already).  So in a JPA 2.0 container like Glassfish or the innards of JBoss, weaving happens automatically when your persistence unit is discovered and deployed.

But the specification does not mandate that such automatic weaving take place when you’re not in a Java EE container.  And if you’re a good unit testing citizen, you want to make sure that your unit test has absolutely no extra layers or dependencies in it other than what it absolutely requires.

So in unit test land, you have to set this up (unless you want to drag in the testing machinery yourself, which is, of course, a viable option, but here we’re focusing on keeping the number of layers to a minimum).

When you go to set up weaving, you have to choose whether you want to do it at build time or at runtime.  I’ve chosen in all three cases to focus on build time weaving.  This has some happy side effects: if you do build-time weaving correctly, then not only do you get faster, more accurate unit tests, but if you perform that weaving in the right place then you can have Maven also deploy JPA-provider-specific versions of your entity classes for you automatically.  That, in turn, means you can install those jar files in your Java EE container and skip the dynamic weaving that it would otherwise have to perform, thus shortening startup time.

Now, all three JPA providers approach build time weaving in a different way (of course).  All three providers provide Ant tasks, but EclipseLink and OpenJPA also provide command line tools.  So we’ll make use of them where we can to avoid the Ant overhead wherever possible.

Regardless of which provider we’re talking about, weaving at build time involves the same necessary inputs:

  • A persistence.xml file somewhere.  This usually lists the classes to be weaved, as well as provider specific properties.  It isn’t (for this purpose) used to connect to any database.
  • The raw classes to be weaved.

Now, wait a minute.  If weaving alters the bytecode of your classes, then what happens if you try to use a Hibernate-weaved class in an EclipseLink persistence unit?

Things blow up, that’s what.

This is where things get regrettably quite complicated.

Before we start weaving, we’re going to need to set up areas for each persistence provider where the weaving may take place.  To set these up, we’re going to step in after compilation and copy the output of plain compilation to each provider’s area.

In Maven speak, anytime you hear the word “copy” you should be thinking about the maven-resources-plugin.  We’re going to have to add that to our pom.xml and configure it to take the classes that result from compiling and copy them to an area for EclipseLink, an area for Hibernate and an area for OpenJPA.

Here is the XML involved for the EclipseLink copy.  This goes in the <plugins> stanza as per usual:

<plugins>
  <plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
      <execution>
        <id>Copy contents of build.outputDirectory to EclipseLink area</id>
        <goals>
          <goal>copy-resources</goal>
        </goals>
        <phase>process-classes</phase>
        <configuration>
          <resources>
            <resource>
              <filtering>false</filtering>
              <directory>${project.build.outputDirectory}</directory>
            </resource>
          </resources>
          <outputDirectory>${project.build.directory}/eclipselink/classes</outputDirectory>
          <overwrite>true</overwrite>
        </configuration>
      </execution>
      <!– and so on –>
    </executions>
  </plugin>
</plugins>

So during the process-classes phase–which happens after compilation has taken place–we copy everything in ${project.build.outputDirectory}, without filtering, to ${project.build.directory}/eclipselink/classes.  Most commonly, this means copying the directory tree target/classes to the directory tree target/eclipselink/classes.  This area will hold EclipseLink-woven classes that we can later–if we choose–pack up into its own jar file and distribute (with an appropriate classifier).

We’ll repeat this later for the other providers, but for now let’s just stick with EclipseLink.

Before we get to the actual weaving, however, there’s (already) a problem.  Most of the time in any reasonably large project your JPA entities are split up across .jar files.  So it’s all fine and good to talk about weaving entities in a given project, but what about other entities that might get pulled in?  What happens when weaving only happens on some classes and not others?  Unpredictable things, that’s what, so we have to make sure that at unit test time all our entities that are involved in the test–whether they come from the current project or are referred to in other .jar files–somehow get weaved.  This gets tricky when you’re talking about .jar files–how do you weave something in a .jar file without affecting the .jar file?

The answer is you don’t.  You have Maven unpack all your (relevant) dependencies for you, then move the component classes into an area where they, too, can be weaved, just like the entity classes from the current project.  Let’s look at how we’ll set those pom.xml fragments up.  You want to be careful here that these dependencies are only woven for the purposes of unit testing.

The first thing is to make use of the maven-dependency-plugin, which, conveniently enough, features the unpack-dependencies goal.  We’ll configure this to unpack dependencies into ${project.build.directory}/dependency (its default output location):

<plugins>
  <plugin>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>2.2</version>
    <executions>
      <execution>
        <id>Unpack all dependencies so that weaving, instrumentation and enhancement may run on them prior to testing</id>
        <phase>generate-test-resources</phase>
        <goals>
          <goal>unpack-dependencies</goal>
        </goals>
        <configuration>
          <includeGroupIds>com.someotherpackage,${project.groupId}</includeGroupIds>
          <includes>**/*.class</includes>             
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>

Here you can see we specify which “group ids” get pulled in–this is just a means of filtering the dependency list.  You can of course alter this any way you see fit.  You’re trying to pull in any JPA entities that are going to be involved in your tests and make sure they get woven, so choose your group ids accordingly, and see the unpack-dependencies documentation for more tweaking you can do here.

So if you were to run mvn clean generate-test-resources at this point, the following things would happen:

  • Your regular classes would get compiled into target/classes.
  • Your regular resources would get copied into target/classes.
  • The entire contents of that directory would then get copied into target/eclipselink/classes.
  • Classes from certain of your dependencies would get extracted into target/dependency, ready for further copying.

Now we’ll copy the unpacked dependency classes into the test weaving area.  This little configuration stanza goes in our prior plugin declaration for the maven-resources-plugin:

<executions>
  <!– other executions –>
  <execution>
    <id>Copy dependencies into EclipseLink test area</id>
    <goals>
      <goal>copy-resources</goal>
    </goals>
    <phase>process-test-resources</phase>
    <configuration>
      <resources>
        <resource>
          <filtering>false</filtering>
          <directory>${project.build.directory}/dependency</directory>
        </resource>
      </resources>
      <outputDirectory>${project.build.directory}/eclipselink/test-classes</outputDirectory>
      <overwrite>true</overwrite>
    </configuration>
  </execution>
</executions>

This is so that the dependencies can be woven with everything else–remember that you’ve got to make sure that all the entities in your unit tests (whether they’re yours or come from another jar involved in the unit test)–are woven.

We have two more bits of copying to do to get our classes all in the right place.  Fortunately they can be combined into the same plugin execution.

The first bit is that we have to take the classes that will have been woven in target/eclipselink/classes and copy them unmolested into the test area so that they can reside there with all the unpacked dependency classes.  This is to preserve classpath semantics.  That is, we’ve already laid down the dependencies inside target/eclipselink/test-classes, so now we need to overlay them with our woven entity classes (obviously once they’ve already been woven) to make sure that in the event of any naming collisions the same semantics apply as would apply with a normal classpath in a normal environment.  At the end of this we’ll have a target/eclipselink/classes directory full of our entity classes that are waiting to be woven, and a target/eclipselink/test-classes directory that will ultimately contain our woven classes as well as those from our dependencies.

The second bit is that since sometimes unit tests define their own entities, we have to make sure that the regular old target/test-classes directory gets copied into the EclipseLink test weaving area as well, and, moreover, we have to make sure this happens last so that any test entities “shadow” any “real” entities with the same name.

As I mentioned, we can accomplish both of these goals with one more execution in maven-resources-plugin:

<execution>
  <id>Copy contents of testOutputDirectory and contents of EclipseLink area to EclipseLink test area</id>
  <phase>process-test-classes</phase>
  <goals>
    <goal>copy-resources</goal>
  </goals
>

  <configuration>
    <resources>
      <resource>
        <filtering>false</filtering>
        <directory>${project.build.directory}/eclipselink/classes</directory>
      </resource>
      <resource>
        <filtering>false</filtering>
        <directory>${project.build.testOutputDirectory}</directory>
      </resource>
    </resources>
    <outputDirectory>${project.build.directory}/eclipselink/test-classes</outputDirectory>
    <overwrite>true</overwrite>
  </configuration>
</execution>

Finally, you’ll recall that I said that there are two inputs needed for weaving:

  1. A persistence.xml file somewhere
  2. The raw classes to be woven

We’ve abused the maven-dependency-plugin and the maven-resources-plugin to get (2).  Now let’s look at (1).

The persistence.xml file that is needed by the EclipseLink weaver is really just used for its <class> elements and its <property> elements.  Pretty much everything else is ignored.  This makes a certain amount of sense: EclipseLink will use it as the definitive source for what classes need to be woven if you don’t tell it anything else, and a particular property (eclipselink.weaving) will instruct EclipseLink that indeed, weaving is to be done and is to be done at build time.

So we’ll put one of these together, and store it in src/eclipselink/resources/META-INF/persistence.xml:

<?xml version=”1.0″ encoding=”UTF-8″?>
<persistence version=”2.0″ 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_2_0.xsd“>
  <persistence-unit name=”instrumentation” transaction-type=”RESOURCE_LOCAL”>
    <class>com.foobar.SomeClass1</class>
    <class>com.foobar.SomeClass2</class>
    <class>com.foobar.SomeClassFromSomeDependency</class>
    <properties>
      <property name=”eclipselink.weaving” value=”static” />
    </properties>
  </persistence-unit>
</persistence>

…and, back in our monstrous maven-resources-plugin stanza, we’ll arrange to have it copied:

<execution>
  <id>Copy EclipseLink persistence.xml used to set up static weaving</id>
  <goals>
    <goal>copy-resources</goal>
  </goals>
  <phase>process-classes</phase>
  <configuration>
    <outputDirectory>${project.build.directory}/eclipselink/META-INF</outputDirectory>
    <overwrite>true</overwrite>
    <resources>
      <resource>
        <filtering>true</filtering>
        <directory>src/eclipselink/resources/META-INF</directory>
      </resource>
    </resources>
  </configuration>
</execution>

It’s finally time to configure the weaving.  For EclipseLink, we’ll use the exec-maven-plugin, and we’ll go ahead and run the StaticWeave class in the same Maven process.  We will run it so that it operates in-place on all the classes in the EclipseLink test area.

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <configuration>
    <includePluginDependencies>true</includePluginDependencies>
    <includeProjectDependencies>true</includeProjectDependencies>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.eclipse.persistence</groupId>
      <artifactId>org.eclipse.persistence.jpa</artifactId>
      <version>2.2.0</version>
    </dependency>
  </dependencies>
  <executions>
    <execution>
      <id>Statically weave this project’s entities for EclipseLink</id>
      <phase>process-classes</phase>
      <goals>
        <goal>java</goal>
      </goals>
      <configuration>
        <arguments>
          <argument>-persistenceinfo</argument>
          <argument>${project.build.directory}/eclipselink</argument>
          <argument>${project.build.directory}/eclipselink/classes</argument>
          <argument>${project.build.directory}/eclipselink/classes</argument>
        </arguments>
        <classpathScope>compile</classpathScope>
        <mainClass>org.eclipse.persistence.tools.weaving.jpa.StaticWeave</mainClass>
      </configuration>
    </execution>
    <!– there will be other executions –>
  </executions>
</plugin>


This stanza simply runs the StaticWeave class, supplies it with (effectively) -persistenceinfo target/eclipselink as its first effective argument, and then tells it to work in place on the target/eclipselink/classes directory.

In part 3, we’ll put all of this together.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s