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 Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,216 @@
1.4 +/*
1.5 + * Copyright (c) 2004, 2013, 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 +}
