/jEdit/tags/jedit-4-2-pre4/com/microstar/xml/XmlHandler.java
Java | 243 lines | 29 code | 28 blank | 186 comment | 0 complexity | a3440e30c40793387f6e777ee7ce9ab5 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
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 <dmeggins@microstar.com>
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>Æ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>Æ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. Æ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>Æ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>Æ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>Æ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>Æ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>Æ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>Æ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>Æ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>Æ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>Æ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>Æ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}