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    */
setContentHandler(ContentHandler handler)45   public void setContentHandler(ContentHandler handler);
46 
47   /**  Register a SAX-style lexical handler for us to output to
48    */
setLexicalHandler(org.xml.sax.ext.LexicalHandler handler)49   public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler);
50 
51   /**  Register a SAX-style DTD handler for us to output to
52    */
setDTDHandler(org.xml.sax.DTDHandler handler)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    * */
deliverMoreNodes(boolean parsemore)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    * */
startParse(InputSource source)87   public void startParse(InputSource source) throws SAXException;
88 
89 } // class IncrementalSAXSource
90