PageRenderTime 25ms CodeModel.GetById 19ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/jEdit/tags/jedit-4-0-pre5/com/microstar/xml/XmlHandler.java

#
Java | 243 lines | 29 code | 28 blank | 186 comment | 0 complexity | a3440e30c40793387f6e777ee7ce9ab5 MD5 | raw file
  1// XmlHandler.java: the callback interface.
  2// NO WARRANTY! See README, and copyright below.
  3// $Id: XmlHandler.java 3792 2001-09-02 05:37:43Z spestov $
  4
  5package com.microstar.xml;
  6
  7/**
  8  * XML Processing Interface.
  9  * <p>Whenever you parse an XML document, you must provide an object
 10  * from a class that implements this interface to receive the parsing 
 11  * events.
 12  * <p>If you do not want to implement this entire interface, you
 13  * can extend the <code>HandlerBase</code> convenience class and
 14  * then implement only what you need.
 15  * <p>If you are using SAX, you should implement the SAX handler
 16  * interfaces rather than this one.
 17  * @author Copyright (c) 1997, 1998 by Microstar Software Ltd.
 18  * @author written by David Megginson &lt;dmeggins@microstar.com&gt;
 19  * @version 1.1
 20  * @see XmlParser
 21  * @see HandlerBase
 22  * @see org.xml.sax.EntityHandler
 23  * @see org.xml.sax.DocumentHandler
 24  * @see org.xml.sax.ErrorHandler
 25  */
 26public interface XmlHandler {
 27
 28  /**
 29    * Start the document.
 30    * <p>&AElig;lfred will call this method just before it
 31    * attempts to read the first entity (the root of the document).
 32    * It is guaranteed that this will be the first method called.
 33    * @exception java.lang.Exception The handler may throw any exception.
 34    * @see #endDocument
 35    */
 36  public void startDocument ()
 37    throws java.lang.Exception;
 38
 39
 40  /**
 41    * End the document.
 42    * <p>&AElig;lfred will call this method once, when it has
 43    * finished parsing the XML document.
 44    * It is guaranteed that this will be the last method called.
 45    * @exception java.lang.Exception The handler may throw any exception.
 46    * @see #startDocument
 47    */
 48  public void endDocument ()
 49    throws java.lang.Exception;
 50
 51
 52  /**
 53    * Resolve an External Entity.
 54    * <p>Give the handler a chance to redirect external entities
 55    * to different URIs.  &AElig;lfred will call this method for the
 56    * top-level document entity, for external text (XML) entities, 
 57    * and the external DTD subset (if any).
 58    * @param publicId The public identifier, or null if none was supplied.
 59    * @param systemId The system identifier.
 60    * @return The replacement system identifier, or null to use
 61    *         the default.
 62    * @exception java.lang.Exception The handler may throw any exception.
 63    * @see #startExternalEntity
 64    * @see #endExternalEntity
 65    */
 66  public Object resolveEntity (String publicId, String systemId)
 67    throws java.lang.Exception;
 68
 69
 70  /**
 71    * Begin an external entity.
 72    * <p>&AElig;lfred will call this method at the beginning of
 73    * each external entity, including the top-level document entity
 74    * and the external DTD subset (if any).
 75    * <p>If necessary, you can use this method to track the location
 76    * of the current entity so that you can resolve relative URIs
 77    * correctly.
 78    * @param systemId The URI of the external entity that is starting.
 79    * @exception java.lang.Exception The handler may throw any exception.
 80    * @see #endExternalEntity
 81    * @see #resolveEntity
 82    */
 83  public void startExternalEntity (String systemId)
 84    throws java.lang.Exception;
 85
 86
 87  /**
 88    * End an external entity.
 89    * <p>&AElig;lfred will call this method at the end of
 90    * each external entity, including the top-level document entity
 91    * and the external DTD subset.
 92    * <p>If necessary, you can use this method to track the location
 93    * of the current entity so that you can resolve relative URIs
 94    * correctly.
 95    * @param systemId The URI of the external entity that is ending.
 96    * @exception java.lang.Exception The handler may throw any exception.
 97    * @see #startExternalEntity
 98    * @see #resolveEntity
 99    */
100  public void endExternalEntity (String systemId)
101    throws java.lang.Exception;
102
103
104  /**
105    * Document type declaration.
106    * <p>&AElig;lfred will call this method when or if it encounters
107    * the document type (DOCTYPE) declaration.
108    * <p>Please note that the public and system identifiers will
109    * not always be a reliable indication of the DTD in use.
110    * @param name The document type name.
111    * @param publicId The public identifier, or null if unspecified.
112    * @param systemId The system identifier, or null if unspecified.
113    * @exception java.lang.Exception The handler may throw any exception.
114    */
115  public void doctypeDecl (String name, String publicId, String systemId)
116    throws java.lang.Exception;
117
118
119  /**
120    * Attribute.
121    * <p>&AElig;lfred will call this method once for each attribute 
122    * (specified or defaulted) before reporting a startElement event.
123    * It is up to your handler to collect the attributes, if
124    * necessary.
125    * <p>You may use XmlParser.getAttributeType() to find the attribute's
126    * declared type.
127    * @param name The name of the attribute.
128    * @param type The type of the attribute (see below).
129    * @param value The value of the attribute, or null if the attribute
130    *        is <code>#IMPLIED</code>.
131    * @param isSpecified True if the value was specified, false if it
132    *       was defaulted from the DTD.
133    * @exception java.lang.Exception The handler may throw any exception.
134    * @see #startElement
135    * @see XmlParser#declaredAttributes
136    * @see XmlParser#getAttributeType
137    * @see XmlParser#getAttributeDefaultValue
138    */
139  public void attribute (String aname, String value, boolean isSpecified)
140    throws java.lang.Exception;
141
142
143  /**
144    * Start an element.
145    * <p>&AElig;lfred will call this method at the beginning of each
146    * element.  By the time this is called, all of the attributes
147    * for the element will already have been reported using the
148    * <code>attribute</code> method.
149    * @param elname The element type name.
150    * @exception java.lang.Exception The handler may throw any exception.
151    * @see #attribute
152    * @see #endElement
153    * @see XmlParser#declaredElements
154    * @see XmlParser#getElementContentType
155    */
156  public void startElement (String elname)
157    throws java.lang.Exception;
158
159
160  /**
161    * End an element.
162    * <p>&AElig;lfred will call this method at the end of each element
163    * (including EMPTY elements).
164    * @param elname The element type name.
165    * @exception java.lang.Exception The handler may throw any exception.
166    * @see #startElement
167    * @see XmlParser#declaredElements
168    * @see XmlParser#getElementContentType
169    */
170  public void endElement (String elname)
171    throws java.lang.Exception;
172
173
174  /**
175    * Character data.
176    * <p>&AElig;lfred will call this method once for each chunk of
177    * character data found in the contents of elements.  Note that
178    * the parser may break up a long sequence of characters into
179    * smaller chunks and call this method once for each chunk.
180    * <p>Do <em>not</em> attempt to read more than <var>length</var>
181    * characters from the array, or to read before the 
182    * <var>start</var> position.
183    * @param ch The character data.
184    * @param start The starting position in the array.
185    * @param length The number of characters available.
186    * @exception java.lang.Exception The handler may throw any exception.
187    */
188  public void charData (char ch[], int start, int length)
189    throws java.lang.Exception;
190
191
192  /**
193    * Ignorable whitespace.
194    * <p>&AElig;lfred will call this method once for each sequence
195    * of ignorable whitespace in element content (never in mixed content).
196    * <p>For details, see section 2.10 of the XML 1.0 recommendation.
197    * <p>Do <em>not</em> attempt to read more than <var>length</var>
198    * characters from the array or to read before the <var>start</var>
199    * position.
200    * @param ch The literal whitespace characters.
201    * @param start The starting position in the array.
202    * @param length The number of whitespace characters available.
203    * @exception java.lang.Exception The handler may throw any exception.
204    */
205  public void ignorableWhitespace (char ch[], int start, int length)
206    throws java.lang.Exception;
207
208
209  /**
210    * Processing instruction.
211    * <p>&AElig;lfred will call this method once for each
212    * processing instruction.  Note that processing instructions may
213    * appear outside of the top-level element.  The
214    * @param target The target (the name at the start of the PI).
215    * @param data The data, if any (the rest of the PI).
216    * @exception java.lang.Exception The handler may throw any exception.
217    */
218  public void processingInstruction (String target, String data)
219    throws java.lang.Exception;
220
221
222  /**
223    * Fatal XML parsing error.
224    * <p>&AElig;lfred will call this method whenever it encounters
225    * a serious error.  The parser will attempt to continue past this 
226    * point so that you can find more possible error points, but if
227    * this method is called you should assume that the document is
228    * corrupt and you should not try to use its contents.
229    * <p>Note that you can use the <code>XmlException</code> class
230    * to encapsulate all of the information provided, though the
231    * use of the class is not mandatory.
232    * @param message The error message.
233    * @param systemId The system identifier of the entity that 
234    *        contains the error.
235    * @param line The approximate line number of the error.
236    * @param column The approximate column number of the error.
237    * @exception java.lang.Exception The handler may throw any exception.
238    * @see XmlException
239    */
240  public void error (String message, String systemId, int line, int column)
241    throws java.lang.Exception;
242
243}