# JiBX: Getting Started with JiBX

JiBX Basics
Overview
Flexibility
Performance
Clean code
News and Status
User Comments
Sponsors
Bugs
Getting Started
Binding Tutorial
A basic binding
Binding extras
Structure mapping
Collections
Using mappings
Advanced binding
Method hooks
Custom code
Binding Compiler
Binding on Load
Runtime
JiBX Extras
Building JiBX
Schema Compatibility
Mailing Lists
FAQ
Contributing
License
Binding Definition
Definition details
Definition contexts
Conversions
XML summary
<binding> element
<include> element
<format> element
<namespace> element
<mapping> element
<value> element
<structure> element
<collection> element
Attribute groups
Usage API
Runtime JavaDocs
Subprojects
Generator Tools
JibxSoap
Xsd2Jibx

### 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.0.jar, jibx-run-1.0.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

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:

- Binding Tutorial
- Binding Compiler
- Bind on Load
- Runtime
- Extras