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.24.1 2004/05/01 08:34:40 jsuttor 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
210
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags