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>&lt;grumble&gt; 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     * &lt;/grumble&gt;</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