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 theValueType.ValueType- The type that JAXB knows how to handle out of the box.
- Direct Known Subclasses:
CollapsedStringAdapter,HexBinaryAdapter,LinkAdapter,NormalizedStringAdapter,ReferenceAdapter,ReferenceAdapterV2,RelationshipLinkAdapter,RestCollectionAdapter
public abstract class XmlAdapter<ValueType,BoundType> extends java.lang.ObjectAdapts a Java type for custom marshaling.Usage:
Some Java types do not map naturally to an XML representation, for example
HashMapor 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.
- Write an adapter that implements this abstract class.
- Install the adapter using the annotation
XmlJavaTypeAdapter
Example: Customized mapping of
HashMapThe following example illustrates the use of
@XmlAdapterand@XmlJavaTypeAdapterto customize the mapping of aHashMap.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>- See Also:
XmlJavaTypeAdapter- Author:
- Sekhar Vajjhala, Sun Microsystems Inc.
- Kohsuke Kawaguchi, Sun Microsystems Inc.
- Since:
- 1.6, JAXB 2.0
-
-
Constructor Summary
Constructors Modifier Constructor Description protectedXmlAdapter()Do-nothing constructor for the derived classes.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description abstract ValueTypemarshal(BoundType v)Convert a bound type to a value type.abstract BoundTypeunmarshal(ValueType v)Convert a value type to a bound type.
-
-
-
Method Detail
-
unmarshal
public abstract BoundType unmarshal(ValueType v) throws java.lang.Exception
Convert a value type to a bound type.- Parameters:
v- The value to be converted. Can be null.- Throws:
java.lang.Exception- if there's an error during the conversion. The caller is responsible for reporting the error to the user throughValidationEventHandler.
-
marshal
public abstract ValueType marshal(BoundType v) throws java.lang.Exception
Convert a bound type to a value type.- Parameters:
v- The value to be convereted. Can be null.- Throws:
java.lang.Exception- if there's an error during the conversion. The caller is responsible for reporting the error to the user throughValidationEventHandler.
-
-