Back to index...

	/*
	* Copyright (c) 2000, 2020, 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 org.xml.sax;

	import java.io.IOException;


	/**
	* Interface for reading an XML document using callbacks.
	*
	*
	* <p>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.</p>
	*
	* <p>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.</p>
	*
	* <p>This interface replaces the (now deprecated) SAX 1.0 {@link
	* org.xml.sax.Parser Parser} interface. The XMLReader interface
	* contains two important enhancements over the old Parser
	* interface (as well as some minor ones):</p>
	*
	* <ol>
	* <li>it adds a standard way to query and set features and
	* properties; and</li>
	* <li>it adds Namespace support, which is required for many
	* higher-level XML standards.</li>
	* </ol>
	*
	* <p>There are adapters available to convert a SAX1 Parser to
	* a SAX2 XMLReader and vice-versa.</p>
	*
	* @apiNote Despite its name, this interface does
	* <em>not</em> extend the standard Java {@link java.io.Reader Reader}
	* interface, because reading XML is a fundamentally different activity
	* than reading character data.
	*
	* @since 1.4, SAX 2.0
	* @author David Megginson
	* @see org.xml.sax.XMLFilter
	* @see org.xml.sax.helpers.ParserAdapter
	* @see org.xml.sax.helpers.XMLReaderAdapter
	*/
	public interface XMLReader
	{


	////////////////////////////////////////////////////////////////////
	// Configuration.
	////////////////////////////////////////////////////////////////////


	/**
	* Look up the value of a feature flag.
	*
	* <p>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.
	* (In the case of an adapter for SAX1 {@link Parser}, there is no
	* implementation-independent way to expose whether the underlying
	* parser is performing validation, expanding external entities,
	* and so forth.) </p>
	*
	* <p>All XMLReaders are required to recognize the
	* http://xml.org/sax/features/namespaces and the
	* http://xml.org/sax/features/namespace-prefixes feature names.</p>
	*
	* <p>Typical usage is something like this:</p>
	*
	* <pre>
	* 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.");
	* }
	* </pre>
	*
	* <p>Implementors are free (and encouraged) to invent their own features,
	* using names built on their own URIs.</p>
	*
	* @param name The feature name, which is a fully-qualified URI.
	* @return The current value of the feature (true or false).
	* @throws org.xml.sax.SAXNotRecognizedException If the feature
	* value can't be assigned or retrieved.
	* @throws org.xml.sax.SAXNotSupportedException When the
	* XMLReader recognizes the feature name but
	* cannot determine its value at this time.
	* @see #setFeature
	*/
	public boolean getFeature (String name)
	throws SAXNotRecognizedException, SAXNotSupportedException;


	/**
	* Set the value of a feature flag.
	*
	* <p>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.</p>
	*
	* <p>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.</p>
	*
	* @param name The feature name, which is a fully-qualified URI.
	* @param value The requested value of the feature (true or false).
	* @throws org.xml.sax.SAXNotRecognizedException If the feature
	* value can't be assigned or retrieved.
	* @throws org.xml.sax.SAXNotSupportedException When the
	* XMLReader recognizes the feature name but
	* cannot set the requested value.
	* @see #getFeature
	*/
	public void setFeature (String name, boolean value)
	throws SAXNotRecognizedException, SAXNotSupportedException;


	/**
	* Look up the value of a property.
	*
	* <p>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.</p>
	*
	* <p>XMLReaders are not required to recognize any specific
	* property names, though an initial core set is documented for
	* SAX2.</p>
	*
	* <p>Implementors are free (and encouraged) to invent their own properties,
	* using names built on their own URIs.</p>
	*
	* @param name The property name, which is a fully-qualified URI.
	* @return The current value of the property.
	* @throws org.xml.sax.SAXNotRecognizedException If the property
	* value can't be assigned or retrieved.
	* @throws 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.
	*
	* <p>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.</p>
	*
	* <p>XMLReaders are not required to recognize setting
	* any specific property names, though a core set is defined by
	* SAX2.</p>
	*
	* <p>This method is also the standard mechanism for setting
	* extended handlers.</p>
	*
	* @param name The property name, which is a fully-qualified URI.
	* @param value The requested value for the property.
	* @throws org.xml.sax.SAXNotRecognizedException If the property
	* value can't be assigned or retrieved.
	* @throws 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.
	*
	* <p>If the application does not register an entity resolver,
	* the XMLReader will perform its own default resolution.</p>
	*
	* <p>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.</p>
	*
	* @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.
	*
	* <p>If the application does not register a DTD handler, all DTD
	* events reported by the SAX parser will be silently ignored.</p>
	*
	* <p>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.</p>
	*
	* @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.
	*
	* <p>If the application does not register a content handler, all
	* content events reported by the SAX parser will be silently
	* ignored.</p>
	*
	* <p>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.</p>
	*
	* @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.
	*
	* <p>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.</p>
	*
	* <p>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.</p>
	*
	* @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.
	*
	* <p>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).</p>
	*
	* <p>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.)
	* </p>
	*
	* <p>During the parse, the XMLReader will provide information
	* about the XML document through the registered event
	* handlers.</p>
	*
	* <p>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.</p>
	*
	* @param input The input source for the top-level of the
	* XML document.
	* @throws org.xml.sax.SAXException Any SAX exception, possibly
	* wrapping another exception.
	* @throws 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).
	*
	* <p>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:</p>
	*
	* <pre>
	* parse(new InputSource(systemId));
	* </pre>
	*
	* <p>If the system identifier is a URL, it must be fully resolved
	* by the application before it is passed to the parser.</p>
	*
	* @param systemId The system identifier (URI).
	* @throws org.xml.sax.SAXException Any SAX exception, possibly
	* wrapping another exception.
	* @throws 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;

	}

Back to index...