Sun GlassFish Enterprise Server v2.1.1 Developer's Guide

Using Java Web Start

Java Web Start allows your application client to be easily launched and automatically downloaded and updated. General information about Java Web Start is available at http://java.sun.com/products/javawebstart/reference/api/index.html.

Java Web Start is discussed in the following topics:

Enabling and Disabling Java Web Start

Java Web Start is enabled for all application clients by default.

The application developer or deployer can specify that Java Web Start is always disabled for an application client by setting the value of the eligible element to false in the sun-application-client.xml file. See the Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.

The Enterprise Server administrator can disable Java Web Start for a previously deployed eligible application client using the asadmin set command.

To disable Java Web Start for all eligible application clients in an application, use the following command:


asadmin set --user adminuser 
domain1.applications.j2ee-application.app-name.java-web-start-enabled="false"

To disable Java Web Start for a stand-alone eligible application client, use the following command:


asadmin set --user adminuser 
domain1.applications.appclient-module.module-name.java-web-start-enabled="false"

Setting java-web-start-enabled="true" re-enables Java Web Start for an eligible application client. For more information about the asadmin set command, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.

Downloading and Launching an Application Client

If Java Web Start is enabled for your deployed application client, you can launch it for testing. Simply click on the Launch button next to the application client or application's listing on the App Client Modules page in the Admin Console.

On other machines, you can download and launch the application client using Java Web Start in the following ways:

When you launch an application client, Java Web Start contacts the server to see if a newer client version is available. This means you can redeploy an application client without having to worry about whether client machines have the latest version.

The Application Client URL

The default URL for an application or module generally is as follows:


http://host:port/context-root

The default URL for a stand-alone application client module is as follows:


http://host:port/appclient-module-id

The default URL for an application client module embedded within an application is as follows. Note that the relative path to the application client JAR file is included.


http://host:port/application-id/appclient-path

If the context-root, appclient-module-id, or application-id is not specified during deployment, the name of the JAR or EAR file without the extension is used. If the application client module or application is not in JAR or EAR file format, an appclient-module-id or application-id is generated.

Regardless of how the context-root or id is determined, it is written to the server log. For details about naming, see Naming Standards in Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.

To set a different URL for an application client, use the context-root subelement of the java-web-start-access element in the sun-application-client.xml file. This overrides the appclient-module-id or application-id. See Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.

You can also pass arguments to the ACC or to the application client's main method as query parameters in the URL. If multiple application client arguments are specified, they are passed in the order specified.

A question mark separates the context root from the arguments. Ampersands (&) separate the arguments and their values. Each argument and each value must begin with arg=. Here is an example URL with a -color argument for a stand-alone application client. The -color argument is passed to the application client's main method.


http://localhost:8080/testClient?arg=-color&arg=red

Note –

If you are using the javaws URL command to launch Java Web Start with a URL that contains arguments, enclose the URL in double quotes (") to avoid breaking the URL at the ampersand (&) symbol.


Ideally, you should build your production application clients with user-friendly interfaces that collect information which might otherwise be gathered as command-line arguments. This minimizes the degree to which users must customize the URLs that launch application clients using Java Web Start. Command-line argument support is useful in a development environment and for existing application clients that depend on it.

Signing JAR Files Used in Java Web Start

Java Web Start enforces a security sandbox. By default it grants any application, including application clients, only minimal privileges. Because Java Web Start applications can be so easily downloaded, Java Web Start provides protection from potentially harmful programs that might be accessible over the network. If an application requires a higher privilege level than the sandbox permits, the code that needs privileges must be in a JAR file that was signed. When Java Web Start downloads such a signed JAR file, it displays information about the certificate that was used to sign the JAR, and it asks you whether you want to trust that signed code. If you agree, the code receives elevated permissions and runs. If you reject the signed code, Java Web Start does not start the downloaded application.

The Enterprise Server serves two types of signed JAR files in response to Java Web Start requests. One type is a JAR file installed as part of the Enterprise Server, which starts an application client during a Java Web Start launch: as-install/lib/appserv-jwsacc.jar.

The other type is a generated application client JAR file. As part of deployment, the Enterprise Server generates a new application client JAR file that contains classes, resources, and descriptors needed to run the application client on end-user systems. When you deploy an application with the asadmin deploy command's --retrieve option, use the asadmin get-client-stubs command, or select the Generate RMIStubs option from the EJB Modules deployment page in the Admin Console, this is the JAR file retrieved to your system. Because application clients need access beyond the minimal sandbox permissions to work in the Java Web Start environment, the generated application client JAR file must be signed before it can be downloaded to and executed on an end-user system.

A JAR file can be signed automatically or manually. The following sections describe the ways of signing JAR files.

Automatically Signing JAR Files

The Enterprise Server automatically creates a signed version of the required JAR file if none exists. When a Java Web Start request for the appserv-jwsacc.jar file arrives, the Enterprise Server looks for domain-dir/java-web-start/appserv-jwsacc.jar. When a request for an application's generated application client JAR file arrives, the Enterprise Server looks in the directory domain-dir/java-web-start/app-name for a file with the same name as the generated JAR file created during deployment.

In either case, if the requested signed JAR file is absent or older than its unsigned counterpart, the Enterprise Server creates a signed version of the JAR file automatically and deposits it in the relevant directory. Whether the Enterprise Server just signed the JAR file or not, it serves the file from the domain-dir/java-web-start directory tree in response to the Java Web Start request.

To sign these JAR files, the Enterprise Server uses its self-signed certificate. When you create a new domain, either by installing the Enterprise Server or by using the asadmin create-domain command, the Enterprise Server creates a self-signed certificate and adds it to the domain's key store.

A self-signed certificate is generally untrustworthy because no certification authority vouches for its authenticity. The automatic signing feature uses the same certificate to create all required signed JAR files. To sign different JAR files with different certificates, do the signing manually.

Manually Signing appserv-jwsacc.jar

You can sign the appserv-jwsacc.jar file manually any time after you have installed the Enterprise Server. Copy the unsigned file from as-install/lib to a different working directory and use the jarsigner command provided with the JDK to create a signed version of exactly the same name using your certificate. Then manually copy the signed file into domain-dir/java-web-start. From then on, the Enterprise Server serves the JAR file signed with your certificate whenever a Java Web Start request asks that domain for the appserv-jwsacc.jar file. Note that you can sign each domain's appserv-jwsacc.jar file differently.

Remember that if you create a new domain and do not sign appserv-jwsacc.jar manually for that domain, the Enterprise Server creates an auto-signed version of it for use by the new domain. Also, if you create a domain-specific signed appserv-jwsacc.jar, delete the domain, and then create a new domain with the same name as the just-deleted domain, the Enterprise Server does not remember the earlier signed appserv-jwsacc.jar. You must recreate the manually signed version.

Manually Signing the Generated Application Client JAR File

You can sign the generated application client JAR file for an application any time after you have deployed the application. As you deploy the application, you can specify the asadmin deploy command's --retrieve option or select the Generate RMIStubs option on the EJB Modules deployment page in the Admin Console. Doing either of these tasks returns a copy of the generated application client JAR file to a directory you specify. Or, after you have deployed an application, you can download the generated application client JAR file using the asadmin get-client-stubs command.

Once you have a copy of the generated application client JAR file, you can sign it using the jarsigner tool and your certificate. Then place the signed JAR file in the domain-dir/java-web-start/app-name directory. You do not need to restart the server to start using the new signed JAR file.

Error Handling

When an application client is launched using Java Web Start, any error that the application client logic does not catch and handle is written to System.err and displayed in a dialog box. This display appears if an error occurs even before the application client logic receives control. It also appears if the application client code does not catch and handle errors itself.

Vendor Icon, Splash Screen, and Text

To specify a vendor-specific icon, splash screen, text string, or a combination of these for Java Web Start download and launch screens, use the vendor element in the sun-application-client.xml file. The complete format of this element's data is as follows:

<vendor>icon-image-URI::splash-screen-image-URI::vendor-text</vendor>

The following example vendor element contains an icon, a splash screen, and a text string:

<vendor>images/icon.jpg::otherDir/splash.jpg::MyCorp, Inc.</vendor>

The following example vendor element contains an icon and a text string:

<vendor>images/icon.jpg::MyCorp, Inc.</vendor>

The following example vendor element contains a splash screen and a text string; note the initial double colon:

<vendor>::otherDir/splash.jpg::MyCorp, Inc.</vendor>

The following example vendor element contains only a text string:

<vendor>MyCorp, Inc.</vendor>

The default value is the text string Application Client.

For more information about the sun-application-client.xml file, see the Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.