XmlElementDecl


1   /*
2    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   package javax.xml.bind.annotation;
7   
8   import java.lang.annotation.Retention  ;
9   import java.lang.annotation.Target  ;
10  
11  import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
12  import static java.lang.annotation.ElementType.METHOD  ;
13  
14  /**
15   * Maps a factory method to a XML element.
16   *
17   * <p> <b>Usage</b> </p>
18   *
19   * The annotation creates a mapping between an XML schema element
20   * declaration and a <i> element factory method </i> that returns a
21   * JAXBElement instance representing the element
22   * declaration. Typically, the element factory method is generated
23   * (and annotated) from a schema into the ObjectFactory class in a
24   * Java package that represents the binding of the element
25   * declaration's target namespace. Thus, while the annotation syntax 
26   * allows &#64;XmlElementDecl to be used on any method, semantically
27   * its use is restricted to annotation of element factory method. 
28   *
29   * The usage is subject to the following constraints:
30   * 
31   * <ul>
32   *   <li> The class containing the element factory method annotated
33   *        with &#64;XmlElementDecl must be marked with {@link
34   *        XmlRegistry}. </li> 
35   *   <li> The element factory method must take one parameter
36   *        assignable to {@link Object}.</li> 
37   * </ul>
38   *
39   * <p><b>Example 1: </b>Annotation on a factory method
40   * <pre>
41   *     // Example: code fragment
42   *     &#64;XmlRegistry
43   *     class ObjectFactory {
44   *         &#64;XmlElementDecl(name="foo")
45   *         JAXBElement&lt;String> createFoo(String s) { ... }
46   *     }
47   * </pre>
48   * <pre><xmp> 
49   *     <!-- XML input -->
50   *       <foo>string</foo>
51   *
52   *     // Example: code fragment corresponding to XML input
53   *     JAXBElement<String> o =
54   *     (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument);
55   *     // print JAXBElement instance to show values
56   *     System.out.println(o.getName());   // prints  "{}foo"
57   *     System.out.println(o.getValue());  // prints  "string"
58   *     System.out.println(o.getValue().getClass()); // prints "java.lang.String"
59   *
60   *     <!-- Example: XML schema definition -->
61   *     <xs:element name="foo" type="xs:string"/>
62   * </xmp></pre>
63   *
64   * <p><b>Example 2: </b> Element declaration with non local scope
65   * <p>
66   * The following example illustrates the use of scope annotation
67   * parameter in binding of element declaration in schema derived
68   * code. 
69   * <p>
70   * The following example may be replaced in a future revision of
71   * this javadoc.
72   * 
73   * <pre><xmp>
74   *     <!-- Example: XML schema definition -->
75   *     <xs:schema>
76   *       <xs:complexType name="pea">
77   *         <xs:choice maxOccurs="unbounded">
78   *           <xs:element name="foo" type="xs:string"/>
79   *           <xs:element name="bar" type="xs:string"/>
80   *         </xs:choice>
81   *       </xs:complexType> 
82   *       <xs:element name="foo" type="xs:int"/>
83   *     </xs:schema>
84   * </xmp></pre> 
85   * <pre>
86   *     // Example: expected default binding
87   *     class Pea {
88   *         &#64;XmlElementRefs({
89   *             &#64;XmlElementRef(name="foo",type=JAXBElement.class)
90   *             &#64;XmlElementRef(name="bar",type=JAXBElement.class)
91   *         })
92   *         List&lt;JAXBElement&lt;String>> fooOrBar;
93   *     }
94   * 
95   *     &#64;XmlRegistry
96   *     class ObjectFactory {
97   *         &#64;XmlElementDecl(scope=Pea.class,name="foo")
98   *         JAXBElement<String> createPeaFoo(String s);
99   * 
100  *         &#64;XmlElementDecl(scope=Pea.class,name="bar")
101  *         JAXBElement<String> createPeaBar(String s);
102  * 
103  *         &#64;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 '' 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags