KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xml > dtm > ref > CoroutineParser


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 /*
17  * $Id: CoroutineParser.java,v 1.8 2004/02/16 23:06:11 minchau Exp $
18  */

19
20 package org.apache.xml.dtm.ref;
21
22 import org.xml.sax.ContentHandler JavaDoc;
23 import org.xml.sax.InputSource JavaDoc;
24 import org.xml.sax.XMLReader JavaDoc;
25
26 /** <p>CoroutineParser is an API for parser threads that operate as
27  * coroutines. See CoroutineSAXParser and CoroutineSAXParser_Xerces
28  * for examples.</p>
29  *
30  * <p>&lt;grumble&gt; I'd like the interface to require a specific form
31  * for either the base constructor or a static factory method. Java
32  * doesn't allow us to specify either, so I'll just document them
33  * here:
34  *
35  * <ul>
36  * <li>public CoroutineParser(CoroutineManager co, int appCoroutine);</li>
37  * <li>public CoroutineParser createCoroutineParser(CoroutineManager co, int appCoroutine);</li>
38  * </ul>
39  *
40  * &lt;/grumble&gt;</p>
41  *
42  * @deprecated Since the ability to start a parse via the
43  * coroutine protocol was not being used and was complicating design.
44  * See {@link IncrementalSAXSource}.
45  * */

46 public interface CoroutineParser {
47
48     /** @return the coroutine ID number for this CoroutineParser object.
49      * Note that this isn't useful unless you know which CoroutineManager
50      * you're talking to. Also note that the do...() methods encapsulate
51      * the common transactions with the CoroutineParser, so you shouldn't
52      * need this in most cases.
53      * */

54     public int getParserCoroutineID();
55
56     /** @return the CoroutineManager for this CoroutineParser object.
57      * If you're using the do...() methods, applications should only
58      * need to talk to the CoroutineManager once, to obtain the
59      * application's Coroutine ID.
60      * */

61     public CoroutineManager getCoroutineManager();
62
63   /** Register a SAX-style content handler for us to output to */
64   public void setContentHandler(ContentHandler JavaDoc handler);
65
66   /** Register a SAX-style lexical handler for us to output to
67    * Not all parsers support this...
68    *
69    * %REVIEW% Not called setLexicalHandler because Xalan uses that name
70    * internally, which causes subclassing nuisances.
71    */

72   public void setLexHandler(org.xml.sax.ext.LexicalHandler JavaDoc handler);
73
74   /* The run() method is required in CoroutineParsers that run as
75    * threads (of course)... but it isn't part of our API, and
76    * shouldn't be declared here.
77    * */

78
79   //================================================================
80
/** doParse() is a simple API which tells the coroutine parser
81    * to begin reading from a file. This is intended to be called from one
82    * of our partner coroutines, and serves both to encapsulate the
83    * communication protocol and to avoid having to explicitly use the
84    * CoroutineParser's coroutine ID number.
85    *
86    * %REVIEW% Can/should this unify with doMore? (if URI hasn't changed,
87    * parse more from same file, else end and restart parsing...?
88    *
89    * @param source The InputSource to parse from.
90    * @param appCoroutine The coroutine ID number of the coroutine invoking
91    * this method, so it can be resumed after the parser has responded to the
92    * request.
93    * @return Boolean.TRUE if the CoroutineParser believes more data may be available
94    * for further parsing. Boolean.FALSE if parsing ran to completion.
95    * Exception if the parser objected for some reason.
96    * */

97   public Object JavaDoc doParse(InputSource JavaDoc source, int appCoroutine);
98
99   /** 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 JavaDoc 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, XMLReader JavaDoc parser );
137
138 } // class CoroutineParser
139
Popular Tags