edu.mit.jverbnet.util.parse
Class MappedHandler<T>

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      edu.mit.jverbnet.util.parse.MappedHandler<T>

All Implemented Interfaces:

IHasParserHandler, ITaggedBlockTaskHandler, ITaggedHandler<T>, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

Direct Known Subclasses:

ArgHandler, CDataHandler, FrameHandler, ListHandler, MemberHandler, PredicateDescHandler, RestrictionHandler, SelRestrictionsHandler, SemanticDescHandler, SyntaxArgDescHandler, SyntaxDescHandler, ThematicRoleHandler, VerbClassHandler

public class MappedHandler<T>
extends org.xml.sax.helpers.DefaultHandler
implements ITaggedHandler<T>, ITaggedBlockTaskHandler

A handler which processes tags internal to its tagged block by assigning handlers to qNames.

Since:

JVerbnet 1.0.0

Version:

1.2.0

Author:

Mark A. Finlayson

Field Summary

static java.lang.String	messageIgnoringElementBlockExternal
protected static java.util.regex.Matcher	messageMatcherIgnoreExternal
protected static java.util.regex.Matcher	messageMatcherIgnoreInternal
static java.lang.String	messageParserNotSet
static java.lang.String	messageUnmappedElementBlockInternal
protected java.util.Stack<java.lang.String>	tagStack The stack of tags encountered inside the tagged block (including the tagged block tag itself)

Constructor Summary

MappedHandler(IHasParserHandler parent, java.lang.String tag)
Convenience constructor.

MappedHandler(java.lang.String tag)
Creates a new mapped handler which is assigned to the specified tag.

MappedHandler(org.xml.sax.XMLReader parser, org.xml.sax.ContentHandler parent, java.lang.String tag)
Full control constructor.

MappedHandler(org.xml.sax.XMLReader parser, java.lang.String tag)
Creates a new mapped handler which uses the specified parser and is assigned to the specified tag.

Method Summary

protected void	checkParserSet() Throws an exception if the parser is not set.
void	clear() Clears the state of the handler.
protected void	clearLocal() Subclasses may override this method to add code to be invoked when clear() is called.
protected T	doGetElement() If subclasses intend to use the getElement() method, they should override this method to provide the code that constructs the object corresponding to the tagged block.
void	endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) Handle an end element.
void	endTaggedBlock(java.lang.String uri, java.lang.String localName, java.lang.String qName) This method is used to run when exiting a tagged block.
org.xml.sax.Locator	getDocumentLocator() Returns the document locator for this handler; may be null
T	getElement() Returns the object representing the data in the parsed tagged block.
java.util.Map<java.lang.String,org.xml.sax.ContentHandler>	getHandlerMappings() Returns the set of tag to handler mappings for this mapped handler.
org.xml.sax.ContentHandler	getParent() Returns the parent of this child handler.
org.xml.sax.XMLReader	getParser() Returns the parser for this handler.
java.lang.String	getTag() Returns the tag that is handled by this handler.
java.util.List<ITaggedBlockTaskHandler>	getTaggedBlockTasks() Returns the list of task handlers that are run when the tagged block is entered and exited.
protected void	handleUnmappedEndElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) Subclasses may override this method to handle end tags.
protected void	handleUnmappedStartElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs) Subclasses may override this method to handle unmapped start tags.
protected void	initHandlerMap(java.util.Map<java.lang.String,org.xml.sax.ContentHandler> map) Adds handlers to the element map.
boolean	isInsideTaggedBlock() Returns true if the handler currently thinks it is inside of its assigned tagged block.
protected void	reportWarning(java.lang.String message) Reports a warning.
boolean	reportWarnings() Returns true if the handler is currently reporting unmapped tags to the error handler (or to standard error, if no error handler is available).
void	setDocumentLocator(org.xml.sax.Locator locator)
void	setParent(org.xml.sax.ContentHandler parent) Sets the parent for this handler.
void	setParser(org.xml.sax.XMLReader parser) Sets the parser for this handler; may be set to null
void	setReportWarnings(boolean value) Sets whether the handler reports unampped tags to the error stream.
void	startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs) Handle a start element.
void	startTaggedBlock(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs) This method is used to run code when entering a tagged block.

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

characters, endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, 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

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

Field Detail

messageParserNotSet

public static final java.lang.String messageParserNotSet

See Also:

Constant Field Values

messageIgnoringElementBlockExternal

public static final java.lang.String messageIgnoringElementBlockExternal

See Also:

Constant Field Values

messageUnmappedElementBlockInternal

public static final java.lang.String messageUnmappedElementBlockInternal

See Also:

Constant Field Values

messageMatcherIgnoreExternal

protected static final java.util.regex.Matcher messageMatcherIgnoreExternal

messageMatcherIgnoreInternal

protected static final java.util.regex.Matcher messageMatcherIgnoreInternal

tagStack

protected java.util.Stack<java.lang.String> tagStack

The stack of tags encountered inside the tagged block (including the tagged block tag itself)

Since:

JVerbnet 1.0.0

Constructor Detail

MappedHandler

public MappedHandler(java.lang.String tag)

Creates a new mapped handler which is assigned to the specified tag. The parser and parent for this handler are set to null.

Parameters:

tag - the tag for this handler; may not be null, empty, or all whitespace; leading and trailing whitespace will be trimmed

Throws:

java.lang.NullPointerException - if the specified tag is null

java.lang.IllegalArgumentException - if the tag is empty or all whitespace

Since:

JVerbnet 1.0.0

MappedHandler

public MappedHandler(org.xml.sax.XMLReader parser,
                     java.lang.String tag)

Creates a new mapped handler which uses the specified parser and is assigned to the specified tag. The parent of this handler is set to null.

Parameters:

parser - the parser for this handler; may not be null

tag - the tag for this handler; may not be null, empty, or all whitespace; leading and trailing whitespace will be trimmed

Throws:

java.lang.NullPointerException - if the specified parser or tag is null

java.lang.IllegalArgumentException - if the tag is empty or all whitespace

Since:

JVerbnet 1.0.0

MappedHandler

public MappedHandler(IHasParserHandler parent,
                     java.lang.String tag)

Convenience constructor. Constructs a new handler with the specified parent, and the same parser as the parent.

Parameters:

parent - the parent of this handler, which has a parser

tag - the xml tag which this handler handles; may not be null, empty, or all whitespace

Throws:

java.lang.NullPointerException - if either parameter is null

java.lang.IllegalArgumentException - if the tag is empty or all whitespace

Since:

JVerbnet 1.0.0

MappedHandler

public MappedHandler(org.xml.sax.XMLReader parser,
                     org.xml.sax.ContentHandler parent,
                     java.lang.String tag)

Full control constructor. Constructs a new handler with the specified parser, parent, and tag.

Parameters:

parser - the parser for this handler

parent - the parent of this handler, which has a parser

tag - the xml tag which this handler handles; may not be null, empty, or all whitespace; the tag will be trimmed of extra whitespace.

Throws:

java.lang.NullPointerException - if either parameter is null

java.lang.IllegalArgumentException - if the tag is empty or all whitespace

Since:

JVerbnet 1.0.0

Method Detail

getParser

public org.xml.sax.XMLReader getParser()

Description copied from interface: IHasParserHandler

Returns the parser for this handler. May return null.

Specified by:

getParser in interface IHasParserHandler

Returns:

the possibly null parser for this handler

setParser

public void setParser(org.xml.sax.XMLReader parser)

Description copied from interface: IHasParserHandler

Sets the parser for this handler; may be set to null

Specified by:

setParser in interface IHasParserHandler

Parameters:

parser - the new parser for this handler; may be null

getParent

public org.xml.sax.ContentHandler getParent()

Returns the parent of this child handler. If the

Specified by:

getParent in interface ITaggedHandler<T>

Returns:

the non-null parent of this child handler

Since:

JVerbnet 1.0.0

checkParserSet

protected void checkParserSet()

Throws an exception if the parser is not set.

Throws:

java.lang.IllegalStateException - if this method is called and the parser is not set

Since:

JVerbnet 1.0.0

setParent

public void setParent(org.xml.sax.ContentHandler parent)

Description copied from interface: ITaggedHandler

Sets the parent for this handler. The new parent may be null

Specified by:

setParent in interface ITaggedHandler<T>

Parameters:

parent - the new parent for the handler; may be null

getTag

public java.lang.String getTag()

Description copied from interface: ITaggedHandler

Returns the tag that is handled by this handler. Will never be null or empty, and will be trimmed of leading and trailing whitespace.

Specified by:

getTag in interface ITaggedHandler<T>

Returns:

the non-null, non-empty, trimmed tag that is handled by this handler

reportWarnings

public boolean reportWarnings()

Returns true if the handler is currently reporting unmapped tags to the error handler (or to standard error, if no error handler is available).

Returns:

true if unmapped tags will be reported to the error stream; false otherwise

Since:

JVerbnet 1.0.0

setReportWarnings

public void setReportWarnings(boolean value)

Sets whether the handler reports unampped tags to the error stream.

Parameters:

value - true if the handler should report unmapped tags; false otherwise

Since:

JVerbnet 1.0.0

setDocumentLocator

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

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

Overrides:

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

getDocumentLocator

public org.xml.sax.Locator getDocumentLocator()

Returns the document locator for this handler; may be null

Returns:

the possibly null document locator for this handler

Since:

JVerbnet 1.0.0

getTaggedBlockTasks

public java.util.List<ITaggedBlockTaskHandler> getTaggedBlockTasks()

Description copied from interface: ITaggedHandler

Returns the list of task handlers that are run when the tagged block is entered and exited. The list may be modified. Tasks are run in order.

Specified by:

getTaggedBlockTasks in interface ITaggedHandler<T>

Returns:

the list of tasks to be run when entering and exiting the tagged block

getHandlerMappings

public final java.util.Map<java.lang.String,org.xml.sax.ContentHandler> getHandlerMappings()

Returns the set of tag to handler mappings for this mapped handler. This method is called a lot, so it should probably just return a pointer to a field that is constructed elsewhere (e.g., in the object constructor).

Returns:

the tag-to-handler map

Since:

JVerbnet 1.0.0

initHandlerMap

protected void initHandlerMap(java.util.Map<java.lang.String,org.xml.sax.ContentHandler> map)

Adds handlers to the element map. Subclasses may override this to provide handlers for different tags.

Parameters:

map - the map to which handlers should be added

Since:

JVerbnet 1.0.0

clear

public final void clear()

Description copied from interface: ITaggedHandler

Clears the state of the handler. This method should be called before control of the parser is passed to this handler.

Specified by:

clear in interface ITaggedHandler<T>

clearLocal

protected void clearLocal()

Subclasses may override this method to add code to be invoked when clear() is called.

Since:

JVerbnet 1.0.0

isInsideTaggedBlock

public boolean isInsideTaggedBlock()

Returns true if the handler currently thinks it is inside of its assigned tagged block.

Returns:

true if the handler currently thinks it is inside of its assigned tagged block; false otherwise

Since:

JVerbnet 1.0.0

startElement

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

Handle a start element. If the start element is assigned tag of this handler, and the handler is not already inside the assigned block, then enter the assigned block by running the startTaggedBlock(String, String, String, Attributes) method. Otherwise, try to find a mapped handler to handle the element.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

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

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

attrs - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined

Throws:

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

java.lang.IllegalStateException - if the parser has not been set when this method is called

Since:

JVerbnet 1.0.0

startTaggedBlock

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

Description copied from interface: ITaggedBlockTaskHandler

This method is used to run code when entering a tagged block.

Specified by:

startTaggedBlock in interface ITaggedBlockTaskHandler

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

attrs - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined

Throws:

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

handleUnmappedStartElement

protected void handleUnmappedStartElement(java.lang.String uri,
                                          java.lang.String localName,
                                          java.lang.String qName,
                                          org.xml.sax.Attributes attrs)
                                   throws org.xml.sax.SAXException

Subclasses may override this method to handle unmapped start tags.

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

attrs - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined

Throws:

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

Since:

JVerbnet 1.0.0

endElement

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

Handle an end element. If the end element is the end element of the assigned block, then exit the assigned block by running the endTaggedBlock(String, String, String) method. Otherwise, try to find a mapped handler to handle the element.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

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

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

Throws:

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

java.lang.IllegalStateException - if the parser has not been set when this method is called

Since:

JVerbnet 1.0.0

endTaggedBlock

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

Description copied from interface: ITaggedBlockTaskHandler

This method is used to run when exiting a tagged block.

Specified by:

endTaggedBlock in interface ITaggedBlockTaskHandler

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified XML name (with prefix), or the empty string if qualified names are not available

Throws:

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

handleUnmappedEndElement

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

Subclasses may override this method to handle end tags.

Parameters:

uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

Throws:

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

Since:

JVerbnet 1.0.0

reportWarning

protected void reportWarning(java.lang.String message)

Reports a warning. Tries to report the warning first to the parser's error handler, if any. If there is none, it reports the warning to System.err.

Parameters:

message - the message to report

Since:

JVerbnet 1.0.0

getElement

public T getElement()

Description copied from interface: ITaggedHandler

Returns the object representing the data in the parsed tagged block.

Specified by:

getElement in interface ITaggedHandler<T>

Returns:

the object representing the data in the parsed tagged block

doGetElement

protected T doGetElement()

If subclasses intend to use the getElement() method, they should override this method to provide the code that constructs the object corresponding to the tagged block.

Returns:

the object corresponding to the tagged block

Since:

JVerbnet 1.0.0