Package org.apache.xml.dtm.ref

Class IncrementalSAXSource_Filter

  • All Implemented Interfaces:
    java.lang.Runnable, IncrementalSAXSource, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.ErrorHandler, org.xml.sax.ext.LexicalHandler
    public class IncrementalSAXSource_Filter
extends java.lang.Object
implements IncrementalSAXSource, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.ext.LexicalHandler, org.xml.sax.ErrorHandler, java.lang.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 Detail

      • IncrementalSAXSource_Filter

        public IncrementalSAXSource_Filter()

      • IncrementalSAXSource_Filter

        public IncrementalSAXSource_Filter​(CoroutineManager co,
                                   int controllerCoroutineID)
        Create a IncrementalSAXSource_Filter which is not yet bound to a specific SAX event source.

    • Method Detail

      • init

        public void init​(CoroutineManager co,
                 int controllerCoroutineID,
                 int sourceCoroutineID)

      • setXMLReader

        public void setXMLReader​(org.xml.sax.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.

      • setErrHandler

        public void setErrHandler​(org.xml.sax.ErrorHandler handler)

      • setReturnFrequency

        public void setReturnFrequency​(int events)

      • characters

        public void characters​(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException
        Specified by:
        characters in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • endDocument

        public void endDocument()
                 throws org.xml.sax.SAXException
        Specified by:
        endDocument in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • endElement

        public void endElement​(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException
        Specified by:
        endElement in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • endPrefixMapping

        public void endPrefixMapping​(java.lang.String prefix)
                      throws org.xml.sax.SAXException
        Specified by:
        endPrefixMapping in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • ignorableWhitespace

        public void ignorableWhitespace​(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException
        Specified by:
        ignorableWhitespace in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • processingInstruction

        public void processingInstruction​(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException
        Specified by:
        processingInstruction in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • setDocumentLocator

        public void setDocumentLocator​(org.xml.sax.Locator locator)
        Specified by:
        setDocumentLocator in interface org.xml.sax.ContentHandler

      • skippedEntity

        public void skippedEntity​(java.lang.String name)
                   throws org.xml.sax.SAXException
        Specified by:
        skippedEntity in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • startDocument

        public void startDocument()
                   throws org.xml.sax.SAXException
        Specified by:
        startDocument in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • startElement

        public void startElement​(java.lang.String namespaceURI,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
                  throws org.xml.sax.SAXException
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • startPrefixMapping

        public void startPrefixMapping​(java.lang.String prefix,
                               java.lang.String uri)
                        throws org.xml.sax.SAXException
        Specified by:
        startPrefixMapping in interface org.xml.sax.ContentHandler
        Throws:
        org.xml.sax.SAXException

      • comment

        public void comment​(char[] ch,
                    int start,
                    int length)
             throws org.xml.sax.SAXException
        Specified by:
        comment in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • endCDATA

        public void endCDATA()
              throws org.xml.sax.SAXException
        Specified by:
        endCDATA in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • endDTD

        public void endDTD()
            throws org.xml.sax.SAXException
        Specified by:
        endDTD in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • endEntity

        public void endEntity​(java.lang.String name)
               throws org.xml.sax.SAXException
        Specified by:
        endEntity in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • startCDATA

        public void startCDATA()
                throws org.xml.sax.SAXException
        Specified by:
        startCDATA in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • startDTD

        public void startDTD​(java.lang.String name,
                     java.lang.String publicId,
                     java.lang.String systemId)
              throws org.xml.sax.SAXException
        Specified by:
        startDTD in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • startEntity

        public void startEntity​(java.lang.String name)
                 throws org.xml.sax.SAXException
        Specified by:
        startEntity in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException

      • notationDecl

        public void notationDecl​(java.lang.String a,
                         java.lang.String b,
                         java.lang.String c)
                  throws org.xml.sax.SAXException
        Specified by:
        notationDecl in interface org.xml.sax.DTDHandler
        Throws:
        org.xml.sax.SAXException

      • unparsedEntityDecl

        public void unparsedEntityDecl​(java.lang.String a,
                               java.lang.String b,
                               java.lang.String c,
                               java.lang.String d)
                        throws org.xml.sax.SAXException
        Specified by:
        unparsedEntityDecl in interface org.xml.sax.DTDHandler
        Throws:
        org.xml.sax.SAXException

      • error

        public void error​(org.xml.sax.SAXParseException exception)
           throws org.xml.sax.SAXException
        Specified by:
        error in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException

      • fatalError

        public void fatalError​(org.xml.sax.SAXParseException exception)
                throws org.xml.sax.SAXException
        Specified by:
        fatalError in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException

      • warning

        public void warning​(org.xml.sax.SAXParseException exception)
             throws org.xml.sax.SAXException
        Specified by:
        warning in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException

      • getSourceCoroutineID

        public int getSourceCoroutineID()

      • getControllerCoroutineID

        public int getControllerCoroutineID()

      • getCoroutineManager

        public CoroutineManager getCoroutineManager()
        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.

      • startParse

        public void startParse​(org.xml.sax.InputSource source)
                throws org.xml.sax.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.
        Specified by:
        startParse in interface IncrementalSAXSource
        Throws:
        org.xml.sax.SAXException - is parse thread is already in progress or parsing can not be started.

      • run

        public void run()
        Specified by:
        run in interface java.lang.Runnable

      • deliverMoreNodes

        public java.lang.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.
        Specified by:
        deliverMoreNodes in interface IncrementalSAXSource
        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.