JiBX: BindGen Customizations

JiBX Basics

Overview

Getting Started

Binding Compiler

Binding on Load

Runtime

Extras

Building JiBX

Maven

Contributing

License

News and Status

Support

FAQ

Mailing Lists

Bugs

User Comments

Introduction to customizations

BindGen supports extensive customizations for modifying the default conversions between Java data structures and XML schema representations. The customizations use an XML representation with a nested structure that matches how your Java classes are organized into packages. Here's a simple example:

<custom force-mapping="true" strip-prefixes="m_">
  <package name="org.jibx.starter2" namespace="http://www.jibx.org/starters/fromcode">
    <class name="Address" requireds="street1 city"/>
    <class name="Customer" requireds="lastName firstName customerNumber">
      <value field="m_customerNumber" attribute="customerNumber"/>
    </class>
    <class name="Item" requireds="id quantity price">
      <value get-method="getId" set-method="setId" attribute="id"/>
      <value property-name="quantity" attribute="quantity"/>
    </class>
  </package>
</custom>

This example defines four levels of customizations. The top level, those defined as attributes of the <custom> element, apply to all classes which BindGen will process. In this case the first option, force-mapping="true", tells BindGen to use global xs:complexType definitions for all classes other than simple text values, while the second one, strip-prefixes="m_" tells BindGen to ignore the prefix "m_" when converting Java field names to value names.

The second level of customizations are defined by the <package> element in the example. On this element, the required name attribute gives the name of the package, while the namespace attribute defines a namespace to be used for classes within that package.

The third level of customizations are defined by the <class> elements nested within the <package> element. On these elements, the required name attribute gives the name of the class (relative to the containing <package> element, if any), while the other attributes set options that apply to that class. In this example, the only options used at this level are telling BindGen that some of the values defined by the classes are required.

Finally, the fourth level of customizations are defined by the <value> elements within some of the <class> elements. The field, get-method/set-method pair, or property-name attributes both identify the value and tell BindGen how it is to be accessed, while the attribute attributes tell BindGen to use attribute to represent the values in XML, with the supplied names. If it seems like a lot of effort to have these separate elements just to say that a value is to be an attribute rather than an element, you'll be relieved to know that there's actually a simpler approach to do the same thing, using flag characters on names in the requireds list (or optionals list, if appropriate) of the containing <class> element - but the <value> element is also useful for other purposes, and this usage is a way to include them in this simple example.

Nesting in customizations

<package> elements can be nested inside other <package> elements. When <package> and <class> elements are nested within the customizations, the names used are always relative to the containing <package> element. You can also use a <class> element directly as a child of the <custom> element, but in this case you need to specify the fully-qualified class name.

You might expect inner classes to be handled the same way, nesting the <class> element for the inner class within that for the containing class - but at least for now, that's not the case. BindGen instead requires a separate <class> element as a sibling of that for the containing class, using a '$' separator for the inner class name (with the inner class name given as "Outer$Inner", for instance).

There are three nesting customization elements: The <custom> element itself, the <package> element, and the <class> element. As mentioned in the last section, the <custom> element is always the root element of a customization document, and can have <package> child elements, <class> child elements, or both. <package> elements can in turn contain other <package> and/or <class> child elements. The only restriction is that you need to nest these in a way that reflects the package structure - so if you have a <package> element present for a particular package, any <package> elements referring to subpackages and any <class> elements referring to classes in that package or in subpackages must be nested inside the original <package> element.

An example might help explain this part: If you have a <package> element referencing the "com.sosnoski.ws.library" package, and another <package> element referencing the "com.sosnoski.ws.library.data" package, and a <class> element referencing the "com.sosnoski.ws.library.data.Book" class, then these elements would need to be nested in that order. If you have another <class> element referencing the "com.sosnoski.ws.store.Item" class, that's outside the package hierarchy for the first three elements. So these would be structured as:

  <package name="com.sosnoski.ws.library" ...>
    <package name="data" ...>
      <class name="Book" .../>
    </package>
  </package>
  <class name="com.sosnoski.ws.store.Item" .../>

Note again that the names used for these nested <package> and <class> elements are always relative to the containing <package>, if any.

Customization attributes

All the different nesting customization elements share a common basic set of attributes, and any values set for these attributes are inherited by child elements (unless overridden by a new setting at the child level). Here's the list:

Nesting customization attributes

force-mapping	Control whether mapping definitions (and corresponding schema xs:complexType or xs:simpleType definitions) are generated for each class. Normally BindGen only generates mapping definitions for classes specified on the command line, and for referenced classes used in more than one place in the data structure; this flag lets you change this behavior. Allowed values are "true" (meaning all classes should be handled as global schema types) and "false" (the default).
force-names	Control whether element names are used as wrappers around the content of every class reference. By default, wrapper element names are not used when the reference is a required value unless the referenced class has a mapping definition, so classes which are only referenced in one place may be effectively inlined into the XML representation of the referencing class. Allowed values are "true" (meaning always use a wrapper element, the default) and "false".
javadoc-formatter	Fully-qualified class name for JavaDoc formatter to be used, which must implement the `org.jibx.custom.classes.IDocumentFormatter`. The function of the formatter is to retrieve JavaDoc text from classes, fields, or methods, and to format the text for use in schema documentation, so by using your own formatter you can make selective changes in cases where JavaDoc conventions (such as the standard "Get the XXX value" text generally used at the start of read access method JavaDocs) don't match the form of documentation needed in schema definitions. The default implementation is `org.jibx.schema.generator.DocumentFormatter`, which can easily be used as a base class for your own customized implementation.
map-abstract	Use abstract mappings (corresponding to xs:complexType definitions) for classes if "true", or concrete mappings (corresponding to xs:element definitions) if "false".
namespace	Basic namespace URI used for definitions. Note that by default, this will just be a base value which will be extended for child packages (see namespace-style attribute, below).
namespace-style	Technique used to derive namespace URIs. Values are "none", "package", or "fixed". The default is "package", meaning namespaces are derived from package names. To set a fixed namespace for a package and all child packages, you need to both specify the namespace (see namespace attribute, above) and set this values "fixed".
name-style	Technique used to derive XML names from Java value names. This can be "camel-case", "upper-camel-case", "hyphenated", "dotted", or "underscored" (all hopefully somewhat self-explanatory). "camel-case" is the default.
property-access	Control how values within a class are found by BindGen and accessed by the generated binding. Allowed values are "true" (meaning to use get/set access methods, as defined for JavaBean properties) and "false" (meaning use fields directly, the default).
require	Types to be treated as required values (unless otherwise specified). This can be "none", "primitives", "objects", or "all". The default is "primitives".
strip-prefixes	Prefix strings to be stripped from Java field names before converting to XML element or attribute names. The value is a list of prefix strings, separated by whitespace characters.
strip-suffixes	Suffix strings to be stripped from Java field names before converting to XML element or attribute names. The value is a list of suffix strings, separated by whitespace characters.
use-javadocs	Control whether JavaDocs are exported to generated schemas. Possible values are "true" (the default) and "false".
value-style	Set the type of representation to be used for simple text values. The allowed values are "attribute" and "element". The default is to use attribute representation for primitive values and a few selected object types (the standard `java.lang` wrapper classes for primitive values, along with `java.math.BigDecimal` and `java.math.BigInteger` and date/time types), while using element representation for all other object types.
wrap-collections	Control whether wrapper elements (an element which contains the repeating child elements representing individual items in the collection) should be used for collection values. Possible values are "true" and "false" (the default).

Besides these common nesting customization attributes, each of the nesting elements defines its own customization attributes. The <custom> element itself defines the following attributes, which are passed through to the generated binding definition as the corresponding attributes of the binding definition <binding> root element:

<custom> customization attributes

add-constructors	If the value of this customization attribute is "true", the binding compiler will add a default constructor to a bound class when necessary to make it usable in the binding. The allowed values are "true" and "false", with no default.
direction	This customization attribute is passed through to the generated binding to specify the types of conversions to and from XML to be supported. The allowed values are "input" (unmarshalling only), "output" (marshalling only), or "both" (both marshalling and unmarshalling). There is no default for this customization attribute, but the generated binding will by default operate as though the value "both" were set.
force-classes	If the value of this customization attribute is "true", it forces generation of marshaller/unmarshaller classes for top-level abstract mappings which are not extended by other mappings. Normally these classes would not be generated, since such mappings are never used directly within the binding. The generated classes can be used at runtime by custom code, though, as the equivalent of type mappings. The allowed values are "true" and "false", with no default.
track-source	When this customization attribute is present with value "true", the binding compiler will add code to each bound object class to implement the `org.jibx.runtime.ITrackSource` interface and store source position information when instance objects are unmarshalled. This interface lets you retrieve information about the source document and specific line and column location of the document component associated with that object. The allowed values are "true" and "false", with no default.

The <package> element defines only one attribute, besides the nesting attributes defined above:

<package> customization attributes

name	This required attribute gives the package name, relative to the containing <package> element (if any).

The <class> element defines the following attributes, in addition to the standard nesting customization attributes:

<class> customization attributes

create-type	Gives the type to be used when creating an instance of the class, as a fully-qualified class name. This customization is mostly useful in cases where the class is abstract or an interface, in which case some way of constructing instances of the class must be defined if the generated binding is going to be used for unmarshalling XML.
deserializer	Fully-qualifed class and method name for a static method used to deserialize a text string representing an instance of the class (see the corresponding attribute in the binding definition string attribute group for details). This may only be used in combination with the attribute form="simple".
element-name	Element name to be used for this class when generating a concrete mapping, corresponding to a schema global element definition.
enum-value-method	This attribute is only relevant for Java 5 enum classes which have XML text values different from the enum value names. The value of the attribute must be the name of a method in the enum class which returns the XML text value. See the corresponding attribute in the binding definition string attribute group for details.
excludes	List of value names to be excluded from the XML representation of the class. Names in the list are separated by whitespace characters.
factory	Gives a factory method to be used for creating an instance of the class, as a fully-qualified class and method name. This customization is mostly useful in cases where the class is abstract or an interface, in which case some way of constructing instances of the class must be defined if the generated binding is going to be used for unmarshalling XML.
form	Form of XML representation to be used for the class. The allowed values are "default" (meaning a concrete mapping corresponding to a schema global element definition for classes specified as input to BindGen, and an abstract mapping corresponding to a schema complex type definition for referenced classes), "abstract-mapping" (meaning an abstract mapping is required), "concrete-mapping" (meaning a concrete mapping is required), and "simple" (meaning the class represents a simple text value corresponding to a schema simple type).
includes	List of value names to be included in the XML representation of the class. Names in the list are separated by whitespace characters, and optionally prefixed with leading '@' (to indicate an attribute representation) or '/' (to indicate an element representation) characters. When this attribute is used, only the values in the list will be included in the XML representation.
name	This required attribute gives the class name, relative to the containing <package> element (if any).
optionals	List of value names to be treated as optional in the XML representation of the class. Names in the list are separated by whitespace characters, and optionally prefixed with leading '@' (to indicate an attribute representation) or '/' (to indicate an element representation) characters.
requireds	List of value names to be treated as required in the XML representation of the class. Names in the list are separated by whitespace characters, and optionally prefixed with leading '@' (to indicate an attribute representation) or '/' (to indicate an element representation) characters.
serializer	Fully-qualifed class and method name for a static method used to serialize an instance of the class to a text string (see the corresponding attribute in the binding definition string attribute group for details). This may only be used in combination with the attribute form="simple".
type-name	Complex type name to be used for this class when generating an abstract mapping, corresponding to a schema global complex type definition.
use-super	Controls whether the values from the superclass will be included in the XML representation of this class. The allowed values are "true" (the default) and "false".

The <value> element uses a separate set of customization attributes. Here's the list of those attributes:

<value> customization attributes

actual-type	Gives the type of a value, as a fully-qualified class name. This overrides the declared type for a field or property.
attribute	This customization makes the XML representation of the value an attribute. The value of this attribute is the name to be used for the value. If this attribute is used, the element attribute cannot be used.
create-type	Gives the type to be used when creating an instance of the value, as a fully-qualified class name. This customization is mostly useful in cases where the value type is an abstract class or interface which cannot be created directly, in which case some alternative way of constructing instances of the class must be defined (which may be done at the point of reference, by using this attribute to specify an implementation class or the factory attribute to specify a constuction method, or at the class level by the <class> customization attribute create-type or factory). As a convenience, the special case of values of type `java.util.List` by default use the create-type `java.util.ArrayList.`.
element	This customization makes the XML representation of the value an element. The value of this attribute is the name to be used for the value. If this attribute is used, the attribute attribute cannot be used.
factory	Gives a static factory method to be used for creating an instance of the value, as a fully-qualified class and method name. As with the create-type customization, this is mostly useful in cases where the value type is an abstract class or interface which cannot be created directly. See the corresponding attribute in the binding definition object attribute group for details.
field	Defines the value as a field of the class. Either this attribute, a property-name attribute, or a get-method/set-method attribute pair is required.
get-method	Defines the value by a read access method name. When this attribute is used, a set-method attribute must also be used unless the XML conversions are output-only (see the direction attribute). Either this attribute pair, a field attribute, or a property-name attribute is required.
item-name	This attribute only applies when the value is an array or collection. In this case, the attribute value is the name used for each item in the collection. If not specified, the name "item" is used by default.
item-type	This attribute only applies when the value is an array or collection. In this case, the attribute value is the actual type of items in the collection (as a fully-qualified class name). This attribute is mainly useful when working with untyped (pre-Java 5) collection classes, where the item type cannot be found by examination of the Java code.
property-name	Defines the value by property name, which must have matching "get"/"set" (or "is"/"set", in the case of a boolean value) methods. Either this attribute, a field attribute, or a get-method/set-method attribute pair is required.
required	Specifies whether the value is treated as a required component ("true") or optional component ("false") of the XML representation.
set-method	Defines the value by a write access method name. When this attribute is used, a get-method attribute must also be used unless the XML conversions are input-only (see the direction attribute). Either this attribute pair, a field attribute, or a property-name attribute is required.

Command line customizations

You can also pass global customizations to BindGen as command-line parameters, without the need to create a customizations file, by using "--" as a special prefix to the customization attribute value. So to set the same global options as used in the introductory example customizations, you'd use --strip-prefixes=m_ and --force-mapping=true on the BindGen command line. No quotes are needed for the attribute value when you use this technique. If you want to set a customization that takes a list of multiple values, just use commas rather than spaces as separators between the individual values (so to ignore the prefixes "m_" and "s_" on field names, for instance, you'd use the command line parameter --strip-prefixes=m_,s_). This technique only allows you to set global customizations, though, so if you're doing anything at the individual package or class level you'll still need to use a customizations file.