Class RunTime

  • public class RunTime
extends java.lang.Object
    Class created by Automatic Code-Generator.
    This class was built using the Chrome Remote Dev-Tools A.P.I., which is specified by two JSON-RPC Files. These files were obtained from the Chrome Dev Tools Protocol Git Hub Page, which has a "Tip of Tree" (the latest) API-Specification Page Here: JSON-RPC Protocol Specification.

    JSON-Viewable Google-API:
    These files may be viewed here: browser_protocol.json and js_protocol.json.
    These files were converted into this Java-Browser (CDT) Library; they are a Java-Alternative to the Node.js implementation.

    HTML-Viewable API:
    In addition to this Class-Library, these files were also converted to a simple HTML Page, which may be browsed here: Browser API Web-Page

    Node.js RDP-API Implementation:
    You may read about the Node.js Chrome Remote Interface on the Node.js Package Manager Web-Site: NPM
    RunTime domain exposes JavaScript runtime by means of remote evaluation and mirror objects. Evaluation results are returned as mirror object that expose object type, string representation and unique identifier that can be used for further object reference. Original objects are maintained in memory unless they are either explicitly released or are released along with the other objects in their object group.

    This class is intended to be used with a Headless Browser

    These methods have been tested, to some degree, using Google Chrome. In order to use this class you must start a web-browser instance and make a connection to the browser using a Remote Debugging Port. The initializations may be accomplished using class BRDPC (Browser Remote Debug Protocol Connection).

    Google-Chrome was used during the development process of the classes in this particular package. Note that, lately, it has been asserted Microsoft has switched to using the Chrome-Engine for its Microsoft Edge Browser Internal Code-Base. Therefore, there may limited support / functionality when running the methods in this class with Microsoft-Edge. There is the possibility these will work with Opera & Safari.

    Check whether the your Web-Browser will allow itself to be driven by the Web-Socket RDP-Port 9223.

    Foreign Function API:
    Every one of the methods that reside in this class are designed to do nothing more than:

    1. Accept Parameters from the User, and "Marshall Them" into a Valid JSON-Request
    2. Transmit the Marshalled Request-JSON to a Headless Web-Browser over a Web-Socket RDP Connection
    3. Receive BOTH that Method's Results AND any Browser Event-Firings from the Web-Socket
    4. Parse JSON Method-Results and Browser-Event Firings, and Subsequently Convert them to Standard Java-Types
    5. Report these Method-Results and Browser-Events to the User via an User-Registered Event-Listener or a Promise Object


    Java-HTML Difference:
    Unlike the bulk of the Java HTML JAR Library, there is very little native Java-Code, and very little testing that may be done on any of the classes & methods in this package. The code inside these classes does nothing more than marshall-and-unmarshall Java-Types into Json-Requests (and vice-versa). The Java-Script & Browser modules inside of a Google-Chrome instance are, theoretically, handling these requests, and returning their results (or events) over the Web-Socket Connection.

    It has been asserted (by Google Chrome Developers) that some of these methods are only "partially working" or "experimental".



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 22 Method(s), 22 declared static
    • 5 Field(s), 5 declared static, 4 declared final
    • Fields excused from final modifier (with explanation):
      Field 'counter' is not final. Reason: CONFIGURATION


    • Method Detail

      • awaitPromise

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<RunTime.RemoteObject,​RunTime.ExceptionDetails>> awaitPromise​
            (java.lang.String promiseObjectId,
             java.lang.Boolean returnByValue,
             java.lang.Boolean generatePreview)
        Add handler to promise with given promise object id.
        Parameters:
        promiseObjectId - Identifier of the promise.
        returnByValue - Whether the result is expected to be a JSON object that should be sent by value.
        OPTIONAL
        generatePreview - Whether preview should be generated for the result.
        OPTIONAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

      • callFunctionOn

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<RunTime.RemoteObject,​RunTime.ExceptionDetails>> callFunctionOn​
            (java.lang.String functionDeclaration,
             java.lang.String objectId,
             RunTime.CallArgument[] arguments,
             java.lang.Boolean silent,
             java.lang.Boolean returnByValue,
             java.lang.Boolean generatePreview,
             java.lang.Boolean userGesture,
             java.lang.Boolean awaitPromise,
             java.lang.Integer executionContextId,
             java.lang.String objectGroup,
             java.lang.Boolean throwOnSideEffect)
        Calls function with given declaration on the given object. Object group of the result is inherited from the target object.
        Parameters:
        functionDeclaration - Declaration of the function to call.
        objectId - Identifier of the object to call function on. Either objectId or executionContextId should be specified.
        OPTIONAL
        arguments - Call arguments. All call arguments must belong to the same JavaScript world as the target object.
        OPTIONAL
        silent - In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
        OPTIONAL
        returnByValue - Whether the result is expected to be a JSON object which should be sent by value.
        OPTIONAL
        generatePreview - Whether preview should be generated for the result.
        OPTIONAL
        EXPERIMENTAL
        userGesture - Whether execution should be treated as initiated by user in the UI.
        OPTIONAL
        awaitPromise - Whether execution should await for resulting value and return once awaited promise is resolved.
        OPTIONAL
        executionContextId - Specifies execution context which global object will be used to call function on. Either executionContextId or objectId should be specified.
        OPTIONAL
        objectGroup - Symbolic group name that can be used to release multiple objects. If objectGroup is not specified and objectId is, objectGroup will be inherited from object.
        OPTIONAL
        throwOnSideEffect - Whether to throw an exception if side effect cannot be ruled out during evaluation.
        OPTIONAL
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

      • compileScript

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<java.lang.String,​RunTime.ExceptionDetails>> compileScript​
            (java.lang.String expression,
             java.lang.String sourceURL,
             boolean persistScript,
             java.lang.Integer executionContextId)
        Compiles expression.
        Parameters:
        expression - Expression to compile.
        sourceURL - Source url to be set for the script.
        persistScript - Specifies whether the compiled script should be persisted.
        executionContextId - Specifies in which execution context to perform script run. If the parameter is omitted the evaluation will be performed in the context of the inspected page.
        OPTIONAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

      • disable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> disable()
        Disables reporting of execution contexts creation.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • discardConsoleEntries

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> discardConsoleEntries
            ()
        Discards collected exceptions and console API calls.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • enable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> enable()
        Enables reporting of execution contexts creation by means of executionContextCreated event. When the reporting gets enabled the event will be sent immediately for each existing execution context.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • evaluate

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<RunTime.RemoteObject,​RunTime.ExceptionDetails>> evaluate​
            (java.lang.String expression,
             java.lang.String objectGroup,
             java.lang.Boolean includeCommandLineAPI,
             java.lang.Boolean silent,
             java.lang.Integer contextId,
             java.lang.Boolean returnByValue,
             java.lang.Boolean generatePreview,
             java.lang.Boolean userGesture,
             java.lang.Boolean awaitPromise,
             java.lang.Boolean throwOnSideEffect,
             java.lang.Number timeout,
             java.lang.Boolean disableBreaks,
             java.lang.Boolean replMode,
             java.lang.Boolean allowUnsafeEvalBlockedByCSP,
             java.lang.String uniqueContextId)
        Evaluates expression on global object.
        Parameters:
        expression - Expression to evaluate.
        objectGroup - Symbolic group name that can be used to release multiple objects.
        OPTIONAL
        includeCommandLineAPI - Determines whether Command Line API should be available during the evaluation.
        OPTIONAL
        silent - In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
        OPTIONAL
        contextId - Specifies in which execution context to perform evaluation. If the parameter is omitted the evaluation will be performed in the context of the inspected page. This is mutually exclusive with uniqueContextId, which offers an alternative way to identify the execution context that is more reliable in a multi-process environment.
        OPTIONAL
        returnByValue - Whether the result is expected to be a JSON object that should be sent by value.
        OPTIONAL
        generatePreview - Whether preview should be generated for the result.
        OPTIONAL
        EXPERIMENTAL
        userGesture - Whether execution should be treated as initiated by user in the UI.
        OPTIONAL
        awaitPromise - Whether execution should await for resulting value and return once awaited promise is resolved.
        OPTIONAL
        throwOnSideEffect - Whether to throw an exception if side effect cannot be ruled out during evaluation. This implies disableBreaks below.
        OPTIONAL
        EXPERIMENTAL
        timeout - Terminate execution after timing out (number of milliseconds).
        OPTIONAL
        EXPERIMENTAL
        disableBreaks - Disable breakpoints during execution.
        OPTIONAL
        EXPERIMENTAL
        replMode - Setting this flag to true enables let re-declaration and top-level await. Note that let variables can only be re-declared if they originate from replMode themselves.
        OPTIONAL
        EXPERIMENTAL
        allowUnsafeEvalBlockedByCSP - The Content Security Policy (CSP) for the target might block 'unsafe-eval' which includes eval(), Function(), setTimeout() and setInterval() when called with non-callable arguments. This flag bypasses CSP for this evaluation and allows unsafe-eval. Defaults to true.
        OPTIONAL
        EXPERIMENTAL
        uniqueContextId - An alternative way to specify the execution context to evaluate in. Compared to contextId that may be reused across processes, this is guaranteed to be system-unique, so it can be used to prevent accidental evaluation of the expression in context different than intended (e.g. as a result of navigation across process boundaries). This is mutually exclusive with contextId.
        OPTIONAL
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

      • getIsolateId

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​java.lang.String> getIsolateId
            ()
        Returns the isolate id.
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, String>

        This script may be executed, using Script.exec(), and afterwards, a Promise<JsonObject, String> will be returned.

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may may be retrieved.

        This Browser Function returns

        • String (id)
          The isolate id.

      • getHeapUsage

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<java.lang.Number,​java.lang.Number>> getHeapUsage
            ()
        Returns the JavaScript heap usage. It is the total usage of the corresponding isolate not scoped to a particular RunTime.
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

        • Ret2.a: Number (usedSize)
          Used heap size in bytes.

        • Ret2.b: Number (totalSize)
          Allocated heap size in bytes.

      • globalLexicalScopeNames

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​java.lang.String[]> globalLexicalScopeNames​
            (java.lang.Integer executionContextId)
        Returns all let, const and class variables from global scope.
        Parameters:
        executionContextId - Specifies in which execution context to lookup global scope variables.
        OPTIONAL
        Returns:
        An instance of Script<String, JsonObject, String[]>

        This script may be executed, using Script.exec(), and afterwards, a Promise<JsonObject, String[]> will be returned.

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may may be retrieved.

        This Browser Function returns

        • String[] (names)
          -

      • releaseObject

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> releaseObject​
            (java.lang.String objectId)
        Releases remote object with given id.
        Parameters:
        objectId - Identifier of the object to release.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • releaseObjectGroup

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> releaseObjectGroup​
            (java.lang.String objectGroup)
        Releases all remote objects that belong to a given group.
        Parameters:
        objectGroup - Symbolic object group name.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • runIfWaitingForDebugger

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> runIfWaitingForDebugger
            ()
        Tells inspected instance to run if it was waiting for debugger to attach.
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • runScript

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<RunTime.RemoteObject,​RunTime.ExceptionDetails>> runScript​
            (java.lang.String scriptId,
             java.lang.Integer executionContextId,
             java.lang.String objectGroup,
             java.lang.Boolean silent,
             java.lang.Boolean includeCommandLineAPI,
             java.lang.Boolean returnByValue,
             java.lang.Boolean generatePreview,
             java.lang.Boolean awaitPromise)
        Runs script with given id in a given context.
        Parameters:
        scriptId - Id of the script to run.
        executionContextId - Specifies in which execution context to perform script run. If the parameter is omitted the evaluation will be performed in the context of the inspected page.
        OPTIONAL
        objectGroup - Symbolic group name that can be used to release multiple objects.
        OPTIONAL
        silent - In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
        OPTIONAL
        includeCommandLineAPI - Determines whether Command Line API should be available during the evaluation.
        OPTIONAL
        returnByValue - Whether the result is expected to be a JSON object which should be sent by value.
        OPTIONAL
        generatePreview - Whether preview should be generated for the result.
        OPTIONAL
        awaitPromise - Whether execution should await for resulting value and return once awaited promise is resolved.
        OPTIONAL
        Returns:
        An instance of Script<String, JsonObject, Ret2>

        This Script may be executed (using Script.exec()), and a Promise returned.

        When the Promise is awaited (using Promise.await()), the Ret2 will subsequently be returned from that call.

        The returned values are encapsulated in an instance of Ret2

      • setAsyncCallStackDepth

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setAsyncCallStackDepth​
            (int maxDepth)
        Enables or disables async call stacks tracking.
        Parameters:
        maxDepth - Maximum depth of async call stacks. Setting to 0 will effectively disable collecting async call stacks (default).
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • setCustomObjectFormatterEnabled

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setCustomObjectFormatterEnabled​
            (boolean enabled)
        [No Description Provided by Google]
        EXPERIMENTAL
        Parameters:
        enabled - -
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • setMaxCallStackSizeToCapture

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setMaxCallStackSizeToCapture​
            (int size)
        [No Description Provided by Google]
        EXPERIMENTAL
        Parameters:
        size - -
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • terminateExecution

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> terminateExecution
            ()
        Terminate current or next JavaScript execution. Will cancel the termination when the outer-most script execution ends.
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • addBinding

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> addBinding​
            (java.lang.String name,
             java.lang.Integer executionContextId,
             java.lang.String executionContextName)
        If executionContextId is empty, adds binding with the given name on the global objects of all inspected contexts, including those created later, bindings survive reloads. Binding function takes exactly one argument, this argument should be string, in case of any other input, function throws an exception. Each binding function call produces RunTime.bindingCalled notification.
        EXPERIMENTAL
        Parameters:
        name - -
        executionContextId - If specified, the binding would only be exposed to the specified execution context. If omitted and executionContextName is not set, the binding is exposed to all execution contexts of the target. This parameter is mutually exclusive with executionContextName. Deprecated in favor of executionContextName due to an unclear use case and bugs in implementation (crbug.com/1169639). executionContextId will be removed in the future.
        OPTIONAL
        DEPRECATED
        executionContextName - If specified, the binding is exposed to the executionContext with matching name, even for contexts created after the binding is added. See also ExecutionContext.name and worldName parameter to Page.addScriptToEvaluateOnNewDocument. This parameter is mutually exclusive with executionContextId.
        OPTIONAL
        EXPERIMENTAL
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.

      • removeBinding

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> removeBinding​
            (java.lang.String name)
        This method does not remove binding function from global object but unsubscribes current runtime agent from RunTime.bindingCalled notifications.
        EXPERIMENTAL
        Parameters:
        name - -
        Returns:
        An instance of Script<String, JsonObject, Ret0>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<JsonObject, Ret0 > to ensure the Browser Function has run to completion.