KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > bind > annotation > 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 JavaDoc;
9 import java.lang.annotation.Target JavaDoc;
10
11 import static java.lang.annotation.ElementType JavaDoc.*;
12 import static java.lang.annotation.RetentionPolicy JavaDoc.*;
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 JavaDoc(RUNTIME) @Target JavaDoc(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 JavaDoc 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 JavaDoc 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 JavaDoc NO_LOCATION = "##generate";
187 }
188
Popular Tags