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  ;
42  import java.io.InputStream  ;
43  import java.util.Map  ;
44  import org.jvnet.fastinfoset.FastInfosetException;
45  import org.jvnet.fastinfoset.FastInfosetParser;
46  import org.xml.sax.SAXException  ;
47  import org.xml.sax.XMLReader  ;
48  import org.xml.sax.ext.LexicalHandler  ;
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  , FastInfosetParser {
146     /**
147      * The property name to be used for getting and setting the 
148      * EncodingAlgorithmContentHandler.
149      *
150      */    
151     public static final String   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   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   s) throws IOException  , FastInfosetException, SAXException  ;
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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags