Save This Page
Home » xml-commons-external-1.4.01-src » javax » xml » bind » annotation » adapters » [javadoc | source]
javax.xml.bind.annotation.adapters
abstract public class: XmlAdapter [javadoc | source]
java.lang.Object
   javax.xml.bind.annotation.adapters.XmlAdapter

Direct Known Subclasses:
    NormalizedStringAdapter, HexBinaryAdapter, CollapsedStringAdapter

Adapts a Java type for custom marshaling.

Usage:

Some Java types do not map naturally to a XML representation, for example HashMap or other non JavaBean classes. Conversely, a XML repsentation may map to a Java type but an application may choose to accesss the XML representation using another Java type. For example, the schema to Java binding rules bind xs:DateTime by default to XmlGregorianCalendar. But an application may desire to bind xs:DateTime to a custom type, MyXmlGregorianCalendar, for example. In both cases, there is a mismatch between bound type , used by an application to access XML content and the value type, that is mapped to an XML representation.

This abstract class defines methods for adapting a bound type to a value type or vice versa. The methods are invoked by the JAXB binding framework during marshaling and unmarshalling:

Writing an adapter therefore involves the following steps:

Example: Customized mapping of HashMap

The following example illustrates the use of @XmlAdapter and @XmlJavaTypeAdapter to customize the mapping of a HashMap.

Step 1: Determine the desired XML representation for HashMap.

    <hashmap>
        <entry key="id123">this is a value</entry>
        <entry key="id312">this is another value</entry>
        ...
      </hashmap>

Step 2: Determine the schema definition that the desired XML representation shown above should follow.


    <xs:complexType name="myHashMapType">
      <xs:sequence>
        <xs:element name="entry" type="myHashMapEntryType"
                       minOccurs = "0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>

    <xs:complexType name="myHashMapEntryType">
      <xs:simpleContent>
        <xs:extension base="xs:string">
          <xs:attribute name="key" type="xs:int"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>

Step 3: Write value types that can generate the above schema definition.

    public class MyHashMapType {
        List<MyHashMapEntryType> entry;
    }

    public class MyHashMapEntryType {
        @XmlAttribute
        public Integer key;

        @XmlValue
        public String value;
    }

Step 4: Write the adapter that adapts the value type, MyHashMapType to a bound type, HashMap, used by the application.

    public final class MyHashMapAdapter extends
                       XmlAdapter<MyHashMapType,HashMap> { ... }

Step 5: Use the adapter.

    public class Foo {
        @XmlJavaTypeAdapter(MyHashMapAdapter.class)
        HashMap hashmap;
        ...
    }
The above code fragment will map to the following schema:
    <xs:complexType name="Foo">
      <xs:sequence>
        <xs:element name="hashmap" type="myHashMapType"
      </xs:sequence>
    </xs:complexType>
Constructor:
 protected XmlAdapter() 
Method from javax.xml.bind.annotation.adapters.XmlAdapter Summary:
marshal,   unmarshal
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from javax.xml.bind.annotation.adapters.XmlAdapter Detail:
 abstract public ValueType marshal(BoundType v) throws Exception
    Convert a bound type to a value type.
 abstract public BoundType unmarshal(ValueType v) throws Exception
    Convert a value type to a bound type.