JiBX: Getting Started with JiBX

# JiBX: Getting Started with JiBX |

JiBX Basics Overview Flexibility Performance Clean code News and Status User Comments Sponsors Support and Training Bugs Getting Started Binding Tutorial A basic binding Binding extras Structure mapping Collections and arrays 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 Eclipse Plug-in Introduction Install Usage Generator Tools Axis2 Usage 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.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 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