<!--

DTD for JiBX binding definition file

This file is generally kept up to date in terms of structure, but the comments
may not match the HTML binding documentation. The HTML documentation should be
considered correct in the case of any differences.

-->

<!--
  Style attribute. This determines whether simple values are expressed as
  attributes or elements in the XML representation. The value is inherited,
  so it can be set at any level of the binding definition hierarchy.

  Basic attributes:
    value-style - mapping style, simple values as: <"element"> or "attribute".
-->

<!ENTITY % style-attribute "
    value-style CDATA   #IMPLIED"
  >

<!--
  Attributes for a name definition. These attributes are used when defining
  an element or attribute name.

  Basic attributes:
    name - element or attribute name
    ns - namespace URI; default is innermost associated namespace ns value
      default, if any
-->

<!ENTITY % name-attributes "
    name        CDATA   #IMPLIED
    ns          CDATA   #IMPLIED"
  >

<!--
  Attributes for an object mapping. These attributes are all used in creating
  a linkage to an object.

  Special instance handling:
    factory - factory method for constructing new instances of object; this
      applies to bindings for unmarshalling only, and if supplied it must be
      in the form of a fully-qualified class+method name (e.g.,
      "com.sosnoski.jibx.ObjectBuilderFactory.newInstance" specifies
      the newInstance() method of the ObjectBuilderFactory class in the
      com.sosnoski.jibx package) for a static, no-argument method returning
      an object of the bound class. If not supplied instances of the
      bound class are constructed using a null argument constructor.
    pre-set - bound class method called on new instances of the class before
      they are populated with data from unmarshalling.
    post-set - bound class method called on new instances of the class after
      they are populated with data from unmarshalling.
    pre-get - bound class method called before instances of the class are
      marshalled.

  Special conversion handling:
    marshaller - custom serialization handler class, as the fully-qualified
      name of a class implementing the org.jibx.runtime.Marshaller interface.
      This is only allowed with an output binding; it is required if an
      unmarshaller is defined for an input-output binding.
    unmarshaller - custom deserialization handler class, as the fully-qualified
      name of a class implementing the org.jibx.runtime.Unmarshaller
      interface. This attribute is only allowed with an input binding; it is
      required if a marshaller is defined for an input-output binding.
  
  The set of attributes used for special instance handling are incompatible
  with those used for special conversion handling.
-->

<!ENTITY % object-attributes "
    factory     CDATA   #IMPLIED
    pre-set     CDATA   #IMPLIED
    post-set    CDATA   #IMPLIED
    pre-get     CDATA   #IMPLIED
    marshaller  CDATA   #IMPLIED
    unmarshaller CDATA   #IMPLIED"
  >

<!--
  Attributes for a property mapping. These attributes are all used in creating
  a binding to a Java language value (primitive or object) that's a property
  of some object.

  Basic attributes:
    field - name of associated field within bound class; this is required
      except for auto-generated identity fields, for values from a collection,
      or when both get-method (for output bindings) and set-method (for input
      bindings) are supplied. The name "this" is always allowed, in order to
      explicitly refer to the containing object, but may not be used in
      combination with either get-method or set-method.
    type - fully-qualified class name for value of field; This can be used to
      force a more specific type for a property value defined by the field
      definition or access method signature as either a base class or an
      interface

  Optional item attributes:
    usage - usage requirement: <"required"> or "optional".
    test-method - method for checking if optional value is present in instance
      of bound class. This is the name of a no-argument method with return type
      "boolean", which must return "true" if the value is present and "false"
      if it is not present. This is only allowed in combination with
      usage="optional". If not specified, a simple "==" comparison is used with
      primitive types to check for a value different from the default, and a
      "equals()" comparison for object types with non-null defaults.

  Special conversion handling:
    get-method - getter method for retrieving value from instance of bound
      class. This is the name of a no-argument method returning a
      value (primitive or object).
    set-method - setter method for storing value in instance of bound class.
      This is the name of a method with return type "void", taking a
      single value (primitive or object) as a parameter. If both get-method
      and set-method are defined, the set-method parameter type must be the
      same as the get-method return value.
-->

<!ENTITY % property-attributes "
    field       CDATA   #IMPLIED
    type        CDATA   #IMPLIED
    usage       CDATA   #IMPLIED
    test-method CDATA   #IMPLIED
    get-method  CDATA   #IMPLIED
    set-method  CDATA   #IMPLIED"
  >

<!--
  Attributes for a string value. These attributes are all used in working with
  simple text values, which may be expressed in XML as attribute values or
  character data content in simple elements (those with no child elements).

  Optional item attributes:
    default - default value; implies an optional value. If not specified,
      the default for primitive types is the same as the member variable initial
      state defined by the JLS, and for object types is "null".

  Special conversion handling:
    serializer - custom serialization handler method, as the fully-qualified
      name of a static method with the signature "String xxxx(Target value)",
      where "xxxx" is the method name and "Target" is the class of the field
      (primitive or object)
    deserializer - custom deserialization handler method, as the
      fully-qualified name of a static method with the signature
      "Target xxxx(String text)", where "xxxx" is the method name and
      "Target" is the class of the field (primitive or object)
-->

<!ENTITY % string-attributes "
    default     CDATA   #IMPLIED
    serializer  CDATA   #IMPLIED
    deserializer CDATA  #IMPLIED"
  >

<!--
  Attributes for component structures. These attributes are used to define and
  reference labeled binding components, allowing reuse of definitions. They're
  supported by structures and collections.
  
  Component references:
    label - identifier for this componet, allowing it to be reused from other
      locations in the binding definition
    using - identifier for component definition to be reused
  
  Component ordering:
    ordered - ordered content flag: <"true"> (child binding components define
      ordered content) or "false" (unordered child content)
    choice - choice of content flag: "true" (choice between child binding
      components) or <"false"> (multiple child binding components allowed)
-->

<!ENTITY % structure-attributes "
    label       CDATA   #IMPLIED
    using       CDATA   #IMPLIED
    ordered     CDATA   #IMPLIED
    choice      CDATA   #IMPLIED"
  >

<!--
  Root element for binding definition.

  Basic attributes:
    name - binding name (default is same as file name, without suffix)
    direction - usage of this binding: "input", "output", or <"both">
    forwards - allow forward references on ids in unmarshalling: <"true">
      (forward references handled) or "false" (all ids must be defined in XML
      before first reference)
    package - package for created binding factory class, default is same
      package as class for first mapping element
    track-source - track unmarshalling source position: "true" or <"false">
    force-classes - force class generation for top-level abstract mappings:
      "true" or <"false">

  along with the style attributes defined above.
-->

<!ELEMENT binding (include*, namespace*, format*, mapping+)>
  <!ATTLIST binding
    name        CDATA   #IMPLIED
    direction   CDATA   #IMPLIED
    forwards    CDATA   #IMPLIED
    package     CDATA   #IMPLIED
    track-source CDATA  #IMPLIED
    force-classes CDATA  #IMPLIED
    %style-attribute;
  >

<!--
  Included binding definition. This can only be used at the top level of a
  binding.

  Basic attributes:
    path - included binding path
-->

<!ELEMENT include EMPTY>
  <!ATTLIST namespace
    path        CDATA   #REQUIRED
  >

<!--
  Namespace mapping definition. This can be defined at the top level of the
  binding, or nested within one or more levels of containing definitions. It
  applies by default to all values of the specified type enclosed within the
  parent element.

  Basic attributes:
    uri - namespace URI
    prefix - prefix to map to namespace, ignored on input (namespace URI
      is used directly to identify elements and attributes). The prefix
      is not required if the binding direction is given as "input", or
      if the default attribute is specified with a value of "elements"
      so long as the namespace is never used except where it's the default.
    default - use this namespace by default for child elements and/or
      attributes of parent: <"none"> (not used by default, only when
      specified), "elements" (default for elements only, not attributes),
      "attributes" (default for attributes only, not elements), "all"
      (default for both elements and attributes). It is an error if multiple
      sibling namespace elements claim to be the default for either elements
      or attributes.
-->

<!ELEMENT namespace EMPTY>
  <!ATTLIST namespace
    uri         CDATA   #REQUIRED
    prefix      CDATA   #IMPLIED
    default     CDATA   #IMPLIED
  >

<!--
  Type conversion format definition. This can be defined at the top level of
  the binding, or nested within one or more levels of containing definitions.

  Basic attributes:
    label - format identifier, only needed for referencing this definition.
    type - fully-qualified class name for conversion.
  
  and the string attributes defined above. If the label attribute is supplied
  this format applies only when referenced by label within a value definition;
  if the label attribute is not supplied this applies by default to all values
  of the specified type enclosed within the parent element.
-->

<!ELEMENT format EMPTY>
  <!ATTLIST format
    label       CDATA   #IMPLIED
    type        CDATA   #REQUIRED
    %string-attributes;
  >

<!--
  Class binding definition. This can be defined at the top level of the
  binding, or nested within one or more levels of containing definitions.

  Basic attributes:
    class - fully qualified class name of bound class, which must be a user
      class modifiable by the binding compiler.
    abstract - abstract definition to be extended by subclass mappings: "true"
      (abstract definition) or <"false"> (concrete definition used directly).
    extends - fully qualified class name of base class with defined abstract
      mapping being extended by subclass.
    type-name - optional type name for an abstract binding.

  along with all the style, name, and object attributes defined above.
  The name attribute is required unless either abstract="true" is specified or
  a marshaller or unmarshaller is supplied using the object attributes.
-->

<!ELEMENT mapping (namespace*, format*, mapping*, (value|structure|collection)*)>
  <!ATTLIST mapping
    class       CDATA   #REQUIRED
    abstract    CDATA   #IMPLIED
    extends     CDATA   #IMPLIED
    type-name   CDATA   #IMPLIED
    %style-attribute;
    %name-attributes;
    %object-attributes;
    %structure-attributes;
  >

<!--
  Value binding definition. This is used to define an attribute or a
  simple element value (one with only character data content).

  Basic attributes:
    format - reference to a named format in a containing scope of the binding
      definition. If given, the named format is used as the default for this
      value binding.
    style - mapping style, express value as: <"element">, "attribute", "text",
      or "cdata".
    constant - contant value always used when marshalling, checked when
      unmarshalling.
 
  Identifier attributes:
    ident - identifier property flag: <"none">, "def" (value is a unique
      identifier for this instance), "auto" (value is autogenerated as a unique
      identifier when marshalling, and used only as an identifier when
      unmarshalling), or "ref" (value is an object with an identifier property,
      the identifier property of the object is used in the XML representation
      rather than the actual object). Only one property with ident="def" or
      "auto" is allowed for a mapping, the property must be a String, and it
	    must be defined directly as a child of the mapping element; it is not
	    allowed as a child of a structure element.
  
  as well as the style, name, property, and string attributes defined above.
  The name attribute is always required. The property attributes are required
  (either as a field name, or as get and/or set methods) unless the value is
  defined as an auto-generated identifier by the string attributes.
-->

<!ELEMENT value EMPTY>
  <!ATTLIST value
    constant    CDATA   #IMPLIED
    format      CDATA   #IMPLIED
    ident       CDATA   #IMPLIED
    style       CDATA   #IMPLIED
    %name-attributes;
    %property-attributes;
    %string-attributes;
  >

<!--
  Structure binding definition. This is used for defining elements with
  complex content. It is also used to include values obtained indirectly
  (from referenced objects) as part of the current element definition, or to
  create an element wrapper containing other values from the current object.

  Mapping references:
    map-as - fully-qualified class name of mapping to be used for property. If
      this attribute is used, the named class must be a superclass or interface
      of the type specified by the property definition and must have a mapping
      defined within an enclosing context. This attribute implies
      mapping="true".

  along with all the style, name, label, property, and object
  attributes defined above. The name attributes are optional; if not supplied, a
  property definition must be present and all contained bindings apply to fields
  of the referenced object. The object attributes are only allowed in
  combination with a field attribute.
-->

<!ELEMENT structure (value|structure|collection)*>
  <!ATTLIST structure
    map-as      CDATA   #IMPLIED
    %style-attribute;
    %name-attributes;
    %object-attributes;
    %property-attributes;
    %structure-attributes;
>
  
<!--
  Collection binding definition. This is used to define handling for Java
  collections.

  Collection handling:
    load-method - indexed load item method for collection. If used, the value is
      the name of a method taking a single int argument and returning the item
      value from the collection. Only allowed in combination with size-method.
    size-method - item count method for collection. If present, the value is the
      name of a no-argument method returning an int count of the items present
      in the collection.
    store-method - indexed store item method for collection. If used, the value
      is the name of a method taking an int and an item value to be stored in
      the collection.
    add-method - add item method for collection. If used, the value is the name
      of a method taking an item value to be appended to the collection.
    iter-method - iterator method for collection. If used, the value is the name
      of a no-argument method returning a java.lang.Iterator or
      java.lang.Enumeration for the objects in a collection.
      
  Value type:
    item-type - fully-qualified class name for items contained in collection,
      where the class has an object type mapping defined at an enclosing level.
      This is used for generic collections and for arrays of a base class or
      interface type. Either this attribute or a contained value or structure
      element with no field attribute must be supplied for a collection-valued
      property.

  along with all the style, name, label, and property attributes
  defined above. The name attributes are optional, but a property definition is
  always required. The collection handling attributes are not needed when the
  property definition is for a standard collection class (java.util.Vector,
  java.util.ArrayList, java.util.List, java.util.Collection,
  com.sun.java.util.ArrayList, com.sun.java.util.List, or
  com.sun.java.util.Collection instance), though if supplied in this case they
  will override the default handling. The direct child components of a
  collection may not use property definitions except for the type attribute.
-->

<!ELEMENT collection (value|structure|collection)*>
  <!ATTLIST collection
    load-method CDATA   #IMPLIED
    size-method CDATA   #IMPLIED
    store-method CDATA  #IMPLIED
    add-method  CDATA   #IMPLIED
    iter-method CDATA   #IMPLIED
    item-type   CDATA   #IMPLIED
    %style-attribute;
    %name-attributes;
    %property-attributes;
    %structure-attributes;
  >