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