Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.microstar.xml
Interface XmlHandler

All Known Implementing Classes:
  HandlerBase

public interface XmlHandler

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.

Version:
  1.1
Author:
  Copyright (c) 1997, 1998 by Microstar Software Ltd., written by David Megginson <dmeggins@microstar.com>
See Also:
  `XmlParser`, `HandlerBase`, `org.xml.sax.EntityHandler`, `org.xml.sax.DocumentHandler`, `org.xml.sax.ErrorHandler`

Method Summary
`void` | `attribute(java.lang.String aname, java.lang.String value, boolean isSpecified)` Attribute.
`void` | `charData(char[] ch, int start, int length)` Character data.
`void` | `doctypeDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` Document type declaration.
`void` | `endDocument()` End the document.
`void` | `endElement(java.lang.String elname)` End an element.
`void` | `endExternalEntity(java.lang.String systemId)` End an external entity.
`void` | `error(java.lang.String message, java.lang.String systemId, int line, int column)` Fatal XML parsing error.
`void` | `ignorableWhitespace(char[] ch, int start, int length)` Ignorable whitespace.
`void` | `processingInstruction(java.lang.String target, java.lang.String data)` Processing instruction.
`java.lang.Object` | `resolveEntity(java.lang.String publicId, java.lang.String systemId)` Resolve an External Entity.
`void` | `startDocument()` Start the document.
`void` | `startElement(java.lang.String elname)` Start an element.
`void` | `startExternalEntity(java.lang.String systemId)` Begin an external entity.

Method Detail

### startDocument

    public void startDocument()
                       throws java.lang.Exception

  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.

  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `endDocument()`

### endDocument

    public void endDocument()
                     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.

  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `startDocument()`

### resolveEntity

    public java.lang.Object resolveEntity(java.lang.String publicId,
                                          java.lang.String systemId)
                                   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).

  Parameters:
    `publicId` - The public identifier, or null if none was supplied.
    `systemId` - The system identifier.
  Returns:
    The replacement system identifier, or null to use the default.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `startExternalEntity(java.lang.String)`, `endExternalEntity(java.lang.String)`

### startExternalEntity

    public void startExternalEntity(java.lang.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.

  Parameters:
    `systemId` - The URI of the external entity that is starting.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `endExternalEntity(java.lang.String)`, `resolveEntity(java.lang.String, java.lang.String)`

### endExternalEntity

    public void endExternalEntity(java.lang.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.

  Parameters:
    `systemId` - The URI of the external entity that is ending.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `startExternalEntity(java.lang.String)`, `resolveEntity(java.lang.String, java.lang.String)`

### doctypeDecl

    public void doctypeDecl(java.lang.String name,
                            java.lang.String publicId,
                            java.lang.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.

  Parameters:
    `name` - The document type name.
    `publicId` - The public identifier, or null if unspecified.
    `systemId` - The system identifier, or null if unspecified.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.

### attribute

    public void attribute(java.lang.String aname,
                          java.lang.String value,
                          boolean isSpecified)
                   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.

  Parameters:
    `value` - The value of the attribute, or null if the attribute is `#IMPLIED`.
    `isSpecified` - True if the value was specified, false if it was defaulted from the DTD.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `startElement(java.lang.String)`, `XmlParser.declaredAttributes(java.lang.String)`, `XmlParser.getAttributeType(java.lang.String, java.lang.String)`, `XmlParser.getAttributeDefaultValue(java.lang.String, java.lang.String)`

### startElement

    public void startElement(java.lang.String elname)
                      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.

  Parameters:
    `elname` - The element type name.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `attribute(java.lang.String, java.lang.String, boolean)`, `endElement(java.lang.String)`, `XmlParser.declaredElements()`, `XmlParser.getElementContentType(java.lang.String)`

### endElement

    public void endElement(java.lang.String elname)
                    throws java.lang.Exception

  End an element.

  Ælfred will call this method at the end of each element (including EMPTY elements).

  Parameters:
    `elname` - The element type name.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `startElement(java.lang.String)`, `XmlParser.declaredElements()`, `XmlParser.getElementContentType(java.lang.String)`

### charData

    public void charData(char[] ch,
                         int start,
                         int length)
                  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.

  Parameters:
    `ch` - The character data.
    `start` - The starting position in the array.
    `length` - The number of characters available.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.

### ignorableWhitespace

    public void ignorableWhitespace(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.

  Parameters:
    `ch` - The literal whitespace characters.
    `start` - The starting position in the array.
    `length` - The number of whitespace characters available.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.

### processingInstruction

    public void processingInstruction(java.lang.String target,
                                      java.lang.String data)
                               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

  Parameters:
    `target` - The target (the name at the start of the PI).
    `data` - The data, if any (the rest of the PI).
  Throws:
    `java.lang.Exception` - The handler may throw any exception.

### error

    public void error(java.lang.String message,
                      java.lang.String systemId,
                      int line,
                      int column)
               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.

  Parameters:
    `message` - The error message.
    `systemId` - The system identifier of the entity that contains the error.
    `line` - The approximate line number of the error.
    `column` - The approximate column number of the error.
  Throws:
    `java.lang.Exception` - The handler may throw any exception.
  See Also:
    `XmlException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD