001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: *
025: * THIS FILE WAS MODIFIED BY SUN MICROSYSTEMS, INC.
026: */
027:
028: /*
029: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
030: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
031: *
032: * This code is free software; you can redistribute it and/or modify it
033: * under the terms of the GNU General Public License version 2 only, as
034: * published by the Free Software Foundation. Sun designates this
035: * particular file as subject to the "Classpath" exception as provided
036: * by Sun in the LICENSE file that accompanied this code.
037: *
038: * This code is distributed in the hope that it will be useful, but WITHOUT
039: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
040: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
041: * version 2 for more details (a copy is included in the LICENSE file that
042: * accompanied this code).
043: *
044: * You should have received a copy of the GNU General Public License version
045: * 2 along with this work; if not, write to the Free Software Foundation,
046: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
047: *
048: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
049: * CA 95054 USA or visit www.sun.com if you need additional information or
050: * have any questions.
051: *
052: * THIS FILE WAS MODIFIED BY SUN MICROSYSTEMS, INC.
053: *
054: */
055:
056: package com.sun.xml.internal.org.jvnet.fastinfoset.sax;
057:
058: import java.io.IOException;
059: import java.io.InputStream;
060: import com.sun.xml.internal.org.jvnet.fastinfoset.FastInfosetException;
061: import com.sun.xml.internal.org.jvnet.fastinfoset.FastInfosetParser;
062: import org.xml.sax.SAXException;
063: import org.xml.sax.XMLReader;
064: import org.xml.sax.ext.DeclHandler;
065: import org.xml.sax.ext.LexicalHandler;
066:
067: /**
068: * Interface for reading an Fast Infoset document using callbacks.
069: *
070: * <p>FastInfosetReader is the interface that a Fast Infoset parser's
071: * SAX2 driver must implement. This interface allows an application to
072: * to register Fast Infoset specific event handlers for encoding algorithms.</p>
073: *
074: * <p>The reception of encoding algorithm events is determined by
075: * the registration of:
076: * <ul>
077: * <li>A {@link PrimitiveTypeContentHandler}, for the recieving of events,
078: * associated with built-in encoding algorithms, for decoded data that
079: * can be reported as Java primitive types.</li>
080: * <li>A {@link EncodingAlgorithmContentHandler}, for the recieving of events,
081: * associated with built-in and application-defined encoding algorithms, for
082: * decoded data that can be reported as an array of octets or as a Java
083: * Object.</li>
084: * <li>{@link com.sun.xml.internal.org.jvnet.fastinfoset.EncodingAlgorithm} implementations, for
085: * the receiving of events, associated with application defined algorithms.
086: * for decoded data that shall be reported as a Java Object by way of the
087: * registered EncodingAlgorithmContentHandler.</li>
088: * </ul>
089: * </p>
090: *
091: * <p>The reporting of element content events for built-in algorithms
092: * is determimed by the following:
093: * <ul>
094: * <li>If a PrimitiveContentHandler is registered then decoded data is reported
095: * as Java primitive types using the corresponding methods on the PrimitiveContentHandler
096: * interface.</li>
097: * <li>If a PrimitiveContentHandler is not registered and a
098: * EncodingAlgorithmContentHandler is registered then decoded data is reported
099: * as Java Objects using {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.
100: * An Object shall correspond to the Java primitive type that
101: * would otherwise be reported using the PrimitiveContentHandler.</li>
102: * <li>If neither is registered then then decoded data is reported as characters.</li>
103: * </ul>
104: * </p>
105: *
106: * <p>The reporting of element content events for application-defined algorithms
107: * is determimed by the following:
108: * <ul>
109: * <li>If an EncodingAlgorithmContentHandler is registered and there is no
110: * EncodingAlgorithm registered for an application-defined encoding algorithm
111: * then decoded data for such an algoroithm is reported as an array of octets
112: * using {@link EncodingAlgorithmContentHandler#octets(String, int, byte[], int, int)};
113: * otherwise</li>
114: * <li>If there is an EncodingAlgorithm registered for the application-defined
115: * encoding algorithm then the decoded data is reported as a Java Object,
116: * returned by decoding according to the EncodingAlgorithm, using
117: * {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.</li>
118: * </ul>
119: * </p>
120: *
121: * <p>The reporting of attribute values for encoding algorithms is achieved using
122: * {@link EncodingAlgorithmAttributes} that extends {@link org.xml.sax.Attributes}.
123: * The registered ContentHandler may cast the attr paramter of the
124: * {@link org.xml.sax.ContentHandler#startElement(String, String, String, org.xml.sax.Attributes)}
125: * to the EncodingAlgorithmAttributes interface to access to encoding algorithm information.
126: * </p>
127: *
128: * <p>The reporting of attribute values for built-in algorithms
129: * is determimed by the following:
130: * <ul>
131: * <li>If a PrimitiveContentHandler or EncodingAlgorithmContentHandler is
132: * registered then decoded data is reported as Java Objects corresponding
133: * to the Java primitive types. The Java Objects may be obtained using
134: * {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.
135: * <li>If neither is registered then then decoded data is reported as characters.</li>
136: * </ul>
137: * </p>
138: *
139: * <p>The reporting of attribute values for application-defined algorithms
140: * is determimed by the following:
141: * <ul>
142: * <li>If an EncodingAlgorithmContentHandler is registered and there is no
143: * EncodingAlgorithm registered for an application-defined encoding algorithm
144: * then decoded data for such an algoroithm is reported as Java Object,
145: * that is an instance of <code>byte[]</code>,
146: * using {@link EncodingAlgorithmAttributes#getAlgorithmData(int)};
147: * otherwise</li>
148: * <li>If there is an EncodingAlgorithm registered for the application-defined
149: * encoding algorithm then the decoded data is reported as a Java Object,
150: * returned by decoding according to the EncodingAlgorithm, using
151: * {@link EncodingAlgorithmAttributes#getAlgorithmData(int)}.</li>
152: * </ul>
153: * </p>
154: *
155: * @see com.sun.xml.internal.org.jvnet.fastinfoset.sax.PrimitiveTypeContentHandler
156: * @see com.sun.xml.internal.org.jvnet.fastinfoset.sax.EncodingAlgorithmContentHandler
157: * @see org.xml.sax.XMLReader
158: * @see org.xml.sax.ContentHandler
159: */
160: public interface FastInfosetReader extends XMLReader, FastInfosetParser {
161: /**
162: * The property name to be used for getting and setting the
163: * EncodingAlgorithmContentHandler.
164: *
165: */
166: public static final String ENCODING_ALGORITHM_CONTENT_HANDLER_PROPERTY = "http://jvnet.org/fastinfoset/sax/properties/encoding-algorithm-content-handler";
167:
168: /**
169: * The property name to be used for getting and setting the
170: * PrimtiveTypeContentHandler.
171: *
172: */
173: public static final String PRIMITIVE_TYPE_CONTENT_HANDLER_PROPERTY = "http://jvnet.org/fastinfoset/sax/properties/primitive-type-content-handler";
174:
175: /**
176: * Parse a fast infoset document from an InputStream.
177: *
178: * <p>The application can use this method to instruct the Fast Infoset
179: * reader to begin parsing a fast infoset document from a byte stream.</p>
180: *
181: * <p>Applications may not invoke this method while a parse is in progress
182: * (they should create a new XMLReader instead for each nested XML document).
183: * Once a parse is complete, an application may reuse the same
184: * FastInfosetReader object, possibly with a different byte stream.</p>
185: *
186: * <p>During the parse, the FastInfosetReader will provide information about
187: * the fast infoset document through the registered event handlers.<p>
188: *
189: * <p> This method is synchronous: it will not return until parsing has ended.
190: * If a client application wants to terminate parsing early, it should throw
191: * an exception.<p>
192: *
193: * @param s The byte stream to parse from.
194: */
195: public void parse(InputStream s) throws IOException,
196: FastInfosetException, SAXException;
197:
198: /**
199: * Allow an application to register a lexical handler.
200: *
201: * <p>Applications may register a new or different handler in the
202: * middle of a parse, and the SAX parser must begin using the new
203: * handler immediately.</p>
204: *
205: * @param handler The lexical handler.
206: * @see #getLexicalHandler
207: */
208: public void setLexicalHandler(LexicalHandler handler);
209:
210: /**
211: * Return the current lexical handler.
212: *
213: * @return The current lexical handler, or null if none
214: * has been registered.
215: * @see #setLexicalHandler
216: */
217: public LexicalHandler getLexicalHandler();
218:
219: /**
220: * Allow an application to register a DTD declaration handler.
221: *
222: * <p>Applications may register a new or different handler in the
223: * middle of a parse, and the SAX parser must begin using the new
224: * handler immediately.</p>
225: *
226: * @param handler The DTD declaration handler.
227: * @see #getLexicalHandler
228: */
229: public void setDeclHandler(DeclHandler handler);
230:
231: /**
232: * Return the current DTD declaration handler.
233: *
234: * @return The current DTD declaration handler, or null if none
235: * has been registered.
236: * @see #setLexicalHandler
237: */
238: public DeclHandler getDeclHandler();
239:
240: /**
241: * Allow an application to register an encoding algorithm handler.
242: *
243: * <p>Applications may register a new or different handler in the
244: * middle of a parse, and the SAX parser must begin using the new
245: * handler immediately.</p>
246: *
247: * @param handler The encoding algorithm handler.
248: * @see #getEncodingAlgorithmContentHandler
249: */
250: public void setEncodingAlgorithmContentHandler(
251: EncodingAlgorithmContentHandler handler);
252:
253: /**
254: * Return the current encoding algorithm handler.
255: *
256: * @return The current encoding algorithm handler, or null if none
257: * has been registered.
258: * @see #setEncodingAlgorithmContentHandler
259: */
260: public EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler();
261:
262: /**
263: * Allow an application to register a primitive type handler.
264: *
265: * <p>Applications may register a new or different handler in the
266: * middle of a parse, and the SAX parser must begin using the new
267: * handler immediately.</p>
268: *
269: * @param handler The primitive type handler.
270: * @see #getPrimitiveTypeContentHandler
271: */
272: public void setPrimitiveTypeContentHandler(
273: PrimitiveTypeContentHandler handler);
274:
275: /**
276: * Return the current primitive type handler.
277: *
278: * @return The current primitive type handler, or null if none
279: * has been registered.
280: * @see #setPrimitiveTypeContentHandler
281: */
282: public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
283: }
|