Home » xml-commons-external-1.4.01-src » javax » xml » parsers » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   // $Id: DocumentBuilder.java 584483 2007-10-14 02:54:48Z mrglavas $
   19   
   20   package javax.xml.parsers;
   21   
   22   import java.io.File;
   23   import java.io.IOException;
   24   import java.io.InputStream;
   25   
   26   import javax.xml.validation.Schema;
   27   
   28   import org.w3c.dom.Document;
   29   import org.w3c.dom.DOMImplementation;
   30   
   31   import org.xml.sax.EntityResolver;
   32   import org.xml.sax.ErrorHandler;
   33   import org.xml.sax.InputSource;
   34   import org.xml.sax.SAXException;
   35   
   36   /**
   37    * Defines the API to obtain DOM Document instances from an XML
   38    * document. Using this class, an application programmer can obtain a
   39    * {@link Document} from XML.<p>
   40    *
   41    * An instance of this class can be obtained from the
   42    * {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once
   43    * an instance of this class is obtained, XML can be parsed from a
   44    * variety of input sources. These input sources are InputStreams,
   45    * Files, URLs, and SAX InputSources.<p>
   46    *
   47    * Note that this class reuses several classes from the SAX API. This
   48    * does not require that the implementor of the underlying DOM
   49    * implementation use a SAX parser to parse XML document into a
   50    * <code>Document</code>. It merely requires that the implementation
   51    * communicate with the application using these existing APIs.
   52    *
   53    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
   54    * @version $Revision: 584483 $, $Date: 2007-10-13 22:54:48 -0400 (Sat, 13 Oct 2007) $
   55    */
   56   
   57   public abstract class DocumentBuilder {
   58       
   59       private static final boolean DEBUG = false;
   60       
   61       /** Protected constructor */
   62       protected DocumentBuilder () {
   63       }
   64   
   65   	/**
   66   	  * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
   67   	  * 
   68   	  * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
   69   	  * {@link DocumentBuilderFactory#newDocumentBuilder()}.
   70   	  * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
   71   	  * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
   72   	  * 
   73   	  * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
   74   	  * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.  It is guaranteed to have a functionally equal
   75   	  * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
   76   	  * 
   77   	  * @since 1.5
   78   	  */
   79   	public void reset() {
   80   	
   81   		// implementors should override this method
   82   		throw new UnsupportedOperationException(
   83   			"This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."
   84   			+ "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
   85   			+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
   86   			);
   87   	}
   88   
   89       /**
   90        * Parse the content of the given <code>InputStream</code> as an XML
   91        * document and return a new DOM {@link Document} object.
   92        * An <code>IllegalArgumentException</code> is thrown if the
   93        * <code>InputStream</code> is null.
   94        *
   95        * @param is InputStream containing the content to be parsed.
   96        * @return <code>Document</code> result of parsing the
   97        *  <code>InputStream</code>
   98        * @exception IOException If any IO errors occur.
   99        * @exception SAXException If any parse errors occur.
  100        * @see org.xml.sax.DocumentHandler
  101        */
  102       
  103       public Document parse(InputStream is)
  104           throws SAXException, IOException {
  105           if (is == null) {
  106               throw new IllegalArgumentException("InputStream cannot be null");
  107           }
  108           
  109           InputSource in = new InputSource(is);
  110           return parse(in);
  111       }
  112   
  113       /**
  114        * Parse the content of the given <code>InputStream</code> as an
  115        * XML document and return a new DOM {@link Document} object.
  116        * An <code>IllegalArgumentException</code> is thrown if the
  117        * <code>InputStream</code> is null.
  118        *
  119        * @param is InputStream containing the content to be parsed.
  120        * @param systemId Provide a base for resolving relative URIs.
  121        * @return A new DOM Document object.
  122        * @exception IOException If any IO errors occur.
  123        * @exception SAXException If any parse errors occur.
  124        * @see org.xml.sax.DocumentHandler
  125        */
  126       
  127       public Document parse(InputStream is, String systemId)
  128           throws SAXException, IOException {
  129           if (is == null) {
  130               throw new IllegalArgumentException("InputStream cannot be null");
  131           }
  132           
  133           InputSource in = new InputSource(is);
  134           in.setSystemId(systemId);
  135           return parse(in);
  136       }
  137   
  138       /**
  139        * Parse the content of the given URI as an XML document
  140        * and return a new DOM {@link Document} object.
  141        * An <code>IllegalArgumentException</code> is thrown if the
  142        * URI is <code>null</code> null.
  143        *
  144        * @param uri The location of the content to be parsed.
  145        * @return A new DOM Document object.
  146        * @exception IOException If any IO errors occur.
  147        * @exception SAXException If any parse errors occur.
  148        * @see org.xml.sax.DocumentHandler
  149        */
  150       
  151       public Document parse(String uri)
  152           throws SAXException, IOException {
  153           if (uri == null) {
  154               throw new IllegalArgumentException("URI cannot be null");
  155           }
  156           
  157           InputSource in = new InputSource(uri);
  158           return parse(in);
  159       }
  160   
  161       /**
  162        * Parse the content of the given file as an XML document
  163        * and return a new DOM {@link Document} object.
  164        * An <code>IllegalArgumentException</code> is thrown if the
  165        * <code>File</code> is <code>null</code> null.
  166        *
  167        * @param f The file containing the XML to parse.
  168        * @exception IOException If any IO errors occur.
  169        * @exception SAXException If any parse errors occur.
  170        * @see org.xml.sax.DocumentHandler
  171        * @return A new DOM Document object.
  172        */
  173       
  174       public Document parse(File f) throws SAXException, IOException {
  175           if (f == null) {
  176               throw new IllegalArgumentException("File cannot be null");
  177           }
  178           
  179           String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
  180           
  181           if (DEBUG) {
  182               System.out.println("Escaped URI = " + escapedURI);
  183           }
  184   
  185           InputSource in = new InputSource(escapedURI);
  186           return parse(in);
  187       }
  188   
  189       /**
  190        * Parse the content of the given input source as an XML document
  191        * and return a new DOM {@link Document} object.
  192        * An <code>IllegalArgumentException</code> is thrown if the
  193        * <code>InputSource</code> is <code>null</code> null.
  194        *
  195        * @param is InputSource containing the content to be parsed.
  196        * @exception IOException If any IO errors occur.
  197        * @exception SAXException If any parse errors occur.
  198        * @see org.xml.sax.DocumentHandler
  199        * @return A new DOM Document object.
  200        */
  201       
  202       public abstract Document parse(InputSource is)
  203           throws  SAXException, IOException;
  204   
  205       
  206       /**
  207        * Indicates whether or not this parser is configured to
  208        * understand namespaces.
  209        *
  210        * @return true if this parser is configured to understand
  211        *         namespaces; false otherwise.
  212        */
  213   
  214       public abstract boolean isNamespaceAware();
  215   
  216       /**
  217        * Indicates whether or not this parser is configured to
  218        * validate XML documents.
  219        *
  220        * @return true if this parser is configured to validate
  221        *         XML documents; false otherwise.
  222        */
  223       
  224       public abstract boolean isValidating();
  225   
  226       /**
  227        * Specify the {@link EntityResolver} to be used to resolve
  228        * entities present in the XML document to be parsed. Setting
  229        * this to <code>null</code> will result in the underlying
  230        * implementation using it's own default implementation and
  231        * behavior.
  232        *
  233        * @param er The <code>EntityResolver</code> to be used to resolve entities
  234        *           present in the XML document to be parsed.
  235        */
  236   
  237       public abstract void setEntityResolver(EntityResolver er);
  238   
  239       /**
  240        * Specify the {@link ErrorHandler} to be used by the parser.
  241        * Setting this to <code>null</code> will result in the underlying
  242        * implementation using it's own default implementation and
  243        * behavior.
  244        *
  245        * @param eh The <code>ErrorHandler</code> to be used by the parser.
  246        */
  247   
  248       public abstract void setErrorHandler(ErrorHandler eh);
  249   
  250       /**
  251        * Obtain a new instance of a DOM {@link Document} object
  252        * to build a DOM tree with.
  253        *
  254        * @return A new instance of a DOM Document object.
  255        */
  256       
  257       public abstract Document newDocument();
  258   
  259       /**
  260        * Obtain an instance of a {@link DOMImplementation} object.
  261        *
  262        * @return A new instance of a <code>DOMImplementation</code>.
  263        */
  264   
  265       public abstract DOMImplementation getDOMImplementation();
  266       
  267       /** <p>Get a reference to the the {@link Schema} being used by
  268        * the XML processor.</p>
  269        *
  270        * <p>If no schema is being used, <code>null</code> is returned.</p>
  271        *
  272        * @return {@link Schema} being used or <code>null</code>
  273        *  if none in use
  274        * 
  275        * @throws UnsupportedOperationException
  276        *      For backward compatibility, when implementations for
  277        *      earlier versions of JAXP is used, this exception will be
  278        *      thrown.
  279        * 
  280        * @since 1.5
  281        */
  282       public Schema getSchema() {
  283           throw new UnsupportedOperationException(
  284               "This parser does not support specification \""
  285               + this.getClass().getPackage().getSpecificationTitle()
  286               + "\" version \""
  287               + this.getClass().getPackage().getSpecificationVersion()
  288               + "\""
  289               );
  290       }
  291       
  292       
  293       /**
  294        * <p>Get the XInclude processing mode for this parser.</p>
  295        * 
  296        * @return
  297        *      the return value of
  298        *      the {@link DocumentBuilderFactory#isXIncludeAware()}
  299        *      when this parser was created from factory.
  300        * 
  301        * @throws UnsupportedOperationException
  302        *      For backward compatibility, when implementations for
  303        *      earlier versions of JAXP is used, this exception will be
  304        *      thrown.
  305        * 
  306        * @since 1.5
  307        * 
  308        * @see DocumentBuilderFactory#setXIncludeAware(boolean)
  309        */
  310       public boolean isXIncludeAware() {
  311           throw new UnsupportedOperationException(
  312               "This parser does not support specification \""
  313               + this.getClass().getPackage().getSpecificationTitle()
  314               + "\" version \""
  315               + this.getClass().getPackage().getSpecificationVersion()
  316               + "\""
  317               );
  318       }
  319   }

Home » xml-commons-external-1.4.01-src » javax » xml » parsers » [javadoc | source]