001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.xml.parsers;
028:
029: import java.io.IOException;
030: import java.io.InputStream;
031:
032: import org.xml.sax.*;
033: import org.xml.sax.helpers.DefaultHandler;
034:
035: /**
036: * Defines the API that represents a simple SAX parser.
037: *
038: * An instance of this class can be obtained from the
039: * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
040: * Once an instance of this class is obtained, XML can be parsed from
041: * an InputStream<p>
042: *
043: * As the content is parsed by the underlying parser, methods of the
044: * given {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
045: *
046: * An implementation of <code>SAXParser</code> is <em>NOT</em>
047: * guaranteed to behave as per the specification if it is used concurrently by
048: * two or more threads. It is recommended to have one instance of the
049: * <code>SAXParser</code> per thread or it is upto the application to
050: * make sure about the use of <code>SAXParser</code> from more than one
051: * thread.
052: *
053: * @since JAXP 1.0
054: * @version 1.0
055: */
056:
057: public abstract class SAXParser {
058:
059: protected SAXParser() {
060: }
061:
062: /**
063: * Parse the content of the given {@link java.io.InputStream}
064: * instance as XML using the specified
065: * {@link org.xml.sax.helpers.DefaultHandler}.
066: *
067: * @param is InputStream containing the content to be parsed.
068: * @param dh The SAX DefaultHandler to use.
069: * @exception IOException If any IO errors occur.
070: * @exception IllegalArgumentException If the given InputStream is null.
071: * @exception SAXException If the underlying parser throws a
072: * SAXException while parsing.
073: */
074:
075: public abstract void parse(InputStream is, DefaultHandler dh)
076: throws SAXException, IOException;
077:
078: /**
079: * Parse the content given {@link org.xml.sax.InputSource}
080: * as XML using the specified
081: * {@link org.xml.sax.helpers.DefaultHandler}.
082: *
083: * @param is The InputSource containing the content to be parsed.
084: * @param dh The SAX DefaultHandler to use.
085: * @exception IOException If any IO errors occur.
086: * @exception IllegalArgumentException If the InputSource is null.
087: * @exception SAXException If the underlying parser throws a
088: * SAXException while parsing.
089: * @see org.xml.sax.DocumentHandler
090: */
091:
092: public abstract void parse(InputSource is, DefaultHandler dh)
093: throws SAXException, IOException;
094:
095: /**
096: * Indicates whether or not this parser is configured to
097: * understand namespaces.
098: *
099: * @return true if this parser is configured to
100: * understand namespaces; false otherwise.
101: */
102:
103: public abstract boolean isNamespaceAware();
104:
105: /**
106: * Indicates whether or not this parser is configured to validate
107: * XML documents.
108: *
109: * @return true if this parser is configured to validate XML
110: * documents; false otherwise.
111: */
112:
113: public abstract boolean isValidating();
114: }
|