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>)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"/>
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 name="bar" type="xs:string"/>
</xs:choice>
</xs:complexType>
<xs:element name="foo" type="xs:int"/>
</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<String> createPeaFoo(String s);
@XmlElementDecl(scope=Pea.class,name="bar")
JAXBElement<String> createPeaBar(String s);
@XmlElementDecl(name="foo")
JAXBElement<Integer> createFoo(Integer i);
}
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Used inscope()
to signal that the declaration is in the global scope. -
Required Element Summary
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionDefault value of this element.namespace name of the XML element.Class
<?> scope of the mapping.XML local name of a substitution group's head element.namespace name of a substitution group's head XML element.
-
Element Details
-
scope
Class<?> scopescope of the mapping.If this is not
XmlElementDecl.GLOBAL
, then this element declaration mapping is only active within the specified class.- Default:
jakarta.xml.bind.annotation.XmlElementDecl.GLOBAL.class
-
namespace
String namespacenamespace 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:
- Default:
"##default"
-
name
String namelocal 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:
-
substitutionHeadNamespace
String substitutionHeadNamespacenamespace 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
substitutionHeadName()
is "", then this value can only be "##default". But the value is ignored since this element is not part of substitution group when the value ofsubstitutionHeadName()
is "".If
substitutionHeadName()
is not "" and the value is "##default", then the namespace name is the namespace name to which the package of the containing class, marked withXmlRegistry
, is mapped.If
substitutionHeadName()
is not "" and the value is not "##default", then the value is the namespace name.- See Also:
- Default:
"##default"
-
substitutionHeadName
String substitutionHeadNameXML 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:
- Default:
""
-
defaultValue
String defaultValueDefault 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"
-