/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javax.xml.parsers;

import org.w3c.dom.DOMImplementation;
import org.w3c.dom.Document;
import org.xml.sax.EntityResolver;
import org.xml.sax.ErrorHandler;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;

import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;

/**
 * Defines a bridge from XML sources (files, stream etc.) to DOM trees. Can be
 * used for easily obtaining a {@link org.w3c.dom.Document} for the input. The
 * class itself is abstract. The class {@link DocumentBuilderFactory} is able to
 * provide instances (of concrete subclasses known to the system).
 * 
 * @since Android 1.0
 */
public abstract class DocumentBuilder {

    /**
     * Do-nothing constructor. Prevents instantiation. To be overridden by
     * concrete subclasses.
     * 
     * @since Android 1.0
     */
    protected DocumentBuilder() {
        // Does nothing.
    }

    /**
     * Queries the DOM implementation this {@code DocumentBuilder} is working
     * on.
     * 
     * @return the DOM implementation
     * 
     * @since Android 1.0
     */
    public abstract DOMImplementation getDOMImplementation();

// TODO No XSchema support in Android 1.0. Maybe later.
//    /**
//     * Queries the XML schema used by the DocumentBuilder.
//     * 
//     * @return The XML schema
//     * 
//     * @throws UnsupportedOperationException when the underlying implementation
//     *         doesn't support XML schemas.
//     */
//    public javax.xml.validation.Schema getSchema() throws
//            UnsupportedOperationException {
//        throw new UnsupportedOperationException();
//    }
     
    /**
     * Queries whether the {@code DocumentBuilder} has namespace support
     * enabled.
     * 
     * @return {@code true} if namespaces are turned on, {@code false}
     *         otherwise.
     * 
     * @since Android 1.0
     */
    public abstract boolean isNamespaceAware();

    /**
     * Queries whether the {@code DocumentBuilder} has validation support
     * enabled.
     * 
     * @return {@code true} if validation is turned on, {@code false} otherwise.
     * 
     * @since Android 1.0
     */
    public abstract boolean isValidating();

    /**
     * Queries whether the {@code DocumentBuilder} has XInclude support enabled.
     * 
     * @return {@code true} if XInclude support is turned on, {@code false}
     *         otherwise.
     * 
     * @throws UnsupportedOperationException if the underlying implementation
     *         doesn't support XInclude.
     * 
     * @since Android 1.0
     */
    public boolean isXIncludeAware() throws UnsupportedOperationException {
        throw new UnsupportedOperationException();
    }

    /**
     * Creates a new, empty document, serving as the starting point for a DOM
     * tree.
     * 
     * @return the document.
     * 
     * @since Android 1.0
     */
    public abstract Document newDocument();

    /**
     * Parses a given XML file and builds a DOM tree from it.
     * 
     * @param file the file to be parsed.
     * @return the document element that represents the root of the DOM tree.
     * 
     * @throws SAXException if the XML parsing fails.
     * @throws IOException if an input/output error occurs.
     * 
     * @since Android 1.0
     */
    public Document parse(File file) throws SAXException, IOException {
        if (file == null) {
            throw new IllegalArgumentException();
        }
        
        return parse(new BufferedInputStream(new FileInputStream(file), 8192));
    }

    /**
     * Parses a given XML input stream and builds a DOM tree from it.
     * 
     * @param stream the stream to be parsed.
     * @return the document element that represents the root of the DOM tree.
     * 
     * @throws SAXException if the XML parsing fails.
     * @throws IOException if an input/output error occurs.
     * 
     * @since Android 1.0
     */
    public Document parse(InputStream stream) throws SAXException, IOException {
        if (stream == null) {
            throw new IllegalArgumentException();
        }
        
        return parse(new InputSource(stream));
    }

    /**
     * Parses a given XML input stream and builds a DOM tree from it.
     * 
     * @param stream the stream to be parsed.
     * @param systemId the base for resolving relative URIs.
     * @return the document element that represents the root of the DOM tree.
     * 
     * @throws SAXException if the XML parsing fails.
     * @throws IOException if an input/output error occurs.
     * 
     * @since Android 1.0
     */
    public org.w3c.dom.Document parse(InputStream stream, String systemId)
            throws SAXException, IOException {
        if (stream == null) {
            throw new IllegalArgumentException();
        }
        
        InputSource source = new InputSource(stream);
        source.setSystemId(systemId);
        return parse(source);
    }

    /**
     * Parses an XML input stream from a given URI and builds a DOM tree from
     * it.
     * 
     * @param uri the URI to fetch the XML stream from.
     * @return the document element that represents the root of the DOM tree.
     * 
     * @throws SAXException if the XML parsing fails.
     * @throws IOException if an input/output error occurs.
     * 
     * @since Android 1.0
     */
    public org.w3c.dom.Document parse(String uri) throws SAXException,
            IOException {
        if (uri == null) {
            throw new IllegalArgumentException();
        }
        
        return parse(new InputSource(uri));
    }

    /**
     * Parses an XML input source and builds a DOM tree from it.
     * 
     * @param source the input source to parse.
     * @return the document element that represents the root of the DOM tree.
     * 
     * @throws SAXException if the XML parsing fails.
     * @throws IOException if an input/output error occurs.
     * 
     * @since Android 1.0
     */
    public abstract org.w3c.dom.Document parse(InputSource source)
            throws SAXException, IOException;

    /**
     * Resets the DocumentBuilder to the same state is was in after its
     * creation.
     * 
     * @since Android 1.0
     */
    public void reset() {
        // Do nothing.
    }

    /**
     * Sets the {@link EntityResolver} used for resolving entities encountered
     * during the parse process. Passing {@code null} results in the
     * {@code DocumentBuilder}'s own {@code EntityResolver} being used.
     * 
     * @param resolver the {@code EntityResolver} to use, or null for the
     *        built-in one.
     * 
     * @since Android 1.0
     */
    public abstract void setEntityResolver(EntityResolver resolver);

    /**
     * Sets the {@link ErrorHandler} used for dealing with errors encountered
     * during the parse process. Passing {@code null} results in the
     * {@code DocumentBuilder}'s own {@code ErrorHandler} being used.
     * 
     * @param handler the {@code ErrorHandler} to use, or {@code null} for the
     *        built-in one.
     * 
     * @since Android 1.0
     */
    public abstract void setErrorHandler(ErrorHandler handler);

}