org.pfsw.pax

Class BaseXMLTagInterpreter

java.lang.Object

org.xml.sax.helpers.DefaultHandler

org.pfsw.pax.BaseXMLTagInterpreter

All Implemented Interfaces:

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

Direct Known Subclasses:

XMLWriteInterpreter

public abstract class BaseXMLTagInterpreter
extends org.xml.sax.helpers.DefaultHandler
implements XMLTagInterpreter

This is a basic implementation of a tag interpreter that is compliant to the interface XMLTagInterpreter.
It extends a HandlerBase which is a "fake" implementation of a ContentHandler. In the concept of PAX there normally is one XMLTagInterpreter for each tag that can be found in an XML stream.
A controller ( see XMLTagInterpreterController ) activates the corresponding interpreter for each new start tag found by the SAX-parser.
This class implements already all of the methods necessary to interact with the controller and the parser. But it is still an abstract class.
Subclasses must define the following four methods:

• getTagName()
• start()
• restart()
• getResult()

Additionally there are two other methods that can be overridden by subclasses if necessary:

• characterData()
• finalizeResult()

Constructor Summary

Constructors

Constructor and Description
BaseXMLTagInterpreter() Initializes any new instance.

Method Summary

Modifier and Type	Method and Description
void	characterData(java.lang.String data) This method is called whenever character data is received from the parser.
void	characters(char[] ch, int start, int length) Is called for PCDATA between a start and end tag.
void	comment(char[] ch, int start, int length)
void	endCDATA()
void	endDTD()
void	endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) Is called from the parser for an end tag.
void	endEntity(java.lang.String name)
protected void	finalizeResult() This method is called just before control is passed back to the controller.
protected XMLTagInterpreterController	getParseController()
abstract java.lang.Object	getResult() Returns the result object, created by this interpreter from the XML data .
abstract java.lang.String	getTagName() Returns the name of the tag, the interpreter is responsible for.
void	invalidSubTagError(java.lang.String tagName) This is a convenience method for throwing an exception, when a an invalid sub tag is detected.
void	requiredAttributeError(java.lang.String attrName) This is a convenience method for throwing an exception, when a a required attribute of a tag is missing.
abstract void	restart(java.lang.String subTagName, java.lang.Object subResult) Restarts the receiver after interpretation of a sub tag.
void	setController(XMLTagInterpreterController controller) Sets the controller, the interpreter has to return control to, when finished.
protected void	setParseController(XMLTagInterpreterController aValue)
abstract void	start(java.lang.String elementName, org.xml.sax.Attributes attributes) Starts the work of the receiver the first time.
void	startCDATA()
void	startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
void	startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attributes) A new sub tag was found.
void	startEntity(java.lang.String name)
protected void	trace(java.lang.String text) Method for debugging output.

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

endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xml.sax.ContentHandler

endDocument, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping

Constructor Detail

BaseXMLTagInterpreter

public BaseXMLTagInterpreter()

Initializes any new instance.

Method Detail

getTagName

public abstract java.lang.String getTagName()

Returns the name of the tag, the interpreter is responsible for.
It must be the exact tag name ( case-sensitive ) without opening and closing bracket ( '<' , '>' ).

Specified by:

getTagName in interface XMLTagInterpreter

Returns:

A string containing the name of the tag the receiver is made for.

start

public abstract void start(java.lang.String elementName,
                           org.xml.sax.Attributes attributes)
                    throws org.xml.sax.SAXException

Starts the work of the receiver the first time.
This method must be overridden by subclasses. The subclass here normally creates a new object corresponding to the tag and the given attributes.

Specified by:

start in interface XMLTagInterpreter

Parameters:

elementName - The name of the found element. Must be the same as getTagName().

attributes - The attributes defined in the start tag.

Throws:

org.xml.sax.SAXException - If the element name is wrong or any attribute is invalid.

See Also:

XMLTagInterpreter.getTagName()

restart

public abstract void restart(java.lang.String subTagName,
                             java.lang.Object subResult)
                      throws org.xml.sax.SAXException

Restarts the receiver after interpretation of a sub tag.
When the work of sub tag interpreter has been finished by reaching its end tag, the control is passed back to the previous tag interpreter, one step higher in the hierarchy. The tag interpreter controller retrieves the result object from that sub tag interpreter and gives it as an argument together with the sub tag's name to the restart method of the parent tag interpreter. Here the result of that sub tag can be put into a slot of this interpreter's object.

Specified by:

restart in interface XMLTagInterpreter

Parameters:

subTagName - The name of the sub tag that was completed

subResult - The resulting object build from the sub tag.

Throws:

org.xml.sax.SAXException - If the subtag is not allowed here.

getResult

public abstract java.lang.Object getResult()

Returns the result object, created by this interpreter from the XML data .

Returns:

The business object resulting from the parsed XML data.

characterData

public void characterData(java.lang.String data)

This method is called whenever character data is received from the parser.
In contrary to the ContentHandler.charachters() method it gets the data as string rather than a char[] array with start and length.
Subclasses must override this method, if their tag contains PCDATA. Here it's not defined as an abstract method, because the method's empty implementation is convenient for tag interpreters without PCDATA.

Parameters:

data - The data received from the parser.

See Also:

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

setController

public void setController(XMLTagInterpreterController controller)

Sets the controller, the interpreter has to return control to, when finished. Must not be used or overridden by subclasses. This method is only for the frameworks internal functionality.

Specified by:

setController in interface XMLTagInterpreter

Parameters:

controller - The controller of the XML interpretation process.

startElement

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

A new sub tag was found. The control is passed to the controller for invocation of the correct tag interpreter.
After finishing this sub tag, the controller returns control to this interpreter by calling restart().
The restart method then gets the result object from this sub tag.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

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

Throws:

org.xml.sax.SAXException

See Also:

restart(String,Object), ContentHandler.startElement(String,String,String,Attributes)

endElement

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

Is called from the parser for an end tag.
This end tag's name must be precisely the same as the tag's name the receiver is responsible for.
Subclasses must not use ore override this method !

This method calls finalizeResult() and then returns controll to the overall tag interpreter controller.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

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

Parameters:

uri - The URI of the tag's namespace or null if no namespace defined

localName - The name of the end tag without any namespace prefix.

qName - The qualified name (might contain the namespace prefix)

Throws:

org.xml.sax.SAXException

See Also:

ContentHandler.endElement(String,String,String)

characters

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

Is called for PCDATA between a start and end tag.
Don't use or override this method ! It will pass the received data as String to the method { @link #characterData(String) }.

Specified by:

characters in interface org.xml.sax.ContentHandler

Overrides:

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

Throws:

org.xml.sax.SAXException

See Also:

characterData(String)

invalidSubTagError

public void invalidSubTagError(java.lang.String tagName)
                        throws org.xml.sax.SAXException

This is a convenience method for throwing an exception, when a an invalid sub tag is detected. Subclasses should call this method with the sub tag's name to throw the appropriate exception. Normally this occurs at the end of the body of method restart(String,Object).

Parameters:

tagName - The name of the invalid sub tag.

Throws:

org.xml.sax.SAXException - Is always thrown by this method !

requiredAttributeError

public void requiredAttributeError(java.lang.String attrName)
                            throws org.xml.sax.SAXException

This is a convenience method for throwing an exception, when a a required attribute of a tag is missing. Subclasses should call this method with the attribute's name to throw the appropriate exception. Normally this occurs in the body of method start(String,Attributes).

Parameters:

attrName - The name of the required attribute.

Throws:

org.xml.sax.SAXException - Is always thrown by this method !

comment

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

Specified by:

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

Throws:

org.xml.sax.SAXException

endCDATA

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

Specified by:

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

Throws:

org.xml.sax.SAXException

endDTD

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

Specified by:

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

Throws:

org.xml.sax.SAXException

endEntity

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

Specified by:

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

Throws:

org.xml.sax.SAXException

startCDATA

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

Specified by:

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

Throws:

org.xml.sax.SAXException

startDTD

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

Specified by:

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

Throws:

org.xml.sax.SAXException

startEntity

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

Specified by:

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

Throws:

org.xml.sax.SAXException

finalizeResult

protected void finalizeResult()

This method is called just before control is passed back to the controller.
It gives the interpreter a chance to do any necessary completion of its result object. Subclasses must override this method, if such finalization is necessary.

trace

protected void trace(java.lang.String text)

Method for debugging output.
Currently not supported !

getParseController

protected XMLTagInterpreterController getParseController()

setParseController

protected void setParseController(XMLTagInterpreterController aValue)