IncrementalSAXSource_Filter implements IncrementalSAXSource, using a
standard SAX2 event source as its input and parcelling out those
events gradually in reponse to deliverMoreNodes() requests. Output from the
filter will be passed along to a SAX handler registered as our
listener, but those callbacks will pass through a counting stage
which periodically yields control back to the controller coroutine.
%REVIEW%: This filter is not currenly intended to be reusable
for parsing additional streams/documents. We may want to consider
making it resettable at some point in the future. But it's a
small object, so that'd be mostly a convenience issue; the cost
of allocating each time is trivial compared to the cost of processing
any nontrival stream.
For a brief usage example, see the unit-test main() method.
This is a simplification of the old CoroutineSAXParser, focusing
specifically on filtering. The resulting controller protocol is _far_
simpler and less error-prone; the only controller operation is deliverMoreNodes(),
and the only requirement is that deliverMoreNodes(false) be called if you want to
discard the rest of the stream and the previous deliverMoreNodes() didn't return
false.
characters
public void characters(char[] ch,
int start,
int length)
throws org.xml.sax.SAXException
comment
public void comment(char[] ch,
int start,
int length)
throws org.xml.sax.SAXException
deliverMoreNodes
public Object deliverMoreNodes(boolean parsemore)
deliverMoreNodes() is a simple API which tells the coroutine
parser that we need more nodes. This is intended to be called
from one of our partner routines, and serves to encapsulate the
details of how incremental parsing has been achieved.
- deliverMoreNodes in interface IncrementalSAXSource
parsemore
- If true, tells the incremental filter to generate
another chunk of output. If false, tells the filter that we're
satisfied and it can terminate parsing of this document.
- Boolean.TRUE if there may be more events available by invoking
deliverMoreNodes() again. Boolean.FALSE if parsing has run to completion (or been
terminated by deliverMoreNodes(false). Or an exception object if something
malfunctioned. %REVIEW% We _could_ actually throw the exception, but
that would require runinng deliverMoreNodes() in a try/catch... and for many
applications, exception will be simply be treated as "not TRUE" in
any case.
endCDATA
public void endCDATA()
throws org.xml.sax.SAXException
endDTD
public void endDTD()
throws org.xml.sax.SAXException
endDocument
public void endDocument()
throws org.xml.sax.SAXException
endElement
public void endElement(String namespaceURI,
String localName,
String qName)
throws org.xml.sax.SAXException
endEntity
public void endEntity(String name)
throws org.xml.sax.SAXException
endPrefixMapping
public void endPrefixMapping(String prefix)
throws org.xml.sax.SAXException
error
public void error(SAXParseException exception)
throws SAXException
fatalError
public void fatalError(SAXParseException exception)
throws SAXException
getControllerCoroutineID
public int getControllerCoroutineID()
getCoroutineManager
public CoroutineManager getCoroutineManager()
- the CoroutineManager this CoroutineFilter object is bound to.
If you're using the do...() methods, applications should only
need to talk to the CoroutineManager once, to obtain the
application's Coroutine ID.
getSourceCoroutineID
public int getSourceCoroutineID()
ignorableWhitespace
public void ignorableWhitespace(char[] ch,
int start,
int length)
throws org.xml.sax.SAXException
init
public void init(CoroutineManager co,
int controllerCoroutineID,
int sourceCoroutineID)
notationDecl
public void notationDecl(String a,
String b,
String c)
throws SAXException
processingInstruction
public void processingInstruction(String target,
String data)
throws org.xml.sax.SAXException
setDTDHandler
public void setDTDHandler(DTDHandler handler)
setDocumentLocator
public void setDocumentLocator(Locator locator)
setErrHandler
public void setErrHandler(ErrorHandler handler)
setLexicalHandler
public void setLexicalHandler(LexicalHandler handler)
setReturnFrequency
public void setReturnFrequency(int events)
setXMLReader
public void setXMLReader(XMLReader eventsource)
Bind our input streams to an XMLReader.
Just a convenience routine; obviously you can explicitly register
this as a listener with the same effect.
skippedEntity
public void skippedEntity(String name)
throws org.xml.sax.SAXException
startCDATA
public void startCDATA()
throws org.xml.sax.SAXException
startDTD
public void startDTD(String name,
String publicId,
String systemId)
throws org.xml.sax.SAXException
startDocument
public void startDocument()
throws org.xml.sax.SAXException
startElement
public void startElement(String namespaceURI,
String localName,
String qName,
Attributes atts)
throws org.xml.sax.SAXException
startEntity
public void startEntity(String name)
throws org.xml.sax.SAXException
startParse
public void startParse(InputSource source)
throws SAXException
Launch a thread that will run an XMLReader's parse() operation within
a thread, feeding events to this IncrementalSAXSource_Filter. Mostly a convenience
routine, but has the advantage that -- since we invoked parse() --
we can halt parsing quickly via a StopException rather than waiting
for the SAX stream to end by itself.
- startParse in interface IncrementalSAXSource
startPrefixMapping
public void startPrefixMapping(String prefix,
String uri)
throws org.xml.sax.SAXException
unparsedEntityDecl
public void unparsedEntityDecl(String a,
String b,
String c,
String d)
throws SAXException
warning
public void warning(SAXParseException exception)
throws SAXException