Package ca.gorman.xml.parse.toolkit

Toolkit for implementing XML stream parser on event-based parsers like the SAX parser.

See:
Description

Interface Summary

ElementStack<T extends Parser>	Stack of the elements that are currently being processed.
EntityStack<T extends Parser>	Stack of the entities that are currently being processed.

Class Summary

AbstractAttribute	Abstract realization of Attribute.
AbstractCharSequence	Character source for Listener methods that receive character input from the Parser.
AbstractElement	Abstract realization of Element.
AbstractEntity	Abstract realization of Entity.
Coroutine	Extends Thread to support a coroutine thread that shares and exchanges control with a main thread.
Coroutine_Callback<T extends Parser>	Base class for invoking Listener methods that call back to the Parser.
Coroutine_NoCallback<T extends Parser>	Base class for invoking Listener methods that do not call back to the Parser.
CoroutineAttributeDecl<T extends Parser>	Invokes attribute declaration handler from the parser thread to run in the application thread.
CoroutineCdata<T extends Parser>	Invokes CDATA marked section handler from the parser thread to run in the application thread.
CoroutineCharacters<T extends Parser>	Invokes character handler from the parser thread to run in the application thread.
CoroutineCheckListener<T extends Parser>	Checks whether a Coroutine-based Parser implementation invokes all of the Listener methods in the correct thread.
CoroutineComment<T extends Parser>	Invokes comment handler from the parser thread to run in the application thread.
CoroutineDocument<T extends Parser>	Invokes document handler from the parser thread to run in the application thread.
CoroutineDtd<T extends Parser>	Invokes DTD handler from the parser thread to run in the application thread.
CoroutineElement<T extends Parser>	Invokes element handler from the parser thread to run in the application thread.
CoroutineElementDecl<T extends Parser>	Invokes element declaration handler from the parser thread to run in the application thread.
CoroutineElementStack<T extends Parser>	Element stack implemented for coroutine parser.
CoroutineEndPrefixMapping<T extends Parser>	Invokes end prefix mapping handler from the parser thread to run in the application thread (still under development, design may change).
CoroutineEntity<T extends Parser>	Invokes entity handler from the parser thread to run in the application thread.
CoroutineEntityStack<T extends Parser>	Entity stack implemented for coroutine parser.
CoroutineError<T extends Parser>	Invokes error declaration handler from the parser thread to run in the application thread.
CoroutineExternalEntityDecl<T extends Parser>	Invokes external entity declaration handler from the parser thread to run in the application thread.
CoroutineFatalError<T extends Parser>	Invokes fatalError declaration handler from the parser thread to run in the application thread.
CoroutineGetExternalSubset<T extends Parser>	Invokes resolve entity handler from the parser thread to run in the application thread.
CoroutineIgnorableWhitespace<T extends Parser>	Invokes ignorable whitespace handler from the parser thread to run in the application thread.
CoroutineInternalEntityDecl<T extends Parser>	Invokes internal entity declaration handler from the parser thread to run in the application thread.
CoroutineNotationDecl<T extends Parser>	Invokes notation declaration handler from the parser thread to run in the application thread.
CoroutineProcessingInstruction<T extends Parser>	Invokes processing instruction handler from the parser thread to run in the application thread.
CoroutineResolveEntity<T extends Parser>	Invokes resolve entity handler from the parser thread to run in the application thread.
CoroutineSkippedEntity<T extends Parser>	Invokes skipped entity handler from the parser thread to run in the application thread.
CoroutineStartPrefixMapping<T extends Parser>	Invokes start prefix mapping handler from the parser thread to run in the application thread (still under development, design may change).
CoroutineUnparsedEntityDecl<T extends Parser>	Invokes unparsed entity declaration handler from the parser thread to run in the application thread.
CoroutineWarning<T extends Parser>	Invokes warning declaration handler from the parser thread to run in the application thread.
MutableAttribute	Constructable and mutable realization of Attribute.
MutableElement	Constructable and mutable realization of Element.
MutableEntity	Constructable and mutable realization of Entity.

Exception Summary

CoroutineRuntimeException	Base class for coroutine unchecked exceptions.
CoroutineTransferException	Unchecked exception for transferring checked exceptions between coroutines.

Package ca.gorman.xml.parse.toolkit Description

Toolkit for implementing XML stream parser on event-based parsers like the SAX parser.

The Coroutine classes are designed for parsers (like David Megginson's SAX parser and James Clark's SP parser) that identify the boundaries of XML objects and report those boundaries as (possibly nested) pairs of start and end events. The Coroutine classes support the conversion of each start-end pair into a single method invocation that presents an XML object for processing. Nested pairs, representing a hierarchy of objects become nested method invocations, the outer method being suspended while the inner method executes and continuing when the inner method returns. Application programmers do not have to keep track of where they are in the document structure, because this is implicit in the way methods are invoked, and a stack of open elements is maintained.

All application code runs in a main thread, properly serialized with a second thread that runs the underlying parser. For most applications, this means that code can be written as if running in a single thread.

The following example, based on nested XML elements and corresponding handlers, shows how a stack of five nested elements, with characters in the innermost element, would be notified from a SAX parser running in a "coroutine" thread, and and processed by application code (written for the Listener interface) running in a "main" thread. The SAX parser invokes an element start notification in the coroutine thread, causing the element method to be invoked in the main thread.. The element method invokes parseContent() to return control to the SAX parser, running in the coroutine thread. At the end of the element, the SAX parser invokes an element end notification, which returns to the element method, running in the main thread. The element method finishes its work and exits, thereby returning control to the parser.

Application         SAX Parser Thread
Thread
                    main suspends itself after starting coroutine
<a "depth=1">       coroutine invokes a in main thread
 <b "depth=2">      a suspends itself, coroutine invokes b in main thread
  <c "depth=3">     b suspends itself, coroutine invokes c in main thread
   <d "depth=4">    c suspends itself, coroutine invokes d in main thread
    <e "depth=5">   d suspends itself, coroutine invokes e in main thread
     characters   e suspends itself, coroutine invokes characters in main thread
    </e>            characters returns, coroutine allows e to resume
   </d>             e returns, coroutine allows d to resume
  </c>              d returns, coroutine allows c to resume
 </b>               c returns, coroutine allows b to resume
</a>                b returns, coroutine allows a to resume
                    a returns, coroutine resumes.
                    coroutine terminates, main resumes

Since all of the application code runs in the "main" thread, the application code can be written as if there were only one thread running, provided that the designer is aware of the sequence of execution within nested handler methods.

Package ca.gorman.xml.parse.sax illustrates how to use Coroutine and the other classes in this package to implement the Listener and Parser interfaces on a SAX parser.

Package Specification

Packages ca.gorman.xml.parse and ca.gorman.xml.parse.toolkit can support a Listener interface on the following event-based parsers:

• The SAX parser
• James Clark's parsers

Related Documentation

See Also:

ca.gorman.xml.parse, ca.gorman.xml.parse.sax