org.jabber.jabberbeans.sax
Class SubHandler

java.lang.Object
  |
  +--org.jabber.jabberbeans.sax.SubHandler

All Implemented Interfaces:

DocumentHandler

Direct Known Subclasses:

HandshakeHandler, HashExtensionHandler, IQAgentHandler, IQAgentsHandler, IQAuthHandler, IQAutoUpdateHandler, IQBrowseHandler, IQPassHandler, IQPrivateHandler, IQSearchHandler, IQTimeHandler, IQVersionHandler, LogHandler, OOBHandler, PacketErrorHandler, PacketSubHandler, RosterHandler, SerializingHandler, XAutoUpdateHandler, XConferenceHandler, XDelayHandler, XMLStreamDocumentHandler, XMLStreamErrorHandler, XMLStreamHeaderHandler

public abstract class SubHandler

extends java.lang.Object

implements DocumentHandler

Subhandlers are registered with the main document handler to handle all data within an element with a specific name.

The basic idea is that a subhandler is built 'around' an element, so that handing a particular type of packet in jabber is the responsibility of different objects. For instance, PresenceHandler, MessageHandler, IQHandler.

The handler is constructed with the attribute list of the element, and is stopped (via stopHandler) when the element is closed. In between these two events, we get all the subelements and characters in the stream.

Constructor Summary

SubHandler()
Creates a new SubHandler instance.

Method Summary

void	characters(char[] ch, int start, int length) This is an exact copy of the characters function in the main handler
void	endDocument() do-nothing implementation
void	endElement(java.lang.String name) This is an exact copy of the end element in the main handler
HandlerFactory	getHandlerFactory() getHandlerFactory is used to get the HandlerFactory used to look up elements and namespace extension handlers.
protected byte	getSubCount() getSubCount returns the element level (the number of tags deep the parser is in within the SubHandler, not globally)
protected void	graftParent(java.lang.String name) graftParent is yet another ugly hack in the graft series, which allows for XMLStreamHeader to be interpreted as a packet instead of a new level.
protected void	graftSubHandler(SubHandler subHandler, java.lang.String name, AttributeList attributes) graftSubHandler is ssimilar to setChildSubHandler, except in that we are not specifying a handler for child tags, but actually one for the current sub-level.
protected void	handleEndElement(java.lang.String name) handleEndElement is overloaded by the new class to provide logic to handle element code.
protected void	handleStartElement(java.lang.String name, AttributeList attributes) handleStartElement is overloaded by the new class to provide logic to handle the element code.
void	ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void	processingInstruction(java.lang.String target, java.lang.String data) do-nothing implementation
protected void	receiveChildData(SubHandler subHandler, java.lang.Object o) receiveChildData is called when a child handler exits, returning control to this code.
protected void	setChildSubHandler(SubHandler subHandler, java.lang.String name, AttributeList attributes) setChildSubHandler is called to hook up a new subHandler to take over parsing the data stream, for instance in the case of a new Extension handler.
void	setDocumentLocator(Locator locator) do-nothing implementation
void	setHandlerFactory(HandlerFactory hf) setHandlerFactory is used to set the HandlerFactory used to look up elements and namespace extension handlers.
void	setParent(SubHandler handler) setParent is used to set the parent object (from the parent)
void	setParser(Parser newParser) setParser is used to set the SAX parser from the parent
void	startDocument() do-nothing implementation
void	startElement(java.lang.String name, AttributeList attributes) This is an exact copy of the start element in the main handler.
protected void	startHandler(java.lang.String name, AttributeList attributes) Gets called when the underlying engine decides to pass an entity and all sub-entities off to your subhandler.
protected java.lang.Object	stopHandler(java.lang.String name) Stophandler is the same as end element, except that it is called saying that the subhandler is no longer in scope.

Methods inherited from class java.lang.Object

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

Constructor Detail

SubHandler

public SubHandler()

Creates a new SubHandler instance.

Method Detail

startDocument

public final void startDocument()
                         throws SAXException

do-nothing implementation

Specified by:

startDocument in interface DocumentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

endDocument

public final void endDocument()
                       throws SAXException

do-nothing implementation

Specified by:

endDocument in interface DocumentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

processingInstruction

public final void processingInstruction(java.lang.String target,
                                        java.lang.String data)
                                 throws SAXException

do-nothing implementation

Specified by:

processingInstruction in interface DocumentHandler

Parameters:

target - The processing instruction target.

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

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

setDocumentLocator

public final void setDocumentLocator(Locator locator)

do-nothing implementation

Specified by:

setDocumentLocator in interface DocumentHandler

Parameters:

locator - An object that can return the location of any SAX document event.

See Also:

Locator

startElement

public final void startElement(java.lang.String name,
                               AttributeList attributes)
                        throws SAXException

This is an exact copy of the start element in the main handler.

Specified by:

startElement in interface DocumentHandler

Parameters:

name - string that holds the element name

attributes - AttributeList of attributes going with this element

Throws:

SAXException - thrown on error (unexpected element)

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

DocumentHandler.endElement(java.lang.String), AttributeList

endElement

public final void endElement(java.lang.String name)
                      throws SAXException

This is an exact copy of the end element in the main handler

Specified by:

endElement in interface DocumentHandler

Parameters:

name - string holding the element name

Throws:

SAXException - thrown on error

SAXException - Any SAX exception, possibly wrapping another exception.

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

This is an exact copy of the characters function in the main handler

Specified by:

characters in interface DocumentHandler

Parameters:

ch - character string detected

start - start position

length - length of string

Throws:

SAXException - thrown on error

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

DocumentHandler.ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Description copied from interface: DocumentHandler

Receive notification of ignorable whitespace in element content.

Validating Parsers must use this method to report each chunk of ignorable whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Specified by:

ignorableWhitespace in interface DocumentHandler

Parameters:

ch - The characters from the XML document.

start - The start position in the array.

length - The number of characters to read from the array.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

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

startHandler

protected void startHandler(java.lang.String name,
                            AttributeList attributes)
                     throws SAXException

Gets called when the underlying engine decides to pass an entity and all sub-entities off to your subhandler.

Upon seeing the element that this subhandler handles, we call this constructor, passing in the attributes.

Parameters:

name - name of the element which we are handling.

attributes - list of attributes on this element

SAXException

handleStartElement

protected void handleStartElement(java.lang.String name,
                                  AttributeList attributes)
                           throws SAXException

handleStartElement is overloaded by the new class to provide logic to handle the element code.

Parameters:

name - a String value

attributes - an AttributeList value

Throws:

SAXException - if an error occurs

handleEndElement

protected void handleEndElement(java.lang.String name)
                         throws SAXException

handleEndElement is overloaded by the new class to provide logic to handle element code.

Parameters:

name - a String value

Throws:

SAXException - if an error occurs

stopHandler

protected java.lang.Object stopHandler(java.lang.String name)
                                throws SAXException

Stophandler is the same as end element, except that it is called saying that the subhandler is no longer in scope.

SAXException

receiveChildData

protected void receiveChildData(SubHandler subHandler,
                                java.lang.Object o)
                         throws SAXException

receiveChildData is called when a child handler exits, returning control to this code. The now-defunct handler along with the data object are both returned.

Parameters:

subHandler - a SubHandler value

o - an Object value

Throws:

SAXException - if there is an error in the returned data

setParser

public final void setParser(Parser newParser)

setParser is used to set the SAX parser from the parent

Parameters:

newParser - a Parser value

setParent

public final void setParent(SubHandler handler)

setParent is used to set the parent object (from the parent)

Parameters:

handler - SubHandler which is this object's parent

setHandlerFactory

public final void setHandlerFactory(HandlerFactory hf)

setHandlerFactory is used to set the HandlerFactory used to look up elements and namespace extension handlers. This is set from the parent

getHandlerFactory

public final HandlerFactory getHandlerFactory()

getHandlerFactory is used to get the HandlerFactory used to look up elements and namespace extension handlers.

Returns:

HandlerFactory

getSubCount

protected final byte getSubCount()

getSubCount returns the element level (the number of tags deep the parser is in within the SubHandler, not globally)

Returns:

a byte value

setChildSubHandler

protected final void setChildSubHandler(SubHandler subHandler,
                                        java.lang.String name,
                                        AttributeList attributes)
                                 throws SAXException

setChildSubHandler is called to hook up a new subHandler to take over parsing the data stream, for instance in the case of a new Extension handler.

Parameters:

subHandler - a SubHandler value

name - a String value

attributes - an AttributeList value

Throws:

SAXException - if an error occurs

graftSubHandler

protected final void graftSubHandler(SubHandler subHandler,
                                     java.lang.String name,
                                     AttributeList attributes)
                              throws SAXException

graftSubHandler is ssimilar to setChildSubHandler, except in that we are not specifying a handler for child tags, but actually one for the current sub-level. The startHandler will be passed no parameters - do not try to use them. When the subhandler finishes, you can write a method to receive the child data, then call endElement yourself (with an appropriate name for your own code) to exit the calling handler.

Parameters:

subHandler - a SubHandler value

name - a String value

attributes - an AttributeList value

Throws:

SAXException - if an error occurs

graftParent

protected final void graftParent(java.lang.String name)
                          throws SAXException

graftParent is yet another ugly hack in the graft series, which allows for XMLStreamHeader to be interpreted as a packet instead of a new level. Without incrementing the parent's count, the whole thing will go to the wrong level once the parent exits, basically crashing the parser tree. Ugh. TODO: if XMLStreamDocumentHandler either parsed the headers itself or was the parent of the current XMLStreamDocumentHandler, this ugly hackedness would go away.

Parameters:

name - Name as would be passed to endElement if this was the end of a packet (same as the name attrib in a corresponding startElement)

SAXException