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
22package org.apache.xml.dtm.ref;
23
24import org.xml.sax.ContentHandler;
25import org.xml.sax.InputSource;
26import 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 * */
37public 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
90