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