View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package javax.xml.parsers;
18  
19  import java.io.IOException;
20  import java.io.InputStream;
21  
22  import org.xml.sax.InputSource;
23  import org.xml.sax.SAXException;
24  import org.xml.sax.helpers.DefaultHandler;
25  
26  /***
27   * Defines the API that wraps an {@link org.xml.sax.XMLReader}
28   * implementation class. In JAXP 1.0, this class wrapped the
29   * {@link org.xml.sax.Parser} interface, however this interface was
30   * replaced by the {@link org.xml.sax.XMLReader}. For ease
31   * of transition, this class continues to support the same name
32   * and interface as well as supporting new methods.
33   *
34   * An instance of this class can be obtained from the
35   * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
36   * Once an instance of this class is obtained, XML can be parsed from
37   * a variety of input sources. These input sources are InputStreams,
38   * Files, URLs, and SAX InputSources.<p>
39   *
40   *
41   * As the content is parsed by the underlying parser, methods of the
42   * given {@link org.xml.sax.HandlerBase} or the
43   * {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
44   *
45   * Implementors of this class which wrap an underlying implementation
46   * can consider using the {@link org.xml.sax.helpers.ParserAdapter}
47   * class to initially adapt their SAX1 impelemntation to work under
48   * this revised class.<p>
49   *
50   * An implementation of <code>SAXParser</code> is <em>NOT</em> 
51   * guaranteed to behave as per the specification if it is used concurrently by 
52   * two or more threads. It is recommended to have one instance of the
53   * <code>SAXParser</code> per thread or it is upto the application to 
54   * make sure about the use of <code>SAXParser</code> from more than one
55   * thread.
56   *
57   * @author Ias (iasandcb@tmax.co.kr)
58   */
59  
60  public abstract class SAXParser {
61  
62  	protected SAXParser() {
63  
64  	}
65  
66  	/***
67  	 * Parse the content of the given {@link java.io.InputStream}
68  	 * instance as XML using the specified
69  	 * {@link org.xml.sax.helpers.DefaultHandler}.
70  	 *
71  	 * @param is InputStream containing the content to be parsed.
72  	 * @param dh The SAX DefaultHandler to use.
73  	 * @exception IOException If any IO errors occur.
74  	 * @exception IllegalArgumentException If the given InputStream is null.
75  	 * @exception SAXException If the underlying parser throws a
76  	 * SAXException while parsing.
77  	 * @see org.xml.sax.DocumentHandler
78  	 */
79  
80  	public abstract void parse(InputStream is, DefaultHandler dh) throws SAXException, IOException;
81  
82  	/***
83  	 * Parse the content given {@link org.xml.sax.InputSource}
84  	 * as XML using the specified
85  	 * {@link org.xml.sax.helpers.DefaultHandler}.
86  	 *
87  	 * @param is The InputSource containing the content to be parsed.
88  	 * @param dh The SAX DefaultHandler to use.
89  	 * @exception IOException If any IO errors occur.
90  	 * @exception IllegalArgumentException If the InputSource is null.
91  	 * @exception SAXException If the underlying parser throws a
92  	 * SAXException while parsing.
93  	 * @see org.xml.sax.DocumentHandler
94  	 */
95  
96  	public abstract void parse(InputSource is, DefaultHandler dh) throws SAXException, IOException;
97  
98  	/***
99  	 * Indicates whether or not this parser is configured to
100 	 * understand namespaces.
101 	 *
102 	 * @return true if this parser is configured to
103 	 *         understand namespaces; false otherwise.
104 	 */
105 
106 	public abstract boolean isNamespaceAware();
107 
108 	/***
109 	 * Indicates whether or not this parser is configured to
110 	 * validate XML documents.
111 	 *
112 	 * @return true if this parser is configured to
113 	 *         validate XML documents; false otherwise.
114 	 */
115 
116 	public abstract boolean isValidating();
117 
118 }