https://github.com/eclipse-ee4j/jaxb-api/jakarta.xml.bind-api: Jakarta XML Binding API (Eclipse Foundation)
  • Roman Grigoriadi (Oracle Corporation) 
/*
 * Copyright (c) 2004, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package javax.xml.bind.annotation.adapters;


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>



Author:
  • Sekhar Vajjhala, Sun Microsystems Inc.
    •  
  •  Kohsuke Kawaguchi, Sun Microsystems Inc.
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.
See Also:
Since:1.6, JAXB 2.0
/**
 * Adapts a Java type for custom marshaling.
 *
 * <p> <b> Usage: </b> </p>
 *
 * <p>
 * Some Java types do not map naturally to an XML representation, for
 * example {@code 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 <i> bound type </i>, used by an application to
 * access XML content and the <i> value type</i>, that is mapped to an
 * XML representation.  
 *
 * <p>
 * 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:
 *
 * <ul>
 *   <li> <b> XmlAdapter.marshal(...): </b> During marshalling, JAXB
 *        binding framework invokes XmlAdapter.marshal(..) to adapt a
 *        bound type to value type, which is then marshaled to XML 
 *        representation. </li> 
 *
 *   <li> <b> XmlAdapter.unmarshal(...): </b> 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. </li> 
 * </ul>
 *
 * Writing an adapter therefore involves the following steps:
 * 
 * <ul>
 *   <li> Write an adapter that implements this abstract class. </li>
 *   <li> Install the adapter using the annotation {@link
 *        XmlJavaTypeAdapter} </li>
 * </ul>
 *
 * <p><b>Example:</b> Customized mapping of {@code HashMap}</p>
 * <p> The following example illustrates the use of 
 * {@code @XmlAdapter} and {@code @XmlJavaTypeAdapter} to
 * customize the mapping of a {@code HashMap}.
 *
 * <p> <b> Step 1: </b> Determine the desired XML representation for HashMap.
 *
 * <pre>{@code
 *     <hashmap>
 *         <entry key="id123">this is a value</entry>
 *         <entry key="id312">this is another value</entry>
 *         ...
 *     </hashmap>
 * }</pre>
 *
 * <p> <b> Step 2: </b> Determine the schema definition that the
 * desired XML representation shown above should follow.
 *
 * <pre>{@code
 *     
 *     <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>
 *
 * }</pre>
 *
 * <p> <b> Step 3: </b> Write value types that can generate the above
 * schema definition.
 *
 * <pre>
 *     public class MyHashMapType {
 *         List&lt;MyHashMapEntryType&gt; entry;
 *     }
 *
 *     public class MyHashMapEntryType {
 *         &#64;XmlAttribute
 *         public Integer key; 
 *
 *         &#64;XmlValue
 *         public String value;
 *     }
 * </pre>
 * 
 * <p> <b> Step 4: </b> Write the adapter that adapts the value type,
 * MyHashMapType to a bound type, HashMap, used by the application.
 *
 * <pre>{@code
 *     public final class MyHashMapAdapter extends
 *                        XmlAdapter<MyHashMapType,HashMap> { ... }
 *      
 * }</pre>
 *
 * <p> <b> Step 5: </b> Use the adapter.
 *
 * <pre>
 *     public class Foo {
 *         &#64;XmlJavaTypeAdapter(MyHashMapAdapter.class)
 *         HashMap hashmap;
 *         ...
 *     }
 * </pre>
 *
 * The above code fragment will map to the following schema:
 * 
 * <pre>{@code
 *     <xs:complexType name="Foo">
 *       <xs:sequence>
 *         <xs:element name="hashmap" type="myHashMapType">
 *       </xs:sequence>
 *     </xs:complexType>
 * }</pre>
 *
 * @param <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 {@code ValueType}.
 * @param <ValueType>
 *      The type that JAXB knows how to handle out of the box.
 *
 * @author <ul><li>Sekhar Vajjhala, Sun Microsystems Inc.</li> <li> Kohsuke Kawaguchi, Sun Microsystems Inc.</li></ul>
 * @see XmlJavaTypeAdapter
 * @since 1.6, JAXB 2.0
 */
public abstract class XmlAdapter<ValueType,BoundType> {

    
Do-nothing constructor for the derived classes.

/**
     * Do-nothing constructor for the derived classes.
     */
    protected XmlAdapter() {}

    
Convert a value type to a bound type.

Params:
  • v – 
     The value to be converted. Can be null.
Throws:
/**
     * Convert a value type to a bound type.
     *
     * @param 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 {@link javax.xml.bind.ValidationEventHandler}.
     */
    public abstract BoundType unmarshal(ValueType v) throws Exception;

    
Convert a bound type to a value type.

Params:
  • v – 
     The value to be convereted. Can be null.
Throws:
/**
     * Convert a bound type to a value type.
     *
     * @param 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 {@link javax.xml.bind.ValidationEventHandler}.
     */
    public abstract ValueType marshal(BoundType v) throws Exception;
}