Introduction to JiBX

1. Overview

JiBX is a tool for binding XML data to Java objects. It provides solid performance compared to other common tools such as JAXB.

JiBX is also quite flexible when compared to other Java-XML tools, using binding definitions to decouple the Java structure from XML representation so that each can be changed independently.

In this article, we’ll explore the different ways provided by JiBX of binding the XML to Java objects.

2. Components of JiBX

2.1. Binding Definition Document

The binding definition document specifies how your Java objects are converted to or from XML.

The JiBX binding compiler takes one or more binding definitions as input, along with actual class files. It compiles the binding definition into Java bytecode by adding it to the class files. Once the class files have been enhanced with this compiled binding definition code, they are ready to work with JiBX runtime.

2.2. Tools

There are three main tools that we are going to use:

• BindGen – to generate the binding and matching schema definitions from Java code
• CodeGen – to create the Java code and a binding definition from an XML schema
• JiBX2Wsdl – to make the binding definition and a matching WSDL along with a schema definition from existing Java code

3. Maven Configuration

3.1. Dependencies

We need to add the jibx-run dependency in the pom.xml:

<dependency>
    <groupId>org.jibx</groupId>
    <artifactId>jibx-run</artifactId>
    <version>1.3.1</version>
</dependency>

The latest version of this dependency can be found here.

3.2. Plugins

To perform the different steps in JiBX like code generation or binding generation, we need to configure maven-jibx-plugin in pom.xml.

For the case when we need to start from the Java code and generate the binding and schema definition, let’s configure the plugin:

<plugin>
    <groupId>org.jibx</groupId>
    <artifactId>maven-jibx-plugin</artifactId>
    ...
    <configuration>
        <directory>src/main/resources</directory>
        <includes>
            <includes>*-binding.xml</includes>
        </includes>
        <excludes>
            <exclude>template-binding.xml</exclude>
        </excludes>
        <verbose>true</verbose>
    </configuration>
    <executions>
        <execution>
            <phase>process-classes</phase>
            <goals>
                <goal>bind</goal>
            </goals>
        </execution>
    </executions>
</plugin>

When we have a schema and we generate the Java code and binding definition, the maven-jibx-plugin is configured with the information about schema file path and path to the source code directory:

<plugin>
    <groupId>org.jibx</groupId>
    <artifactId>maven-jibx-plugin</artifactId>
    ...
    <executions>
        <execution>
        <id>generate-java-code-from-schema</id>
        <goals>
             <goal>schema-codegen</goal>
        </goals>
            <configuration>
                <directory>src/main/jibx</directory>
                <includes>
                    <include>customer-schema.xsd</include>
                </includes>
                <verbose>true</verbose>
            </configuration>
            </execution>
            <execution>
                <id>compile-binding</id>
                <goals>
                    <goal>bind</goal>
                </goals>
            <configuration>
                <directory>target/generated-sources</directory>
                <load>true</load>
                <validate>true</validate>
                <verify>true</verify>
            </configuration>
        </execution>
    </executions>
</plugin>

4. Binding Definitions

Binding definitions are the core part of JiBX. A basic binding file specifies the mapping between XML and Java object fields:

<binding>
    <mapping name="customer" class="com.baeldung.xml.jibx.Customer">
        ...
        <value name="city" field="city" />
    </mapping>
</binding>

4.1. Structure Mapping

Structure mapping makes the XML structure look similar to object structure:

<binding>
    <mapping name="customer" class="com.baeldung.xml.jibx.Customer">
    ...
    <structure name="person" field="person">
        ...
        <value name="last-name" field="lastName" />
    </structure>
    ...    
    </mapping>
</binding>

The corresponding classes for this structure are going to be:

public class Customer {
    
    private Person person;
    ...
    
    // standard getters and setters

}

public class Person {
    
    private String lastName;
    ...
    
    // standard getters and setters

}

4.2. Collection and Array Mappings

JiBX binding provides an easy way for working with a collection of objects:

<mapping class="com.baeldung.xml.jibx.Order" name="Order">
    <collection get-method="getAddressList" 
      set-method="setAddressList" usage="optional" 
      createtype="java.util.ArrayList">
        
        <structure type="com.baeldung.xml.jibx.Order$Address" 
          name="Address">
            <value style="element" name="Name" 
              get-method="getName" set-method="setName"/>
              ...
        </structure>
     ...
</mapping>

Let’s see corresponding mapping Java objects:

public class Order {
    List<Address> addressList = new ArrayList<>();
    ...
 
    // getters and setters here
}

public static class Address {
    private String name;
    
    ...
    // standard getters and setter
    
}

4.3. Advanced Mappings

So far we have seen a basic mapping definition. JiBX mapping provides different flavors of mapping like abstract mapping and mapping inheritance.

Let see how can we define an abstract mapping:

<binding>
    <mapping name="customer" 
      class="com.baeldung.xml.jibx.Customer">

        <structure name="person" field="person">
            ...
            <value name="name" field="name" />
        </structure>
        <structure name="home-phone" field="homePhone" />
        <structure name="office-phone" field="officePhone" />
        <value name="city" field="city" />
    </mapping>
 
    <mapping name="phone" 
      class="com.baeldung.xml.jibx.Phone" abstract="true">
        <value name="number" field="number"/>
    </mapping>
</binding>

Let’s see how this binds to Java objects:

public class Customer {
    private Person person;
    ...
    private Phone homePhone;
    private Phone officePhone;
    
    // standard getters and setters
    
}

Here we have specified multiple Phone fields in Customer class. The Phone itself is again a POJO:

public class Phone {

    private String number;
    
    // standard getters and setters
}

In addition to regular mappings, we can also define extensions. Each extension mapping refers to some base mapping. At the time of marshaling, the actual object type decides which XML mapping is applied.

Let’s see how the extensions work:

<binding>
    <mapping class="com.baeldung.xml.jibx.Identity" 
      abstract="true">
        <value name="customer-id" field="customerId"/>
    </mapping>
    ...  
    <mapping name="person" 
      class="com.baeldung.xml.jibx.Person" 
      extends="com.baeldung.xml.jibx.Identity">
        <structure map-as="com.baeldung.xml.jibx.Identity"/>
        ...
    </mapping>
    ...
</binding>

Let’s look at the corresponding Java objects:

public class Identity {

    private long customerId;
    
    // standard getters and setters
}

5. Conclusion

In this quick article, we have explored different ways by which we can use the JiBX for converting XML to/from Java objects. We have also seen how we can make use binding definitions to work with different representations.