com.devsphere.xml.taglib.process.parse
Class Handler

java.lang.Object
  |
  +--org.xml.sax.helpers.DefaultHandler
        |
        +--com.devsphere.xml.taglib.process.parse.Handler

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.ext.LexicalHandler, SDXController

public class Handler

extends org.xml.sax.helpers.DefaultHandler

implements org.xml.sax.ext.LexicalHandler, SDXController

This handler receives the SAX events as method calls and creates event objects. This is useful when the parsing is performed in one thread and the events must be processed/consumed by another thread. In the case of this tag library, the tag handlers consume the event objects in the JSP thread. The parsing must be done in a separate thread. Otherwise, the parsing would block the JSP thread until the whole document is parsed. The separate parsing thread allows the tag library to parse the document and process the events in parallel.

Constructor Summary

Handler(boolean ignoreSpaces)
Initializes the handler.

Method Summary

protected boolean	addEvent(EventSupport event) Makes an event available for processing.
void	characters(char[] ch, int start, int length) Adds a Characters event.
void	comment(char[] ch, int start, int length) Does nothing.
void	endCDATA() Does nothing.
void	endDocument() Adds an EndDocument event.
void	endDTD() Does nothing.
void	endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qualifiedName) Adds an EndElement event.
void	endEntity(java.lang.String name) Does nothing.
void	endParse() Sets the parseEnded to true.
EventSupport	getEvent() Returns the current parsing event.
void	handleDOM(org.w3c.dom.Element element) Receives the DOM sub-trees for handling.
void	processingInstruction(java.lang.String target, java.lang.String data) Adds a Processing event.
boolean	removeEvent(EventSupport event) Removes the current event to make room for a new event.
void	setDocumentLocator(org.xml.sax.Locator locator) Does nothing.
void	startCDATA() Does nothing.
void	startDocument() Adds a StartDocument event.
void	startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId) Does nothing.
void	startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qualifiedName, org.xml.sax.Attributes attributes) Doesn't add any event because the StartElement event was created and added by wantDOM()
void	startEntity(java.lang.String name) Does nothing.
boolean	wantDOM(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qualifiedName, org.xml.sax.Attributes attributes) Returns true when the application wants to receive a DOM sub-tree for handling.

Methods inherited from class org.xml.sax.helpers.DefaultHandler

endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, resolveEntity, skippedEntity, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Constructor Detail

Handler

public Handler(boolean ignoreSpaces)

Initializes the handler.

Parameters:

ignoreSpaces - a flag indicating if white space character data should be ignored

Method Detail

addEvent

protected boolean addEvent(EventSupport event)
                    throws Ender

Makes an event available for processing. This becomes the new current event that is returned by getEvent(). Before that, this method waits until the old current event, if any, is consumed.

Parameters:

event - the new current event

Returns:

true if the event was accepted or false if the parsing ended before receiving this event

Throws:

Ender - to interrupt the parsing when parseEnded is true and the parsing thread must be stopped

getEvent

public EventSupport getEvent()

Returns the current parsing event. Successive calls on this method will return the same event until the event is consumed or the parsing is interrupted.

Returns:

the current event or null if the parsing ended

removeEvent

public boolean removeEvent(EventSupport event)

Removes the current event to make room for a new event.

Parameters:

event - this must coincide with the current event in order to be removed

Returns:

true if the current event was removed

endParse

public void endParse()

Sets the parseEnded to true. Next time a SAX event is received for handling an Ender exception will be thrown in order to interrupt the parsing.

wantDOM

public boolean wantDOM(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qualifiedName,
                       org.xml.sax.Attributes attributes)
                throws org.xml.sax.SAXException

Returns true when the application wants to receive a DOM sub-tree for handling.

During the SAX parsing, a builder object invokes the wantDOM() method for each startElement() parsing event. If wantDOM() returns false the SAX parsing mode continues. When wantDOM() returns true the builder enters in DOM parsing mode and starts creating a DOM sub-tree from all SAX events between the current startElement() and the corresponding endElement().

Specified by:

wantDOM in interface SDXController

Parameters:

namespaceURI - The element's namespace URI

localName - The element's local name

qualifiedName - The element's qualified name

attributes - The element's attributes

Returns:

A boolean value indicating whether the builder must enter in DOM parsing mode or must remain in SAX parsing mode

Throws:

org.xml.sax.SAXException - If an error must be signaled

handleDOM

public void handleDOM(org.w3c.dom.Element element)
               throws org.xml.sax.SAXException

Receives the DOM sub-trees for handling.

After wantDOM() returns true, the builder constructs a DOM sub-tree from SAX events and passes it to the handleDOM() method. After handling, the builder returns to the SAX parsing mode.

Specified by:

handleDOM in interface SDXController

Parameters:

element - The root of the DOM sub-tree

Throws:

org.xml.sax.SAXException - If an error must be signaled

setDocumentLocator

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

Does nothing.

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

Overrides:

setDocumentLocator in class org.xml.sax.helpers.DefaultHandler

Parameters:

locator - The SAX Locator object

startDocument

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

Adds a StartDocument event.

Specified by:

startDocument in interface org.xml.sax.ContentHandler

Overrides:

startDocument in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

endDocument

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

Adds an EndDocument event.

Specified by:

endDocument in interface org.xml.sax.ContentHandler

Overrides:

endDocument in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

startElement

public void startElement(java.lang.String namespaceURI,
                         java.lang.String localName,
                         java.lang.String qualifiedName,
                         org.xml.sax.Attributes attributes)
                  throws org.xml.sax.SAXException

Doesn't add any event because the StartElement event was created and added by wantDOM()

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

startElement in class org.xml.sax.helpers.DefaultHandler

Parameters:

namespaceURI - The element's namespace URI

localName - The element's local name

qualifiedName - The element's qualified name

attributes - The element's attributes

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

endElement

public void endElement(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qualifiedName)
                throws org.xml.sax.SAXException

Adds an EndElement event.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

endElement in class org.xml.sax.helpers.DefaultHandler

Parameters:

namespaceURI - The element's namespace URI

localName - The element's local name

qualifiedName - The element's qualified name

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

characters

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

Adds a Characters event.

Specified by:

characters in interface org.xml.sax.ContentHandler

Overrides:

characters in class org.xml.sax.helpers.DefaultHandler

Parameters:

ch - The characters from the XML document

start - The start position in the array

length - The number of characters to get from the array

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

Adds a Processing event.

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

Overrides:

processingInstruction in class org.xml.sax.helpers.DefaultHandler

Parameters:

target - The target of the processing instruction.

data - The data of the processing instruction.

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

startDTD

public void startDTD(java.lang.String name,
                     java.lang.String publicId,
                     java.lang.String systemId)
              throws org.xml.sax.SAXException

Does nothing.

Specified by:

startDTD in interface org.xml.sax.ext.LexicalHandler

Parameters:

name - The name of the document's root element.

publicId - The public identifier of the external DTD

systemId - The system identifier of the external DTD

Throws:

org.xml.sax.SAXException - Cannot be thrown since the method does nothing

endDTD

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

Does nothing.

Specified by:

endDTD in interface org.xml.sax.ext.LexicalHandler

Throws:

org.xml.sax.SAXException - Cannot be thrown since the method does nothing

startEntity

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

Does nothing.

Specified by:

startEntity in interface org.xml.sax.ext.LexicalHandler

Parameters:

name - The name of an entity

Throws:

org.xml.sax.SAXException - Cannot be thrown since the method does nothing

endEntity

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

Does nothing.

Specified by:

endEntity in interface org.xml.sax.ext.LexicalHandler

Parameters:

name - The name of an entity

Throws:

org.xml.sax.SAXException - Cannot be thrown since the method does nothing

startCDATA

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

Does nothing.

Specified by:

startCDATA in interface org.xml.sax.ext.LexicalHandler

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

endCDATA

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

Does nothing.

Specified by:

endCDATA in interface org.xml.sax.ext.LexicalHandler

Throws:

org.xml.sax.SAXException - Error reported by the handler's method

comment

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

Does nothing.

Specified by:

comment in interface org.xml.sax.ext.LexicalHandler

Parameters:

ch - An array holding the characters in the comment

start - The start position in the array

length - The number of characters to get from the array

Throws:

org.xml.sax.SAXException - Error reported by the handler's method