Home » xml-commons-external-1.4.01-src » javax » xml » bind » annotation » adapters » [javadoc | source]
abstract public class: XmlAdapter [javadoc | source]

Direct Known Subclasses:
    NormalizedStringAdapter, HexBinaryAdapter, CollapsedStringAdapter

Adapts a Java type for custom marshaling.


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.

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

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

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

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

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

    public class MyHashMapType {
        List<MyHashMapEntryType> entry;

    public class MyHashMapEntryType {
        public Integer key;

        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 {
        HashMap hashmap;
The above code fragment will map to the following schema:
    <xs:complexType name="Foo">
        <xs:element name="hashmap" type="myHashMapType"
 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.