package Torello.Java.Additional;

import java.util.function.Function;
import javax.json.JsonObject;

/**
 * A promise keeps the processing logic for converting a response from an asychronous connection
 * into a result that the end-user can utilize.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=PROMISE>
 * 
 * @param <RESPONSE>    <EMBED CLASS='external-html' DATA-FILE-ID=RESPONSE>
 * @param <RESULT>      <EMBED CLASS='external-html' DATA-FILE-ID=RESULT>
 */
public class Promise<RESPONSE, RESULT> implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // This value is updated by the 'acceptResponse' method
    private RESULT result = null;

    // If an error has occured, these two fields will hold more information
    private boolean response        = false;
    private boolean error           = false;
    private int     errorCode       = 0;
    private String  errorMessage    = null;

    /**
     * Asks {@code 'this'} instance of {@code Promise} whether or not an error has been reported.
     * 
     * @return {@code TRUE} if there were errors reported by the asynchronous channel, and
     * {@code FALSE} otherwise.
     */
    public synchronized boolean hadError() { return error; }

    /**
     * Asks {@code 'this'} instance of {@code Promise} whether any response has been reported.
     * This shall return {@code TRUE} if <I>either an error, or a response has been received</I>.
     * 
     * @return {@code TRUE} if a response or an error has been reported to {@code 'this'} instance,
     * and {@code FALSE} otherwise.
     */
    public synchronized boolean hadResponse() { return response || error; }

    /**
     * Gets all current-state of this {@code Promise}
     * 
     * @return The current state of this {@code Promise}, as an instance of {@link Ret5}.
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>{@code Ret5.a (Boolean)}:
     *      <BR />Whether or not a response has been reported
     *      <BR /><BR /></LI>
     * <LI> {@code Ret5.b (Boolean)}:
     *      <BR />Whether or not an error has been reported
     *      <BR /><BR /></LI>
     * <LI> {@code Ret5.c (RESULT)}:
     *      <BR />The result that has been returned, or null if no result has been received
     *      <BR /><BR /></LI>
     * <LI> {@code Ret5.d (Integer)}:
     *      <BR />The error-code that was received, or 0 if no errors have been reported
     *      <BR /><BR /></LI>
     * <LI> {@code Ret5.e (String)}:
     *      <BR />The error-message (if an error was reported), or null.
     *      </LI>
     * </UL> 
     */
    public synchronized Ret5<Boolean, Boolean, RESULT, Integer, String> getState()
    { return new Ret5<>(response, error, result, errorCode, errorMessage); }

    /**
     * This allows a user to retrieve the result of {@code 'this'} asynchronous {@code Promise}.
     * Note that if no result has been received yet, this method throws an exception.
     * 
     * @return The result of the asynchronous call.
     * 
     * @throws AynchronousException This throws if this {@code Promise} has not received a result
     * yet.
     */
    public synchronized RESULT result()
    {
        if (! response) throw new AsynchronousException("No response has been received yet");
        return result;
    }

    /**
     * This is the "Respone Processor".  As of the writing of this class, the only use that the
     * three classes: Script, Promise &amp; Sender has been for implementing the Google Chrome
     * Browser Remote Debug Protocol.  (Although perhaps these classes will one day be used with a
     * different asychronous protocol)
     * 
     * In this current case (Browser RDP), this receiver is actually doing the "JSON Binding" to
     * bind the JsonObject received from the Browser into a Java Class that the user can actually
     * use.
     */
    public final Function<RESPONSE, RESULT> receiver;

    /**
     * Constructing an instance of {@code Promise} only requires this response-processor (a.k.a. 
     * a 'receiver').
     * 
     * @param receiver This receiver needs to be able to convert the raw asynchronous response
     * - <I>which is just a {@link JsonObject} when used by the Browser RDP Web-Socket Channel</I>
     * - into an instance of {@code 'RESULT'} that the end user can actually use.
     */
    public Promise(Function<RESPONSE, RESULT> receiver)
    { this.receiver = receiver; }

    /**
     * When building a communication-system that uses these {@code Script & Promise} classes, that
     * system needs to invoke {@code 'acceptResponse'} whenever a server-response has been received.
     * 
     * <BR /><BR />With a {@code WebSocket} connection to a Web-Browser via the Remote Debugging
     * Port, mapping the response &amp; request is done by checking the request-ID, and <I>keeping a
     * mapping of ID <B>=&gt;</B> "un-answered Promise Objects."</I>
     * 
     * @param response The response received from the communications channel, Web-Socket, browser
     * etc...
     */
    public synchronized final void acceptResponse(RESPONSE response)
    {
        if (this.error) throw new AsynchronousException(
            "This Promise cannot accept a response object because it has already received " +
            "an rrror.  Current Error Code: [" +
            this.errorCode + "]" +
            ((errorMessage != null) ? ("\nCurrent Error Message: \"" + errorMessage + "\"") : "")
        );

        if (this.response) throw new AsynchronousException
            ("This Promise has already received a response.  A second response is not allowed.");

        this.result     = receiver.apply(response);
        this.response   = true;
    }

    /**
     * If an error occurs in communications-channel logic, that error may be reported to this
     * {@code Promise} by calling {@code 'acceptError'}.
     * 
     * @param errorCode A meaningful error-code.
     * @param errorMessage A meaningful error-message
     * 
     * @throws AsynchronousException If {@code 'this'} instance of {@code 'Promise'} has already
     * received an error (via {@code 'acceptError'}), or if {@code 'this'} has accepted a response
     * (via {@link #acceptResponse(Object)}).
     */
    public synchronized final void acceptError(int errorCode, String errorMessage)
    {
        if (this.error) throw new AsynchronousException(
            "There has already been an error reported to this Promise.  Current Error Code: [" +
            this.errorCode + "]" +
            ((errorMessage != null) ? ("\nError Message: \"" + errorMessage + "\"") : "")
        );

        if (this.response) throw new AsynchronousException
            ("This Promise has already received a response.  It is too late to report an error.");

        this.error          = true;
        this.errorCode      = errorCode;
        this.errorMessage   = errorMessage;
    }

    /**
     * This method will cede the current {@code Thread's} control until the Asynchronous Channel
     * has called this class' {@link #acceptResponse(Object)} method.
     * 
     * @return Once {@code 'this'} instance of {@code 'Promise'} has been notified of a result, it
     * will return that result, as an instance of Type-Parameter {@code 'RESULT'}.
     * 
     * @throws AsynchronousException If a {@code java.lang.InterruptedException} is thrown while
     * awating this {@code Promise}, that exception will be wrapped into an instance of 
     * {@code 'AsynchronousException'}, and then thrown.  This wrapper-exception is an un-checked,
     * {@code RuntimeException}.
     */
    public synchronized final RESULT await()
    {
        try
        {
            // while ((result == null) && (errorCode == 0)) this.wait();
            while ((! response) && (! error)) this.wait();

            return result;
        }
        catch (InterruptedException e)
        {
            throw new AsynchronousException
                ("While awaiting this Promise, an InterruptedException was thrown", e);
        }
    }
}