XmlElementDecl (Java EE 5)

@Retention(value=RUNTIME)
@Target(value=METHOD)

将工厂方法映射到 XML 元素。

用法

该注释在 XML 模式元素声明与元素工厂方法之间创建了映射关系，元素工厂方法返回表示元素声明的 JAXBElement 实例。通常，元素工厂方法是根据 Java 包的 ObjectFactory 类中的模式生成（并注解）的，它表示元素声明的目标名称空间的绑定。因此，当注释语法允许在任何方法上使用 @XmlElementDecl 时，从语义上说，它的使用受限于元素工厂方法的注释。 用法受到以下约束的限制：

• 包含使用 @XmlElementDecl 注释的元素工厂方法的类必须使用 XmlRegistry 标记。
• 元素工厂方法必须采用一个可分配给 Object 的参数。

示例 1：工厂方法上的注释

     // Example: code fragment
     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="foo")
         JAXBElement<String> createFoo(String s) { ... }
     }
 

 
     <!-- XML input -->
       <foo>string</foo>

     // Example: code fragment corresponding to XML input
     JAXBElement<string> o =
     (JAXBElement</string><string>)unmarshaller.unmarshal(aboveDocument);
     // print JAXBElement instance to show values
     System.out.println(o.getName());   // prints  "{}foo"
     System.out.println(o.getValue());  // prints  "string"
     System.out.println(o.getValue().getClass()); // prints "java.lang.String"

     <!-- Example: XML schema definition -->
     <xs:element name="foo" type="xs:string">
 </xs:element></string>

示例 2：具有非本地作用域的元素声明

以下示例演示了如何在模式派生代码的元素声明绑定中使用作用域注释参数。

在此 javadoc 以后的版本中可能会替换以下示例。

     <!-- Example: XML schema definition -->
     <xs:schema>
       <xs:complextype name="pea">
         <xs:choice maxoccurs="unbounded">
           <xs:element name="foo" type="xs:string">
           </xs:element><xs:element name="bar" type="xs:string">
         </xs:element></xs:choice>
       </xs:complextype> 
       <xs:element name="foo" type="xs:int">
     </xs:element></xs:schema>
 

     // Example: expected default binding
     class Pea {
         @XmlElementRefs({
             @XmlElementRef(name="foo",type=JAXBElement.class)
             @XmlElementRef(name="bar",type=JAXBElement.class)
         })
         List<JAXBElement<String>> fooOrBar;
     }
 
     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(scope=Pea.class,name="foo")
         JAXBElement createPeaFoo(String s);
 
         @XmlElementDecl(scope=Pea.class,name="bar")
         JAXBElement createPeaBar(String s);
 
         @XmlElementDecl(name="foo")
         JAXBElement createFoo(Integer i);
     }
 
 

没有作用域，createFoo 和 createPeaFoo 将变得不明确，因为它们两个都使用相同的本地名称 "foo" 映射到 XML 模式元素。

since	JAXB 2.0
See also	javax.xml.bind.annotation.XmlRegistry

英文文档：

Maps a factory method to a XML element.

Usage

The annotation creates a mapping between an XML schema element declaration and a element factory method that returns a JAXBElement instance representing the element declaration. Typically, the element factory method is generated (and annotated) from a schema into the ObjectFactory class in a Java package that represents the binding of the element declaration's target namespace. Thus, while the annotation syntax allows @XmlElementDecl to be used on any method, semantically its use is restricted to annotation of element factory method. The usage is subject to the following constraints:

• The class containing the element factory method annotated with @XmlElementDecl must be marked with XmlRegistry.
• The element factory method must take one parameter assignable to Object.

Example 1: Annotation on a factory method

     // Example: code fragment
     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="foo")
         JAXBElement<String> createFoo(String s) { ... }
     }
 

 
     <!-- XML input -->
       <foo>string</foo>

     // Example: code fragment corresponding to XML input
     JAXBElement<string> o =
     (JAXBElement</string><string>)unmarshaller.unmarshal(aboveDocument);
     // print JAXBElement instance to show values
     System.out.println(o.getName());   // prints  "{}foo"
     System.out.println(o.getValue());  // prints  "string"
     System.out.println(o.getValue().getClass()); // prints "java.lang.String"

     <!-- Example: XML schema definition -->
     <xs:element name="foo" type="xs:string">
 </xs:element></string>

Example 2: Element declaration with non local scope

The following example illustrates the use of scope annotation parameter in binding of element declaration in schema derived code.

The following example may be replaced in a future revision of this javadoc.

     <!-- Example: XML schema definition -->
     <xs:schema>
       <xs:complextype name="pea">
         <xs:choice maxoccurs="unbounded">
           <xs:element name="foo" type="xs:string">
           </xs:element><xs:element name="bar" type="xs:string">
         </xs:element></xs:choice>
       </xs:complextype> 
       <xs:element name="foo" type="xs:int">
     </xs:element></xs:schema>
 

     // Example: expected default binding
     class Pea {
         @XmlElementRefs({
             @XmlElementRef(name="foo",type=JAXBElement.class)
             @XmlElementRef(name="bar",type=JAXBElement.class)
         })
         List<JAXBElement<String>> fooOrBar;
     }
 
     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(scope=Pea.class,name="foo")
         JAXBElement createPeaFoo(String s);
 
         @XmlElementDecl(scope=Pea.class,name="bar")
         JAXBElement createPeaBar(String s);
 
         @XmlElementDecl(name="foo")
         JAXBElement createFoo(Integer i);
     }
 
 

Without scope createFoo and createPeaFoo would become ambiguous since both of them map to a XML schema element with the same local name "foo".

Since:

JAXB 2.0

See Also:

XmlRegistry

---

Required Element Summary
String	name           local name of the XML element.

 

Optional Element Summary
String	defaultValue           Default value of this element.
String	namespace           namespace name of the XML element.
Class	scope           scope of the mapping.
String	substitutionHeadName           XML local name of a substitution group's head element.
String	substitutionHeadNamespace           namespace name of a substitution group's head XML element.

 

Element Detail

abstract public String name()
XML 元素的本地名称。

审阅者的注释：没有默认名称；因为注释是在工厂方法上，所以能否从工厂方法名称派生方法名称不是很清楚。

See also

namespace()

英文文档：

name

public abstract String name

local name of the XML element.

Note to reviewers: There is no default name; since the annotation is on a factory method, it is not clear that the method name can be derived from the factory method name.

See Also:

namespace()

abstract public Class<T> scope()
映射的作用域。

如果此值不是 XmlElementDecl.GLOBAL，那么此元素声明映射只有在指定类中才是活动的。

英文文档：

scope

public abstract Class scope

scope of the mapping.

If this is not XmlElementDecl.GLOBAL, then this element declaration mapping is only active within the specified class.

Default:

javax.xml.bind.annotation.XmlElementDecl.GLOBAL.class

---

abstract public String namespace()
XML 元素的名称空间名。

如果值是 "##default"，那么该值是实现包含此工厂方法类的包的名称空间名。

See also

name()

英文文档：

namespace

public abstract String namespace

namespace name of the XML element.

If the value is "##default", then the value is the namespace name for the package of the class containing this factory method.

See Also:

name()

Default:

"##default"

---

abstract public String substitutionHeadNamespace()
替换组的头 XML 元素的名称空间名。

此值指定本地名称由 substitutionHeadName() 指定的 XML 元素的名称空间名。

如果 susbtitutionHeadName() 为 ""，则此值只能是 "##default"。但该值被忽略，因为在 susbstitutionHeadName() 的值是 "" 时，此元素不是替换组的一部分。

如果 susbtitutionHeadName() 不是 ""，并且值为 "##default"，那么名称空间名是包含用 XmlRegistry 标记的类的包所映射到的名称空间名。

如果 susbtitutionHeadName() 不是 "" 并且值不是 "##default"，那么该值是名称空间名。

See also

substitutionHeadName()

英文文档：

substitutionHeadNamespace

public abstract String substitutionHeadNamespace

namespace name of a substitution group's head XML element.

This specifies the namespace name of the XML element whose local name is specified by substitutionHeadName().

If susbtitutionHeadName() is "", then this value can only be "##default". But the value is ignored since since this element is not part of susbtitution group when the value of susbstitutionHeadName() is "".

If susbtitutionHeadName() is not "" and the value is "##default", then the namespace name is the namespace name to which the package of the containing class, marked with XmlRegistry, is mapped.

If susbtitutionHeadName() is not "" and the value is not "##default", then the value is the namespace name.

See Also:

substitutionHeadName()

Default:

"##default"

---

abstract public String substitutionHeadName()
替换组的头元素的 XML 本地名称。

如果值是 ""，那么此元素不是任何替换组的一部分。

See also

substitutionHeadNamespace()

英文文档：

substitutionHeadName

public abstract String substitutionHeadName

XML local name of a substitution group's head element.

If the value is "", then this element is not part of any substitution group.

See Also:

substitutionHeadNamespace()

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"

---

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.