001 /* SAXParser.java --
002 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath 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 for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.xml.parsers;
039
040 import java.io.File;
041 import java.io.FileInputStream;
042 import java.io.InputStream;
043 import java.io.IOException;
044 import javax.xml.validation.Schema;
045 import org.xml.sax.HandlerBase;
046 import org.xml.sax.InputSource;
047 import org.xml.sax.Parser;
048 import org.xml.sax.SAXException;
049 import org.xml.sax.SAXNotRecognizedException;
050 import org.xml.sax.SAXNotSupportedException;
051 import org.xml.sax.XMLReader;
052 import org.xml.sax.helpers.DefaultHandler;
053
054 /**
055 * Convenience class for using or accessing a SAX version 1 or 2 parser.
056 * Instances of this class are <em>not</em> guaranteed to be thread safe.
057 *
058 * @author (a href='mailto:dog@gnu.org'>Chris Burdess</a)
059 */
060 public abstract class SAXParser
061 {
062
063 protected SAXParser()
064 {
065 }
066
067 /**
068 * Parse the specifed input stream, reporting SAX1 events to the given
069 * handler.
070 * Prefer the SAX2 version of this method, since the HandlerBase class is
071 * now deprecated.
072 * Also prefer the version of this method that specifies a system ID, in
073 * order to resolve external references correctly.
074 * @param is an XML input stream
075 * @param hb the SAX1 handler
076 * @exception IllegalArgumentException if the input stream is null
077 * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler)
078 */
079 public void parse(InputStream is, HandlerBase hb)
080 throws SAXException, IOException
081 {
082 if (is == null)
083 {
084 throw new IllegalArgumentException("input stream is null");
085 }
086 parse(new InputSource(is), hb);
087 }
088
089 /**
090 * Parse the specified input stream, reporting SAX1 events to the given
091 * handler.
092 * Prefer the SAX2 version of this method, since the HandlerBase class is
093 * now deprecated.
094 * @param is an XML input stream
095 * @param hb the SAX1 handler
096 * @param systemId the system ID of the XML document
097 * @exception IllegalArgumentException if the input stream is null
098 * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler,java.lang.String)
099 */
100 public void parse(InputStream is, HandlerBase hb, String systemId)
101 throws SAXException, IOException
102 {
103 if (is == null)
104 {
105 throw new IllegalArgumentException("input stream is null");
106 }
107 InputSource source = new InputSource(is);
108 source.setSystemId(systemId);
109 parse(source, hb);
110 }
111
112 /**
113 * Parse the specified input stream, reporting SAX2 events to the given
114 * handler.
115 * Prefer the version of this method that specifies a system ID, in
116 * order to resolve external references correctly.
117 * @param is an XML input stream
118 * @param dh the SAX2 handler
119 * @exception IllegalArgumentException if the input stream is null
120 */
121 public void parse(InputStream is, DefaultHandler dh)
122 throws SAXException, IOException
123 {
124 if (is == null)
125 {
126 throw new IllegalArgumentException("input stream is null");
127 }
128 parse(new InputSource(is), dh);
129 }
130
131 /**
132 * Parse the specified input stream, reporting SAX2 events to the given
133 * handler.
134 * @param is an XML input stream
135 * @param dh the SAX2 handler
136 * @param systemId the system ID of the XML document
137 * @exception IllegalArgumentException if the input stream is null
138 */
139 public void parse (InputStream is, DefaultHandler dh, String systemId)
140 throws SAXException, IOException
141 {
142 if (is == null)
143 {
144 throw new IllegalArgumentException("input stream is null");
145 }
146 InputSource source = new InputSource(is);
147 source.setSystemId(systemId);
148 parse(source, dh);
149 }
150
151 /**
152 * Parse the content of the specified URI, reporting SAX1 events to the
153 * given handler.
154 * Prefer the SAX2 version of this method, since the HandlerBase class is
155 * now deprecated.
156 * @param uri an XML system ID
157 * @param hb the SAX1 handler
158 * @exception IllegalArgumentException if the URI is null
159 * @see #parse(java.lang.String,org.xml.sax.helpers.DefaultHandler)
160 */
161 public void parse(String uri, HandlerBase hb)
162 throws SAXException, IOException
163 {
164 if (uri == null)
165 {
166 throw new IllegalArgumentException("URI is null");
167 }
168 parse(new InputSource(uri), hb);
169 }
170
171 /**
172 * Parse the content of the specified URI, reporting SAX2 events to the
173 * given handler.
174 * @param uri an XML system ID
175 * @param dh the SAX2 handler
176 * @exception IllegalArgumentException if the URI is null
177 */
178 public void parse(String uri, DefaultHandler dh)
179 throws SAXException, IOException
180 {
181 if (uri == null)
182 {
183 throw new IllegalArgumentException("URI is null");
184 }
185 parse(new InputSource(uri), dh);
186 }
187
188 /**
189 * Parse the content of the specified file, reporting SAX1 events to the
190 * given handler.
191 * Prefer the SAX2 version of this method, since the HandlerBase class is
192 * now deprecated.
193 * @param f an XML file
194 * @param hb the SAX1 handler
195 * @exception IllegalArgumentException if the file is null
196 * @see #parse(java.io.File,org.xml.sax.helpers.DefaultHandler)
197 */
198 public void parse(File f, HandlerBase hb)
199 throws SAXException, IOException
200 {
201 if (f == null)
202 {
203 throw new IllegalArgumentException("file is null");
204 }
205 InputSource source = new InputSource(new FileInputStream(f));
206 source.setSystemId(f.toURL().toString());
207 parse(source, hb);
208 }
209
210 /**
211 * Parse the content of the specified file, reporting SAX2 events to the
212 * given handler.
213 * @param f an XML file
214 * @param dh the SAX2 handler
215 * @exception IllegalArgumentException if the file is null
216 */
217 public void parse(File f, DefaultHandler dh)
218 throws SAXException, IOException
219 {
220 if (f == null)
221 {
222 throw new IllegalArgumentException("file is null");
223 }
224 InputSource source = new InputSource(new FileInputStream(f));
225 source.setSystemId(f.toURL().toString());
226 parse(source, dh);
227 }
228
229 /**
230 * Parse the specified input source, reporting SAX1 events to the
231 * given handler.
232 * Prefer the SAX2 version of this method, since the HandlerBase class is
233 * now deprecated.
234 * @param is the SAX input source
235 * @param hb the SAX1 handler
236 * @exception IllegalArgumentException if the input source is null
237 * @see #parse(org.xml.sax.InputSource,org.xml.sax.helpers.DefaultHandler)
238 */
239 public void parse(InputSource is, HandlerBase hb)
240 throws SAXException, IOException
241 {
242 if (is == null)
243 {
244 throw new IllegalArgumentException("input source is null");
245 }
246 Parser parser = getParser();
247 parser.setDocumentHandler(hb);
248 parser.setDTDHandler(hb);
249 parser.setEntityResolver(hb);
250 parser.setErrorHandler(hb);
251 parser.parse(is);
252 }
253
254 /**
255 * Parse the specified input source, reporting SAX2 events to the
256 * given handler.
257 * @param is an XML file
258 * @param dh the SAX2 handler
259 * @exception IllegalArgumentException if the input source is null
260 */
261 public void parse(InputSource is, DefaultHandler dh)
262 throws SAXException, IOException
263 {
264 if (is == null)
265 {
266 throw new IllegalArgumentException("input source is null");
267 }
268 XMLReader reader = getXMLReader();
269 reader.setContentHandler(dh);
270 reader.setDTDHandler(dh);
271 reader.setEntityResolver(dh);
272 reader.setErrorHandler(dh);
273 reader.parse(is);
274 }
275
276 /**
277 * Returns the underlying SAX1 parser.
278 */
279 public abstract Parser getParser() throws SAXException;
280
281 /**
282 * Returns the underlying SAX2 parser.
283 * @since 1.1
284 */
285 public abstract XMLReader getXMLReader() throws SAXException;
286
287 /**
288 * Indicates whether this parser is XML Namespace aware.
289 */
290 public abstract boolean isNamespaceAware();
291
292 /**
293 * Indicates whether this parser will validate its input.
294 */
295 public abstract boolean isValidating();
296
297 /**
298 * Sets the specified SAX2 parser property.
299 * @param name the name of the property
300 * @param value the value of the property
301 */
302 public abstract void setProperty(String name, Object value)
303 throws SAXNotRecognizedException, SAXNotSupportedException;
304
305 /**
306 * Returns the value of the specified SAX2 parser property.
307 * @param name the name of the property
308 */
309 public abstract Object getProperty(String name)
310 throws SAXNotRecognizedException, SAXNotSupportedException;
311
312 // -- JAXP 1.3 methods --
313
314 /**
315 * Resets this parser to its original configuration.
316 * @since 1.3
317 */
318 public void reset()
319 {
320 }
321
322 /**
323 * Returns the schema in use by this parser.
324 * @since 1.3
325 */
326 public Schema getSchema()
327 {
328 return null;
329 }
330
331 /**
332 * Indicates whether this parser is XInclude-aware.
333 * @since 1.3
334 */
335 public boolean isXIncludeAware()
336 {
337 return false;
338 }
339
340 }