org.xml.sax.XMLReader Maven / Gradle / Ivy
/*
* Portions Copyright 2000-2008 Sun Microsystems, Inc. All Rights
* Reserved. Use is subject to license terms.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
// XMLReader.java - read an XML document.
// http://www.saxproject.org
// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
package org.xml.sax;
import java.io.IOException;
/**
* Interface for reading an XML document using callbacks.
*
* Note: despite its name, this interface does
* not extend the standard Java {@link java.io.Reader Reader}
* interface, because reading XML is a fundamentally different activity
* than reading character data.
*
* XMLReader is the interface that an XML parser's SAX2 driver must
* implement. This interface allows an application to set and
* query features and properties in the parser, to register
* event handlers for document processing, and to initiate
* a document parse.
*
* All SAX interfaces are assumed to be synchronous: the
* {@link #parse parse} methods must not return until parsing
* is complete, and readers must wait for an event-handler callback
* to return before reporting the next event.
*
* This interface replaces the (now deprecated) SAX 1.0
* interface. The XMLReader interface
* contains two important enhancements over the old Parser
* interface (as well as some minor ones):
*
*
* - it adds a standard way to query and set features and
* properties; and
* - it adds Namespace support, which is required for many
* higher-level XML standards.
*
*
* @since SAX 2.0
* @author David Megginson
* @see org.xml.sax.XMLFilter
*/
public interface XMLReader
{
////////////////////////////////////////////////////////////////////
// Configuration.
////////////////////////////////////////////////////////////////////
/**
* Look up the value of a feature flag.
*
* The feature name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a feature name but
* temporarily be unable to return its value.
* Some feature values may be available only in specific
* contexts, such as before, during, or after a parse.
* Also, some feature values may not be programmatically accessible.
*
* All XMLReaders are required to recognize the
* http://xml.org/sax/features/namespaces and the
* http://xml.org/sax/features/namespace-prefixes feature names.
*
* Typical usage is something like this:
*
*
* XMLReader r = new MySAXDriver();
*
* // try to activate validation
* try {
* r.setFeature("http://xml.org/sax/features/validation", true);
* } catch (SAXException e) {
* System.err.println("Cannot activate validation.");
* }
*
* // register event handlers
* r.setContentHandler(new MyContentHandler());
* r.setErrorHandler(new MyErrorHandler());
*
* // parse the first document
* try {
* r.parse("http://www.foo.com/mydoc.xml");
* } catch (IOException e) {
* System.err.println("I/O exception reading XML document");
* } catch (SAXException e) {
* System.err.println("XML exception reading document.");
* }
*
*
* Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.
*
* @param name The feature name, which is a fully-qualified URI and
* which may not be null.
* @return The current value of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot determine its value at this time.
* @throws java.lang.NullPointerException
* @see #setFeature
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Set the value of a feature flag.
*
* The feature name is any fully-qualified URI. It is
* possible for an XMLReader to expose a feature value but
* to be unable to change the current value.
* Some feature values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a parse.
*
* All XMLReaders are required to support setting
* http://xml.org/sax/features/namespaces to true and
* http://xml.org/sax/features/namespace-prefixes to false.
*
* @param name The feature name, which is a fully-qualified URI and
* which may not be null.
* @param value The requested value of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot set the requested value.
* @throws java.lang.NullPointerException
* @see #getFeature
*/
public void setFeature (String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Look up the value of a property.
*
* The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
* temporarily be unable to return its value.
* Some property values may be available only in specific
* contexts, such as before, during, or after a parse.
*
* XMLReaders are not required to recognize any specific
* property names, though an initial core set is documented for
* SAX2.
*
* Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.
*
* @param name The property name, which is a fully-qualified URI.
* @return The current value of the property.
* @exception org.xml.sax.SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @see #setProperty
*/
public Object getProperty (String name)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Set the value of a property.
*
* The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
* to be unable to change the current value.
* Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a parse.
*
* XMLReaders are not required to recognize setting
* any specific property names, though a core set is defined by
* SAX2.
*
* This method is also the standard mechanism for setting
* extended handlers.
*
* @param name The property name, which is a fully-qualified URI.
* @param value The requested value for the property.
* @exception org.xml.sax.SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot set the requested value.
*/
public void setProperty (String name, Object value)
throws SAXNotRecognizedException, SAXNotSupportedException;
////////////////////////////////////////////////////////////////////
// Event handlers.
////////////////////////////////////////////////////////////////////
/**
* Allow an application to register an entity resolver.
*
* If the application does not register an entity resolver,
* the XMLReader will perform its own default resolution.
*
* Applications may register a new or different resolver in the
* middle of a parse, and the SAX parser must begin using the new
* resolver immediately.
*
* @param resolver The entity resolver.
* @see #getEntityResolver
*/
public void setEntityResolver (EntityResolver resolver);
/**
* Return the current entity resolver.
*
* @return The current entity resolver, or null if none
* has been registered.
* @see #setEntityResolver
*/
public EntityResolver getEntityResolver ();
/**
* Allow an application to register a DTD event handler.
*
* If the application does not register a DTD handler, all DTD
* events reported by the SAX parser will be silently ignored.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*
* @param handler The DTD handler.
* @see #getDTDHandler
*/
public void setDTDHandler (DTDHandler handler);
/**
* Return the current DTD handler.
*
* @return The current DTD handler, or null if none
* has been registered.
* @see #setDTDHandler
*/
public DTDHandler getDTDHandler ();
/**
* Allow an application to register a content event handler.
*
* If the application does not register a content handler, all
* content events reported by the SAX parser will be silently
* ignored.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*
* @param handler The content handler.
* @see #getContentHandler
*/
public void setContentHandler (ContentHandler handler);
/**
* Return the current content handler.
*
* @return The current content handler, or null if none
* has been registered.
* @see #setContentHandler
*/
public ContentHandler getContentHandler ();
/**
* Allow an application to register an error event handler.
*
* If the application does not register an error handler, all
* error events reported by the SAX parser will be silently
* ignored; however, normal processing may not continue. It is
* highly recommended that all SAX applications implement an
* error handler to avoid unexpected bugs.
*
* Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.
*
* @param handler The error handler.
* @see #getErrorHandler
*/
public void setErrorHandler (ErrorHandler handler);
/**
* Return the current error handler.
*
* @return The current error handler, or null if none
* has been registered.
* @see #setErrorHandler
*/
public ErrorHandler getErrorHandler ();
////////////////////////////////////////////////////////////////////
// Parsing.
////////////////////////////////////////////////////////////////////
/**
* Parse an XML document.
*
* The application can use this method to instruct the XML
* reader to begin parsing an XML document from any valid input
* source (a character stream, a byte stream, or a URI).
*
*
* Applications may not invoke this method while a parse is in
* progress (they should create a new XMLReader instead for each
* nested XML document). Once a parse is complete, an
* application may reuse the same XMLReader object, possibly with a
* different input source.
* Configuration of the XMLReader object (such as handler bindings and
* values established for feature flags and properties) is unchanged
* by completion of a parse, unless the definition of that aspect of
* the configuration explicitly specifies other behavior.
* (For example, feature flags or properties exposing
* characteristics of the document being parsed.)
*
*
* During the parse, the XMLReader will provide information
* about the XML document through the registered event
* handlers.
*
* This method is synchronous: it will not return until parsing
* has ended. If a client application wants to terminate
* parsing early, it should throw an exception.
*
* @param input The input source for the top-level of the
* XML document, may not be null.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
* @see org.xml.sax.InputSource
* @see #parse(java.lang.String)
* @see #setEntityResolver
* @see #setDTDHandler
* @see #setContentHandler
* @see #setErrorHandler
*/
public void parse (InputSource input)
throws IOException, SAXException;
/**
* Parse an XML document from a system identifier (URI).
*
* This method is a shortcut for the common case of reading a
* document from a system identifier. It is the exact
* equivalent of the following:
*
*
* parse(new InputSource(systemId));
*
*
* If the system identifier is a URL, it must be fully resolved
* by the application before it is passed to the parser.
*
* @param systemId The system identifier (URI); may not be null.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
* @see #parse(org.xml.sax.InputSource)
*/
public void parse (String systemId)
throws IOException, SAXException;
}
// end of XMLReader.java