1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/annotation/XmlElementDecl.java Tue Mar 06 16:09:35 2012 -0800 1.3 @@ -0,0 +1,216 @@ 1.4 +/* 1.5 + * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package javax.xml.bind.annotation; 1.30 + 1.31 +import java.lang.annotation.Retention; 1.32 +import java.lang.annotation.Target; 1.33 + 1.34 +import static java.lang.annotation.RetentionPolicy.RUNTIME; 1.35 +import static java.lang.annotation.ElementType.METHOD; 1.36 + 1.37 +/** 1.38 + * Maps a factory method to a XML element. 1.39 + * 1.40 + * <p> <b>Usage</b> </p> 1.41 + * 1.42 + * The annotation creates a mapping between an XML schema element 1.43 + * declaration and a <i> element factory method </i> that returns a 1.44 + * JAXBElement instance representing the element 1.45 + * declaration. Typically, the element factory method is generated 1.46 + * (and annotated) from a schema into the ObjectFactory class in a 1.47 + * Java package that represents the binding of the element 1.48 + * declaration's target namespace. Thus, while the annotation syntax 1.49 + * allows @XmlElementDecl to be used on any method, semantically 1.50 + * its use is restricted to annotation of element factory method. 1.51 + * 1.52 + * The usage is subject to the following constraints: 1.53 + * 1.54 + * <ul> 1.55 + * <li> The class containing the element factory method annotated 1.56 + * with @XmlElementDecl must be marked with {@link 1.57 + * XmlRegistry}. </li> 1.58 + * <li> The element factory method must take one parameter 1.59 + * assignable to {@link Object}.</li> 1.60 + * </ul> 1.61 + * 1.62 + * <p><b>Example 1: </b>Annotation on a factory method 1.63 + * <pre> 1.64 + * // Example: code fragment 1.65 + * @XmlRegistry 1.66 + * class ObjectFactory { 1.67 + * @XmlElementDecl(name="foo") 1.68 + * JAXBElement<String> createFoo(String s) { ... } 1.69 + * } 1.70 + * </pre> 1.71 + * <pre> 1.72 + * <!-- XML input --> 1.73 + * <foo>string</foo> 1.74 + * 1.75 + * // Example: code fragment corresponding to XML input 1.76 + * JAXBElement<String> o = 1.77 + * (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument); 1.78 + * // print JAXBElement instance to show values 1.79 + * System.out.println(o.getName()); // prints "{}foo" 1.80 + * System.out.println(o.getValue()); // prints "string" 1.81 + * System.out.println(o.getValue().getClass()); // prints "java.lang.String" 1.82 + * 1.83 + * <!-- Example: XML schema definition --> 1.84 + * <xs:element name="foo" type="xs:string"/> 1.85 + * </pre> 1.86 + * 1.87 + * <p><b>Example 2: </b> Element declaration with non local scope 1.88 + * <p> 1.89 + * The following example illustrates the use of scope annotation 1.90 + * parameter in binding of element declaration in schema derived 1.91 + * code. 1.92 + * <p> 1.93 + * The following example may be replaced in a future revision of 1.94 + * this javadoc. 1.95 + * 1.96 + * <pre> 1.97 + * <!-- Example: XML schema definition --> 1.98 + * <xs:schema> 1.99 + * <xs:complexType name="pea"> 1.100 + * <xs:choice maxOccurs="unbounded"> 1.101 + * <xs:element name="foo" type="xs:string"/> 1.102 + * <xs:element name="bar" type="xs:string"/> 1.103 + * </xs:choice> 1.104 + * </xs:complexType> 1.105 + * <xs:element name="foo" type="xs:int"/> 1.106 + * </xs:schema> 1.107 + * </pre> 1.108 + * <pre> 1.109 + * // Example: expected default binding 1.110 + * class Pea { 1.111 + * @XmlElementRefs({ 1.112 + * @XmlElementRef(name="foo",type=JAXBElement.class) 1.113 + * @XmlElementRef(name="bar",type=JAXBElement.class) 1.114 + * }) 1.115 + * List<JAXBElement<String>> fooOrBar; 1.116 + * } 1.117 + * 1.118 + * @XmlRegistry 1.119 + * class ObjectFactory { 1.120 + * @XmlElementDecl(scope=Pea.class,name="foo") 1.121 + * JAXBElement<String> createPeaFoo(String s); 1.122 + * 1.123 + * @XmlElementDecl(scope=Pea.class,name="bar") 1.124 + * JAXBElement<String> createPeaBar(String s); 1.125 + * 1.126 + * @XmlElementDecl(name="foo") 1.127 + * JAXBElement<Integer> createFoo(Integer i); 1.128 + * } 1.129 + * 1.130 + * </pre> 1.131 + * Without scope createFoo and createPeaFoo would become ambiguous 1.132 + * since both of them map to a XML schema element with the same local 1.133 + * name "foo". 1.134 + * 1.135 + * @see XmlRegistry 1.136 + * @since JAXB 2.0 1.137 + */ 1.138 +@Retention(RUNTIME) 1.139 +@Target({METHOD}) 1.140 +public @interface XmlElementDecl { 1.141 + /** 1.142 + * scope of the mapping. 1.143 + * 1.144 + * <p> 1.145 + * If this is not {@link XmlElementDecl.GLOBAL}, then this element 1.146 + * declaration mapping is only active within the specified class. 1.147 + */ 1.148 + Class scope() default GLOBAL.class; 1.149 + 1.150 + /** 1.151 + * namespace name of the XML element. 1.152 + * <p> 1.153 + * If the value is "##default", then the value is the namespace 1.154 + * name for the package of the class containing this factory method. 1.155 + * 1.156 + * @see #name() 1.157 + */ 1.158 + String namespace() default "##default"; 1.159 + 1.160 + /** 1.161 + * local name of the XML element. 1.162 + * 1.163 + * <p> 1.164 + * <b> Note to reviewers: </b> There is no default name; since 1.165 + * the annotation is on a factory method, it is not clear that the 1.166 + * method name can be derived from the factory method name. 1.167 + * @see #namespace() 1.168 + */ 1.169 + String name(); 1.170 + 1.171 + /** 1.172 + * namespace name of a substitution group's head XML element. 1.173 + * <p> 1.174 + * This specifies the namespace name of the XML element whose local 1.175 + * name is specified by <tt>substitutionHeadName()</tt>. 1.176 + * <p> 1.177 + * If <tt>susbtitutionHeadName()</tt> is "", then this 1.178 + * value can only be "##default". But the value is ignored since 1.179 + * since this element is not part of susbtitution group when the 1.180 + * value of <tt>susbstitutionHeadName()</tt> is "". 1.181 + * <p> 1.182 + * If <tt>susbtitutionHeadName()</tt> is not "" and the value is 1.183 + * "##default", then the namespace name is the namespace name to 1.184 + * which the package of the containing class, marked with {@link 1.185 + * XmlRegistry }, is mapped. 1.186 + * <p> 1.187 + * If <tt>susbtitutionHeadName()</tt> is not "" and the value is 1.188 + * not "##default", then the value is the namespace name. 1.189 + * 1.190 + * @see #substitutionHeadName() 1.191 + */ 1.192 + String substitutionHeadNamespace() default "##default"; 1.193 + 1.194 + /** 1.195 + * XML local name of a substitution group's head element. 1.196 + * <p> 1.197 + * If the value is "", then this element is not part of any 1.198 + * substitution group. 1.199 + * 1.200 + * @see #substitutionHeadNamespace() 1.201 + */ 1.202 + String substitutionHeadName() default ""; 1.203 + 1.204 + /** 1.205 + * Default value of this element. 1.206 + * 1.207 + * <p> 1.208 + * The <pre>'\u0000'</pre> value specified as a default of this annotation element 1.209 + * is used as a poor-man's substitute for null to allow implementations 1.210 + * to recognize the 'no default value' state. 1.211 + */ 1.212 + String defaultValue() default "\u0000"; 1.213 + 1.214 + /** 1.215 + * Used in {@link XmlElementDecl#scope()} to 1.216 + * signal that the declaration is in the global scope. 1.217 + */ 1.218 + public final class GLOBAL {} 1.219 +}