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  ;
23  import org.xml.sax.InputSource  ;
24  import org.xml.sax.XMLReader  ;
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   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   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   doParse(InputSource   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   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   parser );
137 
138 } // class CoroutineParser
139
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags