/*

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

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

 *

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

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

 * published by the Free Software Foundation.  Oracle designates this

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

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

 *

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

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

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

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

 * accompanied this code).

 *

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

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

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

 *

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

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

 * questions.

 */

package javax.xml.parsers;

import java.io.File;

import java.io.IOException;

import java.io.InputStream;

import javax.xml.validation.Schema;

import org.w3c.dom.Document;

import org.w3c.dom.DOMImplementation;

import org.xml.sax.EntityResolver;

import org.xml.sax.ErrorHandler;

import org.xml.sax.InputSource;

import org.xml.sax.SAXException;

/**

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

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

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

 *

 * An instance of this class can be obtained from the

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

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

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

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

 *

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

 * does not require that the implementor of the underlying DOM

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

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

 * communicate with the application using these existing APIs.

 *

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

 */

public abstract class DocumentBuilder {

    /** Protected constructor */

    protected DocumentBuilder () {

    }

    /**

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

     *

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

     * {@link DocumentBuilderFactory#newDocumentBuilder()}.

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

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

     *

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

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

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

     *

     * @throws UnsupportedOperationException When implementation does not

     *   override this method.

     *

     * @since 1.5

     */

    public void reset() {

        // implementors should override this method

        throw new UnsupportedOperationException(

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

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

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

                );

    }

    /**

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

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

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

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

     *

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

     *

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

     *  <code>InputStream</code>

     *

     * @throws IOException If any IO errors occur.

     * @throws SAXException If any parse errors occur.

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

     *

     * @see org.xml.sax.DocumentHandler

     */

    public Document parse(InputStream is)

        throws SAXException, IOException {

        if (is == null) {

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

        }

        InputSource in = new InputSource(is);

        return parse(in);

    }

    /**

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

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

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

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

     *

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

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

     *

     * @return A new DOM Document object.

     *

     * @throws IOException If any IO errors occur.

     * @throws SAXException If any parse errors occur.

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

     *

     * @see org.xml.sax.DocumentHandler

     */

    public Document parse(InputStream is, String systemId)

        throws SAXException, IOException {

        if (is == null) {

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

        }

        InputSource in = new InputSource(is);

        in.setSystemId(systemId);

        return parse(in);

    }

    /**

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

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

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

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

     *

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

     *

     * @return A new DOM Document object.

     *

     * @throws IOException If any IO errors occur.

     * @throws SAXException If any parse errors occur.

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

     *

     * @see org.xml.sax.DocumentHandler

     */

    public Document parse(String uri)

        throws SAXException, IOException {

        if (uri == null) {

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

        }

        InputSource in = new InputSource(uri);

        return parse(in);

    }

    /**

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

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

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

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

     *

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

     *

     * @throws IOException If any IO errors occur.

     * @throws SAXException If any parse errors occur.

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

     *

     * @see org.xml.sax.DocumentHandler

     * @return A new DOM Document object.

     */

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

        if (f == null) {

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

        }

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

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

        //RFC 2396,

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

        return parse(in);

    }

    /**

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

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

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

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

     *

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

     *

     * @return A new DOM Document object.

     *

     * @throws IOException If any IO errors occur.

     * @throws SAXException If any parse errors occur.

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

     *

     * @see org.xml.sax.DocumentHandler

     */

    public abstract Document parse(InputSource is)

        throws SAXException, IOException;

    /**

     * Indicates whether or not this parser is configured to

     * understand namespaces.

     *

     * @return true if this parser is configured to understand

     *         namespaces; false otherwise.

     */

    public abstract boolean isNamespaceAware();

    /**

     * Indicates whether or not this parser is configured to

     * validate XML documents.

     *

     * @return true if this parser is configured to validate

     *         XML documents; false otherwise.

     */

    public abstract boolean isValidating();

    /**

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

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

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

     * implementation using it's own default implementation and

     * behavior.

     *

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

     *           present in the XML document to be parsed.

     */

    public abstract void setEntityResolver(EntityResolver er);

    /**

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

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

     * implementation using it's own default implementation and

     * behavior.

     *

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

     */

    public abstract void setErrorHandler(ErrorHandler eh);

    /**

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

     * to build a DOM tree with.

     *

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

     */

    public abstract Document newDocument();

    /**

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

     *

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

     */

    public abstract DOMImplementation getDOMImplementation();

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

     *

     * @return current state canonicalization control

     */

    /*

    public boolean getCanonicalization() {

        return canonicalState;

    }

    */

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

     * the XML processor.</p>

     *

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

     *

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

     *  if none in use

     *

     * @throws UnsupportedOperationException When implementation does not

     *   override this method

     *

     * @since 1.5

     */

    public Schema getSchema() {

        throw new UnsupportedOperationException(

            "This parser does not support specification \""

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

            + "\" version \""

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

            + "\""

            );

    }

    /**

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

     *

     * @return

     *      the return value of

     *      the {@link DocumentBuilderFactory#isXIncludeAware()}

     *      when this parser was created from factory.

     *

     * @throws UnsupportedOperationException When implementation does not

     *   override this method

     *

     * @since 1.5

     *

     * @see DocumentBuilderFactory#setXIncludeAware(boolean)

     */

    public boolean isXIncludeAware() {

        throw new UnsupportedOperationException(

            "This parser does not support specification \""

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

            + "\" version \""

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

            + "\""

            );

    }

}