Source for org.xml.sax.Parser

   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.1 2004/12/23 22:38:42 mark 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