org.apidesign.bck2brwsr.launcher

## Class Launcher

- java.lang.Object
- - org.apidesign.bck2brwsr.launcher.Launcher

-     public abstract class Launcher
      extends Object

  An abstraction for executing tests in a Bck2Brwsr virtual machine. Either in `JavaScript engine`, or in `external browser`.

  There also are methods to `display pages` in an external browser served by internal HTTP server.

  Author:
    Jaroslav Tulach

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Launcher` | `createBrowser(String cmd)` Creates launcher that is using external browser.
    `static Launcher` | `createBrowser(String cmd, ClassLoader classes, String startpage)` Creates launcher that is using external browser.
    `InvocationContext` | `createInvocation(Class<?> clazz, String method)` Builds an invocation context.
    `static Launcher` | `createJavaScript()` Creates launcher that uses internal JavaScript engine (Rhino).
    `abstract void` | `initialize()` Initializes the launcher.
    `static Closeable` | `showDir(File directory, String startpage)` Starts an HTTP server which provides access to certain directory.
    `static Closeable` | `showDir(String brwsr, File directory, ClassLoader classes, String startpage)` Starts an HTTP server which provides access to certain directory.
    `static Closeable` | `showURL(ClassLoader classes, String startpage)` Starts an HTTP server which provides access to classes and resources available in the `classes` URL and shows a start page available as `ClassLoader.getResource(java.lang.String)` from the provide classloader.
    `static Closeable` | `showURL(String brwsr, ClassLoader classes, String startpage)` Starts an HTTP server which provides access to classes and resources available in the `classes` URL and shows a start page available as `ClassLoader.getResource(java.lang.String)` from the provide classloader.
    `abstract void` | `shutdown()` Shuts down the launcher.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### initialize

          public abstract void initialize()
                                   throws IOException

      Initializes the launcher. This may mean starting a web browser or initializing execution engine.
      Throws:
        `IOException` - if something goes wrong

    - #### shutdown

          public abstract void shutdown()
                                 throws IOException

      Shuts down the launcher.
      Throws:
        `IOException` - if something goes wrong

    - #### createInvocation

          public InvocationContext createInvocation(Class<?> clazz,
                                                    String method)

      Builds an invocation context. The context can later be customized and `invoked`.
      Parameters:
        `clazz` - the class to execute method from
        `method` - the method to execute
      Returns:
        the context pointing to the selected method

    - #### createJavaScript

          public static Launcher createJavaScript()

      Creates launcher that uses internal JavaScript engine (Rhino).
      Returns:
        the launcher

    - #### createBrowser

          public static Launcher createBrowser(String cmd)

      Creates launcher that is using external browser.
      Parameters:
        `cmd` - `null` to use `java.awt.Desktop` to show the launcher or a string to execute in an external process (with a parameter to the URL)
      Returns:
        launcher executing in external browser.

    - #### createBrowser

          public static Launcher createBrowser(String cmd,
                                               ClassLoader classes,
                                               String startpage)

      Creates launcher that is using external browser.
      Parameters:
        `classes` - classloader offering access to classes and resources
        `startpage` - page to show in the browser
        `cmd` - `null` to use `java.awt.Desktop` to show the launcher or a string to execute in an external process (with a parameter to the URL)
      Returns:
        launcher executing in external browser.

    - #### showURL

          public static Closeable showURL(ClassLoader classes,
                                          String startpage)
                                   throws IOException

      Starts an HTTP server which provides access to classes and resources available in the `classes` URL and shows a start page available as `ClassLoader.getResource(java.lang.String)` from the provide classloader. Opens a browser with URL showing the start page.
      Parameters:
        `classes` - classloader offering access to classes and resources
        `startpage` - page to show in the browser
      Returns:
        interface that allows one to stop the server
      Throws:
        `IOException` - if something goes wrong

    - #### showURL

          public static Closeable showURL(String brwsr,
                                          ClassLoader classes,
                                          String startpage)
                                   throws IOException

      Starts an HTTP server which provides access to classes and resources available in the `classes` URL and shows a start page available as `ClassLoader.getResource(java.lang.String)` from the provide classloader. Opens a browser with URL showing the start page.
      Parameters:
        `brwsr` - name of browser to use or `null`
        `classes` - classloader offering access to classes and resources
        `startpage` - page to show in the browser
      Returns:
        interface that allows one to stop the server
      Throws:
        `IOException` - if something goes wrong
      Since:
        0.7

    - #### showDir

          public static Closeable showDir(String brwsr,
                                          File directory,
                                          ClassLoader classes,
                                          String startpage)
                                   throws IOException

      Starts an HTTP server which provides access to certain directory. The `startpage` should be relative location inside the root directory. Opens a browser with URL showing the start page.
      Parameters:
        `brwsr` - type of the browser to use
        `directory` - the root directory on disk
        `classes` - additional classloader with access to classes or `null`
        `startpage` - relative path from the root to the page
      Returns:
        instance of server that can be closed
      Throws:
        `IOException` - if something goes wrong.
      Since:
        0.8

    - #### showDir

          public static Closeable showDir(File directory,
                                          String startpage)
                                   throws IOException

      Starts an HTTP server which provides access to certain directory. The `startpage` should be relative location inside the root directory. Opens a browser with URL showing the start page.
      Parameters:
        `directory` - the root directory on disk
        `startpage` - relative path from the root to the page
      Returns:
        instance of server that can be closed
      Throws:
        `IOException` - if something goes wrong.

Copyright © 2025 API Design. All Rights Reserved.