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.ElementType.*;
  32 import static java.lang.annotation.RetentionPolicy.*;
  33 
  34 /**
  35  * <p> Maps a package name to a XML namespace. </p>
  36  *
  37  * <h3>Usage</h3>
  38  * <p>
  39  * The XmlSchema annotation can be used with the following program
  40  * elements:
  41  * <ul>
  42  *   <li>package</li>
  43  * </ul>
  44  *
  45  * <p>
  46  * This is a package level annotation and follows the recommendations
  47  * and restrictions contained in JSR 175, section III, "Annotations".
  48  * Thus the usage is subject to the following constraints and
  49  * recommendations.
  50  * <ul>
  51  *   <li> There can only be one package declaration as noted in JSR
  52  *        175, section III, "Annotations". </li>
  53  *   <li> JSR 175 recommends package-info.java for package level
  54  *        annotations. JAXB Providers that follow this recommendation
  55  *        will allow the package level annotations to be defined in
  56  *        package-info.java.
  57  * </ul>
  58  *
  59  * <p><b>Example 1:</b> Customize name of XML namespace to which
  60  * package is mapped.</p>
  61  *
  62  * <pre>
  63  *    @javax.xml.bind.annotation.XmlSchema (
  64  *      namespace = "http://www.example.com/MYPO1"
  65  *    )
  66  * {@code
  67  *
  68  *    <!-- XML Schema fragment -->
  69  *    <schema
  70  *      xmlns=...
  71  *      xmlns:po=....
  72  *      targetNamespace="http://www.example.com/MYPO1"
  73  *    >
  74  *    <!-- prefixes generated by default are implementation
  75  *            depedenent -->
  76  * }</pre>
  77  *
  78  * <p><b>Example 2:</b> Customize namespace prefix, namespace URI
  79  * mapping</p>
  80  *
  81  * <pre>
  82  *    // Package level annotation
  83  *    @javax.xml.bind.annotation.XmlSchema (
  84  *      xmlns = {
  85  *        @javax.xml.bind.annotation.XmlNs(prefix = "po",
  86  *                   namespaceURI="http://www.example.com/myPO1"),
  87  *
  88  *        @javax.xml.bind.annotation.XmlNs(prefix="xs",
  89  *                   namespaceURI="http://www.w3.org/2001/XMLSchema")
  90  *      }
  91  *    )
  92  * {@code
  93  *
  94  *    <!-- XML Schema fragment -->
  95  *    <schema
  96  *        xmlns:xs="http://www.w3.org/2001/XMLSchema"
  97  *        xmlns:po="http://www.example.com/PO1"
  98  *        targetNamespace="http://www.example.com/PO1">
  99  *
 100  * }</pre>
 101  *
 102  * <p><b>Example 3:</b> Customize elementFormDefault</p>
 103  * <pre>
 104  *    @javax.xml.bind.annotation.XmlSchema (
 105  *      elementFormDefault=XmlNsForm.UNQUALIFIED
 106  *      ...
 107  *    )
 108  * {@code
 109  *
 110  *    <!-- XML Schema fragment -->
 111  *    <schema
 112  *        xmlns="http://www.w3.org/2001/XMLSchema"
 113  *        xmlns:po="http://www.example.com/PO1"
 114  *        elementFormDefault="unqualified">
 115  *
 116  * }</pre>
 117 
 118  * @author Sekhar Vajjhala, Sun Microsystems, Inc.
 119  * @since 1.6, JAXB 2.0
 120  */
 121 
 122 @Retention(RUNTIME) @Target(PACKAGE)
 123 public @interface XmlSchema {
 124 
 125     /**
 126      * Customize the namespace URI, prefix associations. By default,
 127      * the namespace prefixes for a XML namespace are generated by a
 128      * JAXB Provider in an implementation dependent way.
 129      */
 130     XmlNs[]  xmlns() default {};
 131 
 132     /**
 133      * Name of the XML namespace.
 134      */
 135     String namespace() default "";
 136 
 137     /**
 138      * Namespace qualification for elements. By default, element
 139      * default attribute will be absent from the XML Schema fragment.
 140      */
 141     XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
 142 
 143     /**
 144      * Namespace qualification for attributes. By default,
 145      * attributesFormDefault will be absent from the XML Schema fragment.
 146      */
 147     XmlNsForm attributeFormDefault() default XmlNsForm.UNSET;
 148 
 149     /**
 150      * Indicates that this namespace (specified by {@link #namespace()})
 151      * has a schema already available exeternally, available at this location.
 152      *
 153      * <p>
 154      * This instructs the JAXB schema generators to simply refer to
 155      * the pointed schema, as opposed to generating components into the schema.
 156      * This schema is assumed to match what would be otherwise produced
 157      * by the schema generator (same element names, same type names...)
 158      *
 159      * <p>
 160      * This feature is intended to be used when a set of the Java classes
 161      * is originally generated from an existing schema, hand-written to
 162      * match externally defined schema, or the generated schema is modified
 163      * manually.
 164      *
 165      * <p>
 166      * Value could be any absolute URI, like <tt>http://example.org/some.xsd</tt>.
 167      * It is also possible to specify the empty string, to indicate
 168      * that the schema is externally available but the location is
 169      * unspecified (and thus it's the responsibility of the reader of the generate
 170      * schema to locate it.) Finally, the default value of this property
 171      * <tt>"##generate"</tt> indicates that the schema generator is going
 172      * to generate components for this namespace (as it did in JAXB 2.0.)
 173      *
 174      * <p>
 175      * Multiple {@link XmlSchema} annotations on multiple packages are allowed
 176      * to govern the same {@link #namespace()}. In such case, all of them
 177      * must have the same {@link #location()} values.
 178      *
 179      *
 180      * <h3>Note to implementor</h3>
 181      * <p>
 182      * More precisely, the value must be either <tt>""</tt>, <tt>"##generate"</tt>, or
 183      * <a href="http://www.w3.org/TR/xmlschema-2/#anyURI">
 184      * a valid lexical representation of <tt>xs:anyURI</tt></a> that begins
 185      * with <tt>&lt;scheme&gt;:</tt>.
 186      *
 187      * <p>
 188      * A schema generator is expected to generate a corresponding
 189      * <tt>&lt;xs:import namespace="..." schemaLocation="..."/&gt;</tt> (or
 190      * no <tt>schemaLocation</tt> attribute at all if the empty string is specified.)
 191      * However, the schema generator is allowed to use a different value in
 192      * the <tt>schemaLocation</tt> attribute (including not generating
 193      * such attribute), for example so that the user can specify a local
 194      * copy of the resource through the command line interface.
 195      *
 196      * @since 1.6, JAXB 2.1
 197      */
 198     String location() default NO_LOCATION;
 199 
 200     /**
 201      * The default value of the {@link #location()} attribute,
 202      * which indicates that the schema generator will generate
 203      * components in this namespace.
 204      */
 205     // the actual value is chosen because ## is not a valid
 206     // sequence in xs:anyURI.
 207     static final String NO_LOCATION = "##generate";
 208 }