001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: IncrementalSAXSource.java 468653 2006-10-28 07:07:05Z minchau $
020 */
021
022 package org.apache.xml.dtm.ref;
023
024 import org.xml.sax.ContentHandler;
025 import org.xml.sax.InputSource;
026 import org.xml.sax.SAXException;
027
028 /** <p>IncrementalSAXSource is an API that delivers a small number of
029 * SAX events each time a request is made from a "controller"
030 * coroutine. See IncrementalSAXFilter and IncrementalSAXFilter_Xerces
031 * for examples.
032 *
033 * Note that interaction is via the deliverMoreNodes
034 * method, and therefore coroutine support is not exposed
035 * here.</p>
036 * */
037 public interface IncrementalSAXSource
038 {
039 // ------------------------------------------------------------------
040 // SAX Output API
041 // ------------------------------------------------------------------
042
043 /** Register a SAX-style content handler for us to output to
044 */
045 public void setContentHandler(ContentHandler handler);
046
047 /** Register a SAX-style lexical handler for us to output to
048 */
049 public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler);
050
051 /** Register a SAX-style DTD handler for us to output to
052 */
053 public void setDTDHandler(org.xml.sax.DTDHandler handler);
054
055 // ------------------------------------------------------------------
056 // Command Input API
057 // ------------------------------------------------------------------
058
059 /** deliverMoreNodes() is a simple API which tells the thread in which the
060 * IncrementalSAXSource is running to deliver more events (true),
061 * or stop delivering events and close out its input (false).
062 *
063 * This is intended to be called from one of our partner coroutines,
064 * and serves to encapsulate the coroutine communication protocol.
065 *
066 * @param parsemore If true, tells the incremental SAX stream to deliver
067 * another chunk of events. If false, finishes out the stream.
068 *
069 * @return Boolean.TRUE if the IncrementalSAXSource believes more data
070 * may be available for further parsing. Boolean.FALSE if parsing
071 * ran to completion, or was ended by deliverMoreNodes(false).
072 * */
073 public Object deliverMoreNodes (boolean parsemore);
074
075 // ------------------------------------------------------------------
076 // Parse Thread Convenience API
077 // ------------------------------------------------------------------
078
079 /** Launch an XMLReader's parsing operation, feeding events to this
080 * IncrementalSAXSource. In some implementations, this may launch a
081 * thread which runs the previously supplied XMLReader's parse() operation.
082 * In others, it may do other forms of initialization.
083 *
084 * @throws SAXException is parse thread is already in progress
085 * or parsing can not be started.
086 * */
087 public void startParse(InputSource source) throws SAXException;
088
089 } // class IncrementalSAXSource