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