1 /*
   2  * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.bind.annotation;
  27 
  28 import java.lang.annotation.Retention;
  29 import java.lang.annotation.Target;
  30 
  31 import static java.lang.annotation.RetentionPolicy.RUNTIME;
  32 import static java.lang.annotation.ElementType.METHOD;
  33 
  34 /**
  35  * Maps a factory method to a XML element.
  36  *
  37  * <p> <b>Usage</b> </p>
  38  *
  39  * The annotation creates a mapping between an XML schema element
  40  * declaration and a <i> element factory method </i> that returns a
  41  * JAXBElement instance representing the element
  42  * declaration. Typically, the element factory method is generated
  43  * (and annotated) from a schema into the ObjectFactory class in a
  44  * Java package that represents the binding of the element
  45  * declaration's target namespace. Thus, while the annotation syntax
  46  * allows &#64;XmlElementDecl to be used on any method, semantically
  47  * its use is restricted to annotation of element factory method.
  48  *
  49  * The usage is subject to the following constraints:
  50  *
  51  * <ul>
  52  *   <li> The class containing the element factory method annotated
  53  *        with &#64;XmlElementDecl must be marked with {@link
  54  *        XmlRegistry}. </li>
  55  *   <li> The element factory method must take one parameter
  56  *        assignable to {@link Object}.</li>
  57  * </ul>
  58  *
  59  * <p><b>Example 1: </b>Annotation on a factory method
  60  * <pre>
  61  *     // Example: code fragment
  62  *     &#64;XmlRegistry
  63  *     class ObjectFactory {
  64  *         &#64;XmlElementDecl(name="foo")
  65  *         JAXBElement&lt;String> createFoo(String s) { ... }
  66  *     }
  67  * </pre>
  68  * <pre>
  69  *     &lt;!-- XML input -->
  70  *       &lt;foo>string</foo>
  71  *
  72  *     // Example: code fragment corresponding to XML input
  73  *     JAXBElement<String> o =
  74  *     (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument);
  75  *     // print JAXBElement instance to show values
  76  *     System.out.println(o.getName());   // prints  "{}foo"
  77  *     System.out.println(o.getValue());  // prints  "string"
  78  *     System.out.println(o.getValue().getClass()); // prints "java.lang.String"
  79  *
  80  *     &lt;!-- Example: XML schema definition -->
  81  *     &lt;xs:element name="foo" type="xs:string"/>
  82  * </pre>
  83  *
  84  * <p><b>Example 2: </b> Element declaration with non local scope
  85  * <p>
  86  * The following example illustrates the use of scope annotation
  87  * parameter in binding of element declaration in schema derived
  88  * code.
  89  * <p>
  90  * The following example may be replaced in a future revision of
  91  * this javadoc.
  92  *
  93  * <pre>
  94  *     &lt;!-- Example: XML schema definition -->
  95  *     &lt;xs:schema>
  96  *       &lt;xs:complexType name="pea">
  97  *         &lt;xs:choice maxOccurs="unbounded">
  98  *           &lt;xs:element name="foo" type="xs:string"/>
  99  *           &lt;xs:element name="bar" type="xs:string"/>
 100  *         &lt;/xs:choice>
 101  *       &lt;/xs:complexType>
 102  *       &lt;xs:element name="foo" type="xs:int"/>
 103  *     &lt;/xs:schema>
 104  * </pre>
 105  * <pre>
 106  *     // Example: expected default binding
 107  *     class Pea {
 108  *         &#64;XmlElementRefs({
 109  *             &#64;XmlElementRef(name="foo",type=JAXBElement.class)
 110  *             &#64;XmlElementRef(name="bar",type=JAXBElement.class)
 111  *         })
 112  *         List&lt;JAXBElement&lt;String>> fooOrBar;
 113  *     }
 114  *
 115  *     &#64;XmlRegistry
 116  *     class ObjectFactory {
 117  *         &#64;XmlElementDecl(scope=Pea.class,name="foo")
 118  *         JAXBElement<String> createPeaFoo(String s);
 119  *
 120  *         &#64;XmlElementDecl(scope=Pea.class,name="bar")
 121  *         JAXBElement<String> createPeaBar(String s);
 122  *
 123  *         &#64;XmlElementDecl(name="foo")
 124  *         JAXBElement<Integer> createFoo(Integer i);
 125  *     }
 126  *
 127  * </pre>
 128  * Without scope createFoo and createPeaFoo would become ambiguous
 129  * since both of them map to a XML schema element with the same local
 130  * name "foo".
 131  *
 132  * @see XmlRegistry
 133  * @since JAXB 2.0
 134  */
 135 @Retention(RUNTIME)
 136 @Target({METHOD})
 137 public @interface XmlElementDecl {
 138     /**
 139      * scope of the mapping.
 140      *
 141      * <p>
 142      * If this is not {@link XmlElementDecl.GLOBAL}, then this element
 143      * declaration mapping is only active within the specified class.
 144      */
 145     Class scope() default GLOBAL.class;
 146 
 147     /**
 148      * namespace name of the XML element.
 149      * <p>
 150      * If the value is "##default", then the value is the namespace
 151      * name for the package of the class containing this factory method.
 152      *
 153      * @see #name()
 154      */
 155     String namespace() default "##default";
 156 
 157     /**
 158      * local name of the XML element.
 159      *
 160      * <p>
 161      * <b> Note to reviewers: </b> There is no default name; since
 162      * the annotation is on a factory method, it is not clear that the
 163      * method name can be derived from the factory method name.
 164      * @see #namespace()
 165      */
 166     String name();
 167 
 168     /**
 169      * namespace name of a substitution group's head XML element.
 170      * <p>
 171      * This specifies the namespace name of the XML element whose local
 172      * name is specified by <tt>substitutionHeadName()</tt>.
 173      * <p>
 174      * If <tt>susbtitutionHeadName()</tt> is "", then this
 175      * value can only be "##default". But the value is ignored since
 176      * since this element is not part of susbtitution group when the
 177      * value of <tt>susbstitutionHeadName()</tt> is "".
 178      * <p>
 179      * If <tt>susbtitutionHeadName()</tt> is not "" and the value is
 180      * "##default", then the namespace name is the namespace name to
 181      * which the package of the containing class, marked with {@link
 182      * XmlRegistry }, is mapped.
 183      * <p>
 184      * If <tt>susbtitutionHeadName()</tt> is not "" and the value is
 185      * not "##default", then the value is the namespace name.
 186      *
 187      * @see #substitutionHeadName()
 188      */
 189     String substitutionHeadNamespace() default "##default";
 190 
 191     /**
 192      * XML local name of a substitution group's head element.
 193      * <p>
 194      * If the value is "", then this element is not part of any
 195      * substitution group.
 196      *
 197      * @see #substitutionHeadNamespace()
 198      */
 199     String substitutionHeadName() default "";
 200 
 201     /**
 202      * Default value of this element.
 203      *
 204      * <p>
 205      * The <pre>'\u0000'</pre> value specified as a default of this annotation element
 206      * is used as a poor-man's substitute for null to allow implementations
 207      * to recognize the 'no default value' state.
 208      */
 209     String defaultValue() default "\u0000";
 210 
 211     /**
 212      * Used in {@link XmlElementDecl#scope()} to
 213      * signal that the declaration is in the global scope.
 214      */
 215     public final class GLOBAL {}
 216 }