Back to index...

	/*
	* 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 Jeff Suttor
	* @since 1.4
	*/

	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()
	+ "\""
	);
	}
	}

Back to index...