/*

 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.xml.validation;

import java.io.File;

import java.net.URL;

import javax.xml.transform.Source;

import javax.xml.transform.stream.StreamSource;

import org.w3c.dom.ls.LSResourceResolver;

import org.xml.sax.ErrorHandler;

import org.xml.sax.SAXException;

import org.xml.sax.SAXNotRecognizedException;

import org.xml.sax.SAXNotSupportedException;

import org.xml.sax.SAXParseException;

/**

 * Factory that creates {@link Schema} objects. Entry-point to

 * the validation API.

 *

 * <p>

 * {@link SchemaFactory} is a schema compiler. It reads external

 * representations of schemas and prepares them for validation.

 *

 * <p>

 * The {@link SchemaFactory} class is not thread-safe. In other words,

 * it is the application's responsibility to ensure that at most

 * one thread is using a {@link SchemaFactory} object at any

 * given moment. Implementations are encouraged to mark methods

 * as <code>synchronized</code> to protect themselves from broken clients.

 *

 * <p>

 * {@link SchemaFactory} is not re-entrant. While one of the

 * <code>newSchema</code> methods is being invoked, applications

 * may not attempt to recursively invoke the <code>newSchema</code> method,

 * even from the same thread.

 *

 * <h2><a name="schemaLanguage"></a>Schema Language</h2>

 * <p>

 * This spec uses a namespace URI to designate a schema language.

 * The following table shows the values defined by this specification.

 * <p>

 * To be compliant with the spec, the implementation

 * is only required to support W3C XML Schema 1.0. However,

 * if it chooses to support other schema languages listed here,

 * it must conform to the relevant behaviors described in this spec.

 *

 * <p>

 * Schema languages not listed here are expected to

 * introduce their own URIs to represent themselves.

 * The {@link SchemaFactory} class is capable of locating other

 * implementations for other schema languages at run-time.

 *

 * <p>

 * Note that because the XML DTD is strongly tied to the parsing process

 * and has a significant effect on the parsing process, it is impossible

 * to define the DTD validation as a process independent from parsing.

 * For this reason, this specification does not define the semantics for

 * the XML DTD. This doesn't prohibit implementors from implementing it

 * in a way they see fit, but <em>users are warned that any DTD

 * validation implemented on this interface necessarily deviate from

 * the XML DTD semantics as defined in the XML 1.0</em>.

 *

 * <table border="1" cellpadding="2">

 *   <thead>

 *     <tr>

 *       <th>value</th>

 *       <th>language</th>

 *     </tr>

 *   </thead>

 *   <tbody>

 *     <tr>

 *       <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td>

 *       <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>

 *     </tr>

 *     <tr>

 *       <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td>

 *       <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>

 *     </tr>

 *   </tbody>

 * </table>

 *

 * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>

 * @author  <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>

 *

 * @since 1.5

 */

public abstract class SchemaFactory {

     private static SecuritySupport ss = new SecuritySupport();

    /**

     * <p>Constructor for derived classes.</p>

     *

     * <p>The constructor does nothing.</p>

     *

     * <p>Derived classes must create {@link SchemaFactory} objects that have

     * <code>null</code> {@link ErrorHandler} and

     * <code>null</code> {@link LSResourceResolver}.</p>

     */

    protected SchemaFactory() {

    }

    /**

     * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified

     * schema language and return it.</p>

     *

     * <p>To find a <code>SchemaFactory</code> object for a given schema language,

     * this method looks the following places in the following order

     * where "the class loader" refers to the context class loader:</p>

     * <ol>

     *  <li>

     *     If the system property

     *     <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>

     *     is present (where <i>schemaLanguage</i> is the parameter

     *     to this method), then its value is read

     *     as a class name. The method will try to

     *     create a new instance of this class by using the class loader,

     *     and returns it if it is successfully created.

     *   </li>

     *   <li>

     *     <code>$java.home/lib/jaxp.properties</code> is read and

     *     the value associated with the key being the system property above

     *     is looked for. If present, the value is processed just like above.

     *   </li>

     *   <li>

     *   Use the service-provider loading facilities, defined by the

     *   {@link java.util.ServiceLoader} class, to attempt to locate and load an

     *   implementation of the service using the {@linkplain

     *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:

     *   the service-provider loading facility will use the {@linkplain

     *   java.lang.Thread#getContextClassLoader() current thread's context class loader}

     *   to attempt to load the service. If the context class

     *   loader is null, the {@linkplain

     *   ClassLoader#getSystemClassLoader() system class loader} will be used.

     *   <br>

     *   Each potential service provider is required to implement the method

     *        {@link #isSchemaLanguageSupported(String schemaLanguage)}.

     *   <br>

     *   The first service provider found that supports the specified schema

     *   language is returned.

     *   <br>

     *   In case of {@link java.util.ServiceConfigurationError} a

     *   {@link SchemaFactoryConfigurationError} will be thrown.

     *   </li>

     *   <li>

     *     Platform default <code>SchemaFactory</code> is located

     *     in a implementation specific way. There must be a platform default

     *     <code>SchemaFactory</code> for W3C XML Schema.

     *   </li>

     * </ol>

     *

     * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>

     *

     * <p><strong>Tip for Trouble-shooting:</strong></p>

     * <p>See {@link java.util.Properties#load(java.io.InputStream)} for

     * exactly how a property file is parsed. In particular, colons ':'

     * need to be escaped in a property file, so make sure schema language

     * URIs are properly escaped in it. For example:</p>

     * <pre>

     * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory

     * </pre>

     *

     * @param schemaLanguage

     *      Specifies the schema language which the returned

     *      SchemaFactory will understand. See

     *      <a href="#schemaLanguage">the list of available

     *      schema languages</a> for the possible values.

     *

     * @return New instance of a <code>SchemaFactory</code>

     *

     * @throws IllegalArgumentException

     *      If no implementation of the schema language is available.

     * @throws NullPointerException

     *      If the <code>schemaLanguage</code> parameter is null.

     * @throws SchemaFactoryConfigurationError

     *      If a configuration error is encountered.

     *

     * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

     */

    public static SchemaFactory newInstance(String schemaLanguage) {

        ClassLoader cl;

        cl = ss.getContextClassLoader();

        if (cl == null) {

            //cl = ClassLoader.getSystemClassLoader();

            //use the current class loader

            cl = SchemaFactory.class.getClassLoader();

        }

        SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);

        if (f == null) {

            throw new IllegalArgumentException(

                    "No SchemaFactory"

                    + " that implements the schema language specified by: " + schemaLanguage

                    + " could be loaded");

        }

        return f;

    }

    /**

     * <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code>

     * is returned if specified factory class name supports the specified schema language.

     * This function is useful when there are multiple providers in the classpath.

     * It gives more control to the application as it can specify which provider

     * should be loaded.</p>

     *

     * <h2>Tip for Trouble-shooting</h2>

     * <p>Setting the <code>jaxp.debug</code> system property will cause

     * this method to print a lot of debug messages

     * to <code>System.err</code> about what it is doing and where it is looking at.</p>

     *

     * <p> If you have problems try:</p>

     * <pre>

     * java -Djaxp.debug=1 YourProgram ....

     * </pre>

     *

     * @param schemaLanguage Specifies the schema language which the returned

     *                          <code>SchemaFactory</code> will understand. See

     *                          <a href="#schemaLanguage">the list of available

     *                          schema languages</a> for the possible values.

     *

     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.validation.SchemaFactory</code>.

     *

     * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>

     *                     current <code>Thread</code>'s context classLoader is used to load the factory class.

     *

     * @return New instance of a <code>SchemaFactory</code>

     *

     * @throws IllegalArgumentException

     *                   if <code>factoryClassName</code> is <code>null</code>, or

     *                   the factory class cannot be loaded, instantiated or doesn't

     *                   support the schema language specified in <code>schemLanguage</code>

     *                   parameter.

     *

     * @throws NullPointerException

     *      If the <code>schemaLanguage</code> parameter is null.

     *

     * @see #newInstance(String schemaLanguage)

     *

     * @since 1.6

     */

    public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader){

        ClassLoader cl = classLoader;

        if (cl == null) {

            cl = ss.getContextClassLoader();

        }

        SchemaFactory f = new SchemaFactoryFinder(cl).createInstance(factoryClassName);

        if (f == null) {

            throw new IllegalArgumentException(

                    "Factory " + factoryClassName

                    + " could not be loaded to implement the schema language specified by: " + schemaLanguage);

        }

        //if this factory supports the given schemalanguage return this factory else thrown exception

        if(f.isSchemaLanguageSupported(schemaLanguage)){

            return f;

        }else{

            throw new IllegalArgumentException(

                    "Factory " + f.getClass().getName()

                    + " does not implement the schema language specified by: " + schemaLanguage);

        }

    }

    /**

     * <p>Is specified schema supported by this <code>SchemaFactory</code>?</p>

     *

     * @param schemaLanguage Specifies the schema language which the returned <code>SchemaFactory</code> will understand.

     *    <code>schemaLanguage</code> must specify a <a href="#schemaLanguage">valid</a> schema language.

     *

     * @return <code>true</code> if <code>SchemaFactory</code> supports <code>schemaLanguage</code>, else <code>false</code>.

     *

     * @throws NullPointerException If <code>schemaLanguage</code> is <code>null</code>.

     * @throws IllegalArgumentException If <code>schemaLanguage.length() == 0</code>

     *   or <code>schemaLanguage</code> does not specify a <a href="#schemaLanguage">valid</a> schema language.

     */

    public abstract boolean isSchemaLanguageSupported(String schemaLanguage);

    /**

     * Look up the value of a feature flag.

     *

     * <p>The feature name is any fully-qualified URI.  It is

     * possible for a {@link SchemaFactory} to recognize a feature name but

     * temporarily be unable to return its value.

     *

     * <p>Implementors are free (and encouraged) to invent their own features,

     * using names built on their own URIs.</p>

     *

     * @param name The feature name, which is a non-null fully-qualified URI.

     *

     * @return The current value of the feature (true or false).

     *

     * @throws SAXNotRecognizedException If the feature

     *   value can't be assigned or retrieved.

     * @throws SAXNotSupportedException When the

     *   {@link SchemaFactory} recognizes the feature name but

     *   cannot determine its value at this time.

     * @throws NullPointerException If <code>name</code> is <code>null</code>.

     *

     * @see #setFeature(String, boolean)

     */

    public boolean getFeature(String name)

        throws SAXNotRecognizedException, SAXNotSupportedException {

        if (name == null) {

                throw new NullPointerException("the name parameter is null");

        }

        throw new SAXNotRecognizedException(name);

    }

    /**

     * <p>Set a feature for this <code>SchemaFactory</code>,

     * {@link Schema}s created by this factory, and by extension,

     * {@link Validator}s and {@link ValidatorHandler}s created by

     * those {@link Schema}s.

     * </p>

     *

     * <p>Implementors and developers should pay particular attention

     * to how the special {@link Schema} object returned by {@link

     * #newSchema()} is processed. In some cases, for example, when the

     * <code>SchemaFactory</code> and the class actually loading the

     * schema come from different implementations, it may not be possible

     * for <code>SchemaFactory</code> features to be inherited automatically.

     * Developers should

     * make sure that features, such as secure processing, are explicitly

     * set in both places.</p>

     *

     * <p>The feature name is any fully-qualified URI. It is

     * possible for a {@link SchemaFactory} to expose a feature value but

     * to be unable to change the current value.</p>

     *

     * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.

     * When the feature is:</p>

     * <ul>

     *   <li>

     *     <code>true</code>: the implementation will limit XML processing to conform to implementation limits.

     *     If XML processing is limited for security reasons, it will be reported via a call to the registered

     *    {@link ErrorHandler#fatalError(SAXParseException exception)}.

     *     See {@link #setErrorHandler(ErrorHandler errorHandler)}.

     *   </li>

     *   <li>

     *     <code>false</code>: the implementation will processing XML according to the XML specifications without

     *     regard to possible implementation limits.

     *   </li>

     * </ul>

     *

     * @param name The feature name, which is a non-null fully-qualified URI.

     * @param value The requested value of the feature (true or false).

     *

     * @throws SAXNotRecognizedException If the feature

     *   value can't be assigned or retrieved.

     * @throws SAXNotSupportedException When the

     *   {@link SchemaFactory} recognizes the feature name but

     *   cannot set the requested value.

     * @throws NullPointerException If <code>name</code> is <code>null</code>.

     *

     * @see #getFeature(String)

     */

    public void setFeature(String name, boolean value)

        throws SAXNotRecognizedException, SAXNotSupportedException {

        if (name == null) {

                throw new NullPointerException("the name parameter is null");

        }

        throw new SAXNotRecognizedException(name);

    }

    /**

     * Set the value of a property.

     *

     * <p>The property name is any fully-qualified URI.  It is

     * possible for a {@link SchemaFactory} to recognize a property name but

     * to be unable to change the current value.</p>

     *

     * <p>

     * All implementations that implement JAXP 1.5 or newer are required to

     * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and

     * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.

     * </p>

     * <ul>

     *   <li>

     *      <p>Access to external DTDs in Schema files is restricted to the protocols

     *      specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.

     *      If access is denied during the creation of new Schema due to the restriction

     *      of this property, {@link org.xml.sax.SAXException} will be thrown by the

     *      {@link #newSchema(Source)} or {@link #newSchema(File)}

     *      or {@link #newSchema(URL)} or  or {@link #newSchema(Source[])} method.</p>

     *

     *      <p>Access to external DTDs in xml source files is restricted to the protocols

     *      specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.

     *      If access is denied during validation due to the restriction

     *      of this property, {@link org.xml.sax.SAXException} will be thrown by the

     *      {@link javax.xml.validation.Validator#validate(Source)} or

     *      {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p>

     *

     *      <p>Access to external reference set by the schemaLocation attribute is

     *      restricted to the protocols specified by the

     *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.

     *      If access is denied during validation due to the restriction of this property,

     *      {@link org.xml.sax.SAXException} will be thrown by the

     *      {@link javax.xml.validation.Validator#validate(Source)} or

     *      {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p>

     *

     *      <p>Access to external reference set by the Import

     *      and Include element is restricted to the protocols specified by the

     *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.

     *      If access is denied during the creation of new Schema due to the restriction

     *      of this property, {@link org.xml.sax.SAXException} will be thrown by the

     *      {@link #newSchema(Source)} or {@link #newSchema(File)}

     *      or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.</p>

     *   </li>

     * </ul>

     *

     * @param name The property name, which is a non-null fully-qualified URI.

     * @param object The requested value for the property.

     *

     * @throws SAXNotRecognizedException If the property

     *   value can't be assigned or retrieved.

     * @throws SAXNotSupportedException When the

     *   {@link SchemaFactory} recognizes the property name but

     *   cannot set the requested value.

     * @throws NullPointerException If <code>name</code> is <code>null</code>.

     */

    public void setProperty(String name, Object object)

        throws SAXNotRecognizedException, SAXNotSupportedException {

        if (name == null) {

                throw new NullPointerException("the name parameter is null");

        }

        throw new SAXNotRecognizedException(name);

    }

    /**

     * Look up the value of a property.

     *

     * <p>The property name is any fully-qualified URI.  It is

     * possible for a {@link SchemaFactory} to recognize a property name but

     * temporarily be unable to return its value.</p>

     *

     * <p>{@link SchemaFactory}s are not required to recognize any specific

     * property names.</p>

     *

     * <p>Implementors are free (and encouraged) to invent their own properties,

     * using names built on their own URIs.</p>

     *

     * @param name The property name, which is a non-null fully-qualified URI.

     *

     * @return The current value of the property.

     *

     * @throws SAXNotRecognizedException If the property

     *   value can't be assigned or retrieved.

     * @throws SAXNotSupportedException When the

     *   XMLReader recognizes the property name but

     *   cannot determine its value at this time.

     * @throws NullPointerException If <code>name</code> is <code>null</code>.

     *

     * @see #setProperty(String, Object)

     */

    public Object getProperty(String name)

        throws SAXNotRecognizedException, SAXNotSupportedException {

        if (name == null) {

                throw new NullPointerException("the name parameter is null");

        }

        throw new SAXNotRecognizedException(name);

    }

    /**

     * Sets the {@link ErrorHandler} to receive errors encountered

     * during the <code>newSchema</code> method invocation.

     *

     * <p>

     * Error handler can be used to customize the error handling process

     * during schema parsing. When an {@link ErrorHandler} is set,

     * errors found during the parsing of schemas will be first sent

     * to the {@link ErrorHandler}.

     *

     * <p>

     * The error handler can abort the parsing of a schema immediately

     * by throwing {@link SAXException} from the handler. Or for example

     * it can print an error to the screen and try to continue the

     * processing by returning normally from the {@link ErrorHandler}

     *

     * <p>

     * If any {@link Throwable} (or instances of its derived classes)

     * is thrown from an {@link ErrorHandler},

     * the caller of the <code>newSchema</code> method will be thrown

     * the same {@link Throwable} object.

     *

     * <p>

     * {@link SchemaFactory} is not allowed to

     * throw {@link SAXException} without first reporting it to

     * {@link ErrorHandler}.

     *

     * <p>

     * Applications can call this method even during a {@link Schema}

     * is being parsed.