com.programix.saxplus
Interface TagHandler

All Known Implementing Classes:

BaseTagHandler, SimpleTagHandler

public interface TagHandler

All information about the parsing of the XML document is passed to TagHandler's by the SAXPlusProcessor.

The processing flow:

1. The startTag()method is called first passing in the name of the tag (TagHandlers don't necessarily know their own name).
2. The text()method is called for text (if any) within this tag.
1. If the tag is empty, contains only white space (no sub tags), or has only sub tags (with only whitespace between them), then text() is never called.
2. If the tag contains a mixture of text and sub tags, then text()will be called once for each block of (non-whitespace) text found between the sub tags.
3. If a sub tag is encountered, startSubTag()is called to determine the TagHandler for the sub tag. When the sub tag is complete, endSubTag()is called.
4. When this tag is complete, endTag()is called. After that, getResult()may (or may not) be called.
5. Finally, this sequence will repeat if more data arrives for this handler.

All of these methods potentially throw SAXException to indicate a problem in processing the data. If a RuntimeException is thrown from any of these methods, it will be automatically wrapped in a SAXException and that wrapped exception will be throw by SAXPlusProcessor.

Author:

Paul Hyde

Method Summary

void	endSubTag(NameDetail subTagName, Value subTagResult) Called after a sub tag has completed.
void	endTag()
Value	getResult() Called after endTag()to retrieve the results of the processing of this tag (and all of its sub tags).
TagHandler	startSubTag(NameDetail subTagName) Returns the handler for the sub tag.
void	startTag(NameDetail tagName, AttributeGroup attr)
void	text(Value tagText) Delivers textual content within this tag.

Method Detail

startTag

void startTag(NameDetail tagName,
              AttributeGroup attr)
              throws SAXException

Throws:

SAXException

endTag

void endTag()
            throws SAXException

Throws:

SAXException

text

void text(Value tagText)
          throws SAXException

Delivers textual content within this tag. If this tag has no sub tags, then this method is called at most once. If this tag is empty or has no text other than whitespace, this method is not called. If this tag has sub tags and only whitespace between the sub tags, this method is not called. If there is a mixture of (non-whitespace) text and sub tags, this method is called multiple times.

For example:

 <apple>
     <excellent>Red Delicious</excellent>
     <good>Granny Smith</good>
 </apple>
 <fresh value="yes" />
 <mango>
      </mango>
 <story>They are <bold>very</bold> tasty.</story>
 

The text() method is called:

• exactly one time for excellent (no sub tags).
• never for apple (only sub tags and whitespace).
• never for fresh (empty element).
• never for mango (only whitespace).
• two times for story (once for "They are " and a second time for " tasty." ["very" is passed to the text() for the tag handler for bold, not for story.]

Throws:

SAXException

startSubTag

TagHandler startSubTag(NameDetail subTagName)
                       throws SAXException

Returns the handler for the sub tag. Returns null if there is not a handler for this sub tag.

Throws:

SAXException

endSubTag

void endSubTag(NameDetail subTagName,
               Value subTagResult)
               throws SAXException

Called after a sub tag has completed.

Throws:

SAXException

getResult

Value getResult()
                throws SAXException

Called after endTag()to retrieve the results of the processing of this tag (and all of its sub tags).

Returns:

the value calculated, never null.

Throws:

SAXException - if the result can not be assembled (e.g. a required piece of data is missing).