Package com.teamdev.jxbrowser.browser

Interface Browser

All Superinterfaces:
Advisable<BrowserCallback>, AutoCloseable, Closeable, Observable<BrowserEvent>
public interface Browser extends Closeable, Advisable<BrowserCallback>, Observable<BrowserEvent>
A web browser control that allows loading a web page or a local HTML file, accessing DOM and executing JavaScript on the loaded web page, getting notifications about loading progress, dispatching keyboard and mouse events, etc.

The Browser instance itself is running in a separate native process that allocates memory and system resources that must be released. So, when a Browser instance is no longer needed, it must be closed through the close() method to release all the allocated memory and system resources. For example: 

 Browser browser = engine.newBrowser();
 ...
 browser.close();

Any attempt to use an already closed Browser instance will lead to the IllegalStateException.

The Browser instance is closed automatically when its Engine is closed or unexpectedly crashed. If the instance represents a popup window created by JavaScript via the window.open() function, then JavaScript can close the instance using the window.close() function.

To get notifications that the Browser instance has been closed please subscribe to the following event: 


 browser.on(BrowserClosed.class, event -> {
     // The Browser instance has been closed.
 });

  • Method Summary

    Modifier and Type
    Method
    Description
    Audio
    audio()
    Returns Audio that allows controlling audio on a web page loaded in the current browser instance.
    Bitmap
    bitmap()
    Returns a Bitmap that contains the image of the currently loaded web page.
    List<CaptureSession>
    captureSessions()
    Returns an immutable list of all active capture sessions initiated by the browser.
    CompletableFuture<CastSession>
    cast(MediaReceiver receiver)
    Starts casting the browser content to the media receiver.
    CompletableFuture<CastSession>
    castScreen(MediaReceiver receiver)
    Starts casting screen's content by selecting the screen in the picker dialog.
    CompletableFuture<CastSession>
    castScreen(MediaReceiver receiver, ScreenCastOptions options)
    Starts casting the screen's content to the media receiver.
    void
    close()
    Closes the current browser instance and releases all allocated resources.
    void
    close(CloseOptions options)
    Closes the current browser instance according to the given options.
    Optional<PresentationRequest>
    defaultPresentationRequest()
    Returns the default JavaScript PresentationRequest specified on the page.
    DevTools
    devTools()
    Returns DevTools that allows working with Chromium Developer Tools.
    void
    dispatch(KeyPressed event)
    Dispatches the key pressed event to the currently focused element on the loaded web page.
    void
    dispatch(KeyReleased event)
    Dispatches the key released event to the currently focused element on the loaded web page.
    void
    dispatch(KeyTyped event)
    Dispatches the key typed event to the currently focused element on the loaded web page.
    void
    dispatch(MouseDragged event)
    Dispatches the mouse dragged event to the currently loaded web page.
    void
    dispatch(MouseEntered event)
    Dispatches the mouse entered event to the currently loaded web page.
    void
    dispatch(MouseExited event)
    Dispatches the mouse exited event to the currently loaded web page.
    void
    dispatch(MouseMoved event)
    Dispatches the mouse moved event to the currently loaded web page.
    void
    dispatch(MousePressed event)
    Dispatches the mouse pressed event to the currently loaded web page.
    void
    dispatch(MouseReleased event)
    Dispatches the mouse released event to the currently loaded web page.
    void
    dispatch(MouseWheel event)
    Dispatches the mouse wheel event to the currently loaded web page.
    void
    dispatch(TouchCanceled event)
    Dispatches the touch canceled event to the currently loaded web page.
    void
    dispatch(TouchEnded event)
    Dispatches the touch ended event to the currently loaded web page.
    void
    dispatch(TouchMoved event)
    Dispatches the touch moved event to the currently loaded web page.
    void
    dispatch(TouchStarted event)
    Dispatches the touch started event to the currently loaded web page.
    Display
    display()
    Returns the display where the current browser instance is located.
    void
    downloadUrl(String url)
    Starts downloading the resource at the specified URL.
    Engine
    engine()
    Returns the engine instance of the current browser.
    Bitmap
    favicon()
    Returns a Bitmap that contains the favicon of the currently loaded web page or a Bitmap that contains default Chromium favicon if the browser did not load any web pages or loaded web page URL is invalid.
    void
    focus()
    Tells the current browser instance that it has focus and must be activated.
    Optional<Frame>
    focusedFrame()
    Returns an Optional that contains the focused Frame on the currently loaded web page, otherwise an empty Optional.
    List<Frame>
    frames()
    Returns all the frames on the currently loaded web page or an empty collection if the current browser did not load any web pages.
    FullScreen
    fullScreen()
    Returns the service that controls the fullscreen mode.
    Optional<Frame>
    mainFrame()
    Returns an Optional that contains the main Frame of the currently loaded web page if it exists, otherwise an empty Optional.
    Navigation
    navigation()
    Returns Navigation that allows controlling navigation in the current browser instance.
    Profile
    profile()
    Returns the profile that the browser belongs to.
    void
    replaceMisspelledWord(String word)
    Replaces misspelled word under cursor on the currently loaded web page with the given word.
    void
    resize(int width, int height)
    Updates size of this Browser instance with the given width and height.
    void
    resize(Size size)
    Updates size of the current browser instance with the given one.
    boolean
    saveWebPage(Path htmlFilePath, Path resourcesDir, SavePageType saveType)
    Initiates the saving process of the currently loaded web page.
    BrowserSettings
    settings()
    Returns BrowserSettings that allows configuring the current browser instance.
    Size
    size()
    Returns the size of the current browser instance in the logical pixels.
    TextFinder
    textFinder()
    Returns TextFinder that allows finding text on a web page loaded in the current browser instance.
    String
    title()
    Returns a string that represents the title of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
    void
    unfocus()
    Tells the current browser instance that it does not have focus and must be deactivated.
    String
    url()
    Returns a string that represents URL of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
    String
    userAgent()
    Returns a string that represents the user-agent of the current browser instance.
    void
    userAgent(String userAgent)
    Updates the user-agent string of the current browser instance and reloads the currently loaded web page.
    void
    userAgent(String userAgent, UserAgentData data)
    Updates the user-agent string of the current browser instance, sets the user-agent data and reloads the currently loaded web page.
    UserAgentData
    userAgentData()
    Returns the user-agent data of the current browser instance.
    void
    userAgentData(UserAgentData data)
    Updates the user-agent data of the current browser instance and reloads the currently loaded web page.
    Zoom
    zoom()
    Returns Zoom that allows zooming content of a web page loaded in the current browser instance.

    Methods inherited from interface com.teamdev.jxbrowser.callback.Advisable

    get, remove, set

    Methods inherited from interface com.teamdev.jxbrowser.Closeable

    isClosed

    Methods inherited from interface com.teamdev.jxbrowser.event.Observable

    on

  • Method Details

    • engine

      Engine engine()
      Returns the engine instance of the current browser.

    • profile

      Profile profile()
      Returns the profile that the browser belongs to.

    • mainFrame

      Optional<Frame> mainFrame()
      Returns an Optional that contains the main Frame of the currently loaded web page if it exists, otherwise an empty Optional.

      Make sure that the web page is loaded completely before accessing its main frame.

      Throws:
      ObjectClosedException - when the browser is already closed

    • focusedFrame

      Optional<Frame> focusedFrame()
      Returns an Optional that contains the focused Frame on the currently loaded web page, otherwise an empty Optional.

      Make sure that the web page is loaded completely before accessing its focused frame.

      Throws:
      ObjectClosedException - when the browser is already closed

    • frames

      List<Frame> frames()
      Returns all the frames on the currently loaded web page or an empty collection if the current browser did not load any web pages.
      Throws:
      ObjectClosedException - when the browser is already closed

    • bitmap

      Bitmap bitmap()
      Returns a Bitmap that contains the image of the currently loaded web page.

      The bitmap size depends on the size of the current browser instance and the device scale factor of the display where it is located at the moment. If the current browser size is empty, then the bitmap will be empty as well.

      For example, if the device scale factor of the display where the browser instance is located at the moment is 2.0 and the browser size is 100x100, then the size of the bitmap is expected to be 200x200.

      Throws:
      ObjectClosedException - when the browser is already closed
      BitmapTimeoutException - when the bitmap can not be retrieved within 10 seconds
      Since:
      7.1
      See Also:

    • favicon

      Bitmap favicon()
      Returns a Bitmap that contains the favicon of the currently loaded web page or a Bitmap that contains default Chromium favicon if the browser did not load any web pages or loaded web page URL is invalid.

      Maximum bitmap size is 16x16. If actual favicon size is bigger it will be resized to fit this constant.

      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      7.2

    • textFinder

      TextFinder textFinder()
      Returns TextFinder that allows finding text on a web page loaded in the current browser instance.

    • zoom

      Zoom zoom()
      Returns Zoom that allows zooming content of a web page loaded in the current browser instance.

    • captureSessions

      List<CaptureSession> captureSessions()
      Returns an immutable list of all active capture sessions initiated by the browser.
      Throws:
      ObjectClosedException - if the browser is closed
      Since:
      7.20

    • audio

      Audio audio()
      Returns Audio that allows controlling audio on a web page loaded in the current browser instance.

    • settings

      BrowserSettings settings()
      Returns BrowserSettings that allows configuring the current browser instance.

    • devTools

      DevTools devTools()
      Returns DevTools that allows working with Chromium Developer Tools.
      Since:
      7.1

    • fullScreen

      FullScreen fullScreen()
      Returns the service that controls the fullscreen mode.
      Since:
      7.28

    • cast

      CompletableFuture<CastSession> cast(MediaReceiver receiver)
      Starts casting the browser content to the media receiver.

      In case when the web page has the default PresentationRequest: 

       const presentationRequest = new PresentationRequest(['receiver/index.html']);
 navigator.presentation.defaultRequest = presentationRequest;

      the presentation of the media content specified in this request is started instead of casting the browser content. This implies that the receiver should support the presentation as a media source. Otherwise, if there is no default PresentationRequest, the receiver should support any browser's content as a media source.

      Returns a new CompletableFuture that is completed when the cast session has been started. If the cast session has not been started, the future is completed with CastSessionStartFailedException. If the browser is closed during the casting start, the future will be canceled.

      Throws:
      IllegalStateException - if media routing is disabled
      ObjectClosedException - if the browser is closed
      Since:
      7.29
      See Also:

    • castScreen

      CompletableFuture<CastSession> castScreen(MediaReceiver receiver)
      Starts casting screen's content by selecting the screen in the picker dialog.

      Returns a new CompletableFuture that is completed when the cast session has been started. If the cast session has not been started, the future is completed with CastSessionStartFailedException. If the browser is closed during the casting start, the future will be canceled.

      The receiver should support the CastMode.SCREEN cast mode.

      Throws:
      IllegalStateException - if media routing is disabled
      ObjectClosedException - if the browser is closed
      Since:
      7.29
      See Also:

    • castScreen

      CompletableFuture<CastSession> castScreen(MediaReceiver receiver, ScreenCastOptions options)
      Starts casting the screen's content to the media receiver.

      Returns a new CompletableFuture that is completed when the cast session has been started. If the cast session has not been started, the future is completed with CastSessionStartFailedException. If the browser is closed during the casting start, the future will be canceled.

      The receiver should support the CastMode.SCREEN cast mode.

      Throws:
      IllegalStateException - if media routing is disabled
      ObjectClosedException - if the browser is closed
      Since:
      7.29
      See Also:

    • defaultPresentationRequest

      Optional<PresentationRequest> defaultPresentationRequest()
      Returns the default JavaScript PresentationRequest specified on the page.

      Usually, the default PresentationRequest is specified on resources like YouTube. The developer can specify it this way: 

       const presentationRequest = new PresentationRequest(['receiver/index.html']);
 navigator.presentation.defaultRequest = presentationRequest;
      Throws:
      ObjectClosedException - if the browser is closed
      Since:
      7.34

    • replaceMisspelledWord

      void replaceMisspelledWord(String word)
      Replaces misspelled word under cursor on the currently loaded web page with the given word. If there is no misspelled word under cursor, this method does nothing.
      Parameters:
      word - a string that represents the word for replacement
      Throws:
      IllegalArgumentException - when word is an empty or blank string

    • saveWebPage

      boolean saveWebPage(Path htmlFilePath, Path resourcesDir, SavePageType saveType)
      Initiates the saving process of the currently loaded web page. The web page can be saved as a single HTML file or the file with resources. Before saving a web page make sure that it is not being loaded. It is recommended to completely loaded the web page and only then save it.
      Parameters:
      htmlFilePath - an absolute path to a file in which the web page will be saved
      resourcesDir - an absolute path to a directory in which the resources (e.g. images, css) of the web page will be saved. If the directory does not exist, it will be created
      saveType - determines how the web page will be saved: as an HTML file with all the required resources (e.g. images, css etc.), a single HTML or MHTML file
      Returns:
      true if the saving process has been initialized successfully
      Throws:
      ObjectClosedException - when the browser is already closed

    • url

      String url()
      Returns a string that represents URL of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
      Throws:
      ObjectClosedException - when the browser is already closed

    • title

      String title()
      Returns a string that represents the title of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
      Throws:
      ObjectClosedException - when the browser is already closed

    • userAgentData

      UserAgentData userAgentData()
      Returns the user-agent data of the current browser instance.

      If the user-agent data has not been overridden, then this method returns the default user-agent data.

      Since:
      8.4.0

    • userAgentData

      void userAgentData(UserAgentData data)
      Updates the user-agent data of the current browser instance and reloads the currently loaded web page.

      The user-agent data is a part of the User-Agent Client Hints API. The API provides a better way of exposing browser and platform information via User-Agent response and request headers, and a JavaScript API.

      Parameters:
      data - a new user-agent data
      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      8.4.0

    • userAgent

      String userAgent()
      Returns a string that represents the user-agent of the current browser instance.

      The user-agent string can be overridden for each browser instance via userAgent(String). If the string has not been overridden, then this method returns the default user-agent string obtained through Network.userAgent().

      Throws:
      ObjectClosedException - when the browser is already closed
      See Also:

    • userAgent

      void userAgent(String userAgent)
      Updates the user-agent string of the current browser instance and reloads the currently loaded web page.
      Parameters:
      userAgent - a new user-agent string
      Throws:
      ObjectClosedException - when the browser is already closed
      IllegalArgumentException - when userAgent is empty or blank

    • userAgent

      void userAgent(String userAgent, UserAgentData data)
      Updates the user-agent string of the current browser instance, sets the user-agent data and reloads the currently loaded web page.

      The user-agent data is a part of the User-Agent Client Hints API. The API provides a better way of exposing browser and platform information via User-Agent response and request headers, and a JavaScript API.

      Parameters:
      userAgent - a new user-agent string
      data - a new user-agent data
      Throws:
      ObjectClosedException - when the browser is already closed
      IllegalArgumentException - when userAgent is empty or blank
      Since:
      8.4.0

    • focus

      void focus()
      Tells the current browser instance that it has focus and must be activated.
      Throws:
      ObjectClosedException - when the browser is already closed

    • unfocus

      void unfocus()
      Tells the current browser instance that it does not have focus and must be deactivated.
      Throws:
      ObjectClosedException - when the browser is already closed

    • resize

      void resize(Size size)
      Updates size of the current browser instance with the given one.

      By default, the size of the browser is empty. Many web pages rely on the browser size and require that it is not empty. The DOM document of a web page might not be loaded and displayed at all, because there is no sense in loading and rendering DOM document when it is empty.

      Use this method when you do not need to display content of the loaded web page, but the web page must "think" it has been loaded in a browser instance with a non-empty size.

      Parameters:
      size - a new size in the logical pixels
      Throws:
      IllegalArgumentException - when size is empty
      ObjectClosedException - when the browser is already closed

    • resize

      void resize(int width, int height)
      Updates size of this Browser instance with the given width and height.

      By default, Browser's size is empty. Many web pages rely on the Browser's size and require that it is not empty. DOM document of a web page might not be loaded and displayed at all, because there is no sense in loading and rendering DOM document when it is empty.

      Use this method when you do not need to display content of the loaded web page, but the web page must "think" it has been loaded in a Browser instance with non-empty size.

      Parameters:
      width - the specified width in the logical pixels
      height - the specified height in the logical pixels
      Throws:
      IllegalArgumentException - when width or height is not positive
      ObjectClosedException - when this Browser is already closed

    • size

      Size size()
      Returns the size of the current browser instance in the logical pixels.

      By default, the size of the browser is empty.

      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      7.1

    • display

      Display display()
      Returns the display where the current browser instance is located.

      By default, it is a primary display.

      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      7.1

    • dispatch

      void dispatch(KeyPressed event)
      Dispatches the key pressed event to the currently focused element on the loaded web page.
      Parameters:
      event - the key pressed event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(KeyReleased event)
      Dispatches the key released event to the currently focused element on the loaded web page.
      Parameters:
      event - the key released event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(KeyTyped event)
      Dispatches the key typed event to the currently focused element on the loaded web page.
      Parameters:
      event - the key typed event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MousePressed event)
      Dispatches the mouse pressed event to the currently loaded web page.
      Parameters:
      event - the mouse pressed event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseReleased event)
      Dispatches the mouse released event to the currently loaded web page.
      Parameters:
      event - the mouse released event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseEntered event)
      Dispatches the mouse entered event to the currently loaded web page.
      Parameters:
      event - the mouse entered event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseExited event)
      Dispatches the mouse exited event to the currently loaded web page.
      Parameters:
      event - the mouse exited event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseDragged event)
      Dispatches the mouse dragged event to the currently loaded web page.
      Parameters:
      event - the mouse dragged event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseMoved event)
      Dispatches the mouse moved event to the currently loaded web page.
      Parameters:
      event - the mouse moved event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(MouseWheel event)
      Dispatches the mouse wheel event to the currently loaded web page.
      Parameters:
      event - the mouse wheel event
      Throws:
      ObjectClosedException - when the browser is already closed

    • dispatch

      void dispatch(TouchStarted event)
      Dispatches the touch started event to the currently loaded web page.

      Touch forwarding is not supported on macOS.

      Parameters:
      event - the touch started event
      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      8.0.0

    • dispatch

      void dispatch(TouchMoved event)
      Dispatches the touch moved event to the currently loaded web page.

      To dispatch the touch moved event, you must first fire a touch started event on the touch point with the same identifier.

      Touch forwarding is not supported on macOS.

      Parameters:
      event - the touch moved event
      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      8.0.0

    • dispatch

      void dispatch(TouchEnded event)
      Dispatches the touch ended event to the currently loaded web page.

      To dispatch the touch ended event, you must first fire a touch started event on the touch point with the same identifier.

      Touch forwarding is not supported on macOS.

      Parameters:
      event - the touch ended event
      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      8.0.0

    • dispatch

      void dispatch(TouchCanceled event)
      Dispatches the touch canceled event to the currently loaded web page.

      To dispatch the touch canceled event, you must first fire a touch started event on the touch point with the same identifier.

      Touch forwarding is not supported on macOS.

      Parameters:
      event - the touch canceled event
      Throws:
      ObjectClosedException - when the browser is already closed
      Since:
      8.0.0

    • close

      void close()
      Closes the current browser instance and releases all allocated resources.

      The unload and beforeunload JavaScript events will not be fired in this case. This method is equivalent of close(CloseOptions.newBuilder().build()).

      If the browser is already closed, then this method does nothing.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      See Also:

    • close

      void close(CloseOptions options)
      Closes the current browser instance according to the given options.

      If the currently loaded web page registers the onbeforeunload JavaScript event and the given options tell the browser to fire the beforeunload event, then this method will not close the browser immediately.

      In this case, the BeforeUnloadCallback will be invoked, and if the callback instructs the browser to stay on the web page, the browser will not close.

      The following example demonstrates how to close the browser as if a user manually clicked the close button of the tab or window. 

       browser.close(CloseOptions.newBuilder()
         .fireBeforeUnload()
         .build());

      If the browser is already closed, this method does nothing.

      Since:
      7.6

    • downloadUrl

      void downloadUrl(String url)
      Starts downloading the resource at the specified URL.

      If the given URL is valid and points to a downloadable resource, then the download process will be started. To control the download process, use StartDownloadCallback.

      The method does nothing if the given URL is invalid or points to a resource that cannot be downloaded.

      Parameters:
      url - the URL of the resource to download
      Throws:
      IllegalArgumentException - when url is an empty or blank string
      ObjectClosedException - when the browser is already closed
      Since:
      8.8.0