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 @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 @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 * @XmlRegistry 63 * class ObjectFactory { 64 * @XmlElementDecl(name="foo") 65 * JAXBElement<String> createFoo(String s) { ... } 66 * } 67 * </pre> 68 * <pre> 69 * <!-- XML input --> 70 * <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 * <!-- Example: XML schema definition --> 81 * <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 * <!-- Example: XML schema definition --> 95 * <xs:schema> 96 * <xs:complexType name="pea"> 97 * <xs:choice maxOccurs="unbounded"> 98 * <xs:element name="foo" type="xs:string"/> 99 * <xs:element name="bar" type="xs:string"/> 100 * </xs:choice> 101 * </xs:complexType> 102 * <xs:element name="foo" type="xs:int"/> 103 * </xs:schema> 104 * </pre> 105 * <pre> 106 * // Example: expected default binding 107 * class Pea { 108 * @XmlElementRefs({ 109 * @XmlElementRef(name="foo",type=JAXBElement.class) 110 * @XmlElementRef(name="bar",type=JAXBElement.class) 111 * }) 112 * List<JAXBElement<String>> fooOrBar; 113 * } 114 * 115 * @XmlRegistry 116 * class ObjectFactory { 117 * @XmlElementDecl(scope=Pea.class,name="foo") 118 * JAXBElement<String> createPeaFoo(String s); 119 * 120 * @XmlElementDecl(scope=Pea.class,name="bar") 121 * JAXBElement<String> createPeaBar(String s); 122 * 123 * @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 }