org.dflib.jjava.jupyter.channels.ReplyEnvironment Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jupyter-jvm-basekernel Show documentation

The newest version!

package org.dflib.jjava.jupyter.channels;

import org.dflib.jjava.jupyter.messages.ContentType;
import org.dflib.jjava.jupyter.messages.Message;
import org.dflib.jjava.jupyter.messages.MessageType;
import org.dflib.jjava.jupyter.messages.reply.ErrorReply;

public interface ReplyEnvironment {
    void publish(Message msg);

    void reply(Message msg);

    /**
     * Defer the next message send until {@link #resolveDeferrals()}. Deferrals
     * are resolve in a Last In First Out (LIFO) order.
     * 
     * The use case that inspired this functionality is the busy-idle protocol
     * component required by Jupyter.
     *
     * 
     *      ShellReplyEnvironment env = ...;
     *
     *      env.setStatusBusy();
     *      env.defer().setStatusIdle(); //Push idle message to defer stack
     *
     *      env.defer().reply(new ExecuteReply(...)); //Push reply to stack
     *
     *      env.writeToStdOut("Test"); //Write "Test" to std out now
     *
     *      env.resolveDeferrals();
     *      //Send the reply
     *      //Send the idle message
     * 
     *
     * @return this instance for call chaining
     */
    ReplyEnvironment defer();

    /**
     * Defer an arbitrary action. See {@link #defer()} but instead of
     * deferring the next message send, defer a specific action.
     *
     * @param action the action to run when the deferrals are resolved
     */
    void defer(Runnable action);

    void resolveDeferrals();

    > void publish(T content);

    > void reply(T content);

    void replyError(MessageType type, ErrorReply error);

    void setStatusBusy();

    void setStatusIdle();

    void setBusyDeferIdle();
}