Java Platform, Standard Edition Deployment Guide
Contents    Previous    Next

19 Deployment in the Browser

This topic explains how to deploy Java and JavaFX applications in the browser using the Deployment Toolkit, dtjava.js. An API overview, information about the callback methods, and typical examples of use are provided.

Use the Deployment Toolkit library to embed a Java or JavaFX application in a web page or launch it from a browser. The Deployment Toolkit provides a JavaScript API to simplify web deployment of applications and improve the end user experience when starting the application.

In addition to providing functionality to add HTML tags needed to insert Java or JavaFX applications into the web page, the Deployment Toolkit also provides the following actions:

  • Detects if the user's environment is supported

  • Offers to install the JRE, if needed

  • Provides visual feedback to the user while the application is loaded

  • Reports unexpected errors to the user

  • Provides other helper APIs to the developer, which can be used to simplify deployment and integration with the web page

To use the Deployment Toolkit, import the Deployment Toolkit JavaScript file from the shared location at https://java.com/js/dtjava.js.

This way your application always uses the latest recommended way to integrate into a web page. If you cannot use the shared location, you can include the necessary files with your application by using the includeDT option in the <fx:deploy> Ant task.

Note that for the majority of simple use cases, the code needed for deployment is generated by the Java packaging tools (see Section 5.3.1, "Java Packaging Tools.") You can use callbacks to tune the default behavior further. If you need more flexibility, you can use the Deployment Toolkit APIs directly.

This topic contains the following sections:

19.1 API Overview

The Deployment Toolkit API provides the following important methods:

  • dtjava.embed(app, platform, callbacks)

    Embeds the application into the browser based on a given application descriptor. If JRE installation is required, by default the Deployment Toolkit prompts the user to install the JRE or redirects to the page where the installer can be downloaded.

  • dtjava.launch(app, platform, callbacks)

    Launches applications that are deployed outside of the browser, based on a given application descriptor. If JRE installation is required, then by default the Deployment Toolkit performs the following actions:

    • Attempts to start the JRE installer.

    • If automated installation of the Runtime is not possible, presents a popup request for the user to install manually.

  • dtjava.install(platform, callbacks)

    Initiates installation of required components according to platform requirements.

  • dtjava.validate(platform)

    Validates that the user's environment satisfies platform requirements, for example, verifies that the required version of the JRE is available. Returns PlatformMismatchEvent describing problems, if any.

  • dtjava.hideSplash(id)

    Hides the HTML splash screen for an application with a given ID. If the splash screen does not exist, this method has no effect. For JavaFX applications, this method is called automatically after the application is ready.

See the following sections for more information about arguments taken by these methods.

19.1.1 Application Descriptor (dtjava.App)

The application launch descriptor is an instance of the dtjava.App object. The launch descriptor contains all of the details describing what needs to be launched. The dtjava.App constructor takes the following parameters:

dtjava.App(url, {attribute_map});

The first parameter is the required url attribute, which contains a URL or a relative link to the JNLP file. The second parameter is a subset of the attributes that are described in the following list:

  • id

    Identifier of the application. The identifier is expected to be unique on the web page. If the identifier is null, then an identifier is autogenerated. Later, the identifier can be used to get the handle of the application in JavaScript code.

  • jnlp_content

    (optional) Content of the JNLP file in BASE64 encoding.

  • params

    The set of named parameters to pass to an application, if any. This attribute takes the following form:

    params: { variable: 'value' }

  • width and height

    Dimensions used to reserve space for an embedded application. The values can be absolute in pixels, or relative, for example, 50 or 50%.

  • placeholder

    Reference to a DOM node, or an identifier of a DOM node, in which to embed an application.

  • toolkit

    Identifies the UI toolkit used. Use fx for JavaFX applications, use swing for Swing applications. If no value is specified, the parameter defaults to fx.


Note:

The width, height, and placeholder attributes are required for applications that run in the browser (in other words, applications that use the dtjava.embed() method, but not for other types of deployment, such as applications that use the dtjava.launch() method).

Example 19-1 shows an example of application launch descriptor code for an application that runs in the browser.

19.1.2 Platform (dtjava.Platform)

Platform requirements for an application to launch are defined by the dtjava.Platform object. The following attributes are supported:

  • javafx

    The minimum JavaFX version needed. Default is null.

  • jvm

    Minimum version of the JRe needed. The default is 1.6+.

  • jvmargs

    List of requested JVM arguments. The default is null.

Version strings are treated according to the following rules:

  • The null version string is treated as if there is no requirement to have it installed. Validation passes whether this component is installed or not.

  • The version pattern strings are of the form #[.#[.#[_#]]][+|*], which includes strings such as "1.7", "2.2*", and "1.7.0_25+".

  • An asterisk (*) means any version within this family, where family is defined by a prefix.

  • A plus sign (+) means any version greater or equal to the specified version.

  • If the version pattern does not include all four version components but does not end with an asterisk or plus sign, it will be treated as if it ended with an asterisk.

To clarify the differences, consider the following examples:

  • "1.6.0*" matches 1.6.0_25 but not 1.7.0_01, whereas "1.6.0+" or "1.*" matches both.

  • "2.1" is equivalent to "2.1*",and matches any version number beginning with "2.1".

  • Both asterisk and plus sign patterns match any installed version of the component. However, if the component is not installed, then validation fails.

Example 19-2 shows a dtjava.Platform object:

If platform requirements are not met, then dtjava.PlatformMismatchEvent is returned, either as a return value from the validate() method or passed to the onDeployError callback. This object provides the following helper methods to identify root causes:

  • javafxStatus()

    Returns ok if the error was not due to a missing JavaFX Runtime. Otherwise, this method returns one of the following error codes characterizing the problem:

    • none

      No JavaFX runtime is detected on the system.

    • old

      A version of JavaFX Runtime is detected, but it does not match the platform requirements.

    • disabled

      A matching version of JavaFX Runtime is detected, but it is disabled.

    • unsupported

      JavaFX is not supported on this platform.

  • jreStatus()

    Returns ok if the error was not due to a missing JRE. Otherwise, this method returns one of the following error codes characterizing the problem:

    • none

      No JRE was detected on the system.

    • old

      A version of the JRE is detected, but it does not match the platform requirements.

    • oldplugin

      A matching JRE was found, but it is configured to use a deprecated Java plug-in.

  • canAutoInstall()

    Returns true if the installation of missing components can be triggered automatically or if there are no missing components.

  • isRelaunchNeeded()

    Returns true if a browser must be restarted before the application can be loaded. This often is true in conjunction with the need to perform an installation.

  • isUnsupportedBrowser()

    Returns true if the current browser is not supported, for example, when the browser is out of date.

  • isUnsupportedPlatform()

    Returns true if this platform does not satisfy the supported platform requirements. For example, a JavaFX application attempts to launch on Solaris, which is not supported.

  • javafxInstallerURL (locale)

    Returns the URL of a page to download and install the required version of the JRE manually. If a matching JRE is already installed or not supported, then the return value is null.

  • jreInstallerURL (locale)

    Returns the URL of a page to visit to install the required version of Java. If a matching JRE is already installed or not supported, then the return value is null.

19.2 Callbacks

The Deployment Toolkit provides a set of hooks that can be used to customize startup behavior. To use the hook, the developer must provide a callback function. The following hooks are supported:

  • onDeployError: function(app, mismatchEvent)

    Called when platform requirements are not met.

  • onInstallFinished: function(placeholder, component, status, relaunchNeeded)

    Called after the installation of a required component is completed, unless installation was started manually.

  • onInstallNeeded: function(app, platform, cb, isAutoinstall, needRelaunch, launchFunc)

    Called if embedding or launching an application needs additional components to be installed.

  • onInstallStarted - function(placeholder, component, isAuto, restartNeeded)

    Called before installation of the required component is triggered.

The following hooks are specific to embedded applications:

  • onGetNoPluginMessage function(app)

    Called to get content shown in the application area if the Java Plug-in is not installed and none of the callbacks have helped.

  • onGetSplash: function(app)

    For embedded applications, called to get the content of the splash screen.

  • onJavascriptReady: function(id)

    Called after the application is ready to accept JavaScript calls.

  • onRuntimeError: function(id)

    Called if the application failed to launch.

19.2.1 onDeployError

This handler can be utilized to customize error handling behavior, such as showing messages in the user's language. See the example in Section 19.3.8, "Create a Handler for an Unsupported Platform" for an example of the onDeployError handler.

A callback function is called if the application cannot be deployed because the current platform does not match the given platform requirements. It is also called if a request to install missing components cannot be completed due to platform incompatibility.

Function signature:

onDeployError : function(app, mismatchEvent)

The problem can be a fatal error or a transient issue, such as a required relaunch. Further details can be extracted from the mismatchEvent that is provided. Here are some typical combinations:

  • The browser is not supported by Java.

    mismatchEvent.isUnsupportedBrowser() returns true

  • The browser must be restarted before the application can be launched.

    mismatchEvent.isRelaunchNeeded() returns true

JRE-specific codes:

  • JRE is not supported on this platform.

    mismatchEvent.jreStatus() == "unsupported"

  • JRE is not detected and must be installed.

    mismatchEvent.jreStatus() == "none"

  • The installed version of JRE does not match application requirements.

    mimatchEvent.jreStatus() == "old"

  • A matching JRE is detected, but a deprecated Java Plug-in is used.

    mimatchEvent.jreStatus() == "oldplugin"

JavaFX-specific codes:

  • JavaFX is not supported on this platform.

    mismatchEvent.javafxStatus() == "unsupported"

  • JavaFX Runtime is missing and must be installed manually.

    mismatchEvent.javafxStatus() == "none"

  • The installed version of JavaFX Runtime does not match application requirements.

    mismatchEvent.javafxStatus() == "old"

  • JavaFX Runtime is installed but is disabled.

    mismatchEvent.javafxStatus() == "disabled"

The default error handler handles both application launch errors and embedded content.

19.2.2 onGetNoPluginMessage

This handler is called to get content to be shown in the application area if the Java Plug-in is not installed and none of the callbacks helped to resolve the situation.

Function signature:

onGetNoPluginMessag : function(app)

19.2.4 onInstallFinished

This handler is called after the installation of a required component is completed. This method is not called if the installation is performed in manual mode.

Function signature:

onInstallFinished: function(placeholder, component, status, relaunchNeeded)

Parameters:

  • placeholder: A DOM element that was passed to onInstallStarted to insert visual feedback.

  • component: String "jre" or "javafx"

  • status: String that categorizes the status of the installation, for example, "success", "error:generic", "error:download" or "error:canceled".

  • relaunchNeeded: Boolean value to specify if a browser restart is required to complete the installation.

19.2.5 onInstallNeeded

This handler is called if the embedding or launching application needs additional components to be installed. This callback is responsible for handling situations such as reporting to the user the need to install something, initiating installation using install(), and hiding the splash screen for embedded applications, if needed. After installation is complete, the callback implementation can retry the attempt to launch the application using the provided launch function.

This method is not called if the platform requirement could not be met, for example, if the platform is not supported or if installation is not possible.

The default handler provides a click-to-install solution for applications embedded in a browser and attempts to perform installation without additional questions for applications that have been started using launch().

If the handler is null, then it is treated as a no-op handler.

Function signature:

onInstallNeeded: function(app, platform, cb, isAutoinstall, needRelaunch, launchFunc)

Parameters:

  • app: Application launch descriptor. For embedded applications, app.placeholder refers to the root of the embedded application area in the DOM tree, which is used for visual feedback.

  • platform: Application platform requirements.

  • cb: The set of callbacks to be used during the installation process.

  • isAutoinstall: True, if the installation can be launched automatically.

  • needRestart: True, if restarting the browser is required after installation is complete.

  • launchFunction: Function to be executed to retry launching the application after the installation is finished.

19.2.6 onInstallStarted

This handler is called before the installation of the required component is triggered. For a manual installation scenario, it is called before the installation page is opened.

This hook can be used to provide visual feedback to the user during the installation. The placeholder points to the area that can be used for visualization. For embedded applications, this is the area into which the application will be embedded. If null, then the object called must find a place for display on its own.

In case of automatic launch of the installation, onInstallFinished is called after installation is complete, successfully or not.

If the handler is null, then it is treated as no-op handler.

Function signature:

onInstallStarted: function(placeholder, component, isAuto, restartNeeded)

Parameters:

  • placeholder: The DOM element to insert visual feedback into. If null, then the object called must add visual feedback to the document on its own, for example, embedding the application into a web page.

  • component: String "Java", "JavaFX", or "Java bundle".

  • isAutoInstall: True, if the installer is launched automatically.

  • restartNeeded: Boolean value to specify if a browser restart is required.

19.2.7 onJavascriptReady

This handler is called after the embedded application is ready to accept JavaScript calls.

Function signature:

onJavascriptReady: function(id)

19.2.8 onRuntimeError

This handler is called if the embedded application fails to launch.

Function signature:

onRuntimeError: function(id)

19.3 Examples

This section shows examples of deployment that use the Deployment Toolkit.


Note:

Some of the Deployment Toolkit methods might not be fully operational if used before the web page body is loaded, because the Deployment Toolkit plug-ins cannot be instantiated. If you intend to use the Deployment Toolkit before the web page DOM tree is constructed, then dtjava.js must be loaded inside the <body> element of the page and called before any other Deployment Toolkit APIs.

To initiate deployment, use onload handlers to add the application after the HTML content is loaded, for the following reasons:

  • The DOM tree must exist when the application content is inserted. The DOM tree is created after the HTML content page loads.

  • The Deployment Toolkit's detection code does not prevent loading of the HTML page.

  • The Deployment Toolkit avoids loading concurrently with other resources that are needed for the page.

19.3.1 Embedded Application Starts After the DOM Tree Is Constructed

Example 19-3 shows the default deployment scenario for applications embedded in a web page. The application is added to the web page in the deployIt() function. This function is called after the page is loaded and its DOM tree is constructed. The position of the application in the DOM tree is determined by the value of the placeholder parameter. In this case, the application is inserted into a <div> tag with id="place".

Adding the application to a web page after the main page is loaded helps to get a complete web page, including the embedded application, to load faster, because the application starts concurrently with loading other resources required by the web page.

Note that the value of the placeholder element can be a string or a JavaScript variable pointing to the container DOM node. If that node is detached from the document DOM tree, then the application is not initialized until the parent node is attached to the DOM tree.

Contents    Previous    Next

Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved.