author | joehw |
Wed, 04 Oct 2017 10:54:18 -0700 | |
changeset 47312 | d4f959806fe9 |
parent 47216 | 71c04702a3d5 |
child 48412 | d4412e380f6b |
permissions | -rw-r--r-- |
12005 | 1 |
/* |
45261 | 2 |
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. |
12005 | 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.validation; |
|
27 |
||
42390
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
28 |
import com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory; |
12005 | 29 |
import java.io.File; |
30 |
import java.net.URL; |
|
31 |
import javax.xml.transform.Source; |
|
32 |
import javax.xml.transform.stream.StreamSource; |
|
47312 | 33 |
import jdk.xml.internal.SecuritySupport; |
12005 | 34 |
import org.w3c.dom.ls.LSResourceResolver; |
35 |
import org.xml.sax.ErrorHandler; |
|
36 |
import org.xml.sax.SAXException; |
|
37 |
import org.xml.sax.SAXNotRecognizedException; |
|
38 |
import org.xml.sax.SAXNotSupportedException; |
|
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
39 |
import org.xml.sax.SAXParseException; |
12005 | 40 |
|
41 |
/** |
|
29999 | 42 |
* Factory that creates {@link Schema} objects. Entry-point to |
12005 | 43 |
* the validation API. |
44 |
* |
|
45 |
* <p> |
|
46 |
* {@link SchemaFactory} is a schema compiler. It reads external |
|
47 |
* representations of schemas and prepares them for validation. |
|
48 |
* |
|
49 |
* <p> |
|
50 |
* The {@link SchemaFactory} class is not thread-safe. In other words, |
|
51 |
* it is the application's responsibility to ensure that at most |
|
52 |
* one thread is using a {@link SchemaFactory} object at any |
|
53 |
* given moment. Implementations are encouraged to mark methods |
|
29999 | 54 |
* as {@code synchronized} to protect themselves from broken clients. |
12005 | 55 |
* |
56 |
* <p> |
|
57 |
* {@link SchemaFactory} is not re-entrant. While one of the |
|
29999 | 58 |
* {@code newSchema} methods is being invoked, applications |
59 |
* may not attempt to recursively invoke the {@code newSchema} method, |
|
12005 | 60 |
* even from the same thread. |
61 |
* |
|
45261 | 62 |
* <h2><a id="schemaLanguage"></a>Schema Language</h2> |
12005 | 63 |
* <p> |
64 |
* This spec uses a namespace URI to designate a schema language. |
|
65 |
* The following table shows the values defined by this specification. |
|
66 |
* <p> |
|
67 |
* To be compliant with the spec, the implementation |
|
68 |
* is only required to support W3C XML Schema 1.0. However, |
|
69 |
* if it chooses to support other schema languages listed here, |
|
70 |
* it must conform to the relevant behaviors described in this spec. |
|
71 |
* |
|
72 |
* <p> |
|
73 |
* Schema languages not listed here are expected to |
|
74 |
* introduce their own URIs to represent themselves. |
|
75 |
* The {@link SchemaFactory} class is capable of locating other |
|
76 |
* implementations for other schema languages at run-time. |
|
77 |
* |
|
78 |
* <p> |
|
79 |
* Note that because the XML DTD is strongly tied to the parsing process |
|
80 |
* and has a significant effect on the parsing process, it is impossible |
|
81 |
* to define the DTD validation as a process independent from parsing. |
|
82 |
* For this reason, this specification does not define the semantics for |
|
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
83 |
* the XML DTD. This doesn't prohibit implementors from implementing it |
12005 | 84 |
* in a way they see fit, but <em>users are warned that any DTD |
85 |
* validation implemented on this interface necessarily deviate from |
|
86 |
* the XML DTD semantics as defined in the XML 1.0</em>. |
|
87 |
* |
|
45261 | 88 |
* <table class="striped"> |
89 |
* <caption>URIs for Supported Schema languages</caption> |
|
12005 | 90 |
* <thead> |
91 |
* <tr> |
|
45855 | 92 |
* <th scope="col">value</th> |
93 |
* <th scope="col">language</th> |
|
12005 | 94 |
* </tr> |
95 |
* </thead> |
|
96 |
* <tbody> |
|
97 |
* <tr> |
|
45855 | 98 |
* <th scope="row">{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("{@code http://www.w3.org/2001/XMLSchema}")</th> |
12005 | 99 |
* <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td> |
100 |
* </tr> |
|
101 |
* <tr> |
|
45855 | 102 |
* <th scope="row">{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("{@code http://relaxng.org/ns/structure/1.0}")</th> |
12005 | 103 |
* <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td> |
104 |
* </tr> |
|
105 |
* </tbody> |
|
106 |
* </table> |
|
107 |
* |
|
108 |
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> |
|
109 |
* @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a> |
|
110 |
* |
|
111 |
* @since 1.5 |
|
112 |
*/ |
|
113 |
public abstract class SchemaFactory { |
|
114 |
||
115 |
/** |
|
29999 | 116 |
* Constructor for derived classes. |
12005 | 117 |
* |
29999 | 118 |
* <p>The constructor does nothing. |
12005 | 119 |
* |
120 |
* <p>Derived classes must create {@link SchemaFactory} objects that have |
|
29999 | 121 |
* {@code null} {@link ErrorHandler} and |
122 |
* {@code null} {@link LSResourceResolver}. |
|
12005 | 123 |
*/ |
124 |
protected SchemaFactory() { |
|
125 |
} |
|
126 |
||
127 |
/** |
|
42390
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
128 |
* Creates a new instance of the {@code SchemaFactory} builtin |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
129 |
* system-default implementation. |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
130 |
* |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
131 |
* @implSpec The {@code SchemaFactory} builtin |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
132 |
* system-default implementation is only required to support the |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
133 |
* <a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a>, |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
134 |
* but may support additional <a href="#schemaLanguage">schema languages</a>. |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
135 |
* |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
136 |
* @return A new instance of the {@code SchemaFactory} builtin |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
137 |
* system-default implementation. |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
138 |
* |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
139 |
* @since 9 |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
140 |
*/ |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
141 |
public static SchemaFactory newDefaultInstance() { |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
142 |
return XMLSchemaFactory.newXMLSchemaFactoryNoServiceLoader(); |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
143 |
} |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
144 |
|
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
145 |
/** |
29999 | 146 |
* Lookup an implementation of the {@code SchemaFactory} that supports the specified |
147 |
* schema language and return it. |
|
12005 | 148 |
* |
29999 | 149 |
* <p>To find a {@code SchemaFactory} object for a given schema language, |
12005 | 150 |
* this method looks the following places in the following order |
29999 | 151 |
* where "the class loader" refers to the context class loader: |
12005 | 152 |
* <ol> |
153 |
* <li> |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
154 |
* <p> |
12005 | 155 |
* If the system property |
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
156 |
* {@code "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"} |
12005 | 157 |
* is present (where <i>schemaLanguage</i> is the parameter |
158 |
* to this method), then its value is read |
|
159 |
* as a class name. The method will try to |
|
160 |
* create a new instance of this class by using the class loader, |
|
161 |
* and returns it if it is successfully created. |
|
162 |
* </li> |
|
163 |
* <li> |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
164 |
* <p> |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
165 |
* Use the configuration file "jaxp.properties". The file is in standard |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
166 |
* {@link java.util.Properties} format and typically located in the |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
167 |
* conf directory of the Java installation. It contains the fully qualified |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
168 |
* name of the implementation class with the key being the system property |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
169 |
* defined above. |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
170 |
* <p> |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
171 |
* The jaxp.properties file is read only once by the JAXP implementation |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
172 |
* and its values are then cached for future use. If the file does not exist |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
173 |
* when the first attempt is made to read from it, no further attempts are |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
174 |
* made to check for its existence. It is not possible to change the value |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
175 |
* of any property in jaxp.properties after it has been read for the first time. |
12005 | 176 |
* </li> |
177 |
* <li> |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
178 |
* <p> |
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
179 |
* Use the service-provider loading facility, defined by the |
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
180 |
* {@link java.util.ServiceLoader} class, to attempt to locate and load an |
20581
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
181 |
* implementation of the service using the {@linkplain |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
182 |
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
183 |
* the service-provider loading facility will use the {@linkplain |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
184 |
* java.lang.Thread#getContextClassLoader() current thread's context class loader} |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
185 |
* to attempt to load the service. If the context class |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
186 |
* loader is null, the {@linkplain |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
187 |
* ClassLoader#getSystemClassLoader() system class loader} will be used. |
65d17ea72da3
8025745: Clarify API documentation of JAXP factories.
dfuchs
parents:
17534
diff
changeset
|
188 |
* <br> |
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
189 |
* Each potential service provider is required to implement the method |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
190 |
* {@link #isSchemaLanguageSupported(String schemaLanguage)}. |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
191 |
* <br> |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
192 |
* The first service provider found that supports the specified schema |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
193 |
* language is returned. |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
194 |
* <br> |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
195 |
* In case of {@link java.util.ServiceConfigurationError} a |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
196 |
* {@link SchemaFactoryConfigurationError} will be thrown. |
12005 | 197 |
* </li> |
198 |
* <li> |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
199 |
* <p> |
29999 | 200 |
* Platform default {@code SchemaFactory} is located |
42390
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
201 |
* in an implementation specific way. There must be a |
4083bc2c3b5b
8169778: Add new public methods to get new instances of the JAXP factories builtin system-default implementations
dfuchs
parents:
29999
diff
changeset
|
202 |
* {@linkplain #newDefaultInstance() platform default} |
29999 | 203 |
* {@code SchemaFactory} for W3C XML Schema. |
12005 | 204 |
* </li> |
205 |
* </ol> |
|
206 |
* |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
207 |
* <p>If everything fails, {@link IllegalArgumentException} will be thrown. |
12005 | 208 |
* |
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
209 |
* <p><strong>Tip for Trouble-shooting:</strong> |
12005 | 210 |
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for |
211 |
* exactly how a property file is parsed. In particular, colons ':' |
|
212 |
* need to be escaped in a property file, so make sure schema language |
|
29419
534054ee6062
8049378: Examine references to ${java.home}/lib in JAXP
joehw
parents:
27574
diff
changeset
|
213 |
* URIs are properly escaped in it. For example: |
12005 | 214 |
* <pre> |
215 |
* http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory |
|
216 |
* </pre> |
|
217 |
* |
|
218 |
* @param schemaLanguage |
|
219 |
* Specifies the schema language which the returned |
|
220 |
* SchemaFactory will understand. See |
|
221 |
* <a href="#schemaLanguage">the list of available |
|
222 |
* schema languages</a> for the possible values. |
|
223 |
* |
|
29999 | 224 |
* @return New instance of a {@code SchemaFactory} |
12005 | 225 |
* |
226 |
* @throws IllegalArgumentException |
|
227 |
* If no implementation of the schema language is available. |
|
228 |
* @throws NullPointerException |
|
29999 | 229 |
* If the {@code schemaLanguage} parameter is null. |
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
230 |
* @throws SchemaFactoryConfigurationError |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
231 |
* If a configuration error is encountered. |
12005 | 232 |
* |
233 |
* @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) |
|
234 |
*/ |
|
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
235 |
public static SchemaFactory newInstance(String schemaLanguage) { |
12005 | 236 |
ClassLoader cl; |
47312 | 237 |
cl = SecuritySupport.getContextClassLoader(); |
12005 | 238 |
|
239 |
if (cl == null) { |
|
240 |
//cl = ClassLoader.getSystemClassLoader(); |
|
241 |
//use the current class loader |
|
242 |
cl = SchemaFactory.class.getClassLoader(); |
|
243 |
} |
|
244 |
||
245 |
SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage); |
|
246 |
if (f == null) { |
|
247 |
throw new IllegalArgumentException( |
|
248 |
"No SchemaFactory" |
|
249 |
+ " that implements the schema language specified by: " + schemaLanguage |
|
250 |
+ " could be loaded"); |
|
251 |
} |
|
252 |
return f; |
|
253 |
} |
|
254 |
||
255 |
/** |
|
29999 | 256 |
* Obtain a new instance of a {@code SchemaFactory} from class name. {@code SchemaFactory} |
12005 | 257 |
* is returned if specified factory class name supports the specified schema language. |
258 |
* This function is useful when there are multiple providers in the classpath. |
|
259 |
* It gives more control to the application as it can specify which provider |
|
29999 | 260 |
* should be loaded. |
12005 | 261 |
* |
262 |
* <h2>Tip for Trouble-shooting</h2> |
|
29999 | 263 |
* <p>Setting the {@code jaxp.debug} system property will cause |
12005 | 264 |
* this method to print a lot of debug messages |
29999 | 265 |
* to {@code System.err} about what it is doing and where it is looking at. |
12005 | 266 |
* |
29999 | 267 |
* <p> If you have problems try: |
12005 | 268 |
* <pre> |
269 |
* java -Djaxp.debug=1 YourProgram .... |
|
270 |
* </pre> |
|
271 |
* |
|
272 |
* @param schemaLanguage Specifies the schema language which the returned |
|
29999 | 273 |
* {@code SchemaFactory} will understand. See |
12005 | 274 |
* <a href="#schemaLanguage">the list of available |
275 |
* schema languages</a> for the possible values. |
|
276 |
* |
|
29999 | 277 |
* @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.validation.SchemaFactory}. |
12005 | 278 |
* |
29999 | 279 |
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null} |
280 |
* current {@code Thread}'s context classLoader is used to load the factory class. |
|
12005 | 281 |
* |
29999 | 282 |
* @return New instance of a {@code SchemaFactory} |
12005 | 283 |
* |
284 |
* @throws IllegalArgumentException |
|
29999 | 285 |
* if {@code factoryClassName} is {@code null}, or |
12005 | 286 |
* the factory class cannot be loaded, instantiated or doesn't |
29999 | 287 |
* support the schema language specified in {@code schemLanguage} |
12005 | 288 |
* parameter. |
289 |
* |
|
290 |
* @throws NullPointerException |
|
29999 | 291 |
* If the {@code schemaLanguage} parameter is null. |
12005 | 292 |
* |
293 |
* @see #newInstance(String schemaLanguage) |
|
294 |
* |
|
295 |
* @since 1.6 |
|
296 |
*/ |
|
297 |
public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader){ |
|
298 |
ClassLoader cl = classLoader; |
|
299 |
||
300 |
if (cl == null) { |
|
47312 | 301 |
cl = SecuritySupport.getContextClassLoader(); |
12005 | 302 |
} |
303 |
||
304 |
SchemaFactory f = new SchemaFactoryFinder(cl).createInstance(factoryClassName); |
|
305 |
if (f == null) { |
|
306 |
throw new IllegalArgumentException( |
|
307 |
"Factory " + factoryClassName |
|
308 |
+ " could not be loaded to implement the schema language specified by: " + schemaLanguage); |
|
309 |
} |
|
310 |
//if this factory supports the given schemalanguage return this factory else thrown exception |
|
311 |
if(f.isSchemaLanguageSupported(schemaLanguage)){ |
|
312 |
return f; |
|
313 |
}else{ |
|
314 |
throw new IllegalArgumentException( |
|
315 |
"Factory " + f.getClass().getName() |
|
316 |
+ " does not implement the schema language specified by: " + schemaLanguage); |
|
317 |
} |
|
318 |
||
319 |
} |
|
320 |
||
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
321 |
/** |
29999 | 322 |
* Is specified schema supported by this {@code SchemaFactory}? |
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
323 |
* |
29999 | 324 |
* @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand. |
325 |
* {@code schemaLanguage} must specify a <a href="#schemaLanguage">valid</a> schema language. |
|
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
326 |
* |
29999 | 327 |
* @return {@code true} if {@code SchemaFactory} supports {@code schemaLanguage}, else {@code false}. |
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
328 |
* |
29999 | 329 |
* @throws NullPointerException If {@code schemaLanguage} is {@code null}. |
330 |
* @throws IllegalArgumentException If {@code schemaLanguage.length() == 0} |
|
331 |
* or {@code schemaLanguage} does not specify a <a href="#schemaLanguage">valid</a> schema language. |
|
17264
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
332 |
*/ |
3aff554ad461
8005954: JAXP Plugability Layer should use java.util.ServiceLoader
dfuchs
parents:
12457
diff
changeset
|
333 |
public abstract boolean isSchemaLanguageSupported(String schemaLanguage); |
12005 | 334 |
|
335 |
/** |
|
336 |
* Look up the value of a feature flag. |
|
337 |
* |
|
338 |
* <p>The feature name is any fully-qualified URI. It is |
|
339 |
* possible for a {@link SchemaFactory} to recognize a feature name but |
|
340 |
* temporarily be unable to return its value. |
|
341 |
* |
|
342 |
* <p>Implementors are free (and encouraged) to invent their own features, |
|
29999 | 343 |
* using names built on their own URIs. |
12005 | 344 |
* |
345 |
* @param name The feature name, which is a non-null fully-qualified URI. |
|
346 |
* |
|
347 |
* @return The current value of the feature (true or false). |
|
348 |
* |
|
349 |
* @throws SAXNotRecognizedException If the feature |
|
350 |
* value can't be assigned or retrieved. |
|
351 |
* @throws SAXNotSupportedException When the |
|
352 |
* {@link SchemaFactory} recognizes the feature name but |
|
353 |
* cannot determine its value at this time. |
|
29999 | 354 |
* @throws NullPointerException If {@code name} is {@code null}. |
12005 | 355 |
* |
356 |
* @see #setFeature(String, boolean) |
|
357 |
*/ |
|
358 |
public boolean getFeature(String name) |
|
359 |
throws SAXNotRecognizedException, SAXNotSupportedException { |
|
360 |
||
361 |
if (name == null) { |
|
362 |
throw new NullPointerException("the name parameter is null"); |
|
363 |
} |
|
364 |
throw new SAXNotRecognizedException(name); |
|
365 |
} |
|
366 |
||
367 |
/** |
|
29999 | 368 |
* Set a feature for this {@code SchemaFactory}, |
12005 | 369 |
* {@link Schema}s created by this factory, and by extension, |
370 |
* {@link Validator}s and {@link ValidatorHandler}s created by |
|
371 |
* those {@link Schema}s. |
|
372 |
* |
|
373 |
* <p>Implementors and developers should pay particular attention |
|
374 |
* to how the special {@link Schema} object returned by {@link |
|
375 |
* #newSchema()} is processed. In some cases, for example, when the |
|
29999 | 376 |
* {@code SchemaFactory} and the class actually loading the |
12005 | 377 |
* schema come from different implementations, it may not be possible |
29999 | 378 |
* for {@code SchemaFactory} features to be inherited automatically. |
12005 | 379 |
* Developers should |
380 |
* make sure that features, such as secure processing, are explicitly |
|
29999 | 381 |
* set in both places. |
12005 | 382 |
* |
383 |
* <p>The feature name is any fully-qualified URI. It is |
|
384 |
* possible for a {@link SchemaFactory} to expose a feature value but |
|
29999 | 385 |
* to be unable to change the current value. |
12005 | 386 |
* |
387 |
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. |
|
29999 | 388 |
* When the feature is: |
12005 | 389 |
* <ul> |
390 |
* <li> |
|
29999 | 391 |
* {@code true}: the implementation will limit XML processing to conform to implementation limits. |
24887 | 392 |
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources. |
12005 | 393 |
* If XML processing is limited for security reasons, it will be reported via a call to the registered |
394 |
* {@link ErrorHandler#fatalError(SAXParseException exception)}. |
|
395 |
* See {@link #setErrorHandler(ErrorHandler errorHandler)}. |
|
396 |
* </li> |
|
397 |
* <li> |
|
29999 | 398 |
* {@code false}: the implementation will processing XML according to the XML specifications without |
12005 | 399 |
* regard to possible implementation limits. |
400 |
* </li> |
|
401 |
* </ul> |
|
402 |
* |
|
403 |
* @param name The feature name, which is a non-null fully-qualified URI. |
|
404 |
* @param value The requested value of the feature (true or false). |
|
405 |
* |
|
406 |
* @throws SAXNotRecognizedException If the feature |
|
407 |
* value can't be assigned or retrieved. |
|
408 |
* @throws SAXNotSupportedException When the |
|
409 |
* {@link SchemaFactory} recognizes the feature name but |
|
410 |
* cannot set the requested value. |
|
29999 | 411 |
* @throws NullPointerException If {@code name} is {@code null}. |
12005 | 412 |
* |
413 |
* @see #getFeature(String) |
|
414 |
*/ |
|
415 |
public void setFeature(String name, boolean value) |
|
416 |
throws SAXNotRecognizedException, SAXNotSupportedException { |
|
417 |
||
418 |
if (name == null) { |
|
419 |
throw new NullPointerException("the name parameter is null"); |
|
420 |
} |
|
421 |
throw new SAXNotRecognizedException(name); |
|
422 |
} |
|
423 |
||
424 |
/** |
|
425 |
* Set the value of a property. |
|
426 |
* |
|
29999 | 427 |
* <p>The property name is any fully-qualified URI. It is |
12005 | 428 |
* possible for a {@link SchemaFactory} to recognize a property name but |
29999 | 429 |
* to be unable to change the current value. |
12005 | 430 |
* |
17534 | 431 |
* <p> |
432 |
* All implementations that implement JAXP 1.5 or newer are required to |
|
433 |
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and |
|
434 |
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties. |
|
29999 | 435 |
* |
17534 | 436 |
* <ul> |
437 |
* <li> |
|
438 |
* <p>Access to external DTDs in Schema files is restricted to the protocols |
|
439 |
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. |
|
440 |
* If access is denied during the creation of new Schema due to the restriction |
|
441 |
* of this property, {@link org.xml.sax.SAXException} will be thrown by the |
|
442 |
* {@link #newSchema(Source)} or {@link #newSchema(File)} |
|
29999 | 443 |
* or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method. |
17534 | 444 |
* |
445 |
* <p>Access to external DTDs in xml source files is restricted to the protocols |
|
446 |
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. |
|
447 |
* If access is denied during validation due to the restriction |
|
448 |
* of this property, {@link org.xml.sax.SAXException} will be thrown by the |
|
449 |
* {@link javax.xml.validation.Validator#validate(Source)} or |
|
29999 | 450 |
* {@link javax.xml.validation.Validator#validate(Source, Result)} method. |
17534 | 451 |
* |
452 |
* <p>Access to external reference set by the schemaLocation attribute is |
|
453 |
* restricted to the protocols specified by the |
|
454 |
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property. |
|
455 |
* If access is denied during validation due to the restriction of this property, |
|
456 |
* {@link org.xml.sax.SAXException} will be thrown by the |
|
457 |
* {@link javax.xml.validation.Validator#validate(Source)} or |
|
29999 | 458 |
* {@link javax.xml.validation.Validator#validate(Source, Result)} method. |
17534 | 459 |
* |
460 |
* <p>Access to external reference set by the Import |
|
461 |
* and Include element is restricted to the protocols specified by the |
|
462 |
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property. |
|
463 |
* If access is denied during the creation of new Schema due to the restriction |
|
464 |
* of this property, {@link org.xml.sax.SAXException} will be thrown by the |
|
465 |
* {@link #newSchema(Source)} or {@link #newSchema(File)} |
|
29999 | 466 |
* or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method. |
17534 | 467 |
* </li> |
468 |
* </ul> |
|
12005 | 469 |
* |
470 |
* @param name The property name, which is a non-null fully-qualified URI. |
|
471 |
* @param object The requested value for the property. |
|
472 |
* |
|
473 |
* @throws SAXNotRecognizedException If the property |
|
474 |
* value can't be assigned or retrieved. |
|
475 |
* @throws SAXNotSupportedException When the |
|
476 |
* {@link SchemaFactory} recognizes the property name but |
|
477 |
* cannot set the requested value. |
|
29999 | 478 |
* @throws NullPointerException If {@code name} is {@code null}. |
12005 | 479 |
*/ |
480 |
public void setProperty(String name, Object object) |
|
481 |
throws SAXNotRecognizedException, SAXNotSupportedException { |
|
482 |
||
483 |
if (name == null) { |
|
484 |
throw new NullPointerException("the name parameter is null"); |
|
485 |
} |
|
486 |
throw new SAXNotRecognizedException(name); |
|
487 |
} |
|
488 |
||
489 |
/** |
|
490 |
* Look up the value of a property. |
|
491 |
* |
|
492 |
* <p>The property name is any fully-qualified URI. It is |
|
493 |
* possible for a {@link SchemaFactory} to recognize a property name but |
|
29999 | 494 |
* temporarily be unable to return its value. |
12005 | 495 |
* |
496 |
* <p>{@link SchemaFactory}s are not required to recognize any specific |
|
29999 | 497 |
* property names. |
12005 | 498 |
* |
499 |
* <p>Implementors are free (and encouraged) to invent their own properties, |
|
29999 | 500 |
* using names built on their own URIs. |
12005 | 501 |
* |
502 |
* @param name The property name, which is a non-null fully-qualified URI. |
|
503 |
* |
|
504 |
* @return The current value of the property. |
|
505 |
* |
|
506 |
* @throws SAXNotRecognizedException If the property |
|
507 |
* value can't be assigned or retrieved. |
|
508 |
* @throws SAXNotSupportedException When the |
|
509 |
* XMLReader recognizes the property name but |
|
510 |
* cannot determine its value at this time. |
|
29999 | 511 |
* @throws NullPointerException If {@code name} is {@code null}. |
12005 | 512 |
* |
513 |
* @see #setProperty(String, Object) |
|
514 |
*/ |
|
515 |
public Object getProperty(String name) |
|
516 |
throws SAXNotRecognizedException, SAXNotSupportedException { |
|
517 |
||
518 |
if (name == null) { |
|
519 |
throw new NullPointerException("the name parameter is null"); |
|
520 |
} |
|
521 |
throw new SAXNotRecognizedException(name); |
|
522 |
} |
|
523 |
||
524 |
/** |
|
525 |
* Sets the {@link ErrorHandler} to receive errors encountered |
|
29999 | 526 |
* during the {@code newSchema} method invocation. |
12005 | 527 |
* |
528 |
* <p> |
|
529 |
* Error handler can be used to customize the error handling process |
|
530 |
* during schema parsing. When an {@link ErrorHandler} is set, |
|
531 |
* errors found during the parsing of schemas will be first sent |
|
532 |
* to the {@link ErrorHandler}. |
|
533 |
* |
|
534 |
* <p> |
|
535 |
* The error handler can abort the parsing of a schema immediately |
|
536 |
* by throwing {@link SAXException} from the handler. Or for example |
|
537 |
* it can print an error to the screen and try to continue the |
|
538 |
* processing by returning normally from the {@link ErrorHandler} |
|
539 |
* |
|
540 |
* <p> |
|
541 |
* If any {@link Throwable} (or instances of its derived classes) |
|
542 |
* is thrown from an {@link ErrorHandler}, |
|
29999 | 543 |
* the caller of the {@code newSchema} method will be thrown |
12005 | 544 |
* the same {@link Throwable} object. |
545 |
* |
|
546 |
* <p> |
|
547 |
* {@link SchemaFactory} is not allowed to |
|
548 |
* throw {@link SAXException} without first reporting it to |
|
549 |
* {@link ErrorHandler}. |
|
550 |
* |
|
551 |
* <p> |
|
552 |
* Applications can call this method even during a {@link Schema} |
|
553 |
* is being parsed. |
|
554 |
* |
|
555 |
* <p> |
|
556 |
* When the {@link ErrorHandler} is null, the implementation will |
|
557 |
* behave as if the following {@link ErrorHandler} is set: |
|
558 |
* <pre> |
|
559 |
* class DraconianErrorHandler implements {@link ErrorHandler} { |
|
560 |
* public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { |
|
561 |
* throw e; |
|
562 |
* } |
|
563 |
* public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { |
|
564 |
* throw e; |
|
565 |
* } |
|
566 |
* public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { |
|
567 |
* // noop |
|
568 |
* } |
|
569 |
* } |
|
570 |
* </pre> |
|
571 |
* |
|
572 |
* <p> |
|
573 |
* When a new {@link SchemaFactory} object is created, initially |
|
574 |
* this field is set to null. This field will <em>NOT</em> be |
|
575 |
* inherited to {@link Schema}s, {@link Validator}s, or |
|
576 |
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. |
|
577 |
* |
|
578 |
* @param errorHandler A new error handler to be set. |
|
29999 | 579 |
* This parameter can be {@code null}. |
12005 | 580 |
*/ |
581 |
public abstract void setErrorHandler(ErrorHandler errorHandler); |
|
582 |
||
583 |
/** |
|
584 |
* Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}. |
|
585 |
* |
|
586 |
* @return |
|
587 |
* This method returns the object that was last set through |
|
588 |
* the {@link #setErrorHandler(ErrorHandler)} method, or null |
|
589 |
* if that method has never been called since this {@link SchemaFactory} |
|
590 |
* has created. |
|
591 |
* |
|
592 |
* @see #setErrorHandler(ErrorHandler) |
|
593 |
*/ |
|
594 |
public abstract ErrorHandler getErrorHandler(); |
|
595 |
||
596 |
/** |
|
597 |
* Sets the {@link LSResourceResolver} to customize |
|
598 |
* resource resolution when parsing schemas. |
|
599 |
* |
|
600 |
* <p> |
|
601 |
* {@link SchemaFactory} uses a {@link LSResourceResolver} |
|
602 |
* when it needs to locate external resources while parsing schemas, |
|
603 |
* although exactly what constitutes "locating external resources" is |
|
604 |
* up to each schema language. For example, for W3C XML Schema, |
|
29999 | 605 |
* this includes files {@code <include>}d or {@code <import>}ed, |
12005 | 606 |
* and DTD referenced from schema files, etc. |
607 |
* |
|
608 |
* <p> |
|
609 |
* Applications can call this method even during a {@link Schema} |
|
610 |
* is being parsed. |
|
611 |
* |
|
612 |
* <p> |
|
613 |
* When the {@link LSResourceResolver} is null, the implementation will |
|
614 |
* behave as if the following {@link LSResourceResolver} is set: |
|
615 |
* <pre> |
|
616 |
* class DumbDOMResourceResolver implements {@link LSResourceResolver} { |
|
617 |
* public {@link org.w3c.dom.ls.LSInput} resolveResource( |
|
618 |
* String publicId, String systemId, String baseURI) { |
|
619 |
* |
|
620 |
* return null; // always return null |
|
621 |
* } |
|
622 |
* } |
|
623 |
* </pre> |
|
624 |
* |
|
625 |
* <p> |
|
626 |
* If a {@link LSResourceResolver} throws a {@link RuntimeException} |
|
627 |
* (or instances of its derived classes), |
|
628 |
* then the {@link SchemaFactory} will abort the parsing and |
|
29999 | 629 |
* the caller of the {@code newSchema} method will receive |
12005 | 630 |
* the same {@link RuntimeException}. |
631 |
* |
|
632 |
* <p> |
|
633 |
* When a new {@link SchemaFactory} object is created, initially |
|
634 |
* this field is set to null. This field will <em>NOT</em> be |
|
635 |
* inherited to {@link Schema}s, {@link Validator}s, or |
|
636 |
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. |
|
637 |
* |
|
638 |
* @param resourceResolver |
|
639 |
* A new resource resolver to be set. This parameter can be null. |
|
640 |
*/ |
|
641 |
public abstract void setResourceResolver(LSResourceResolver resourceResolver); |
|
642 |
||
643 |
/** |
|
644 |
* Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}. |
|
645 |
* |
|
646 |
* @return |
|
647 |
* This method returns the object that was last set through |
|
648 |
* the {@link #setResourceResolver(LSResourceResolver)} method, or null |
|
649 |
* if that method has never been called since this {@link SchemaFactory} |
|
650 |
* has created. |
|
651 |
* |
|
652 |
* @see #setErrorHandler(ErrorHandler) |
|
653 |
*/ |
|
654 |
public abstract LSResourceResolver getResourceResolver(); |
|
655 |
||
656 |
/** |
|
29999 | 657 |
* Parses the specified source as a schema and returns it as a schema. |
12005 | 658 |
* |
29999 | 659 |
* <p>This is a convenience method for {@link #newSchema(Source[] schemas)}. |
12005 | 660 |
* |
661 |
* @param schema Source that represents a schema. |
|
662 |
* |
|
29999 | 663 |
* @return New {@code Schema} from parsing {@code schema}. |
12005 | 664 |
* |
665 |
* @throws SAXException If a SAX error occurs during parsing. |
|
29999 | 666 |
* @throws NullPointerException if {@code schema} is null. |
12005 | 667 |
*/ |
668 |
public Schema newSchema(Source schema) throws SAXException { |
|
669 |
return newSchema(new Source[]{schema}); |
|
670 |
} |
|
671 |
||
672 |
/** |
|
29999 | 673 |
* Parses the specified {@code File} as a schema and returns it as a {@code Schema}. |
12005 | 674 |
* |
29999 | 675 |
* <p>This is a convenience method for {@link #newSchema(Source schema)}. |
12005 | 676 |
* |
677 |
* @param schema File that represents a schema. |
|
678 |
* |
|
29999 | 679 |
* @return New {@code Schema} from parsing {@code schema}. |
12005 | 680 |
* |
681 |
* @throws SAXException If a SAX error occurs during parsing. |
|
29999 | 682 |
* @throws NullPointerException if {@code schema} is null. |
12005 | 683 |
*/ |
684 |
public Schema newSchema(File schema) throws SAXException { |
|
685 |
return newSchema(new StreamSource(schema)); |
|
686 |
} |
|
687 |
||
688 |
/** |
|
29999 | 689 |
* Parses the specified {@code URL} as a schema and returns it as a {@code Schema}. |
12005 | 690 |
* |
29999 | 691 |
* <p>This is a convenience method for {@link #newSchema(Source schema)}. |
12005 | 692 |
* |
29999 | 693 |
* @param schema {@code URL} that represents a schema. |
12005 | 694 |
* |
29999 | 695 |
* @return New {@code Schema} from parsing {@code schema}. |
12005 | 696 |
* |
697 |
* @throws SAXException If a SAX error occurs during parsing. |
|
29999 | 698 |
* @throws NullPointerException if {@code schema} is null. |
12005 | 699 |
*/ |
700 |
public Schema newSchema(URL schema) throws SAXException { |
|
701 |
return newSchema(new StreamSource(schema.toExternalForm())); |
|
702 |
} |
|
703 |
||
704 |
/** |
|
705 |
* Parses the specified source(s) as a schema and returns it as a schema. |
|
706 |
* |
|
707 |
* <p> |
|
708 |
* The callee will read all the {@link Source}s and combine them into a |
|
709 |
* single schema. The exact semantics of the combination depends on the schema |
|
710 |
* language that this {@link SchemaFactory} object is created for. |
|
711 |
* |
|
712 |
* <p> |
|
713 |
* When an {@link ErrorHandler} is set, the callee will report all the errors |
|
714 |
* found in sources to the handler. If the handler throws an exception, it will |
|
715 |
* abort the schema compilation and the same exception will be thrown from |
|
716 |
* this method. Also, after an error is reported to a handler, the callee is allowed |
|
717 |
* to abort the further processing by throwing it. If an error handler is not set, |
|
718 |
* the callee will throw the first error it finds in the sources. |
|
719 |
* |
|
720 |
* <h2>W3C XML Schema 1.0</h2> |
|
721 |
* <p> |
|
722 |
* The resulting schema contains components from the specified sources. |
|
723 |
* The same result would be achieved if all these sources were |
|
724 |
* imported, using appropriate values for schemaLocation and namespace, |
|
725 |
* into a single schema document with a different targetNamespace |
|
726 |
* and no components of its own, if the import elements were given |
|
727 |
* in the same order as the sources. Section 4.2.3 of the XML Schema |
|
728 |
* recommendation describes the options processors have in this |
|
729 |
* regard. While a processor should be consistent in its treatment of |
|
730 |
* JAXP schema sources and XML Schema imports, the behaviour between |
|
731 |
* JAXP-compliant parsers may vary; in particular, parsers may choose |
|
29999 | 732 |
* to ignore all but the first {@code <import>} for a given namespace, |
12005 | 733 |
* regardless of information provided in schemaLocation. |
734 |
* |
|
735 |
* <p> |
|
736 |
* If the parsed set of schemas includes error(s) as |
|
737 |
* specified in the section 5.1 of the XML Schema spec, then |
|
738 |
* the error must be reported to the {@link ErrorHandler}. |
|
739 |
* |
|
740 |
* <h2>RELAX NG</h2> |
|
741 |
* |
|
742 |
* <p>For RELAX NG, this method must throw {@link UnsupportedOperationException} |
|
29999 | 743 |
* if {@code schemas.length!=1}. |
12005 | 744 |
* |
745 |
* |
|
746 |
* @param schemas |
|
747 |
* inputs to be parsed. {@link SchemaFactory} is required |
|
748 |
* to recognize {@link javax.xml.transform.sax.SAXSource}, |
|
749 |
* {@link StreamSource}, |
|
750 |
* {@link javax.xml.transform.stax.StAXSource}, |
|
751 |
* and {@link javax.xml.transform.dom.DOMSource}. |
|
752 |
* Input schemas must be XML documents or |
|
753 |
* XML elements and must not be null. For backwards compatibility, |
|
754 |
* the results of passing anything other than |
|
755 |
* a document or element are implementation-dependent. |
|
756 |
* Implementations must either recognize and process the input |
|
757 |
* or thrown an IllegalArgumentException. |
|
758 |
* |
|
759 |
* @return |
|
760 |
* Always return a non-null valid {@link Schema} object. |
|
761 |
* Note that when an error has been reported, there is no |
|
762 |
* guarantee that the returned {@link Schema} object is |
|
763 |
* meaningful. |
|
764 |
* |
|
765 |
* @throws SAXException |
|
766 |
* If an error is found during processing the specified inputs. |
|
767 |
* When an {@link ErrorHandler} is set, errors are reported to |
|
768 |
* there first. See {@link #setErrorHandler(ErrorHandler)}. |
|
769 |
* @throws NullPointerException |
|
29999 | 770 |
* If the {@code schemas} parameter itself is null or |
12005 | 771 |
* any item in the array is null. |
772 |
* @throws IllegalArgumentException |
|
773 |
* If any item in the array is not recognized by this method. |
|
774 |
* @throws UnsupportedOperationException |
|
775 |
* If the schema language doesn't support this operation. |
|
776 |
*/ |
|
777 |
public abstract Schema newSchema(Source[] schemas) throws SAXException; |
|
778 |
||
779 |
/** |
|
780 |
* Creates a special {@link Schema} object. |
|
781 |
* |
|
782 |
* <p>The exact semantics of the returned {@link Schema} object |
|
783 |
* depend on the schema language for which this {@link SchemaFactory} |
|
784 |
* is created. |
|
785 |
* |
|
786 |
* <p>Also, implementations are allowed to use implementation-specific |
|
29999 | 787 |
* property/feature to alter the semantics of this method. |
12005 | 788 |
* |
789 |
* <p>Implementors and developers should pay particular attention |
|
790 |
* to how the features set on this {@link SchemaFactory} are |
|
791 |
* processed by this special {@link Schema}. |
|
792 |
* In some cases, for example, when the |
|
793 |
* {@link SchemaFactory} and the class actually loading the |
|
794 |
* schema come from different implementations, it may not be possible |
|
795 |
* for {@link SchemaFactory} features to be inherited automatically. |
|
796 |
* Developers should |
|
797 |
* make sure that features, such as secure processing, are explicitly |
|
29999 | 798 |
* set in both places. |
12005 | 799 |
* |
800 |
* <h2>W3C XML Schema 1.0</h2> |
|
801 |
* <p> |
|
802 |
* For XML Schema, this method creates a {@link Schema} object that |
|
803 |
* performs validation by using location hints specified in documents. |
|
804 |
* |
|
805 |
* <p> |
|
806 |
* The returned {@link Schema} object assumes that if documents |
|
807 |
* refer to the same URL in the schema location hints, |
|
808 |
* they will always resolve to the same schema document. This |
|
809 |
* asusmption allows implementations to reuse parsed results of |
|
810 |
* schema documents so that multiple validations against the same |
|
811 |
* schema will run faster. |
|
812 |
* |
|
813 |
* <p> |
|
814 |
* Note that the use of schema location hints introduces a |
|
815 |
* vulnerability to denial-of-service attacks. |
|
816 |
* |
|
817 |
* |
|
818 |
* <h2>RELAX NG</h2> |
|
819 |
* <p> |
|
820 |
* RELAX NG does not support this operation. |
|
821 |
* |
|
822 |
* @return |
|
823 |
* Always return non-null valid {@link Schema} object. |
|
824 |
* |
|
825 |
* @throws UnsupportedOperationException |
|
826 |
* If this operation is not supported by the callee. |
|
827 |
* @throws SAXException |
|
828 |
* If this operation is supported but failed for some reason. |
|
829 |
*/ |
|
830 |
public abstract Schema newSchema() throws SAXException; |
|
831 |
} |