1 /*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5 /*
6 * Licensed to the Apache Software Foundation (ASF) under one or more
7 * contributor license agreements. See the NOTICE file distributed with
8 * this work for additional information regarding copyright ownership.
9 * The ASF licenses this file to You under the Apache License, Version 2.0
10 * (the "License"); you may not use this file except in compliance with
11 * the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
21
22 package com.sun.org.apache.xml.internal.dtm.ref;
23
24 import org.xml.sax.ContentHandler;
25 import org.xml.sax.InputSource;
26 import org.xml.sax.XMLReader;
27
28 /** <p>CoroutineParser is an API for parser threads that operate as
29 * coroutines. See CoroutineSAXParser and CoroutineSAXParser_Xerces
30 * for examples.</p>
31 *
32 * <p><grumble> I'd like the interface to require a specific form
33 * for either the base constructor or a static factory method. Java
34 * doesn't allow us to specify either, so I'll just document them
35 * here:
36 *
37 * <ul>
38 * <li>public CoroutineParser(CoroutineManager co, int appCoroutine);</li>
39 * <li>public CoroutineParser createCoroutineParser(CoroutineManager co, int appCoroutine);</li>
40 * </ul>
41 *
42 * </grumble></p>
43 *
44 * @deprecated Since the ability to start a parse via the
45 * coroutine protocol was not being used and was complicating design.
46 * See {@link IncrementalSAXSource}.
47 * */
48 public interface CoroutineParser {
49
50 /** @return the coroutine ID number for this CoroutineParser object.
51 * Note that this isn't useful unless you know which CoroutineManager
52 * you're talking to. Also note that the do...() methods encapsulate
53 * the common transactions with the CoroutineParser, so you shouldn't
54 * need this in most cases.
55 * */
56 public int getParserCoroutineID();
57
58 /** @return the CoroutineManager for this CoroutineParser object.
59 * If you're using the do...() methods, applications should only
60 * need to talk to the CoroutineManager once, to obtain the
61 * application's Coroutine ID.
62 * */
63 public CoroutineManager getCoroutineManager();
64
65 /** Register a SAX-style content handler for us to output to */
66 public void setContentHandler(ContentHandler handler);
67
68 /** Register a SAX-style lexical handler for us to output to
69 * Not all parsers support this...
70 *
71 * %REVIEW% Not called setLexicalHandler because Xalan uses that name
72 * internally, which causes subclassing nuisances.
73 */
74 public void setLexHandler(org.xml.sax.ext.LexicalHandler handler);
75
76 /* The run() method is required in CoroutineParsers that run as
77 * threads (of course)... but it isn't part of our API, and
78 * shouldn't be declared here.
79 * */
80
81 //================================================================
82 /** doParse() is a simple API which tells the coroutine parser
83 * to begin reading from a file. This is intended to be called from one
84 * of our partner coroutines, and serves both to encapsulate the
85 * communication protocol and to avoid having to explicitly use the
86 * CoroutineParser's coroutine ID number.
87 *
88 * %REVIEW% Can/should this unify with doMore? (if URI hasn't changed,
89 * parse more from same file, else end and restart parsing...?
90 *
91 * @param source The InputSource to parse from.
92 * @param appCoroutine The coroutine ID number of the coroutine invoking
93 * this method, so it can be resumed after the parser has responded to the
94 * request.
95 * @return Boolean.TRUE if the CoroutineParser believes more data may be available
96 * for further parsing. Boolean.FALSE if parsing ran to completion.
97 * Exception if the parser objected for some reason.
98 * */
99 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