XmlHandler


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   
5   package 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    */
26  public 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 }
244
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags