/*
 * Copyright (c) 2005, 2006, 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.
 *
 * THIS FILE WAS MODIFIED BY SUN MICROSYSTEMS, INC.
 */

package com.sun.xml.internal.org.jvnet.fastinfoset.sax;

import java.io.IOException;
import java.io.InputStream;
import com.sun.xml.internal.org.jvnet.fastinfoset.FastInfosetException;
import com.sun.xml.internal.org.jvnet.fastinfoset.FastInfosetParser;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import org.xml.sax.ext.DeclHandler;
import org.xml.sax.ext.LexicalHandler;

/**
 * Interface for reading an Fast Infoset document using callbacks.
 *
 * <p>FastInfosetReader is the interface that a Fast Infoset parser's 
 * SAX2 driver must implement. This interface allows an application to 
 * to register Fast Infoset specific event handlers for encoding algorithms.</p>
 *
 * <p>The reception of encoding algorithm events is determined by 
 * the registration of:
 * <ul>
 *    <li>A {@link PrimitiveTypeContentHandler}, for the recieving of events, 
 *        associated with built-in encoding algorithms, for decoded data that 
 *        can be reported as Java primitive types.</li>
 *    <li>A {@link EncodingAlgorithmContentHandler}, for the recieving of events,
 *        associated with built-in and application-defined encoding algorithms, for
 *        decoded data that can be reported as an array of octets or as a Java 
 *        Object.</li>
 *    <li>{@link com.sun.xml.internal.org.jvnet.fastinfoset.EncodingAlgorithm} implementations, for
 *        the receiving of events, associated with application defined algorithms.
 *        for decoded data that shall be reported as a Java Object by way of the
 *        registered EncodingAlgorithmContentHandler.</li>
 * </ul>
 * </p>
 *
 * <p>The reporting of element content events for built-in algorithms 
 *    is determimed by the following:
 * <ul>
 *    <li>If a PrimitiveContentHandler is registered then decoded data is reported
 *        as Java primitive types using the corresponding methods on the PrimitiveContentHandler
 *        interface.</li>
 *    <li>If a PrimitiveContentHandler is not registered and a 
 *        EncodingAlgorithmContentHandler is registered then decoded data is reported
 *        as Java Objects using {@link EncodingAlgorithmContentHandler#object(String, int, Object)}. 
 *        An Object shall correspond to the Java primitive type that
 *        would otherwise be reported using the PrimitiveContentHandler.</li>
 *    <li>If neither is registered then then decoded data is reported as characters.</li>
 * </ul>
 * </p>
 *
 * <p>The reporting of element content events for application-defined algorithms 
 *    is determimed by the following:
 * <ul>
 *    <li>If an EncodingAlgorithmContentHandler is registered and there is no 
 *        EncodingAlgorithm registered for an application-defined encoding algorithm
 *        then decoded data for such an algoroithm is reported as an array of octets
 *        using {@link EncodingAlgorithmContentHandler#octets(String, int, byte[], int, int)}; 
 *        otherwise</li> 
 *    <li>If there is an EncodingAlgorithm registered for the application-defined 
 *        encoding algorithm then the decoded data is reported as a Java Object,
 *        returned by decoding according to the EncodingAlgorithm, using
 *        {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.</li>
 * </ul>
 * </p>
 * 
 * <p>The reporting of attribute values for encoding algorithms is achieved using
 * {@link EncodingAlgorithmAttributes} that extends {@link org.xml.sax.Attributes}.
 * The registered ContentHandler may cast the attr paramter of the 
 * {@link org.xml.sax.ContentHandler#startElement(String, String, String, org.xml.sax.Attributes)} 
 * to the EncodingAlgorithmAttributes interface to access to encoding algorithm information.
 * </p>
 *
 * <p>The reporting of attribute values for built-in algorithms 
 *    is determimed by the following:
 * <ul>
 *    <li>If a PrimitiveContentHandler or EncodingAlgorithmContentHandler is 
 *        registered then decoded data is reported as Java Objects corresponding
 *        to the Java primitive types. The Java Objects may be obtained using 
 *        {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.
 *    <li>If neither is registered then then decoded data is reported as characters.</li>
 * </ul>
 * </p>
 *
 * <p>The reporting of attribute values for application-defined algorithms 
 *    is determimed by the following:
 * <ul>
 *    <li>If an EncodingAlgorithmContentHandler is registered and there is no 
 *        EncodingAlgorithm registered for an application-defined encoding algorithm
 *        then decoded data for such an algoroithm is reported as Java Object,
 *        that is an instance of <code>byte[]</code>,
 *        using {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}; 
 *        otherwise</li> 
 *    <li>If there is an EncodingAlgorithm registered for the application-defined 
 *        encoding algorithm then the decoded data is reported as a Java Object,
 *        returned by decoding according to the EncodingAlgorithm, using
 *        {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.</li>
 * </ul>
 * </p>
 *
 * @see com.sun.xml.internal.org.jvnet.fastinfoset.sax.PrimitiveTypeContentHandler
 * @see com.sun.xml.internal.org.jvnet.fastinfoset.sax.EncodingAlgorithmContentHandler
 * @see org.xml.sax.XMLReader
 * @see org.xml.sax.ContentHandler
 */
public interface FastInfosetReader extends XMLReader, FastInfosetParser {
    /**
     * The property name to be used for getting and setting the 
     * EncodingAlgorithmContentHandler.
     *
     */    
    public static final String ENCODING_ALGORITHM_CONTENT_HANDLER_PROPERTY =
            "http://jvnet.org/fastinfoset/sax/properties/encoding-algorithm-content-handler";
    
    /**
     * The property name to be used for getting and setting the 
     * PrimtiveTypeContentHandler.
     *
     */    
    public static final String PRIMITIVE_TYPE_CONTENT_HANDLER_PROPERTY =
            "http://jvnet.org/fastinfoset/sax/properties/primitive-type-content-handler";
    
    /**
     * Parse a fast infoset document from an InputStream.
     *
     * <p>The application can use this method to instruct the Fast Infoset
     * reader to begin parsing a fast infoset document from a byte stream.</p>
     *
     * <p>Applications may not invoke this method while a parse is in progress 
     * (they should create a new XMLReader instead for each nested XML document). 
     * Once a parse is complete, an application may reuse the same 
     * FastInfosetReader object, possibly with a different byte stream.</p>
     *
     * <p>During the parse, the FastInfosetReader will provide information about 
     * the fast infoset document through the registered event handlers.<p>
     *
     * <p> This method is synchronous: it will not return until parsing has ended. 
     * If a client application wants to terminate parsing early, it should throw 
     * an exception.<p>
     *
     * @param s The byte stream to parse from.
     */
    public void parse(InputStream s) throws IOException, FastInfosetException, SAXException;

    /**
     * Allow an application to register a lexical handler.
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The lexical handler.
     * @see #getLexicalHandler
     */
    public void setLexicalHandler(LexicalHandler handler);

    /**
     * Return the current lexical handler.
     *
     * @return The current lexical handler, or null if none
     *         has been registered.
     * @see #setLexicalHandler
     */
    public LexicalHandler getLexicalHandler();
   
    /**
     * Allow an application to register a DTD declaration handler.
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The DTD declaration handler.
     * @see #getLexicalHandler
     */
    public void setDeclHandler(DeclHandler handler);

    /**
     * Return the current DTD declaration handler.
     *
     * @return The current DTD declaration handler, or null if none
     *         has been registered.
     * @see #setLexicalHandler
     */
    public DeclHandler getDeclHandler();
    
    /**
     * Allow an application to register an encoding algorithm handler.
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The encoding algorithm handler.
     * @see #getEncodingAlgorithmContentHandler
     */
    public void setEncodingAlgorithmContentHandler(EncodingAlgorithmContentHandler handler);

    /**
     * Return the current encoding algorithm handler.
     *
     * @return The current encoding algorithm handler, or null if none
     *         has been registered.
     * @see #setEncodingAlgorithmContentHandler
     */
    public EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler();

    /**
     * Allow an application to register a primitive type handler.
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The primitive type handler.
     * @see #getPrimitiveTypeContentHandler
     */
    public void setPrimitiveTypeContentHandler(PrimitiveTypeContentHandler handler);


    /**
     * Return the current primitive type handler.
     *
     * @return The current primitive type handler, or null if none
     *         has been registered.
     * @see #setPrimitiveTypeContentHandler
     */
    public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
}