XmlAdapter (Java SE 10 & JDK 10 )
Keywords: javax.xml.bind.annotation.adapters.XmlAdapter class

Module java.xml.bind
Package 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 an XML representation, for example `HashMap` or other non JavaBean classes. Conversely, an XML representation may map to a Java type but an application may choose to access 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:
    1.6, JAXB 2.0
  See Also:
    `XmlJavaTypeAdapter`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XmlAdapter()` | Do-nothing constructor for the derived classes.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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 declared in 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`.