001/* SAXParser.java --
002   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.xml.parsers;
039
040import java.io.File;
041import java.io.FileInputStream;
042import java.io.InputStream;
043import java.io.IOException;
044import javax.xml.validation.Schema;
045import org.xml.sax.HandlerBase;
046import org.xml.sax.InputSource;
047import org.xml.sax.Parser;
048import org.xml.sax.SAXException;
049import org.xml.sax.SAXNotRecognizedException;
050import org.xml.sax.SAXNotSupportedException;
051import org.xml.sax.XMLReader;
052import 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 */
060public 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}