1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one or more 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * contributor license agreements. See the NOTICE file distributed with 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this work for additional information regarding copyright ownership. 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The ASF licenses this file to You under the Apache License, Version 2.0 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (the "License"); you may not use this file except in compliance with 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the License. You may obtain a copy of the License at 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unless required by applicable law or agreed to in writing, software 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * See the License for the specific language governing permissions and 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * limitations under the License. 16320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 17320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 18320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson// $Id: SchemaFactory.java 884952 2009-11-27 18:55:08Z mrglavas $ 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 20320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage javax.xml.validation; 21320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 22320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport java.io.File; 23320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport java.net.URL; 24320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport javax.xml.transform.Source; 25320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport javax.xml.transform.stream.StreamSource; 26320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.w3c.dom.ls.LSResourceResolver; 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.xml.sax.ErrorHandler; 28320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.xml.sax.SAXException; 29320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.xml.sax.SAXNotRecognizedException; 30320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.xml.sax.SAXNotSupportedException; 31320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 32320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 33320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Factory that creates {@link Schema} objects. Entry-point to 34320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the validation API. 35320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 36320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link SchemaFactory} is a schema compiler. It reads external 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * representations of schemas and prepares them for validation. 39f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 40320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The {@link SchemaFactory} class is not thread-safe. In other words, 42320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it is the application's responsibility to ensure that at most 43320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * one thread is using a {@link SchemaFactory} object at any 44320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * given moment. Implementations are encouraged to mark methods 45320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * as <tt>synchronized</tt> to protect themselves from broken clients. 46f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 47320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 48320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link SchemaFactory} is not re-entrant. While one of the 49320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>newSchema</code> methods is being invoked, applications 50320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * may not attempt to recursively invoke the <code>newSchema</code> method, 51320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * even from the same thread. 52f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 53320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <h2><a name="schemaLanguage"></a>Schema Language</h2> 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This spec uses a namespace URI to designate a schema language. 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The following table shows the values defined by this specification. 57320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 58f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * To be compliant with the spec, the implementation 59320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is only required to support W3C XML Schema 1.0. However, 60320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if it chooses to support other schema languages listed here, 61320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it must conform to the relevant behaviors described in this spec. 62f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 63320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 64320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Schema languages not listed here are expected to 65f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * introduce their own URIs to represent themselves. 66320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The {@link SchemaFactory} class is capable of locating other 67320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * implementations for other schema languages at run-time. 68f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 69320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 70320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Note that because the XML DTD is strongly tied to the parsing process 71320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and has a significant effect on the parsing process, it is impossible 72f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to define the DTD validation as a process independent from parsing. 73320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * For this reason, this specification does not define the semantics for 7455b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * the XML DTD. This doesn't prohibit implementers from implementing it 75320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * in a way they see fit, but <em>users are warned that any DTD 76320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * validation implemented on this interface necessarily deviate from 77320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the XML DTD semantics as defined in the XML 1.0</em>. 78f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 79320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <table border="1" cellpadding="2"> 80320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <thead> 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 82320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <th>value</th> 83320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <th>language</th> 84320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </thead> 86320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tbody> 87320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 88320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td> 89320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td> 90320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 91320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 92320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td> 93320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td> 94320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 95320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tbody> 96320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </table> 97f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 98320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> 99320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @version $Revision: 884952 $, $Date: 2009-11-27 10:55:08 -0800 (Fri, 27 Nov 2009) $ 100320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @since 1.5 101320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 102320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic abstract class SchemaFactory { 103f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 104320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 105320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Constructor for derived classes.</p> 106f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 107320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The constructor does nothing.</p> 108f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 109320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Derived classes must create {@link SchemaFactory} objects that have 110320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>null</code> {@link ErrorHandler} and 111320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>null</code> {@link LSResourceResolver}.</p> 112320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 113320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson protected SchemaFactory() { 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 115f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 116320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 117320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified 118320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * schema language and return it.</p> 119f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 120320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>To find a <code>SchemaFactory</code> object for a given schema language, 121320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this method looks the following places in the following order 122320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * where "the class loader" refers to the context class loader:</p> 123320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <ol> 124320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 125320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the system property 126320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code> 127320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is present (where <i>schemaLanguage</i> is the parameter 128320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to this method), then its value is read 129320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * as a class name. The method will try to 130320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * create a new instance of this class by using the class loader, 131320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and returns it if it is successfully created. 132320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 133320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 134320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>$java.home/lib/jaxp.properties</code> is read and 135320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the value associated with the key being the system property above 136320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is looked for. If present, the value is processed just like above. 137320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 138320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 139320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The class loader is asked for service provider provider-configuration files matching 140320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>javax.xml.validation.SchemaFactory</code> in the resource directory META-INF/services. 141320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * See the JAR File Specification for file format and parsing rules. 142320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Each potential service provider is required to implement the method:</p> 143320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 144320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link #isSchemaLanguageSupported(String schemaLanguage)} 145f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * </pre> 146320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The first service provider found in class loader order that supports the specified schema language is returned. 147320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 148320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 149320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Platform default <code>SchemaFactory</code> is located 150320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * in a implementation specific way. There must be a platform default 151320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>SchemaFactory</code> for W3C XML Schema. 152320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 153320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </ol> 154f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 155320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p> 156f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 157320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><strong>Tip for Trouble-shooting:</strong></p> 158320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See {@link java.util.Properties#load(java.io.InputStream)} for 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * exactly how a property file is parsed. In particular, colons ':' 160320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * need to be escaped in a property file, so make sure schema language 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * URIs are properly escaped in it. For example:</p> 162320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 163320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory 164320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 165f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 166320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param schemaLanguage 167320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Specifies the schema language which the returned 168320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * SchemaFactory will understand. See 169320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <a href="#schemaLanguage">the list of available 170320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * schema languages</a> for the possible values. 171f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 172320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return New instance of a <code>SchemaFactory</code> 173f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 174320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException 175320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If no implementation of the schema language is available. 176f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 177320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException 17855b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * If the <tt>schemaLanguage</tt> parameter is null. 179320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 18055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson public static SchemaFactory newInstance(String schemaLanguage) { 181f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes ClassLoader cl; 182670c354edf01dcda0d9c4363a0996923bb30169bJesse Wilson cl = Thread.currentThread().getContextClassLoader(); 183f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 184320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (cl == null) { 185320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson //cl = ClassLoader.getSystemClassLoader(); 186320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson //use the current class loader 187320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson cl = SchemaFactory.class.getClassLoader(); 188f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 189320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 190320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage); 191320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (f == null) { 192320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new IllegalArgumentException(schemaLanguage); 193320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 194320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson return f; 195320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 196320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 19755b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson /** 19855b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * Returns an instance of the named implementation of {@code SchemaFactory}. 19955b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * 20055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * @throws IllegalArgumentException if {@code factoryClassName} is not available, cannot be 20155b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * instantiated, or doesn't support {@code schemaLanguage}. 20255b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * @since 1.6 20355b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson */ 20455b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, 20555b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson ClassLoader classLoader) { 20686acc043d3334651ee26c65467d78d6cefedd397Kenny Root if (schemaLanguage == null) { 20786acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("schemaLanguage == null"); 20886acc043d3334651ee26c65467d78d6cefedd397Kenny Root } else if (factoryClassName == null) { 20986acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("factoryClassName == null"); 21055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } 21155b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson if (classLoader == null) { 21255b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson classLoader = Thread.currentThread().getContextClassLoader(); 21355b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } 21455b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson try { 21555b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson Class<?> type = classLoader != null 21655b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson ? classLoader.loadClass(factoryClassName) 21755b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson : Class.forName(factoryClassName); 21855b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson SchemaFactory result = (SchemaFactory) type.newInstance(); 21955b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson if (result == null || !result.isSchemaLanguageSupported(schemaLanguage)) { 22055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson throw new IllegalArgumentException(schemaLanguage); 22155b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } 22255b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson return result; 22355b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } catch (ClassNotFoundException e) { 22455b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson throw new IllegalArgumentException(e); 22555b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } catch (InstantiationException e) { 22655b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson throw new IllegalArgumentException(e); 22755b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } catch (IllegalAccessException e) { 22855b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson throw new IllegalArgumentException(e); 22955b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } 23055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson } 231f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 232d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes /** 233d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>Is specified schema supported by this <code>SchemaFactory</code>?</p> 234f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 235d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @param schemaLanguage Specifies the schema language which the returned <code>SchemaFactory</code> will understand. 236320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>schemaLanguage</code> must specify a <a href="#schemaLanguage">valid</a> schema language. 237f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 238d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @return <code>true</code> if <code>SchemaFactory</code> supports <code>schemaLanguage</code>, else <code>false</code>. 239f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 240d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @throws NullPointerException If <code>schemaLanguage</code> is <code>null</code>. 241d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @throws IllegalArgumentException If <code>schemaLanguage.length() == 0</code> 242f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * or <code>schemaLanguage</code> does not specify a <a href="#schemaLanguage">valid</a> schema language. 243f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes */ 244d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes public abstract boolean isSchemaLanguageSupported(String schemaLanguage); 245320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 246320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 247320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Look up the value of a feature flag. 248320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 249320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The feature name is any fully-qualified URI. It is 250320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * possible for a {@link SchemaFactory} to recognize a feature name but 251320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * temporarily be unable to return its value. 252320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 25355b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * <p>Implementers are free (and encouraged) to invent their own features, 254320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * using names built on their own URIs.</p> 255320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 256320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param name The feature name, which is a non-null fully-qualified URI. 257320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The current value of the feature (true or false). 258320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotRecognizedException If the feature 259320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * value can't be assigned or retrieved. 260320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotSupportedException When the 261f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * {@link SchemaFactory} recognizes the feature name but 262320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * cannot determine its value at this time. 263320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception NullPointerException 264320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if the name parameter is null. 265320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see #setFeature(String, boolean) 266320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 267320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException { 268f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 269320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (name == null) { 27086acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("name == null"); 271f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 272320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new SAXNotRecognizedException(name); 273320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 274f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 275320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 276320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Set the value of a feature flag. 277320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 278320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 279320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Feature can be used to control the way a {@link SchemaFactory} 280320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * parses schemas, although {@link SchemaFactory}s are not required 281320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to recognize any specific feature names.</p> 282320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 283320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The feature name is any fully-qualified URI. It is 284320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * possible for a {@link SchemaFactory} to expose a feature value but 285320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to be unable to change the current value.</p> 286320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 287d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. 288d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * When the feature is:</p> 289d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <ul> 290d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <li> 291d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <code>true</code>: the implementation will limit XML processing to conform to implementation limits. 292d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources. 293d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * If XML processing is limited for security reasons, it will be reported via a call to the registered 29455b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * {@link ErrorHandler#fatalError(org.xml.sax.SAXParseException)}. 295d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * See {@link #setErrorHandler(ErrorHandler errorHandler)}. 296d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * </li> 297d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <li> 298d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <code>false</code>: the implementation will processing XML according to the XML specifications without 299d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * regard to possible implementation limits. 300d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * </li> 301d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * </ul> 302f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 303320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param name The feature name, which is a non-null fully-qualified URI. 304320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param value The requested value of the feature (true or false). 305f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 306320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotRecognizedException If the feature 307320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * value can't be assigned or retrieved. 308320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotSupportedException When the 309f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * {@link SchemaFactory} recognizes the feature name but 310320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * cannot set the requested value. 311320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception NullPointerException 312320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if the name parameter is null. 313f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 314320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see #getFeature(String) 315320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 316320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setFeature(String name, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException { 317320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (name == null) { 31886acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("name == null"); 319f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 320320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new SAXNotRecognizedException(name); 321320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 322f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 323320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 324320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Set the value of a property. 325320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 326320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The property name is any fully-qualified URI. It is 327320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * possible for a {@link SchemaFactory} to recognize a property name but 328320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to be unable to change the current value.</p> 329320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 330320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>{@link SchemaFactory}s are not required to recognize setting 331320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * any specific property names.</p> 332320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 333320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param name The property name, which is a non-null fully-qualified URI. 334320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param object The requested value for the property. 335320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotRecognizedException If the property 336320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * value can't be assigned or retrieved. 337320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotSupportedException When the 338f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * {@link SchemaFactory} recognizes the property name but 339320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * cannot set the requested value. 340320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception NullPointerException 341320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if the name parameter is null. 342320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 343320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setProperty(String name, Object object) throws SAXNotRecognizedException, SAXNotSupportedException { 344320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (name == null) { 34586acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("name == null"); 346f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 347320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new SAXNotRecognizedException(name); 348320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 349f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 350320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 351320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Look up the value of a property. 352320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 353320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The property name is any fully-qualified URI. It is 354320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * possible for a {@link SchemaFactory} to recognize a property name but 355320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * temporarily be unable to return its value.</p> 356320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 357320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>{@link SchemaFactory}s are not required to recognize any specific 358320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * property names.</p> 359320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 36055b2d1c3f492f6140ad6dd18a4bec4ec2643d664Jesse Wilson * <p>Implementers are free (and encouraged) to invent their own properties, 361320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * using names built on their own URIs.</p> 362320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 363320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param name The property name, which is a non-null fully-qualified URI. 364320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The current value of the property. 365320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotRecognizedException If the property 366320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * value can't be assigned or retrieved. 367320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception org.xml.sax.SAXNotSupportedException When the 368f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * XMLReader recognizes the property name but 369320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * cannot determine its value at this time. 370320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception NullPointerException 371320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if the name parameter is null. 372320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see #setProperty(String, Object) 373320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 374320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException { 375320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (name == null) { 37686acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("name == null"); 377f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 378320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new SAXNotRecognizedException(name); 379320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 380f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 381320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 382320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Sets the {@link ErrorHandler} to receive errors encountered 383320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * during the <code>newSchema</code> method invocation. 384f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 385320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 386320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Error handler can be used to customize the error handling process 387320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * during schema parsing. When an {@link ErrorHandler} is set, 388320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * errors found during the parsing of schemas will be first sent 389320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to the {@link ErrorHandler}. 390f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 391320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 392320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The error handler can abort the parsing of a schema immediately 393320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * by throwing {@link SAXException} from the handler. Or for example 394320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it can print an error to the screen and try to continue the 395f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * processing by returning normally from the {@link ErrorHandler} 396f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 397320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 398320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If any {@link Throwable} (or instances of its derived classes) 399320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is thrown from an {@link ErrorHandler}, 400320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the caller of the <code>newSchema</code> method will be thrown 401320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the same {@link Throwable} object. 402f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 403320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 404320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link SchemaFactory} is not allowed to 405320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * throw {@link SAXException} without first reporting it to 406320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link ErrorHandler}. 407f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 408320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 409320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Applications can call this method even during a {@link Schema} 410f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is being parsed. 411f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 412320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 413320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When the {@link ErrorHandler} is null, the implementation will 414320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * behave as if the following {@link ErrorHandler} is set: 415320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 416320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * class DraconianErrorHandler implements {@link ErrorHandler} { 417320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 418320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * throw e; 419320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 420320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 421320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * throw e; 422320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 423320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 424320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * // noop 425320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 426320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 427320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 428f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 429320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 430320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When a new {@link SchemaFactory} object is created, initially 431320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this field is set to null. This field will <em>NOT</em> be 432f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inherited to {@link Schema}s, {@link Validator}s, or 433320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. 434f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 435f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 436320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param errorHandler 437320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * A new error handler to be set. This parameter can be null. 438320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 439320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract void setErrorHandler(ErrorHandler errorHandler); 440f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 441320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 442320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}. 443f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 444320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return 445320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This method returns the object that was last set through 446320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the {@link #setErrorHandler(ErrorHandler)} method, or null 447320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if that method has never been called since this {@link SchemaFactory} 448320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * has created. 449f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 450320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see #setErrorHandler(ErrorHandler) 451320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 452320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract ErrorHandler getErrorHandler(); 453f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 454320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 455320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Sets the {@link LSResourceResolver} to customize 456320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * resource resolution when parsing schemas. 457f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 458320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 459320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link SchemaFactory} uses a {@link LSResourceResolver} 460320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * when it needs to locate external resources while parsing schemas, 461320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * although exactly what constitutes "locating external resources" is 462320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * up to each schema language. For example, for W3C XML Schema, 463320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this includes files <tt><include></tt>d or <tt><import></tt>ed, 464320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and DTD referenced from schema files, etc. 465f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 466320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 467320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Applications can call this method even during a {@link Schema} 468f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is being parsed. 469f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 470320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 471320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When the {@link LSResourceResolver} is null, the implementation will 472320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * behave as if the following {@link LSResourceResolver} is set: 473320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 474320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * class DumbDOMResourceResolver implements {@link LSResourceResolver} { 475320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * public {@link org.w3c.dom.ls.LSInput} resolveResource( 476320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * String publicId, String systemId, String baseURI) { 477f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 478320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * return null; // always return null 479320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 480320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * } 481320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 482f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 483320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 484320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If a {@link LSResourceResolver} throws a {@link RuntimeException} 485320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (or instances of its derived classes), 486f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * then the {@link SchemaFactory} will abort the parsing and 487320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the caller of the <code>newSchema</code> method will receive 488f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the same {@link RuntimeException}. 489f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 490320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 491320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When a new {@link SchemaFactory} object is created, initially 492320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this field is set to null. This field will <em>NOT</em> be 493f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inherited to {@link Schema}s, {@link Validator}s, or 494320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. 495f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 496320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param resourceResolver 497320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * A new resource resolver to be set. This parameter can be null. 498320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 499320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract void setResourceResolver(LSResourceResolver resourceResolver); 500f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 501320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 502320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}. 503f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 504320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return 505320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This method returns the object that was last set through 506320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the {@link #setResourceResolver(LSResourceResolver)} method, or null 507320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if that method has never been called since this {@link SchemaFactory} 508320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * has created. 509f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 510320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see #setErrorHandler(ErrorHandler) 511320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 512320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract LSResourceResolver getResourceResolver(); 513f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 514320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 515320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Parses the specified source as a schema and returns it as a schema.</p> 516f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 517320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.</p> 518f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 519320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param schema Source that represents a schema. 520f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 521320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return New <code>Schema</code> from parsing <code>schema</code>. 522f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 523320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws SAXException If a SAX error occurs during parsing. 524320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException if <tt>schema</tt> is null. 525320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 526320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Schema newSchema(Source schema) throws SAXException { 527d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes return newSchema(new Source[]{schema}); 528320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 529f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 530320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 531320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Parses the specified <code>File</code> as a schema and returns it as a <code>Schema</code>.</p> 532f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 533320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p> 534f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 535320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param schema File that represents a schema. 536f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 537320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return New <code>Schema</code> from parsing <code>schema</code>. 538f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 539320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws SAXException If a SAX error occurs during parsing. 540320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException if <tt>schema</tt> is null. 541320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 542320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Schema newSchema(File schema) throws SAXException { 543320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson return newSchema(new StreamSource(schema)); 544320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 545f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 546320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 547320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Parses the specified <code>URL</code> as a schema and returns it as a <code>Schema</code>.</p> 548f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 549320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p> 550f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 551320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param schema <code>URL</code> that represents a schema. 552f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 553320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return New <code>Schema</code> from parsing <code>schema</code>. 554f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 555320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws SAXException If a SAX error occurs during parsing. 556320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException if <tt>schema</tt> is null. 557320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 558320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Schema newSchema(URL schema) throws SAXException { 559320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson return newSchema(new StreamSource(schema.toExternalForm())); 560320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 561f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 562320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 563320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Parses the specified source(s) as a schema and returns it as a schema. 564f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 565320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 566320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The callee will read all the {@link Source}s and combine them into a 567320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * single schema. The exact semantics of the combination depends on the schema 568320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * language that this {@link SchemaFactory} object is created for. 569f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 570320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 571320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When an {@link ErrorHandler} is set, the callee will report all the errors 572320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * found in sources to the handler. If the handler throws an exception, it will 573320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * abort the schema compilation and the same exception will be thrown from 574320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this method. Also, after an error is reported to a handler, the callee is allowed 575320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to abort the further processing by throwing it. If an error handler is not set, 576f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the callee will throw the first error it finds in the sources. 577f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 578320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <h2>W3C XML Schema 1.0</h2> 579320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 580320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The resulting schema contains components from the specified sources. 581320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The same result would be achieved if all these sources were 582320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * imported, using appropriate values for schemaLocation and namespace, 583320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * into a single schema document with a different targetNamespace 584320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and no components of its own, if the import elements were given 585320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * in the same order as the sources. Section 4.2.3 of the XML Schema 586320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * recommendation describes the options processors have in this 587320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * regard. While a processor should be consistent in its treatment of 5885501a3d4b3d7657c183ed5446fe67fa011fbf70bElliott Hughes * JAXP schema sources and XML Schema imports, the behavior between 589320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * JAXP-compliant parsers may vary; in particular, parsers may choose 590320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to ignore all but the first <import> for a given namespace, 591320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * regardless of information provided in schemaLocation. 592f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 593320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 594320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the parsed set of schemas includes error(s) as 595320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * specified in the section 5.1 of the XML Schema spec, then 596320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the error must be reported to the {@link ErrorHandler}. 597f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 598320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <h2>RELAX NG</h2> 599f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 600320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>For RELAX NG, this method must throw {@link UnsupportedOperationException} 601f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * if <tt>schemas.length!=1</tt>. 602f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 603f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 604320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param schemas 605320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * inputs to be parsed. {@link SchemaFactory} is required 606f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to recognize {@link StreamSource}, 607320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link javax.xml.transform.sax.SAXSource}, 608320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and {@link javax.xml.transform.dom.DOMSource}. 609f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 610320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return 611320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Always return a non-null valid {@link Schema} object. 612320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Note that when an error has been reported, there is no 613320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * guarantee that the returned {@link Schema} object is 614320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * meaningful. 615f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 616320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws SAXException 617320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If an error is found during processing the specified inputs. 618320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When an {@link ErrorHandler} is set, errors are reported to 619320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * there first. See {@link #setErrorHandler(ErrorHandler)}. 620320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException 621320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the <code>schemas</code> parameter itself is null or 622320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * any item in the array is null. 623320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException 624f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * If any item in the array is not recognized by this method. 625320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws UnsupportedOperationException 626320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the schema language doesn't support this operation. 627320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 628320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract Schema newSchema(Source[] schemas) throws SAXException; 629f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 630320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 631320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Creates a special {@link Schema} object. 632f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 633320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 634320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The exact semantics of the returned {@link Schema} object depends 635320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * on the schema language that this {@link SchemaFactory} is created 636320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * for. 637f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 638320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 639320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Also, implementations are allowed to use implementation-specific 640320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * property/feature to alter the semantics of this method. 641f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 642f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 643320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <h2>W3C XML Schema 1.0</h2> 644320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 645320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * For XML Schema, this method creates a {@link Schema} object that 646320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * performs validation by using location hints specified in documents. 647f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 648320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 649320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The returned {@link Schema} object assumes that if documents 650320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * refer to the same URL in the schema location hints, 651320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * they will always resolve to the same schema document. This 652320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * assumption allows implementations to reuse parsed results of 653320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * schema documents so that multiple validations against the same 654320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * schema will run faster. 655f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 656320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 657320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Note that the use of schema location hints introduces a 658f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * vulnerability to denial-of-service attacks. 659f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 660f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 661320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <h2>RELAX NG</h2> 662320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 663f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * RELAX NG does not support this operation. 664f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 665320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return 666320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Always return non-null valid {@link Schema} object. 667f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 668320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws UnsupportedOperationException 669320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If this operation is not supported by the callee. 670320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws SAXException 671320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If this operation is supported but failed for some reason. 672320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 673320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract Schema newSchema() throws SAXException; 674320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 675