JAXB v2.2.4

## javax.xml.bind.annotation.adapters
Class XmlAdapter<ValueType,BoundType>

    java.lang.Object
      javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType>

Type Parameters:
  `BoundType` - The type that JAXB doesn't know how to handle. An adapter is written to allow this type to be used as an in-memory representation through the `ValueType`.
  `ValueType` - The type that JAXB knows how to handle out of the box.

Direct Known Subclasses:
  CollapsedStringAdapter, HexBinaryAdapter, NormalizedStringAdapter

    public abstract class XmlAdapter<ValueType,BoundType>

extends Object

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:

- XmlAdapter.marshal(...): During marshalling, JAXB binding framework invokes XmlAdapter.marshal(..) to adapt a bound type to value type, which is then marshaled to XML representation.
- XmlAdapter.unmarshal(...): During unmarshalling, JAXB binding framework first unmarshals XML representation to a value type and then invokes XmlAdapter.unmarshal(..) to adapt the value type to a bound type.

Writing an adapter therefore involves the following steps:

- Write an adapter that implements this abstract class.
- Install the adapter using the annotation `XmlJavaTypeAdapter`

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>

Since:
  JAXB 2.0
Author:
  - Sekhar Vajjhala, Sun Microsystems Inc.
  - Kohsuke Kawaguchi, Sun Microsystems Inc.
See Also:
  `XmlJavaTypeAdapter`

Constructor Summary
`protected` `XmlAdapter()` Do-nothing constructor for the derived classes.

Method Summary
`abstract ValueType` `marshal(BoundType v)` Convert a bound type to a value type.
`abstract BoundType` `unmarshal(ValueType v)` Convert a value type to a bound type.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XmlAdapter

    protected XmlAdapter()

  Do-nothing constructor for the derived classes.

Method Detail

### unmarshal

    public abstract BoundType unmarshal(ValueType v)
                                 throws Exception

  Convert a value type to a bound type.

  Parameters:
    `v` - The value to be converted. Can be null.
  Throws:
    `Exception` - if there's an error during the conversion. The caller is responsible for reporting the error to the user through `ValidationEventHandler`.

### marshal

    public abstract ValueType marshal(BoundType v)
                               throws Exception

  Convert a bound type to a value type.

  Parameters:
    `v` - The value to be convereted. Can be null.
  Throws:
    `Exception` - if there's an error during the conversion. The caller is responsible for reporting the error to the user through `ValidationEventHandler`.

JAXB v2.2.4

Comments to: spec-comments@jsr222.java.net
More information at: http://jaxb.java.net

Copyright © 2004-2011 Oracle