XML Parser for Java 1.1.16

com.ibm.xml.parser
Class SAXDriver

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

public class SAXDriver
extends java.lang.Object
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:
Revision: 23 1.20 src/com/ibm/xml/parser/SAXDriver.java, xml4jsrc, xml4j-jtcsv, xml4j_1_1_16
See Also:
Parser, AttributeList, TXDocument

Constructor Summary
SAXDriver()
           
 
Method Summary
 void closeInputStream(Source source)
          This method is for XML4J-internal use and should not be called by SAX applications.
 int 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 loadCatalog(java.io.Reader reader)
          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 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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setDocumentHandler(org.xml.sax.DocumentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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.

Specified by:
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(com.ibm.xml.parser.Source)

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.

Specified by:
closeInputStream in interface StreamProducer
Parameters:
source - CURRENTLY NOT IMPLEMENTED.
See Also:
getInputStream(java.lang.String, java.lang.String, java.lang.String)

loadCatalog

public void loadCatalog(java.io.Reader reader)
                 throws java.io.IOException
This method is for XML4J-internal use and should not be called by SAX applications.

This method is defined by StreamProducer.

Specified by:
loadCatalog in interface StreamProducer

error

public int 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.

Specified by:
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(org.xml.sax.ErrorHandler)

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.

Specified by:
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(org.xml.sax.DocumentHandler), handleEndTag(com.ibm.xml.parser.TXElement, boolean)

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.

Specified by:
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(org.xml.sax.DocumentHandler), handleStartTag(com.ibm.xml.parser.TXElement, boolean)

XML Parser for Java 1.1.16