Installation

To install JiBX, just download the distribution zip file and unpack it. This will create a jibx directory that contains the distribution files, including a complete copy of this documentation. The readme.html file in the unpacked root directory gives more information and links to some included demonstration code, and to the local copy of this documentation.

If you're using Maven, you can use the JiBX repository at http://jibx.sourceforge.net/maven/ to get a specific version of the distribution jar files (as jibx-bind-1.x.x.jar, jibx-run-1.x.x.jar, etc.). There's also a Maven2 plugin available for JiBX.

Binding definitions

To use JiBX, you'll need to first create a binding definition that describes how your XML documents are connected to your Java objects. Here's a simple example just to give you a feeling for how this works:

Figure 1. Simple binding example
Simple binding

In this example I've got an XML document with a <customer> root element that I want to bind to a Customer class in my Java code. The binding definition tells JiBX the details of how this binding is to be performed. The color coding in the diagram shows how the three parts interrelate. The mapping element within the binding definition (shown in green) creates the basic linkage between the <customer> element and the Customer class. The child elements of the mapping element provide the details of this linkage - for example, the first value child element (shown in blue) links the <first-name> child element to the firstName field of the Customer class.

JiBX's binding capabilities go far beyond what's shown by this simple example. On the Java side, you can use fields of any access type (including private), or use JavaBean-style get/set methods if you prefer. You can easily define custom serialization handlers for data values, and you can tell JiBX to call your own methods at various points in the binding process to allow further customizations. To learn more about using these and many other JiBX features check out the Binding Tutorial section of this site.

If you're starting from existing Java code you may find the Generator Tools subproject useful. This includes a tool which will generate a default binding for a set of Java classes (and a separate tool to generate an XML schema definition from a binding definition and the referenced Java classes). Similarly, if you're starting from an XML schema definition you may find the Xsd2Jibx subproject useful. This provides a tool to generate a set of Java classes and a corresponding binding definition from a schema. These subprojects can help a lot in getting started, but you should still take the time to understand how bindings work before you go too far with JiBX.

Using JiBX

Once you've got a binding definition for your document format you're ready to begin using JiBX. To do this, you first compile your application classes as normal, then run the JiBX Binding Compiler. The binding compiler converts your binding definition into actual code in the form of binding methods that it adds to your application class files (you can also run the binding compiler at runtime, to modify your classes before they're loaded into the JVM). The methods added by the binding compiler are then used by the JiBX Runtime to actually marshal and unmarshal your Java classes to and from XML.

Starter project

The JiBX distribution includes an example starter project, with an Ant build.xml script for compiling, binding, and running the project code. This is found in the starter directory off the installation root. See the index.html page in this directory for details.

Details

That's the summary. Here are the links for the details of these steps, along with information on some useful tools included in the distribution: