alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

What this is

This file is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Other links

The source code

// XmlHandler.java: the callback interface.
// NO WARRANTY! See README, and copyright below.
// $Id: XmlHandler.java,v 1.1.1.1 2001/08/20 22:31:23 gfx Exp $

package com.microstar.xml;

/**
  * XML Processing Interface.
  * 

Whenever you parse an XML document, you must provide an object * from a class that implements this interface to receive the parsing * events. *

If you do not want to implement this entire interface, you * can extend the HandlerBase convenience class and * then implement only what you need. *

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. *

Æ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. *

Æ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. *

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. *

Æ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). *

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. *

Ælfred will call this method at the end of * each external entity, including the top-level document entity * and the external DTD subset. *

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. *

Ælfred will call this method when or if it encounters * the document type (DOCTYPE) declaration. *

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. *

Æ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. *

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 #IMPLIED. * @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. *

Æ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 * attribute 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. *

Æ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. *

Æ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. *

Do not attempt to read more than length * characters from the array, or to read before the * start 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. *

Ælfred will call this method once for each sequence * of ignorable whitespace in element content (never in mixed content). *

For details, see section 2.10 of the XML 1.0 recommendation. *

Do not attempt to read more than length * characters from the array or to read before the start * 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. *

Æ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. *

Æ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. *

Note that you can use the XmlException 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; }

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.