XmlAdapter (Java EE 5)

使用：

一些 Java 类型不能自然映射到 XML 表示形式，例如，HashMap 或其他非 JavaBean 类。反之，XML 表示形式可以映射到 Java 类型，但是应用程序可能会选择使用另一种 Java 类型访问 XML 表示形式。例如，默认情况下，Java 绑定规则模式将 xs:DateTime 绑定到 XmlGregorianCalendar。但应用程序可能需要将 xs:DateTime 绑定到自定义类型，例如 MyXmlGregorianCalendar。在这两种情况下，应用程序用来访问 XML 内容的 bound 类型 与映射到 XML 表示形式的 value 类型 不匹配。

此抽象类定义将 bound 类型修改为 value 类型或将 value 类型修改为 bound 类型的方法。在编组或解组过程中，由 JAXB 绑定框架调用这些方法：

• XmlAdapter.marshal(...)：编组过程中，JAXB 绑定框架调用 XmlAdapter.marshal(..) 将 bound 类型修改为 value 类型，然后将 value 类型编组为 XML 表示形式。
• XmlAdapter.unmarshal(...)：解组过程中，JAXB 绑定框架首先将 XML 表示形式解组为 value 类型，然后调用 XmlAdapter.unmarshal(..) 将 value 类型修改为 bound 类型。

• 编写实现此抽象类的适配器。
• 安装使用注释 XmlJavaTypeAdapter 的适配器。

示例：自定义 HashMap 的映射。

以下示例演示了如何使用 @XmlAdapter 和 @XmlJavaTypeAdapter 自定义 HashMap 的映射。

步骤 1：确定 HashMap 需要的 XML 表示形式。

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

步骤 2：确定上文所示的所需 XML 表示形式应当遵循的模式定义。

     
<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>

 

步骤 3：编写能够生成上述模式定义的 value 类型。

     public class MyHashMapType {
         List<MyHashMapEntryType> entry;
     }

     public class MyHashMapEntryType {
         @XmlAttribute
         public Integer key; 

         @XmlValue
         public String value;
     }
 

步骤 4：编写将 value 类型 (MyHashMapType) 修改为 bound 类型（应用程序使用的 HashMap）的适配器。

public final class MyHashMapAdapter extends
XmlAdapter<HashMap, MyHashMapType> { ... } }
      
 

步骤 5：使用适配器。

     public class Foo {
         @XmlJavaTypeAdapter(MyHashMapAdapter.class)
         HashMap hashmap;
         ...
     }
 

<xs:complexType name="Foo">
<xs:sequence>
<xs:element name="hashmap" type="myHashMapType"
</xs:sequence>
</xs:complexType>
 

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.

• 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<HashMap, MyHashMapType> { ... }
      
 

Step 5: Use the adapter.

     public class Foo {
         @XmlJavaTypeAdapter(MyHashMapAdapter.class)
         HashMap hashmap;
         ...
     }
 

     <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

protected XmlAdapter()
派生类的构造方法，不执行任何操作。

英文文档：

XmlAdapter

protected XmlAdapter()

Do-nothing constructor for the derived classes.

英文文档：

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.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.