1 /*

     2  * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.xml.parsers;

    27 

    28 import java.io.File;

    29 import java.io.IOException;

    30 import java.io.InputStream;

    31 

    32 import javax.xml.validation.Schema;

    33 

    34 import org.w3c.dom.Document;

    35 import org.w3c.dom.DOMImplementation;

    36 

    37 import org.xml.sax.EntityResolver;

    38 import org.xml.sax.ErrorHandler;

    39 import org.xml.sax.InputSource;

    40 import org.xml.sax.SAXException;

    41 

    42 /**

    43  * Defines the API to obtain DOM Document instances from an XML

    44  * document. Using this class, an application programmer can obtain a

    45  * {@link Document} from XML.<p>

    46  *

    47  * An instance of this class can be obtained from the

    48  * {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once

    49  * an instance of this class is obtained, XML can be parsed from a

    50  * variety of input sources. These input sources are InputStreams,

    51  * Files, URLs, and SAX InputSources.<p>

    52  *

    53  * Note that this class reuses several classes from the SAX API. This

    54  * does not require that the implementor of the underlying DOM

    55  * implementation use a SAX parser to parse XML document into a

    56  * <code>Document</code>. It merely requires that the implementation

    57  * communicate with the application using these existing APIs.

    58  *

    59  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>

    60  */

    61 

    62 public abstract class DocumentBuilder {

    63 

    64 

    65     /** Protected constructor */

    66     protected DocumentBuilder () {

    67     }

    68 

    69     /**

    70      * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>

    71      *

    72      * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with

    73      * {@link DocumentBuilderFactory#newDocumentBuilder()}.

    74      * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s

    75      * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>

    76      *

    77      * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}

    78      * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.  It is guaranteed to have a functionally equal

    79      * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>

    80      *

    81      * @throws UnsupportedOperationException When implementation does not

    82      *   override this method.

    83      *

    84      * @since 1.5

    85      */

    86     public void reset() {

    87 

    88         // implementors should override this method

    89         throw new UnsupportedOperationException(

    90                 "This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."

    91                 + "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""

    92                 + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""

    93                 );

    94     }

    95 

    96     /**

    97      * Parse the content of the given <code>InputStream</code> as an XML

    98      * document and return a new DOM {@link Document} object.

    99      * An <code>IllegalArgumentException</code> is thrown if the

   100      * <code>InputStream</code> is null.

   101      *

   102      * @param is InputStream containing the content to be parsed.

   103      *

   104      * @return <code>Document</code> result of parsing the

   105      *  <code>InputStream</code>

   106      *

   107      * @throws IOException If any IO errors occur.

   108      * @throws SAXException If any parse errors occur.

   109      * @throws IllegalArgumentException When <code>is</code> is <code>null</code>

   110      *

   111      * @see org.xml.sax.DocumentHandler

   112      */

   113 

   114     public Document parse(InputStream is)

   115         throws SAXException, IOException {

   116         if (is == null) {

   117             throw new IllegalArgumentException("InputStream cannot be null");

   118         }

   119 

   120         InputSource in = new InputSource(is);

   121         return parse(in);

   122     }

   123 

   124     /**

   125      * Parse the content of the given <code>InputStream</code> as an

   126      * XML document and return a new DOM {@link Document} object.

   127      * An <code>IllegalArgumentException</code> is thrown if the

   128      * <code>InputStream</code> is null.

   129      *

   130      * @param is InputStream containing the content to be parsed.

   131      * @param systemId Provide a base for resolving relative URIs.

   132      *

   133      * @return A new DOM Document object.

   134      *

   135      * @throws IOException If any IO errors occur.

   136      * @throws SAXException If any parse errors occur.

   137      * @throws IllegalArgumentException When <code>is</code> is <code>null</code>

   138      *

   139      * @see org.xml.sax.DocumentHandler

   140      */

   141 

   142     public Document parse(InputStream is, String systemId)

   143         throws SAXException, IOException {

   144         if (is == null) {

   145             throw new IllegalArgumentException("InputStream cannot be null");

   146         }

   147 

   148         InputSource in = new InputSource(is);

   149         in.setSystemId(systemId);

   150         return parse(in);

   151     }

   152 

   153     /**

   154      * Parse the content of the given URI as an XML document

   155      * and return a new DOM {@link Document} object.

   156      * An <code>IllegalArgumentException</code> is thrown if the

   157      * URI is <code>null</code> null.

   158      *

   159      * @param uri The location of the content to be parsed.

   160      *

   161      * @return A new DOM Document object.

   162      *

   163      * @throws IOException If any IO errors occur.

   164      * @throws SAXException If any parse errors occur.

   165      * @throws IllegalArgumentException When <code>uri</code> is <code>null</code>

   166      *

   167      * @see org.xml.sax.DocumentHandler

   168      */

   169 

   170     public Document parse(String uri)

   171         throws SAXException, IOException {

   172         if (uri == null) {

   173             throw new IllegalArgumentException("URI cannot be null");

   174         }

   175 

   176         InputSource in = new InputSource(uri);

   177         return parse(in);

   178     }

   179 

   180     /**

   181      * Parse the content of the given file as an XML document

   182      * and return a new DOM {@link Document} object.

   183      * An <code>IllegalArgumentException</code> is thrown if the

   184      * <code>File</code> is <code>null</code> null.

   185      *

   186      * @param f The file containing the XML to parse.

   187      *

   188      * @throws IOException If any IO errors occur.

   189      * @throws SAXException If any parse errors occur.

   190      * @throws IllegalArgumentException When <code>f</code> is <code>null</code>

   191      *

   192      * @see org.xml.sax.DocumentHandler

   193      * @return A new DOM Document object.

   194      */

   195 

   196     public Document parse(File f) throws SAXException, IOException {

   197         if (f == null) {

   198             throw new IllegalArgumentException("File cannot be null");

   199         }

   200 

   201         //convert file to appropriate URI, f.toURI().toASCIIString()

   202         //converts the URI to string as per rule specified in

   203         //RFC 2396,

   204         InputSource in = new InputSource(f.toURI().toASCIIString());

   205         return parse(in);

   206     }

   207 

   208     /**

   209      * Parse the content of the given input source as an XML document

   210      * and return a new DOM {@link Document} object.

   211      * An <code>IllegalArgumentException</code> is thrown if the

   212      * <code>InputSource</code> is <code>null</code> null.

   213      *

   214      * @param is InputSource containing the content to be parsed.

   215      *

   216      * @return A new DOM Document object.

   217      *

   218      * @throws IOException If any IO errors occur.

   219      * @throws SAXException If any parse errors occur.

   220      * @throws IllegalArgumentException When <code>is</code> is <code>null</code>

   221      *

   222      * @see org.xml.sax.DocumentHandler

   223      */

   224 

   225     public abstract Document parse(InputSource is)

   226         throws SAXException, IOException;

   227 

   228 

   229     /**

   230      * Indicates whether or not this parser is configured to

   231      * understand namespaces.

   232      *

   233      * @return true if this parser is configured to understand

   234      *         namespaces; false otherwise.

   235      */

   236 

   237     public abstract boolean isNamespaceAware();

   238 

   239     /**

   240      * Indicates whether or not this parser is configured to

   241      * validate XML documents.

   242      *

   243      * @return true if this parser is configured to validate

   244      *         XML documents; false otherwise.

   245      */

   246 

   247     public abstract boolean isValidating();

   248 

   249     /**

   250      * Specify the {@link EntityResolver} to be used to resolve

   251      * entities present in the XML document to be parsed. Setting

   252      * this to <code>null</code> will result in the underlying

   253      * implementation using it's own default implementation and

   254      * behavior.

   255      *

   256      * @param er The <code>EntityResolver</code> to be used to resolve entities

   257      *           present in the XML document to be parsed.

   258      */

   259 

   260     public abstract void setEntityResolver(EntityResolver er);

   261 

   262     /**

   263      * Specify the {@link ErrorHandler} to be used by the parser.

   264      * Setting this to <code>null</code> will result in the underlying

   265      * implementation using it's own default implementation and

   266      * behavior.

   267      *

   268      * @param eh The <code>ErrorHandler</code> to be used by the parser.

   269      */

   270 

   271     public abstract void setErrorHandler(ErrorHandler eh);

   272 

   273     /**

   274      * Obtain a new instance of a DOM {@link Document} object

   275      * to build a DOM tree with.

   276      *

   277      * @return A new instance of a DOM Document object.

   278      */

   279 

   280     public abstract Document newDocument();

   281 

   282     /**

   283      * Obtain an instance of a {@link DOMImplementation} object.

   284      *

   285      * @return A new instance of a <code>DOMImplementation</code>.

   286      */

   287 

   288     public abstract DOMImplementation getDOMImplementation();

   289 

   290     /** <p>Get current state of canonicalization.</p>

   291      *

   292      * @return current state canonicalization control

   293      */

   294     /*

   295     public boolean getCanonicalization() {

   296         return canonicalState;

   297     }

   298     */

   299 

   300     /** <p>Get a reference to the the {@link Schema} being used by

   301      * the XML processor.</p>

   302      *

   303      * <p>If no schema is being used, <code>null</code> is returned.</p>

   304      *

   305      * @return {@link Schema} being used or <code>null</code>

   306      *  if none in use

   307      *

   308      * @throws UnsupportedOperationException When implementation does not

   309      *   override this method

   310      *

   311      * @since 1.5

   312      */

   313     public Schema getSchema() {

   314         throw new UnsupportedOperationException(

   315             "This parser does not support specification \""

   316             + this.getClass().getPackage().getSpecificationTitle()

   317             + "\" version \""

   318             + this.getClass().getPackage().getSpecificationVersion()

   319             + "\""

   320             );

   321     }

   322 

   323 

   324     /**

   325      * <p>Get the XInclude processing mode for this parser.</p>

   326      *

   327      * @return

   328      *      the return value of

   329      *      the {@link DocumentBuilderFactory#isXIncludeAware()}

   330      *      when this parser was created from factory.

   331      *

   332      * @throws UnsupportedOperationException When implementation does not

   333      *   override this method

   334      *

   335      * @since 1.5

   336      *

   337      * @see DocumentBuilderFactory#setXIncludeAware(boolean)

   338      */

   339     public boolean isXIncludeAware() {

   340         throw new UnsupportedOperationException(

   341             "This parser does not support specification \""

   342             + this.getClass().getPackage().getSpecificationTitle()

   343             + "\" version \""

   344             + this.getClass().getPackage().getSpecificationVersion()

   345             + "\""

   346             );

   347     }

   348 }