/*

 * reserved comment block

 * DO NOT REMOVE OR ALTER!

 */

/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You under the Apache License, Version 2.0

 * (the "License"); you may not use this file except in compliance with

 * the License.  You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.sun.org.apache.xerces.internal.xni.grammars;

import com.sun.org.apache.xerces.internal.xni.parser.XMLConfigurationException;

import com.sun.org.apache.xerces.internal.xni.parser.XMLErrorHandler;

import com.sun.org.apache.xerces.internal.xni.parser.XMLEntityResolver;

import com.sun.org.apache.xerces.internal.xni.parser.XMLInputSource;

import com.sun.org.apache.xerces.internal.xni.XNIException;

import java.io.IOException;

import java.util.Locale;

/**

 * The intention of this interface is to provide a generic means

 * by which Grammar objects may be created without parsing instance

 * documents.  Implementations of this interface will know how to load

 * specific types of grammars (e.g., DTD's or schemas); a wrapper

 * will be provided for user applications to interact with these implementations.

 *

 * @author Neil Graham, IBM

 */

public interface XMLGrammarLoader {

    /**

     * Returns a list of feature identifiers that are recognized by

     * this XMLGrammarLoader.  This method may return null if no features

     * are recognized.

     */

    public String[] getRecognizedFeatures();

    /**

     * Returns the state of a feature.

     *

     * @param featureId The feature identifier.

     *

     * @throws XMLConfigurationException Thrown on configuration error.

     */

    public boolean getFeature(String featureId)

            throws XMLConfigurationException;

    /**

     * Sets the state of a feature.

     *

     * @param featureId The feature identifier.

     * @param state     The state of the feature.

     *

     * @throws XMLConfigurationException Thrown when a feature is not

     *                  recognized or cannot be set.

     */

    public void setFeature(String featureId,

                boolean state) throws XMLConfigurationException;

    /**

     * Returns a list of property identifiers that are recognized by

     * this XMLGrammarLoader.  This method may return null if no properties

     * are recognized.

     */

    public String[] getRecognizedProperties();

    /**

     * Returns the state of a property.

     *

     * @param propertyId The property identifier.

     *

     * @throws XMLConfigurationException Thrown on configuration error.

     */

    public Object getProperty(String propertyId)

            throws XMLConfigurationException;

    /**

     * Sets the state of a property.

     *

     * @param propertyId The property identifier.

     * @param state     The state of the property.

     *

     * @throws XMLConfigurationException Thrown when a property is not

     *                  recognized or cannot be set.

     */

    public void setProperty(String propertyId,

                Object state) throws XMLConfigurationException;

    /**

     * Set the locale to use for messages.

     *

     * @param locale The locale object to use for localization of messages.

     *

     * @exception XNIException Thrown if the parser does not support the

     *                         specified locale.

     */

    public void setLocale(Locale locale);

    /** Return the Locale the XMLGrammarLoader is using. */

    public Locale getLocale();

    /**

     * Sets the error handler.

     *

     * @param errorHandler The error handler.

     */

    public void setErrorHandler(XMLErrorHandler errorHandler);

    /** Returns the registered error handler.  */

    public XMLErrorHandler getErrorHandler();

    /**

     * Sets the entity resolver.

     *

     * @param entityResolver The new entity resolver.

     */

    public void setEntityResolver(XMLEntityResolver entityResolver);

    /** Returns the registered entity resolver.  */

    public XMLEntityResolver getEntityResolver();

    /**

     * Returns a Grammar object by parsing the contents of the

     * entity pointed to by source.

     *

     * @param source        the location of the entity which forms

     *                          the starting point of the grammar to be constructed.

     * @throws IOException      When a problem is encountered reading the entity

     *          XNIException    When a condition arises (such as a FatalError) that requires parsing

     *                              of the entity be terminated.

     */

    public Grammar loadGrammar(XMLInputSource source)

        throws IOException, XNIException;

} // XMLGrammarLoader