com.simonstl.midp.tam
Interface TamHandler

All Known Implementing Classes:
TAMHandlerImpl

public interface TamHandler

The Tiny API for Markup (TAM) provides a very small interface for parsing XML and similar documents. TAM is designed to report pretty much everything the parser encounters, leaving it to applications to do some work (notably DTD interpretation) if they need it.

TAM is based on a subset of SAX2, which is then slightly expanded. TAM is not a proper drop-in replacement for SAX - it uses similar method calls, and a similar approach, but it's been reduced to meet the needs of even smaller projects, and expanded slightly to reflect that TAM parsers are not required to process the DTD.

TAM is deliberately small and is not intended to be extensible. It should be possible for applications to use the information provided here to extend its functionality toward complete support for XML 1.0, but such work is left as an exercise for the application.

CDATA section and comment support is provided per the SAX2 ext lexical handler.

Author:
Simon St.Laurent (simonstl@simonstl.com)

Method Summary
 void characters(char[] buf, int offset, int length)
          The characters() method behaves like its SAX2 equivalent.
 void comment(char[] ch, int start, int length)
          The comment() method behaves like its SAX2 ext LexicalHandler equivalent.
 void doctype(char[] buf, int offset, int length)
          This event provides applications with the complete contents of the DOCTYPE declaration.
 void endCDATA()
          The endCDATA() method behaves like its SAX2 ext LexicalHandler equivalent.
 void endDocument()
          This event is called at the end of parsing, just like its SAX2 counterpart.
 void endElement(java.lang.String uri, java.lang.String localName, java.lang.String prefix)
          endElement behaves like SAX2, except that it reports the prefix rather than the QName.
 void error(TAMException x)
          The error() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.
 void fatalError(TAMException x)
          The fatalError() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.
 void processingInstruction(java.lang.String target, java.lang.String data)
          The processingInstruction() method behaves like its SAX2 equivalent.
 void skippedEntity(java.lang.String name)
          Because TAM-based parsers aren't required to read the DTD, all entities other than the built-in entities (lt, gt, apos, and quot) will be reported as skipped entities.
 void startCDATA()
          The startCDATA() method behaves like its SAX2 ext LexicalHandler equivalent.
 void startDocument()
          This event is called at the beginning of parsing, just like its SAX2 counterpart.
 void startElement(java.lang.String uri, java.lang.String localName, java.lang.String prefix, TamAttributes attributes)
          startElement behaves like SAX2 except that it reports the prefix rather than the QName.
 void warning(TAMException x)
          The warning() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.
 void XMLDecl(java.lang.String version, java.lang.String encoding, java.lang.String standalone)
          The XMLDecl method is new, and may be useful to applications who need to know if the encoding used by a given document is supported by their environment.
 

Method Detail

startDocument

public void startDocument()
                   throws TAMException
This event is called at the beginning of parsing, just like its SAX2 counterpart.

endDocument

public void endDocument()
                 throws TAMException
This event is called at the end of parsing, just like its SAX2 counterpart. It's especially useful if you need to capture events after the root element has completed.

doctype

public void doctype(char[] buf,
                    int offset,
                    int length)
             throws TAMException
This event provides applications with the complete contents of the DOCTYPE declaration. As TAM-based parsers may not have the space to keep these declarations around, the application is given the option of such processing. Note that this approach is a fundamental change to the division of responsibilities that XML 1.0 establishes between applications and parsers. All DTD work is now the responsibility of the application, not the parser, including default values for attributes and entity processing.

startElement

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String prefix,
                         TamAttributes attributes)
                  throws TAMException
startElement behaves like SAX2 except that it reports the prefix rather than the QName. There is no "namespaces on or off" setting - if an element or attribute lacks a namespace, it is reported as an empty string. Local names and qNames are both always reported.

endElement

public void endElement(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String prefix)
                throws TAMException
endElement behaves like SAX2, except that it reports the prefix rather than the QName. There is no "namespaces on or off" setting - if an element or attribute lacks a namespace, it is reported as an empty string. Local names and prefixes are both always reported.

characters

public void characters(char[] buf,
                       int offset,
                       int length)
                throws TAMException
The characters() method behaves like its SAX2 equivalent. Applications should be cautious in making sure that they collect all the character events that collectively make up a single "text node", as TAM-based parsers are likely to report lots of fragments because of buffering and entity handling.

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws TAMException
The processingInstruction() method behaves like its SAX2 equivalent.

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws TAMException
The comment() method behaves like its SAX2 ext LexicalHandler equivalent.

startCDATA

public void startCDATA()
                throws TAMException
The startCDATA() method behaves like its SAX2 ext LexicalHandler equivalent.

endCDATA

public void endCDATA()
              throws TAMException
The endCDATA() method behaves like its SAX2 ext LexicalHandler equivalent.

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws TAMException
Because TAM-based parsers aren't required to read the DTD, all entities other than the built-in entities (lt, gt, apos, and quot) will be reported as skipped entities.

error

public void error(TAMException x)
           throws TAMException
The error() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.

fatalError

public void fatalError(TAMException x)
                throws TAMException
The fatalError() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.

warning

public void warning(TAMException x)
             throws TAMException
The warning() method behaves like its SAX2 equivalent except that it uses TAMExceptions instead of SAXExceptions.

XMLDecl

public void XMLDecl(java.lang.String version,
                    java.lang.String encoding,
                    java.lang.String standalone)
The XMLDecl method is new, and may be useful to applications who need to know if the encoding used by a given document is supported by their environment. (J2ME is much more limited in this regard than J2SE, despite using Unicode internally.)