001: /*
002: * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind.annotation;
007:
008: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
009: import java.lang.annotation.Retention;
010: import java.lang.annotation.Target;
011:
012: import static java.lang.annotation.ElementType.*;
013: import static java.lang.annotation.RetentionPolicy.*;
014:
015: /**
016: * Maps a JavaBean property to a XML element derived from property name.
017: *
018: * <p> <b>Usage</b> </p>
019: * <p>
020: * </tt>@XmlElement</tt> annotation can be used with the following program
021: * elements:
022: * <ul>
023: * <li> a JavaBean property </li>
024: * <li> non static, non transient field </li>
025: * <li> within {@link XmlElements}
026: * <p>
027: *
028: * </ul>
029: *
030: * The usage is subject to the following constraints:
031: * <ul>
032: * <li> This annotation can be used with following annotations:
033: * {@link XmlID},
034: * {@link XmlIDREF},
035: * {@link XmlList},
036: * {@link XmlSchemaType},
037: * {@link XmlValue},
038: * {@link XmlAttachmentRef},
039: * {@link XmlMimeType},
040: * {@link XmlInlineBinaryData},
041: * {@link XmlElementWrapper},
042: * {@link XmlJavaTypeAdapter}</li>
043: * <li> if the type of JavaBean property is a collection type of
044: * array, an indexed property, or a parameterized list, and
045: * this annotation is used with {@link XmlElements} then,
046: * <tt>@XmlElement.type()</tt> must be DEFAULT.class since the
047: * collection item type is already known. </li>
048: * </ul>
049: *
050: * <p>
051: * A JavaBean property, when annotated with @XmlElement annotation
052: * is mapped to a local element in the XML Schema complex type to
053: * which the containing class is mapped.
054: *
055: * <p>
056: * <b>Example 1: </b> Map a public non static non final field to local
057: * element
058: * <pre>
059: * //Example: Code fragment
060: * public class USPrice {
061: * @XmlElement(name="itemprice")
062: * public java.math.BigDecimal price;
063: * }
064: *
065: * <!-- Example: Local XML Schema element -->
066: * <xs:complexType name="USPrice"/>
067: * <xs:sequence>
068: * <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
069: * </sequence>
070: * </xs:complexType>
071: * </pre>
072: * <p>
073: *
074: * <b> Example 2: </b> Map a field to a nillable element.
075: * <pre>
076: *
077: * //Example: Code fragment
078: * public class USPrice {
079: * @XmlElement(nillable=true)
080: * public java.math.BigDecimal price;
081: * }
082: *
083: * <!-- Example: Local XML Schema element -->
084: * <xs:complexType name="USPrice">
085: * <xs:sequence>
086: * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
087: * </sequence>
088: * </xs:complexType>
089: * </pre>
090: * <p>
091: * <b> Example 3: </b> Map a field to a nillable, required element.
092: * <pre>
093: *
094: * //Example: Code fragment
095: * public class USPrice {
096: * @XmlElement(nillable=true, required=true)
097: * public java.math.BigDecimal price;
098: * }
099: *
100: * <!-- Example: Local XML Schema element -->
101: * <xs:complexType name="USPrice">
102: * <xs:sequence>
103: * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
104: * </sequence>
105: * </xs:complexType>
106: * </pre>
107: * <p>
108: *
109: * <p> <b>Example 4: </b>Map a JavaBean property to an XML element
110: * with anonymous type.</p>
111: * <p>
112: * See Example 6 in @{@link XmlType}.
113: *
114: * <p>
115: * @author Sekhar Vajjhala, Sun Microsystems, Inc.
116: * @since JAXB2.0
117: * @version $Revision: 1.19 $
118: */
119:
120: @Retention(RUNTIME)
121: @Target({FIELD,METHOD})
122: public @interface XmlElement {
123: /**
124: * Name of the XML Schema element.
125: * <p> If the value is "##default", then element name is derived from the
126: * JavaBean property name.
127: */
128: String name() default "##default";
129:
130: /**
131: * Customize the element declaration to be nillable.
132: * <p>If nillable() is true, then the JavaBean property is
133: * mapped to a XML Schema nillable element declaration.
134: */
135: boolean nillable() default false;
136:
137: /**
138: * Customize the element declaration to be required.
139: * <p>If required() is true, then Javabean property is mapped to
140: * an XML schema element declaration with minOccurs="1".
141: * maxOccurs is "1" for a single valued property and "unbounded"
142: * for a multivalued property.
143: * <p>If required() is false, then the Javabean property is mapped
144: * to XML Schema element declaration with minOccurs="0".
145: * maxOccurs is "1" for a single valued property and "unbounded"
146: * for a multivalued property.
147: */
148:
149: boolean required() default false;
150:
151: /**
152: * XML target namespace of the XML Schema element.
153: * <p>
154: * If the value is "##default", then the namespace is determined
155: * as follows:
156: * <ol>
157: * <li>
158: * If the enclosing package has {@link XmlSchema} annotation,
159: * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
160: * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
161: * the enclosing class.
162: *
163: * <li>
164: * Otherwise "" (which produces unqualified element in the default
165: * namespace.
166: * </ol>
167: */
168: String namespace() default "##default";
169:
170: /**
171: * Default value of this element.
172: *
173: * <p>
174: * The '\u0000' value specified as a default of this annotation element
175: * is used as a poor-man's substitute for null to allow implementations
176: * to recognize the 'no default value' state.
177: */
178: String defaultValue() default "\u0000";
179:
180: /**
181: * The Java class being referenced.
182: */
183: Class type() default DEFAULT.class;
184:
185: /**
186: * Used in {@link XmlElement#type()} to
187: * signal that the type be inferred from the signature
188: * of the property.
189: */
190: static final class DEFAULT {
191: }
192: }
|