JiBX is one of the fastest XML object mapping frameworks out there (check out this performance test). Furthermore, it is very flexible in binding XML structures to objects. In this blog post I will describe, how a basic JiBX project can be set up with Maven2. The focus of this entry is on getting in touch with JiBX (and a little bit with Maven).
To use JiBX in our project, we just have to add the dependency to our pom.xml. JiBX is fast, but to get it’s high performance, it uses byte code enhancement. For this reason, the byte code need’s to be edited by JiBX after the compilation phase. This is done with a Maven JiBX plugin, which is executed in the build phase “process-classes”.

Besides, I also wanted a JAR file, which contains all dependencies and has a defined main class (to which I will come to later). The creation of the JAR file is done with the Maven Assembly.

Check out the pom.xml for this test run.

After setting up the pom.xml, we can begin to develop a mapping example with Eclipse. JiBX has two main parts on which we have to focus, binding and the runtime part.
In the binding part, JiBX enhances the byte code (based on a binding definition) to enable the mapping between Java objects and a XML files. In the runtim part, the JiBX runtime components are used to perform the marshal (objects to XML) or unmarshal (XML to objects) tasks.

As you have seen in the pom.xml, the JiBX binding files should be located in src/main/jibx. The names of the JiBX files should end with -binding.xml.

Our goal is to map an XML file, based on following schema CustomerSchema.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://stefanjaeger.ch/CustomerSchema"
  xmlns:sja="http://stefanjaeger.ch/CustomerSchema"
  elementFormDefault="qualified">
  <element name="customer">
    <complexType>
      <sequence>
        <element ref="sja:person" maxOccurs="1" />
        <element ref="sja:city" maxOccurs="1" />
      </sequence>
    </complexType>
  </element>
  <element name="person">
    <complexType>
      <sequence>
        <element ref="sja:first-name" maxOccurs="1" />
        <element ref="sja:last-name" maxOccurs="1" />
      </sequence>
    </complexType>
  </element>
  <element name="first-name" type="string" />
  <element name="last-name" type="string" />
  <element name="city" type="string" />
</schema>

Our XML Customer1.xml file looks like:

<?xml version="1.0" encoding="UTF-8"?>
<customer xmlns="http://stefanjaeger.ch/CustomerSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://stefanjaeger.ch/CustomerSchema CustomerSchema.xsd">
  <person>
    <first-name>Stefan</first-name>
    <last-name>Jaeger</last-name>
  </person>
  <city>Davos Dorf</city>
</customer>

We want to map the XML in the two objects Customer and Person (to simplify these lines of code, the getter, setter and toString methods are not described).

public class Customer {
  private Person person;
  private String city;
}
 
public class Person {
  private String firstName;
  private String lastName;
}

To map the XML file to these classes, we create following binding definition. Because we use a XML schema, we have to define the namespace. Also the fully qualified name of the mapped class Customer need’s to be used. Because the class Person is in relation with the Customer class, JiBX recognizes automatically the fully qualified name of Person.

<?xml version="1.0" encoding="UTF-8"?>
<binding>
  <mapping name="customer" class="ch.stefanjaeger.jibx.Customer">
  <namespace uri="http://stefanjaeger.ch/CustomerSchema" default="elements"/>
    <structure name="person" field="person">
      <value name="first-name" field="firstName" />
      <value name="last-name" field="lastName" />
    </structure>
    <value name="city" field="city" />
  </mapping>
</binding>

Now, we have a XML file, some Java classes and a binding between them. What we now need is an application, which does the unmarshalling of the XML file.

public class JiBXDemoApplication {
  public static void main(String[] args) throws Exception {
    IBindingFactory bfact = BindingDirectory.getFactory(Customer.class);
    IUnmarshallingContext uctx = bfact.createUnmarshallingContext();
    Customer customer = (Customer) uctx.unmarshalDocument(
      new FileInputStream("Customer1.xml"), null);
 
    System.out.println(customer.toString());
  }
}

We are finished now. Just build the project with the command mvn package and let’s see, how the test run is working. Remember to place the XML schema and the XML file to the same location as the JAR file (after mvn package, it should be located in /target/).

The command

java -jar jibx_playground-1.0-SNAPSHOT-jar-with-dependencies.jar

results in

ch.stefanjaeger.jibx.Customer@12d03f9
[person=ch.stefanjaeger.jibx.Person@15dfd77
 [firstName=Stefan,lastName=Jaeger]
,city=Davos Dorf]

I have to admit, that I did the same example with ANT. It tooks me a little bit longer… From today on, I’m a Maven fan

Download here the source code of this example. You only have to run mvn package to build the project.

1. Hi SteveJ,
   I am able to execute example with dependency jar successfully but when I try to run the example using without dependency jar, its not working. Do I need to set the classpath(for all the jars) before running it?

   Comment by Sharad — 7.7.2008 @ 15:07

2. Hi SteveJ,
   I have requirement where I have to ignore the root element present in the data.xml and do binding only for the child elements of the root element. Can you help me on this?
   Thanks in advance.]

   Regards,
   Sharad

   Comment by Sharad — 7.7.2008 @ 15:49

3. Hi Sharad
   1. question:
   Yes, that’s right. The “maven-assembly-plugin” just put all required jar files into the newly created jar file. In our case, this is used for the commons-lang library and the JiBX library. I have done this just for the example, so that you can just run “java -jar abc.jar”.

   If you have the jar files outside the created jar, you have to define the classpath with all needed jars (e.g. java -cp ./path/to/libs/*.jar -jar abc.jar)

   2. question
   I don’t understand your question completly. In this example, I also don’t map the root element customer directly. It’s just to define a main class, and all items in it are mapped than. It is able, that the root element contains elements, which are from another class. Just have a look at http://jibx.sourceforge.net/tutorial/binding-start.html.

   Sorry for the late answers, I was in holiday…

   Comment by Steve J. — 14.7.2008 @ 22:36

4. Dear SteveJ
   Thanks for the post. I have successfully clean and build the project in eclipse.. but when I try to run it, It says that the system cannot find the file which is the Customer1.xml. I put the file in target folder but it didn’t work then I put in src/main/resource folder but still the same.. Please help me on this
   Thanks
   Pathum

   Comment by Pathum — 28.9.2009 @ 09:38

5. Dear Pathum
   The xml file has just to be in the same folder as the JAR file jibx_playground-1.0-SNAPSHOT-jar-with-dependencies.jar. If you run it directly from target with “java -jar jibx_playground…”, the Customer1.xml needs to be stored in the target folder.
   Regards Steve

   Comment by Steve J. — 1.10.2009 @ 10:29

6. Hi SteveJ,

   I am using a reactor pom, under which there are 2 modules. And each modules has its own binding files. When I run mvn clean install(with verbose turned on), I see that some of the jibx generated files are getting deleted, I do not know to stop it. Please help me on this.

   Thanks
   Vignesh

   Comment by Vignesh — 20.4.2010 @ 17:36

7. Hi Vignesh
   Try to ask your question at Stackoverflow. I think it’s a more appropriate platform for such questions.
   Thanks and Regards
   Stefan

   Comment by Steve J. — 21.4.2010 @ 08:51

8. hi,

   1000x thanks for the tutorial.

   I saved me a few agonizing hours in trying to figure this out.

   oren

   Comment by oren — 14.6.2010 @ 14:20