001    /* DocumentBuilder.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.w3c.dom.Document;
046    import org.w3c.dom.DOMImplementation;
047    import org.xml.sax.InputSource;
048    import org.xml.sax.EntityResolver;
049    import org.xml.sax.ErrorHandler;
050    import org.xml.sax.SAXException;
051    
052    /**
053     * Convenience class for parsing an XML document into a W3C DOM object
054     * graph.
055     * Instances of this class are <em>not</em> guaranteed to be thread safe.
056     *
057     * @author (a href='mailto:dog@gnu.org'>Chris Burdess</a)
058     */
059    public abstract class DocumentBuilder
060    {
061    
062      protected DocumentBuilder()
063      {
064      }
065    
066      /**
067       * Parse the specified input stream and return a DOM Document.
068       * Prefer the version of this method that specifies a system ID, in order
069       * to resolve external references correctly.
070       * @param is an XML input stream
071       * @exception IllegalArgumentException if the input stream is null
072       */
073      public Document parse(InputStream is) 
074        throws SAXException, IOException
075      {
076        if (is == null)
077          {
078            throw new IllegalArgumentException("input stream is null");
079          }
080        return parse(new InputSource(is));
081      }
082    
083      /**
084       * Parse the specified input stream and return a DOM Document.
085       * @param is an XML input stream
086       * @param systemId the system ID of the XML document
087       * @exception IllegalArgumentException if the input stream is null
088       */
089      public Document parse(InputStream is, String systemId) 
090        throws SAXException, IOException
091      {
092        if (is == null)
093          {
094            throw new IllegalArgumentException("input stream is null");
095          }
096        InputSource  source = new InputSource(is);
097        source.setSystemId(systemId);
098        return parse(source);
099      }
100    
101      /**
102       * Parse the content of the specified URI and return a DOM Document.
103       * @param uri an XML system ID
104       * @exception IllegalArgumentException if the URI is null
105       */
106      public Document parse(String uri) 
107        throws SAXException, IOException
108      {
109        if (uri == null)
110          {
111            throw new IllegalArgumentException("URI is null");
112          }
113        return parse(new InputSource(uri));
114      }
115    
116      /**
117       * Parse the specified file and return a DOM Document.
118       * @param f the XML file
119       * @exception IllegalArgumentException if the file is null
120       */
121      public Document parse(File f) 
122        throws SAXException, IOException
123      {
124        if (f == null)
125          {
126            throw new IllegalArgumentException("file is null");
127          }
128        InputSource  source = new InputSource(new FileInputStream(f));
129        source.setSystemId(f.toURL().toString());
130        return parse(source);
131      }
132    
133      /**
134       * Parse the specified input source and return a DOM Document.
135       * @param source the input source
136       * @exception IllegalArgumentException if the input source is null
137       */
138      public abstract Document parse(InputSource source) 
139        throws SAXException, IOException;
140    
141      /**
142       * Indicates whether this document builder is XML Namespace aware.
143       */
144      public abstract boolean isNamespaceAware();
145    
146      /**
147       * Indicates whether this document builder will validate its input.
148       */
149      public abstract boolean isValidating();
150    
151      /**
152       * Sets the SAX entity resolver callback used to resolve external entities
153       * in the XML document(s) to parse.
154       * @param er an entity resolver
155       */
156      public abstract void setEntityResolver(EntityResolver er);
157    
158      /**
159       * Sets the SAX error handler callback used to report parsing errors.
160       * @param eh the error handler
161       */
162      public abstract void setErrorHandler(ErrorHandler eh);
163    
164      /**
165       * Creates a new, empty DOM Document.
166       * To create a document with a root element and optional doctype, use the
167       * <code>DOMImplementation</code> instead.
168       * @see org.w3c.dom.DOMImplementation#createDocument
169       */
170      public abstract Document newDocument();
171    
172      /**
173       * Returns the DOM implementation.
174       */
175      public abstract DOMImplementation getDOMImplementation();
176    
177      // -- JAXP 1.3 methods --
178      
179      /**
180       * Reset this document builder to its original configuration.
181       * @since 1.3
182       */
183      public void reset()
184      {
185      }
186    
187      /**
188       * Returns the schema in use by the XML processor.
189       */
190      public Schema getSchema()
191      {
192        return null;
193      }
194    
195      /**
196       * Returns the XInclude processing mode in use by the parser.
197       */
198      public boolean isXIncludeAware()
199      {
200        return false;
201      }
202      
203    }