BindGen tool

BindGen is the tool used to generate a binding definition and matching schema definition from existing Java code.

Running BindGen

BindGen executes as a Java application, meaning it needs to be run directly from a console window using the "java" command, or though some equivalent technique (such as an Ant <java> task, discussed below). However it's being run, you need to include jibx-tools.jar from your JiBX installation lib directory in the Java classpath, along with the path for the compiled class files you'll use as input to the generation. You'll also need several of the other jars from the JiBX lib directory (including jibx-bind.jar, jibx-schema.jar, and jibx-run.jar). As long as these jars are in the same directory as jibx-tools.jar you don't need to list them in the classpath, though - they'll be picked up automatically.

The BindGen application main class is org.jibx.binding.generator.BindGen, and it takes as parameters the fully-qualified names of one or more root class(es) to be to be included in the binding generation. In schema terms, each of these root classes will be treated as a separate global definition.

Here's a sample of running BindGen on Unix/Linux systems from the examples/bindgen directory of the distribution (in a single line, shown split here only for formatting):

java -cp ../../lib/jibx-tools.jar:bin org.jibx.binding.generator.BindGen
 org.jibx.starter1.Order

On Windows, the corresponding command line is:

java -cp ..\..\lib\jibx-tools.jar;bin org.jibx.binding.generator.BindGen
 org.jibx.starter.Order

By default, BindGen output just goes to the current directory where it was executed. The generated root binding definition is named binding.xml, and the generated schema name is derived from the target namespace (which in turn is derived from the Java package name).

Using build tools

You can easily run BindGen from an Ant build, just as you would any other Java application. The build.xml in the examples/bindgen directory gives an example of this (which passes an optional source directory path parameter, in addition to a root class name), as shown below:

  <!-- set classpath for compiling and running application with JiBX -->
  <path id="classpath">
    <fileset dir="${jibx-home}/lib" includes="*.jar"/>
    <pathelement location="bin"/>
  </path>
  ...
  <!-- generate default binding and schema -->
  <target name="bindgen">
  
    <echo message="Running BindGen tool"/>
    <java classpathref="classpath" fork="true" failonerror="true"
        classname="org.jibx.binding.generator.BindGen">
      <arg value="-s"/>
      <arg value="src"/>
      <arg value="org.jibx.starter1.Order"/>
    </java>
    
  </target>

Most IDEs allow you to directly execute an Ant build target, so you can use the Ant approach to running BindGen from within your IDE.

Command line parameters

You can pass a variety of command line parameters to BindGen, as listed below in alphabetical order:

Parameter Purpose
-a Force abstract mapping (equivalent to a schema complexType) generation for classes passed as input parameters.
-b name Generated root binding definition file name (default name is binding.xml)
-c path Path to input customizations file
-m Force concrete mapping (equivalent to a schema complexType plus an element of that type) generation for classes passed as input parameters
-n uri=name,... Give schema namespace URI and file-name pairs (default generates file names from schema namespace URIs)
-o Binding generation only (no schema generation)
-p path,... Paths for loading Java class files (default is the classpath used to run BindGen)
-s path,... Paths for loading Java source files (source is not used by default)
-t path Target directory path for generated output (default is current directory)
-v Verbose output
-w Wipe all files from target directory before generating output (ignored if the target directory is the same as the current directory)

You need to specify one or more class names as command line parameters to BindGen. Each class you name is used as a starting point for generating binding definitions. BindGen examines each class listed to find references to other classes, and then recursively examines the referenced classes, to find the complete set of classes necessary to represent your data. It then generates binding and schema definitions for all of these classes. The class names must be at the end of the command line, following any other command line parameters.

You can pass global customizations to BindGen as command-line parameters, by using -- as a special prefix to the customization attribute name. This is explained in more detail in the BindGen customization reference page. Before digging into the details of customizations you may find it useful to review the BindGen examples to learn how BindGen works and see some basic applications of customizations.