| /* |
| * Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| * CA 95054 USA or visit www.sun.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(); |
| } |