Apache XMLBeans with Netbeans – Quick Start

Apache XMLBeans is an excellent and simple library for managing XML through a set of custom classes that match the XML’s schema definition (from an .xsd file).  It does a similar thing to JAXB, but is IMO simpler to use and less error prone.  XMLBeans also does a better job of preserving the the formatting of XML that you read and is apparently very fast in comparison to other similar solutions.

How it Integrates with the Build

In essence, you use it like this:

Create an XML schema document that …

XMLBeans performs code generation (i.e. it creates .java files) for each of the elements of your XML schema.  When you perform this code generation is up to you, but I found it most workable to simply run it as part of the regular build process – generating the source code into the source tree of the project and then letting the regular build process compile that (there are other compile options, including having XMLBeans compile it’s own code – I like to be able to see the source, just in case; also you can just run the code generation manually whenever the schema is updated instead of after each compile).  This ensures that any schema changes are reflected in the generated code on your next compile.  Fortunately, schema generation tends to be very fast for relatively small XML schema (only a couple of seconds on a decent machine) so it shouldn’t bother you too much.

After XMLBeans does it’s code generation, you’re pretty much home free.  As long as you have the right jars in your class path you can just start hacking away.  See the XMLBeans tutorial for how to get rolling.

Configuration with Netbeans

After trying a few different configurations for this, I’ve arrived at the following as the technique that seems to work the best with Netbeans (tested with Netbeans 6.0 and 6.1):

• Download and extract the latest version of the XMLBeans binary distribution (2.3.0 as of this writing): http://xmlbeans.apache.org/sourceAndBinaries/index.html#Current+Release
• Add the following jar files to your project (pretty simple, eh? – try adding all of the dependencies for Hibernate sometime when you want a comparison)
  • xbean.jar
  • jsr173.jar
• Now you’ll need to define the Ant task, which is as simple as adding this to your build.xml (you of course need to replace out the PATH_TO_JARS with the correct path, relative to the root of your project):

<taskdef name=”xmlbean”
classname=”org.apache.xmlbeans.impl.tool.XMLBean”
classpath=”PATH_TO_JARS/xbean.jar:PATH_TO_JARS/jsr173.jar” />

• Now you create the target that will perform the code generation.  We use the Netbeans -pre-compile target which is executed as part of the Netbeans Ant build before the actual compilation occurs.  Here’s an example of how this goes (the comments describe what you need to modify for your project):

<target name=”-pre-compile”>
<antcall target=”gen-schema-source”/>
</target>
<target name=”gen-schema-source”>
<xmlbean
srconly=”true”
verbose=”true”
srcgendir=”src”
classgendir=”build/classes”>
<!– set ‘dir’ to the path where the .java files go and ‘includes’ to where
to find your XML schema –>
<fileset dir=”src/org/whatever/schema/” includes=”**/*.xsd **/*.xsdconfig”/>
</xmlbean>
</target>

• If you wish to customize which package your Java classes will be generated in, you must create an .xsdconfig file and place it along side your .xsd file.  Example:

<?xml version=”1.0″ encoding=”UTF-8″?>

<xb:config xmlns:xb=”http://xml.apache.org/xmlbeans/2004/02/xbean/config”>

<xb:namespace uri=”http://wherever.com/schemaUriGoesHere”&gt;
<xb:package>org.whatever.schema</xb:package>
</xb:namespace>

</xb:config>

• Now build your project.  You should be all good to go!

Comments are welcome!