001: /*
002: * $Id: XMLEntityReader.java,v 1.2 2006/04/01 06:01:48 jeffsuttor Exp $
003: */
004:
005: /*
006: * The contents of this file are subject to the terms
007: * of the Common Development and Distribution License
008: * (the License). You may not use this file except in
009: * compliance with the License.
010: *
011: * You can obtain a copy of the license at
012: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
013: * See the License for the specific language governing
014: * permissions and limitations under the License.
015: *
016: * When distributing Covered Code, include this CDDL
017: * Header Notice in each file and include the License file
018: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
019: * If applicable, add the following below the CDDL Header,
020: * with the fields enclosed by brackets [] replaced by
021: * you own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * [Name of File] [ver.__] [Date]
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028:
029: /*
030: * The Apache Software License, Version 1.1
031: *
032: *
033: * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
034: * reserved.
035: *
036: * Redistribution and use in source and binary forms, with or without
037: * modification, are permitted provided that the following conditions
038: * are met:
039: *
040: * 1. Redistributions of source code must retain the above copyright
041: * notice, this list of conditions and the following disclaimer.
042: *
043: * 2. Redistributions in binary form must reproduce the above copyright
044: * notice, this list of conditions and the following disclaimer in
045: * the documentation and/or other materials provided with the
046: * distribution.
047: *
048: * 3. The end-user documentation included with the redistribution,
049: * if any, must include the following acknowledgment:
050: * "This product includes software developed by the
051: * Apache Software Foundation (http://www.apache.org/)."
052: * Alternately, this acknowledgment may appear in the software itself,
053: * if and wherever such third-party acknowledgments normally appear.
054: *
055: * 4. The names "Xerces" and "Apache Software Foundation" must
056: * not be used to endorse or promote products derived from this
057: * software without prior written permission. For written
058: * permission, please contact apache@apache.org.
059: *
060: * 5. Products derived from this software may not be called "Apache",
061: * nor may "Apache" appear in their name, without prior written
062: * permission of the Apache Software Foundation.
063: *
064: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
065: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
066: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
067: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
068: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
069: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
070: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
071: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
072: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
073: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
074: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
075: * SUCH DAMAGE.
076: */
077:
078: package com.sun.xml.stream;
079:
080: import java.io.IOException;
081:
082: import com.sun.xml.stream.xerces.util.XMLStringBuffer;
083: import com.sun.xml.stream.xerces.xni.*;
084:
085: /**
086: * This class allows various parser scanners to scan basic XML constructs
087: * from entities. This class works directly with the entity manager to
088: * provide this functionality.
089: * <p>
090: * There is only one entity scanner and entity manager per parser. The
091: * entity manager <em>could</em> implement the methods to perform entity
092: * scanning, but the entity scanner class allows a cleaner separation
093: * between entity management API and entity scanning.
094: *
095: * @author Andy Clark, IBM
096: * @author Neeraj Bajaj Sun Microsystems
097: * @author K.Venugopal Sun Microsystems
098: * @version $Id: XMLEntityReader.java,v 1.2 2006/04/01 06:01:48 jeffsuttor Exp $
099: *
100: * @see XMLEntityHandler
101: * @see XMLEntityManager
102: */
103: public abstract class XMLEntityReader implements XMLLocator {
104:
105: //
106: // Public methods
107: //
108:
109: /**
110: * Sets the encoding of the scanner. This method is used by the
111: * scanners if the XMLDecl or TextDecl line contains an encoding
112: * pseudo-attribute.
113: * <p>
114: * <strong>Note:</strong> The underlying character reader on the
115: * current entity will be changed to accomodate the new encoding.
116: * However, the new encoding is ignored if the current reader was
117: * not constructed from an input stream (e.g. an external entity
118: * that is resolved directly to the appropriate java.io.Reader
119: * object).
120: *
121: * @param encoding The IANA encoding name of the new encoding.
122: *
123: * @throws IOException Thrown if the new encoding is not supported.
124: *
125: * @see com.sun.xml.stream.xerces.util.EncodingMap
126: * @see com.sun.xml.stream.xerces.util.XMLChar#isValidIANAEncoding
127: * @see com.sun.xml.stream.xerces.util.XMLChar#isValidJavaEncoding
128: */
129: public abstract void setEncoding(String encoding)
130: throws IOException;
131:
132: public abstract String getEncoding();
133:
134: public abstract int getCharacterOffset();
135:
136: /** the version of the current entity being scanned or the version of the entity on which reader is operating */
137: public abstract void setVersion(String version);
138:
139: /** get the version of the entity on which reader is operating */
140: public abstract String getVersion();
141:
142: /** Returns true if the current entity being scanned is external. */
143: public abstract boolean isExternal();
144:
145: /**
146: * Returns the next character on the input.
147: * <p>
148: * <strong>Note:</strong> The character is <em>not</em> consumed.
149: *
150: * @throws IOException Thrown if i/o error occurs.
151: * @throws EOFException Thrown on end of file.
152: */
153: public abstract int peekChar() throws IOException;
154:
155: /**
156: * Returns the next character on the input.
157: * <p>
158: * <strong>Note:</strong> The character is consumed.
159: *
160: * @throws IOException Thrown if i/o error occurs.
161: * @throws EOFException Thrown on end of file.
162: */
163: public abstract int scanChar() throws IOException;
164:
165: /**
166: * Returns a string matching the NMTOKEN production appearing immediately
167: * on the input as a symbol, or null if NMTOKEN Name string is present.
168: * <p>
169: * <strong>Note:</strong> The NMTOKEN characters are consumed.
170: * <p>
171: * <strong>Note:</strong> The string returned must be a symbol. The
172: * SymbolTable can be used for this purpose.
173: *
174: * @throws IOException Thrown if i/o error occurs.
175: * @throws EOFException Thrown on end of file.
176: *
177: * @see com.sun.xml.stream.xerces.util.SymbolTable
178: * @see com.sun.xml.stream.xerces.util.XMLChar#isName
179: */
180: public abstract String scanNmtoken() throws IOException;
181:
182: /**
183: * Returns a string matching the Name production appearing immediately
184: * on the input as a symbol, or null if no Name string is present.
185: * <p>
186: * <strong>Note:</strong> The Name characters are consumed.
187: * <p>
188: * <strong>Note:</strong> The string returned must be a symbol. The
189: * SymbolTable can be used for this purpose.
190: *
191: * @throws IOException Thrown if i/o error occurs.
192: * @throws EOFException Thrown on end of file.
193: *
194: * @see com.sun.xml.stream.xerces.util.SymbolTable
195: * @see com.sun.xml.stream.xerces.util.XMLChar#isName
196: * @see com.sun.xml.stream.xerces.util.XMLChar#isNameStart
197: */
198: public abstract String scanName() throws IOException;
199:
200: /**
201: * Scans a qualified name from the input, setting the fields of the
202: * QName structure appropriately.
203: * <p>
204: * <strong>Note:</strong> The qualified name characters are consumed.
205: * <p>
206: * <strong>Note:</strong> The strings used to set the values of the
207: * QName structure must be symbols. The SymbolTable can be used for
208: * this purpose.
209: *
210: * @param qname The qualified name structure to fill.
211: *
212: * @return Returns true if a qualified name appeared immediately on
213: * the input and was scanned, false otherwise.
214: *
215: * @throws IOException Thrown if i/o error occurs.
216: * @throws EOFException Thrown on end of file.
217: *
218: * @see com.sun.xml.stream.xerces.util.SymbolTable
219: * @see com.sun.xml.stream.xerces.util.XMLChar#isName
220: * @see com.sun.xml.stream.xerces.util.XMLChar#isNameStart
221: */
222: public abstract boolean scanQName(QName qname) throws IOException;
223:
224: /**
225: * CHANGED:
226: * Scans a range of parsed character data, This function appends the character data to
227: * the supplied buffer.
228: * <p>
229: * <strong>Note:</strong> The characters are consumed.
230: * <p>
231: * <strong>Note:</strong> This method does not guarantee to return
232: * the longest run of parsed character data. This method may return
233: * before markup due to reaching the end of the input buffer or any
234: * other reason.
235: * <p>
236: *
237: * @param content The content structure to fill.
238: *
239: * @return Returns the next character on the input, if known. This
240: * value may be -1 but this does <em>note</em> designate
241: * end of file.
242: *
243: * @throws IOException Thrown if i/o error occurs.
244: * @throws EOFException Thrown on end of file.
245: */
246: public abstract int scanContent(XMLString content)
247: throws IOException;
248:
249: /**
250: * Scans a range of attribute value data, setting the fields of the
251: * XMLString structure, appropriately.
252: * <p>
253: * <strong>Note:</strong> The characters are consumed.
254: * <p>
255: * <strong>Note:</strong> This method does not guarantee to return
256: * the longest run of attribute value data. This method may return
257: * before the quote character due to reaching the end of the input
258: * buffer or any other reason.
259: * <p>
260: * <strong>Note:</strong> The fields contained in the XMLString
261: * structure are not guaranteed to remain valid upon subsequent calls
262: * to the entity scanner. Therefore, the caller is responsible for
263: * immediately using the returned character data or making a copy of
264: * the character data.
265: *
266: * @param quote The quote character that signifies the end of the
267: * attribute value data.
268: * @param content The content structure to fill.
269: *
270: * @return Returns the next character on the input, if known. This
271: * value may be -1 but this does <em>note</em> designate
272: * end of file.
273: *
274: * @throws IOException Thrown if i/o error occurs.
275: * @throws EOFException Thrown on end of file.
276: */
277: public abstract int scanLiteral(int quote, XMLString content)
278: throws IOException;
279:
280: /**
281: * Scans a range of character data up to the specicied delimiter,
282: * setting the fields of the XMLString structure, appropriately.
283: * <p>
284: * <strong>Note:</strong> The characters are consumed.
285: * <p>
286: * <strong>Note:</strong> This assumes that the internal buffer is
287: * at least the same size, or bigger, than the length of the delimiter
288: * and that the delimiter contains at least one character.
289: * <p>
290: * <strong>Note:</strong> This method does not guarantee to return
291: * the longest run of character data. This method may return before
292: * the delimiter due to reaching the end of the input buffer or any
293: * other reason.
294: * <p>
295: * <strong>Note:</strong> The fields contained in the XMLString
296: * structure are not guaranteed to remain valid upon subsequent calls
297: * to the entity scanner. Therefore, the caller is responsible for
298: * immediately using the returned character data or making a copy of
299: * the character data.
300: *
301: * @param delimiter The string that signifies the end of the character
302: * data to be scanned.
303: * @param data The data structure to fill.
304: *
305: * @return Returns true if there is more data to scan, false otherwise.
306: *
307: * @throws IOException Thrown if i/o error occurs.
308: * @throws EOFException Thrown on end of file.
309: */
310: public abstract boolean scanData(String delimiter,
311: XMLStringBuffer data) throws IOException;
312:
313: /**
314: * Skips a character appearing immediately on the input.
315: * <p>
316: * <strong>Note:</strong> The character is consumed only if it matches
317: * the specified character.
318: *
319: * @param c The character to skip.
320: *
321: * @return Returns true if the character was skipped.
322: *
323: * @throws IOException Thrown if i/o error occurs.
324: * @throws EOFException Thrown on end of file.
325: */
326: public abstract boolean skipChar(int c) throws IOException;
327:
328: /**
329: * Skips space characters appearing immediately on the input.
330: * <p>
331: * <strong>Note:</strong> The characters are consumed only if they are
332: * space characters.
333: *
334: * @return Returns true if at least one space character was skipped.
335: *
336: * @throws IOException Thrown if i/o error occurs.
337: * @throws EOFException Thrown on end of file.
338: *
339: * @see com.sun.xml.stream.xerces.util.XMLChar#isSpace
340: */
341: public abstract boolean skipSpaces() throws IOException;
342:
343: /**
344: * Skips the specified string appearing immediately on the input.
345: * <p>
346: * <strong>Note:</strong> The characters are consumed only if they are
347: * space characters.
348: *
349: * @param s The string to skip.
350: *
351: * @return Returns true if the string was skipped.
352: *
353: * @throws IOException Thrown if i/o error occurs.
354: * @throws EOFException Thrown on end of file.
355: */
356: public abstract boolean skipString(String s) throws IOException;
357:
358: public abstract void registerListener(XMLBufferListener listener);
359:
360: } // class XMLEntityScanner
|