XmlElement (Java EE 5)

@Retention(value=RUNTIME)
@Target(value={FIELD, METHOD})

将 JavaBean 属性映射到派生自属性名称的 XML 元素。

使用

@XmlElement 注释可以与以下程序元素一起使用：

• JavaBean 属性
• 非静态、非瞬态字段
• XmlElements 中的程序元素

使用上受到以下约束的限制：

• 此注释可与以下注释一起使用：XmlID、XmlIDREF、XmlList、XmlSchemaType、XmlValue、XmlAttachmentRef、XmlMimeType、XmlInlineBinaryData、XmlElementWrapper 和 XmlJavaTypeAdapter。
• 如果 JavaBean 属性的类型是数组的 collection 类型、索引 (indexed) 属性或参数化列表，并且此注释与 XmlElements 一起使用，那么 @XmlElement.type() 在 collection 项类型已知的情况下必须是 DEFAULT.class。

在使用 @XmlElement 注释进行注释时，JavaBean 属性被映射到 XML 模式复杂类型中的本地元素，包含的类被映射到此 XML 模式复杂类型。

示例 1：将 public 非 static 非 final 字段映射到本地元素。

     //Example: Code fragment
     public class USPrice {
         @XmlElement(name="itemprice")
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice"/>
       <xs:sequence>
         <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
       </sequence>
     </xs:complexType>
   

示例 2：将字段映射到 nillable 元素。

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
       </sequence>
     </xs:complexType>
   

示例 3：将字段映射到 nillable、required 元素。

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true, required=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
       </sequence>
     </xs:complexType>
   

示例 4：将 JavaBean 属性映射到具有匿名类型的 XML 元素。

请参见 @XmlType 中的示例 6。

since	JAXB2.0
version	en $Revision: 1.19 $

英文文档：

Maps a JavaBean property to a XML element derived from property name.

Usage

@XmlElement annotation can be used with the following program elements:

• a JavaBean property
• non static, non transient field
• within XmlElements

The usage is subject to the following constraints:

• This annotation can be used with following annotations: XmlID, XmlIDREF, XmlList, XmlSchemaType, XmlValue, XmlAttachmentRef, XmlMimeType, XmlInlineBinaryData, XmlElementWrapper, XmlJavaTypeAdapter
• if the type of JavaBean property is a collection type of array, an indexed property, or a parameterized list, and this annotation is used with XmlElements then, @XmlElement.type() must be DEFAULT.class since the collection item type is already known.

A JavaBean property, when annotated with @XmlElement annotation is mapped to a local element in the XML Schema complex type to which the containing class is mapped.

Example 1: Map a public non static non final field to local element

     //Example: Code fragment
     public class USPrice {
         @XmlElement(name="itemprice")
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice"/>
       <xs:sequence>
         <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
       </sequence>
     </xs:complexType>
   

Example 2: Map a field to a nillable element.

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
       </sequence>
     </xs:complexType>
   

Example 3: Map a field to a nillable, required element.

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true, required=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
       </sequence>
     </xs:complexType>
   

Example 4: Map a JavaBean property to an XML element with anonymous type.

See Example 6 in @XmlType.

Since:

JAXB2.0

Version:

$Revision: 1.19 $

Author:

Sekhar Vajjhala, Sun Microsystems, Inc.

---

Optional Element Summary
String	defaultValue           Default value of this element.
String	name           Name of the XML Schema element.
String	namespace           XML target namespace of the XML Schema element.
boolean	nillable           Customize the element declaration to be nillable.
boolean	required           Customize the element declaration to be required.
Class	type           The Java class being referenced.

 

abstract public String name()
XML 模式元素的名称。

如果值为 "##default"，那么元素名称派生于 JavaBean 属性名称。

英文文档：

name

public abstract String name

Name of the XML Schema element.

If the value is "##default", then element name is derived from the JavaBean property name.

Default:

"##default"

---

abstract public boolean nillable()
将元素声明自定义为 nillable。

如果 nillable() 为 true，那么 JavaBean 属性被映射到 XML 模式 nillable 元素声明。

英文文档：

nillable

public abstract boolean nillable

Customize the element declaration to be nillable.

If nillable() is true, then the JavaBean property is mapped to a XML Schema nillable element declaration.

Default:

false

---

abstract public boolean required()
自定义所需的元素声明。

如果 required() 为 true，则将 Javabean 属性映射到一个 minOccurs="1" 的 XML 模式元素声明。maxOccurs 为 "1" 表示单个赋值的属性，maxOccurs 为 "unbounded" 则表示多个赋值的属性。

如果 required() 为 false，则将 Javabean 属性映射到一个 minOccurs="0" 的 XML 模式元素声明。maxOccurs 为 "1" 表示单个赋值的属性，maxOccurs 为 "unbounded" 则表示多个赋值的属性。

英文文档：

required

public abstract boolean required

Customize the element declaration to be required.

If required() is true, then Javabean property is mapped to an XML schema element declaration with minOccurs="1". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

If required() is false, then the Javabean property is mapped to XML Schema element declaration with minOccurs="0". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

Default:

false

---

abstract public String namespace()
XML 模式元素的 XML 目标名称空间。

如果该值为 "##default"，则名称空间通过以下方式确定：

1. 如果封闭包中包含 XmlSchema 注释，并且其 elementFormDefault 为 QUALIFIED，则名称空间为封闭类的名称空间。
2. 否则名称空间为 ""（这将导致在默认名称空间中生成非限定元素）。

英文文档：

namespace

public abstract String namespace

XML target namespace of the XML Schema element.

If the value is "##default", then the namespace is determined as follows:

1. If the enclosing package has XmlSchema annotation, and its elementFormDefault is QUALIFIED, then the namespace of the enclosing class.
2. Otherwise "" (which produces unqualified element in the default namespace.

Default:

"##default"

---

abstract public String defaultValue()
此元素的默认值。

作为此注释元素的默认值指定的 '' 值被用作 null 的替代，从而允许识别 'no default value' 状态。

英文文档：

defaultValue

public abstract String defaultValue

Default value of this element.

The '' value specified as a default of this annotation element is used as a poor-man's substitute for null to allow implementations to recognize the 'no default value' state.

Default:

"\u0000"

---

abstract public Class<T> type()
正被引用的 Java 类。

英文文档：

type

public abstract Class type

The Java class being referenced.

Default:

javax.xml.bind.annotation.XmlElement.DEFAULT.class

---

Overview  Package   Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: REQUIRED | OPTIONAL	DETAIL: ELEMENT

---

Submit a bug or feature

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