/*
 * 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 org.apache.xerces.xni.grammars;

import java.io.IOException;
import java.util.Locale;

import org.apache.xerces.xni.XNIException;
import org.apache.xerces.xni.parser.XMLConfigurationException;
import org.apache.xerces.xni.parser.XMLEntityResolver;
import org.apache.xerces.xni.parser.XMLErrorHandler;
import org.apache.xerces.xni.parser.XMLInputSource;

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
Version:
$Id: XMLGrammarLoader.java 699892 2008-09-28 21:08:27Z mrglavas $/**
 * 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
 * @version $Id: XMLGrammarLoader.java 699892 2008-09-28 21:08:27Z mrglavas $
 */

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.
/**
     * 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.
Params:
featureId – The feature identifier.
Throws:
XMLConfigurationException – Thrown on configuration error./**
     * 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. 
Params:
featureId – The feature identifier.
state –     The state of the feature.
Throws:
XMLConfigurationException – Thrown when a feature is not
                 recognized or cannot be set./**
     * 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.
/**
     * 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.
Params:
propertyId – The property identifier.
Throws:
XMLConfigurationException – Thrown on configuration error./**
     * 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. 
Params:
propertyId – The property identifier.
state –     The state of the property.
Throws:
XMLConfigurationException – Thrown when a property is not
                 recognized or cannot be set./**
     * 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.
Params:
locale – The locale object to use for localization of messages.
Throws:
XNIException – Thrown if the parser does not support the
                        specified locale./**
     * 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. /** Return the Locale the XMLGrammarLoader is using. */
    public Locale getLocale();

    
Sets the error handler.
Params:
errorHandler – The error handler./**
     * Sets the error handler.
     *
     * @param errorHandler The error handler.
     */
    public void setErrorHandler(XMLErrorHandler errorHandler);

    
Returns the registered error handler.  /** Returns the registered error handler.  */
    public XMLErrorHandler getErrorHandler();

    
Sets the entity resolver.
Params:
entityResolver – The new entity resolver./**
     * Sets the entity resolver.
     *
     * @param entityResolver The new entity resolver.
     */
    public void setEntityResolver(XMLEntityResolver entityResolver);

    
Returns the registered entity resolver.  /** Returns the registered entity resolver.  */
    public XMLEntityResolver getEntityResolver();

    
Returns a Grammar object by parsing the contents of the
entity pointed to by source.
Params:
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./**
     * 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