libjava/org/xml/sax/Parser.java

   1 // SAX parser interface.
   2 // http://www.saxproject.org
   3 // No warranty; no copyright -- use this as you will.
   4 // $Id: Parser.java,v 1.3.2.3 2002/01/29 21:34:14 dbrownell Exp $
   5
   6 package org.xml.sax;
   7
   8 import java.io.IOException;
   9 import java.util.Locale;
  10
  11
  12 /**
  13  * Basic interface for SAX (Simple API for XML) parsers.
  14  *
  15  * <blockquote>
  16  * <em>This module, both source code and documentation, is in the
  17  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  18  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  19  * for further information.
  20  * </blockquote>
  21  *
  22  * <p>This was the main event supplier interface for SAX1; it has
  23  * been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader},
  24  * which includes Namespace support and sophisticated configurability
  25  * and extensibility.</p>
  26  *
  27  * <p>All SAX1 parsers must implement this basic interface: it allows
  28  * applications to register handlers for different types of events
  29  * and to initiate a parse from a URI, or a character stream.</p>
  30  *
  31  * <p>All SAX1 parsers must also implement a zero-argument constructor
  32  * (though other constructors are also allowed).</p>
  33  *
  34  * <p>SAX1 parsers are reusable but not re-entrant: the application
  35  * may reuse a parser object (possibly with a different input source)
  36  * once the first parse has completed successfully, but it may not
  37  * invoke the parse() methods recursively within a parse.</p>
  38  *
  39  * @deprecated This interface has been replaced by the SAX2
  40  *             {@link org.xml.sax.XMLReader XMLReader}
  41  *             interface, which includes Namespace support.
  42  * @since SAX 1.0
  43  * @author David Megginson
  44  * @version 2.0.1 (sax2r2)
  45  * @see org.xml.sax.EntityResolver
  46  * @see org.xml.sax.DTDHandler
  47  * @see org.xml.sax.DocumentHandler
  48  * @see org.xml.sax.ErrorHandler
  49  * @see org.xml.sax.HandlerBase
  50  * @see org.xml.sax.InputSource
  51  */
  52 public interface Parser
  53 {
  54
  55     /**
  56      * Allow an application to request a locale for errors and warnings.
  57      *
  58      * <p>SAX parsers are not required to provide localisation for errors
  59      * and warnings; if they cannot support the requested locale,
  60      * however, they must throw a SAX exception.  Applications may
  61      * not request a locale change in the middle of a parse.</p>
  62      *
  63      * @param locale A Java Locale object.
  64      * @exception org.xml.sax.SAXException Throws an exception
  65      *            (using the previous or default locale) if the
  66      *            requested locale is not supported.
  67      * @see org.xml.sax.SAXException
  68      * @see org.xml.sax.SAXParseException
  69      */
  70     public abstract void setLocale (Locale locale)
  71         throws SAXException;
  72
  73
  74     /**
  75      * Allow an application to register a custom entity resolver.
  76      *
  77      * <p>If the application does not register an entity resolver, the
  78      * SAX parser will resolve system identifiers and open connections
  79      * to entities itself (this is the default behaviour implemented in
  80      * HandlerBase).</p>
  81      *
  82      * <p>Applications may register a new or different entity resolver
  83      * in the middle of a parse, and the SAX parser must begin using
  84      * the new resolver immediately.</p>
  85      *
  86      * @param resolver The object for resolving entities.
  87      * @see EntityResolver
  88      * @see HandlerBase
  89      */
  90     public abstract void setEntityResolver (EntityResolver resolver);
  91
  92
  93     /**
  94      * Allow an application to register a DTD event handler.
  95      *
  96      * <p>If the application does not register a DTD handler, all DTD
  97      * events reported by the SAX parser will be silently
  98      * ignored (this is the default behaviour implemented by
  99      * HandlerBase).</p>
 100      *
 101      * <p>Applications may register a new or different
 102      * handler in the middle of a parse, and the SAX parser must
 103      * begin using the new handler immediately.</p>
 104      *
 105      * @param handler The DTD handler.
 106      * @see DTDHandler
 107      * @see HandlerBase
 108      */
 109     public abstract void setDTDHandler (DTDHandler handler);
 110
 111
 112     /**
 113      * Allow an application to register a document event handler.
 114      *
 115      * <p>If the application does not register a document handler, all
 116      * document events reported by the SAX parser will be silently
 117      * ignored (this is the default behaviour implemented by
 118      * HandlerBase).</p>
 119      *
 120      * <p>Applications may register a new or different handler in the
 121      * middle of a parse, and the SAX parser must begin using the new
 122      * handler immediately.</p>
 123      *
 124      * @param handler The document handler.
 125      * @see DocumentHandler
 126      * @see HandlerBase
 127      */
 128     public abstract void setDocumentHandler (DocumentHandler handler);
 129
 130
 131     /**
 132      * Allow an application to register an error event handler.
 133      *
 134      * <p>If the application does not register an error event handler,
 135      * all error events reported by the SAX parser will be silently
 136      * ignored, except for fatalError, which will throw a SAXException
 137      * (this is the default behaviour implemented by HandlerBase).</p>
 138      *
 139      * <p>Applications may register a new or different handler in the
 140      * middle of a parse, and the SAX parser must begin using the new
 141      * handler immediately.</p>
 142      *
 143      * @param handler The error handler.
 144      * @see ErrorHandler
 145      * @see SAXException
 146      * @see HandlerBase
 147      */
 148     public abstract void setErrorHandler (ErrorHandler handler);
 149
 150
 151     /**
 152      * Parse an XML document.
 153      *
 154      * <p>The application can use this method to instruct the SAX parser
 155      * to begin parsing an XML document from any valid input
 156      * source (a character stream, a byte stream, or a URI).</p>
 157      *
 158      * <p>Applications may not invoke this method while a parse is in
 159      * progress (they should create a new Parser instead for each
 160      * additional XML document).  Once a parse is complete, an
 161      * application may reuse the same Parser object, possibly with a
 162      * different input source.</p>
 163      *
 164      * @param source The input source for the top-level of the
 165      *        XML document.
 166      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 167      *            wrapping another exception.
 168      * @exception java.io.IOException An IO exception from the parser,
 169      *            possibly from a byte stream or character stream
 170      *            supplied by the application.
 171      * @see org.xml.sax.InputSource
 172      * @see #parse(java.lang.String)
 173      * @see #setEntityResolver
 174      * @see #setDTDHandler
 175      * @see #setDocumentHandler
 176      * @see #setErrorHandler
 177      */
 178     public abstract void parse (InputSource source)
 179         throws SAXException, IOException;
 180
 181
 182     /**
 183      * Parse an XML document from a system identifier (URI).
 184      *
 185      * <p>This method is a shortcut for the common case of reading a
 186      * document from a system identifier.  It is the exact
 187      * equivalent of the following:</p>
 188      *
 189      * <pre>
 190      * parse(new InputSource(systemId));
 191      * </pre>
 192      *
 193      * <p>If the system identifier is a URL, it must be fully resolved
 194      * by the application before it is passed to the parser.</p>
 195      *
 196      * @param systemId The system identifier (URI).
 197      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 198      *            wrapping another exception.
 199      * @exception java.io.IOException An IO exception from the parser,
 200      *            possibly from a byte stream or character stream
 201      *            supplied by the application.
 202      * @see #parse(org.xml.sax.InputSource)
 203      */
 204     public abstract void parse (String systemId)
 205         throws SAXException, IOException;
 206
 207 }
 208
 209 // end of Parser.java