org.jvnet.fastinfoset.sax.FastInfosetReader Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2004, 2022 Oracle and/or its affiliates. All rights reserved.
*
* Oracle licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jvnet.fastinfoset.sax;
import java.io.IOException;
import java.io.InputStream;
import org.jvnet.fastinfoset.FastInfosetException;
import 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 {@link PrimitiveTypeContentHandler}, for the recieving of events,
* associated with built-in encoding algorithms, for decoded data that
* can be reported as Java primitive types.
* - 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.
* - {@link 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.
*
*
* 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 {@link 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 {@link 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
* {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.
*
*
* 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.
*
*
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
* {@link 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 {@link 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
* {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.
*
*
* @see org.jvnet.fastinfoset.sax.PrimitiveTypeContentHandler
* @see 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.
*
* 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.
*
* @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.
*
* @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.
*
* 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.
*
* @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.
*
* 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.
*
* @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.
*
* 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.
*
* @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();
}