package Torello.Java.Additional;

import java.util.Objects;
import java.util.function.Function;
import javax.json.JsonObject; // Needed for @link

/**
 * The class script simply sends an asynchronous request, and returns an instance of {@link Promise}
 * which may be awaited.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=SCRIPT>
 * 
 * @param <INPUT>       <EMBED CLASS='external-html' DATA-FILE-ID=INPUT>
 * @param <RESPONSE>    <EMBED CLASS='external-html' DATA-FILE-ID=RESPONSE>
 * @param <RESULT>      <EMBED CLASS='external-html' DATA-FILE-ID=RESULT>
 */
public class Script<INPUT, RESPONSE, RESULT>
    implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    /**
     * When opening a connection to an asynchronous channel, for instance a Web-Socket to a Google
     * Chrome Browser, the web-socket connecton to that browser receives messages from this sender.
     * 
     * <BR /><BR />If a user needs to have more than one browser opened at the same time, a second
     * sender can be created, and messages may be sent to a different browser by using the 
     * {@link #exec(Sender)} method.
     */
    public final Sender<INPUT> defaultSender;

    /**
     * ID number that was ascribed to this request.  Each request must have an ID because this
     * script is used in an asynchronous communications context.  The only way to link a response
     * to a request is by matching an ID number received as a response, to an ID that was sent with
     * a particular request.
     */
    public final int requestID;

    /**
     * This is the request that the {@code 'sender'} is going to send over the Asynchronous I/O
     * Channel.
     */
    public final INPUT request;

    /**
     * The {@link Promise} that is produced by this class, after invoking an {@code 'exec'} method
     * needs to be able to do any processing on the raw-output that is received from the
     * Asynchronous Communication's Channel.
     * 
     * <BR /><BR />If the type of the {@code 'RESPONSE'} was {@code JsonObject}, then this function
     * pointer would have to perform the <I><B STYLE='color: red;'>Json-Binding</B></I> to convert 
     * the {@link JsonObject} into a Java {@code Object} (ultimately having type {@code 'RESULT'}).
     */
    public final Function<RESPONSE, RESULT> receiver;

    /**
     * Constructs an instance of this class.  This constructor does not actually execute the
     * asychronous-request, but rather just initializes the fields.  The asynchronous call is not
     * made until the user calls an {@code 'exec'} method.  Furthermore, the user will not get a
     * response until he has awaited the {@link Promise} object that is returned from that 
     * {@code 'exec'} call.
     * 
     * @param defaultSender This parameter needs to be passed here to actually do the sending.
     * Perhaps it may be confusing that the sender is passed to this constructor.  The reason that
     * it is not automatically included is because it allows the user to change or modify the
     * sender used before actually executing this script.
     * 
     * @param requestID This is just an ID used to send the message.  When these asynchronous
     * classes are applied / used-by the {@code WebSocket's} package for communicating with a
     * headless browser, this ID is the Web-Socket request ID.  The Web-Socket ID allows the
     * Web-Socket client to match a response to a request.
     * 
     * @param request The request that is passed to the sender's {@code 'send'} method.
     * 
     * @param receiver This Function-Pointer needs to be able to convert the Asynchronous Channel's
     * {@code 'RESPONSE'}-typed object into type {@code 'RESULT'}, which is what the user is
     * ultimately expecting.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color: red;'>Note:</B> Thus far in Java HTML Development, the Type-Parameter
     * {@code 'RESPONSE'} has always been {@link JsonObject}.  This {@code 'receiver'} parameter is
     * actually expected to perform the <B STYLE='color: red;'>JSON-Binding</B> that maps
     * Json-Properties into 'Plain Old Java Objects' (POJO's).
     * </DIV>
     * 
     * <BR />It is conceivable that later uses of these {@code Promise / Script} Generic
     * Classes wouldn't necessarily operate over Web-Sockets, and wouldn't use Json as a
     * communication medium / protocol.
     */
    public Script(
            final Sender<INPUT>                 defaultSender,
            final int                           requestID,
            final INPUT                         request,
            final Function<RESPONSE, RESULT>    receiver
        )
    {
        // Standard Java FAIL-FAST checks
        if (request == null)    throw new NullPointerException("Parameter 'request' is null.");
        if (receiver == null)   throw new NullPointerException("Parameter 'receiver' is null.");

        this.defaultSender  = defaultSender;
        this.requestID      = requestID;
        this.request        = request;
        this.receiver       = receiver;
    }

    /**
     * Constructs an instance of this class in which there is no internal {@link defaultSender}.
     * If an attempt is made to execute this {@code Script}-Instance using the 
     * <B STYLE='color:red;'><I>zero argument</I></B> {@link #exec()}-Method, then that method 
     * shall throw a {@link NoSenderException}.
     */
    public Script(
            final int                           requestID,
            final INPUT                         request,
            final Function<RESPONSE, RESULT>    receiver
        )
    {
        // Standard Java FAIL-FAST checks
        if (request == null)    throw new NullPointerException("Parameter 'request' is null.");
        if (receiver == null)   throw new NullPointerException("Parameter 'receiver' is null.");

        this.defaultSender  = null;
        this.requestID      = requestID;
        this.request        = request;
        this.receiver       = receiver;
    }


    /**
     * This builds a {@link Promise} object, and then uses the {@code 'defaultSender'} to send a
     * message to the Asynchronous I/O Channel.
     *
     * <BR /><BR />When using {@code Script's} that were generated by the Browser Remote Debug
     * Protocol API, the {@code 'defaultSender'} is merely a connection to the first
     * Chrome-Browser opened by the class {@code BDRPC} (which is a a browser connection class).
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * The instance of {@code Promise} must be created here, not because it would be "dangerous" to
     * allow {@link Sender} to create it (even though it is a user implemented
     * functional-interface), but rather because as a Java-Generic, the only way to guarantee that
     * the Generic-Type parameters are easy to deal with, is by creating the promise here and
     * returning the generic immediately to the user.
     * </DIV>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SCRIPTRET>
     */
    public Promise<RESPONSE, RESULT> exec()
    {
        if (defaultSender == null) throw new NoSenderException();
        Promise<RESPONSE, RESULT> promise = new Promise<>(receiver);
        defaultSender.send(requestID, request, promise);
        return promise;
    }

    /**
     * If there are reasons to use a different sender - <I>because certain configurations need to
     * change</I> - then using this {@code exec} method allows a user to change senders.
     * 
     * @param userProvidedSender The {@link Sender} Instance to use when executing this 
     * {@link Script} object-instance.  This allows for a user to either force a pre-compiled 
     * {@code 'Script'}-Instance to use an alternate {@link Sender}, or provide a {@code 'Sender'}
     * Instance if none were provided at the time of Construction of this Object.
     * 
     * <BR /><BR />In the Browser Remote Debug Package (Headless Chrome), the {@code 'Script'} 
     * instances which are generated expect the user to provide their own constructed
     * {@code Sender} instances to facilitate:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>Pre-Compiling Scripts ahead of time for future use, using future Browser-Connections</LI>
     * <LI>Utilizing alternate &amp; various Page-Connections, for different Open-Pages</LI>
     * <LI>Re-using Pre-Compiled Script Components</LI>
     * </UL>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SCRIPTRET>
     */
    public Promise<RESPONSE, RESULT> exec(final Sender<INPUT> userProvidedSender)
    {
        Objects.requireNonNull(userProvidedSender, "Parameter 'userProvidedSender' is null.");
        Promise<RESPONSE, RESULT> promise = new Promise<>(receiver);
        userProvidedSender.send(requestID, request, promise);
        return promise;
    }
}