Class Browser

  • public class Browser
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
    The Browser domain defines methods and events for browser managing.

    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
    • 17 Method(s), 17 declared static
    • 9 Field(s), 9 declared static, 8 declared final
    • Fields excused from final modifier (with explanation):
      Field 'counter' is not final. Reason: CONFIGURATION


    • Nested Class Summary

       
      Type Classes: Browser Domain Types
      Modifier and Type Inner-Class
      static class  Browser.Bounds
      Browser window bounds information

      EXPERIMENTAL
      static class  Browser.Bucket
      Chrome histogram bucket.
      static class  Browser.Histogram
      Chrome histogram.
      static class  Browser.PermissionDescriptor
      Definition of PermissionDescriptor defined in the Permissions API: https://w3c.github.io/permissions/#dictdef-permissiondescriptor.
       
      Event Classes: Browser Domain Events
      Modifier and Type Inner-Class
      static class  Browser.downloadProgress
      Fired when download makes progress.
      static class  Browser.downloadWillBegin
      Fired when page is about to start a download.

    • Field Summary

       
      Browser Domain Enumerated String Types
      Modifier and Type Field
      static String[] BrowserCommandId
      Browser command ids used by executeBrowserCommand.
      static String[] PermissionSetting
      [No Description Provided by Google]

      EXPERIMENTAL
      static String[] PermissionType
      [No Description Provided by Google]

      EXPERIMENTAL
      static String[] WindowState
      The state of the browser window.

    • Method Detail

      • setPermission

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setPermission​
            (Browser.PermissionDescriptor permission,
             java.lang.String setting,
             java.lang.String origin,
             java.lang.String browserContextId)
        Set permission settings for given origin.
        EXPERIMENTAL
        Parameters:
        permission - Descriptor of permission to override.
        setting - Setting of the permission.
        origin - Origin the permission applies to, all origins if not specified.
        OPTIONAL
        browserContextId - Context to override. When omitted, default browser context is used.
        OPTIONAL
        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.

      • grantPermissions

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> grantPermissions​
            (java.lang.String[] permissions,
             java.lang.String origin,
             java.lang.String browserContextId)
        Grant specific permissions to the given origin and reject all others.
        EXPERIMENTAL
        Parameters:
        permissions - -
        origin - Origin the permission applies to, all origins if not specified.
        OPTIONAL
        browserContextId - BrowserContext to override permissions. When omitted, default browser context is used.
        OPTIONAL
        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.

      • resetPermissions

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> resetPermissions​
            (java.lang.String browserContextId)
        Reset all permission management for all origins.
        EXPERIMENTAL
        Parameters:
        browserContextId - BrowserContext to reset permissions. When omitted, default browser context is used.
        OPTIONAL
        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.

      • setDownloadBehavior

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setDownloadBehavior​
            (java.lang.String behavior,
             java.lang.String browserContextId,
             java.lang.String downloadPath,
             java.lang.Boolean eventsEnabled)
        Set the behavior when downloading a file.
        EXPERIMENTAL
        Parameters:
        behavior - Whether to allow all or deny all download requests, or use default Chrome behavior if available (otherwise deny). |allowAndName| allows download and names files according to their dowmload guids.
        Acceptable Values: ["deny", "allow", "allowAndName", "default"]
        browserContextId - BrowserContext to set download behavior. When omitted, default browser context is used.
        OPTIONAL
        downloadPath - The default path to save downloaded files to. This is required if behavior is set to 'allow' or 'allowAndName'.
        OPTIONAL
        eventsEnabled - Whether to emit download events (defaults to false).
        OPTIONAL
        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.

      • cancelDownload

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> cancelDownload​
            (java.lang.String guid,
             java.lang.String browserContextId)
        Cancel a download if in progress
        EXPERIMENTAL
        Parameters:
        guid - Global unique identifier of the download.
        browserContextId - BrowserContext to perform the action in. When omitted, default browser context is used.
        OPTIONAL
        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.

      • close

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> close()
        Close browser gracefully.
        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.

      • crash

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> crash()
        Crashes browser on the main thread.
        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.

      • crashGpuProcess

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> crashGpuProcess()
        Crashes GPU process.
        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.

      • getVersion

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret5<java.lang.String,​java.lang.String,​java.lang.String,​java.lang.String,​java.lang.String>> getVersion
            ()
        Returns version information.
        Returns:
        An instance of Script<String, JsonObject, Ret5>

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

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

        The returned values are encapsulated in an instance of Ret5

        • Ret5.a: String (protocolVersion)
          Protocol version.

        • Ret5.b: String (product)
          Product name.

        • Ret5.c: String (revision)
          Product revision.

        • Ret5.d: String (userAgent)
          User-Agent.

        • Ret5.e: String (jsVersion)
          V8 version.

      • getBrowserCommandLine

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​java.lang.String[]> getBrowserCommandLine
            ()
        Returns the command line switches for the browser process if, and only if --enable-automation is on the commandline.
        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[] (arguments)
          Commandline parameters

      • getHistograms

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Browser.Histogram[]> getHistograms​
            (java.lang.String query,
             java.lang.Boolean delta)
        Get Chrome histograms.
        EXPERIMENTAL
        Parameters:
        query - Requested substring in name. Only histograms which have query as a substring in their name are extracted. An empty or absent query returns all histograms.
        OPTIONAL
        delta - If true, retrieve delta since last call.
        OPTIONAL
        Returns:
        An instance of Script<String, JsonObject, Browser.Histogram[]>

        This script may be executed, using Script.exec(), and afterwards, a Promise<JsonObject, Browser.Histogram[]> 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

      • getWindowForTarget

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret2<java.lang.Integer,​Browser.Bounds>> getWindowForTarget​
            (java.lang.String targetId)
        Get the browser window that contains the devtools target.
        EXPERIMENTAL
        Parameters:
        targetId - Devtools agent host id. If called as a part of the session, associated targetId is used.
        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

        • Ret2.a: Integer (windowId)
          Browser window id.

        • Ret2.b: Browser.Bounds (bounds)
          Bounds information of the window. When window state is 'minimized', the restored window position and size are returned.

      • setWindowBounds

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setWindowBounds​
            (int windowId,
             Browser.Bounds bounds)
        Set position and/or size of the browser window.
        EXPERIMENTAL
        Parameters:
        windowId - Browser window id.
        bounds - New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged.
        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.

      • setDockTile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> setDockTile​
            (java.lang.String badgeLabel,
             java.lang.String image)
        Set dock tile details, platform-specific.
        EXPERIMENTAL
        Parameters:
        badgeLabel - -
        OPTIONAL
        image - Png encoded image. (Encoded as a base64 string when passed over JSON)
        OPTIONAL
        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.

      • executeBrowserCommand

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String,​JsonObject,​Ret0> executeBrowserCommand​
            (java.lang.String commandId)
        Invoke custom browser commands used by telemetry.
        EXPERIMENTAL
        Parameters:
        commandId - -
        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.