/*
 * 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;

import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;

/**
 * This interface contains common operations for all parsers. The interface is
 * intentionally different from iterator interface. In addition to operation
 * specified here, there is an additional operation "current()" that returns the
 * current token.
 * 
 * Note that parsers do not read anything from the stream when they are created.
 * 
 * @author const
 * @param <TokenType>
 *            a type for the token
 */
public interface AbstractParser<TokenType extends AbstractToken> {

	/**
	 * @return true if partial tokens are reported
	 */
	boolean arePartialTokensReported();

	/**
	 * This method allows specifying if partial tokens are reported. If the
	 * value true, then for multiline tokens like
	 * {@link Tokens#MULTILINE_STRING} the tokens
	 * {@link Tokens#MULTILINE_STRING_START},
	 * {@link Tokens#MULTILINE_STRING_PART}, and
	 * {@link Tokens#MULTILINE_STRING_END} are reported instead of the single
	 * token.
	 * 
	 * @param value
	 *            a new value
	 */
	void setPartialTokensReported(boolean value);

	/**
	 * @return system id associated with this lexer
	 */
	String getSystemId();

	/**
	 * @return current entity resolver of the parser
	 */
	EntityResolver getEntityResolver();

	/**
	 * Set new resolver for the parser
	 * 
	 * @param resolver
	 *            a new resolver
	 */
	void setEntityResolver(EntityResolver resolver);

	/**
	 * Move to next token in the stream.
	 * 
	 * @return true if next token was parsed, false if end of file is reached an
	 *         no more tokens are available.
	 * @throws ParserIOException
	 *             if there is IO problem.
	 */
	boolean advance();

	/**
	 * Closes lexer and underlying stream if there is one.
	 * 
	 * @throws ParserIOException
	 *             if there is IO problem during close.
	 */
	void close();

	/**
	 * @return true if parser is valid and still open. If method advance or
	 *         current had thrown exception, than parser becomes invalid.
	 */
	boolean isValid();

	/**
	 * @return true if parser has been closed
	 */
	boolean isClosed();

	/**
	 * <p>
	 * Start parsing source at position (1,1,0).
	 * </p>
	 * 
	 * <p>
	 * Note that this method is currently a security risk. It can be used to
	 * submit data to third parties if parser has more privileges than caller.
	 * The solution under consideration is to require that entity resolver is
	 * supplied and that after entity resolver has finished its work there
	 * should be either InputStream or Reader in input source. However usability
	 * issues of such decision are not yet clear yet. So expect backward
	 * compatibility problems with this parse method in the future.
	 * </p>
	 * 
	 * @param source
	 *            an input source to parse
	 */
	void parse(InputSource source);

	/**
	 * @return current token
	 * @see AbstractParser#advance()
	 */
	TokenType current();
}