libcore/luni/src/main/java/org/apache/xml/dtm/ref/IncrementalSAXSource.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements. See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership. The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the  "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 /*
  19  * $Id: IncrementalSAXSource.java 468653 2006-10-28 07:07:05Z minchau $
  20  */
  21
  22 package org.apache.xml.dtm.ref;
  23
  24 import org.xml.sax.ContentHandler;
  25 import org.xml.sax.InputSource;
  26 import org.xml.sax.SAXException;
  27
  28 /** <p>IncrementalSAXSource is an API that delivers a small number of
  29  * SAX events each time a request is made from a "controller"
  30  * coroutine.  See IncrementalSAXFilter and IncrementalSAXFilter_Xerces
  31  * for examples.
  32  *
  33  * Note that interaction is via the deliverMoreNodes
  34  * method, and therefore coroutine support is not exposed
  35  * here.</p>
  36  * */
  37 public interface IncrementalSAXSource
  38 {
  39   // ------------------------------------------------------------------
  40   // SAX Output API
  41   // ------------------------------------------------------------------
  42
  43   /** Register a SAX-style content handler for us to output to
  44    */
  45   public void setContentHandler(ContentHandler handler);
  46
  47   /**  Register a SAX-style lexical handler for us to output to
  48    */
  49   public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler);
  50
  51   /**  Register a SAX-style DTD handler for us to output to
  52    */
  53   public void setDTDHandler(org.xml.sax.DTDHandler handler);
  54
  55   // ------------------------------------------------------------------
  56   // Command Input API
  57   // ------------------------------------------------------------------
  58
  59   /** deliverMoreNodes() is a simple API which tells the thread in which the
  60    * IncrementalSAXSource is running to deliver more events (true),
  61    * or stop delivering events and close out its input (false).
  62    *
  63    * This is intended to be called from one of our partner coroutines,
  64    * and serves to encapsulate the coroutine communication protocol.
  65    *
  66    * @param parsemore If true, tells the incremental SAX stream to deliver
  67    * another chunk of events. If false, finishes out the stream.
  68    *
  69    * @return Boolean.TRUE if the IncrementalSAXSource believes more data
  70    * may be available for further parsing. Boolean.FALSE if parsing
  71    * ran to completion, or was ended by deliverMoreNodes(false).
  72    * */
  73   public Object deliverMoreNodes (boolean parsemore);
  74
  75   // ------------------------------------------------------------------
  76   // Parse Thread Convenience API
  77   // ------------------------------------------------------------------
  78
  79   /** Launch an XMLReader's parsing operation, feeding events to this
  80    * IncrementalSAXSource. In some implementations, this may launch a
  81    * thread which runs the previously supplied XMLReader's parse() operation.
  82    * In others, it may do other forms of initialization.
  83    *
  84    * @throws SAXException is parse thread is already in progress
  85    * or parsing can not be started.
  86    * */
  87   public void startParse(InputSource source) throws SAXException;
  88
  89 } // class IncrementalSAXSource