Java

README

Java TM Web Start

Version 1.0.1

 

 Please send comments and feedback to javawebstart-feedback@eng.sun.com.

Table of Contents

Introduction
Using Java Web Start
System Requirements
Installation Instructions
Adding a new JRE
JNLP Specification Conformance
Changes

Introduction

Java Web Start is a new deployment technology for Java TM technology-based applications.  It is the plumbing between the computer and the Internet that allows the user to launch and manage applications right off the Web. Java Web Start provides easy, one-click activation of applications, and guarantees that you are always running the latest version, eliminating complicated installation or upgrade procedures.

Traditionally, distributing software across the Web, requires the user to find the installer on the Web, download the installer, locate the installer, and execute the installer. Once, the installer is executed, it prompts for installation directories and installation options such as full, typical, or minimum. This is typically a time-consuming and complicated task, and it has to be repeated for each new version of the software.

In contrast, Web-deployed applications, such as your favorite HTML-based email client and calendar,  auction sites, and so on, are a breeze to install and use. The Web browser has automated the entire process. There is no complicated download, setup, and configuration steps, and you are guaranteed to always be running the latest version.

Java Web Start provides the same benefits to full-featured applications as described above for HTML-based applications. Java Web Start is an application deployment solution for the Web. Using a full-featured application instead of an HTML-based client can have many benefits:

The trade-off is that you have to download the application the first-time. An HTML-based application has a very low first time activation cost. Typically, a Web page is brought up in a matter of seconds. A Java TM technology-based application will require download times in the order of minutes on a typical modem connection. Java Web Start caches all downloaded files locally on the computer. Thus, although the first-time activation cost is higher for applications than for HTML pages, the subsequent times you launch an application, it will be launched almost instantaneously, since all the required resources are already available locally.

On each launch, Java Web Start checks the Web server to see if a new version of the application is available, and automatically downloads and launches it. Thus, applications are automatically brought up-to-date. There is no complicated upgrade procedure.

Security

Java Web Start is built on top of the Java 2 platform, which provides a comprehensive security architecture. Applications launched with Java Web Start will, by default, run in a restricted environment ("sandbox") with limited access to files and network. Thus, launching applications using Java Web Start maintains system security and integrity.

An application can request unrestricted access to your system. In this case, Java Web Start will show a Security Warning dialog when the application is launched for the first time. The security warning will show information about the origin of the application, i.e., the vendor who developed the application. If you choose to trust the vendor, then the application will be launched. The information about the origin of the application is based on digital code signing.

Using Java Web Start

Java Web Start allows you to launch Java technology-based application directly from the Web. An application can be launched in three different ways: The application runs the same no matter which method you choose to launch it. In particular, Java Web Start is always going to connect back to the Web server to check for an updated version of the particular application.

Launching from a Web browser

On the Java Web Start product page (http://java.sun.com/products/javawebstart), there are links to a number of applications that can be launched with a single click of a mouse. Try launching the different applications by clicking on the launch buttons. The Web browser will launch Java Web Start, which will then download, cache, and execute the given application. You will notice that the second time you launch an application, it starts much quicker since it is already present locally and does not need to be downloaded again.

Most of the demos on the page are just downloaded and executed without any user intervention. These applications run in a restricted environment, where they are prevented from accessing the local disk and network, and can be guaranteed not to install any viruses on your computer.

Some demos require extra privileges, such as access to your local hard disk. For these applications, a security dialog will pop up with information about the origin of the application based on who digitally signed the code. The application will run only if you decide to trust the vendor.

That is really all there is to using Java Web Start, but how does it work? The HTML links that launch the applications are, in fact, standard HTML links. However, instead of pointing to another Web page, they link to a special configuration file called a JNLP file. The Web browser examines the file extension and/or the MIME type of the file, and sees that it belongs to Java Web Start. It then launches Java Web Start with the downloaded JNLP file as an argument. Java Web Start shows a splash screen and proceeds with downloading, caching, and running the application as directed by the JNLP file. 

Launching from the built-in Application Manager

The Application Manager is a built-in part of Java Web Start. It lets you quickly and easily launch applications that have previously been launched by Java Web Start. It is a combination of a History menu and a Start/Programs menu for your Web deployed Java technology-based applications. The Application Manager also allows you to see additional information about an application, and go the home page of a particular application.

You launch an application from the Application Manager by double clicking on the application icon or by clicking the launch button.

Another important feature of the Application Manager is the Preferences dialog which lets you examine and modify settings used by Java Web Start. For example, this includes tabs which allow you to:

The Application Manager is launched by either clicking on the Java Web Start icon on the desktop or in the Start Menu on Windows. On Solaris/Linux, it is launched by invoking the javaws command in the Java Web Start installation directory. The Application Manager can also be launched from a Web browser. The product page (http://java.sun.com/products/javawebstart) shows an example of this.

Launching from desktop icons and the Start Menu (Windows only)

Java Web Start can automatically create shortcuts on the Windows desktop and in the Start Menu for Web deployed Java technology-based applications. By default, Java Web Start asks the second time an application is launched, if a shortcut should be created. This can be changed using the Preference panel.

Shortcuts can also be added and removed by using the Application Manager, using the Application/Create Shortcut, and using Application/Remove Shortcut menu item.

Using Java Web Start Behind a Proxy Server/Firewall

Java Web Start must be configured with the correct proxy settings in order to launch applications from outside your firewall. Java Web Start will automatically try to detect the proxy settings from the default browser on your system (IE or Netscape on Windows, and Netscape on Solaris/Linux). Java Web Start supports most web proxy auto-configuration scripts. It can detect proxy settings in almost all environments.

If the proxy setting cannot be automatically detected, then you will be prompted to specify the proxy settings the first time you use Java Web Start. Java Web Start will also prompt you for a user name and password required to access an authenticating proxy server. This user name and password will be stored for the current invocation of Java Web Start. However, at the time a newly invoked Java Virtual Machine, if accessing a secure web site, will prompt you for the user name and password since this information is stored within a Java Virtual Machine instance.

You can also use the Java Web Start Preferences panel to view or edit the proxy configuration. Launch the Application Manager, either by clicking on the icon on the desktop (Windows), or type ./javaws in the Java Web Start installation directory (Solaris/Linux), and then select Edit/Preferences.  If you are in an environment where access to the Web is through a proxy server, you are encouraged to use the Java Web Start Preferences panel to check that these are set-up correctly.
 

System Requirements

This release of Java Web Start has been tested following systems: The platform requirements for using Java Web Start are the same as recommended for JRE implementations.

Installation Instructions

Upgrading from the 1.0 release

The 1.0 release does not have to be uninstalled before the 1.0.1 release is installed. However, the installation for 1.0.1 will overwrite the 1.0 release, and update the browsers to use the new 1.0.1 release. To reactivate the 1.0 release, you will need to re-installed it.

The 1.0 and 1.0.1 uses the same configuration files and program files folder, so all your settings should be kept the same after the upgrade.

On Windows, a special upgrade bundle that does not include a Java Runtime Environment is provided. It is recommended to download and install that if you already got Java Web Start 1.0 installed.

Upgrading from the 1.0-beta release

The cache layout and the location of javaws.cfg have changed between 1.0-beta and this release. This can, in rare circumstances, cause Java Web Start 1.0.1 not to work. Cleaning the user-local configuration directory should solve this problem. It is located at ~/.javaws/ on Solaris/Linux, and typically on C:\Windows\Profiles\.javaws or C:\Windows\Profiles\<username>\.javaws on Windows.

Installing on Windows 95/98/NT/2000

Download the javaws-1_0_1-win-us-rt.exe file from the java.sun.com Web site by clicking on the Download Now icon. Then locate and execute the downloaded file. This will launch a standard Windows-style installer that will guide you through the installation. The installer prompts for the installation directory (default is c:\Program Files\Java Web Start). Most likely, this will be acceptable. Click the next button, and the installer will install all necessary files and settings for Java Web Start. The installer will prompt you to restart the Netscape Navigator browser if it is running.

The installer looks in the Windows Registry for already installed Java Runtime Environments (JREs), version 1.2 and higher, and automatically configures Java Web Start to use them. The installer will also install Java 2 Runtime Environment 1.3.0 if it is not present.

The installation registers the file extension .jnlp and the MIME type application/x-java-jnlp-file with Windows, so Java Web Start will be launched from both Netscape Navigator and Internet Explorer (and most other browsers) when a link to a JNLP file is activated. The installer also installs shortcuts to the Application Manager on the desktop and in the Windows Start menu.

Installing on Solaris/Linux

The Solaris and Linux versions of Java Web Start is delivered as a ZIP file. The ZIP file contains the installation script, install.sh, along with the readme.html (this file). The installation script is a sh shell script for Solaris, and a bash shell script for Linux. The installer does not come with a JRE, so that must be preinstalled on the system.

Download the javaws-1_0_1-solsparc-us.zip for Solaris/SPARC, javaws-1_0_1-solx86-ea.zip for Solaris/x86, or javaws-1_0_1-linux-ea.zip for Linux/x86.

When you are prompted for a place to save the Java Web Start installer, pick a directory that would make a sensible permanent home for your copy of Java Web Start, for example, your home directory.

When the download finishes, unzip and execute the Java Web Start install script. The script will prompt you for the location of a Java 2 compatible JRE. For example: (the text in red is entered by the user)

mushmouth% unzip javaws-1_0_1-solsparc-ea.zip
mushmouth% ./install.sh
...
Do you agree to the above license terms? [yes or no]
yes
In order to use Java Web Start you must have a version of Java 2 standard edition installed. If you do not, you can download one from http://java.sun.com.
Please enter the path of your installation (e.g. /usr/local/java/jdk1.2): /usr/local/java/jdk1.2.2

Creating javaws.cfg...
Extracting...
Updating action...
Updating ~/.mailcap...
Updating ~/.mime.types...

The installer will create the javaws subdirectory and installs all the Java Web Start files into it.

The installer also updates the .mailcap and .mime.types files, so Java Web Start will be invoked when Netscape Navigator encounters a link to a JNLP link. On Solaris, it installs hooks into CDE so double-clicking on .jnlp files in the File Manager will also launch Java Web Start.

Make sure to restart Netscape to ensure that it picks up the new MIME type.

Using Java Web Start with Netscape 6/6.01

For Netscape 6/6.01 users, please setup the Java Web Start MIME type (JNLP) in the Edit->Preferences->Navigator->Helper Applications section. The file extension is "jnlp", MIME Type is "application/x-java-jnlp-file", and it should be handle by the javaws executable file in your Java Web Start directory.

Also note that you must use the non-javascript version of the demos page, due to a problem with the Javascript with Netscape 6/6.01. For more information please refer to the developer's guide.

Troubleshooting the Installation

If Java Web Start prints out a bad installation error message, then it has not been configured with the right information about your JRE locations. Check the contents of the javaws.cfg file. It will be in the installation directory of Java Web Start (typically at C:\Program Files\Java Web Start\javaws.cfg on Windows).

These configuration entries need to reflect the locations of the Java 2 SE JRE installations on your system. For example:

javaws.cfg.jre.0.path=/usr/local/java/jdk1.3/solaris/bin/java
javaws.cfg.jre.0.platform=1.3
javaws.cfg.jre.0.product=1.3.0
javaws.cfg.jre.1.path=/usr/local/java/jdk1.2.2/solaris/bin/java
javaws.cfg.jre.1.product=1.2.2-W
javaws.cfg.jre.1.platform=1.2
javaws.cfg.jre.default=0

Modify this file to reflect your system configuration by adding, removing, or deleting javaws.cfg.jre.<n>.location, javaws.cfg.jre.<n>.path, javaws.cfg.jre.<n>.platform and javaws.cfg.jre.<n>.product entries. Make sure that the javaws.cfg.jre.default=<n> refers to an existing entry. Entries are numbered consecutively starting at 0.

Java Web Start will not work with any version of the JRE 1.1.x software, or earlier versions.

Adding a new JRE

Java Web Start is bundled with the Java 2 Runtime Environment 1.3.0 on Windows. Thus, this JRE will be automatically available to applications launched with Java Web Start. On Solaris and Linux, the installer prompts for the location of a Java 2 Runtime Environment. This can either be a 1.2.2 or a 1.3.0 release.

It is possible to associate new JREs to Java Web Start by using the Preference Panel in the built-in Application Manager. The Launching from the built-in Application Manager section describes how to launch the Application Manager.

In the Preference Panel, select the Java tab. This tab lists all the current associated JREs that are available for an application to be launched on. The easiest way to add a new JRE, is to click on the Find... button, which opens up a Wizard that allows you to search the harddisk for already installed JREs.

In the second pane, either:

This will guarantee that the search starts at the given directory.

JNLP Specification Conformance

This release is the product quality reference implementation (RI) of the Java TM Network Launching Protocol & API (JNLP) Specification, v1.0.1.

Changes

Changes since the 1.0.1-ea release: Changes since the 1.0 release:
For more information on Java technology
and other software from Sun Microsystems, call:
(800) 786-7638
Outside the U.S. and Canada, dial your country's AT&T Direct Access Number first.
Sun Microsystems, Inc.
Copyright © 2000-2001 Sun Microsystems, Inc.
All Rights Reserved. Terms of Use. Privacy Policy.