JiBX: <collection> Element

<collection> Element Definition

The collection element defines the binding for a Java collection. Many variations of list-like collections are supported, including user-defined collection types. Arrays are also supported. Maps are not supported directly in JiBX 1.0 (but see the JiBX extras description for custom marshaller/unmarshaller classes which can help with this types of structures).

Collections may consist of a single type of object or multiple types. The simplest form of collection just uses a single mapped item type. This may either be defined using the item-type attribute, in which case no child definitions are necessary, or implied by the absence of child definitions (equivalent to using item-type="java.lang.Object").

Collections consisting of multiple types are defined using multiple child definitions within the collection element. These may be ordered (where the different types occur in a particular sequence) or unordered (where all are mixed together), as determined by the ordered attribute of the structure attribute group. Child definitions within collections must define elements rather than text or attribute values (though the elements defined may themselves have attributes and/or text values). Child definitions within collections are always treated as optional, with any number of occurrances of the corresponding element allowed (zero or more).

The collection element supports several unique attributes along with several common attribute groups, listed below. The unique attributes are used for special types of data access to the collection. These are all optional, and have defaults for common collection types, including java.util.Vector and java.util.ArrayList (as well as subclasses of these classes) along with collection classes implementing the java.util.Collection interface. You can use these attributes to select methods of the containing object for accessing data within a collection (with no property definition for the actual collection object).

One potential issue in working with collections is that JiBX generally needs a way to create an instance of the collection when unmarshalling. If the collection is defined using an interface such as java.util.List you'll need to either define a concrete implementation type with a no-argument constructor to be used for the collection (using the type attribute of the property attribute group) or use the factory attribute of the object attribute group to define a factory method to call when an instance of the collection is needed. The org.jibx.runtime.Utility.arrayListFactory is an example of such a factory method, which can be used directly to supply instances of the java.util.ArrayList class.

As with all object-valued properties, if the collection property is already initialized when JiBX begins unmarshalling the existing collection instance will be used to hold the unmarshalled items of the collection. JiBX does not clear items from the existing collection before unmarshalling, so if you want to reuse existing data structures with a collection you should clear the collection yourself before unmarshalling (one easy way of doing this is with a pre-set method on the containing object class). This is only necessary when reusing objects, not when unmarshalling to a new instance of an object (where any collections created by the object constructor will initially be empty in any case). If an element name is used with an optional collection, and that name is missing from an input XML document, the collection property will be set to null. If you don't want the collection property to ever be set to null, use a wrapper structure element for the optional element name around the collection element.

Attributes