XmlSchema


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