001: // XmlHandler.java: the callback interface.
002: // NO WARRANTY! See README, and copyright below.
003: // $Id: XmlHandler.java 3792 2001-09-02 05:37:43Z spestov $
004:
005: package com.microstar.xml;
006:
007: /**
008: * XML Processing Interface.
009: * <p>Whenever you parse an XML document, you must provide an object
010: * from a class that implements this interface to receive the parsing
011: * events.
012: * <p>If you do not want to implement this entire interface, you
013: * can extend the <code>HandlerBase</code> convenience class and
014: * then implement only what you need.
015: * <p>If you are using SAX, you should implement the SAX handler
016: * interfaces rather than this one.
017: * @author Copyright (c) 1997, 1998 by Microstar Software Ltd.
018: * @author written by David Megginson <dmeggins@microstar.com>
019: * @version 1.1
020: * @see XmlParser
021: * @see HandlerBase
022: * @see org.xml.sax.EntityHandler
023: * @see org.xml.sax.DocumentHandler
024: * @see org.xml.sax.ErrorHandler
025: */
026: public interface XmlHandler {
027:
028: /**
029: * Start the document.
030: * <p>Ælfred will call this method just before it
031: * attempts to read the first entity (the root of the document).
032: * It is guaranteed that this will be the first method called.
033: * @exception java.lang.Exception The handler may throw any exception.
034: * @see #endDocument
035: */
036: public void startDocument() throws java.lang.Exception;
037:
038: /**
039: * End the document.
040: * <p>Ælfred will call this method once, when it has
041: * finished parsing the XML document.
042: * It is guaranteed that this will be the last method called.
043: * @exception java.lang.Exception The handler may throw any exception.
044: * @see #startDocument
045: */
046: public void endDocument() throws java.lang.Exception;
047:
048: /**
049: * Resolve an External Entity.
050: * <p>Give the handler a chance to redirect external entities
051: * to different URIs. Ælfred will call this method for the
052: * top-level document entity, for external text (XML) entities,
053: * and the external DTD subset (if any).
054: * @param publicId The public identifier, or null if none was supplied.
055: * @param systemId The system identifier.
056: * @return The replacement system identifier, or null to use
057: * the default.
058: * @exception java.lang.Exception The handler may throw any exception.
059: * @see #startExternalEntity
060: * @see #endExternalEntity
061: */
062: public Object resolveEntity(String publicId, String systemId)
063: throws java.lang.Exception;
064:
065: /**
066: * Begin an external entity.
067: * <p>Ælfred will call this method at the beginning of
068: * each external entity, including the top-level document entity
069: * and the external DTD subset (if any).
070: * <p>If necessary, you can use this method to track the location
071: * of the current entity so that you can resolve relative URIs
072: * correctly.
073: * @param systemId The URI of the external entity that is starting.
074: * @exception java.lang.Exception The handler may throw any exception.
075: * @see #endExternalEntity
076: * @see #resolveEntity
077: */
078: public void startExternalEntity(String systemId)
079: throws java.lang.Exception;
080:
081: /**
082: * End an external entity.
083: * <p>Ælfred will call this method at the end of
084: * each external entity, including the top-level document entity
085: * and the external DTD subset.
086: * <p>If necessary, you can use this method to track the location
087: * of the current entity so that you can resolve relative URIs
088: * correctly.
089: * @param systemId The URI of the external entity that is ending.
090: * @exception java.lang.Exception The handler may throw any exception.
091: * @see #startExternalEntity
092: * @see #resolveEntity
093: */
094: public void endExternalEntity(String systemId)
095: throws java.lang.Exception;
096:
097: /**
098: * Document type declaration.
099: * <p>Ælfred will call this method when or if it encounters
100: * the document type (DOCTYPE) declaration.
101: * <p>Please note that the public and system identifiers will
102: * not always be a reliable indication of the DTD in use.
103: * @param name The document type name.
104: * @param publicId The public identifier, or null if unspecified.
105: * @param systemId The system identifier, or null if unspecified.
106: * @exception java.lang.Exception The handler may throw any exception.
107: */
108: public void doctypeDecl(String name, String publicId,
109: String systemId) throws java.lang.Exception;
110:
111: /**
112: * Attribute.
113: * <p>Ælfred will call this method once for each attribute
114: * (specified or defaulted) before reporting a startElement event.
115: * It is up to your handler to collect the attributes, if
116: * necessary.
117: * <p>You may use XmlParser.getAttributeType() to find the attribute's
118: * declared type.
119: * @param name The name of the attribute.
120: * @param type The type of the attribute (see below).
121: * @param value The value of the attribute, or null if the attribute
122: * is <code>#IMPLIED</code>.
123: * @param isSpecified True if the value was specified, false if it
124: * was defaulted from the DTD.
125: * @exception java.lang.Exception The handler may throw any exception.
126: * @see #startElement
127: * @see XmlParser#declaredAttributes
128: * @see XmlParser#getAttributeType
129: * @see XmlParser#getAttributeDefaultValue
130: */
131: public void attribute(String aname, String value,
132: boolean isSpecified) throws java.lang.Exception;
133:
134: /**
135: * Start an element.
136: * <p>Ælfred will call this method at the beginning of each
137: * element. By the time this is called, all of the attributes
138: * for the element will already have been reported using the
139: * <code>attribute</code> method.
140: * @param elname The element type name.
141: * @exception java.lang.Exception The handler may throw any exception.
142: * @see #attribute
143: * @see #endElement
144: * @see XmlParser#declaredElements
145: * @see XmlParser#getElementContentType
146: */
147: public void startElement(String elname) throws java.lang.Exception;
148:
149: /**
150: * End an element.
151: * <p>Ælfred will call this method at the end of each element
152: * (including EMPTY elements).
153: * @param elname The element type name.
154: * @exception java.lang.Exception The handler may throw any exception.
155: * @see #startElement
156: * @see XmlParser#declaredElements
157: * @see XmlParser#getElementContentType
158: */
159: public void endElement(String elname) throws java.lang.Exception;
160:
161: /**
162: * Character data.
163: * <p>Ælfred will call this method once for each chunk of
164: * character data found in the contents of elements. Note that
165: * the parser may break up a long sequence of characters into
166: * smaller chunks and call this method once for each chunk.
167: * <p>Do <em>not</em> attempt to read more than <var>length</var>
168: * characters from the array, or to read before the
169: * <var>start</var> position.
170: * @param ch The character data.
171: * @param start The starting position in the array.
172: * @param length The number of characters available.
173: * @exception java.lang.Exception The handler may throw any exception.
174: */
175: public void charData(char ch[], int start, int length)
176: throws java.lang.Exception;
177:
178: /**
179: * Ignorable whitespace.
180: * <p>Ælfred will call this method once for each sequence
181: * of ignorable whitespace in element content (never in mixed content).
182: * <p>For details, see section 2.10 of the XML 1.0 recommendation.
183: * <p>Do <em>not</em> attempt to read more than <var>length</var>
184: * characters from the array or to read before the <var>start</var>
185: * position.
186: * @param ch The literal whitespace characters.
187: * @param start The starting position in the array.
188: * @param length The number of whitespace characters available.
189: * @exception java.lang.Exception The handler may throw any exception.
190: */
191: public void ignorableWhitespace(char ch[], int start, int length)
192: throws java.lang.Exception;
193:
194: /**
195: * Processing instruction.
196: * <p>Ælfred will call this method once for each
197: * processing instruction. Note that processing instructions may
198: * appear outside of the top-level element. The
199: * @param target The target (the name at the start of the PI).
200: * @param data The data, if any (the rest of the PI).
201: * @exception java.lang.Exception The handler may throw any exception.
202: */
203: public void processingInstruction(String target, String data)
204: throws java.lang.Exception;
205:
206: /**
207: * Fatal XML parsing error.
208: * <p>Ælfred will call this method whenever it encounters
209: * a serious error. The parser will attempt to continue past this
210: * point so that you can find more possible error points, but if
211: * this method is called you should assume that the document is
212: * corrupt and you should not try to use its contents.
213: * <p>Note that you can use the <code>XmlException</code> class
214: * to encapsulate all of the information provided, though the
215: * use of the class is not mandatory.
216: * @param message The error message.
217: * @param systemId The system identifier of the entity that
218: * contains the error.
219: * @param line The approximate line number of the error.
220: * @param column The approximate column number of the error.
221: * @exception java.lang.Exception The handler may throw any exception.
222: * @see XmlException
223: */
224: public void error(String message, String systemId, int line,
225: int column) throws java.lang.Exception;
226:
227: }
|