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