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: + * + *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 + * + * // Example: code fragment corresponding to XML input + * JAXBElement+ * + *o = + * (JAXBElement )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 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".
+ *
+ * @see XmlRegistry
+ * @since JAXB 2.0
+ */
+@Retention(RUNTIME)
+@Target({METHOD})
+public @interface XmlElementDecl {
+ /**
+ * scope of the mapping.
+ *
+ * + * If this is not {@link XmlElementDecl.GLOBAL}, then this element + * declaration mapping is only active within the specified class. + */ + Class scope() default GLOBAL.class; + + /** + * 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 #name() + */ + String namespace() default "##default"; + + /** + * 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 #namespace() + */ + String name(); + + /** + * 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 {@link + * XmlRegistry }, is mapped. + *
+ * If susbtitutionHeadName() is not "" and the value is + * not "##default", then the value is the namespace name. + * + * @see #substitutionHeadName() + */ + String substitutionHeadNamespace() default "##default"; + + /** + * 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 #substitutionHeadNamespace() + */ + String substitutionHeadName() default ""; + + /** + * Default value of this element. + * + *
+ * The
'\u0000'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. + */ + String defaultValue() default "\u0000"; + + /** + * Used in {@link XmlElementDecl#scope()} to + * signal that the declaration is in the global scope. + */ + public final class GLOBAL {} +}