Getting started

To get started using JiBX, you just need to download the distribution zip file from the SourceForge downloads page and unzip it to a convenient location on your system. The distribution comes with all the core components of JiBX, including the binding compiler, runtime, extras, and various flavors of generation tools. There are also convenient examples to help get you going, in four flavors:

  • bindgen - use JiBX binding and schema generation from code
  • codegen - use JiBX binding and code generation from schema
  • jibx2wsdl - use JiBX binding, WSDL, and schema generation from code
  • starter - use JiBX with supplied (or hand-written) binding definition

All the examples are set up to use the Ant build tool. If you don't already have Ant installed on your system, you can get it from the Ant Project page.

Once you've installed the distribution on your system, open the readme.html file located in the root of the JiBX distribution. This will provide some details of what's new in the JiBX release, and also links to both the above examples and the offline version of this documentation, also included in the distribution.

Basic use of JiBX

Whether you're using JiBX directly, with a binding definition you've constructed on your own, or using one of the generator tools to create a binding, you're going to need to go through certain steps every time you build your application:

  1. Compile your source code (only if compiled class files are out of date)
  2. Run the JiBX binding compiler on your compiled class files
  3. Use the JiBX runtime and some form of parser when you run your application

This sequence doesn't mean you can't do other steps in between. You may want to assemble your class files into jar files, for instance, after you've run the binding compiler (which currently requires the class files in un-jarred form). You can even use other bytecode manipulation tools along with JiBX, as long as those tools obey the JVM rules for bytecode handling.

The starter examples all include these steps as Ant targets. You can also see the separate pages in this section of the documentation for details on the binding compiler and runtime usage.

Start from code

If you're starting from existing Java code, you can use the BindGen tool included in the JiBX distribution to automatically generate a binding definition and corresponding XML schema definition from your code. BindGen uses default behaviors which will give good XML structure for most data models - but if the default generation is not satisfactory for your needs you can easily customize the generation handling at every level, with features such as:

  • Support for both Java 5-style enum and typed collections, and pre-Java 5 alternatives
  • Specify which class properties are to be included in the XML
  • Control XML representation as attributes or elements, and required or optional
  • Format JavaDocs for export to XML schema definition documentation
  • Change XML naming conventions and namespace usage

You can also use the Jibx2Wsdl tool to generate a WSDL web service definition based on an existing service class. Jibx2Wsdl builds on BindGen and supports all the same customization features for data model classes, along with some added customizations for the service class and WSDL usage.

The bindgen examples show how to use BindGen for binding and schema generation, both with and without customizations. The jibx2wsdl examples do the same for the Jibx2Wsdl tool. For more details of using JiBX with existing Java code, including full details of the customizations structure, see the Start from Code section of this documentation.

Start from schema

If you're starting from an existing XML schema definition, you can use the CodeGen tool included in the JiBX distribution to automatically generate a Java data model and corresponding JiBX binding definition to match your XML documents. Here again, the code and binding generation uses default behaviors which will give a good data model for most schemas, but can be customized at every level to improve handling with features including:

  • Simplify the data model by excluding schema definition components not used in your documents
  • Selectively ignore the content of portions of input documents
  • Inline schema definitions which are only used in one place
  • Support for generating both Java 5-style enum and typed collections, and pre-Java 5 versions
  • Change Java naming conventions and package usage
  • Add your own custom extensions to the code generation for special handling

The codegen examples show how to use the code and binding generation from schema, both with and without customizations. For more details of using JiBX with existing XML schemas, including full details of the customizations structure, see the Start from Schema section of this documentation.