content: /*
   * Copyright (c) 2000, 2005, 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.
   */
  
  // XMLReader.java - read an XML document.
  // http://www.saxproject.org
  // Written by David Megginson
  // NO WARRANTY!  This class is in the Public Domain.
  // $Id: XMLReader.java,v 1.3 2004/11/03 22:55:32 jsuttor Exp $
  
  package org.xml.sax;
  
  import org.xml.sax.ContentHandler;
  import org.xml.sax.DTDHandler;
  import org.xml.sax.EntityResolver;
  import org.xml.sax.ErrorHandler;
  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 java.io.IOException;
  
  
  /**
   * Interface for reading an XML document using callbacks.
   *
   * <blockquote>
   * <em>This module, both source code and documentation, is in the
   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
   * for further information.
   * </blockquote>
   *
   * <p><strong>Note:</strong> 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.</p>
   *
   * <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>
   *
   * @since 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).
       * @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.
       * @see #setFeature
       */
      public boolean getFeature (String name)
          throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.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).
       * @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.
       * @see #getFeature
       */
      public void setFeature (String name, boolean value)
          throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.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.
       * @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 org.xml.sax.SAXNotRecognizedException, org.xml.sax.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.
       * @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.
       *
       * <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 (org.xml.sax.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 (org.xml.sax.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 (org.xml.sax.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 (org.xml.sax.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.
       * @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, org.xml.sax.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).
       * @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;
  
  }
  