Class Script<INPUT,​RESPONSE,​RESULT>

  • Type Parameters:
    INPUT - This reqpresents the type that the Asynchronous Communications I/O is expecting to send. This class was originally developled to be used with WebSockets, and in that case, 'INPUT' type would be of type java.lang.String.

    NOTE: The contents of that String are in JSON format.
    RESPONSE - This type is the 'Reponse Type' that is produced by the Asynchronous I/O. In the case of the WebSocket's Processor used by the Browser Remote Debugging Protocol, this type will always be JsonObject.

    The web-browser Remote Debugging Protocol solely uses JSON in those communications.
    RESULT - This type indicates the type used by return-value that's ultimately received by the user. This type is the class which is actually returned when a user makes a call to Promise.await().
    All Implemented Interfaces:
    java.io.Serializable
    public class Script<INPUT,​RESPONSE,​RESULT>
extends java.lang.Object
implements java.io.Serializable
    The class script simply sends an asynchronous request, and returns an instance of Promise which may be awaited.

    The three classes, Script, Promise and Sender are designed to allow for the creation of 'Asynchronous Scripts' that may be executed and made to appear to be synchronous through the Promise.await() method.

    These three classes are made use of in the Browser Remote Debugging Protocol Package. Theoretically, they could be used by any asynchronous communication system.
    See Also:
    Serialized Form


    • Constructor Summary

      Constructors 
      Constructor Description
      Script​(Sender<INPUT> defaultSender, int requestID, INPUT request, Function<RESPONSE,​RESULT> receiver)
      Constructs an instance of this class.

    • Method Summary

       
      Execute Asynchronous Request, Return Promise
      Modifier and Type Method
      Promise<RESPONSE,​RESULT> exec()
       
      Execute Request, Return Promise, but Use Alternate Channel
      Modifier and Type Method
      Promise<RESPONSE,​RESULT> exec​(Sender<INPUT> alternateUserProvidedSender)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

      • defaultSender

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final Sender<INPUT> defaultSender
        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.

        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 exec(Sender) method.

      • requestID

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int requestID
        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.

      • receiver

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.util.function.Function<RESPONSE,​RESULT> receiver
        The Promise that is produced by this class, after invoking an 'exec' method needs to be able to do any processing on the raw-output that is received from the Asynchronous Communication's Channel.

        If the type of the 'RESPONSE' was JsonObject, then this function pointer would have to perform the Json-Binding to convert the JsonObject into a Java Object (ultimately having type 'RESULT').

    • Constructor Detail

      • Script

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Script​(Sender<INPUT> defaultSender,
              int requestID,
              INPUT request,
              java.util.function.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 'exec' method. Furthermore, the user will not get a response until he has awaited the Promise object that is returned from that 'exec' call.
        Parameters:
        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.
        requestID - This is just an ID used to send the message. When these asynchronous classes are applied / used-by the 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.
        request - The request that is passed to the sender's 'send' method.
        receiver - This Function-Pointer needs to be able to convert the Asynchronous Channel's 'RESPONSE'-typed object into type 'RESULT', which is what the user is ultimately expecting.

        NOTE: Thus far in Java HTML Development, the Type Parameter 'RESPONSE' has always been JsonObject. This 'receiver' parameter is actually expected to perform the JSON-Binding that maps Json-Properties into 'Plain Old Java Objects' (POJO's).

        It is conceivable that later uses of these Promise / Script Generic Classes wouldn't necessarily operate over Web-Sockets, and wouldn't use Json as a communication medium / protocol.

    • Method Detail

      • exec

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Promise<RESPONSE,​RESULT> exec()
        This builds a Promise object, and then uses the 'defaultSender' to send a message to the Asynchronous I/O Channel.

        When using Script's that were generated by the Browser Remote Debug Protocol API, the 'defaultSender' is merely a connection to the first Chrome-Browser opened by the class BDRPC (which is a a browser connection class).

        ASIDE: The instance of Promise must be created here, not because it would be "dangerous" to allow 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.
        Returns:
        An instance of Promise. Calling that returned Promise' method Promise.await() is how to actually retrieve the 'RESULT' that was transmitted by the channel.

        NOTE: It isn't mandatory to call Promise.await(). The result can simply be obtained by waiting a long enough time for the 'RESULT' of this call to have been both transmited, and processed.
        Code:
        Exact Method Body:
         Promise<RESPONSE, RESULT> promise = new Promise<>(receiver);
 defaultSender.send(requestID, request, promise);
 return promise;

      • exec

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public Promise<RESPONSE,​RESULT> exec​
            (Sender<INPUT> alternateUserProvidedSender)
        If there are reasons to use a different sender - because certain configurations need to change - then using this exec method allows a user to change senders.
        Parameters:
        alternateUserProvidedSender - A different sender when executing a Script object-instance. This would allow a user to ask that a pre-compiled script use an alternate Aynchronous I/O Channel for sending his compiled-request to whatever server is receiving these communications.

        In the Browser Remote Debug Package (Headless Chrome), if multiple headless browses instances were started and opened, using this variant of 'exec' would allow a programmer to decide which requests / compiled-scripts were sent to which opened-browser.
        Returns:
        An instance of Promise. Calling that returned Promise' method Promise.await() is how to actually retrieve the 'RESULT' that was transmitted by the channel.

        NOTE: It isn't mandatory to call Promise.await(). The result can simply be obtained by waiting a long enough time for the 'RESULT' of this call to have been both transmited, and processed.
        Code:
        Exact Method Body:
         Promise<RESPONSE, RESULT> promise = new Promise<>(receiver);
 alternateUserProvidedSender.send(requestID, request, promise);
 return promise;