< prev index next >
src/java.xml.bind/share/classes/javax/xml/bind/annotation/XmlElementRef.java
Print this page
*** 37,47 ****
* <p>
* Maps a JavaBean property to a XML element derived from property's type.
* <p>
* <b>Usage</b>
* <p>
! * <tt>@XmlElementRef</tt> annotation can be used with a
* JavaBean property or from within {@link XmlElementRefs}
* <p>
* This annotation dynamically associates an XML element name with the JavaBean
* property. When a JavaBean property is annotated with {@link
* XmlElement}, the XML element name is statically derived from the
--- 37,47 ----
* <p>
* Maps a JavaBean property to a XML element derived from property's type.
* <p>
* <b>Usage</b>
* <p>
! * {@code @XmlElementRef} annotation can be used with a
* JavaBean property or from within {@link XmlElementRefs}
* <p>
* This annotation dynamically associates an XML element name with the JavaBean
* property. When a JavaBean property is annotated with {@link
* XmlElement}, the XML element name is statically derived from the
*** 60,82 ****
* public void setTerm(JAXBElement<? extends Operator>);
* public JAXBElement<? extends Operator> getTerm();
* }</pre>
* <p>
* An element factory method annotated with {@link XmlElementDecl} is
! * used to create a <tt>JAXBElement</tt> instance, containing an XML
! * element name. The presence of @XmlElementRef annotation on an
! * element property indicates that the element name from <tt>JAXBElement</tt>
* instance be used instead of deriving an XML element name from the
* JavaBean property name.
*
* <p>
* The usage is subject to the following constraints:
* <ul>
* <li> If the collection item type (for collection property) or
* property type (for single valued property) is
* {@link javax.xml.bind.JAXBElement}, then
! * <tt>@XmlElementRef}.name()</tt> and <tt>@XmlElementRef.namespace()</tt> must
* point an element factory method with an @XmlElementDecl
* annotation in a class annotated with @XmlRegistry (usually
* ObjectFactory class generated by the schema compiler) :
* <ul>
* <li> @XmlElementDecl.name() must equal @XmlElementRef.name() </li>
--- 60,82 ----
* public void setTerm(JAXBElement<? extends Operator>);
* public JAXBElement<? extends Operator> getTerm();
* }</pre>
* <p>
* An element factory method annotated with {@link XmlElementDecl} is
! * used to create a {@code JAXBElement} instance, containing an XML
! * element name. The presence of {@code @XmlElementRef} annotation on an
! * element property indicates that the element name from {@code JAXBElement}
* instance be used instead of deriving an XML element name from the
* JavaBean property name.
*
* <p>
* The usage is subject to the following constraints:
* <ul>
* <li> If the collection item type (for collection property) or
* property type (for single valued property) is
* {@link javax.xml.bind.JAXBElement}, then
! * {@code @XmlElementRef.name()} and {@code @XmlElementRef.namespace()} must
* point an element factory method with an @XmlElementDecl
* annotation in a class annotated with @XmlRegistry (usually
* ObjectFactory class generated by the schema compiler) :
* <ul>
* <li> @XmlElementDecl.name() must equal @XmlElementRef.name() </li>
*** 153,163 ****
* ....
* </javac>
* </target>
* }</pre>
* <p>
! * It is not an error to have a class that extends <tt>Task</tt>
* that doesn't have {@link XmlRootElement}. But they can't show up in an
* XML instance (because they don't have XML element names).
*
* <p><b>Example 2: XML Schema Susbstitution group support</b>
* <p> The following example shows the annotations for XML Schema
--- 153,163 ----
* ....
* </javac>
* </target>
* }</pre>
* <p>
! * It is not an error to have a class that extends {@code Task}
* that doesn't have {@link XmlRootElement}. But they can't show up in an
* XML instance (because they don't have XML element names).
*
* <p><b>Example 2: XML Schema Susbstitution group support</b>
* <p> The following example shows the annotations for XML Schema
*** 232,257 ****
/**
* This parameter and {@link #name()} are used to determine the
* XML element for the JavaBean property.
*
! * <p> If <tt>type()</tt> is <tt>JAXBElement.class</tt> , then
! * <tt>namespace()</tt> and <tt>name()</tt>
* point to a factory method with {@link XmlElementDecl}. The XML
* element name is the element name from the factory method's
* {@link XmlElementDecl} annotation or if an element from its
* substitution group (of which it is a head element) has been
* substituted in the XML document, then the element name is from the
* {@link XmlElementDecl} on the substituted element.
*
! * <p> If {@link #type()} is not <tt>JAXBElement.class</tt>, then
* the XML element name is the XML element name statically
* associated with the type using the annotation {@link
* XmlRootElement} on the type. If the type is not annotated with
* an {@link XmlElementDecl}, then it is an error.
*
! * <p> If <tt>type()</tt> is not <tt>JAXBElement.class</tt>, then
* this value must be "".
*
*/
String namespace() default "";
/**
--- 232,257 ----
/**
* This parameter and {@link #name()} are used to determine the
* XML element for the JavaBean property.
*
! * <p> If {@code type()} is {@code JAXBElement.class} , then
! * {@code namespace()} and {@code name()}
* point to a factory method with {@link XmlElementDecl}. The XML
* element name is the element name from the factory method's
* {@link XmlElementDecl} annotation or if an element from its
* substitution group (of which it is a head element) has been
* substituted in the XML document, then the element name is from the
* {@link XmlElementDecl} on the substituted element.
*
! * <p> If {@link #type()} is not {@code JAXBElement.class}, then
* the XML element name is the XML element name statically
* associated with the type using the annotation {@link
* XmlRootElement} on the type. If the type is not annotated with
* an {@link XmlElementDecl}, then it is an error.
*
! * <p> If {@code type()} is not {@code JAXBElement.class}, then
* this value must be "".
*
*/
String namespace() default "";
/**
*** 280,290 ****
* to XML Schema element declaration with minOccurs="0".
* maxOccurs is "1" for a single valued property and "unbounded"
* for a multivalued property.
*
* <p>
! * For compatibility with JAXB 2.1, this property defaults to <tt>true</tt>,
* despite the fact that {@link XmlElement#required()} defaults to false.
*
* @since 1.7, JAXB 2.2
*/
boolean required() default true;
--- 280,290 ----
* to XML Schema element declaration with minOccurs="0".
* maxOccurs is "1" for a single valued property and "unbounded"
* for a multivalued property.
*
* <p>
! * For compatibility with JAXB 2.1, this property defaults to {@code true},
* despite the fact that {@link XmlElement#required()} defaults to false.
*
* @since 1.7, JAXB 2.2
*/
boolean required() default true;
< prev index next >