Contents | Package | Class | Tree | Deprecated | Index | Help | XML for Java
PREV | NEXT | SHOW LISTS | HIDE LISTS |

# Class com.ibm.xml.parser.SAXDriver

    java.lang.Object
        |
        +----com.ibm.xml.parser.DefaultElementFactory
                |
                +----com.ibm.xml.parser.SAXDriver

public class SAXDriver
extends DefaultElementFactory
implements Parser, AttributeList, ErrorListener, TagHandler, StreamProducer

This is the Simple API for XML (SAX) 1.0 driver for IBM XML4J. It implements the Parser and AttributeInterfaces as defined by SAX, and the ErrorListener, TagHandler, and StreamProducer interfaces defined by XML4J.

The Parser interface allows applications to register handlers for different types of events and to initiate a parse from a URI, or a character stream.

The AttributeList interface enables XML4J to pass an instance to the SAX application as the second argument of each startElement event. The instance provided will return valid results only during the scope of the startElement invocation.

Version:
  1.1
See Also:
  Parser, AttributeList, DefaultElementFactory

Constructor Summary
SAXDriver()

Method Summary
void | closeInputStream(Source source) This method is for XML4J-internal use and should not be called by SAX applications.
TXCDATASection | createCDATA(java.lang.String data) This method is for XML4J-internal use and should not be called by SAX applications.
DTD | createDTD(java.lang.String rootElementName, ExternalID externalID) This method is for XML4J-internal use and should not be called by SAX applications.
Entity | createEntity(java.lang.String name, ExternalID externalID, boolean isParameter, java.lang.String ndata) This method is for XML4J-internal use and should not be called by SAX applications.
NamespacePI | createNamespacePI(java.lang.String name, java.lang.String data, java.lang.String nsURI, java.lang.String prefixName, java.lang.String srcURI) This method is for XML4J-internal use and should not be called by SAX applications.
TXNotation | createNotation(java.lang.String name, ExternalID externalID) This method is for XML4J-internal use and should not be called by SAX applications.
TXPI | createPI(java.lang.String name, java.lang.String data) This method is for XML4J-internal use and should not be called by SAX applications.
StylesheetPI | createStylesheetPI(java.lang.String name, java.lang.String data, java.lang.String type, java.lang.String hrefURI, java.lang.String title) This method is for XML4J-internal use and should not be called by SAX applications.
TXText | createText(char[] carray, int offset, int length, boolean ignorableWhitespace) This method is for XML4J-internal use and should not be called by SAX applications.
void | error(java.lang.String fileName, int lineNo, int charOffset, java.lang.Object key, java.lang.String msg) This method is for XML4J-internal use and should not be called by SAX applications.
Source | getInputStream(java.lang.String name, java.lang.String publicID, java.lang.String systemID) This method is for XML4J-internal use and should not be called by SAX applications.
int | getLength() Return the number of attributes in this list.
java.lang.String | getName(int i) Return the name of an attribute in this list according to the specified index i.
java.lang.String | getType(int i) Return the type of an attribute in the list according to the specified index i.
java.lang.String | getType(java.lang.String name) Return the type of an attribute in the list according to the specified name.
java.lang.String | getValue(int i) Return the value of an attribute in the list according to the specified index i.
java.lang.String | getValue(java.lang.String name) Return the value of an attribute in the list according to the specified name.
void | handleEndTag(TXElement el, boolean empty) This method is for XML4J-internal use and should not be called by SAX applications.
void | handleStartTag(TXElement element, boolean empty) This method is for XML4J-internal use and should not be called by SAX applications.
void | parse(InputSource isrc) Begin parsing an XML document from any valid input source (a character stream or a byte stream).
void | parse(java.lang.String systemId) Begin parsing an XML document from a system identifier (URI).
void | setDocumentHandler(DocumentHandler handler) Register a document event handler.
void | setDTDHandler(DTDHandler handler) Register a DTD event handler.
void | setEntityResolver(EntityResolver handler) Register a custom entity resolver.
void | setErrorHandler(ErrorHandler handler) Register an error event handler.
void | setLocale(java.util.Locale locale) Sets a locale for errors and warnings.

Methods inherited from class com.ibm.xml.parser.DefaultElementFactory
createAttDef, createAttlist, createAttribute, createAttributeList, createCDATA, createComment, createContentModel, createContentModel, createDocument, createDTD, createDTD, createElement, createElementDecl, createEntity, createEntity, createGeneralReference, createMessageDigest, createNamespacePI, createNotation, createPI, createStylesheetPI, createText, createText, createText, getInstance, makeDigest, print, printAttDef, printAttlist, printComment, printDocument, printDTD, printElement, printElementDecl, printEntity, printGeneralReference, printNotation, printPI, printPseudoNode, printText, setDigestAlgorithm, toString, toStringAttDef, toStringAttlist, toStringAttribute, toStringComment, toStringDocument, toStringDTD, toStringElement, toStringElementDecl, toStringEntity, toStringGeneralReference, toStringNotation, toStringPI, toStringPseudoNode, toStringText

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

### SAXDriver

    public SAXDriver()

Method Detail

### setLocale

    public void setLocale(java.util.Locale locale) throws SAXException

  Sets a locale for errors and warnings. Locale changes are not supported in the middle of a parse.

  This method is defined by SAX.

  Implements:
    setLocale in interface Parser
  Parameters:
    `locale` - A Java Locale object.
  Throws:
    SAXException - Throws an exception, using the previous or default locale, if the requested locale is not supported.
  See Also:
    SAXException, SAXParseException

### setEntityResolver

    public void setEntityResolver(EntityResolver handler)

  Register a custom entity resolver. If no entity resolver is registered, XML4J itself will resolve all system identifiers and open connections to entities. Applications may register a new or different entity resolver in the middle of a parse, and XML4J will begin using the new resolver immediately.

  This method is defined by SAX.

  Implements:
    setEntityResolver in interface Parser
  Parameters:
    `handler` - The entity hander.
  See Also:
    EntityResolver, HandlerBase

### setDTDHandler

    public void setDTDHandler(DTDHandler handler)

  Register a DTD event handler. If no DTD handler is registered, XML4J will silently ignore all DTD events. Applications may register a new or different handler in the middle of a parse, and XML4J will begin using the new handler immediately.

  This method is defined by SAX.

  Implements:
    setDTDHandler in interface Parser
  Parameters:
    `handler` - The DTD handler.
  See Also:
    DTDHandler, HandlerBase

### setDocumentHandler

    public void setDocumentHandler(DocumentHandler handler)

  Register a document event handler. If no document handler is registered, XML4J will silently ignore all document events. Applications may register a new or different handler in the middle of a parse, and XML4J will begin using the new handler immediately.

  This method is defined by SAX.

  Implements:
    setDocumentHandler in interface Parser
  Parameters:
    `handler` - The document handler.
  See Also:
    DocumentHandler, HandlerBase

### setErrorHandler

    public void setErrorHandler(ErrorHandler handler)

  Register an error event handler. If no error handler is registered, XML4J will silently ignore all error events except for fatalError, which will throw a SAXException. Applications may register a new or different handler in the middle of a parse, and XML4J will begin using the new handler immediately.

  This method is defined by SAX.

  Implements:
    setErrorHandler in interface Parser
  Parameters:
    `handler` - The error handler.
  See Also:
    ErrorHandler, SAXException, HandlerBase

### parse

    public void parse(InputSource isrc) throws SAXException

  Begin parsing an XML document from any valid input source (a character stream or a byte stream). Applications may not invoke this method while a parse is in progress (they should create a new Parser instead for each additional XML document). Once a parse is complete, an application may reuse the same Parser object, possibly with a different input source.

  This method is defined by SAX.

  Implements:
    parse in interface Parser
  Parameters:
    `source` - The input source for the top-level of the XML document.
  Throws:
    SAXException - Any SAX exception, possibly wrapping another exception.
  See Also:
    InputSource, parse(java.lang.String), setEntityResolver, setDTDHandler, setDocumentHandler, setErrorHandler

### parse

    public void parse(java.lang.String systemId) throws SAXException

  Begin parsing an XML document from a system identifier (URI). This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

  >     parse(new InputSource(systemId));

  If the system identifier is a URL, it must be fully resolved by the application before it is passed to XML4J.

  This method is defined by SAX.

  Implements:
    parse in interface Parser
  Parameters:
    `systemId` - The system identifier (URI).
  Throws:
    SAXException - Any SAX exception, possibly wrapping another exception.
  See Also:
    parse(org.xml.sax.InputSource)

### getLength

    public int getLength()

  Return the number of attributes in this list.

  This method is defined by SAX.

  Implements:
    getLength in interface AttributeList
  Returns:
    The number of attributes in the list.

### getName

    public java.lang.String getName(int i)

  Return the name of an attribute in this list according to the specified index i. If the attribute name has a namespace prefix, the prefix will still be attached.

  This method is defined by SAX.

  Implements:
    getName in interface AttributeList
  Parameters:
    `i` - The index of the attribute in the list (starting at 0).
  Returns:
    The name of the indexed attribute, or null if the index is out of range.
  See Also:
    getLength

### getType

    public java.lang.String getType(int i)

  Return the type of an attribute in the list according to the specified index i.

  The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in upper case). If the parser has not read a declaration for the attribute, the value "CDATA" is returned. For an enumerated attribute that is not a notation, the parser will report the type as "NMTOKEN".

  This method is defined by SAX.

  Implements:
    getType in interface AttributeList
  Parameters:
    `i` - The index of the attribute in the list (starting at 0).
  Returns:
    The attribute type as a string, or null if the index is out of range.
  See Also:
    getLength, getType(java.lang.String)

### getType

    public java.lang.String getType(java.lang.String name)

  Return the type of an attribute in the list according to the specified name. The return value is the same as the return value for getType(int). If the attribute name has a namespace prefix, the prefix must be attached.

  This method is defined by SAX.

  Implements:
    getType in interface AttributeList
  Parameters:
    `name` - The name of the attribute.
  Returns:
    The attribute type as a string, or null if no such attribute exists.
  See Also:
    getType(int)

### getValue

    public java.lang.String getValue(int i)

  Return the value of an attribute in the list according to the specified index i. If the attribute value is a list of tokens (IDREFS, ENTITIES, or NMTOKENS), the tokens will be concatenated into a single string separated by whitespace.

  This method is defined by SAX.

  Implements:
    getValue in interface AttributeList
  Parameters:
    `i` - The index of the attribute in the list (starting at 0).
  Returns:
    The attribute value as a string, or null if the index is out of range.
  See Also:
    getLength, getValue(java.lang.String)

### getValue

    public java.lang.String getValue(java.lang.String name)

  Return the value of an attribute in the list according to the specified name. The return value is the same as the return value for getValue(int). If the attribute name has a namespace prefix, the prefix must be attached.

  This method is defined by SAX.

  Implements:
    getValue in interface AttributeList
  Parameters:
    `i` - The index of the attribute in the list.
  Returns:
    The attribute value as a string, or null if no such attribute exists.
  See Also:
    getValue(int)

### getInputStream

    public Source getInputStream(java.lang.String name,
                                 java.lang.String publicID,
                                 java.lang.String systemID) throws java.io.IOException, java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Returns the source of the input stream (could be a character stream or a byte stream) based on the entity specified by the system ID and/or public ID. Any registered entity handler will be invoked to resolve the entity specified by the system and public IDs.

  This method is defined by StreamProducer.

  Implements:
    getInputStream in interface StreamProducer
  Parameters:
    `name` - CURRENTLY NOT IMPLEMENTED.
    `publicID` - Entity's public ID, or null if no public ID (see ExternalID for details).
    `systemID` - Entity's system ID.
  Returns:
    The resolved source of the input stream, or null if unable to resolve.
  Throws:
    java.io.IOException - Thrown if unable to open the source defined by the specified IDs.
    java.lang.RuntimeException - Thrown if the `entityHandler` is unable to resolve the entity from the specified IDs.
  See Also:
    ExternalID, closeInputStream

### closeInputStream

    public void closeInputStream(Source source)

  This method is for XML4J-internal use and should not be called by SAX applications.

  Removes the input stream currently in use.

  This method is defined by StreamProducer.

  Implements:
    closeInputStream in interface StreamProducer
  Parameters:
    `source` - CURRENTLY NOT IMPLEMENTED.
  See Also:
    getInputStream

### error

    public void error(java.lang.String fileName,
                      int lineNo,
                      int charOffset,
                      java.lang.Object key,
                      java.lang.String msg) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Listen for XML4J parser errors, and reports these errors through any registered SAX error handler.

  Implements:
    error in interface ErrorListener
  Parameters:
    `fileName` - Processing file name, or null if error or warning occurs in a document.
    `lineNo` - The line number where the current document event ends, or -1 if not available. Note that this is the line position of the first character after the text associated with the document event. Do NOT trust this value when the input stream includes invalid octet as its encoding.
    `charOffset` - The column number where the current document event ends, or -1 if not available. Note that this is the column number of the first character after the text associated with the document event. The first column in a line is position 1. Do NOT trust this value when the input stream includes invalid octet as its encoding.
    `key` - The object may be an instance of `String` or `Exception`. When this object is `String`, this value may help classify msg as an error (begins with "E_") or warning (begins with "W_").
    `msg` - The error or warning message.

    This method is defined by ErrorListener.

  Throws:
    java.lang.RuntimeException - Thrown if the `errorHandler` fails.
  See Also:
    setErrorHandler

### handleStartTag

    public void handleStartTag(TXElement element,
                               boolean empty) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a start tag (and any attributes) has been parsed. This method will notify any registered document handlers.

  This method is defined by TagHandler.

  Implements:
    handleStartTag in interface TagHandler
  Parameters:
    `element` - TXElement that was parsed.
    `empty` - Not used by this method.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  See Also:
    setDocumentHandler, handleEndTag

### handleEndTag

    public void handleEndTag(TXElement el,
                             boolean empty) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that an end tag has been parsed. This method will notify any registered document handlers.

  This method is defined by TagHandler.

  Implements:
    handleEndTag in interface TagHandler
  Parameters:
    `el` - TXElement that was parsed.
    `empty` - Not used by this method.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  See Also:
    setDocumentHandler, handleStartTag

### createDTD

    public DTD createDTD(java.lang.String rootElementName,
                         ExternalID externalID)

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a DTD has been parsed.

  This method is defined by ElementFactory.

  Parameters:
    `rootElementName` - Name of the root Element to associate with the DTD.
    `externalID` - The external ID associated with the DTD, or null if the DTD does not have an external ID.
  Overrides:
    createDTD in class DefaultElementFactory
  See Also:
    DTD, ExternalID

### createEntity

    public Entity createEntity(java.lang.String name,
                               ExternalID externalID,
                               boolean isParameter,
                               java.lang.String ndata) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that an entity has been parsed. This method will notify any registered DTD handlers if an external binary entity is recognized.

  This method is defined by ElementFactory.

  Parameters:
    `name` - The name of the entity.
    `externalID` - The external ID associated with the Entity, or null if the Entity does not have an external ID (i.e. it is an internal entity).
    `isParameter` - =true if a parameter Entity; otherwise =false.
    `ndata` - The notation associated with the binary Entity, or null if the Entity is a text Entity.
  Throws:
    java.lang.RuntimeException - Thrown if the `dtdHandler` fails.
  Overrides:
    createEntity in class DefaultElementFactory
  See Also:
    setDTDHandler, Entity

### createNotation

    public TXNotation createNotation(java.lang.String name,
                                     ExternalID externalID) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a Notation has been parsed. This method will notify any registered DTD handlers.

  This method is defined by ElementFactory.

  Parameters:
    `name` - The name of the Notation.
    `externalID` - The external ID associated with the Notation, or null if the Notation does not have an external ID (i.e. it is an internal entity).
  Throws:
    java.lang.RuntimeException - Thrown if the `dtdHandler` fails.
  Overrides:
    createNotation in class DefaultElementFactory
  See Also:
    setDTDHandler, ExternalID

### createText

    public TXText createText(char[] carray,
                             int offset,
                             int length,
                             boolean ignorableWhitespace) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that Text has been parsed. This method will notify any registered document handlers.

  This method is defined by ElementFactory.

  Parameters:
    `carray` - an array of chracter including the actual content of the Text Node.
    `offset` - a position of starting content.
    `length` - a length of content
    `ignorableWhiteSpace` - The boolean indicator which determines whether white space (blanks) is to be considered for this Text Node. =true indicates whitespace is ignored; =false indicates whitespace is significant.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  Overrides:
    createText in class DefaultElementFactory
  See Also:
    setDocumentHandler

### createCDATA

    public TXCDATASection createCDATA(java.lang.String data) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a CDATA section has been parsed. This method will notify any registered document handlers.

  This method is defined by ElementFactory.

  Parameters:
    `data` - The actual data of the CDATA section.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  Overrides:
    createCDATA in class DefaultElementFactory
  See Also:
    setDocumentHandler

### createPI

    public TXPI createPI(java.lang.String name,
                         java.lang.String data) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a processing instruction (PI) has been parsed. This method will notify any registered document handlers.

  This method is defined by ElementFactory.

  Parameters:
    `name` - The first token following the markup.
    `data` - From the character immediately after name to the character immediately preceding the `?>`.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  Overrides:
    createPI in class DefaultElementFactory
  See Also:
    setDocumentHandler

### createNamespacePI

    public NamespacePI createNamespacePI(java.lang.String name,
                                         java.lang.String data,
                                         java.lang.String nsURI,
                                         java.lang.String prefixName,
                                         java.lang.String srcURI) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a namespacePI has been parsed. This method will notify any registered document handlers.

  This method is defined by ElementFactory.

  Parameters:
    `name` - The first token following the markup (i.e. "xml:namespace").
    `data` - From the character immediately after the name to the character immediately preceding the `?>`.
    `nsURI` - The value of the `ns=` attribute.
    `prefixName` - The value of the `prefix=` attribute.
    `srcURI` - The value of the `src=` attribute, or null.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  Overrides:
    createNamespacePI in class DefaultElementFactory
  See Also:
    setDocumentHandler

### createStylesheetPI

    public StylesheetPI createStylesheetPI(java.lang.String name,
                                           java.lang.String data,
                                           java.lang.String type,
                                           java.lang.String hrefURI,
                                           java.lang.String title) throws java.lang.RuntimeException

  This method is for XML4J-internal use and should not be called by SAX applications.

  Called by the XML4J parser in order to signal that a stylesheetPI has been parsed. This method will notify any registered document handlers.

  This method is defined by ElementFactory.

  Parameters:
    `name` - The first token following the markup (e.g. `"xml:stylesheet"`).
    `data` - From the character immediately after name to the character immediately preceding the `?>`.
    `type` - The value of the `type=` attribute.
    `hrefURI` - The value of the `href=` attribute.
    `title` - The value of the `title=` attribute, or null.
  Throws:
    java.lang.RuntimeException - Thrown if the `documentHandler` fails.
  Overrides:
    createStylesheetPI in class DefaultElementFactory
  See Also:
    setDocumentHandler

Contents | Package | Class | Tree | Deprecated | Index | Help |
PREV | NEXT | SHOW LISTS | HIDE LISTS |