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: CoroutineParser.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.XMLReader;
027
028 /** <p>CoroutineParser is an API for parser threads that operate as
029 * coroutines. See CoroutineSAXParser and CoroutineSAXParser_Xerces
030 * for examples.</p>
031 *
032 * <p><grumble> I'd like the interface to require a specific form
033 * for either the base constructor or a static factory method. Java
034 * doesn't allow us to specify either, so I'll just document them
035 * here:
036 *
037 * <ul>
038 * <li>public CoroutineParser(CoroutineManager co, int appCoroutine);</li>
039 * <li>public CoroutineParser createCoroutineParser(CoroutineManager co, int appCoroutine);</li>
040 * </ul>
041 *
042 * </grumble></p>
043 *
044 * @deprecated Since the ability to start a parse via the
045 * coroutine protocol was not being used and was complicating design.
046 * See {@link IncrementalSAXSource}.
047 * */
048 public interface CoroutineParser {
049
050 /** @return the coroutine ID number for this CoroutineParser object.
051 * Note that this isn't useful unless you know which CoroutineManager
052 * you're talking to. Also note that the do...() methods encapsulate
053 * the common transactions with the CoroutineParser, so you shouldn't
054 * need this in most cases.
055 * */
056 public int getParserCoroutineID();
057
058 /** @return the CoroutineManager for this CoroutineParser object.
059 * If you're using the do...() methods, applications should only
060 * need to talk to the CoroutineManager once, to obtain the
061 * application's Coroutine ID.
062 * */
063 public CoroutineManager getCoroutineManager();
064
065 /** Register a SAX-style content handler for us to output to */
066 public void setContentHandler(ContentHandler handler);
067
068 /** Register a SAX-style lexical handler for us to output to
069 * Not all parsers support this...
070 *
071 * %REVIEW% Not called setLexicalHandler because Xalan uses that name
072 * internally, which causes subclassing nuisances.
073 */
074 public void setLexHandler(org.xml.sax.ext.LexicalHandler handler);
075
076 /* The run() method is required in CoroutineParsers that run as
077 * threads (of course)... but it isn't part of our API, and
078 * shouldn't be declared here.
079 * */
080
081 //================================================================
082 /** doParse() is a simple API which tells the coroutine parser
083 * to begin reading from a file. This is intended to be called from one
084 * of our partner coroutines, and serves both to encapsulate the
085 * communication protocol and to avoid having to explicitly use the
086 * CoroutineParser's coroutine ID number.
087 *
088 * %REVIEW% Can/should this unify with doMore? (if URI hasn't changed,
089 * parse more from same file, else end and restart parsing...?
090 *
091 * @param source The InputSource to parse from.
092 * @param appCoroutine The coroutine ID number of the coroutine invoking
093 * this method, so it can be resumed after the parser has responded to the
094 * request.
095 * @return Boolean.TRUE if the CoroutineParser believes more data may be available
096 * for further parsing. Boolean.FALSE if parsing ran to completion.
097 * Exception if the parser objected for some reason.
098 * */
099 public Object doParse(InputSource source, int appCoroutine);
100
101 /** doMore() is a simple API which tells the coroutine parser
102 * that we need more nodes. This is intended to be called from one
103 * of our partner coroutines, and serves both to encapsulate the
104 * communication protocol and to avoid having to explicitly use the
105 * CoroutineParser's coroutine ID number.
106 *
107 * @param parsemore If true, tells the incremental parser to generate
108 * another chunk of output. If false, tells the parser that we're
109 * satisfied and it can terminate parsing of this document.
110 * @param appCoroutine The coroutine ID number of the coroutine invoking
111 * this method, so it can be resumed after the parser has responded to the
112 * request.
113 * @return Boolean.TRUE if the CoroutineParser believes more data may be available
114 * for further parsing. Boolean.FALSE if parsing ran to completion.
115 * Exception if the parser objected for some reason.
116 * */
117 public Object doMore (boolean parsemore, int appCoroutine);
118
119 /** doTerminate() is a simple API which tells the coroutine
120 * parser to terminate itself. This is intended to be called from
121 * one of our partner coroutines, and serves both to encapsulate the
122 * communication protocol and to avoid having to explicitly use the
123 * CoroutineParser's coroutine ID number.
124 *
125 * Returns only after the CoroutineParser has acknowledged the request.
126 *
127 * @param appCoroutine The coroutine ID number of the coroutine invoking
128 * this method, so it can be resumed after the parser has responded to the
129 * request.
130 * */
131 public void doTerminate(int appCoroutine);
132
133 /**
134 * Initialize the coroutine parser. Same parameters could be passed
135 * in a non-default constructor, or by using using context ClassLoader
136 * and newInstance and then calling init()
137 */
138 public void init( CoroutineManager co, int appCoroutineID, XMLReader parser );
139
140 } // class CoroutineParser