old-autovect-branch/libjava/classpath/javax/xml/parsers/SAXParser.java

   1 /* SAXParser.java --
   2    Copyright (C) 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.xml.parsers;
  39
  40 import java.io.File;
  41 import java.io.FileInputStream;
  42 import java.io.InputStream;
  43 import java.io.IOException;
  44 import javax.xml.validation.Schema;
  45 import org.xml.sax.HandlerBase;
  46 import org.xml.sax.InputSource;
  47 import org.xml.sax.Parser;
  48 import org.xml.sax.SAXException;
  49 import org.xml.sax.SAXNotRecognizedException;
  50 import org.xml.sax.SAXNotSupportedException;
  51 import org.xml.sax.XMLReader;
  52 import org.xml.sax.helpers.DefaultHandler;
  53
  54 /**
  55  * Convenience class for using or accessing a SAX version 1 or 2 parser.
  56  * Instances of this class are <em>not</em> guaranteed to be thread safe.
  57  *
  58  * @author (a href='mailto:dog@gnu.org'>Chris Burdess</a)
  59  */
  60 public abstract class SAXParser
  61 {
  62
  63   protected SAXParser()
  64   {
  65   }
  66
  67   /**
  68    * Parse the specifed input stream, reporting SAX1 events to the given
  69    * handler.
  70    * Prefer the SAX2 version of this method, since the HandlerBase class is
  71    * now deprecated.
  72    * Also prefer the version of this method that specifies a system ID, in
  73    * order to resolve external references correctly.
  74    * @param is an XML input stream
  75    * @param hb the SAX1 handler
  76    * @exception IllegalArgumentException if the input stream is null
  77    * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler)
  78    */
  79   public void parse(InputStream is, HandlerBase hb)
  80     throws SAXException, IOException
  81   {
  82     if (is == null)
  83       {
  84         throw new IllegalArgumentException("input stream is null");
  85       }
  86     parse(new InputSource(is), hb);
  87   }
  88
  89   /**
  90    * Parse the specified input stream, reporting SAX1 events to the given
  91    * handler.
  92    * Prefer the SAX2 version of this method, since the HandlerBase class is
  93    * now deprecated.
  94    * @param is an XML input stream
  95    * @param hb the SAX1 handler
  96    * @param systemId the system ID of the XML document
  97    * @exception IllegalArgumentException if the input stream is null
  98    * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler,java.lang.String)
  99    */
 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 }