customize

Nesting customizations

Jibx2Wsdl 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 organization that matches how your Java classes are organized into packages. Here's a simple example (taken from example2):

<custom force-classes="true" strip-prefixes="m_">
  <package name="com.sosnoski.ws.library.jibx2wsdl"
      namespace="http://sosnoski.com/ws/library">
    <class name="Book" requireds="type title isbn authors">
      <field field="m_type" attribute="type"/>
      <field field="m_isbn" attribute="isbn"/>
    </class>
    <class name="Type" requireds="description name"/>
  </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 Jibx2Wsdl will process. In this case the first option, force-classes="true", just sets an option on the binding definition itself, while the second one, strip-prefixes="m_" tells Jibx2Wsdl 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, while the other attributes set options that apply to that class. In this example, the only options used at this level are telling Jibx2Wsdl that some of the values defined by the classes are required.

Finally, the fourth level of customizations are defined by the <field> elements within the first <class> element. The required field attribute gives the field name, while the attribute attribute tells Jibx2Wsdl to use attributes for the XML representation of these fields, and gives the corresponding attribute name. 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 <field> element or alternatives are still useful for other purposes, and this usage is a way to include them in this simple example.

<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. Jibx2Wsdl 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).

Nesting elements and attributes

The basic nesting customization elements are used for controlling how Java data structures are translated into XML representations. These customizations are used by both Jibx2Wsdl and BindingGenerator. Jibx2Wsdl also defines some extension elements which can be added to the customizations information for controlling how service classes are translated into WSDL definitions.

The basic nesting customization elements are the three you were introduced to in the last section: The <custom> element itself, the <package> element, and the <class> element. As mentioned in that 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.

The Jibx2Wsdl extension elements are <wsdl> and <service>. The <wsdl> element, if present, must always be a direct child of the <custom> element at the root of the customization document. It can contain any number of child <service> elements, which can in turn contain <operation> elements, and the latter can contain other elements. The <operation> elements don't define any settings inherited by their child elements, though, so they're not considered as part of this set of nesting customization elements.

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:

Besides these attributes that apply to all the different nesting customization elements, there's another set that applies only to the ones used for basic bindings (<custom>, <package>, and <class>):

The third group of nesting customization attributes apply only to the WSDL-specific nesting elements (<wsdl> and <service>):

Nesting customization element details

<custom> element

This is the root of the customization document. The only child elements allowed are <wsdl> (if using Jibx2Wsdl, not if using BindingGenerator), <package>, and <class>. In addition to the first two groups of nesting attributes listed above, this supports the following attributes:

<package> element

This element defines customizations that apply to a particular package, along with any subpackages, and classes both in the package and any subpackages. The only child elements allowed are <package> and <class>. In addition to the first two groups of nesting attributes listed above, this supports the following attributes:

<class> element

This element defines customizations that apply to a particular class. The only child elements allowed are <field>, <collection-field>, <property>, and <collection-property>. In addition to the first two groups of nesting attributes listed above, this supports the following attributes:

Value names used in the include, exclude, requireds, and optionals lists are either field names, with any prefixes or suffixes stripped, or property names (as found from get/set access methods), whichever is appropriate (see the property-access attribute in the second table of common nesting definitions, above). In the case of the include, requireds, and optionals lists the names can be prefixed with a flag character to indicate the type of representation to be used for the value: '@' for an attribute, '/' for an element, and '#' for a text value (NOTE: '#' is not yet supported). This approach provides an easy way to override the default choice of representation without needing to add a separate child element for each value.

Value specification elements

The value specification elements each provide customization details for a particular field or property of a class. They can only be used as the children of a <class> element, and cannot have any child elements. They share a common set of attribute values:

<field> element

This element defines customizations that apply to a particular field. This defines one attribute in addition to the common set listed above:

<collection-field> element

This element defines customizations that apply to a particular field defining a collection of values. This defines three attributes in addition to the common set listed above:

<property> element

This element defines customizations that apply to a particular property. This defines two attributes in addition to the common set listed above:

<collection-property> element

This element defines customizations that apply to a particular property defining a collection of values. This defines four attributes in addition to the common set listed above: