Source for javax.xml.parsers.DocumentBuilder

   1: /* DocumentBuilder.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.w3c.dom.Document;
  46: import org.w3c.dom.DOMImplementation;
  47: import org.xml.sax.InputSource;
  48: import org.xml.sax.EntityResolver;
  49: import org.xml.sax.ErrorHandler;
  50: import org.xml.sax.SAXException;
  51: 
  52: /**
  53:  * Convenience class for parsing an XML document into a W3C DOM object
  54:  * graph.
  55:  * Instances of this class are <em>not</em> guaranteed to be thread safe.
  56:  *
  57:  * @author (a href='mailto:dog@gnu.org'>Chris Burdess</a)
  58:  */
  59: public abstract class DocumentBuilder
  60: {
  61: 
  62:   protected DocumentBuilder()
  63:   {
  64:   }
  65: 
  66:   /**
  67:    * Parse the specified input stream and return a DOM Document.
  68:    * Prefer the version of this method that specifies a system ID, in order
  69:    * to resolve external references correctly.
  70:    * @param is an XML input stream
  71:    * @exception IllegalArgumentException if the input stream is null
  72:    */
  73:   public Document parse(InputStream is) 
  74:     throws SAXException, IOException
  75:   {
  76:     if (is == null)
  77:       {
  78:         throw new IllegalArgumentException("input stream is null");
  79:       }
  80:     return parse(new InputSource(is));
  81:   }
  82: 
  83:   /**
  84:    * Parse the specified input stream and return a DOM Document.
  85:    * @param is an XML input stream
  86:    * @param systemId the system ID of the XML document
  87:    * @exception IllegalArgumentException if the input stream is null
  88:    */
  89:   public Document parse(InputStream is, String systemId) 
  90:     throws SAXException, IOException
  91:   {
  92:     if (is == null)
  93:       {
  94:         throw new IllegalArgumentException("input stream is null");
  95:       }
  96:     InputSource  source = new InputSource(is);
  97:     source.setSystemId(systemId);
  98:     return parse(source);
  99:   }
 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: }