/*
 * Copyright (c) 2004, 2012, 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.
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.
The reception of encoding algorithm events is determined by
the registration of:

   
A PrimitiveTypeContentHandler, for the recieving of events, associated with built-in encoding algorithms, for decoded data that can be reported as Java primitive types.
   
A 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.
   
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.


The reporting of element content events for built-in algorithms
   is determimed by the following:

   
If a PrimitiveContentHandler is registered then decoded data is reported
       as Java primitive types using the corresponding methods on the PrimitiveContentHandler
       interface.
   
If a PrimitiveContentHandler is not registered and a EncodingAlgorithmContentHandler is registered then decoded data is reported as Java Objects using EncodingAlgorithmContentHandler.object(String, int, Object). An Object shall correspond to the Java primitive type that would otherwise be reported using the PrimitiveContentHandler.
   
If neither is registered then then decoded data is reported as characters.


The reporting of element content events for application-defined algorithms
   is determimed by the following:

   
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 EncodingAlgorithmContentHandler.octets(String, int, byte[], int, int); otherwise
   
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 EncodingAlgorithmContentHandler.object(String, int, Object).


The reporting of attribute values for encoding algorithms is achieved using EncodingAlgorithmAttributes that extends Attributes. The registered ContentHandler may cast the attr paramter of the ContentHandler.startElement(String, String, String, Attributes) to the EncodingAlgorithmAttributes interface to access to encoding algorithm information. 
The reporting of attribute values for built-in algorithms
   is determimed by the following:

   
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 EncodingAlgorithmAttributes.getAlgorithmData(int). 
If neither is registered then then decoded data is reported as characters.


The reporting of attribute values for application-defined algorithms
   is determimed by the following:

   
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 byte[], using EncodingAlgorithmAttributes.getAlgorithmData(int); otherwise
   
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 EncodingAlgorithmAttributes.getAlgorithmData(int).


See Also:
PrimitiveTypeContentHandler
EncodingAlgorithmContentHandler
XMLReader
ContentHandler/**
 * 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.
/**
     * 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.
/**
     * 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.
The application can use this method to instruct the Fast Infoset
reader to begin parsing a fast infoset document from a byte stream.
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.
During the parse, the FastInfosetReader will provide information about
the fast infoset document through the registered event handlers.

 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.

Params:
s – The byte stream to parse from./**
     * 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.
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.
Params:
handler – The lexical handler.
See Also:
getLexicalHandler/**
     * 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.
See Also:
setLexicalHandler
Returns:
The current lexical handler, or null if none
        has been registered./**
     * 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.
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.
Params:
handler – The DTD declaration handler.
See Also:
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.
See Also:
setLexicalHandler
Returns:
The current DTD declaration handler, or null if none
        has been registered./**
     * 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.
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.
Params:
handler – The encoding algorithm handler.
See Also:
getEncodingAlgorithmContentHandler/**
     * 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.
See Also:
setEncodingAlgorithmContentHandler
Returns:
The current encoding algorithm handler, or null if none
        has been registered./**
     * 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.
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.
Params:
handler – The primitive type handler.
See Also:
getPrimitiveTypeContentHandler/**
     * 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.
See Also:
setPrimitiveTypeContentHandler
Returns:
The current primitive type handler, or null if none
        has been registered./**
     * Return the current primitive type handler.
     *
     * @return The current primitive type handler, or null if none
     *         has been registered.
     * @see #setPrimitiveTypeContentHandler
     */
    public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
}