001/* DocumentBuilder.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.w3c.dom.Document;
046import org.w3c.dom.DOMImplementation;
047import org.xml.sax.InputSource;
048import org.xml.sax.EntityResolver;
049import org.xml.sax.ErrorHandler;
050import 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 */
059public 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}