com.sun.org.apache.xml.internal.dtm.ref.CoroutineParser Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*
*
* This file incorporates work covered by the following copyright and
* permission notice:
*
* 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.
*/
/*
* $Id: CoroutineParser.java,v 1.8 2010-11-01 04:34:37 joehw Exp $
*/
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 {@link IncrementalSAXSource}.
* */
public interface CoroutineParser {
/** @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();
/** @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 */
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.
*/
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...?
*
* @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.
*
* @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.
*
* @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()
*/
public void init( CoroutineManager co, int appCoroutineID, XMLReader parser );
} // class CoroutineParser