1 /* 2 * Copyright (c) 2004, 2015, 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> {@code 69 * 70 * <!-- XML input --> 71 * <foo>string</foo> 72 * 73 * // Example: code fragment corresponding to XML input 74 * JAXBElement<String> o = 75 * (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument); 76 * // print JAXBElement instance to show values 77 * System.out.println(o.getName()); // prints "{}foo" 78 * System.out.println(o.getValue()); // prints "string" 79 * System.out.println(o.getValue().getClass()); // prints "java.lang.String" 80 * 81 * <!-- Example: XML schema definition --> 82 * <xs:element name="foo" type="xs:string"/> 83 * }</pre> 84 * 85 * <p><b>Example 2: </b> Element declaration with non local scope 86 * <p> 87 * The following example illustrates the use of scope annotation 88 * parameter in binding of element declaration in schema derived 89 * code. 90 * <p> 91 * The following example may be replaced in a future revision of 92 * this javadoc. 93 * 94 * <pre>{@code 95 * <!-- Example: XML schema definition --> 96 * <xs:schema> 97 * <xs:complexType name="pea"> 98 * <xs:choice maxOccurs="unbounded"> 99 * <xs:element name="foo" type="xs:string"/> 100 * <xs:element name="bar" type="xs:string"/> 101 * </xs:choice> 102 * </xs:complexType> 103 * <xs:element name="foo" type="xs:int"/> 104 * </xs:schema> 105 * }</pre> 106 * <pre> 107 * // Example: expected default binding 108 * class Pea { 109 * @XmlElementRefs({ 110 * @XmlElementRef(name="foo",type=JAXBElement.class) 111 * @XmlElementRef(name="bar",type=JAXBElement.class) 112 * }) 113 * List<JAXBElement<String>> fooOrBar; 114 * } 115 * 116 * @XmlRegistry 117 * class ObjectFactory { 118 * @XmlElementDecl(scope=Pea.class,name="foo") 119 * JAXBElement<String> createPeaFoo(String s); 120 * 121 * @XmlElementDecl(scope=Pea.class,name="bar") 122 * JAXBElement<String> createPeaBar(String s); 123 * 124 * @XmlElementDecl(name="foo") 125 * JAXBElement<Integer> createFoo(Integer i); 126 * } 127 * 128 * </pre> 129 * Without scope createFoo and createPeaFoo would become ambiguous 130 * since both of them map to a XML schema element with the same local 131 * name "foo". 132 * 133 * @see XmlRegistry 134 * @since 1.6, JAXB 2.0 135 */ 136 @Retention(RUNTIME) 137 @Target({METHOD}) 138 public @interface XmlElementDecl { 139 /** 140 * scope of the mapping. 141 * 142 * <p> 143 * If this is not {@link XmlElementDecl.GLOBAL}, then this element 144 * declaration mapping is only active within the specified class. 145 */ 146 Class scope() default GLOBAL.class; 147 148 /** 149 * namespace name of the XML element. 150 * <p> 151 * If the value is "##default", then the value is the namespace 152 * name for the package of the class containing this factory method. 153 * 154 * @see #name() 155 */ 156 String namespace() default "##default"; 157 158 /** 159 * local name of the XML element. 160 * 161 * <p> 162 * <b> Note to reviewers: </b> There is no default name; since 163 * the annotation is on a factory method, it is not clear that the 164 * method name can be derived from the factory method name. 165 * @see #namespace() 166 */ 167 String name(); 168 169 /** 170 * namespace name of a substitution group's head XML element. 171 * <p> 172 * This specifies the namespace name of the XML element whose local 173 * name is specified by <tt>substitutionHeadName()</tt>. 174 * <p> 175 * If <tt>susbtitutionHeadName()</tt> is "", then this 176 * value can only be "##default". But the value is ignored since 177 * since this element is not part of susbtitution group when the 178 * value of <tt>susbstitutionHeadName()</tt> is "". 179 * <p> 180 * If <tt>susbtitutionHeadName()</tt> is not "" and the value is 181 * "##default", then the namespace name is the namespace name to 182 * which the package of the containing class, marked with {@link 183 * XmlRegistry }, is mapped. 184 * <p> 185 * If <tt>susbtitutionHeadName()</tt> is not "" and the value is 186 * not "##default", then the value is the namespace name. 187 * 188 * @see #substitutionHeadName() 189 */ 190 String substitutionHeadNamespace() default "##default"; 191 192 /** 193 * XML local name of a substitution group's head element. 194 * <p> 195 * If the value is "", then this element is not part of any 196 * substitution group. 197 * 198 * @see #substitutionHeadNamespace() 199 */ 200 String substitutionHeadName() default ""; 201 202 /** 203 * Default value of this element. 204 * 205 * <p> 206 * The <pre>'\u0000'</pre> value specified as a default of this annotation element 207 * is used as a poor-man's substitute for null to allow implementations 208 * to recognize the 'no default value' state. 209 */ 210 String defaultValue() default "\u0000"; 211 212 /** 213 * Used in {@link XmlElementDecl#scope()} to 214 * signal that the declaration is in the global scope. 215 */ 216 public final class GLOBAL {} 217 }