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:

Revision: 23 1.4 src/com/ibm/xml/parser/SAXDriver.java, xml4jsrc, xml4j-jtcsv, xml4j_1_0_4

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	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 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, setDigestAlgorithm

 

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Constructor Detail

SAXDriver

public SAXDriver()

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

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.

Implements:

loadCatalog in interface StreamProducer

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