Binding custom objects to attributes in JAXB

When generating Java sources from an XML Schema with JAXB, the type of field used to represent an attribute is determined by it's type in the schema.

For example, a snippet from jabber-client.xsd:

   <xs:element name="message">
     <xs:complextype>
        <xs:attribute name="from" type="xs:string" use="optional">
        <xs:attribute name="to" type="xs:string" use="optional">
     </xs:complextype>
   </xs:sequence>
   </xs:element>

By default, JAXB would create the object (Message in this case) with two String properties. To change this to another object (say JID) we would add a simple binding changing these to use JID and define two static methods who's job it is to convert between a String and a JID.

So the bindings would be something like:

   <bindings schemalocation="jabber-client.xsd">
     <bindings node="/xsd:schema/xsd:element[@name='message']/xsd:complexType">
       <bindings node="xsd:attribute[@name='from']">
         <property>
           <baseType>
             <javaType name="uk.org.retep.xmpp.JID"
               parseMethod="uk.org.retep.xmpp.jaxb.adaptor.XMPPDatatypeConverter.parseJID" 
               printMethod="uk.org.retep.xmpp.jaxb.adaptor.XMPPDatatypeConverter.printJID"
             />
           </baseType>
         </property>
       </bindings>
     </bindings>
   </bindings>

Now for mose usecases this is fine and works pretty well. The problem is when you have a large number of custom bindings.

What JAXB does for each binding is that it generates an anonymous Adapter class. In that adaper class are two methods which call the two methods declared in the binding - in the case of binding to a Double you would get the following:

public class Adapter1
    extends XmlAdapter<String, Double>
{

    public Double unmarshal(String value) {
        return (javax.xml.bind.DatatypeConverter.parseDouble(value));
    }

    public String marshal(Double value) {
        if (value == null) {
            return null;
        }
        return (javax.xml.bind.DatatypeConverter.printDouble(value));
    }

}

The problem here is that JAXB generates one of these for every instance, so you can end up having multiple Adapter classes present, all doing the same thing. In one instance I had a single schema contain 16 duplicates of the above code. In retepXMPP I had almost 60 spread over multiple schemas just for handling JID. This is a lot of wasted, duplicated code and if you use a large number of schemas then this is going to cause both your jar sizes and permgen use to increase for no real reason.

So it would be nice to reduce this down to a single adapter.

Fortunately there is a way when using the JAXB RI. There is an alternate javaType binding which takes the full class name of an adapter class instead - using this causes JAXB to use that single class instead of generating these duplicate classes. The main difference is replacing the parseMethod and printMethod attributes with a single adapter attribute, and qualifying the javaType with the http://java.sun.com/xml/ns/jaxb/xjc namespace.

So the bindings would be something like:

<bindings
    xmlns="http://java.sun.com/xml/ns/jaxb"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
    xmlns:retep="http://retep.org/xml/ns/retepTools"
    version="2.0">
   <bindings schemalocation="jabber-client.xsd">
     <bindings node="/xsd:schema/xsd:element[@name='message']/xsd:complexType">
       <bindings node="xsd:attribute[@name='from']">
         <property>
           <baseType>
             <xjc:javaType adapter="uk.org.retep.xmpp.jaxb.adaptor.JIDAdapter" name="uk.org.retep.xmpp.JID" />
           </baseType>
         </property>
       </bindings>
     </bindings>
   </bindings>
</bindings>

Then just create a single adapter implementation. in retepXMPP thats some 60 classes reduced to one, if you generate any javadocs based on the generated sources there's no more "Adapter" spam - large numbers of apparently duplicated classes in the javadocs etc.

Tip: Just make sure you keep an eye on that namespace - miss it out and XJC will spurt out some unusual error messages.

Using groovy to generate java sources in maven

In this article I'll briefly cover how to use Groovy to generate java sources as part of a maven build.

There are times when you need to generate Java source which is either repetitive, based on external data or both. Now there are tools out there for some tasks like this, but for most simple tasks running a groovy script is more than enough.

Now for the purposes of this article, I'm going to presume we need an enum which represents the cards in a Standard deck of cards, one entry per card.

First we need to create our groovy script. Now the best place to put this is in the src/main/script directory of your project. Here's the script for this (writing groovy is not in scope for this article) which goes into the file src/main/script/CardDeckGen.groovy:

class CardDeckGen {

    public generate( project, String packageName, String className ) {

        // Where to write the classes
        File targetDirectory = new File( project.build.directory + '/generated-sources/groovy' )

        // The directory to write the source to
        File packageDir = new File( targetDirectory, packageName.replace( '.', '/' ) )

        // Now to create our enum
        def out = []
        out<<'package '+packageName+';\n'
        out<<'public enum '+className+' {\n'

        // We have four suits
        def suit = [ 'D', 'S', 'H', 'C']

        // Each suit has A, 2-9, T, J, Q & K
        def rank = [ 'A', '2', '3', '4', '5', '6', '7', '8', '9', 'T', 'J', 'Q', 'K' ]

        // For each suit, write an entry for each card
        suit.eachWithIndex {
            s, i -> def indent = i==0 ? '    ' : ',\n    '
            rank.each {
                r -> out<< indent + s + r
                indent = ','
            }
        }

        // Mark the end of the enum list
        out<<';\n'

        // Finish the enum class
        out<<'}\n'

        // Convert the array into a string
        StringBuilder sb = new StringBuilder()
        out.each { sb.append(it) }

        // Now write the source, ensuring the directory exists first
        packageDir.mkdirs()
        new File( packageDir, className + ".java" ).write( sb.toString() );
    }

}

Next we need to get maven to run this script, so in pom.xml we first need to make sure we are using the correct version of the jdk - 1.5 or 1.6 would be enough:

<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>1.6</source>
        <target>1.6</target>
    </configuration>
</plugin>

Next groovy, here we add the gmaven-plugin which runs a small code snippet calling our class:

<plugin>
    <groupId>org.codehaus.groovy.maven</groupId>
    <artifactId>gmaven-plugin</artifactId>
    <executions>
        <execution>
            <phase>generate-resources</phase>
            <goals>
                <goal>execute</goal>
            </goals>
            <configuration>
                <scriptpath>
                    <element>${basedir}/src/main/script</element>
                </scriptpath>
                <source>
                    CardDeckGen cdg = new CardDeckGen()
                    cdg.generate( project, 'uk.org.retep.example', 'CardDeck' )
                </source>
            </configuration>
        </execution>
    </executions>
</plugin>

Now that's enough to generate our enum, however maven doesn't know about it so it wont compile. To do that we need to add it so the compiler picks it up:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>add-groovy-sources</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>add-source</goal>
            </goals>
            <configuration>
                <sources>
                    <source>${project.build.directory}/generated-sources/groovy</source>
                </sources>
            </configuration>
        </execution>
    </executions>

Now you can run maven.mvn clean install
If all goes well you'll get a maven artifact containing an enum:

package uk.org.retep.example;
public enum CardDeck {
    DA,D2,D3,D4,D5,D6,D7,D8,D9,DT,DJ,DQ,DK,
    SA,S2,S3,S4,S5,S6,S7,S8,S9,ST,SJ,SQ,SK,
    HA,H2,H3,H4,H5,H6,H7,H8,H9,HT,HJ,HQ,HK,
    CA,C2,C3,C4,C5,C6,C7,C8,C9,CT,CJ,CQ,CK;
}

This was a simple example but quite a powerful one. I've used this technique for generating more complex versions of Card's to classes based on data contained within RFC's (STRINGPREP etc).

For help on writing Groovy stripts take a look at the Groovy Getting Started Guide.

Releasing to Kenai via Maven

Ever since the website feature appeared on Kenai I've been trying to get releases to work using it to host the maven repository. Although it works, it's always had the odd issue where whilst uploading artifacts to the repository, the connection would timeout causing the release build to fail.

For small projects this isn't really a problem, but for some of mine this is an issue to either the number of artifacts present (retepXMPP currently has over a hundred) we can't have the release build to fail part way through leaving both the mercurial and maven repositories in an inconsistent state.

The retepMicroKernel project is further complicated by the fact that it has native code - so a release has to be performed in parts with the native code built on the respective platforms.

Fortunately there is a solution to this - perform the release build into a staging repository then once it's complete merge that repository with the public one. This also means we can perform a release and if something horrible goes wrong we just redo the release without the public seeing the failed release.

Fabrizio Giudici also found this solution with an additional benefit. The maven release process makes several commits into the repository, but as mercurial is a distributed scm we can use that to our advantage - if the release build fails it doesn't cause issues remotely with having to remove tags etc (which I've done before).

So here's what I did when releasing version 9.11 of retepTools this week, first I followed Fabrizio's suggestions for configuring the root pom.xml file.

Then I created a temporary directory and inside that clone the public mercurial repo then make a clone of the clone:

# The maven staging repository
mkdir -p ~/tmp/stagingrepo

# The staging mercurial repository - this is a clone of the public repository
cd ~/tmp
hg clone https://hg.kenai.com/hg/reteptools~hg reteptools-stage

# The release mercurial repository - this is the one we will run maven against
# it is a clone of the staging repository
hg clone reteptools-stage reteptools

Now we run the release process:

cd ~/tmp/reteptools
mvn --batch-mode \
       -Dstaging.hg.repo.url=~/tmp/reteptools \
       -Dstaging.mvn.repo.url=file:///Users/peter/tmp/stagingrepo \
       -DreleaseVersion=9.11 \
       -DdevelopmentVersion=9.12-SNAPSHOT \
       -Dtag=retepTools-9.11 \
       release:prepare release:perform

Maven will now perform the release, making commits into the ~/tmp/reteptools repository and pushing them to ~/tmp/reteptools-stage.

Once we are happy that the release is clean we make it public. First mercurial - we need to push the changes back to kenai:

cd ~/tmp/reteptools-stage
hg push

Next the artifacts:

# A temporary directory for maven - it will not run without this directory
mkdir -p tmpdir
mvn org.codehaus.mojo:wagon-maven-plugin:1.0-beta-2:merge-maven-repos \
  -Dwagon.source=file:///Users/peter/tmp/stagingrepo/ \
  -Dwagon.target=dav:https://kenai.com/website/reteptools/maven/releases/ \
  -Dwagon.targetId=retep.releases \
  -Djava.io.tmpdir=target

[Edited to fix a couple of errors in the maven commands]