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.

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

var app = new dtjava.App(
        'ssh.jnlp', 
    {
        id: 'SSH',
        width: 100,
        height: 25,
        placeholder: 'SSH_application_container', 
        params: { 
            config: 'ssh_application.conf', 
        } 
    }
); 

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:

var platform = new dtjava.Platform({
                    javafx: "2.2+",
                   jvmargs: "-Dapp.property= ? -Xmx1024m"
                 });

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.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.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 19.3.7, "Add a Custom HTML Splash Screen" and Section 19.3.6, "Disable the HTML Splash Screen."

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

<head>
    <script type="text/javascript" src="//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>

19.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 19-4. Either relative or absolute links are acceptable.

<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 19-5.

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

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

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

<head>
    <script type="text/javascript" src="//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:

<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");

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

<head>
    <script type="text/javascript" src="//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>

19.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 19-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 19-10.

<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 19-11.

<head>
    <script type="text/javascript" src="//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>

19.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 19-12. For information about application startup phases, see Section 4.2, "Application Startup Process, Experience, and Customization."

<head>
    <script type="text/javascript" src="//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.

19.3.7 Add a Custom HTML Splash Screen

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

<head>
    <script type="text/javascript" src="//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>

19.3.8 Create a Handler for an Unsupported Platform

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

<head>
    <script type="text/javascript" src="//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>

19.3.9 Check for Presence of JavaFX Runtime

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

<html>
    <head>
        <script type="text/javascript" 
                src="//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>