https://openjdk.java.net/ 
/*
 * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
 */
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.sun.org.apache.xml.internal.dtm.ref;

import org.xml.sax.ContentHandler;
import org.xml.sax.InputSource;
import org.xml.sax.XMLReader;


CoroutineParser is an API for parser threads that operate as
coroutines. See CoroutineSAXParser and CoroutineSAXParser_Xerces
for examples.


<grumble> I'd like the interface to require a specific form
for either the base constructor or a static factory method. Java
doesn't allow us to specify either, so I'll just document them
here:

    

  • public CoroutineParser(CoroutineManager co, int appCoroutine);
    • 

  • public CoroutineParser createCoroutineParser(CoroutineManager co, int appCoroutine);
    • 


</grumble>


Deprecated:Since the ability to start a parse via the coroutine protocol was not being used and was complicating design. See IncrementalSAXSource.
/** <p>CoroutineParser is an API for parser threads that operate as
 * coroutines. See CoroutineSAXParser and CoroutineSAXParser_Xerces
 * for examples.</p>
 *
 * <p>&lt;grumble&gt; I'd like the interface to require a specific form
 * for either the base constructor or a static factory method. Java
 * doesn't allow us to specify either, so I'll just document them
 * here:
 *
 * <ul>
 * <li>public CoroutineParser(CoroutineManager co, int appCoroutine);</li>
 * <li>public CoroutineParser createCoroutineParser(CoroutineManager co, int appCoroutine);</li>
 * </ul>
 *
 * &lt;/grumble&gt;</p>
 *
 * @deprecated Since the ability to start a parse via the
 * coroutine protocol was not being used and was complicating design.
 * See {@link IncrementalSAXSource}.
 * */
@Deprecated
public interface CoroutineParser {

    
Returns:the coroutine ID number for this CoroutineParser object.
Note that this isn't useful unless you know which CoroutineManager
you're talking to. Also note that the do...() methods encapsulate
the common transactions with the CoroutineParser, so you shouldn't
need this in most cases.
/** @return the coroutine ID number for this CoroutineParser object.
     * Note that this isn't useful unless you know which CoroutineManager
     * you're talking to. Also note that the do...() methods encapsulate
     * the common transactions with the CoroutineParser, so you shouldn't
     * need this in most cases.
     * */
    public int getParserCoroutineID();

    
Returns:the CoroutineManager for this CoroutineParser object.
If you're using the do...() methods, applications should only
need to talk to the CoroutineManager once, to obtain the
application's Coroutine ID.
/** @return the CoroutineManager for this CoroutineParser object.
     * If you're using the do...() methods, applications should only
     * need to talk to the CoroutineManager once, to obtain the
     * application's Coroutine ID.
     * */
    public CoroutineManager getCoroutineManager();

  
Register a SAX-style content handler for us to output to 
/** Register a SAX-style content handler for us to output to */
  public void setContentHandler(ContentHandler handler);

  
 Register a SAX-style lexical handler for us to output to
 Not all parsers support this...
%REVIEW% Not called setLexicalHandler because Xalan uses that name
internally, which causes subclassing nuisances.

/**  Register a SAX-style lexical handler for us to output to
   *  Not all parsers support this...
   *
   * %REVIEW% Not called setLexicalHandler because Xalan uses that name
   * internally, which causes subclassing nuisances.
   */
  public void setLexHandler(org.xml.sax.ext.LexicalHandler handler);

  /* The run() method is required in CoroutineParsers that run as
   * threads (of course)... but it isn't part of our API, and
   * shouldn't be declared here.
   * */

  //================================================================
  
doParse() is a simple API which tells the coroutine parser
to begin reading from a file.  This is intended to be called from one
of our partner coroutines, and serves both to encapsulate the
communication protocol and to avoid having to explicitly use the
CoroutineParser's coroutine ID number.
%REVIEW% Can/should this unify with doMore? (if URI hasn't changed,
parse more from same file, else end and restart parsing...?

Params:
  • source – The InputSource to parse from.
  • appCoroutine – The coroutine ID number of the coroutine invoking
this method, so it can be resumed after the parser has responded to the
request.
Returns:Boolean.TRUE if the CoroutineParser believes more data may be available
for further parsing. Boolean.FALSE if parsing ran to completion.
Exception if the parser objected for some reason.
/** doParse() is a simple API which tells the coroutine parser
   * to begin reading from a file.  This is intended to be called from one
   * of our partner coroutines, and serves both to encapsulate the
   * communication protocol and to avoid having to explicitly use the
   * CoroutineParser's coroutine ID number.
   *
   * %REVIEW% Can/should this unify with doMore? (if URI hasn't changed,
   * parse more from same file, else end and restart parsing...?
   *
   * @param source The InputSource to parse from.
   * @param appCoroutine The coroutine ID number of the coroutine invoking
   * this method, so it can be resumed after the parser has responded to the
   * request.
   * @return Boolean.TRUE if the CoroutineParser believes more data may be available
   * for further parsing. Boolean.FALSE if parsing ran to completion.
   * Exception if the parser objected for some reason.
   * */
  public Object doParse(InputSource source, int appCoroutine);

  
doMore() is a simple API which tells the coroutine parser
that we need more nodes.  This is intended to be called from one
of our partner coroutines, and serves both to encapsulate the
communication protocol and to avoid having to explicitly use the
CoroutineParser's coroutine ID number.

Params:
  • parsemore – If true, tells the incremental parser to generate
another chunk of output. If false, tells the parser that we're
satisfied and it can terminate parsing of this document.
  • appCoroutine – The coroutine ID number of the coroutine invoking
this method, so it can be resumed after the parser has responded to the
request.
Returns:Boolean.TRUE if the CoroutineParser believes more data may be available
for further parsing. Boolean.FALSE if parsing ran to completion.
Exception if the parser objected for some reason.
/** doMore() is a simple API which tells the coroutine parser
   * that we need more nodes.  This is intended to be called from one
   * of our partner coroutines, and serves both to encapsulate the
   * communication protocol and to avoid having to explicitly use the
   * CoroutineParser's coroutine ID number.
   *
   * @param parsemore If true, tells the incremental parser to generate
   * another chunk of output. If false, tells the parser that we're
   * satisfied and it can terminate parsing of this document.
   * @param appCoroutine The coroutine ID number of the coroutine invoking
   * this method, so it can be resumed after the parser has responded to the
   * request.
   * @return Boolean.TRUE if the CoroutineParser believes more data may be available
   * for further parsing. Boolean.FALSE if parsing ran to completion.
   * Exception if the parser objected for some reason.
   * */
  public Object doMore (boolean parsemore, int appCoroutine);

  
doTerminate() is a simple API which tells the coroutine
parser to terminate itself.  This is intended to be called from
one of our partner coroutines, and serves both to encapsulate the
communication protocol and to avoid having to explicitly use the
CoroutineParser's coroutine ID number.
Returns only after the CoroutineParser has acknowledged the request.

Params:
  • appCoroutine – The coroutine ID number of the coroutine invoking
this method, so it can be resumed after the parser has responded to the
request.
/** doTerminate() is a simple API which tells the coroutine
   * parser to terminate itself.  This is intended to be called from
   * one of our partner coroutines, and serves both to encapsulate the
   * communication protocol and to avoid having to explicitly use the
   * CoroutineParser's coroutine ID number.
   *
   * Returns only after the CoroutineParser has acknowledged the request.
   *
   * @param appCoroutine The coroutine ID number of the coroutine invoking
   * this method, so it can be resumed after the parser has responded to the
   * request.
   * */
  public void doTerminate(int appCoroutine);

  
Initialize the coroutine parser. Same parameters could be passed
in a non-default constructor, or by using using context ClassLoader
and newInstance and then calling init()

/**
   * Initialize the coroutine parser. Same parameters could be passed
   * in a non-default constructor, or by using using context ClassLoader
   * and newInstance and then calling init()
   */
  public void init( CoroutineManager co, int appCoroutineID, XMLReader parser );

} // class CoroutineParser