/*
 * Reference ETL Parser for Java
 * Copyright (c) 2000-2009 Constantine A Plotnikov
 *
 * Permission is hereby granted, free of charge, to any person 
 * obtaining a copy of this software and associated documentation 
 * files (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge, 
 * publish, distribute, sublicense, and/or sell copies of the Software, 
 * and to permit persons to whom the Software is furnished to do so, 
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be 
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
 * SOFTWARE. 
 */
package net.sf.etl.parsers.internal.term_parser;

import org.xml.sax.InputSource;

/**
 * Instances of this interface are used to locate grammars.
 * 
 * @author const
 * 
 */
public interface GrammarLocator {
	/**
	 * Locate grammar for the parser
	 * 
	 * @param termParser
	 *            a parser that initiated grammar loading. All errors that
	 *            happens during grammar loading are reported on this class.
	 * @param sourceSystemId
	 *            a location of source that is being parsed. If it is null,
	 *            relative system ids for grammar location are not supported.
	 * @param grammarSystemId
	 *            a specified system id of the grammar
	 * @param grammarPublicId
	 *            a specified public id of the grammar
	 * @param requiredContext
	 *            a context that is required for the grammar or null if
	 *            availability of default context is required.
	 * @return a peer factory assoicated with grammar. If there were errors
	 *         associated with grammar, a factory for DefaultGrammarPeer is
	 *         returned.
	 */
	PeerFactory getGrammar(DefaultTermParser termParser, String sourceSystemId,
			String grammarSystemId, String grammarPublicId,
			String requiredContext);

	/**
	 * Register peer with grammar locator
	 * 
	 * @param systemId
	 *            a system id of grammar
	 * @param publicId
	 *            a public id of grammar
	 * @param factory
	 *            a factory compiled from grammar
	 */
	void registerPeer(String systemId, String publicId, PeerFactory factory);

	/**
	 * Get input source using specified parameters.
	 * 
	 * @param termParser
	 *            a term parser for source in context of which grammar is loaded
	 * @param referrerSystemId
	 *            a system id of file that refers to the grammar
	 * @param systemId
	 *            a system id by which the grammar is reffered. It might be
	 *            relative.
	 * @param publicId
	 *            a public id by which the grammar is reffered.
	 * @return an input source to use.
	 */
	InputSource resolveGrammar(DefaultTermParser termParser,
			String referrerSystemId, String systemId, String publicId);
}