JAVA Web Start provides the power to launch full-featured applications with a single click. Users can download and launch applications, such as a complete spreadsheet program or an Internet chat client, without going through complicated installation procedures.
With Java Web Start, the user can launch a Java application by clicking a link in a Web page. The link points to a JNLP file, which instructs Java Web Start to download, cache, and run the application.
Java Web Start provides Java developers and users with many deployment advantages:
With Java Web Start, you can place a single Java application on a Web server for deployment to a wide variety of platforms, including Windows 2003/Vista/2000/XP, Linux, and Solaris.
Java Web Start supports multiple, simultaneous versions of the Java Standard Edition platform. Specific applications can request specific Java versions without conflicting with the different needs of other applications. Java Web Start automatically downloads and installs the correct version of the Java platform as necessary based on the application’s needs and the user’s environment.
Users can launch a Java Web Start application independent of a Web browser. The user can be offline or unable to access the browser. Desktop shortcuts can also launch the application, providing the user with the same experience as a native application.
Java Web Start takes advantage of the inherent security of the Java platform. By default, applications have restricted access to local disk and network resources. Users can safely run applications from sources that are not trusted.
Applications launched with Java Web Start are cached locally, for improved performance.
Java Web Start provides limited support for applets through its built-in applet viewer. However, this is not intended to be a full-scale applet environment, such as the one provided by Java Plug-in. Java Web Start’s applet viewer has certain limitations; for example, you cannot specify class files as resources, and it does not accept policy files.
In Java version 1.4.2 and beyond, Java Web Start is installed as part of the JRE. Users do not have to install it separately or perform additional tasks to use Java Web Start applications.
This chapter is intended to get you started with Java Web Start and does not include all available documentation. For more information about Java Web Start, see the following:
Users can run Java Web Start applications in the following ways:
Running a Java Web Start application from a browser
Running an application from the Java Cache Viewer
Running a Java Web Start application from the desktop
Note
Users of applications deployed with Java Web Start must have a compatible version of the Java Runtime Environment (JRE). The complete JDK is not required.
You run an application with Java Web Start from a browser simply by clicking a link to the application’s JNLP file, such as:
<a href="Notepad.jnlp">Launch Notepad Application</a>
Java Web Start then loads and runs the application based on instructions in the JNLP file.
If you are using Java Version 1.6.0, you can run a Java Web Start application through the Java Cache Viewer.
When Java Web Start first loads an application, information from the application’s JNLP file is stored in the local Java Cache Viewer. To launch the application again, you do not need to return to the Web page where you first launched it; you can simply open the Java Cache Viewer.
To open the Java Cache Viewer:
Open the Control Panel.
Double-click on the Java icon. The Java Control Panel opens.
Select the General tab.
Click View. The Java Cache Viewer opens.
The application is listed in the viewer as shown in Figure 17.1.
To run the application, select it and click the Run button, 
, or double-click the application. The application starts just as it did from the Web page.
Through the Java Cache Viewer, you can add a shortcut to the application to your desktop. Simply select the application, right-click and select Install Shortcuts, or click the Install button, 
. A shortcut is then added to the desktop as shown in Figure 17.2.
You can then launch the Java Web Start application just as you would any native application.
This section describes the basics of deploying an application using Java Web Start. Deploying an application involves the following steps:
This section uses the Notepad example application to demonstrate Java Web Start technology. You can find all the source files for the Notepad application example in the demopluginjfcNotepad directory within the JDK installation directory.
Before you can deploy an application with Java Web Start over the Web, you must ensure that the Web server you are using can handle JNLP files.
Configure the Web server so that files with the .jnlp extension are set to the application/x-java-jnlp-file MIME type.
How you set the JNLP MIME type depends on the Web server you are using. For example, for the Apache Web server, you simply add the line:
application/x-java-jnlp-file JNLP
to the mime.types file.
For other Web servers, check the documentation for instructions on setting MIME types.
The key to running an application with Java Web Start is the Java Network Launching Protocol, or JNLP, file. The JNLP file is an XML file that contains elements and attributes that tell Java Web Start how to run the application.
Following is the JNLP file for the Notepad demo:[6]
<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for Notepad -->
<jnlp spec="1.0+"
codebase="http://java.sun.com/docs/books/
tutorialJWS/deployment/webstart/examples/"
href="Notepad.jnlp">
<information>
<title>Notepad Demo</title>
<vendor>
The Java(tm) Tutorial: Sun Microsystems, Inc.
</vendor>
<description>Notepad Demo</description>
<homepage href="http://java.sun.com/docs/books/
tutorial/deployment/webstart/running.html"/>
<description kind="short">
ClickMeApp uses 3 custom classes plus several
standard ones
</description>
<offline-allowed/>
</information>
<resources>
<jar href="Notepad.jar"/>
<j2se version="1.6+"
href="http://java.sun.com/products/autodl/j2se"/>
</resources>
<application-desc main-class="Notepad"/>
</jnlp>
Table 17.1 describes the elements and attributes in the sample JNLP file.
Table 17.1. Elements and Attributes of a JNLP File
Element | Attributes | Description | Since | Required |
|---|---|---|---|---|
| This is the main xml element for a JNLP file. Everything is contained within the jnlp element. | 1.0 | yes | |
| The | 1.0 | ||
| The | 1.0 | ||
| The | 1.0 | ||
| The version of the application being launched, as well as the version of the JNLP file itself. | 1.0 | ||
| The | 1.0 | yes | |
| Specifies the operating system for which this information element should be considered. | 1.5.0 | ||
| Specifies the architecture for which this information element should be considered. | 1.5.0 | ||
| Specifies the platform for which this information element should be considered. | 1.5.0 | ||
| Specifies the locale for which this information element should be considered. | 1.5.0 | ||
| The | 1.0 | yes | |
| The | 1.0 | yes | |
| The homepage of the application. | 1.0 | ||
| A URL pointing to where more information on this application can be found. | 1.0 | yes | |
| A short statement describing the application. | 1.0 | ||
| An indicator as to what type of description this is; legal values are | 1.0 | ||
| Describes an icon that can be used to identify the application to the user. | 1.0 | ||
| A URL pointing to the icon file; may be in one of the following formats: gif, jpg, png, ico. | 1.0 | yes | |
| Indicates the suggested use of the icon; can be | 1.0 | ||
| Can be used to indicate the resolution of the image. | 1.0 | ||
| Can be used to indicate the resolution of the image. | 1.0 | ||
| Can be used to indicate the resolution of the image. | 1.0 | ||
| Indicates that this application can operate when the client system is disconnected from the network. | 1.0 | ||
| The | 1.5.0 | ||
| Can be used to describe the application’s preference for creating a shortcut to run online or offline. | 1.5.0 | ||
| Can be used to indicate an application’s preference for putting a shortcut on the user’s desktop. | 1.5.0 | ||
| Can be used to indicate an application’s preference for putting a menu item in the user’s start menus. | 1.5.0 | ||
| Can be used to indicate an application’s preference for where to place the menu item. | 1.5.0 | ||
| Can be used to hint to the JNLP client that it wishes to be registered with the operating system as the primary handler of certain extensions and a certain mime-type. | 1.5.0 | ||
| Contains a list of file extensions (separated by spaces) that the application requests it be registered to handle. | 1.5.0 | ||
| Contains the mime-type that the application requests it be registered to handle. | 1.5.0 | ||
| Describes an additional piece of related content that may be integrated with the application. | 1.5.0 | ||
| A URL pointing to the related content. | 1.5.0 | yes | |
| The | 1.6.0 | ||
| Indicates the preference for when the JNLP client should check for updates. It can be | 1.6.0 | ||
| Indicates the preference for how the JNLP client should handle an application update when it is known that an update is available before the application is launched. It can be | 1.6.0 | ||
| This element can be used to request enhanced permissions. | 1.0 | ||
| Requests that the application be run with all permissions. | 1.0 | ||
| Requests that the application be run with a permission set that meets the security specifications of the J2EE Application Client environment. | 1.0 | ||
| Describes all the resources that are needed for an application. | 1.0 | yes | |
| Specifies the operating system for which the resources element should be considered. | 1.0 | ||
| Specifies the architecture for which the resources element should be considered. | 1.0 | ||
| Specifies that the locales for which the resources element should be considered. | |||
| Specifies what version(s) of Java to run the application with. | 1.6.0 (java) | ||
| Describes an ordered list of version ranges to use. | 1.0 | yes | |
| The URL denoting the supplier of this version of java and where it may be downloaded from. | 1.0 | ||
| Indicates an additional set of standard and nonstandard virtual machine arguments that the application would prefer the JNLP client to use when launching Java. | 1.0 | ||
| Indicates the initial size of the Java heap. | 1.0 | ||
| Indicates the maximum size of the Java heap. | 1.0 | ||
| Specifies a JAR file that is part of the application’s classpath. | 1.0 | yes | |
| The URL of the JAR file. | 1.0 | yes | |
| The requested version of the JAR file. Requires using the version-based download protocol. | 1.0 | ||
| Indicates whether this jar contains the class containing the main method of the application. | 1.0 | ||
| Can be used to indicate that this jar may be downloaded lazily, or when needed. | 1.0 | ||
| Indicates the downloadable size of the JAR file in bytes. | 1.0 | ||
| Can be used to group resources together so they will be downloaded at the same time. | 1.0 | ||
| Specifies a JAR file that contains native libraries in its root directory. | 1.0 | ||
| The URL of the JAR file. | 1.0 | yes | |
| The requested version of the JAR file. Requires using the version-based download protocol. | 1.0 | ||
| Can be used to indicate this jar may be downloaded lazily. | 1.0 | ||
| Indicates the downloadable size of the JAR file in bytes. | 1.0 | ||
| Can be used to group resources together so they will be downloaded at the same time. | 1.0 | ||
| Contains pointer to an additional component-desc or installer-desc to be used with this application. | 1.0 | ||
| The URL to the additional extension JNLP file. | 1.0 | yes | |
| The version of the additional extension JNLP file. | 1.0 | ||
| The name of the additional extension JNLP file. | 1.0 | ||
| Can be used in an extension element to denote the parts contained in a component-extension. | 1.0 | ||
| Describes the name of a part that can be expected to be found in the extension. | 1.0 | yes | |
| Can be used to indicate that this extension may be downloaded eagerly or lazily. | 1.0 | ||
| Denotes the name of a part in this JNLP file to include the extension in. | 1.0 | ||
| Can be used to indicate to the JNLP client which packages are implemented in which JAR files. | 1.0 | ||
| Package name contained in the JAR files of the given part. | 1.0 | yes | |
| Part name containing the JAR files that include the given package name. | 1.0 | yes | |
| Can be used to indicate that all package names, beginning with the given name, can be found in the given part. | 1.0 | ||
| Defines a system property that will be available through the | 1.0 | ||
| Name of the system property. | 1.0 | yes | |
| Value it will be set to. | 1.0 | yes | |
Note: A JNLP file must contain one of | 1.0 | yes | ||
| Denotes this is the JNLP file for an application. | 1.0 | ||
| The name of the class containing the | 1.0 | yes | |
| Each argument contains (in order) an additional argument to be passed to main. | 1.0 | ||
| Denotes this is the JNLP file for an applet. | 1.0 | ||
| This is the name of the main applet class. | 1.0 | yes | |
| The document base for the applet as a URL. | 1.0 | ||
| Name of the applet. | 1.0 | yes | |
| The width of the applet in pixels. | 1.0 | yes | |
| The height of the applet in pixels. | 1.0 | yes | |
| A set of parameters that can be passed into the applet. | 1.0 | ||
| The name of this parameter. | 1.0 | yes | |
| The value of this parameter. | 1.0 | yes | |
| Denotes this is the JNLP file for a component extension. | 1.0 | ||
| Denotes this is the JNLP file for an installed extension. | 1.0 | ||
| The name of the class containing the | 1.0 | yes |
Note
This table does not include all possible contents of the JNLP file. For more information, see the Java Network Launching Protocol & API Specification (JSR-56).[7]
Java Web Start supports encoding of JNLP files in any character encoding supported by the Java platform. For more information on character encoding in Java, see the Supported Encodings Guide.[8] To encode a JNLP file, specify an encoding in the XML prolog of that file. For example, the following line indicates that the JNLP file is encoded in UTF-16:
<?xml version="1.0" encoding="utf-16"?>
The next step in deploying your application with Java Web Start is as simple as placing all the application’s JAR files and the JNLP file on the Web server. You must ensure the JAR files are in the locations specified by the href attribute of the jar element in the JNLP file.
Once you’ve completed the preceding steps, you are ready to write a Web page that gives users access to your application. Adding a link to your application in a Web page for users with Java Web Start already installed is simple; however, you must also design your Web page for users that might not have Java Web Start installed.
In order to enable your users to launch the application from a Web page, you must include a link to the application’s JNLP file from that Web page. To add this link, you use the standard HTML link syntax, with the href attribute specifying the location of the JNLP file:
<a href="Notepad.jnlp">Launch Notepad Application</a>
Assuming Java Web Start is installed on the client computer, when the user clicks this link, Java Web Start executes the application based on the instructions in the JNLP file.
For users who might not have Java Web Start installed, you must write scripts in your Web page to:
Detect which browser the user has.
Detect whether Java Web Start is installed.
If Java Web Start is not installed, either auto-install it or direct the user to a download page.
For more information and sample scripts to use for these steps, see the Java Web Start Guide.
For the most part, you develop applications to be deployed through Java Web Start just as you would develop stand-alone Java applications. However, there are some packaging considerations, which are described in the following sections.
To deploy an application with Java Web Start, you must package the application as one or more JAR files. In particular, you must package the application’s files into one or more JAR files.
Note
Other resources such as images and property files can, if necessary, be outside of JAR files and retrieved using HTTP requests. However, storing resources in JAR files is preferred, because JAR files are cached on the local computer by Java Web Start.
If the application needs unrestricted access to the local system, all JAR files and entries must be signed. For more information, see the Java Web Start and Security section (page 538).
Use the getResource method to read resources from a JAR file. For example, the following code example retrieves images from a JAR file:
// Get current classloader
ClassLoader cl = this.getClass().getClassLoader();
// Create icons
Icon saveIcon = new
ImageIcon(cl.getResource("images/save.gif"));
Icon cutIcon = new
ImageIcon(cl.getResource("images/cut.gif"));
The example assumes that the following entries exist in the JAR files for the application:
images/save.gifimages/cut.gif
Unless you sign your application’s JAR files, which requires users to accept your certificate, your application deployed through Java Web Start is untrusted. Untrusted applications have the following restrictions:
The application cannot access the local disk.
All JAR files for the application must be downloaded from the same server.
The application can only make network connections to the server from which the JAR files were downloaded.
A security manager cannot be removed or replaced.
The application cannot use native libraries.
The application has limited access to system properties. The application has read/write access to a set of system properties known to be secure and read-only access to the same set of properties as an applet.
For more information, see the Java Web Start and Security section (page 538).
Also, see the next section for information on using the special Java Web Start packages in your applications.
The Java platform includes the JNLP API to enable you to provide additional information to applications deployed through Java Web Start.
The JNLP API is included in the javax.jnlp package, which is delivered in the jnlp.jar as part of the Java Development Kit version 6, in the sample/jnlp/servlet directory. The javax.jnlp package is also delivered in the javaws.jar, which is located in the JRE’s lib directory.
Table 17.2 provides an overview of the main interfaces and classes in the javax.jnlp package. For more information, see the API documentation and the Java Web Start Guide.
Table 17.2. Interfaces and Classes in the javax.jnlp Package
This section describes the basics of security for applications deployed through Java Web Start.
Applications launched with Java Web Start are, by default, run in a restricted environment, known as a sandbox. In this sandbox, Java Web Start:
Protects users against malicious code that could affect local files
Protects enterprises against code that could attempt to access or destroy data on networks
Unsigned JAR files launched by Java Web Start remain in this sandbox, meaning they cannot access local files or the network.
Java Web Start supports signed JAR files so that your application can work outside of the sandbox described above, enabling the application to access local files and the network.
Java Web Start verifies that the contents of the JAR file have not changed since it was signed. If verification of a digital signature fails, Java Web Start does not run the application.
When the user first runs an application as a signed JAR file, Java Web Start opens a dialog box displaying the application’s origin based on the signer’s certificate. The user can then make an informed decision regarding running the application.
For more information, see the Signing and Verifying JAR Files section (page 507).
For a signed JAR file to have access to the local file system and network, you must specify security settings in the JNLP file. The security element contains security settings for the application.
The following example provides the application with complete access to the client system if all of its JAR files are signed:
<security> <all-permissions/> </security>
Java Web Start dynamically imports certificates as browsers typically do. To do this, Java Web Start sets its own https handler, using the java.protocol.handler.pkgs system properties, to initialize defaults for the SSLSocketFactory[9] and HostnameVerifier.[10] It sets the defaults with the methods HttpsURLConnection. setDefaultSSLSocketFactory[11] and HttpsURLConnection.setDefaultHostnameVerifier.
If your application uses these two methods, ensure that they are invoked after the Java Web Start initializes the https handler, otherwise your custom handler will be replaced by the Java Web Start default handler.
You can ensure that your own customized SSLSocketFactory and HostnameVerifiter are used by doing one of the following:
Install your own
httpshandler to replace the Java Web Starthttpshandler. For more information, see the document A New Era for Java Protocol Handlers.[12]In your application, invoke
HttpsURLConnection.setDefaultSSLSocketFactoryorHttpsURLConnection.setDefaultHostnameVerifieronly after the firsthttps URLobject is created, which executes the Java Web Starthttpshandler initialization code first.
Problem: My browser shows the JNLP file for my application as plain text. Most likely, your Web server is not aware of the proper MIME type for JNLP files. See the Setting Up the Web Server section (page 525) for more information.
Furthermore, if you are using a proxy server, ensure that the update versions of the files are returned by updating the time stamp of the resources on the Web server such that the proxies will update their caches.
Problem: When I click on a link to a JNLP file with Internet Explorer and Java Web Start launches, I get the message “Could not load file/URL specified: C:Documents and Settings…application[1].jnlp”. This problem only occurs with Internet Explorer. It is usually caused by a no-cache directive from the Web or proxy server, which causes Internet Explorer to not write the JNLP file to the local disk.
This frequently happens when you upgrade a Tomcat-based server, as later versions set the no-cache directive by default for any resource that is within a security constraint in the
web.xmlfile. Try removing the relevant URI from the security constraint.This problem can also occur because of a full cache or if the cache is turned off in Internet Explorer.
Problem: My browser seems to find the JNLP file, but Java Web Start says it can’t find it. The most likely cause is that your browser and Java Web Start have different proxy settings. To modify Java Web Start proxy settings:
[1] docs/technotes/guides/javaws/developersguide/contents.html
[2] docs/technotes/guides/javaws/developersguide/faq.html
[4] docs/jre/api/javaws/jnlp/index.html
[6] docs/books/tutorialJWS/deployment/webstart/examples/Notepad.jnlp
[8] docs/technotes/guides/intl/encoding.doc.html
[9] docs/api/javax/net/ssl/SSLSocketFactory.html
[10] docs/api/javax/net/ssl/HostnameVerifier.html
[11] docs/api/javax/net/ssl/HttpsURLConnection.html
[12] http://java.sun.com/developer/onlineTraining/protocolhandlers/