/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
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
- // XmlHandler.java: the callback interface.
- // NO WARRANTY! See README, and copyright below.
- // $Id: XmlHandler.java 3792 2001-09-02 05:37:43Z spestov $
- package com.microstar.xml;
- /**
- * XML Processing Interface.
- * <p>Whenever you parse an XML document, you must provide an object
- * from a class that implements this interface to receive the parsing
- * events.
- * <p>If you do not want to implement this entire interface, you
- * can extend the <code>HandlerBase</code> convenience class and
- * then implement only what you need.
- * <p>If you are using SAX, you should implement the SAX handler
- * interfaces rather than this one.
- * @author Copyright (c) 1997, 1998 by Microstar Software Ltd.
- * @author written by David Megginson <dmeggins@microstar.com>
- * @version 1.1
- * @see XmlParser
- * @see HandlerBase
- * @see org.xml.sax.EntityHandler
- * @see org.xml.sax.DocumentHandler
- * @see org.xml.sax.ErrorHandler
- */
- public interface XmlHandler {
- /**
- * Start the document.
- * <p>Ælfred will call this method just before it
- * attempts to read the first entity (the root of the document).
- * It is guaranteed that this will be the first method called.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #endDocument
- */
- public void startDocument ()
- throws java.lang.Exception;
- /**
- * End the document.
- * <p>Ælfred will call this method once, when it has
- * finished parsing the XML document.
- * It is guaranteed that this will be the last method called.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #startDocument
- */
- public void endDocument ()
- throws java.lang.Exception;
- /**
- * Resolve an External Entity.
- * <p>Give the handler a chance to redirect external entities
- * to different URIs. Ælfred will call this method for the
- * top-level document entity, for external text (XML) entities,
- * and the external DTD subset (if any).
- * @param publicId The public identifier, or null if none was supplied.
- * @param systemId The system identifier.
- * @return The replacement system identifier, or null to use
- * the default.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #startExternalEntity
- * @see #endExternalEntity
- */
- public Object resolveEntity (String publicId, String systemId)
- throws java.lang.Exception;
- /**
- * Begin an external entity.
- * <p>Ælfred will call this method at the beginning of
- * each external entity, including the top-level document entity
- * and the external DTD subset (if any).
- * <p>If necessary, you can use this method to track the location
- * of the current entity so that you can resolve relative URIs
- * correctly.
- * @param systemId The URI of the external entity that is starting.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #endExternalEntity
- * @see #resolveEntity
- */
- public void startExternalEntity (String systemId)
- throws java.lang.Exception;
- /**
- * End an external entity.
- * <p>Ælfred will call this method at the end of
- * each external entity, including the top-level document entity
- * and the external DTD subset.
- * <p>If necessary, you can use this method to track the location
- * of the current entity so that you can resolve relative URIs
- * correctly.
- * @param systemId The URI of the external entity that is ending.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #startExternalEntity
- * @see #resolveEntity
- */
- public void endExternalEntity (String systemId)
- throws java.lang.Exception;
- /**
- * Document type declaration.
- * <p>Ælfred will call this method when or if it encounters
- * the document type (DOCTYPE) declaration.
- * <p>Please note that the public and system identifiers will
- * not always be a reliable indication of the DTD in use.
- * @param name The document type name.
- * @param publicId The public identifier, or null if unspecified.
- * @param systemId The system identifier, or null if unspecified.
- * @exception java.lang.Exception The handler may throw any exception.
- */
- public void doctypeDecl (String name, String publicId, String systemId)
- throws java.lang.Exception;
- /**
- * Attribute.
- * <p>Ælfred will call this method once for each attribute
- * (specified or defaulted) before reporting a startElement event.
- * It is up to your handler to collect the attributes, if
- * necessary.
- * <p>You may use XmlParser.getAttributeType() to find the attribute's
- * declared type.
- * @param name The name of the attribute.
- * @param type The type of the attribute (see below).
- * @param value The value of the attribute, or null if the attribute
- * is <code>#IMPLIED</code>.
- * @param isSpecified True if the value was specified, false if it
- * was defaulted from the DTD.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #startElement
- * @see XmlParser#declaredAttributes
- * @see XmlParser#getAttributeType
- * @see XmlParser#getAttributeDefaultValue
- */
- public void attribute (String aname, String value, boolean isSpecified)
- throws java.lang.Exception;
- /**
- * Start an element.
- * <p>Ælfred will call this method at the beginning of each
- * element. By the time this is called, all of the attributes
- * for the element will already have been reported using the
- * <code>attribute</code> method.
- * @param elname The element type name.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #attribute
- * @see #endElement
- * @see XmlParser#declaredElements
- * @see XmlParser#getElementContentType
- */
- public void startElement (String elname)
- throws java.lang.Exception;
- /**
- * End an element.
- * <p>Ælfred will call this method at the end of each element
- * (including EMPTY elements).
- * @param elname The element type name.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see #startElement
- * @see XmlParser#declaredElements
- * @see XmlParser#getElementContentType
- */
- public void endElement (String elname)
- throws java.lang.Exception;
- /**
- * Character data.
- * <p>Ælfred will call this method once for each chunk of
- * character data found in the contents of elements. Note that
- * the parser may break up a long sequence of characters into
- * smaller chunks and call this method once for each chunk.
- * <p>Do <em>not</em> attempt to read more than <var>length</var>
- * characters from the array, or to read before the
- * <var>start</var> position.
- * @param ch The character data.
- * @param start The starting position in the array.
- * @param length The number of characters available.
- * @exception java.lang.Exception The handler may throw any exception.
- */
- public void charData (char ch[], int start, int length)
- throws java.lang.Exception;
- /**
- * Ignorable whitespace.
- * <p>Ælfred will call this method once for each sequence
- * of ignorable whitespace in element content (never in mixed content).
- * <p>For details, see section 2.10 of the XML 1.0 recommendation.
- * <p>Do <em>not</em> attempt to read more than <var>length</var>
- * characters from the array or to read before the <var>start</var>
- * position.
- * @param ch The literal whitespace characters.
- * @param start The starting position in the array.
- * @param length The number of whitespace characters available.
- * @exception java.lang.Exception The handler may throw any exception.
- */
- public void ignorableWhitespace (char ch[], int start, int length)
- throws java.lang.Exception;
- /**
- * Processing instruction.
- * <p>Ælfred will call this method once for each
- * processing instruction. Note that processing instructions may
- * appear outside of the top-level element. The
- * @param target The target (the name at the start of the PI).
- * @param data The data, if any (the rest of the PI).
- * @exception java.lang.Exception The handler may throw any exception.
- */
- public void processingInstruction (String target, String data)
- throws java.lang.Exception;
- /**
- * Fatal XML parsing error.
- * <p>Ælfred will call this method whenever it encounters
- * a serious error. The parser will attempt to continue past this
- * point so that you can find more possible error points, but if
- * this method is called you should assume that the document is
- * corrupt and you should not try to use its contents.
- * <p>Note that you can use the <code>XmlException</code> class
- * to encapsulate all of the information provided, though the
- * use of the class is not mandatory.
- * @param message The error message.
- * @param systemId The system identifier of the entity that
- * contains the error.
- * @param line The approximate line number of the error.
- * @param column The approximate column number of the error.
- * @exception java.lang.Exception The handler may throw any exception.
- * @see XmlException
- */
- public void error (String message, String systemId, int line, int column)
- throws java.lang.Exception;
- }