001: /*
002: * Fast Infoset ver. 0.1 software ("Software")
003: *
004: * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * Software is licensed under the Apache License, Version 2.0 (the "License");
007: * you may not use this file except in compliance with the License. You may
008: * obtain a copy of the License at:
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015: * License for the specific language governing permissions and limitations.
016: *
017: * Sun supports and benefits from the global community of open source
018: * developers, and thanks the community for its important contributions and
019: * open standards-based technology, which Sun has adopted into many of its
020: * products.
021: *
022: * Please note that portions of Software may be provided with notices and
023: * open source licenses from such communities and third parties that govern the
024: * use of those portions, and any licenses granted hereunder do not alter any
025: * rights and obligations you may have under such open source licenses,
026: * however, the disclaimer of warranty and limitation of liability provisions
027: * in this License will apply to all Software in this distribution.
028: *
029: * You acknowledge that the Software is not designed, licensed or intended
030: * for use in the design, construction, operation or maintenance of any nuclear
031: * facility.
032: *
033: * Apache License
034: * Version 2.0, January 2004
035: * http://www.apache.org/licenses/
036: *
037: */
038:
039: package org.jvnet.fastinfoset.sax;
040:
041: import java.io.IOException;
042: import java.io.InputStream;
043: import org.jvnet.fastinfoset.FastInfosetException;
044: import org.jvnet.fastinfoset.FastInfosetParser;
045: import org.xml.sax.SAXException;
046: import org.xml.sax.XMLReader;
047: import org.xml.sax.ext.DeclHandler;
048: import org.xml.sax.ext.LexicalHandler;
049:
050: /**
051: * Interface for reading an Fast Infoset document using callbacks.
052: *
053: * <p>FastInfosetReader is the interface that a Fast Infoset parser's
054: * SAX2 driver must implement. This interface allows an application to
055: * to register Fast Infoset specific event handlers for encoding algorithms.</p>
056: *
057: * <p>The reception of encoding algorithm events is determined by
058: * the registration of:
059: * <ul>
060: * <li>A {@link PrimitiveTypeContentHandler}, for the recieving of events,
061: * associated with built-in encoding algorithms, for decoded data that
062: * can be reported as Java primitive types.</li>
063: * <li>A {@link EncodingAlgorithmContentHandler}, for the recieving of events,
064: * associated with built-in and application-defined encoding algorithms, for
065: * decoded data that can be reported as an array of octets or as a Java
066: * Object.</li>
067: * <li>{@link org.jvnet.fastinfoset.EncodingAlgorithm} implementations, for
068: * the receiving of events, associated with application defined algorithms.
069: * for decoded data that shall be reported as a Java Object by way of the
070: * registered EncodingAlgorithmContentHandler.</li>
071: * </ul>
072: * </p>
073: *
074: * <p>The reporting of element content events for built-in algorithms
075: * is determimed by the following:
076: * <ul>
077: * <li>If a PrimitiveContentHandler is registered then decoded data is reported
078: * as Java primitive types using the corresponding methods on the PrimitiveContentHandler
079: * interface.</li>
080: * <li>If a PrimitiveContentHandler is not registered and a
081: * EncodingAlgorithmContentHandler is registered then decoded data is reported
082: * as Java Objects using {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.
083: * An Object shall correspond to the Java primitive type that
084: * would otherwise be reported using the PrimitiveContentHandler.</li>
085: * <li>If neither is registered then then decoded data is reported as characters.</li>
086: * </ul>
087: * </p>
088: *
089: * <p>The reporting of element content events for application-defined algorithms
090: * is determimed by the following:
091: * <ul>
092: * <li>If an EncodingAlgorithmContentHandler is registered and there is no
093: * EncodingAlgorithm registered for an application-defined encoding algorithm
094: * then decoded data for such an algoroithm is reported as an array of octets
095: * using {@link EncodingAlgorithmContentHandler#octets(String, int, byte[], int, int)};
096: * otherwise</li>
097: * <li>If there is an EncodingAlgorithm registered for the application-defined
098: * encoding algorithm then the decoded data is reported as a Java Object,
099: * returned by decoding according to the EncodingAlgorithm, using
100: * {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.</li>
101: * </ul>
102: * </p>
103: *
104: * <p>The reporting of attribute values for encoding algorithms is achieved using
105: * {@link EncodingAlgorithmAttributes} that extends {@link org.xml.sax.Attributes}.
106: * The registered ContentHandler may cast the attr paramter of the
107: * {@link org.xml.sax.ContentHandler#startElement(String, String, String, org.xml.sax.Attributes)}
108: * to the EncodingAlgorithmAttributes interface to access to encoding algorithm information.
109: * </p>
110: *
111: * <p>The reporting of attribute values for built-in algorithms
112: * is determimed by the following:
113: * <ul>
114: * <li>If a PrimitiveContentHandler or EncodingAlgorithmContentHandler is
115: * registered then decoded data is reported as Java Objects corresponding
116: * to the Java primitive types. The Java Objects may be obtained using
117: * {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.
118: * <li>If neither is registered then then decoded data is reported as characters.</li>
119: * </ul>
120: * </p>
121: *
122: * <p>The reporting of attribute values for application-defined algorithms
123: * is determimed by the following:
124: * <ul>
125: * <li>If an EncodingAlgorithmContentHandler is registered and there is no
126: * EncodingAlgorithm registered for an application-defined encoding algorithm
127: * then decoded data for such an algoroithm is reported as Java Object,
128: * that is an instance of <code>byte[]</code>,
129: * using {@link EncodingAlgorithmAttributes#getAlgorithmData(int)};
130: * otherwise</li>
131: * <li>If there is an EncodingAlgorithm registered for the application-defined
132: * encoding algorithm then the decoded data is reported as a Java Object,
133: * returned by decoding according to the EncodingAlgorithm, using
134: * {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.</li>
135: * </ul>
136: * </p>
137: *
138: * @see org.jvnet.fastinfoset.sax.PrimitiveTypeContentHandler
139: * @see org.jvnet.fastinfoset.sax.EncodingAlgorithmContentHandler
140: * @see org.xml.sax.XMLReader
141: * @see org.xml.sax.ContentHandler
142: */
143: public interface FastInfosetReader extends XMLReader, FastInfosetParser {
144: /**
145: * The property name to be used for getting and setting the
146: * EncodingAlgorithmContentHandler.
147: *
148: */
149: public static final String ENCODING_ALGORITHM_CONTENT_HANDLER_PROPERTY = "http://jvnet.org/fastinfoset/sax/properties/encoding-algorithm-content-handler";
150:
151: /**
152: * The property name to be used for getting and setting the
153: * PrimtiveTypeContentHandler.
154: *
155: */
156: public static final String PRIMITIVE_TYPE_CONTENT_HANDLER_PROPERTY = "http://jvnet.org/fastinfoset/sax/properties/primitive-type-content-handler";
157:
158: /**
159: * Parse a fast infoset document from an InputStream.
160: *
161: * <p>The application can use this method to instruct the Fast Infoset
162: * reader to begin parsing a fast infoset document from a byte stream.</p>
163: *
164: * <p>Applications may not invoke this method while a parse is in progress
165: * (they should create a new XMLReader instead for each nested XML document).
166: * Once a parse is complete, an application may reuse the same
167: * FastInfosetReader object, possibly with a different byte stream.</p>
168: *
169: * <p>During the parse, the FastInfosetReader will provide information about
170: * the fast infoset document through the registered event handlers.<p>
171: *
172: * <p> This method is synchronous: it will not return until parsing has ended.
173: * If a client application wants to terminate parsing early, it should throw
174: * an exception.<p>
175: *
176: * @param s The byte stream to parse from.
177: */
178: public void parse(InputStream s) throws IOException,
179: FastInfosetException, SAXException;
180:
181: /**
182: * Allow an application to register a lexical handler.
183: *
184: * <p>Applications may register a new or different handler in the
185: * middle of a parse, and the SAX parser must begin using the new
186: * handler immediately.</p>
187: *
188: * @param handler The lexical handler.
189: * @see #getLexicalHandler
190: */
191: public void setLexicalHandler(LexicalHandler handler);
192:
193: /**
194: * Return the current lexical handler.
195: *
196: * @return The current lexical handler, or null if none
197: * has been registered.
198: * @see #setLexicalHandler
199: */
200: public LexicalHandler getLexicalHandler();
201:
202: /**
203: * Allow an application to register a DTD declaration handler.
204: *
205: * <p>Applications may register a new or different handler in the
206: * middle of a parse, and the SAX parser must begin using the new
207: * handler immediately.</p>
208: *
209: * @param handler The DTD declaration handler.
210: * @see #getLexicalHandler
211: */
212: public void setDeclHandler(DeclHandler handler);
213:
214: /**
215: * Return the current DTD declaration handler.
216: *
217: * @return The current DTD declaration handler, or null if none
218: * has been registered.
219: * @see #setLexicalHandler
220: */
221: public DeclHandler getDeclHandler();
222:
223: /**
224: * Allow an application to register an encoding algorithm handler.
225: *
226: * <p>Applications may register a new or different handler in the
227: * middle of a parse, and the SAX parser must begin using the new
228: * handler immediately.</p>
229: *
230: * @param handler The encoding algorithm handler.
231: * @see #getEncodingAlgorithmContentHandler
232: */
233: public void setEncodingAlgorithmContentHandler(
234: EncodingAlgorithmContentHandler handler);
235:
236: /**
237: * Return the current encoding algorithm handler.
238: *
239: * @return The current encoding algorithm handler, or null if none
240: * has been registered.
241: * @see #setEncodingAlgorithmContentHandler
242: */
243: public EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler();
244:
245: /**
246: * Allow an application to register a primitive type handler.
247: *
248: * <p>Applications may register a new or different handler in the
249: * middle of a parse, and the SAX parser must begin using the new
250: * handler immediately.</p>
251: *
252: * @param handler The primitive type handler.
253: * @see #getPrimitiveTypeContentHandler
254: */
255: public void setPrimitiveTypeContentHandler(
256: PrimitiveTypeContentHandler handler);
257:
258: /**
259: * Return the current primitive type handler.
260: *
261: * @return The current primitive type handler, or null if none
262: * has been registered.
263: * @see #setPrimitiveTypeContentHandler
264: */
265: public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
266: }
|