org.apache.xml.dtm.ref
public class IncrementalSAXSource_Filter extends Object implements IncrementalSAXSource, ContentHandler, DTDHandler, LexicalHandler, ErrorHandler, Runnable
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.
Constructor Summary | |
---|---|
IncrementalSAXSource_Filter() | |
IncrementalSAXSource_Filter(CoroutineManager co, int controllerCoroutineID) Create a IncrementalSAXSource_Filter which is not yet bound to a specific
SAX event source.
|
Method Summary | |
---|---|
void | characters(char[] ch, int start, int length) |
void | comment(char[] ch, int start, int length) |
static IncrementalSAXSource | createIncrementalSAXSource(CoroutineManager co, int controllerCoroutineID) |
Object | deliverMoreNodes(boolean parsemore) deliverMoreNodes() is a simple API which tells the coroutine
parser that we need more nodes. |
void | endCDATA() |
void | endDocument() |
void | endDTD() |
void | endElement(String namespaceURI, String localName, String qName) |
void | endEntity(String name) |
void | endPrefixMapping(String prefix) |
void | error(SAXParseException exception) |
void | fatalError(SAXParseException exception) |
int | getControllerCoroutineID() |
CoroutineManager | getCoroutineManager() |
int | getSourceCoroutineID() |
void | ignorableWhitespace(char[] ch, int start, int length) |
void | init(CoroutineManager co, int controllerCoroutineID, int sourceCoroutineID) |
void | notationDecl(String a, String b, String c) |
void | processingInstruction(String target, String data) |
void | run() |
void | setContentHandler(ContentHandler handler) |
void | setDocumentLocator(Locator locator) |
void | setDTDHandler(DTDHandler handler) |
void | setErrHandler(ErrorHandler handler) |
void | setLexicalHandler(LexicalHandler handler) |
void | setReturnFrequency(int events) |
void | setXMLReader(XMLReader eventsource) Bind our input streams to an XMLReader.
|
void | skippedEntity(String name) |
void | startCDATA() |
void | startDocument() |
void | startDTD(String name, String publicId, String systemId) |
void | startElement(String namespaceURI, String localName, String qName, Attributes atts) |
void | startEntity(String name) |
void | startParse(InputSource source) Launch a thread that will run an XMLReader's parse() operation within
a thread, feeding events to this IncrementalSAXSource_Filter. |
void | startPrefixMapping(String prefix, String uri) |
void | unparsedEntityDecl(String a, String b, String c, String d) |
void | warning(SAXParseException exception) |
Parameters: 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.
Returns: 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.
Returns: 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.
Throws: SAXException is parse thread is already in progress or parsing can not be started.