317 lines
11 KiB
Java
317 lines
11 KiB
Java
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership.
|
|
* The ASF licenses this file to You 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.
|
|
*/
|
|
|
|
// $Id: DocumentBuilder.java 584483 2007-10-14 02:54:48Z mrglavas $
|
|
|
|
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.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;
|
|
|
|
/**
|
|
* 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>
|
|
* @version $Revision: 584483 $, $Date: 2007-10-13 19:54:48 -0700 (Sat, 13 Oct 2007) $
|
|
*/
|
|
|
|
public abstract class DocumentBuilder {
|
|
|
|
private static final boolean DEBUG = false;
|
|
|
|
/** Protected constructor */
|
|
protected DocumentBuilder () {
|
|
}
|
|
|
|
/**
|
|
* <p>Reset this <code>DocumentBuilder</code>.</p>
|
|
*
|
|
* This method removes both the <code>EntityResolver</code> and <code>ErrorHandler</code>
|
|
* instances associated with this <code>DocumentBuilder</code> and sets all internal
|
|
* properties to false including those set by the <code>DocumentBuilderFactory</code> when
|
|
* this <code>DocumentBuilder</code> was created.
|
|
*
|
|
* @see #setEntityResolver(EntityResolver)
|
|
* @see #setErrorHandler(ErrorHandler)
|
|
* @see DocumentBuilderFactory
|
|
*
|
|
* @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>
|
|
* @exception IOException If any IO errors occur.
|
|
* @exception SAXException If any parse errors occur.
|
|
* @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.
|
|
* @exception IOException If any IO errors occur.
|
|
* @exception SAXException If any parse errors occur.
|
|
* @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.
|
|
* @exception IOException If any IO errors occur.
|
|
* @exception SAXException If any parse errors occur.
|
|
* @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.
|
|
* @exception IOException If any IO errors occur.
|
|
* @exception SAXException If any parse errors occur.
|
|
* @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");
|
|
}
|
|
|
|
String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
|
|
|
|
if (DEBUG) {
|
|
System.out.println("Escaped URI = " + escapedURI);
|
|
}
|
|
|
|
InputSource in = new InputSource(escapedURI);
|
|
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.
|
|
* @exception IOException If any IO errors occur.
|
|
* @exception SAXException If any parse errors occur.
|
|
* @see org.xml.sax.DocumentHandler
|
|
* @return A new DOM Document object.
|
|
*/
|
|
|
|
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 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
|
|
* For backward compatibility, when implementations for
|
|
* earlier versions of JAXP is used, this exception will be
|
|
* thrown.
|
|
*
|
|
* @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
|
|
* For backward compatibility, when implementations for
|
|
* earlier versions of JAXP is used, this exception will be
|
|
* thrown.
|
|
*
|
|
* @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()
|
|
+ "\""
|
|
);
|
|
}
|
|
}
|