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    }