com.realtime.xmpp
Class SaxEventManager

java.lang.Object
  |
  +--com.realtime.xmpp.SaxEventManager

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

public class SaxEventManager

extends java.lang.Object

implements org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

Interpret a stream of SAX events and pass the events to interested listeners. This class is used by the XmppStream to propogate SAX events to XMPP stream interpreters, or "transformers". Each transformer creates an in-memory representation of packets, and then signals packet listeners.

This plugable architecture provides the freedom to adopt whichever packet object model suits the task at hand.

As per the XMPP-Core draft document "XML streams are used to transport a subset of XML. Specifically, XML streams SHOULD NOT contain processing instructions, non-predefined entities (as defined in Section 4.6 of the XML 1.0 specification [8]), comments, or DTDs. Any such XML data SHOULD be ignored." As such, unecessary/illegal SAX events are not propogated.

Version:

1.0 Copyright © 2002 Real Time Entertainment Group, LLC - All rights reserved.

Author:

Mike Prince

Field Summary

protected org.xml.sax.ContentHandler[]	m_contentHandlers The list of ContentHandlers.
protected int	m_elementDepth The current element depth.
protected org.xml.sax.ContentHandler[]	m_newTransformers The list of new transformers, which will take affect just before the next packet event set starts.
protected java.util.Map	m_streamAttributes Stream attributes.

Constructor Summary

SaxEventManager()
Simple default constructor.

Method Summary

void	characters(char[] ch, int start, int length) Receive notification of character data inside an element.
void	endDocument() This event is not propogated to the XMPP interpreter.
void	endElement(java.lang.String sUri, java.lang.String sLocalName, java.lang.String sQName) Receive notification of the end of an element.
void	endPrefixMapping(java.lang.String sPrefix) Receive notification of the end of a Namespace mapping.
void	error(org.xml.sax.SAXParseException e) Receive notification of a recoverable parser error.
void	fatalError(org.xml.sax.SAXParseException e) Report a fatal XML parsing error.
java.lang.String	getAttribute(java.lang.String sQName) Provide an attribute from the <stream:stream> top level element.
boolean	hasAttributes() Determine if this stream has provided any attributes.
void	ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void	processingInstruction(java.lang.String sTarget, java.lang.String sData) XMPP SHOULD NOT contain processing instructions!
void	reset() Reset this event manager so it's ready to start accepting a fresh set of SAX events.
void	setDocumentLocator(org.xml.sax.Locator locator) Receive a Locator object for document events.
void	setTransformers(org.xml.sax.ContentHandler[] transformers) Set the list of transformers to use for each SAX event.
void	skippedEntity(java.lang.String name) Receive notification of a skipped entity.
void	startDocument() This event is NOT propogated to the XMPP interpreter.
void	startElement(java.lang.String sUri, java.lang.String sLocalName, java.lang.String sQName, org.xml.sax.Attributes attributes) Receive notification of the start of an element.
void	startPrefixMapping(java.lang.String sPrefix, java.lang.String sUri) Receive notification of the start of a Namespace mapping.
protected void	startXmppPacket() This method is called before the start of each NEW XMPP packet in the XML stream.
void	warning(org.xml.sax.SAXParseException e) Receive notification of a parser warning.

Methods inherited from class java.lang.Object

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

Field Detail

m_streamAttributes

protected java.util.Map m_streamAttributes

Stream attributes. If this is non-null, then the XMPP stream has been started.

m_newTransformers

protected org.xml.sax.ContentHandler[] m_newTransformers

The list of new transformers, which will take affect just before the next packet event set starts.

m_contentHandlers

protected org.xml.sax.ContentHandler[] m_contentHandlers

The list of ContentHandlers.

m_elementDepth

protected int m_elementDepth

The current element depth. Zero means we are at the root, or stream, element level. Each packet starts at depth=1.

Constructor Detail

SaxEventManager

public SaxEventManager()

Simple default constructor. Remember to register transformers to interpret the XMPP event stream.

Method Detail

reset

public void reset()

Reset this event manager so it's ready to start accepting a fresh set of SAX events.

setTransformers

public void setTransformers(org.xml.sax.ContentHandler[] transformers)

Set the list of transformers to use for each SAX event. This list DOES NOT go into effect until the start of the next XMPP packet.

Parameters:

transformers - An array of transformers to handle each SAX event.

startXmppPacket

protected void startXmppPacket()

This method is called before the start of each NEW XMPP packet in the XML stream. This gives us a chance to make any changes that could not be done while in the middle of interpreting a set of SAX events.

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

Receive a Locator object for document events. Perhaps this is useful for locating the position in a XMPP stream for SAX events.

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

Parameters:

locator - A locator for all SAX document events.

See Also:

ContentHandler.setDocumentLocator(org.xml.sax.Locator), Locator

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

This event is NOT propogated to the XMPP interpreter. Instead, the first element of each XMPP packet causes this event to be fired.

Specified by:

startDocument in interface org.xml.sax.ContentHandler

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

This event is not propogated to the XMPP interpreter. Instead, the last element of each XMPP packet causes this event to be fired.

Specified by:

endDocument in interface org.xml.sax.ContentHandler

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.endDocument()

startPrefixMapping

public void startPrefixMapping(java.lang.String sPrefix,
                               java.lang.String sUri)
                        throws org.xml.sax.SAXException

Receive notification of the start of a Namespace mapping.

Specified by:

startPrefixMapping in interface org.xml.sax.ContentHandler

Parameters:

sPrefix - The Namespace prefix being declared.

sUri - The Namespace URI mapped to the prefix.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(java.lang.String sPrefix)
                      throws org.xml.sax.SAXException

Receive notification of the end of a Namespace mapping.

Specified by:

endPrefixMapping in interface org.xml.sax.ContentHandler

Parameters:

sPrefix - The Namespace prefix being declared.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(java.lang.String sUri,
                         java.lang.String sLocalName,
                         java.lang.String sQName,
                         org.xml.sax.Attributes attributes)
                  throws org.xml.sax.SAXException

Receive notification of the start of an element.

If this is the first element in the stream then the attributes are cached and made available through getAttribute().

Second level elements trigger a startDocument() event.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Parameters:

sUri - The URI.

sLocalName - The element local name.

sQName - The elements qualified name.

attributes - The specified or defaulted attributes.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endElement

public void endElement(java.lang.String sUri,
                       java.lang.String sLocalName,
                       java.lang.String sQName)
                throws org.xml.sax.SAXException

Receive notification of the end of an element.

Send level elements trigger an endDocument() event.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Parameters:

sUri - The URI.

sLocalName - The local name of the element.

sQName - The qualified name of the element.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

Receive notification of character data inside an element.

Specified by:

characters in interface org.xml.sax.ContentHandler

Parameters:

ch - The characters.

start - The start position in the character array.

length - The number of characters to use from the character array.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.characters(char[], int, int)

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException

Receive notification of ignorable whitespace in element content.

Specified by:

ignorableWhitespace in interface org.xml.sax.ContentHandler

Parameters:

ch - The whitespace characters.

start - The start position in the character array.

length - The number of characters to use from the character array.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(java.lang.String sTarget,
                                  java.lang.String sData)

XMPP SHOULD NOT contain processing instructions!

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

Parameters:

sTarget - The processing instruction target.

sData - The processing instruction data, or null if none is supplied.

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

Receive notification of a skipped entity.

Specified by:

skippedEntity in interface org.xml.sax.ContentHandler

Parameters:

name - The name of the skipped entity.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.processingInstruction(java.lang.String, java.lang.String)

warning

public void warning(org.xml.sax.SAXParseException e)
             throws org.xml.sax.SAXException

Receive notification of a parser warning.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each warning, such as inserting the message in a log file or printing it to the console.

Specified by:

warning in interface org.xml.sax.ErrorHandler

Parameters:

e - The warning information encoded as an exception.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

error

public void error(org.xml.sax.SAXParseException e)
           throws org.xml.sax.SAXException

Receive notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

Specified by:

error in interface org.xml.sax.ErrorHandler

Parameters:

e - The warning information encoded as an exception.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

fatalError

public void fatalError(org.xml.sax.SAXParseException e)
                throws org.xml.sax.SAXException

Report a fatal XML parsing error.

The default implementation throws a SAXParseException. Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

Parameters:

e - The error information encoded as an exception.

Throws:

org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ErrorHandler.fatalError(org.xml.sax.SAXParseException), SAXParseException

getAttribute

public java.lang.String getAttribute(java.lang.String sQName)

Provide an attribute from the <stream:stream> top level element. Typical attributes are id and from.

* @param sQName The name of the attribute. * @return The value of the attribute,

hasAttributes

public boolean hasAttributes()

Determine if this stream has provided any attributes. This can also be used to determine if the session opening <stream:stream> element has been received yet.

Returns:

True if the opening stream element has been received along with any attributes. False otherwise.