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 org.xml.sax.SAXException;
042:
043: /**
044: * SAX2 extention handler to receive notification of character data as
045: * primtive types.
046: *
047: * <p>This is an optional extension handler for SAX2. XML readers are not
048: * required to recognize this handler, and it is not part of core-only
049: * SAX2 distributions.</p>
050: *
051: * <p>This interface may be used with with a Fast Infoset
052: * SAX parser to receive notification of data encoded using the
053: * following built-in encoding algorithms specified in ITU-T Rec. X.891 | ISO/IEC 24824-1
054: * (Fast Infoset), clause 10: "boolean", "base64", "short", "int", "long",
055: * "float", "double" and "uuid" encoding algorithms.<p>
056: *
057: * <p>To set the PrimitiveTypeContentHandler for an XML reader, use the
058: * {@link org.xml.sax.XMLReader#setProperty setProperty} method
059: * with the property name
060: * <code>URI TO BE DEFINED</code>
061: * and an object implementing this interface (or null) as the value.
062: * If the reader does not report primitive data types, it will throw a
063: * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}</p>
064: *
065: * <p>To set the PrimitiveTypeContentHandler for an Fast Infoset reader, use
066: * {@link org.jvnet.fastinfoset.sax.FastInfosetReader#setPrimitiveTypeContentHandler
067: * setPrimitiveTypeContentHandler} method.<p>
068:
069: * <p>The Parser will call methods of this interface to report each
070: * chunk of character data that has been converted to an array of primitive
071: * types, for example an array of integer or an array of float. Parsers may
072: * return all contiguous primtive types in a single chunk, or they may split
073: * it into several chunks</p>
074: *
075: * <p>The application must not attempt to read from the array
076: * outside of the specified range.</p>
077: *
078: * @see org.jvnet.fastinfoset.sax.EncodingAlgorithmContentHandler
079: * @see org.jvnet.fastinfoset.sax.FastInfosetReader
080: * @see org.xml.sax.XMLReader
081: */
082: public interface PrimitiveTypeContentHandler {
083: /**
084: * Receive notification of character data as an array of boolean.
085: *
086: * <p>The application must not attempt to read from the array
087: * outside of the specified range.</p>
088: *
089: * <p>Such notifications will occur for a Fast Infoset SAX parser
090: * when processing data encoded using the "boolean" encoding
091: * algorithm, see subclause 10.7<p>.
092: *
093: * @param b the array of boolean
094: * @param start the start position in the array
095: * @param length the number of boolean to read from the array
096: * @throws org.xml.sax.SAXException any SAX exception, possibly
097: * wrapping another exception
098: */
099: public void booleans(boolean[] b, int start, int length)
100: throws SAXException;
101:
102: /**
103: * Receive notification of character data as an array of byte.
104: *
105: * <p>The application must not attempt to read from the array
106: * outside of the specified range.</p>
107: *
108: * <p>Such notifications will occur for a Fast Infoset SAX parser
109: * when processing data encoded using the "base64" encoding
110: * algorithm, see subclause 10.3, or the "hexadecimal" encoding
111: * algorithm, see subclause 10.2.
112: *
113: * <p>Such a notification may occur for binary data that would
114: * normally require base 64 encoding and reported as character data
115: * using the {@link org.xml.sax.ContentHandler#characters characters}
116: * method <p>.
117: *
118: * @param b the array of byte
119: * @param start the start position in the array
120: * @param length the number of byte to read from the array
121: * @throws org.xml.sax.SAXException any SAX exception, possibly
122: * wrapping another exception
123: */
124: public void bytes(byte[] b, int start, int length)
125: throws SAXException;
126:
127: /**
128: * Receive notification of character data as an array of short.
129: *
130: * <p>The application must not attempt to read from the array
131: * outside of the specified range.</p>
132: *
133: * <p>Such notifications will occur for a Fast Infoset SAX parser
134: * when processing data encoded using the "short" encoding
135: * algorithm, see subclause 10.4<p>.
136: *
137: * @param s the array of short
138: * @param start the start position in the array
139: * @param length the number of short to read from the array
140: * @throws org.xml.sax.SAXException any SAX exception, possibly
141: * wrapping another exception
142: */
143: public void shorts(short[] s, int start, int length)
144: throws SAXException;
145:
146: /**
147: * Receive notification of character data as an array of int.
148: *
149: * <p>The application must not attempt to read from the array
150: * outside of the specified range.</p>
151: *
152: * <p>Such notifications will occur for a Fast Infoset SAX parser
153: * when processing data encoded using the "int" encoding
154: * algorithm, see subclause 10.5<p>.
155: *
156: * @param i the array of int
157: * @param start the start position in the array
158: * @param length the number of int to read from the array
159: * @throws org.xml.sax.SAXException any SAX exception, possibly
160: * wrapping another exception
161: */
162: public void ints(int[] i, int start, int length)
163: throws SAXException;
164:
165: /**
166: * Receive notification of character data as an array of long.
167: *
168: * <p>The application must not attempt to read from the array
169: * outside of the specified range.</p>
170: *
171: * <p>Such notifications will occur for a Fast Infoset SAX parser
172: * when processing data encoded using the "long" encoding
173: * algorithm, see subclause 10.6<p>.
174: *
175: * @param l the array of long
176: * @param start the start position in the array
177: * @param length the number of long to read from the array
178: * @throws org.xml.sax.SAXException any SAX exception, possibly
179: * wrapping another exception
180: */
181: public void longs(long[] l, int start, int length)
182: throws SAXException;
183:
184: /**
185: * Receive notification of character data as an array of float.
186: *
187: * <p>The application must not attempt to read from the array
188: * outside of the specified range.</p>
189: *
190: * <p>Such notifications will occur for a Fast Infoset SAX parser
191: * when processing data encoded using the "float" encoding
192: * algorithm, see subclause 10.8<p>.
193: *
194: * @param f the array of float
195: * @param start the start position in the array
196: * @param length the number of float to read from the array
197: * @throws org.xml.sax.SAXException any SAX exception, possibly
198: * wrapping another exception
199: */
200: public void floats(float[] f, int start, int length)
201: throws SAXException;
202:
203: /**
204: * Receive notification of character data as an array of double.
205: *
206: * <p>The application must not attempt to read from the array
207: * outside of the specified range.</p>
208: *
209: * <p>Such notifications will occur for a Fast Infoset SAX parser
210: * when processing data encoded using the "double" encoding
211: * algorithm, see subclause 10.9<p>.
212: *
213: * @param d the array of double
214: * @param start the start position in the array
215: * @param length the number of double to read from the array
216: * @throws org.xml.sax.SAXException any SAX exception, possibly
217: * wrapping another exception
218: */
219: public void doubles(double[] d, int start, int length)
220: throws SAXException;
221:
222: /**
223: * Receive notification of character data as an two array of UUID.
224: *
225: * <p>The application must not attempt to read from the array
226: * outside of the specified range.</p>
227: *
228: * <p>Such notifications will occur for a Fast Infoset SAX parser
229: * when processing data encoded using the "uuid" encoding
230: * algorithm, see subclause 10.10<p>.
231: *
232: * @param msblsb the array of long containing pairs of most signficant
233: * bits and least significant bits of the UUIDs
234: * @param start the start position in the array
235: * @param length the number of long to read from the array. This will
236: * be twice the number of UUIDs, which are pairs of two long values
237: * @throws org.xml.sax.SAXException any SAX exception, possibly
238: * wrapping another exception
239: */
240: public void uuids(long[] msblsb, int start, int length)
241: throws SAXException;
242: }
|