1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/annotation/XmlSchema.java Tue Mar 06 16:09:35 2012 -0800
1.3 @@ -0,0 +1,206 @@
1.4 +/*
1.5 + * Copyright (c) 2004, 2010, 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.ElementType.*;
1.35 +import static java.lang.annotation.RetentionPolicy.*;
1.36 +
1.37 +/**
1.38 + * <p> Maps a package name to a XML namespace. </p>
1.39 + *
1.40 + * <h3>Usage</h3>
1.41 + * <p>
1.42 + * The XmlSchema annotation can be used with the following program
1.43 + * elements:
1.44 + * <ul>
1.45 + * <li>package</li>
1.46 + * </ul>
1.47 + *
1.48 + * <p>
1.49 + * This is a package level annotation and follows the recommendations
1.50 + * and restrictions contained in JSR 175, section III, "Annotations".
1.51 + * Thus the usage is subject to the following constraints and
1.52 + * recommendations.
1.53 + * <ul>
1.54 + * <li> There can only be one package declaration as noted in JSR
1.55 + * 175, section III, "Annotations". </li>
1.56 + * <li> JSR 175 recommends package-info.java for package level
1.57 + * annotations. JAXB Providers that follow this recommendation
1.58 + * will allow the package level annotations to be defined in
1.59 + * package-info.java.
1.60 + * </ul>
1.61 + * <p>
1.62 + *
1.63 + * <p><b>Example 1:</b> Customize name of XML namespace to which
1.64 + * package is mapped.</p>
1.65 + *
1.66 + * <pre>
1.67 + * @javax.xml.bind.annotation.XmlSchema (
1.68 + * namespace = "http://www.example.com/MYPO1"
1.69 + * )
1.70 + *
1.71 + * <!-- XML Schema fragment -->
1.72 + * <schema
1.73 + * xmlns=...
1.74 + * xmlns:po=....
1.75 + * targetNamespace="http://www.example.com/MYPO1"
1.76 + * >
1.77 + * <!-- prefixes generated by default are implementation
1.78 + * depedenent -->
1.79 + * </pre>
1.80 + *
1.81 + * <p><b>Example 2:</b> Customize namespace prefix, namespace URI
1.82 + * mapping</p>
1.83 + *
1.84 + * <pre>
1.85 + * // Package level annotation
1.86 + * @javax.xml.bind.annotation.XmlSchema (
1.87 + * xmlns = {
1.88 + * @javax.xml.bind.annotation.XmlNs(prefix = "po",
1.89 + * namespaceURI="http://www.example.com/myPO1"),
1.90 + *
1.91 + * @javax.xml.bind.annotation.XmlNs(prefix="xs",
1.92 + * namespaceURI="http://www.w3.org/2001/XMLSchema")
1.93 + * )
1.94 + * )
1.95 + *
1.96 + * <!-- XML Schema fragment -->
1.97 + * <schema
1.98 + * xmlns:xs="http://www.w3.org/2001/XMLSchema"
1.99 + * xmlns:po="http://www.example.com/PO1"
1.100 + * targetNamespace="http://www.example.com/PO1">
1.101 + *
1.102 + * </pre>
1.103 + *
1.104 + * <p><b>Example 3:</b> Customize elementFormDefault</p>
1.105 + * <pre>
1.106 + * @javax.xml.bind.annotation.XmlSchema (
1.107 + * elementFormDefault=XmlNsForm.UNQUALIFIED
1.108 + * ...
1.109 + * )
1.110 + *
1.111 + * <!-- XML Schema fragment -->
1.112 + * <schema
1.113 + * xmlns="http://www.w3.org/2001/XMLSchema"
1.114 + * xmlns:po="http://www.example.com/PO1"
1.115 + * elementFormDefault="unqualified">
1.116 + *
1.117 + * </pre>
1.118 +
1.119 + * @author Sekhar Vajjhala, Sun Microsystems, Inc.
1.120 + * @since JAXB2.0
1.121 + */
1.122 +
1.123 +@Retention(RUNTIME) @Target(PACKAGE)
1.124 +public @interface XmlSchema {
1.125 +
1.126 + /**
1.127 + * Customize the namespace URI, prefix associations. By default,
1.128 + * the namespace prefixes for a XML namespace are generated by a
1.129 + * JAXB Provider in an implementation dependent way.
1.130 + */
1.131 + XmlNs[] xmlns() default {};
1.132 +
1.133 + /**
1.134 + * Name of the XML namespace.
1.135 + */
1.136 + String namespace() default "";
1.137 +
1.138 + /**
1.139 + * Namespace qualification for elements. By default, element
1.140 + * default attribute will be absent from the XML Schema fragment.
1.141 + */
1.142 + XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
1.143 +
1.144 + /**
1.145 + * Namespace qualification for attributes. By default,
1.146 + * attributesFormDefault will be absent from the XML Schema fragment.
1.147 + */
1.148 + XmlNsForm attributeFormDefault() default XmlNsForm.UNSET;
1.149 +
1.150 + /**
1.151 + * Indicates that this namespace (specified by {@link #namespace()})
1.152 + * has a schema already available exeternally, available at this location.
1.153 + *
1.154 + * <p>
1.155 + * This instructs the JAXB schema generators to simply refer to
1.156 + * the pointed schema, as opposed to generating components into the schema.
1.157 + * This schema is assumed to match what would be otherwise produced
1.158 + * by the schema generator (same element names, same type names...)
1.159 + *
1.160 + * <p>
1.161 + * This feature is intended to be used when a set of the Java classes
1.162 + * is originally generated from an existing schema, hand-written to
1.163 + * match externally defined schema, or the generated schema is modified
1.164 + * manually.
1.165 + *
1.166 + * <p>
1.167 + * Value could be any absolute URI, like <tt>http://example.org/some.xsd</tt>.
1.168 + * It is also possible to specify the empty string, to indicate
1.169 + * that the schema is externally available but the location is
1.170 + * unspecified (and thus it's the responsibility of the reader of the generate
1.171 + * schema to locate it.) Finally, the default value of this property
1.172 + * <tt>"##generate"</tt> indicates that the schema generator is going
1.173 + * to generate components for this namespace (as it did in JAXB 2.0.)
1.174 + *
1.175 + * <p>
1.176 + * Multiple {@link XmlSchema} annotations on multiple packages are allowed
1.177 + * to govern the same {@link #namespace()}. In such case, all of them
1.178 + * must have the same {@link #location()} values.
1.179 + *
1.180 + *
1.181 + * <h3>Note to implementor</h3>
1.182 + * <p>
1.183 + * More precisely, the value must be either <tt>""</tt>, <tt>"##generate"</tt>, or
1.184 + * <a href="http://www.w3.org/TR/xmlschema-2/#anyURI">
1.185 + * a valid lexical representation of <tt>xs:anyURI</tt></a> that begins
1.186 + * with <tt><scheme>:</tt>.
1.187 + *
1.188 + * <p>
1.189 + * A schema generator is expected to generate a corresponding
1.190 + * <tt><xs:import namespace="..." schemaLocation="..."/></tt> (or
1.191 + * no <tt>schemaLocation</tt> attribute at all if the empty string is specified.)
1.192 + * However, the schema generator is allowed to use a different value in
1.193 + * the <tt>schemaLocation</tt> attribute (including not generating
1.194 + * such attribute), for example so that the user can specify a local
1.195 + * copy of the resource through the command line interface.
1.196 + *
1.197 + * @since JAXB2.1
1.198 + */
1.199 + String location() default NO_LOCATION;
1.200 +
1.201 + /**
1.202 + * The default value of the {@link #location()} attribute,
1.203 + * which indicates that the schema generator will generate
1.204 + * components in this namespace.
1.205 + */
1.206 + // the actual value is chosen because ## is not a valid
1.207 + // sequence in xs:anyURI.
1.208 + static final String NO_LOCATION = "##generate";
1.209 +}
