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