/*
* 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.xml.sax.HandlerBase;
import org.xml.sax.InputSource;
import org.xml.sax.Parser;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.XMLReader;
import org.xml.sax.helpers.DefaultHandler;
import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
/**
* Provides a wrapper around a SAX {@link XMLReader}. This abstract
* class only defines the interface, whereas the {@link SAXParserFactory} class
* is used to obtain instances of concrete subclasses.
*
* @since Android 1.0
*/
public abstract class SAXParser extends java.lang.Object {
/**
* Do-nothing constructor. Prevents instantiation. To be overridden by
* concrete subclasses.
*
* @since Android 1.0
*/
protected SAXParser() {
// Does nothing.
}
/**
* Queries the underlying SAX {@link Parser} object.
*
* @return the SAX {@code Parser}.
*
* @throws SAXException if a problem occurs.
*
* @since Android 1.0
*/
public abstract Parser getParser()
throws SAXException;
/**
* Queries a property of the underlying SAX {@link XMLReader}.
*
* @param name the name of the property.
* @return the value of the property.
*
* @throws SAXNotRecognizedException if the property is not known to the
* underlying SAX {@code XMLReader}.
* @throws SAXNotSupportedException if the property is known, but not
* supported by the underlying SAX {@code XMLReader}.
*
* @since Android 1.0
*/
public abstract Object getProperty(String name)
throws SAXNotRecognizedException, SAXNotSupportedException;
// TODO No XSchema support in Android 1.0. Maybe later.
// /**
// * Queries the XML Schema used by the underlying XMLReader.
// *
// * @return The XML Schema.
// */
// public Schema getSchema() {
// return schema;
// }
/**
* Queries the underlying SAX XMLReader object.
*
* @return the SAX XMLREader.
*
* @throws SAXException if a problem occurs.
*
* @since Android 1.0
*/
public abstract XMLReader getXMLReader() throws SAXException;
/**
* Reflects whether this {@code SAXParser} is namespace-aware.
*
* @return {@code true} if the {@code SAXParser} is namespace-aware, or
* {@code false} otherwise.
*
* @since Android 1.0
*/
public abstract boolean isNamespaceAware();
/**
* Reflects whether this {@code SAXParser} is validating.
*
* @return {@code true} if the {@code SAXParser} is validating, or {@code
* false} otherwise.
*
* @since Android 1.0
*/
public abstract boolean isValidating();
/**
* Reflects whether this {@code SAXParser} is XInclude-aware.
*
* @return {@code true} if the {@code SAXParser} is XInclude-aware, or
* {@code false} otherwise.
*
* @throws UnsupportedOperationException if the underlying implementation
* doesn't know about XInclude at all (backwards compatibility).
*
* @since Android 1.0
*/
public boolean isXIncludeAware() throws UnsupportedOperationException {
throw new UnsupportedOperationException();
}
/**
* Parses the given XML file using the given SAX event handler.
*
* @param file the file containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(File file, HandlerBase handler) throws SAXException,
IOException {
if (file == null) {
throw new IllegalArgumentException("file must not be null");
}
if (file.isDirectory()) {
throw new IllegalArgumentException("file must not be a directory");
}
InputSource source = new InputSource("file:" + file.getAbsolutePath());
parse(source, handler);
}
/**
* Parses the given XML file using the given SAX event handler.
*
* @param file the file containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(File file, DefaultHandler handler) throws SAXException,
IOException {
if (file == null) {
throw new IllegalArgumentException("file must not be null");
}
if (file.isDirectory()) {
throw new IllegalArgumentException("file must not be a directory");
}
InputSource source = new InputSource("file:" + file.getAbsolutePath());
parse(source, handler);
}
/**
* Parses the given XML InputStream using the given SAX event handler.
*
* @param stream the InputStream containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputStream stream, HandlerBase handler)
throws SAXException, IOException {
if (stream == null) {
throw new IllegalArgumentException("stream must not be null");
}
parse(new InputSource(stream), handler);
}
/**
* Parses the given XML InputStream using the given SAX event handler and
* system ID.
*
* @param stream the InputStream containing the XML document.
* @param handler the SAX handler.
* @param systemId the system ID.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputStream stream, HandlerBase handler, String systemId)
throws SAXException, IOException {
if (stream == null) {
throw new IllegalArgumentException("stream must not be null");
}
InputSource source = new InputSource(stream);
if (systemId != null) {
source.setSystemId(systemId);
}
parse(source, handler);
}
/**
* Parses the given XML InputStream using the given SAX event handler.
*
* @param stream the InputStream containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputStream stream, DefaultHandler handler)
throws SAXException, IOException {
parse(new InputSource(stream), handler);
}
/**
* Parses the given XML InputStream using the given SAX event handler and
* system ID.
*
* @param stream the InputStream containing the XML document.
* @param handler the SAX handler.
* @param systemId the system ID.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputStream stream, DefaultHandler handler,
String systemId) throws SAXException, IOException {
if (stream == null) {
throw new IllegalArgumentException("stream must not be null");
}
InputSource source = new InputSource(stream);
if (systemId != null) {
source.setSystemId(systemId);
}
parse(source, handler);
}
/**
* Parses the contents of the given URI using the given SAX event handler.
*
* @param uri the URI pointing to the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(String uri, HandlerBase handler) throws SAXException,
IOException {
if (uri == null) {
throw new IllegalArgumentException("uri must not be null");
}
parse(new InputSource(uri), handler);
}
/**
* Parses the contents of the given URI using the given SAX event handler.
*
* @param uri the URI pointing to the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(String uri, DefaultHandler handler) throws SAXException,
IOException {
if (uri == null) {
throw new IllegalArgumentException("uri must not be null");
}
parse(new InputSource(uri), handler);
}
/**
* Parses the given SAX {@link InputSource} using the given SAX event
* handler.
*
* @param source the SAX {@code InputSource} containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputSource source, HandlerBase handler)
throws SAXException, IOException {
Parser parser = getParser();
if (source == null) {
throw new IllegalArgumentException("source must not be null");
}
if (handler != null) {
parser.setDocumentHandler(handler);
parser.setDTDHandler(handler);
parser.setEntityResolver(handler);
parser.setErrorHandler(handler);
}
parser.parse(source);
}
/**
* Parses the given SAX {@link InputSource} using the given SAX event
* handler.
*
* @param source the SAX {@code InputSource} containing the XML document.
* @param handler the SAX handler.
*
* @throws SAXException if a problem occurs during SAX parsing.
* @throws IOException if a general IO problem occurs.
*
* @since Android 1.0
*/
public void parse(InputSource source, DefaultHandler handler)
throws SAXException, IOException {
if (source == null) {
throw new IllegalArgumentException("source must not be null");
}
XMLReader reader = getXMLReader();
if (handler != null) {
reader.setContentHandler(handler);
reader.setDTDHandler(handler);
reader.setEntityResolver(handler);
reader.setErrorHandler(handler);
}
reader.parse(source);
}
/**
* Resets the {@code SAXParser} to the same state is was in after its
* creation.
*
* @since Android 1.0
*/
public void reset() {
// Do nothing.
}
/**
* Sets a property of the underlying SAX {@link XMLReader}.
*
* @param name the name of the property.
* @param value the value of the property.
*
* @throws SAXNotRecognizedException if the property is not known to the
* underlying SAX {@code XMLReader}.
* @throws SAXNotSupportedException if the property is known, but not
* supported by the underlying SAX {@code XMLReader}.
*
* @since Android 1.0
*/
public abstract void setProperty(String name, Object value)
throws SAXNotRecognizedException, SAXNotSupportedException;
}
|
