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 java.lang.annotation.Retention;
009: import java.lang.annotation.Target;
010:
011: import static java.lang.annotation.RetentionPolicy.RUNTIME;
012: import static java.lang.annotation.ElementType.METHOD;
013:
014: /**
015: * Maps a factory method to a XML element.
016: *
017: * <p> <b>Usage</b> </p>
018: *
019: * The annotation creates a mapping between an XML schema element
020: * declaration and a <i> element factory method </i> that returns a
021: * JAXBElement instance representing the element
022: * declaration. Typically, the element factory method is generated
023: * (and annotated) from a schema into the ObjectFactory class in a
024: * Java package that represents the binding of the element
025: * declaration's target namespace. Thus, while the annotation syntax
026: * allows @XmlElementDecl to be used on any method, semantically
027: * its use is restricted to annotation of element factory method.
028: *
029: * The usage is subject to the following constraints:
030: *
031: * <ul>
032: * <li> The class containing the element factory method annotated
033: * with @XmlElementDecl must be marked with {@link
034: * XmlRegistry}. </li>
035: * <li> The element factory method must take one parameter
036: * assignable to {@link Object}.</li>
037: * </ul>
038: *
039: * <p><b>Example 1: </b>Annotation on a factory method
040: * <pre>
041: * // Example: code fragment
042: * @XmlRegistry
043: * class ObjectFactory {
044: * @XmlElementDecl(name="foo")
045: * JAXBElement<String> createFoo(String s) { ... }
046: * }
047: * </pre>
048: * <pre><xmp>
049: * <!-- XML input -->
050: * <foo>string</foo>
051: *
052: * // Example: code fragment corresponding to XML input
053: * JAXBElement<String> o =
054: * (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument);
055: * // print JAXBElement instance to show values
056: * System.out.println(o.getName()); // prints "{}foo"
057: * System.out.println(o.getValue()); // prints "string"
058: * System.out.println(o.getValue().getClass()); // prints "java.lang.String"
059: *
060: * <!-- Example: XML schema definition -->
061: * <xs:element name="foo" type="xs:string"/>
062: * </xmp></pre>
063: *
064: * <p><b>Example 2: </b> Element declaration with non local scope
065: * <p>
066: * The following example illustrates the use of scope annotation
067: * parameter in binding of element declaration in schema derived
068: * code.
069: * <p>
070: * The following example may be replaced in a future revision of
071: * this javadoc.
072: *
073: * <pre><xmp>
074: * <!-- Example: XML schema definition -->
075: * <xs:schema>
076: * <xs:complexType name="pea">
077: * <xs:choice maxOccurs="unbounded">
078: * <xs:element name="foo" type="xs:string"/>
079: * <xs:element name="bar" type="xs:string"/>
080: * </xs:choice>
081: * </xs:complexType>
082: * <xs:element name="foo" type="xs:int"/>
083: * </xs:schema>
084: * </xmp></pre>
085: * <pre>
086: * // Example: expected default binding
087: * class Pea {
088: * @XmlElementRefs({
089: * @XmlElementRef(name="foo",type=JAXBElement.class)
090: * @XmlElementRef(name="bar",type=JAXBElement.class)
091: * })
092: * List<JAXBElement<String>> fooOrBar;
093: * }
094: *
095: * @XmlRegistry
096: * class ObjectFactory {
097: * @XmlElementDecl(scope=Pea.class,name="foo")
098: * JAXBElement<String> createPeaFoo(String s);
099: *
100: * @XmlElementDecl(scope=Pea.class,name="bar")
101: * JAXBElement<String> createPeaBar(String s);
102: *
103: * @XmlElementDecl(name="foo")
104: * JAXBElement<Integer> createFoo(Integer i);
105: * }
106: *
107: * </pre>
108: * Without scope createFoo and createPeaFoo would become ambiguous
109: * since both of them map to a XML schema element with the same local
110: * name "foo".
111: *
112: * @see XmlRegistry
113: * @since JAXB 2.0
114: */
115: @Retention(RUNTIME)
116: @Target({METHOD})
117: public @interface XmlElementDecl {
118: /**
119: * scope of the mapping.
120: *
121: * <p>
122: * If this is not {@link XmlElementDecl.GLOBAL}, then this element
123: * declaration mapping is only active within the specified class.
124: */
125: Class scope() default GLOBAL.class;
126:
127: /**
128: * namespace name of the XML element.
129: * <p>
130: * If the value is "##default", then the value is the namespace
131: * name for the package of the class containing this factory method.
132: *
133: * @see #name()
134: */
135: String namespace() default "##default";
136:
137: /**
138: * local name of the XML element.
139: *
140: * <p>
141: * <b> Note to reviewers: </b> There is no default name; since
142: * the annotation is on a factory method, it is not clear that the
143: * method name can be derived from the factory method name.
144: * @see #namespace()
145: */
146: String name();
147:
148: /**
149: * namespace name of a substitution group's head XML element.
150: * <p>
151: * This specifies the namespace name of the XML element whose local
152: * name is specified by <tt>substitutionHeadName()</tt>.
153: * <p>
154: * If <tt>susbtitutionHeadName()</tt> is "", then this
155: * value can only be "##default". But the value is ignored since
156: * since this element is not part of susbtitution group when the
157: * value of <tt>susbstitutionHeadName()</tt> is "".
158: * <p>
159: * If <tt>susbtitutionHeadName()</tt> is not "" and the value is
160: * "##default", then the namespace name is the namespace name to
161: * which the package of the containing class, marked with {@link
162: * XmlRegistry }, is mapped.
163: * <p>
164: * If <tt>susbtitutionHeadName()</tt> is not "" and the value is
165: * not "##default", then the value is the namespace name.
166: *
167: * @see #substitutionHeadName()
168: */
169: String substitutionHeadNamespace() default "##default";
170:
171: /**
172: * XML local name of a substitution group's head element.
173: * <p>
174: * If the value is "", then this element is not part of any
175: * substitution group.
176: *
177: * @see #substitutionHeadNamespace()
178: */
179: String substitutionHeadName() default "";
180:
181: /**
182: * Default value of this element.
183: *
184: * <p>
185: * The '\u0000' value specified as a default of this annotation element
186: * is used as a poor-man's substitute for null to allow implementations
187: * to recognize the 'no default value' state.
188: */
189: String defaultValue() default "\u0000";
190:
191: /**
192: * Used in {@link XmlElementDecl#scope()} to
193: * signal that the declaration is in the global scope.
194: */
195: public final class GLOBAL {
196: }
197: }
|