1 /*

     2  * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 // XMLReader.java - read an XML document.

    27 // http://www.saxproject.org

    28 // Written by David Megginson

    29 // NO WARRANTY!  This class is in the Public Domain.

    30 // $Id: XMLReader.java,v 1.3 2004/11/03 22:55:32 jsuttor Exp $

    31 

    32 package org.xml.sax;

    33 

    34 import java.io.IOException;

    35 

    36 

    37 /**

    38  * Interface for reading an XML document using callbacks.

    39  *

    40  * <blockquote>

    41  * <em>This module, both source code and documentation, is in the

    42  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

    43  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>

    44  * for further information.

    45  * </blockquote>

    46  *

    47  * <p><strong>Note:</strong> despite its name, this interface does

    48  * <em>not</em> extend the standard Java {@link java.io.Reader Reader}

    49  * interface, because reading XML is a fundamentally different activity

    50  * than reading character data.</p>

    51  *

    52  * <p>XMLReader is the interface that an XML parser's SAX2 driver must

    53  * implement.  This interface allows an application to set and

    54  * query features and properties in the parser, to register

    55  * event handlers for document processing, and to initiate

    56  * a document parse.</p>

    57  *

    58  * <p>All SAX interfaces are assumed to be synchronous: the

    59  * {@link #parse parse} methods must not return until parsing

    60  * is complete, and readers must wait for an event-handler callback

    61  * to return before reporting the next event.</p>

    62  *

    63  * <p>This interface replaces the (now deprecated) SAX 1.0 {@link

    64  * org.xml.sax.Parser Parser} interface.  The XMLReader interface

    65  * contains two important enhancements over the old Parser

    66  * interface (as well as some minor ones):</p>

    67  *

    68  * <ol>

    69  * <li>it adds a standard way to query and set features and

    70  *  properties; and</li>

    71  * <li>it adds Namespace support, which is required for many

    72  *  higher-level XML standards.</li>

    73  * </ol>

    74  *

    75  * <p>There are adapters available to convert a SAX1 Parser to

    76  * a SAX2 XMLReader and vice-versa.</p>

    77  *

    78  * @since SAX 2.0

    79  * @author David Megginson

    80  * @see org.xml.sax.XMLFilter

    81  * @see org.xml.sax.helpers.ParserAdapter

    82  * @see org.xml.sax.helpers.XMLReaderAdapter

    83  */

    84 public interface XMLReader

    85 {

    86 

    87 

    88     ////////////////////////////////////////////////////////////////////

    89     // Configuration.

    90     ////////////////////////////////////////////////////////////////////

    91 

    92 

    93     /**

    94      * Look up the value of a feature flag.

    95      *

    96      * <p>The feature name is any fully-qualified URI.  It is

    97      * possible for an XMLReader to recognize a feature name but

    98      * temporarily be unable to return its value.

    99      * Some feature values may be available only in specific

   100      * contexts, such as before, during, or after a parse.

   101      * Also, some feature values may not be programmatically accessible.

   102      * (In the case of an adapter for SAX1 {@link Parser}, there is no

   103      * implementation-independent way to expose whether the underlying

   104      * parser is performing validation, expanding external entities,

   105      * and so forth.) </p>

   106      *

   107      * <p>All XMLReaders are required to recognize the

   108      * http://xml.org/sax/features/namespaces and the

   109      * http://xml.org/sax/features/namespace-prefixes feature names.</p>

   110      *

   111      * <p>Typical usage is something like this:</p>

   112      *

   113      * <pre>

   114      * XMLReader r = new MySAXDriver();

   115      *

   116      *                         // try to activate validation

   117      * try {

   118      *   r.setFeature("http://xml.org/sax/features/validation", true);

   119      * } catch (SAXException e) {

   120      *   System.err.println("Cannot activate validation.");

   121      * }

   122      *

   123      *                         // register event handlers

   124      * r.setContentHandler(new MyContentHandler());

   125      * r.setErrorHandler(new MyErrorHandler());

   126      *

   127      *                         // parse the first document

   128      * try {

   129      *   r.parse("http://www.foo.com/mydoc.xml");

   130      * } catch (IOException e) {

   131      *   System.err.println("I/O exception reading XML document");

   132      * } catch (SAXException e) {

   133      *   System.err.println("XML exception reading document.");

   134      * }

   135      * </pre>

   136      *

   137      * <p>Implementors are free (and encouraged) to invent their own features,

   138      * using names built on their own URIs.</p>

   139      *

   140      * @param name The feature name, which is a fully-qualified URI.

   141      * @return The current value of the feature (true or false).

   142      * @exception org.xml.sax.SAXNotRecognizedException If the feature

   143      *            value can't be assigned or retrieved.

   144      * @exception org.xml.sax.SAXNotSupportedException When the

   145      *            XMLReader recognizes the feature name but

   146      *            cannot determine its value at this time.

   147      * @see #setFeature

   148      */

   149     public boolean getFeature (String name)

   150         throws SAXNotRecognizedException, SAXNotSupportedException;

   151 

   152 

   153     /**

   154      * Set the value of a feature flag.

   155      *

   156      * <p>The feature name is any fully-qualified URI.  It is

   157      * possible for an XMLReader to expose a feature value but

   158      * to be unable to change the current value.

   159      * Some feature values may be immutable or mutable only

   160      * in specific contexts, such as before, during, or after

   161      * a parse.</p>

   162      *

   163      * <p>All XMLReaders are required to support setting

   164      * http://xml.org/sax/features/namespaces to true and

   165      * http://xml.org/sax/features/namespace-prefixes to false.</p>

   166      *

   167      * @param name The feature name, which is a fully-qualified URI.

   168      * @param value The requested value of the feature (true or false).

   169      * @exception org.xml.sax.SAXNotRecognizedException If the feature

   170      *            value can't be assigned or retrieved.

   171      * @exception org.xml.sax.SAXNotSupportedException When the

   172      *            XMLReader recognizes the feature name but

   173      *            cannot set the requested value.

   174      * @see #getFeature

   175      */

   176     public void setFeature (String name, boolean value)

   177         throws SAXNotRecognizedException, SAXNotSupportedException;

   178 

   179 

   180     /**

   181      * Look up the value of a property.

   182      *

   183      * <p>The property name is any fully-qualified URI.  It is

   184      * possible for an XMLReader to recognize a property name but

   185      * temporarily be unable to return its value.

   186      * Some property values may be available only in specific

   187      * contexts, such as before, during, or after a parse.</p>

   188      *

   189      * <p>XMLReaders are not required to recognize any specific

   190      * property names, though an initial core set is documented for

   191      * SAX2.</p>

   192      *

   193      * <p>Implementors are free (and encouraged) to invent their own properties,

   194      * using names built on their own URIs.</p>

   195      *

   196      * @param name The property name, which is a fully-qualified URI.

   197      * @return The current value of the property.

   198      * @exception org.xml.sax.SAXNotRecognizedException If the property

   199      *            value can't be assigned or retrieved.

   200      * @exception org.xml.sax.SAXNotSupportedException When the

   201      *            XMLReader recognizes the property name but

   202      *            cannot determine its value at this time.

   203      * @see #setProperty

   204      */

   205     public Object getProperty (String name)

   206         throws SAXNotRecognizedException, SAXNotSupportedException;

   207 

   208 

   209     /**

   210      * Set the value of a property.

   211      *

   212      * <p>The property name is any fully-qualified URI.  It is

   213      * possible for an XMLReader to recognize a property name but

   214      * to be unable to change the current value.

   215      * Some property values may be immutable or mutable only

   216      * in specific contexts, such as before, during, or after

   217      * a parse.</p>

   218      *

   219      * <p>XMLReaders are not required to recognize setting

   220      * any specific property names, though a core set is defined by

   221      * SAX2.</p>

   222      *

   223      * <p>This method is also the standard mechanism for setting

   224      * extended handlers.</p>

   225      *

   226      * @param name The property name, which is a fully-qualified URI.

   227      * @param value The requested value for the property.

   228      * @exception org.xml.sax.SAXNotRecognizedException If the property

   229      *            value can't be assigned or retrieved.

   230      * @exception org.xml.sax.SAXNotSupportedException When the

   231      *            XMLReader recognizes the property name but

   232      *            cannot set the requested value.

   233      */

   234     public void setProperty (String name, Object value)

   235         throws SAXNotRecognizedException, SAXNotSupportedException;

   236 

   237 

   238 

   239     ////////////////////////////////////////////////////////////////////

   240     // Event handlers.

   241     ////////////////////////////////////////////////////////////////////

   242 

   243 

   244     /**

   245      * Allow an application to register an entity resolver.

   246      *

   247      * <p>If the application does not register an entity resolver,

   248      * the XMLReader will perform its own default resolution.</p>

   249      *

   250      * <p>Applications may register a new or different resolver in the

   251      * middle of a parse, and the SAX parser must begin using the new

   252      * resolver immediately.</p>

   253      *

   254      * @param resolver The entity resolver.

   255      * @see #getEntityResolver

   256      */

   257     public void setEntityResolver (EntityResolver resolver);

   258 

   259 

   260     /**

   261      * Return the current entity resolver.

   262      *

   263      * @return The current entity resolver, or null if none

   264      *         has been registered.

   265      * @see #setEntityResolver

   266      */

   267     public EntityResolver getEntityResolver ();

   268 

   269 

   270     /**

   271      * Allow an application to register a DTD event handler.

   272      *

   273      * <p>If the application does not register a DTD handler, all DTD

   274      * events reported by the SAX parser will be silently ignored.</p>

   275      *

   276      * <p>Applications may register a new or different handler in the

   277      * middle of a parse, and the SAX parser must begin using the new

   278      * handler immediately.</p>

   279      *

   280      * @param handler The DTD handler.

   281      * @see #getDTDHandler

   282      */

   283     public void setDTDHandler (DTDHandler handler);

   284 

   285 

   286     /**

   287      * Return the current DTD handler.

   288      *

   289      * @return The current DTD handler, or null if none

   290      *         has been registered.

   291      * @see #setDTDHandler

   292      */

   293     public DTDHandler getDTDHandler ();

   294 

   295 

   296     /**

   297      * Allow an application to register a content event handler.

   298      *

   299      * <p>If the application does not register a content handler, all

   300      * content events reported by the SAX parser will be silently

   301      * ignored.</p>

   302      *

   303      * <p>Applications may register a new or different handler in the

   304      * middle of a parse, and the SAX parser must begin using the new

   305      * handler immediately.</p>

   306      *

   307      * @param handler The content handler.

   308      * @see #getContentHandler

   309      */

   310     public void setContentHandler (ContentHandler handler);

   311 

   312 

   313     /**

   314      * Return the current content handler.

   315      *

   316      * @return The current content handler, or null if none

   317      *         has been registered.

   318      * @see #setContentHandler

   319      */

   320     public ContentHandler getContentHandler ();

   321 

   322 

   323     /**

   324      * Allow an application to register an error event handler.

   325      *

   326      * <p>If the application does not register an error handler, all

   327      * error events reported by the SAX parser will be silently

   328      * ignored; however, normal processing may not continue.  It is

   329      * highly recommended that all SAX applications implement an

   330      * error handler to avoid unexpected bugs.</p>

   331      *

   332      * <p>Applications may register a new or different handler in the

   333      * middle of a parse, and the SAX parser must begin using the new

   334      * handler immediately.</p>

   335      *

   336      * @param handler The error handler.

   337      * @see #getErrorHandler

   338      */

   339     public void setErrorHandler (ErrorHandler handler);

   340 

   341 

   342     /**

   343      * Return the current error handler.

   344      *

   345      * @return The current error handler, or null if none

   346      *         has been registered.

   347      * @see #setErrorHandler

   348      */

   349     public ErrorHandler getErrorHandler ();

   350 

   351 

   352 

   353     ////////////////////////////////////////////////////////////////////

   354     // Parsing.

   355     ////////////////////////////////////////////////////////////////////

   356 

   357     /**

   358      * Parse an XML document.

   359      *

   360      * <p>The application can use this method to instruct the XML

   361      * reader to begin parsing an XML document from any valid input

   362      * source (a character stream, a byte stream, or a URI).</p>

   363      *

   364      * <p>Applications may not invoke this method while a parse is in

   365      * progress (they should create a new XMLReader instead for each

   366      * nested XML document).  Once a parse is complete, an

   367      * application may reuse the same XMLReader object, possibly with a

   368      * different input source.

   369      * Configuration of the XMLReader object (such as handler bindings and

   370      * values established for feature flags and properties) is unchanged

   371      * by completion of a parse, unless the definition of that aspect of

   372      * the configuration explicitly specifies other behavior.

   373      * (For example, feature flags or properties exposing

   374      * characteristics of the document being parsed.)

   375      * </p>

   376      *

   377      * <p>During the parse, the XMLReader will provide information

   378      * about the XML document through the registered event

   379      * handlers.</p>

   380      *

   381      * <p>This method is synchronous: it will not return until parsing

   382      * has ended.  If a client application wants to terminate

   383      * parsing early, it should throw an exception.</p>

   384      *

   385      * @param input The input source for the top-level of the

   386      *        XML document.

   387      * @exception org.xml.sax.SAXException Any SAX exception, possibly

   388      *            wrapping another exception.

   389      * @exception java.io.IOException An IO exception from the parser,

   390      *            possibly from a byte stream or character stream

   391      *            supplied by the application.

   392      * @see org.xml.sax.InputSource

   393      * @see #parse(java.lang.String)

   394      * @see #setEntityResolver

   395      * @see #setDTDHandler

   396      * @see #setContentHandler

   397      * @see #setErrorHandler

   398      */

   399     public void parse (InputSource input)

   400         throws IOException, SAXException;

   401 

   402 

   403     /**

   404      * Parse an XML document from a system identifier (URI).

   405      *

   406      * <p>This method is a shortcut for the common case of reading a

   407      * document from a system identifier.  It is the exact

   408      * equivalent of the following:</p>

   409      *

   410      * <pre>

   411      * parse(new InputSource(systemId));

   412      * </pre>

   413      *

   414      * <p>If the system identifier is a URL, it must be fully resolved

   415      * by the application before it is passed to the parser.</p>

   416      *

   417      * @param systemId The system identifier (URI).

   418      * @exception org.xml.sax.SAXException Any SAX exception, possibly

   419      *            wrapping another exception.

   420      * @exception java.io.IOException An IO exception from the parser,

   421      *            possibly from a byte stream or character stream

   422      *            supplied by the application.

   423      * @see #parse(org.xml.sax.InputSource)

   424      */

   425     public void parse (String systemId)

   426         throws IOException, SAXException;

   427 

   428 }