001: /*
002: * @(#)SAXParser.java 1.9 01/12/03
003: *
004: * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
005: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
006: */
007:
008: package javax.xml.parsers;
009:
010: import java.io.InputStream;
011: import java.io.IOException;
012: import java.io.File;
013:
014: import org.xml.sax.Parser;
015: import org.xml.sax.XMLReader;
016: import org.xml.sax.HandlerBase;
017: import org.xml.sax.helpers.DefaultHandler;
018: import org.xml.sax.InputSource;
019: import org.xml.sax.SAXException;
020: import org.xml.sax.SAXNotRecognizedException;
021: import org.xml.sax.SAXNotSupportedException;
022:
023: /**
024: * Defines the API that wraps an {@link org.xml.sax.XMLReader}
025: * implementation class. In JAXP 1.0, this class wrapped the
026: * {@link org.xml.sax.Parser} interface, however this interface was
027: * replaced by the {@link org.xml.sax.XMLReader}. For ease
028: * of transition, this class continues to support the same name
029: * and interface as well as supporting new methods.
030: *
031: * An instance of this class can be obtained from the
032: * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
033: * Once an instance of this class is obtained, XML can be parsed from
034: * a variety of input sources. These input sources are InputStreams,
035: * Files, URLs, and SAX InputSources.<p>
036: *
037: *
038: * As the content is parsed by the underlying parser, methods of the
039: * given {@link org.xml.sax.HandlerBase} or the
040: * {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
041: *
042: * Implementors of this class which wrap an underlying implementation
043: * can consider using the {@link org.xml.sax.helpers.ParserAdapter}
044: * class to initially adapt their SAX1 impelemntation to work under
045: * this revised class.<p>
046: *
047: * An implementation of <code>SAXParser</code> is <em>NOT</em>
048: * guaranteed to behave as per the specification if it is used concurrently by
049: * two or more threads. It is recommended to have one instance of the
050: * <code>SAXParser</code> per thread or it is upto the application to
051: * make sure about the use of <code>SAXParser</code> from more than one
052: * thread.
053: *
054: * @since JAXP 1.0
055: * @version 1.0
056: */
057:
058: public abstract class SAXParser {
059:
060: protected SAXParser() {
061:
062: }
063:
064: /**
065: * Parse the content of the given {@link java.io.InputStream}
066: * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
067: * <i> Use of the DefaultHandler version of this method is recommended as
068: * the HandlerBase class has been deprecated in SAX 2.0</i>
069: *
070: * @param is InputStream containing the content to be parsed.
071: * @param hb The SAX HandlerBase to use.
072: * @exception IOException If any IO errors occur.
073: * @exception IllegalArgumentException If the given InputStream is null.
074: * @exception SAXException If the underlying parser throws a
075: * SAXException while parsing.
076: * @see org.xml.sax.DocumentHandler
077: */
078:
079: public void parse(InputStream is, HandlerBase hb)
080: throws SAXException, IOException {
081: if (is == null) {
082: throw new IllegalArgumentException(
083: "InputStream cannot be null");
084: }
085:
086: InputSource input = new InputSource(is);
087: this .parse(input, hb);
088: }
089:
090: /**
091: * Parse the content of the given {@link java.io.InputStream}
092: * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
093: * <i> Use of the DefaultHandler version of this method is recommended as
094: * the HandlerBase class has been deprecated in SAX 2.0</i>
095: *
096: * @param is InputStream containing the content to be parsed.
097: * @param hb The SAX HandlerBase to use.
098: * @param systemId The systemId which is needed for resolving relative URIs.
099: * @exception IOException If any IO errors occur.
100: * @exception IllegalArgumentException If the given InputStream is null.
101: * @exception SAXException If the underlying parser throws a
102: * SAXException while parsing.
103: * @see org.xml.sax.DocumentHandler
104: * version of this method instead.
105: */
106:
107: public void parse(InputStream is, HandlerBase hb, String systemId)
108: throws SAXException, IOException {
109: if (is == null) {
110: throw new IllegalArgumentException(
111: "InputStream cannot be null");
112: }
113:
114: InputSource input = new InputSource(is);
115: input.setSystemId(systemId);
116: this .parse(input, hb);
117: }
118:
119: /**
120: * Parse the content of the given {@link java.io.InputStream}
121: * instance as XML using the specified
122: * {@link org.xml.sax.helpers.DefaultHandler}.
123: *
124: * @param is InputStream containing the content to be parsed.
125: * @param dh The SAX DefaultHandler to use.
126: * @exception IOException If any IO errors occur.
127: * @exception IllegalArgumentException If the given InputStream is null.
128: * @exception SAXException If the underlying parser throws a
129: * SAXException while parsing.
130: * @see org.xml.sax.DocumentHandler
131: */
132:
133: public void parse(InputStream is, DefaultHandler dh)
134: throws SAXException, IOException {
135: if (is == null) {
136: throw new IllegalArgumentException(
137: "InputStream cannot be null");
138: }
139:
140: InputSource input = new InputSource(is);
141: this .parse(input, dh);
142: }
143:
144: /**
145: * Parse the content of the given {@link java.io.InputStream}
146: * instance as XML using the specified
147: * {@link org.xml.sax.helpers.DefaultHandler}.
148: *
149: * @param is InputStream containing the content to be parsed.
150: * @param dh The SAX DefaultHandler to use.
151: * @param systemId The systemId which is needed for resolving relative URIs.
152: * @exception IOException If any IO errors occur.
153: * @exception IllegalArgumentException If the given InputStream is null.
154: * @exception SAXException If the underlying parser throws a
155: * SAXException while parsing.
156: * @see org.xml.sax.DocumentHandler
157: * version of this method instead.
158: */
159:
160: public void parse(InputStream is, DefaultHandler dh, String systemId)
161: throws SAXException, IOException {
162: if (is == null) {
163: throw new IllegalArgumentException(
164: "InputStream cannot be null");
165: }
166:
167: InputSource input = new InputSource(is);
168: input.setSystemId(systemId);
169: this .parse(input, dh);
170: }
171:
172: /**
173: * Parse the content described by the giving Uniform Resource
174: * Identifier (URI) as XML using the specified
175: * {@link org.xml.sax.HandlerBase}.
176: * <i> Use of the DefaultHandler version of this method is recommended as
177: * the <code>HandlerBase</code> class has been deprecated in SAX 2.0</i>
178: *
179: * @param uri The location of the content to be parsed.
180: * @param hb The SAX HandlerBase to use.
181: * @exception IOException If any IO errors occur.
182: * @exception IllegalArgumentException If the uri is null.
183: * @exception SAXException If the underlying parser throws a
184: * SAXException while parsing.
185: * @see org.xml.sax.DocumentHandler
186: */
187:
188: public void parse(String uri, HandlerBase hb) throws SAXException,
189: IOException {
190: if (uri == null) {
191: throw new IllegalArgumentException("uri cannot be null");
192: }
193:
194: InputSource input = new InputSource(uri);
195: this .parse(input, hb);
196: }
197:
198: /**
199: * Parse the content described by the giving Uniform Resource
200: * Identifier (URI) as XML using the specified
201: * {@link org.xml.sax.helpers.DefaultHandler}.
202: *
203: * @param uri The location of the content to be parsed.
204: * @param dh The SAX DefaultHandler to use.
205: * @exception IOException If any IO errors occur.
206: * @exception IllegalArgumentException If the uri is null.
207: * @exception SAXException If the underlying parser throws a
208: * SAXException while parsing.
209: * @see org.xml.sax.DocumentHandler
210: */
211:
212: public void parse(String uri, DefaultHandler dh)
213: throws SAXException, IOException {
214: if (uri == null) {
215: throw new IllegalArgumentException("uri cannot be null");
216: }
217:
218: InputSource input = new InputSource(uri);
219: this .parse(input, dh);
220: }
221:
222: /**
223: * Parse the content of the file specified as XML using the
224: * specified {@link org.xml.sax.HandlerBase}.
225: * <i> Use of the DefaultHandler version of this method is recommended as
226: * the HandlerBase class has been deprecated in SAX 2.0</i>
227: *
228: * @param f The file containing the XML to parse
229: * @param hb The SAX HandlerBase to use.
230: * @exception IOException If any IO errors occur.
231: * @exception IllegalArgumentException If the File object is null.
232: * @see org.xml.sax.DocumentHandler
233: * @exception SAXException If the underlying parser throws a
234: * SAXException while parsing.
235: */
236:
237: public void parse(File f, HandlerBase hb) throws SAXException,
238: IOException {
239: if (f == null) {
240: throw new IllegalArgumentException("File cannot be null");
241: }
242:
243: String uri = "file:" + f.getAbsolutePath();
244: if (File.separatorChar == '\\') {
245: uri = uri.replace('\\', '/');
246: }
247: InputSource input = new InputSource(uri);
248: this .parse(input, hb);
249: }
250:
251: /**
252: * Parse the content of the file specified as XML using the
253: * specified {@link org.xml.sax.helpers.DefaultHandler}.
254: *
255: * @param f The file containing the XML to parse
256: * @param dh The SAX DefaultHandler to use.
257: * @exception IOException If any IO errors occur.
258: * @exception IllegalArgumentException If the File object is null.
259: * @exception SAXException If the underlying parser throws a
260: * SAXException while parsing.
261: * @see org.xml.sax.DocumentHandler
262: */
263:
264: public void parse(File f, DefaultHandler dh) throws SAXException,
265: IOException {
266: if (f == null) {
267: throw new IllegalArgumentException("File cannot be null");
268: }
269:
270: String uri = "file:" + f.getAbsolutePath();
271: if (File.separatorChar == '\\') {
272: uri = uri.replace('\\', '/');
273: }
274: InputSource input = new InputSource(uri);
275: this .parse(input, dh);
276: }
277:
278: /**
279: * Parse the content given {@link org.xml.sax.InputSource}
280: * as XML using the specified
281: * {@link org.xml.sax.HandlerBase}.
282: * <i> Use of the DefaultHandler version of this method is recommended as
283: * the HandlerBase class has been deprecated in SAX 2.0</i>
284: *
285: * @param is The InputSource containing the content to be parsed.
286: * @param hb The SAX HandlerBase to use.
287: * @exception IOException If any IO errors occur.
288: * @exception IllegalArgumentException If the InputSource is null.
289: * @exception SAXException If the underlying parser throws a
290: * SAXException while parsing.
291: * @see org.xml.sax.DocumentHandler
292: */
293:
294: public void parse(InputSource is, HandlerBase hb)
295: throws SAXException, IOException {
296: if (is == null) {
297: throw new IllegalArgumentException(
298: "InputSource cannot be null");
299: }
300:
301: Parser parser = this .getParser();
302: if (hb != null) {
303: parser.setDocumentHandler(hb);
304: parser.setEntityResolver(hb);
305: parser.setErrorHandler(hb);
306: parser.setDTDHandler(hb);
307: }
308: parser.parse(is);
309: }
310:
311: /**
312: * Parse the content given {@link org.xml.sax.InputSource}
313: * as XML using the specified
314: * {@link org.xml.sax.helpers.DefaultHandler}.
315: *
316: * @param is The InputSource containing the content to be parsed.
317: * @param dh The SAX DefaultHandler to use.
318: * @exception IOException If any IO errors occur.
319: * @exception IllegalArgumentException If the InputSource is null.
320: * @exception SAXException If the underlying parser throws a
321: * SAXException while parsing.
322: * @see org.xml.sax.DocumentHandler
323: */
324:
325: public void parse(InputSource is, DefaultHandler dh)
326: throws SAXException, IOException {
327: if (is == null) {
328: throw new IllegalArgumentException(
329: "InputSource cannot be null");
330: }
331:
332: XMLReader reader = this .getXMLReader();
333: if (dh != null) {
334: reader.setContentHandler(dh);
335: reader.setEntityResolver(dh);
336: reader.setErrorHandler(dh);
337: reader.setDTDHandler(dh);
338: }
339: reader.parse(is);
340: }
341:
342: /**
343: * Returns the SAX parser that is encapsultated by the
344: * implementation of this class.
345: *
346: * @return The SAX parser that is encapsultated by the
347: * implementation of this class.
348: */
349:
350: public abstract org.xml.sax.Parser getParser() throws SAXException;
351:
352: /**
353: * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
354: * implementation of this class.
355: *
356: * @return The XMLReader that is encapsulated by the
357: * implementation of this class.
358: */
359:
360: public abstract org.xml.sax.XMLReader getXMLReader()
361: throws SAXException;
362:
363: /**
364: * Indicates whether or not this parser is configured to
365: * understand namespaces.
366: *
367: * @return true if this parser is configured to
368: * understand namespaces; false otherwise.
369: */
370:
371: public abstract boolean isNamespaceAware();
372:
373: /**
374: * Indicates whether or not this parser is configured to
375: * validate XML documents.
376: *
377: * @return true if this parser is configured to
378: * validate XML documents; false otherwise.
379: */
380:
381: public abstract boolean isValidating();
382:
383: /**
384: * Sets the particular property in the underlying implementation of
385: * {@link org.xml.sax.XMLReader}.
386: * A list of the core features and properties can be found at
387: * <a href="http://www.megginson.com/SAX/Java/features.html"> http://www.megginson.com/SAX/Java/features.html </a>
388: *
389: * @param name The name of the property to be set.
390: * @param value The value of the property to be set.
391: * @exception SAXNotRecognizedException When the underlying XMLReader does
392: * not recognize the property name.
393: *
394: * @exception SAXNotSupportedException When the underlying XMLReader
395: * recognizes the property name but doesn't support the
396: * property.
397: *
398: * @see org.xml.sax.XMLReader#setProperty
399: */
400: public abstract void setProperty(String name, Object value)
401: throws SAXNotRecognizedException, SAXNotSupportedException;
402:
403: /**
404: *
405: * Returns the particular property requested for in the underlying
406: * implementation of {@link org.xml.sax.XMLReader}.
407: *
408: * @param name The name of the property to be retrieved.
409: * @return Value of the requested property.
410: *
411: * @exception SAXNotRecognizedException When the underlying XMLReader does
412: * not recognize the property name.
413: *
414: * @exception SAXNotSupportedException When the underlying XMLReader
415: * recognizes the property name but doesn't support the
416: * property.
417: *
418: * @see org.xml.sax.XMLReader#getProperty
419: */
420: public abstract Object getProperty(String name)
421: throws SAXNotRecognizedException, SAXNotSupportedException;
422: }
|