Deployment in the Browser

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.

17.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.

17.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 17.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.

17.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)

17.2.3 onGetSplash

This handler gets the content of the splash screen when the application is embedded in a browser.

Function signature:

onGetSplash: function(app)

Gets the application launch descriptor as input. If null is returned, then the splash screen is disabled. A non-null return value is expected to be a HTML code to be added into the splash overlay. Note that the splash overlay does not enforce any specific size. You must ensure that the custom splash image is sized to fit the area in which the application will run.

For examples of customizing the splash screen, see Section 17.3.7, "Add a Custom HTML Splash Screen" and Section 17.3.6, "Disable the HTML Splash Screen."

Note:

Automatically hiding the splash screen is only supported by JavaFX applications. If you are deploying a Swing applet, then the application must call dtjava.hideSplash() explicitly to hide the splash screen. See Example 6-6 on the Swing deployment page.

17.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.

17.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.

17.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.

17.2.7 onJavascriptReady

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

Function signature:

onJavascriptReady: function(id)

17.2.8 onRuntimeError

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

Function signature:

onRuntimeError: function(id)

17.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.

17.3.1 Embedded Application Starts After the DOM Tree Is Constructed

Example 17-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.

Example 17-3 Insert the Application into the HTML Body with a Placeholder

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function deployIt() {
            dtjava.embed(
                    {         id: "myApp",
                             url: "Fish.jnlp",
                           width: 300,
                          height: 200,
                     placeholder: "place"
                    },
                    { javafx: "2.2+" },
                    {}
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>           
</body>

17.3.2 Launch a Web Start Application from a Web Page

The canonical form for the link to launch a Java Web Start application is shown in Example 17-4. Either relative or absolute links are acceptable.

Example 17-4 Canonical Link to Launch a Web Start Application

<a href="my.jnlp" 
   onclick="dtjava.launch(new dtjava.App('my.jnlp')); 
   return false;">Launch me!</a>

An alternative simplified syntax is shown in Example 17-5.

Example 17-5 Link to Launch a Web Start Application, Simplified

<a href="my.jnlp" 
   onclick="dtjava.launch({url: 'my.jnlp'}); 
   return false;">Launch me!</a>

A third form for simple applications is shown in the following example.

Example 17-6 Link to Launch a Web Start Application, Third Example

<a href="my.jnlp" 
   onclick="dtjava.launch('my.jnlp'); 
   return false;">Launch me!</a>

If JavaScript is disabled in the browser, the Deployment Toolkit does not work. In this case, the browser tries to use the href attribute. If the JRE is installed, then the application launches. The return false; statement ensures that the browser does not leave the current page if the launch is successful.

17.3.3 Pass Parameters to a Web Application

You can pass dynamic parameters to applications from a web page. For this you need to add a set of named parameters as the params attribute of the application descriptor.

In Example 17-7, the embedded application gets two dynamic parameters from the web page. Note that the "zip" parameter is assigned with the value of the JavaScript variable.

Example 17-7 Pass Parameters to an Embedded Application

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function deployIt() {
            var zipcode = 95054;
 
            dtjava.embed(
                {            id: "myApp",
                            url: "Map.jnlp",
                          width: 300,
                         height: 200,
                    placeholder: "place",
                    params: {
                              mode: "streetview",
                              zip: zipcode
                    }
                },
                { javafx: "2.2+" },
                {}
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

The same approach works for Java Web Start applications if the user has JRE 7u6 or later. Here is an example:

Example 17-8 Pass Parameters to a Web Start Application

<script>
    var zipcode = 95054;
 
    function launchApp() {
        dtjava.launch(
            {   url: 'my.jnlp',
                params: {
                           mode: "streetview",
                           zip: zipcode
                }
            },
            {   javafx : '2.2+'  },
            {}
        );
        return false;
    }
</script>
 
<a href="my.jnlp" onclick="launchApp(); return false;">
    Launch me!
</a>

To access parameters in the application code, use the getParameters() method of the Application class, for example:

String zipcode = app.getParameters().getNamed("zip");

17.3.4 Specify Platform Requirements and Pass JVM Options

Use the second argument group of the dtjava.embed() function to specify platform requirements for the application.

In Example 17-9, JRE 1.7 or later is specified in the jvm parameter; JavaFX 2.2 or later is specified in the javafx parameter; and the jvmargs parameter indicates that the application should be executed in the Java Virtual Machine (JVM) with a 1 gigabyte heap size and given options.

Example 17-9 Specify Platform Requirements and Passing JVM Properties

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function deployIt() {
            dtjava.embed(
                {            id: "my",
                            url: "app.jnlp",
                          width: 300,
                         height: 200,
                    placeholder: "place"
                },
                {
                        jvm: "1.7.0+",
                     javafx: "2.2+",
                    jvmargs: "-Dapp.property=somevalue -Xmx1024m"
                }
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

17.3.5 Access Your Code from JavaScript

To access a Java or JavaFX application from JavaScript, you must get a reference to the JavaScript object representing the application. Specify an id parameter in the first argument group of the dtjava.embed() function, as shown in Example 17-3.

For example, if an id parameter is set to my, then a public method of the application can be accessed with the script shown in Example 17-10.

Example 17-10 Access an Application Method with an id Parameter

<script>
    var a = document.getElementById("my");
    a.java_method();
</script>

Attempts to call application methods might not work until the application finishes the initialization phase. For a description of startup phases, see Section 4.2, "Application Startup Process, Experience, and Customization." To access an application while it is loading, use an onJavascriptReady callback, as shown in Example 17-11.

Example 17-11 Access an Application Method While the Application Is Loading

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function callApp(id) {
            //it is safe to call now
            var a = document.getElementById(id);
            a.java_method();
        }
        function deployIt() {
            dtjava.embed(
                {            id: "my",
                            url: "fxapp.jnlp",
                          width: 300,
                         height: 200,
                    placeholder: "place"
                    },
                    {},
                    {
                        onJavascriptReady: callApp
                    }
 
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

17.3.6 Disable the HTML Splash Screen

To disable the HTML splash screen for a JavaFX application, add an onGetSplash handler that returns null:, as shown in Example 17-12. For information about application startup phases, see Section 4.2, "Application Startup Process, Experience, and Customization."

Example 17-12 Disable the HTML Splash Screen

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function deployIt() {
            dtjava.embed(
                {            id: "my",
                            url: "app.jnlp",
                          width: 300,
                         height: 200,
                    placeholder: "place"
                },
                {
                       jvm: "1.7.0+",
                    javafx: "2.2+",
                },
                {
                    onGetSplash: function(app) {return null;}
                }
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

If you are deploying a Swing applet, then the application must call dtjava.hideSplash() explicitly to hide the splash screen.

17.3.7 Add a Custom HTML Splash Screen

Example 17-13 shows how to replace the default HTML splash screen with a green rectangle, defined in a JavaScript function.

Example 17-13 Replace the Splash Screen with a Custom One

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function getSplash(app) {
            //custom splash - green rectangle
            var p = document.createElement('div');
            p.style.width  = app.width;
            p.style.height = app.height;
            p.style.background="green";
            return p;             
        }
         
        function deployIt() {
            dtjava.embed(
                {            id: "my",
                            url: "app.jnlp",
                          width: 300,
                         height: 200,
                    placeholder: "place"
                },
                {
                       jvm: "1.7.0+",
                    javafx: "2.2+",
                },
                {
                    onGetSplash: getSplash
                }
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

17.3.8 Create a Handler for an Unsupported Platform

Example 17-14 shows the use of JavaScript to handle an unsupported browser.

Example 17-14 Handle an Unsupported Browser with JavaScript

<head>
    <script type="text/javascript" src="http://java.com/js/dtjava.js"></script>
    <script>
        function reportError(app, r) {
            //ovewrite behavior for unsupported browser
            var a = app.placeholder;
            if (a != null && r.isUnsupportedBrowser()) {
                var p = document.createElement('div');
                p.id = "splash";
                p.style.width  = app.width;
                p.style.height = app.height;
                p.style.background="red";
                p.appendChild(
                  document.createTextNode("This browser is not supported."));
 
                //clear embedded application placeholder
                while(a.hasChildNodes()) a.removeChild(a.firstChild);
 
                //show custom message
                a.appendChild(p);
            } else {
                //use default handlers otherwise
                var def = new dtjava.Callbacks();
                return def.onDeployError(app, r);
            }
        }
         
        function deployIt() {
            dtjava.embed(
                {       id: "my",
                       url: "app.jnlp",
                     width: 300,
                    height: 200
                },
                {
                       jvm: "1.7.0+",
                    javafx: "2.2+",
                },
                {
                    onDeployError: reportError
                }
            );
        }
        dtjava.addOnloadCallback(deployIt);
    </script>
</head>
<body>
    <div id="place"></div>
</body>

17.3.9 Check for Presence of JavaFX Runtime

Example 17-15 shows the use of JavaScript to replace the default text offering to install JavaFX. It is replaced with an offer to start the application only if the correct version of JavaFX is found on the user's system.

Example 17-15 Launch Only If JavaFX Is Installed

<html>
    <head>
        <script type="text/javascript" 
                src="http://java.com/js/dtjava.js"></script>
        <script>
            function mayBeOfferLaunch() {
                var platform = new dtjava.Platform({'javafx' : '2.2+'});
 
                //check if validate find any problems
                if (dtjava.validate(platform) == null) {
                    var t = document.getElementById("text");
                    t.innerHTML = "<a href='my.jnlp' " +
                    "onclick='dtjava.launch({url: 'my.jnlp'}); return false;'>" +
                    "Launch me!</a>";
                }
            }
            dtjava.addOnloadCallback(mayBeOfferLaunch);
        </script>
    </head>
    <body>
        <div id="text">To view this content you need 
       <a href="http://javafx.com">to install 
           JavaFX Runtime 2.2</a>.</div>
    </body>
</html>

17.2.1 onDeployError

17.2.2 onGetNoPluginMessage

17.2.3 onGetSplash

17.2.4 onInstallFinished

17.2.5 onInstallNeeded

17.2.6 onInstallStarted

17.2.7 onJavascriptReady

17.2.8 onRuntimeError

17 Deployment in the Browser

17.1 API Overview

17.1.1 Application Descriptor (dtjava.App)

17.1.2 Platform (dtjava.Platform)

17.2 Callbacks

17.3 Examples

17.3.1 Embedded Application Starts After the DOM Tree Is Constructed

17.3.2 Launch a Web Start Application from a Web Page

17.3.3 Pass Parameters to a Web Application

17.3.4 Specify Platform Requirements and Pass JVM Options

17.3.5 Access Your Code from JavaScript

17.3.6 Disable the HTML Splash Screen

17.3.7 Add a Custom HTML Splash Screen

17.3.8 Create a Handler for an Unsupported Platform

17.3.9 Check for Presence of JavaFX Runtime