io.muserver.AsyncHandle Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mu-server Show documentation
A simple but powerful web server framework
There is a newer version: 2.0.3
package io.muserver;

import java.nio.ByteBuffer;
import java.util.concurrent.Future;

/**
 * A class to handle the request and response handling when using asynchronous request handling.
 * To asynchronously read the request body, see {@link #setReadListener(RequestBodyListener)}. To
 * write data, this interface provides asynchronous write operations, or alternatively you can use the
 * blocking write operations on the original {@link MuResponse}.
 */
public interface AsyncHandle {

    /**
     * Sets a listener that will be notified when chunks of request data become available.
     * If this is not set, then the usual (blocking) request reading methods on the request object can be used.
     * @param readListener The listener.
     */
    void setReadListener(RequestBodyListener readListener);

    /**
     * Call this to indicate that the response is complete.
     */
    void complete();

    /**
     * Calling this will mark the request as complete and log the error message. If possible, a 500 Internal Server Error
     * message will be sent to the client.
     * @param throwable an exception to log
     */
    void complete(Throwable throwable);


    /**
     * Writes data to the response asynchronously.
     * Note that even in async mode it is possible to use the blocking write methods on the {@link MuResponse}
     * See {@link #write(ByteBuffer)} for an alternative that returns a future.
     * @param data The data to write
     * @param callback The callback when the write succeeds or fails
     */
    void write(ByteBuffer data, WriteCallback callback);

    /**
     * Writes data to the response asynchronously.
     * Note that even in async mode it is possible to use the blocking write methods on the {@link MuResponse}
     * See {@link #write(ByteBuffer, WriteCallback)} for an alternative that uses a callback.
     * @param data The data to write
     * @return A future that is resolved when the write succeeds or fails.
     */
    Future write(ByteBuffer data);

    /**
     * Add a listener for when request processing is complete. One use of this is to detect early client disconnects
     * so that expensive operations can be cancelled.
     * @param responseCompletedListener The handler to invoke when the request is complete.
     */
    void setResponseCompletedHandler(ResponseCompletedListener responseCompletedListener);

    interface ResponseCompletedListener {
        /**
         * Called when it is detected that the client request is completed.
         * Note that this may be called if the client disconnects early, however it many cases network disconnects will not be detected.
         * @param responseWasCompleted True if the response was fully processed; false if it wasn't (for example if the
         *                            request was closed by the client before completing).
         */
        void onComplete(boolean responseWasCompleted);
    }
}