KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jvnet > fastinfoset > sax > FastInfosetReader


1 /*
2  * Fast Infoset ver. 0.1 software ("Software")
3  *
4  * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
5  *
6  * Software is licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License. You may
8  * obtain a copy of the License at:
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
15  * License for the specific language governing permissions and limitations.
16  *
17  * Sun supports and benefits from the global community of open source
18  * developers, and thanks the community for its important contributions and
19  * open standards-based technology, which Sun has adopted into many of its
20  * products.
21  *
22  * Please note that portions of Software may be provided with notices and
23  * open source licenses from such communities and third parties that govern the
24  * use of those portions, and any licenses granted hereunder do not alter any
25  * rights and obligations you may have under such open source licenses,
26  * however, the disclaimer of warranty and limitation of liability provisions
27  * in this License will apply to all Software in this distribution.
28  *
29  * You acknowledge that the Software is not designed, licensed or intended
30  * for use in the design, construction, operation or maintenance of any nuclear
31  * facility.
32  *
33  * Apache License
34  * Version 2.0, January 2004
35  * http://www.apache.org/licenses/
36  *
37  */

38
39 package org.jvnet.fastinfoset.sax;
40
41 import java.io.IOException JavaDoc;
42 import java.io.InputStream JavaDoc;
43 import java.util.Map JavaDoc;
44 import org.jvnet.fastinfoset.FastInfosetException;
45 import org.jvnet.fastinfoset.FastInfosetParser;
46 import org.xml.sax.SAXException JavaDoc;
47 import org.xml.sax.XMLReader JavaDoc;
48 import org.xml.sax.ext.LexicalHandler JavaDoc;
49
50 /**
51  * Interface for reading an Fast Infoset document using callbacks.
52  *
53  * <p>FastInfosetReader is the interface that a Fast Infoset parser's
54  * SAX2 driver must implement. This interface allows an application to
55  * to register Fast Infoset specific event handlers for encoding algorithms.</p>
56  *
57  * <p>The reception of encoding algorithm events is determined by
58  * the registration of:
59  * <ul>
60  * <li>A {@link PrimitiveTypeContentHandler}, for the recieving of events,
61  * associated with built-in encoding algorithms, for decoded data that
62  * can be reported as Java primitive types.</li>
63  * <li>A {@link EncodingAlgorithmContentHandler}, for the recieving of events,
64  * associated with built-in and application-defined encoding algorithms, for
65  * decoded data that can be reported as an array of octets or as a Java
66  * Object.</li>
67  * <li>{@link org.jvnet.fastinfoset.EncodingAlgorithm} implementations, for
68  * the receiving of events, associated with application defined algorithms.
69  * for decoded data that shall be reported as a Java Object by way of the
70  * registered EncodingAlgorithmContentHandler.</li>
71  * </ul>
72  * </p>
73  *
74  * <p>The reporting of element content events for built-in algorithms
75  * is determimed by the following:
76  * <ul>
77  * <li>If a PrimitiveContentHandler is registered then decoded data is reported
78  * as Java primitive types using the corresponding methods on the PrimitiveContentHandler
79  * interface.</li>
80  * <li>If a PrimitiveContentHandler is not registered and a
81  * EncodingAlgorithmContentHandler is registered then decoded data is reported
82  * as Java Objects using {@link EncodingAlgorithmContentHandler#object(String, int, Object)}.
83  * An Object shall correspond to the Java primitive type that
84  * would otherwise be reported using the PrimitiveContentHandler.</li>
85  * <li>If neither is registered then then decoded data is reported as characters.</li>
86  * </ul>
87  * </p>
88  *
89  * <p>The reporting of element content events for application-defined algorithms
90  * is determimed by the following:
91  * <ul>
92  * <li>If an EncodingAlgorithmContentHandler is registered and there is no
93  * EncodingAlgorithm registered for an application-defined encoding algorithm
94  * then decoded data for such an algoroithm is reported as an array of octets
95  * using {@link EncodingAlgorithmContentHandler#octets(String, int, byte[], int, int)};
96  * otherwise</li>
97  * <li>If there is an EncodingAlgorithm registered for the application-defined
98  * encoding algorithm then the decoded data is reported as a Java Object,
99  * 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  * @version 0.1
139  * @see org.jvnet.fastinfoset.VocbularyReader
140  * @see org.jvnet.fastinfoset.sax.PrimitiveTypeContentHandler
141  * @see org.jvnet.fastinfoset.sax.EncodingAlgorithmContentHandler
142  * @see org.xml.sax.XMLReader
143  * @see org.xml.sax.ContentHandler
144  */

145 public interface FastInfosetReader extends XMLReader JavaDoc, FastInfosetParser {
146     /**
147      * The property name to be used for getting and setting the
148      * EncodingAlgorithmContentHandler.
149      *
150      */

151     public static final String JavaDoc ENCODING_ALGORITHM_CONTENT_HANDLER_PROPERTY =
152             "http://jvnet.org/fastinfoset/sax/properties/encoding-algorithm-content-handler";
153     
154     /**
155      * The property name to be used for getting and setting the
156      * PrimtiveTypeContentHandler.
157      *
158      */

159     public static final String JavaDoc PRIMITIVE_TYPE_CONTENT_HANDLER_PROPERTY =
160             "http://jvnet.org/fastinfoset/sax/properties/primitive-type-content-handler";
161     
162     /**
163      * Parse a fast infoset document from an InputStream.
164      *
165      * <p>The application can use this method to instruct the Fast Infoset
166      * reader to begin parsing a fast infoset document from a byte stream.</p>
167      *
168      * <p>Applications may not invoke this method while a parse is in progress
169      * (they should create a new XMLReader instead for each nested XML document).
170      * Once a parse is complete, an application may reuse the same
171      * FastInfosetReader object, possibly with a different byte stream.</p>
172      *
173      * <p>During the parse, the FastInfosetReader will provide information about
174      * the fast infoset document through the registered event handlers.<p>
175      *
176      * <p> This method is synchronous: it will not return until parsing has ended.
177      * If a client application wants to terminate parsing early, it should throw
178      * an exception.<p>
179      *
180      * @param s The byte stream to parse from.
181      */

182     public void parse(InputStream JavaDoc s) throws IOException JavaDoc, FastInfosetException, SAXException JavaDoc;
183
184     /**
185      * Allow an application to register a lexical handler.
186      *
187      * <p>Applications may register a new or different handler in the
188      * middle of a parse, and the SAX parser must begin using the new
189      * handler immediately.</p>
190      *
191      * @param handler The lexical handler.
192      * @see #getLexicalHandler
193      */

194     public void setLexicalHandler(LexicalHandler JavaDoc handler);
195
196     /**
197      * Return the current lexical handler.
198      *
199      * @return The current lexical handler, or null if none
200      * has been registered.
201      * @see #setLexicalHandler
202      */

203     public LexicalHandler JavaDoc getLexicalHandler();
204    
205     /**
206      * Allow an application to register an encoding algorithm handler.
207      *
208      * <p>Applications may register a new or different handler in the
209      * middle of a parse, and the SAX parser must begin using the new
210      * handler immediately.</p>
211      *
212      * @param handler The encoding algorithm handler.
213      * @see #getEncodingAlgorithmContentHandler
214      */

215     public void setEncodingAlgorithmContentHandler(EncodingAlgorithmContentHandler handler);
216
217     /**
218      * Return the current encoding algorithm handler.
219      *
220      * @return The current encoding algorithm handler, or null if none
221      * has been registered.
222      * @see #setEncodingAlgorithmContentHandler
223      */

224     public EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler();
225
226     /**
227      * Allow an application to register a primitive type handler.
228      *
229      * <p>Applications may register a new or different handler in the
230      * middle of a parse, and the SAX parser must begin using the new
231      * handler immediately.</p>
232      *
233      * @param handler The primitive type handler.
234      * @see #getPrimitiveTypeContentHandler
235      */

236     public void setPrimitiveTypeContentHandler(PrimitiveTypeContentHandler handler);
237
238
239     /**
240      * Return the current primitive type handler.
241      *
242      * @return The current primitive type handler, or null if none
243      * has been registered.
244      * @see #setPrimitiveTypeContentHandler
245      */

246     public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
247 }
248
Popular Tags