java web start guide

Java Web Start Guide

Note: There are two ways to navigate this guide:

Search the guide Select from the contents below:

Related Documents

Overview

Java Web Start TechnologyWhere to Find Java Web Start TechnologyUsing Java Web Start SoftwareRequirements

Setting up the Web Site

IntroductionBasic Steps

Creating the Web Page That Launches the Application

IntroductionDetecting if Java Web Start is installed on NetscapeDetecting if Java Web Start is installed on IE, and if so, the version numberLaunching the application if Java Web Start is Installed—or providing a link for auto-install or general download pageCreating an auto-install page

Application Development Considerations

IntroductionRetrieving Resources from JAR filesSecurity and Code SigningSigning JAR Files with a Test CertificateHow to Encode JNLP FilesDynamic Download of HTTPS Certificates

JnlpDownloadServlet Guide

IntroductionExamplesServlet ConfigurationSpecifying ResourcesMapping Requests to ResourcesProcessing of JNLP Files

JNLP File Syntax

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/contents.html

IntroductionThe jnlp ElementThe information ElementThe security ElementThe resources ElementThe application-desc ElementThe applet-desc Element

JNLP API Examples

IntroductionUsing a BasicService ServiceUsing a ClipboardService ServiceUsing a DownloadService ServiceUsing a FileOpenService ServiceUsing a FileSaveService ServiceUsing a PrintService ServiceUsing a PersistenceService ServiceUsing FileContentsUsing a JNLPRandomAccessFileUsing a SingleInstanceService ServiceUsing an ExtendedService Service

The javaws Command Line Interface

Appendices:

FAQJNLP API (JavaDoc)

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/contents.html

Overview

Java Web Start Technology

Java Web Start is a helper application that gets associated with a Web browser. When a user clicks on a link that points to a special launch file (JNLP file), it causes the browser to launch Java Web Start, which then automatically downloads, caches, and runs the given Java Technology-based application. The entire process is typically completed without requiring any user interaction, except for the initial single click.

From a technology standpoint, Java Web Start has a number of key benefits that make it an attractive platform to use for deploying applications:

Java Web Start is built exclusively to launch applications written to the Java(TM) Platform Standard Edition. Thus, a single application can be made available on a Web server and then deployed on a wide variety of platforms, including Windows 98/NT/2000/ME/XP, Linux, and the SolarisTM Operating Environment. The Java platform has proven to be a very robust, productive, and expressive development platform, leading to a significant cost savings due to minimized development and testing costs.

Java Web Start supports multiple revisions of the Java(TM) Platform Standard Edition. Thus, an application can request a particular version of the platform it requires, such as Java SETM 1.5.0. Several applications can run at the same time on different platform revisions without causing conflicts, and Java Web Start can automatically download and install a revision of the platform if an application requests a version that is not installed on the client system.

Java Web Start allows applications to be launched independently of a Web browser. This can be used for off-line operation of an application, where launching through the browser is often inconvenient or impossible. The application can also be launched through desktop shortcuts, making launching the Web-deployed application similar to launching a native application.

Java Web Start takes advantage of the inherent security of the Java Platform. Applications are by default run in a protective environment (sandbox) with restricted access to local disk and network resources. It allows the user to safely run applications from sources that are not trusted.

Applications launched with Java Web Start are cached locally. Thus, an already-downloaded application is launched on par with a traditionally installed application.

The technology underlying Java Web Start is the Java TM Network Launching Protocol & API (JNLP). This technology was developed via the Java Community Process (JCP). Java Web Start is the reference implementation (RI) for the JNLP specification. The JNLP technology defines, among other things, a standard file format that describes how to launch an application called a JNLP file.

Security

Java Web Start is built on top of the Java(TM) SE 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 display a Security Warningdialog when the application is launched for the first time. The security warning will show information about 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.

Select a Chapter/Topic

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/overview.html

Where to find Java Web Start

Java Web Start is included in the Java Runtime Environment available at http://java.sun.com. The JNLP specification can be found at JSR 56: Java Network Launching Protocol and API.

Using Java Web Start Software

Java Web Start allows you to launch Java-technology-based applications directly from the Web. An application can be launched in three different ways:

From a Web browser by clicking on a link. From desktop icons or the Start Menu. From the Java Cache Viewer

Regardless of which way is used, Java Web Start will connect back to the Web server each time an application is launched to check whether an updated version of the application is available.

Launching from a Web browser

Point your web browser to a page with a link to a jnlp application, and click on that link.

Some applications 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 proceeds with downloading, caching, and running the application as directed by the JNLP file.

Launching from desktop icons and the Start Menu (Microsoft Windows and Unix running GNOME 2.0+)

Java Web Start technology can automatically create shortcuts for your application on the desktop and in the Start Menu for Web-deployed applications developed with Java technology. You can use the Java Control Panel to control the shortcut settings. Shortcuts can also be added by using the Java Web Start Cache Viewer, using the install shortcut menu item.

Using Java Web Start Software Behind a Proxy Server/Firewall

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

You can also use the Java Web Start Control Panel to view or edit the proxy configuration. Refer to the Java Control Panel for more details.

Requirements

Desktop/Client requirements:

The client machine requires support for the Java Runtime Environment (JRE), version 1.3 or later. Java Web Start is available for Windows 98/NT/2000/ME/XP, the Solaris Operating Environment, and Linux.


Server requirements:

Applications can be deployed from any standard Web server. In order to use Java Web Start, the Web server must be configured with support for a new MIME type. See Setting Up the Web Site.


Setting Up the Web Site

Introduction

Java Web Start leverages existing Internet technology, such as the HTTP protocol and Web servers, so existing infrastructure for deploying HTML-based contents can be reused to deploy Java Technology-based applications using Java Web Start.

In order to deploy your application to client machines, you must make sure that all files containing your application are accessible through a Web server. This typically amounts to copying one or more JAR files, along with a JNLP file, into the Web server's directories. The set-up required for enabling the Web site to support Java Web Start is very similar to deploying HTML-based contents. The only caveat is that a new MIME type needs to be configured for the Web server.

Basic Steps

1. Configure the Web server to use the Java Web Start MIME type

Configure the Web server so that all files with the .jnlp file extension are set to the application/x-java-jnlp-file MIME type.

Most Web browsers use the MIME type returned with the contents from the Web server to determine how to handle the particular content. The server must return application/x-java-jnlp-file MIME type for JNLP files in order for Java Web Start to be invoked.

Each Web server has a specific way in which to add MIME types. For example, for the Apache Web server you must add the following line to the .mime.types configuration file:

application/x-java-jnlp-file JNLP

Check the documentation for the specifics of your Web server.

2. Create a JNLP file for the application

The easiest way to create this file is to modify an existing JNLP file to your requirements.

The syntax and format for the JNLP file is described in a later section.

3. Make the application accessible on the Web server

Ensure your application's JAR files and the JNLP file are accessible at the URLs listed in the JNLP file.

4. Create the web page that launches the application

See the next chapter, Creating the Web Page that launches the Application, for details on step 4.


http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/setup.html

Creating the Web Page That Launches the Application

Select a Chapter/TopicTable of ContentsSearch PageOverviewSetting Up the Web SiteCreating the Web Page That Launches the ApplicationApplication Development ConsiderationsPackaging JNLP Applications in a Web ArchiveJNLP File SyntaxJNLP API Examplesjavaws Command LineFAQJNLP API (JavaDoc)

This chapter includes the following topics:

Introduction Detecting if Java Web Start is installed on Netscape Detecting if Java Web Start is installed on IE, and if so, the version number Launching the application if Java Web Start is Installed—or providing a link for auto-install or general download page Creating an auto-install page

Introduction

In order for an application to be launched from a web page via JNLP, the page must include a link to the JNLP file. E.g., to be able to launch application app.jnlp on a web site http://www.MySite.com, the page needs to include the following link:

<a href=http://www.MySite.com/app.jnlp>Launch the application</a>

It may be the case, however, that Java Web Start is not installed on the user's computer. Thus the page needs to include logic (scripts) to take account of this. In fact, the page should include logic for the following:

Detect if Java Web Start is installed

If so, launch the application. If not, detect if user is running IE on Window.

If so, provide link to a page that can auto-install the JRE for Windows If not, provide a link to the general download page for the JDK/JRE.

The scripts, and the HTML for the auto-install page, are discussed below.

Detecting if Java Web Start is installed on Netscape

Here is the first script that should be run on a web page for launching an application via JNLP:

<SCRIPT LANGUAGE="JavaScript"> var javawsInstalled = 0; var javaws142Installed=0;var javaws150Installed=0;var javaws160Installed = 0;isIE = "false"; if (navigator.mimeTypes && navigator.mimeTypes.length) { x = navigator.mimeTypes['application/x-java-jnlp-file']; if (x) { javawsInstalled = 1; javaws142Installed=1; javaws150Installed=1; javaws160Installed = 1; } } else { isIE = "true"; } </SCRIPT>

This script looks at the navigator.mimeTypes object and the navigator.mimeTypes.length var to decide if the browser is Netscape or

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/launch.html

IE. If length is 0, it is assumed the browser is IE, as with IE the navigator.mimeTypes array is defined but always empty. If length is non-zero, then the browser is assumed to be Netscape and the JNLP MIME type is checked to see if it exists on Netscape. If so, javawsInstalled, javaws142Installed, javaws150Installed and javaws160Installed are all set to 1. With Netscape it is not possible to determine which particular version of Java Web Start is installed, so all four variables are set to 1.

Detecting if JavaWeb Start is installed on IE, and if so, the version

The above JavaScript should be followed by a VBScript that sets variables related to Internet Explorer browers:

<SCRIPT LANGUAGE="VBScript">on error resume nextIf isIE = "true" Then If Not(IsObject(CreateObject("JavaWebStart.isInstalled"))) Then javawsInstalled = 0 Else javawsInstalled = 1 End If If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.4.2.0"))) Then javaws142Installed = 0 Else javaws142Installed = 1 End If If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.5.0.0"))) Then javaws150Installed = 0 Else javaws150Installed = 1 End If If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.6.0.0"))) Then javaws160Installed = 0 Else javaws160Installed = 1 End If End If</SCRIPT>

This VBScript is executed if the variable isIE from the preceeding JavaScript is "true"; i.e., if the end-user's browser is Internet Explorer. This script instantiates the isInstalled COM object in JavaWebStart.dll, and this object determines four things:

whether the client machine has any version of Java Web Start installed; whether the client machine has version 1.2 of Java Web Start installed; whether the client machine has versions 1.4.2 of Java Web Start installed; whether the client machine has versions 1.5.0 of Java Web Start installed. whether the client machine has versions 1.6.0 of Java Web Start installed.

After the above two scripts have been executed, the variables javawsInstalled, javaws142Installed, javawsInstalled150 and javawsInstalled160 will be set to either 1 or 0, as follows:

Launching the application if Java Web Start is Installed—or providing a link for auto-install or general download page

An additional JavaScript can be used to decide whether to:

provide a link to the application's jnlp file (i.e., Java Web Start is installed); initiate auto-download of JRE 6.0, which includes Java Web Start (i.e., Java Web Start is not installed and the user is running IE on

Windows);

Browser javawsInstalled javaws142Installed javaws150Installed javaws160Installed

Internet Explorer

1 if any version of Java Web Start is installed; 0 otherwise.

1 if Java Web Start 1.4.2 is installed; 0 otherwise.



Netscape Navigator






or provide a link to the general download page for the 6.0 JDK/JRE (i.e., Java Web Start is not installed and the user is not running IE on Windows).

The following JavaScript handles these scenarios:

<script language="JavaScript">/* Note that the logic below always launches the JNLP application *if the browser is Gecko based. This is because it is not possible *to detect MIME type application/x-java-jnlp-file on Gecko-based browsers. */if (javawsInstalled || (navigator.userAgent.indexOf("Gecko") !=-1)) { document.write("<a href=http://www.MySite.com/app.jnlp>Launch the application</a>");} else { document.write("Click "); document.write("<a href=http://java.sun.com/PluginBrowserCheck? pass=http://www.MySite.com/download.html& fail=http://java.sun.com/javase/downloads/ea.jsp>here</a> "); document.write("to download and install JRE 5.0 and the application.");}</SCRIPT>

If javawsInstalled is 1, indicating that Java Web Start is already available on the client, then the script provides a link to the application's jnlp file. If Java Web Start is not installed on the client, the script instead provides a link to the PluginBrowserCheckprogram on the java.sun.com web site. PluginBrowserCheck checks whether the client uses Internet Explorer on a Microsoft Windows platform. If so, PluginBrowserCheck sends the user to the auto-install page http://www.MySite.com/download.html. (See the next section, Creating an auto-install page, for how to create an auto-install page for IE running on Windows.) If PluginBrowserCheckdetermines the user is not using Internet Explorer on Microsoft Windows, the user is redirected to the 6.0 JRE general download page on java.sun.com.

Creating an auto-install page

The download.html file should be staged on the server side. It contains special OBJECT and PARAM tags that will download to the client an auto-installer for JRE 6.0 . Along with Java Web Start, an ActiveX control will be downloaded to the client. The ActiveX control will launch the application using the newly installed Java Web Start. Here is a sample download.html file:

<HTML><BODY><OBJECT codebase="http://java.sun.com/update/1.6.0/jinstall-6-windows-i586.cab#Version=6,0,0,0" classid="clsid:5852F5ED-8BF4-11D4-A245-0080C6F74284" height=0 width=0><PARAM name="app" value="http://www.MySite.com/app.jnlp"><PARAM name="back" value="true"><A href="http://java.sun.com/javase/downloads/ea.jsp">Download Java Web Start</A></OBJECT></BODY></HTML>

Notes:

1. The script only uses javawsInstalled—not javaws142Installed or javaws150Installed or javaws160Installed.

2. The line breaks following '?' and '&' are for readability purposes only; in an actual script there should be no breaks in the href string.

Note:

The.cab file in the codebase attribute below will not be available until the GA release of the 6.0 JDK/JRE.

For a complete list of JRE releases that can be autodownloaded via a .cab file, as mentioned below, see Autodownload Files (Windows Only).

The OBJECT tag fetches a .cab file that contains an auto-installer for JRE 6.0.

The URL: http://java.sun.com/update/1.6.0/jinstall-6-windows-i586.cab will return the latest update release available for the Java SE 6 release.

The string: Version=6,0,0,0 will be used to compare with the wsdetect.dll version, which is registered with the CLSID above. If the local machine has the dll installed and the version is greater than or equal to the Version specified, we will just load the dll in the local machine. Otherwise it will download and install Java from the codebase specified.

The PARAM tags specify the location of the application's jnlp file so that it may be automatically launched after the JRE is installed on the client.

app: Once the Java Web Start Active-X control is installed/loaded, it will invoke Java Web Start to launch the application specified by this URL.

back: This controls the behavior of the browser after launching the application. It can remain on the current page (download.html in this case) or navigate back to the previous page.

For issues relating to application development see the next chapter, Application Development Considerations.


Application Development Considerations


Introduction Retrieving Resources from JAR files Security and Code Signing Signing JAR Files With a Test Certificate How to Encode JNLP Files Dynamic Download of HTTPS Certificates

Introduction

Developing applications for deployment with Java Web Start is generally the same as developing stand-alone applications for the Java(TM) Platform Standard Edition. For instance, the entry point for the application is the standard public static void main(String[] argv).

However, in order to support Web deployment—automatic download and launching of an application—and to ensure that an application can run in a secure sandbox, there are some additional considerations:

An application must be delivered as a set of JAR files. All application resources, such as files and images must be stored in JAR files; and they must be referenced using the

getResource mechanism in the Java(TM) Platform Standard Edition (see below). If an application is written to run in a secure sandbox, it must follow these restrictions:

No access to local disk. All JAR files must be downloaded from the same host. Network connections are enabled only to the host from which the JAR files are downloaded. No security manager can be installed. No native libraries may be used. Limited access to system properties. The application has read/write access to all system properties defined in the

JNLP File, as well as read-only access to the same set of properties that an Applet has access to. An application is allowed to use the System.exit call. An application that needs unrestricted access to the system will need to be delivered in a set of signed JAR files. All

entries in each JAR file must be signed.

Retrieving Resources from JAR files

Java Web Start only transfers JAR files from the Web server to the client machine. It determines where to store the JAR files on the local machine. Thus, an application cannot use disk-relative references to resources such as images and configuration files.

All application resources must be retrieved from the JAR files specified in the resources section of the JNLP file, or retrieved explicitly using an HTTP request to the Web server. Storing resources in JAR files is recommended, since they will be cached on the local machine by Java Web Start.

The following code example shows how to retrieve images from a JAR file:

// Get current classloader


http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/development.html

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 one of the JAR files for the application:

images/save.gifimages/cut.gif

Security and Code Signing

Java Web Start addresses the security issues:

Protecting users against malicious code (intentional & unintentional) that may affect local files; Protecting enterprises against code that may attempt to access or destroy data on networks.

Applications launched with Java Web Start are, by default, run in a restricted environment where they have limited access to local computing resources, such as storage devices and the local network. In this sandbox environment, Java Web Start can guarantee that a downloaded and potentially untrusted application cannot compromise the security of the local files or the network.

An additional security feature supported by Java Web Start is digital code signing. If an application being invoked is delivered in one or more signed JAR files, Java Web Start will verify that the contents of the JAR file have not been modified since they were signed. If verification of a digital signature fails, Java Web Start will not run the application, since it may have been compromised by a third-party.

The support for code signing is important for both users and for application service providers. This service makes it possible for users to verify that an application comes from a trusted source. Because the application service provider signs the code, both can be ensured that no other party can impersonate the application on the Web. A signed application that is trusted by the user can also request additional system privileges, such as access to a local disk.

Java Web Start presents a dialog displaying the application's origin, based on the signer's certificate, before the application is launched. This allows the user to make an informed decision about whether or not to grant additional privileges to the downloaded code.

By including the following settings in the JNLP file, an application can request full access to a client system if all its JAR files are signed :

<security> <all-permissions/></security>

The implementation of code signing in Java Web Start is based on the security API in the core Java(TM) Platform Standard Edition. The Java 2 SE JRE 1.4.2 supports code signing with the SHA1withDSA and MD5withRSA algorithms.

Developers sign code for use with Java Web Start in the same way as for Java Applets—by using the standard jarsigner tool from the Java(TM) Platform Standard Edition. The jarsigner tool documentation provides examples of how to sign code and create test certificates, and it discusses other issues related to signing.

Java Web Start also supports use of the Netscape signtool used with SDK/JRE 1.4.2. See the Netscape Web site for details: http://developer.netscape.com/software/signedobj/

Signing JAR Files With a Test Certificate


Here are the steps needed to sign a JAR file with a test certificate:

1. Make sure that you have an SDK 1.4.2 keytool and jarsigner in your path. These tools are located in the SDK bin directory.

2. Create a new key in a new keystore as follows:

keytool -genkey -keystore myKeystore -alias myself

You will get prompted for a information about the new key, such as password, name, etc. This will create the myKeystore file on disk.

3. Then create a self-signed test certificate as follows:

keytool -selfcert -alias myself -keystore myKeystore

This will prompt for the password. Generating the certificate may take a few minutes.

4. Check to make sure that everything is okay. To list the contents of the keystore, use this command:

keytool -list -keystore myKeystore

It should list something like:

Keystore type: jksKeystore provider: SUN

Your keystore contains 1 entry:

myself, Tue Jan 23 19:29:32 PST 2001, keyEntry,Certificate fingerprint (MD5):C2:E9:BF:F9:D3:DF:4C:8F:3C:5F:22:9E:AF:0B:42:9D

5. Finally, sign the JAR file with the test certificate as follows:

jarsigner -keystore myKeystore test.jar myself

Repeat this step with all of your JAR files.

Note that a self-signed test certificate should only be used for internal testing, since it does not guarantee the identity of the user and therefore cannot be trusted. A trust-worthy certificate can be obtained from a certificate authority, such as VeriSign or Thawte, and should be used when the application is put into production.

How to Encode JNLP Files

Beginning with Java Web Start version 1.2, JNLP files may be encoded in any character encoding supported by the Java(TM) Platform Standard Edition. (See the Java(TM) Platform Standard Edition documentation for a list of supported encodings.)

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 will be encoded in UTF-16.

<?xml version="1.0" encoding="utf-16"?>

The XML prolog itself must be UTF-8-encoded.

Dynamic Download of HTTPS Certificates


Beginning with 1.4.2, Java Web Start dynamically imports certificates in much the same way as browsers do. In order to make this work, Java Web Start now sets its own https handler, using the java.protocol.handler.pkgs system properties, to initialize defaults for SSLSocketFactory and HostnameVerifier. It sets the defaults with HttpsURLConnection.setDefaultSSLSocketFactory and HttpsURLConnection.setDefaultHostnameVerifier.

If your application uses those two method, make sure they are called after the Java Web Start https handler is initialized, 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 either of the following:

1. Installing your own https handler, which will completely replace the Java Web Start https handler (for more information, see A New Era for Java Protocol Handlers);

2. Calling HttpsURLConnection.setDefaultSSLSocketFactory or HttpsURLConnection.setDefaultHostnameVerifier only after the first https url object is created, which will execute the Java Web Start https handler initialization code first.

For information on creating a download servlet see the next chapter, JnlpDownloadServlet Guide.


JnlpDownloadServlet Guide

Table of Contents

IntroductionExamplesServlet ConfigurationSpecifying ResourcesMapping Requests to ResourcesProcessing of JNLP FilesPack200 Support

Introduction

Java Web Start includes a servlet in the sample/jnlp directory of the JDK. It can be used on either a JNOP file and its associated resources packaged in a Web Archive (.war) file, or on an unarchived directory. The purpose of the servlet is to provide a simple and convenient packaging format for JNLP applications, so they can be easily deployed in a Web Container, such as Tomcat or a Java EE-compliant Application Server.

The download servlet supports the following features:

Automatic installation of the codebase URL into JNLP files, thus eliminating manual management of hard-coded URLs into JNLP files.

Explicit specification of the timestamp for a JNLP file, independent of the file-system timestamp. Supports all download protocols defined in the JNLP specification v1.0.1. These include basic download protocol,

version-based download protocol, and extension download protocol. Version-based information is specified per file or per directory in the Web archive. Thus, no centralized file needs to be

managed for the entire archive. Automatic generation of JARDiff files Pack200 support

The packaging support consists of one servlet: JnlpDownloadServlet. The servlet is packaged into the jnlp-servlet.jarfile, which can be found in the SDK under samples/jnlp/servlet/.

Below are two examples of how to use the servlet followed by a detailed description of the functionality of the servlet.

Examples

The first example shows how an application can be packaged into a WAR file without using the version-based download. The JnlpDownloadServlet is used to insert the exact URL into the JNLP file at request time. The second example shows how to add support for version-based download as well.

WAR file without use of version-download protocol

The example1.war contains:


http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html

/index.html /app/launch.jnlp /app/application.jar /app/images/icon.gif /WEB-INF/web.xml /WEB-INF/lib/jnlp-servlet.jar /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)

The JNLP file for the application would look like this:

TS: 2002-04-23 19:21:05 <?xml version="1.0" encoding="UTF-8"?> <jnlp codebase="$$codebase"> <information> <title>Example 1</title> <vendor>Myself</vendor> <description>just an example</description> <icon href="images/icon.gif"/> </information> <resources> <j2se version="1.2+"/> <jar href="application.jar"/> </resources> <application-desc/> </jnlp>

The first line with the TS tag contains the timestamp that the servlet will return for the JNLP file. The format of the timestamp is in ISO 8601 format. If the line is omitted, the timestamp of the file in the WAR file is used. The $$codebase string is modified by the JnlpDownloadServlet to be the actual URL for the request.

The web.xml file instructs the Web container to invoke the JNLPDownloadServlet for all requests to a JNLP file.

<web-app> <servlet> <servlet-name>JnlpDownloadServlet</servlet-name> <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>JnlpDownloadServlet</servlet-name> <url-pattern>*.jnlp</url-pattern> </servlet-mapping> </web-app>

The JnlpDownloadServlet requires an XML parser in order to work. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise please add jar files that implement a Java XML parser to the WEB-INF/libdirectory. The reference implementation of the parser can be downloaded from http://java.sun.com/xml.

WAR file with use of version-download protocol

The example2.war contains:

/index.html /app/version.xml /app/launch.jnlp /app/application.jar /app/lib__V2.1.jar /app/images/icon.gif /WEB-INF/web.xml /WEB-INF/lib/jnlp-servlet.jar /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)

The /app directory contains two JAR resources: application.jar and lib.jar. The lib.jar uses a naming convention to associate the version-id 2.1, i.e., the version information is associated on a per-file basis. The version of the application.jar


file is described in the version.xml file, i.e., on a per-directory basis. The version.xml file looks like this:

<jnlp-versions> <resource> <pattern> <name>application.jar</name> <version-id>1.1</version-id> </pattern> <file>application.jar</file> </resource> </jnlp-versions>

The JNLP file for the application looks like this:

TS: 2002-04-23 19:21:05 <?xml version="1.0" encoding="UTF-8"?> <jnlp codebase="$$codebase" href="$$name"> <information> <title>Example 2</title> <vendor>Myself</vendor> <description>just an example</description> <icon href="images/icon.gif"/> </information> <resources> <j2se version="1.2+"/> <jar href="application.jar" version="1.1"/> <jar href="lib.jar" version="2.1"/> </resources> <application-desc/> </jnlp>

Finally, the web.xml file configures the JnlpDownloadServlet to be invoked for all requests into the /app directory.

<web-app> <servlet> <servlet-name>JnlpDownloadServlet</servlet-name> <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>JnlpDownloadServlet</servlet-name> <url-pattern>/app/*</url-pattern> </servlet-mapping> </web-app>

Servlet Configuration

This section shows how to configure a WAR file to include the JnlpDownloadServlet and also how the servlet can be configured.

Adding the Servlet to a WAR archive

First the necessary servlet code must be made available to the servlet container. This is done by populating the WEB-INF/libdirectory. The servlet is added to a WAR archive by including the jnlp-servlet.jar file in the WEB-INF/lib/ directory. The servlet needs access to an XML parser. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise JAR files implementing a Java XML parser must also be added. They can be downloaded from http://java.sun.com/xml.

Once the servlet code is available, the Web container must be told to invoke the servlet on the right set of JNLP and JAR files,


or on a given subdirectory. This is all configured in the WEB-INF/web.xml file inside the <web-app> tag:

<web-app> ... </web-app>

The first thing to do is to tell the Web container how to invoke the servlet. This is done by using the <servlet> tag:

<servlet> <servlet-name>JnlpDownloadServlet</servlet-name> <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class> </servlet>

Secondly, the Web container must be told when to invoke the servlet. This can be done in several ways. It can be invoked for certain directories or for files with certain extensions. For example, to invoke it for JNLP files, add the following to the web.xml file:

<servlet-mapping> <servlet-name>JnlpDownloadServlet</servlet-name> <url-pattern>*.jnlp</url-pattern> </servlet-mapping>

Or for a given subdirectory:

<servlet-mapping> <servlet-name>JnlpDownloadServlet</servlet-name> <url-pattern>/app/*</url-pattern> </servlet-mapping>

See also example1 and example2 for examples on how to configure the servlet.

Logging

The servlet has built-in logging capabilities to monitor its behavior. Logging messages are generated in 4 different categories:

FATAL

A malfunction or internal error happened inside the servlet. WARNING

An error processing some of the information in the WAR file, e.g., parsing the version.xml file. INFORMATIONAL

Logging all requests and replies, re-scanning of directories, etc. DEBUG

Detailed internal information about how a request is processed.

The logging output is controlled by two servlet initialization parameters, logLevel and logPath. The log level can be set to either NONE, FATAL, WARNING, INFORMATIONAL, or DEBUG. The log path specifies a file where the output will be written to. If no path is specified, logging is done to the standard log for servlets (using the ServletContext.log method). For example:

<servlet> <servlet-name> JnlpDownloadServlet </servlet-name> <servlet-class> jnlp.sample.servlet.JnlpDownloadServlet </servlet-class>

<init-param> <param-name>


logLevel </param-name>

<param-value> DEBUG </param-value> </init-param>

<init-param> <param-name> logPath </param-name>

<param-value> /logs/jnlpdownloadservlet.log </param-value> </init-param>

</servlet>

Configuring file extensions and MIME types

The servlet treats JNLP and JAR files specially. JNLP files will be macro-expanded as described in a section below. A version-based request for a JAR file might result in the generation for an incremental update. The servlet uses extensions to determine if a file is a JNLP or JAR file. The default extension of JNLP files is .jnlp and for JAR files is .jar. These default extensions can be overwritten by the initialization parameters: jnlp-extension and jar-extension. For example:

<init-param> <param-name> jnlp-extension </param-name>

<param-value> .xjnlp </param-value> </init-param>

The MIME type that is returned for a file is also based on its extension. The MIME type is looked up in the configuration files for the Web container and the WAR file. If no mapping is specified, the default MIME types are shown below:

Extension Default MIME type ------------------------------------------- .jnlp application/x-java-jnlp-file .jar application/x-java-archive .jardiff application/x-java-archive-diff

A mapping can be overwritten by using the <mime-type> element in the web.xml file. For example:

<web-app> ... <mime-mapping> <extension>jnlp</extension> <mime-type>text/ascii</mime-type> </mime-mapping> ... </web-app>

Specifying Resources

Application resources such as images, JAR files, and JNLP files are stored in the WAR file. The WAR file itself is a hierarchical directory structure, and the location of a resource inside the WAR file determines what URL will be used to look it up.


Assume that the WAR file (or servlet) has been configured so it handles all URL requests that starts with http://www.mytool.com/tool/. If the following requests is made: http://www.mytool.com/tool/app/launch.jnlp. Then the JnlpDownloadServlet will look for the launch.jnlp resource in the app/ directory in the WAR file.

No version information

A resource that has no associated version information, such as a JNLP file for an application, is simply just added to the WAR file. For example, given the above example, then the WAR file should included the following file:

/app/launch.jnlp

In general, the timestamp that will be returned for the file is the last-modified timestamp that the file has in the WAR file. The only exception is for JNLP files where it can be explicitly specified in the JNLP file (see below).

Version information and more

The version-based and extension-based download protocols in the JNLP specification allows a resource to be looked up based on version-id, operating system, system architecture, and locale. The JnlpDownloadServlet provides two mechanisms for associating this information with a resource. It can be done on a per-file basis, using a naming convention, or by a per-directory basis, using a configuration file. Both methods can be used for the same directory.

The following information can be associated with a resource:

A path to the resource, e.g., /app A name for the resource, e.g., launch.jnlp A version-id, e.g., 1.1.0 A list of supported operations systems, e.g., SunOS Linux A list of supported architectures, e.g., x86 A list of supported locales, e.g., da da_DK A flag indicating if the version-id is a product version or a platform version (only used for JRE downloading)

The path is specified by the location of the resource in the WAR archive. The rest of the information is either specified by the use of a naming convention or in the version.xml file.

Resource Naming

The file naming convention is used if a double underscore (__) marker is found in the filename. The filename is parsed according to the BNF notation shown below:

file ::= name __ options . extoptions ::= option ( __ options ) *option ::= V version-id |

O os | A arch | L locale

Only one version-id can be specified per file. However, multiple os, arch, and locale fields can be specified. For example:

application__V1.2__Len_US__Len.jar

will mean that the resource application.jar has a version-id of 1.2, and the following associated locales: en_US and en.

The version.xml file

In each directory, a version.xml file can be placed to describe the additional properties, such as a version-id, for files in that particular directory. This is an alternative to the file naming convention.


For example, placing the file application-1_2-us.jar in a directory, along with a version.xml with the following content:

<jnlp-versions> <resource> <pattern> <name>application.jar</name> <version-id>1.2</version-id> <locale>en_US</locale> <locale>en</locale> </pattern> <file>application-1_2-us.jar</file> </resource> </jnlp-versions>

will be the same as having placed the file application__V1.2__Len_US__Len.jar in the directory.

A resource can also be specified with a platform version-id in the version.xml file. Such a resource is used to match a particular platform request for a JRE. A resource with a platform version-id is specified using the <platform> element. For example:

<platform> <pattern> <name>JRE</name> <version-id>1.3</version-id> <locale>en_US</locale> <locale>en</locale> </pattern> <file>j2re-1_3.0-us.jnlp</file> <product-version-id>1.3.0</product-version-id> </platform>

Platform version requests are generated internally by Java Web Start, when an application has requested a version of the Java platform that is currently not installed on the local system.

The complete document type definition (DTD) for the version.xml is shown in the following:

<!ELEMENT jnlp-versions <resource*, platform*)> <!ELEMENT resource (pattern, file)> <!ELEMENT platform (pattern, file, product-version-id)> <!ELEMENT pattern (name, version-id, os*, arch*, locale*)> <!ELEMENT name (#PCDATA)> <!ELEMENT version-id (#PCDATA)> <!ELEMENT os (#PCDATA)> <!ELEMENT arch (#PCDATA)> <!ELEMENT locale (#PCDATA)> <!ELEMENT file (#PCDATA)> <!ELEMENT product-version-id (#PCDATA)>

Mapping Requests to Resources

The JNLP specification defines four different kinds of download requests that Java Web Start (or more generally, a JNLP Client) can make to a server when requesting a resource:

Basic Download Request: This is an ordinary URL request to a specific file. The Last-Modified field of the response is used to determine if an update is available on the server. The basic download request can be used for all resource types.

Version-based Download Request: This request type can be used for JAR files and images, i.e., the following elements will generate a version-based download request: <jar>, <nativelib>, and <icon>, when the version attribute is included.

Extension Download Request: This request type is an extension of the version-based request type and is generated by either the <j2se> or <extension> elements. In addition to the version information, it also contains information about


operating system, system architecture, and locale. Platform-version Download Request: This is simliar to the extension download request, but used to request a

particular version of the J2SE Runtime Environment (JRE). This request is generated by Java Web Start, when a JNLP file has requested a particular version of the JRE that is not currently installed on the client system.

A request is initially processed by the JNLPDownloadServlet, and it extracts the following information from the request:

Path in WAR file, Name of requested file Version string (version-id parameter or platform-version-id parameter) Current version-id (current-version-id parameter) List of operation systems (os parameter) List of architectures (arch parameter) List of locales (locale parameter)

Consider example2, and assume that it is being hosted at http://www.mytool.com/tool2/. If the following requests is made: http://www.mytool.com/tool2/app/lib.jar&version-id=2.1. Then the path of the resource would be, app/, the name would be lib.jar, the version string would be 2.1, and the lists for os, architecture, and locales would be empty.

A request to a directory, e.g., http://www.mytool.com/tool2/app/, will get appended the default filename: launch.jnlp. Thus, it would be the same as http://www.mytool.com/tool2/app/launch.jnlp.

Handling a basic download request

A request for which no version-id is specified (neither version-id parameter or platform-version-id parameter is specified in the request) is handled as a basic download request.

The request is first checked to see if it contains a double underscore (__) or is a request to the version.xml file. If so, the request is rejected and a HTTP 404 error code is returned.

The JnlpDownloadServlet will then try to locate the resource with the given path and name in the WAR file, and if found return it. If the resource is not found, a HTTP 404 error code is returned for the request.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Handling a version-based download request

The resource lookup for resources with a version-id is uniform across the version-based download protocol, the extension download protocol, and the platform-version download request.

First, the JnlpDownloadServlet will build a database of all the resources that are located in the WAR file directory that the URL request is accessing (based on the path in the request). The database is built by scanning the version.xml file (if present), and the list of files in the directory that is using the naming convention described above. The servlet caches the information internally. It only does a re-scan if the timestamp of the version.xml file is more recent than at the last scan. Thus, if you add a file using the naming convention, make sure to touch the version.xml file to force the servlet to do a re-scan.

Secondly, the servlet will scan through the entries in the database to find a match for the given request (the match rules are described below). For a non-platform request, first the resource entries in the version.xml file are scanned in the order they are specified, and then secondly the entries that are specified using the naming convention. For a platform-version request, the platform entries in the version.xml file is scanned in the order they are specified. If several entries matches the request, then the entry with the highest version-id is returned. If multiple matches is found with the same highest version-id, then the first one specified is returned.

The matching rules are as follows:


1. The name of the resource must match the request 2. The version-id of the resource must match the version string in the request 3. For the os, arch, and locale lists the following rules are used:

1. If an empty list is specified for the resource, then it is a match 2. If a non-empty list is specified for the resource, then it is a match, if at least one of the values specified for the

resource is a prefix of at least one of the values specified in the request.

The x-java-jnlp-version-id returned in the response is the version-id for the matching resource, except for a platform request where it is taken from the <product-version-id> field in the version.xml file.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Automatic JARDiff generation

The servlet will automatically generate and return incremental updates to JAR files, if possible. If the current-version-idparameter is included in the request and the servlet can find both a match on the current-version-id and the requested version (given the above matching rules) and the request is for a JAR file (e.g., the target resource has the .jar extension), then a JARDiff file will be generated by the servlet. The JARDiff file is returned as long as its size is less than that of the requested version.

The JARDiff file is generated and stored in a temporary directory that is specific to the given Web container. The servlet locates the temporary working directory using the javax.servlet.context.tempdir context attribute.

Processing of JNLP files

The JnlpDownloadServlet will automatically macro-expand certain template values in a JNLP file and replace them with URLs that are specific to the current request. This will enable JNLP files to be written and deployed without containing hard-coded URLs.

Macro expansions

The servlet will automatically substitute certain fixed keys in the JNLP file (prefixed with $$) with URLs that are based on the current request. The keys are designed so location-independent WAR files can be created and deployed into a Web container.

The table below shows the 4 keys that the servlet will look for and substitute:

Pattern Value ---------------------------------------------------------------- $$codebase Complete URL for request, except name of JNLP file

$$name Name of the JNLP file $$context Base URL for the Web Archive

$$site Web site address without the WAR context portion

For example: Consider the example1 WAR file. Lets assume that it has been deployed at the following location: http://www.mytool.com/tool. Thus, a request to http://www.mytool.com/tool/app/launch.jnlp will return the JNLP file. The values of the macro-expanded keys would be:

$$codebase = http://www.mytool.com/tool/app/ $$name = launch.jnlp $$context = http://www.mytool.com/tool/ $$site = http://www.mytool.com/

The servlet does not validate the format of the JNLP file nor that the XML is well-formed. The value substitution is purely textual.

Explicit Timestamps


An explicit timestamp can be included in a JNLP file to ensure that a consistent timestamp will be returned from the Web Server. This is especially useful if a JNLP file is replicated onto multiple Web servers that are serving the same URL in a round-robin or load-balancing fashion. Note that a similar method is not provided for JAR files. The version-based download protocol should be used instead.

An explicit timestamp is included in the JNLP if the first-line starts with TS:. If so, it is parsed accordingly to the ISO 8601 formatting of timestamps (see below). The first line is also removed from the contents.

See example1 and example2 above for sample JNLP files using the TS: element.

ISO 8601 Formatting

The general format of a timestamp is:

YYYY-MM-DD hh:mm:ss

The dashes, colons, and seconds are optional:

YYYYMMDDhhmm

The hh is in 24h notation. By default, the local time zone is used. A Universal Time (UTC) (also know as GMT time) can be specified by appending the capital letter Z to a time as in:

23:59:59Z or 235959Z

The strings

+hh:mm, +hhmm, or +hh

can be added to the time to indicate that the used local time zone is hh hours and mm minutes ahead of UTC. For time zones west of the zero meridian, which are behind UTC, the notation

-hh:mm, -hhmm, or -hh

is used instead. For example, Central European Time (CET) is +0100 and U.S./Canadian Eastern Standard Time (EST) is -0500. The following strings all indicate the same point of time:

12:00Z = 13:00+01:00 = 0700-0500

Pack200 Support

You can now host *.jar.pack.gz or *.jar.gz files together with your original *.jar files. If the client supports the pack200-gzip or gzip file formats, the servlet will return the compressed file if it is available on the server. Java Web Start 5.0 supports both compression formats. You must host both the original jar file and the pack file in the server, otherwise the servlet will not pick up the pack file. The pack file can be created with the pack200.exe command included in J2SE 5.0. For more information on the pack200 compression technology, please see Pack200 and Compression for Network Deployment.


JNLP File Syntax

This chapter covers the following topics:

Introduction Example JNLP Elements

jnlp Element information Element security Element update Element resources Element application-desc Element applet-desc Element component-desc Element installer-desc Element

Introduction

The format used in this release is that specified in the Java Network Launching Protocol & API Specification (JSR-56) version 6.0. This document describes the most commonly used elements of a JNLP file. For a complete description of the format, refer to the specification.

JNLP File Contents


Element Attributes Description Since Required

jnlp This is the main xml element for a jnlp file. Everything is contained within the jnlp element. 1.0 yes

spec The spec attribute can be 1.0, 1.5.0, or 6.0 or can use the wildcards such as 1.0+. It denoted the minimum version of the JNLP Specification that this jnlp file can work woth.

1.0

codebase The codebase attribute specifies the base location for all relative URLs specified in href attributes in the JNLP file. 1.0

href The href specifies the URL of the JNLP file itself. 1.0

version The version of the application being launched, as well as the version of the JNLP file itself. 1.0

information The information element contains other elements that describe the application and it's source. 1.0 yes

os Specifies the operating system for which this information element should be considered.1.5.0

arch Specifies the architecture for which this information element should be considered 1.5.0

platform Specifies the platform for which this information element should be considered. 1.5.0

locale Specifies the locale for which this information element should be considered. 1.5.0

title The title element specifies the title of the application. 1.0 yes

vendor The vendor element specifies the provider of the application. 1.0 yes

homepage The homepage of the application. 1.0

href A URL pointing to where more information on this application can be found. 1.0 yes

description A short statement describing the application. 1.0

kind An indicator as to what type of description this is, legal values are one-line, short, and tooltip. 1.0

icon Describes an icon that can be used to identify the application to the user. 1.0

href A URL pointing to the icon file, may be in one of the following formats: gif, jpg, png, ico. 1.0 yes

kind Indicates the suggested use of the icon, can be: default, selected, disabled, rollover, splash, or shortcut. 1.0

width Can be used to indicate the resolution of the image. 1.0

height Can be used to indicate the resolution of the image. 1.0

depth Can be used to indicate the resolution of the image. 1.0

offline-allowed Indicates that this application can operate when the client system is disconnected from the network. 1.0

shortcut The shortcut element can be used to indicate an application's preferences for desktop integration. 1.5.0

online Can be used to describe the application's preference for creating a shortcut to run online or offline. 1.5.0

desktop Can be used to indicate an application's preference for putting a shortcut on the users desktop. 1.5.0

menu Can be used to indicate an application's preference for putting a menu item in the users start menus. 1.5.0

sub-menu Can be used to indicate an application's preference for where to place the menu item. 1.5.0

association 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

extensionsContains a list of file extensions (separated by spaces) that the application requests it be registered to handle. 1.5.0

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html

mime-type Contains the mime-type that the application requests it be registered to handle. 1.5.0

related-content Describes an additional piece of related content that may be integrated with the application. 1.5.0

href A URL pointing to the related content. 1.5.0 yes

update The update element is used to indicate the preferences for how application updates should be handled by the JNLP Client.

6.0

check Indicates the preference for when the JNLP Client should check for updates. It can be always, timeout, or background.. 6.0

policyIndicates the preference for how the JNLP Client should handle an application update when it is known an update is available before the application is launched. It can be always, prompt-update, or prompt-run.

6.0

1.0

security This element can be used to request enhanced permissions. 1.0

all-permissions Requests that the application be run with all permissions. 1.0

j2ee-application-client-permissions

Requests that the application be run with a permission set that meets the security specifications of the J2EE Application Client environment. 1.0

1.0

resources Describes all the resources that are needed for an application. 1.0 yes

os Specifies the operating system for which the resources element should be considered. 1.0

arch Specifies the architecture for which the resources element should be considered. 1.0

locale Specifies that the locales for which the resources element should be considered.

java (or j2se) Specifies what version(s) of Java to run the application with. 6.0 (java)

version Describes an ordered list of version ranges to use. 1.0 yes

href The URL denoting the supplier of this version of java, and where it may be downloaded from. 1.0

java-vm-args Indicates an additional set of standard and non-standard virtual machine arguments that the application would prefer the JNLP Client to use when launching Java.

1.0

initial-heap-size Indicates the initial size of the Java heap. 1.0

max-heap-size Indicates the maximum size of the Java heap. 1.0

jar Specifies a JAR file that is part of the application's classpath. 1.0 yes

href The URL of the jar file. 1.0 yes

version The requested version of the jar file. Requires using the version-based download protocol 1.0

main Indicates if this jar contains the class containing the main method of the application. 1.0

download Can be used to indicate this jar may be downloaded lazily, or when needed. 1.0

size Indicates the downloadable size of the jar file in bytes. 1.0

part Can be used to group resources together so they will be downloaded at the same time. 1.0

nativelib Specifies a JAR file that contains native libraries in it's root directory. 1.0

href The URL of the jar file. 1.0 yes

version The requested version of the jar file. Requires using the version-based download protocol 1.0

download Can be used to indicate this jar may be downloaded lazily. 1.0

size Indicates the downloadable size of the jar file in bytes. 1.0

part Can be used to group resources together so they will be downloaded at the same time. 1.0

extension Contains pointer to an additional component-desc or installer-desc to be used with this application. 1.0

href The URL to the additional extension jnlp file. 1.0 yes

version The version of the additional extension jnlp file. 1.0

name The name of the additional extension jnlp file 1.0

ext-download Can be used in an extension element to denote the parts contained in a component-extension. 1.0

ext-part Describes the name of a part that can be expected to be found in the extension. 1.0 yes

download Can be used to indicate this extension may be downloaded eagerly or lazily. 1.0

part Denotes the name of a part in this jnlp file to include the extension in. 1.0

package Can be used to indicate to the JNLP Client which packages are implemented in which JAR files. 1.0

name Package name contained in the jar files of the given part. 1.0 yes

part Part name containing the jar files that include the given package name. 1.0 yes

recursiveCan be used to indicated that all package names beginning with the given name, can be found in the given part. 1.0

property Defines a system property that will be available through the System.getProperty and System.getProperties methods.

1.0

name Name of the system property. 1.0 yes

value Value it will be set to. 1.0 yes

1.0


The JNLP file is an XML document. The following shows a complete example of a JNLP file.

Example

<?xml version="1.0" encoding="utf-8"?>

<jnlp spec="6.0+"

codebase="http://my_company.com/jaws/apps" href="swingset2.jnlp">

<information> <title>SwingSet2 Demo Application</title> <vendor>Sun Microsystems, Inc.</vendor>

<homepage href="docs/help.html"/> <description>SwingSet2 Demo Application</description> <description kind="short">A demo of the capabilities of the Swing Graphical User Interface.</description>

<icon href="images/swingset2.jpg"/> <icon kind="splash" href="images/splash.gif"/>

<offline-allowed/> <association>

<mime-type="application-x/swingset2-file"/> <extensions="swingset2"/>

</association> <shortcut online="false">

<desktop/> <menu submenu="My Corporation Apps"/>

</shortcut> </information>

<information os="linux"> <title> SwingSet2 Demo on Linux </title> <homepage href="docs/linuxhelp.html">

</information> <security>

<all-permissions/> </security> <resources>

<j2se version="1.6+" java-vm-args="-esa -Xnoclassgc"/> <jar href="lib/SwingSet2.jar"/>

</resources> <application-desc main-class="SwingSet2"/>

</jnlp>

The example shows the basic outline of the document. The root element is jnlp, which has four subelements: information, security, resources, and application-desc. In addition, Java Web Start also supports launching applets by using the applet-desc element. The elements are described in more detail below.

JNLP Elements

jnlp Element

spec attribute: This attribute must be 1.0 or higher to work with this release. The default value is "1.0+". Thus, it can typically be omited. Note that this version supports both spec version 1.0, version 1.5, and version 6.0, whereas previous versions support only 1.0 and 1.5. A jnlp file specifying spec="6.0+" will work with this version, but not previous versions of Java Web Start.

codebase attribute: All relative URLs specified in href attributes in the JNLP file are using this URL as a base.

href attribute: This is a URL pointing to the location of the JNLP file itself.

information Element

title element: The name of the application.

vendor element: The name of the vendor of the application.

homepage element: Contains a single attribute, href, which is a URL locating the home page for the Application. It is used by the Java Application Cache Viewer to point the user to a Web page where more information about the application can be found.

description element: A short statement about the application. Description elements are optional. The kind attribute defines how the description should be used. It can have one of the following values:

Note: A jnlp file must contain one of application-desc, applet-desc, component-desc, or installer-desc

1.0 yes

applicaation-desc Denotes this is the jnlp file for an application. 1.0

main-class The name of the class containing the public static void main(String[]) method of the application. 1.0 yes

argument Each argument contains (in order) an additional argument to be passed to main. 1.0

applet-desc Denotes this is the jnlp file for an applet. 1.0

main-class This is the name of the main Applet class. 1.0 yes

documentbase The document base for the Applet as a URL. 1.0

name Name of the Applet. 1.0 yes

width The width of the applet in pixels. 1.0 yes

height The height of the applet in pixels 1.0 yes

param A set of parameters that can be passed into the applet. 1.0

name The name of this parameter 1.0 yes

value The value of this parameter 1.0 yes

component-desc Denotes this is the jnlp file for a component extension. 1.0

installer-desc Denotes this is the jnlp file for an installed extension. 1.0

main-class The name of the class containing the public static void main(String[]) method of the installer. 1.0 yes

one-line: If a reference to the application is going to appear on one row in a list or a table, this description will be used. short: If a reference to the application is going to be displayed in a situation where there is room for a paragraph, this description is used.

tooltip: If a reference to the application is going to appear in a tooltip, this description is used.

Only one description element of each kind can be specified. A description element without a kind is used as a default value. Thus, if Java Web Start needs a description of kind short, and it is not specified in the JNLP file, then the text from the description without an attribute is used.

All descriptions contain plain text. No formatting, such as with HTML tags, is supported.

icon element: Contains an HTTP URL to an image file in either GIF or JPEG format. The icons are used to represents the application

during launch when Java Web Start presents the application to the user; in the Java Application Cache Viewer;

in desktop shortcuts.

A 64x64 icon is shown during download; in the Java Application Cache Viewer and in desktop shortcuts a 32x32 icon is used. Java Web Start automatically resizes an icon to the appropriate size.

Optional width and height attributes can be used to indicate the size of the images.

The optional kind="splash" attribute may be used in an icon element to indicate that the image is to be used as a "splash" screen during the launch of an application. If the JNLP file does not contain an icon element with kind="splash" attribute, Java Web Start will construct a splash screen using other items from the information Element.

If the JNLP file does not contain any icon images, the splash image will consist of the application's title and vendor, as taken from the JNLP file.

The first time an application is launched following the addition or modification of the icon element in the JNLP file, the old splash image will still be displayed. The new splash image will appear on the second and subsequent launches of the application.

offline-allowed element: The optional offline-allowed element indicates if the application can be launched offline.

If offline-allowed is specified, then the application can be launched offline by the Java Application Cache Viewer, and shortcuts can be created which launch the application offline.

If an application is launched offline, it will not check for updates and the API call BasicService.isOffline() will return true.

The offline-allowed element also controls how Java Web Start checks for an update to an application. If the element is not specified—i.e., the application is required to be online to run—Java Web Start will always check for an updated version before launching the application. And if an update is found, the new application will be downloaded and launched. Thus, it is guaranteed that the

user always runs the latest version of the application. The application, however, must be run online.

If offline-allowed is specified, Java Web Start will also check to see if an update is available. However, if the application is already downloaded the check will timeout after a few seconds, in which case the cached application will be launched instead. Given a reasonably fast server connection, the latest version of the application will usually be run, but it is not guaranteed. The application,

however, can be run offline.

shortcut element: The optional shortcut element can be used to indicate an application's preferences for desktop integration. The shortcut element and it's sub-elements provide hints that the JNLP Client may or may not use. The shortcut element can contain the optional online attribute, and the two optional sub-elements, desktop and menu.

association element: The optional association element is a 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. The association element must have the extensions and mime-type attributes.

related-content element: The optional related-content element describes an additional piece of related content, such as a readme file, help pages, or links to registration pages, as a hint to a JNLP Client. The application is asking that this content be included in its desktop integration. The related-content element has a mandatory href and title attribute. It can contain any of the following two

sub-elements:

description element: A short description of the related content. icon element: The icon can be used by the JNLP Client to identify the related content to the user.

security Element

Each application is, by default, run in a restricted execution environment, similar to the Applet sandbox. The security element can be used to request unrestricted access.

If the all-permissions element is specified, the application will have full access to the client machine and local network. If an application requests full access, then all JAR files must be signed. The user will be prompted to accept the certificate the first time the application is launched.

update Element

The update element is used to indicate the preferences for how application updates should be handled by Java Web Start.

The update element can contain the following two optional attributes:

check attribute: The check attribute indicates the preference for when the JNLP Client should check for updates, and can have one of the three values: "always", "timeout", and "background"

A value of "always" means to always check for updates before launching the application.

A value of "timeout" (default) means to check for updates until timeout before launching the application. If the update check is not completed before the timeout, the application is launched, and the update check will continue in the background.

A value of "background" means to launch the application while checking for updates in the background.

policy attribute: The policy attribute indicates the preference for how the JNLP Client should handle an application update when it is known an update is available before the application is launched, and can have one of the following three values: "always", "prompt-update", and "prompt-run"

A value of "always" (default) means to always download updates without any prompt.

A value of "prompt-update" means to ask the user if he/she wants to download and run the updated version, or launch the cached version.

A value of "prompt-run" means to ask the user if he/she wants to download and run the updated version, or cancel and abort runing the application.

For example:

<update check="always" policy="prompt-update">

resources Element

The resources element is used to specify all the resources, such as Java class files, native libraries, and system properties, that are part of the application. A resource definition can be restricted to a specific operating system, architecture, or locale using the os, arch, and locale attributes.


The resources element has six different possible subelements: jar, nativelib, j2se, property, package, and extension. The package and extension elements are not discussed in this developer's guide. See the Java Network Launching Protocol & API Specification (JSR-56) version 6.0 for details.

A jar element specifies a JAR file that is part of the application's classpath. For example:

<jar href="myjar.jar"/>

The jar file will be loaded into the JVM using a ClassLoader object. The jar file will typically contain Java classes that contain the code for the particular application, but can also contain other resources, such as icons and configuration files, that are available through the getResource mechanism.

A nativelib element specifies a JAR file that contains native libraries. For example:

<nativelib href="lib/windows/corelib.jar"/>

The JNLP client must ensure that each file entry in the root directory of the JAR file (i.e., /) can be loaded into the running process using the System.loadLibrary method. Each entry must contain a platform-dependent shared library with the correct naming convention, e.g., *.dll on Windows or lib*.so on Solaris/Linux. The application is responsible for doing the actual call to

System.loadLibrary.

Native libraries would typically be included in a resources element that is geared toward a particular operating system and architecture. For example:

<resources os="SunOS" arch="sparc"> <nativelib href="lib/solaris/corelibs.jar"/>

</resource>

By default, jar and nativelib resources will be downloaded eagerly, i.e., they are downloaded and available locally to the JVM running the application before the application is launched. The jarand nativelib elements also allow a resource to be specified as lazy. This means the resource does not have to be downloaded onto the client system before the application is launched.

The download attribute is used to control whether a resource is downloaded eagerly or lazily. For example:

<jar href="sound.jar" download="lazy"/> <nativelib href="native-sound.jar" download="eager"/>

The j2se element specifies what Java(TM) Platform Standard Edition Runtime Environment (JRE) versions an application is supported on, as well as standard parameters to the Java Virtual Machine. If several JREs are specified, this indicates a prioritized list of the supported JREs, with the most preferred version first. For example:

<j2se version="1.3" initial-heap-size="64m" max-heap-size="128m"/> <j2se version="1.4.2+" href="http://java.sun.com/products/autodl/j2se" java-vm-args="-esa -Xnoclassgc"/>

The version attribute refers, by default, to a platform version (specification version) of the Java(TM) Platform Standard Edition. Currently defined platform versions are 1.2, 1.3, 1.4, 1.5 and 1.6. (A platform version will not normally contain a micro version number; e.g., 1.4.2.)

Exact product versions (implementation versions) may also be specified. by including the href attribute. For example, 1.3.1_07, 1.4.2, or 1.5.0-beta2 by Sun Microsystems, Inc. For example,

<j2se version="1.4.2" href="http://java.sun.com/products/autodl/j2se"/

or

<j2se version="1.4.2_04" href="http://java.sun.com/products/autodl/j2se"/>

If a platform version is specified (i.e., no href attribute is provided), Java Web Start will not consider an installed non-FCS (i.e., milestone) JRE as a match. E.g., a request of the form

<j2se version="1.4+"/>

would not consider an installed 1.4.1-ea or 1.4.2-beta JRE as a match for the request. Starting with 1.3.0, a JRE from Sun Microsystems, Inc., is by convention a non-FCS (milestone) JRE if there is a dash (-) in the version string.

The java-vm-args attribute of the j2se element specifies a preferred set of virtual machine arguments to use when launching java.

<j2se version="1.4+" java-vm-args="-ea -Xincgc"/>

The following java-vm-args are supported by this version:

-d32, /* use a 32-bit data model if available */-client, /* to select the client VM */-server, /* to select the server VM */-verbose, /* enable verbose output */

-version, /* print product version and exit */-showversion, /* print product version and continue */

-help, /* print this help message */-X, /* print help on non-standard options */

-ea, /* enable assertions */-enableassertions, /* enable assertions */-da, /* disable assertions */-disableassertions, /* disable assertions */

-esa, /* enable system assertions */-enablesystemassertions, /* enable system assertions */-dsa, /* disable system assertione */-disablesystemassertions, /* disable system assertione */

-Xmixed, /* mixed mode execution (default) */-Xint, /* interpreted mode execution only */-Xnoclassgc, /* disable class garbage collection */

-Xincgc, /* enable incremental garbage collection */-Xbatch, /* disable background compilation */

-Xprof, /* output cpu profiling data */-Xdebug, /* enable remote debugging */

-Xfuture, /* enable strictest checks, anticipating future default */-Xrs, /* reduce use of OS signals by Java/VM (see documentation) */

-XX:+ForceTimeHighResolution, /* use high resolution timer */-XX:-ForceTimeHighResolution, /* use low resolution (default) */

Plus any argument starting with one of the following:

-ea, /* enable assertions for classes */-enableassertions, /* enable assertions for classes */-da, /* disable assertions for classes */-disableassertions, /* disable assertions for classes */

-verbose, /* enable verbose output */-Xms, /* set initial Java heap size */-Xmx, /* set maximum Java heap size */


-Xss, /* set java thread stack size */-XX:NewRatio, /* set Ratio of new/old gen sizes */

-XX:NewSize, /* set initial size of new generation */-XX:MaxNewSize, /* set max size of new generation */

-XX:PermSize, /* set initial size of permanent gen */-XX:MaxPermSize, /* set max size of permanent gen */

-XX:MaxHeapFreeRatio, /* heap free percentage (default 70) */-XX:MinHeapFreeRatio, /* heap free percentage (default 40) */

-XX:UseSerialGC, /* use serial garbage collection */-XX:ThreadStackSize, /* thread stack size (in KB) */

-XX:MaxInlineSize, /* set max num of bytecodes to inline */-XX:ReservedCodeCacheSize, /* Reserved code cache size (bytes) */

-XX:MaxDirectMemorySize,

The property element defines a system property that will be available through the System.getProperty and System.setProperties methods. It has two required attributes: name and value. For example:

<property name="key" value="overwritten"/>

Properties set in the jnlp file will normally be set by Java Web Start after the VM is started but before the application is invoked. Some properties are considered "secure" properties and can be passed as -Dkey=value arguments on the java invocation command line.

The following properties are considered "secure" and will be passed to the VM in this way:

sun.java2d.noddraw, javax.swing.defaultlf,

javaws.cfg.jauthenticator, swing.useSystemFontSettings,

swing.metalTheme, http.agent,

http.keepAlive, sun.awt.noerasebackground,

sun.java2d.opengl, sun.java2d.d3d,

java.awt.syncLWRequests, java.awt.Window.locationByPlatform, sun.awt.erasebackgroundonresize,

swing.noxp, swing.boldMetal,

awt.useSystemAAFontSettings, sun.java2d.dpiaware,

For an untrusted application, system properties set in the JNLP file will only be set by Java Web Start if they are considered secure, or if the property name begins with "jnlp." or "javaws.".

application-desc Element

The application element indicates that the JNLP file is launching an application (as opposed to an applet). The application element has an optional attribute, main-class, which can be used to specify the name of the application's main class, i.e., the class that contains the public static void main(String argv[]) method where execution must begin.

The main-class attribute can be omitted if the first JAR file specified in the JNLP file contains a manifest file containing the main class.

Arguments can be specified to the application by including one or more nested argument elements. For example:

<application-desc main-class="Main"> <argument>arg1</argument> <argument>arg2</argument>

</application-desc>

applet-desc Element

Java Web Start has support for launching Java applets. This support provides easy migration of existing code to Java Web Start.

An applet is launched using the applet-desc element instead of the application-desc element. For example:

<applet-desc documentBase="http://..."

name="TimePilot" main-class="TimePilot.TimePilotApp"

width="527" height="428">

<param name="key1" value="value1"/> <param name="key2" value="value2"/>

</applet-desc>

The JAR files that make up the applet are described using the resources element as for applications. The documentBase must be provided explicitly since a JNLP file is not embedded in an HTML page. The rest of the attributes correspond to the respective HTML applet tag elements.

The main-class attribute is used instead of the code attribute. The main-class attribute is assigned the name of the Applet class (without the .class extension). This attribute can be omitted if the Applet class can be found from the Main-Class manifest entry in the main JAR file.

Note: Applets must be packaged in JAR files in order to work with Java Web Start.

component-desc Element

The component-desc element denotes that this jnlp file is not an application or an applet but an extension that can be used as a resource in an application, applet or another extension.

A component extension is typically used to factor out a set of resources that are shared between multiple applications or that have separate security needs.

installer-desc Element

The installer-desc element denotes that this jnlp file is an installer extension that defines an application that will be run only once, the first time this extension jnlp file is used in an application, applet or another extension.

An installer extension is typically used to install platform specific native code that requires a more complicated setup than simply loading a native library into the VM.


JNLP API Examples


Introduction Using a BasicService Service Using a ClipboardService Service Using a DownloadService Service Using a FileOpenService Service Using a FileSaveService Service Using a PrintService Service Using a PersistenceService Service Using FileContents Using a JNLPRandomAccessFile Using a SingleInstanceService Service Using a ExtendedService Service

Introduction

The JNLP API is designed to provide additional information to the application that would otherwise not be available using the standard Java(TM) Platform Standard Edition API. The following code examples show how the following services can be used: BasicService, ClipboardService, DownloadService, FileOpenService, FileSaveService, PrintService, and PersistenceService.

The public classes and interfaces in the JNLP API are included in the jnlp.jar file. This JAR file must be included in the classpath when compiling source files that use the JNLP API. For example on Windows:

javac -classpath .;jnlp.jar *.java

The jnlp.jar file is included in the JNLP Developers Pack.

Using a BasicService Service

The javax.jnlp.BasicService service provides a set of methods for querying and interacting with the environment similar to what the AppletContext provides for a Java Applet.

The showURL method uses the JNLP API to direct the default browser on the platform to show the given URL. The method returns true if the request succeeds, otherwise false.

import javax.jnlp.*; ...

// Method to show a URL boolean showURL(URL url) { try { // Lookup the javax.jnlp.BasicService object BasicService bs = (BasicService)ServiceManager.lookup("javax.jnlp.BasicService"); // Invoke the showDocument method return bs.showDocument(url);


http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html

} catch(UnavailableServiceException ue) { // Service is not supported return false; } }

Using a ClipboardService Service

The javax.jnlp.ClipboardService service provides methods for accessing the shared system-wide clipboard, even for applications that are running in the restricted execution environment.

Java Web Start will warn the user of the potential security risk of letting an untrusted application access potentially confidential information stored in the clipboard, or overwriting contents stored in the clipboard.

import javax.jnlp; ...

private ClipboardService cs;

try { cs = (ClipboardService)ServiceManager.lookup ("javax.jnlp.ClipboardService"); } catch (UnavailableServiceException e) { cs = null; }

if (cs != null) { // set the system clipboard contents to a string selection StringSelection ss = new StringSelection("Java Web Start!"); cs.setContents(ss); // get the contents of the system clipboard and print them Transferable tr = cs.getContents(); if (tr.isDataFlavorSupported(DataFlavor.stringFlavor)) { try { String s = (String)tr.getTransferData(DataFlavor.stringFlavor); System.out.println("Clipboard contents: " + s); } catch (Exception e) { e.printStackTrace(); } } }

Using a DownloadService Service

The javax.jnlp.DownloadService service allows an application to control how its own resources are cached.

The service allows an application to determine which of its resources are cached, to force resources to be cached, and to remove resources from the cache.


DownloadService ds;

try { ds = (DownloadService)ServiceManager.lookup("javax.jnlp.DownloadService"); } catch (UnavailableServiceException e) { ds = null; }


if (ds != null) {

try { // determine if a particular resource is cached URL url = new URL("http://java.sun.com/javase/technologies/desktop/javawebstart/lib/draw.jar"); boolean cached = ds.isResourceCached(url, "1.0"); // remove the resource from the cache if (cached) { ds.removeResource(url, "1.0"); } // reload the resource into the cache DownloadServiceListener dsl = ds.getDefaultProgressWindow(); ds.loadResource(url, "1.0", dsl); } catch (Exception e) { e.printStackTrace(); } }

Using a FileOpenService Service

The javax.jnlp.FileOpenService service provides methods for importing files from the local disk, even for applications that are running in the restricted execution environment.

This interface is designed to provide the same kind of of disk access to potentially untrusted Web-deployed applications that a Web developer has when using HTML. HTML forms support the inclusion of files by displaying a file open dialog.


FileOpenService fos;

try { fos = (FileOpenService)ServiceManager.lookup("javax.jnlp.FileOpenService"); } catch (UnavailableServiceException e) { fos = null; }

if (fos != null) { try { // ask user to select a file through this service FileContents fc = fos.openFileDialog(null, null); // ask user to select multiple files through this service FileContents[] fcs = fos.openMultiFileDialog(null, null); } catch (Exception e) { e.printStackTrace(); } }

Using a FileSaveService Service

The javax.jnlp.FileSaveService service provides methods for exporting files to the local disk, even for applications that are running in the restricted execution environment.

This interface is designed to provide the same level of disk access to potentially untrusted Web-deployed applications that a Web browser provides for contents that it is displaying. Most browsers provide a Save As... dialog as part of their user interface.


FileSaveService fss;



try { fos = (FileOpenService)ServiceManager.lookup("javax.jnlp.FileOpenService"); fss = (FileSaveService)ServiceManager.lookup ("javax.jnlp.FileSaveService"); } catch (UnavailableServiceException e) { fss = null; fos = null; }

if (fss != null && fos != null) { try { // get a file with FileOpenService FileContents fc = fos.openFileDialog(null, null); // one way to save a file FileContents newfc = fss.saveFileDialog(null, null, fc.getInputStream(), "newFileName.txt"); // another way to save a file FileContents newfc2 = fss.saveAsFileDialog(null, null, fc);

} catch (Exception e) { e.printStackTrace(); } }

Also see Using FileContents.

Using a PrintService Service

The javax.jnlp.PrintService service provides methods for access to printing, even for applications that are running in the restricted execution environment.

Using this service, an application can submit a print job. Java Web Start will then show this request to the user and, if accepted, queue the request to the printer.

In Java Web Start 5.0, you can now directly use the Java Printing APIs, and Java Web Start will pop up a security dialog asking the user to grant PrintPermission if the application is running in a sandbox. There is no need to use the JNLP Printing APIs anymore. You can have full access to the Java Printing APIs in any JNLP application.


PrintService ps;

try { ps = (PrintService)ServiceManager.lookup("javax.jnlp.PrintService"); } catch (UnavailableServiceException e) { ps = null; }

if (ps != null) { try { // get the default PageFormat PageFormat pf = ps.getDefaultPage();

// ask the user to customize the PageFormat PageFormat newPf = ps.showPageFormatDialog(pf);

// print the document with the PageFormat above ps.print(new DocToPrint()); } catch (Exception e) { e.printStackTrace();


} }

// Code to construct the Printable Document class DocToPrint implements Printable { public int print(Graphics g, PageFormat pageformat, int PageIndex){ // code to generate what you want to print } }

Using a PersistenceService Service

The javax.jnlp.PersistenceService service provides methods for storing data locally on the client system, even for applications that are running in the restricted execution environment.

The service is designed to be somewhat similar to that which the cookie mechanism provides to HTML-based applications. Cookies allow a small amount of data to be stored locally on the client system. That data can be securely managed by the browser and can only be retrieved by HTML pages which originate from the same URL as the page that stored the data.


PersistenceService ps; BasicService bs;

try { ps = (PersistenceService)ServiceManager.lookup("javax.jnlp.PersistenceService"); bs = (BasicService)ServiceManager.lookup("javax.jnlp.BasicService"); } catch (UnavailableServiceException e) { ps = null; bs = null; }

if (ps != null && bs != null) {

try { // find all the muffins for our URL URL codebase = bs.getCodeBase(); String [] muffins = ps.getNames(url);

// get the attributes (tags) for each of these muffins. // update the server's copy of the data if any muffins // are dirty int [] tags = new int[muffins.length]; URL [] muffinURLs = new URL[muffins.length]; for (int i = 0; i < muffins.length; i++) { muffinURLs[i] = new URL(codebase.toString() + muffins[i]); tags[i] = ps.getTag(muffinURLs[i]); // update the server if anything is tagged DIRTY if (tags[i] == PersistenceService.DIRTY) { doUpdateServer(muffinURLs[i]); } }

// read in the contents of a muffin and then delete it FileContents fc = ps.get(muffinURLs[0]); long maxsize = fc.getMaxLength(); byte [] buf = new byte[fc.getLength()]; InputStream is = fc.getInputStream(); long pos = 0; while((pos = is.read(buf, pos, buf.length - pos)) > 0) { // just loop } is.close();

ps.delete(muffinURLs[0]);


// re-create the muffin and repopulate its data ps.create(muffinURLs[0], maxsize); fc = ps.get(muffinURLs[0]); // don't append OutputStream os = fc.getOutputStream(false); os.write(buf); os.close();


void doUpdateServer(URL url) { // update the server's copy of the persistent data // represented by the given URL ... ps.setTag(url, PersistenceService.CACHED); }

Using FileContents

javax.jnlp.FileContents objects encapsulate the name and contents of a file. An object of this class is used by the FileOpenService, FileSaveService and PersistenceService. Here is an example of how an instance of a FileContents can be used to read from and write to a file:



//Initialize fos (see Using a FileOpenService Service example) ...

if (fos != null) {

try {

// get a FileContents object to work with from the // FileOpenService FileContents fc = fos.openFileDialog(null, null);

// get the InputStream from the file and read a few bytes byte [] buf = new byte[fc.getLength()]; InputStream is = fc.getInputStream(); int pos = 0; while ((pos = is.read(buf, pos, buf.length - pos)) > 0) { // just loop } is.close();

// get the OutputStream and write the file back out if (fc.canWrite()) { // don't append OutputStream os = fc.getOutputStream(false); os.write(buf); }


Using a JNLPRandomAccessFile


Instances of javax.jnlp.JNLPRandomAccessFile support both reading and writing to a random access file. A random access file behaves like a large array of bytes stored in the file system. Here is an example of how an instance of a JNLPRandomAccessFilecan be used to write to a random access file:



//Initialize fos (see Using a FileOpenService Service example) ...

if (fos != null) { try { // ask the user to choose a file to open FileContents fc = fos.openFileDialog(null, null);

// attempt to increase the maximum file length long grantedLength = fc.getLength(); if (grantedLength + 1024 > fc.getMaxLength()) { // attempt to increase the maximum file size defined by // the client grantedLength = fc.setMaxLength(grantedLength + 1024); }

// if we were able to increase the maximum allowable file size, // get a JNLPRandomAccessFile representation of the file, and // write to it if (fc.getMaxSize() > fc.getLength() && fc.canWrite()) { JNLPRandomAccessFile raf = fc.getRandomAccessFile("rw"); raf.seek(raf.length() - 1); raf.writeUTF("Java Web Start!"); raf.close(); } } catch (Exception e) { e.printStackTrace(); } }

Using a SingleInstanceService Service

The javax.jnlp.SingleInstanceService provides a set of methods for applications to register themselves as singletons, and to register listener(s) for handling arguments passed in from different instances of applications.


SingleInstanceService sis;

...

try { sis = (SingleInstanceService)ServiceManager.lookup("javax.jnlp.SingleInstanceService"); } catch (UnavailableServiceException e) { sis=null; }

...

// Register the single instance listener at the start of your application SISListener sisL = new SISListener(); sis.addSingleInstanceListener(sisL);

...


// Remember to remove the listener before your application exits sis.removeSingleInstanceListener(sisL); System.exit(0);

// Implement the SingleInstanceListener for your application class SISListener implements SingleInstanceListener { public void newActivation(String[] params) { // your code to handle the new arguments here ... } }

Using an ExtendedService Service

The javax.jnlp.ExtendedService provides additional support to the current JNLP API. It allows applications to open specific file(s) in the client's file system.


ExtendedService es;

...

try { es = (ExtendedService)ServiceManager.lookup("javax.jnlp.ExtendedService"); } catch (UnavailableServiceException e) { es=null; }

...

// Open a specific file in the local machine File a = new File("c:\somefile.txt");

... // Java Web Start will pop up a dialog asking the user to grant permission // to read/write the file c:\somefile.txt FileContents fc_a = es.openFile(a);

// You can now use the FileContents object to read/write the file ...

// Open a specific set of files in the local machine File[2] fArray = new File[2]; fArray[0] = a; fArray[1] = new File("c:\anotherFile.txt");

// Java Web Start will pop up a dialog asking the user to grant permission // to read/write files in fArray


FileContents[] fc_Array = es.OpenFiles(fArray);

// You can now read/write the set of files in fc_Array using the // FileContents objects }

For detailed information on using javaws, see the javaws Command Line Interface.


Package javax.jnlp

Package Class Tree Index PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

Interface Summary

BasicServiceThe BasicService interface provides access to the codebase of the application, if an application is run in offline mode, and simple interaction with the native browser on the given platform.

ClipboardServiceClipboardService provides methods for accessing the shared system-wide clipboard, even forapplications that are running in the untrusted execution environment.

DownloadServiceDownloadService service allows an application to control how its own resources are cached, to determine which of its resources are currently cached, to force resources to be cached, and to remove resources from the cache.

DownloadServiceListenerThe DownloadServiceListener provides an interface for a callback object implementation, which may be used by a DownloadService implementation.

ExtendedServiceExtendedService provides additional support to the current JNLP API, which allowapplications to open a specific file in the client's file system.

ExtensionInstallerServiceThe ExtensionInstallerService is used by an extension installer to communicate with the JNLP Client.

FileContents FileContents objects encapsulate the name and contents of a file.

FileOpenServiceFileOpenService service allows the user to choose a file from the local file system, even for applications that are running in the untrusted execution environment.

FileSaveServiceFileSaveService service allows the user to save a file to the local file system, even forapplications that are running in the untrusted execution environment.

JNLPRandomAccessFile Instances of this class support both reading and writing to a random access file.

PersistenceServicePersistenceService provides methods for storing data locally on the client system, even forapplications that are running in the untrusted execution environment.

PrintServicePrintService provides methods for access to printing functions, even for applications that are running in the untrusted execution environment.

ServiceManagerStubA ServiceManagerStub object implements the particular lookup of JNLP services by the JNLP Client.

SingleInstanceListenerSingleInstanceListener is a interface which should be implemented by a JNLP application if they wish to support single instance behaviour.

SingleInstanceServiceSingleInstanceService allow applications launched under Java Web Start to register themselves as singletons, and to be passed in new parameter sets when user attempts to launch new instances of them.

Class SummaryServiceManager The ServiceManager provides static methods to lookup JNLP services.

Exception Summary

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/package-summary.html

Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved

UnavailableServiceExceptionThe UnavailableServiceException is thrown by the ServiceManager when a non-existing or unavailable service is looked up.

Package Class Tree Index PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/package-summary.html

javax.jnlp

Interface BasicService

public interface BasicService

The BasicService interface provides access to the codebase of the application, if an application is run in offline mode, and simple interaction with the native browser on the given platform.

This interface mimics loosely the AppletContext functionality.

Since:1.0

getCodeBase

java.net.URL getCodeBase()

Returns the codebase for the application. The codebase is either specified directly in the JNLP file, or it is the location of the JAR file containing the main class of the application.

Returns:a URL with the codebase of the application

isOffline

boolean isOffline()

Package Class Tree Index PREV CLASS NEXT CLASS FRAMES NO FRAMES All ClassesSUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Method Summary java.net.URL getCodeBase()

Returns the codebase for the application. boolean isOffline()

Determines if the system is offline. boolean isWebBrowserSupported()

Checks if a Web browser is supported on the current platform and by the given JNLP Client. boolean showDocument(java.net.URL url)

Directs a browser on the client to show the given URL.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/BasicService.html

Determines if the system is offline. The return value represents the JNLP client's "best guess" at the online / offline state of the client system. The return value is does not have to be guaranteed to be reliable, as it is sometimes difficult toascertain the true online / offline state of a client system.

Returns:true if the system is offline, otherwise false

showDocument

boolean showDocument(java.net.URL url)

Directs a browser on the client to show the given URL. This will typically replace the page currently being viewed in a browser with the given URL, or cause a browser to be launched that will show the given URL.

Parameters:url - an URL giving the location of the document. A relative URL will be relative to the codebase.

Returns:true if the request succeded, otherwise false

isWebBrowserSupported

boolean isWebBrowserSupported()

Checks if a Web browser is supported on the current platform and by the given JNLP Client. If this is not the case, then showDocument(java.net.URL) will always return false.

Returns:true if a Web browser is supported, otherwise false



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/BasicService.html

javax.jnlp

Interface ClipboardService

public interface ClipboardService

ClipboardService provides methods for accessing the shared system-wide clipboard, even for applications that are running in the untrusted execution environment. Implementors should warn the user of the potential security risk of letting an untrusted application have access to potentially confidential information stored in the clipboard, or overwriting the contents of the clipboard.

Since:1.0

getContents

java.awt.datatransfer.Transferable getContents()

Returns a Transferable object representing the current contents of the clipboard. If the clipboard currently has no contents, it returns null.

Returns:The current Transferable object on the clipboard.

setContents

void setContents(java.awt.datatransfer.Transferable contents)

Sets the current contents of the clipboard to the specified Transferable object.

Parameters:contents - The Transferable object representing clipboard content.



Method Summary java.awt.datatransfer.Transferable getContents()

Returns a Transferable object representing the current contents of the clipboard. void setContents(java.awt.datatransfer.Transferable contents)

Sets the current contents of the clipboard to the specified Transferable object.

Method Detail


http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ClipboardService.html

javax.jnlp

Interface DownloadService

public interface DownloadService

DownloadService service allows an application to control how its own resources are cached, to determine which of its resources are currently cached, to force resources to be cached, and to remove resources from the cache. The JNLP Client is responsible for providing a specific implementation of this service.

Since:1.0


Method Summary DownloadServiceListener getDefaultProgressWindow()

Return a default DownloadServiceListener implementation which, when passed to a loadmethod, should pop up and update a progress window as the load progresses.

boolean isExtensionPartCached(java.net.URL ref, java.lang.String version, java.lang.String part) Returns true if the given part of the given extension is cached, and the extension and part are mentioned in the JNLP file for the application.

boolean isExtensionPartCached(java.net.URL ref, java.lang.String version, java.lang.String[] parts) Returns true if the given parts of the given extension are cached, and the extension and parts are mentioned in the JNLP file for the application.

boolean isPartCached(java.lang.String part) Returns true if the part referred to by the given string is cached, and that part is mentioned in the JNLP file for the application.

boolean isPartCached(java.lang.String[] parts) Returns true if the parts referred to by the given array are cached, and those parts are mentioned in the JNLP file for the application.

boolean isResourceCached(java.net.URL ref, java.lang.String version) Returns true if the resource referred to by the given URL and version is cached, and that resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or the calling application has been granted all-permissions.

void loadExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String[] parts, DownloadServiceListener progress) Downloads the given parts of the given extension, if the parts and the extension are mentioned in the JNLP file for the application.

void loadExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String part, DownloadServiceListener progress) Downloads the given part of the given extension, if the part and the extension are mentioned in the JNLP file for the application.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html

isResourceCached

boolean isResourceCached(java.net.URL ref, java.lang.String version)

Returns true if the resource referred to by the given URL and version is cached, and that resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or the calling application has been granted all-permissions. .

Parameters:ref - The URL for the resource.version - The version string, or null for no version.

Returns:true if the above conditions are met, and false otherwise.

isPartCached

boolean isPartCached(java.lang.String part)

Returns true if the part referred to by the given string is cached, and that part is mentioned in the JNLP file for the

void loadPart(java.lang.String[] parts, DownloadServiceListener progress) Downloads the given parts, if the parts are mentioned in the JNLP file for the application.

void loadPart(java.lang.String part, DownloadServiceListener progress) Downloads the given part, if the part is mentioned in the JNLP file for the application.

void loadResource(java.net.URL ref, java.lang.String version, DownloadServiceListener progress) Downloads the given resource, if the resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or if the calling application has been granted all-permissions.

void removeExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String part) Removes the given part of the given extension from the cache, if the part and the extension are mentioned in the JNLP file for the application.

void removeExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String[] parts) Removes the given parts of the given extension from the cache, if the parts and the extension are mentioned in the JNLP file for the application.

void removePart(java.lang.String part) Removes the given part from the cache, if the part is mentioned in the JNLP file for the application.

void removePart(java.lang.String[] parts) Removes the given parts from the cache, if the parts are mentioned in the JNLP file for the application.

void removeResource(java.net.URL ref, java.lang.String version) Removes the given resource from the cache, if the resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or if the calling application has been granted all-permissions.

Method Detail


application.

Parameters:part - The name of the part.


isPartCached

boolean isPartCached(java.lang.String[] parts)

Returns true if the parts referred to by the given array are cached, and those parts are mentioned in the JNLP file for the application.

Parameters:parts - An array of part names.


isExtensionPartCached

boolean isExtensionPartCached(java.net.URL ref, java.lang.String version, java.lang.String part)

Returns true if the given part of the given extension is cached, and the extension and part are mentioned in the JNLP file for the application.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.part - The name of the part.


isExtensionPartCached

boolean isExtensionPartCached(java.net.URL ref, java.lang.String version, java.lang.String[] parts)

Returns true if the given parts of the given extension are cached, and the extension and parts are mentioned in the JNLP file for the application.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.parts - An array of part names.



loadResource

void loadResource(java.net.URL ref, java.lang.String version, DownloadServiceListener progress) throws java.io.IOException

Downloads the given resource, if the resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or if the calling application has been granted all-permissions. This method will block until the download is completed or an exception occurs.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.progress - Download progress callback object.

Throws:java.io.IOException

loadPart

void loadPart(java.lang.String part, DownloadServiceListener progress) throws java.io.IOException

Downloads the given part, if the part is mentioned in the JNLP file for the application. This method will block until the download is completed or an exception occurs.

Parameters:part - The name of the part.progress - Download progress callback object.


loadPart

void loadPart(java.lang.String[] parts, DownloadServiceListener progress) throws java.io.IOException

Downloads the given parts, if the parts are mentioned in the JNLP file for the application. This method will block until the download is completed or an exception occurs.

Parameters:parts - An array of part names.progress - Download progress callback object.


loadExtensionPart


void loadExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String part, DownloadServiceListener progress) throws java.io.IOException

Downloads the given part of the given extension, if the part and the extension are mentioned in the JNLP file for the application. This method will block until the download is completed or an exception occurs.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.part - The name of the part.progress - Download progress callback object.


loadExtensionPart

void loadExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String[] parts, DownloadServiceListener progress) throws java.io.IOException

Downloads the given parts of the given extension, if the parts and the extension are mentioned in the JNLP file for the application. This method will block until the download is completed or an exception occurs.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.parts - An array of part names to load.progress - Download progress callback object.


removeResource

void removeResource(java.net.URL ref, java.lang.String version) throws java.io.IOException

Removes the given resource from the cache, if the resource is either mentioned in the calling applications JNLP file, is within the codebase of the calling applications JNLP file, or if the calling application has been granted all-permissions.



removePart


void removePart(java.lang.String part) throws java.io.IOException

Removes the given part from the cache, if the part is mentioned in the JNLP file for the application.

Parameters:part - The name of the part.


removePart

void removePart(java.lang.String[] parts) throws java.io.IOException

Removes the given parts from the cache, if the parts are mentioned in the JNLP file for the application.

Parameters:parts - An array of part names.


removeExtensionPart

void removeExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String part) throws java.io.IOException

Removes the given part of the given extension from the cache, if the part and the extension are mentioned in the JNLP file for the application.

Parameters:ref - The URL for the resource.version - The version string, or null for no version.part - The name of the part.


removeExtensionPart

void removeExtensionPart(java.net.URL ref, java.lang.String version, java.lang.String[] parts) throws java.io.IOException

Removes the given parts of the given extension from the cache, if the parts and the extension are mentioned in the JNLP file for the application.



parts - An array of part names.Throws:

java.io.IOException

getDefaultProgressWindow

DownloadServiceListener getDefaultProgressWindow()

Return a default DownloadServiceListener implementation which, when passed to a load method, should pop up and update a progress window as the load progresses.

Returns:A DownloadServiceListener object representing a download progress listener.




javax.jnlp

Interface DownloadServiceListener

public interface DownloadServiceListener

The DownloadServiceListener provides an interface for a callback object implementation, which may be used by a DownloadService implementation. The DownloadServiceListener implementation's methods should be invoked by the DownloadService implementation at various stages of the download, allowing an application that uses the JNLP API to display a progress bar during a DownloadService download.

Since:1.0

See Also:DownloadService

progress

void progress(java.net.URL url, java.lang.String version, long readSoFar, long total, int overallPercent)

A JNLP client's DownloadService implementation should call this method several times during a download. A


Method Summary void downloadFailed(java.net.URL url, java.lang.String version)

A JNLP client's DownloadService implementation should call this method if a download fails or aborts unexpectedly.

void progress(java.net.URL url, java.lang.String version, long readSoFar, long total,int overallPercent) A JNLP client's DownloadService implementation should call this method several times during a download.

void upgradingArchive(java.net.URL url, java.lang.String version, int patchPercent,int overallPercent) A JNLP client's DownloadService implementation should call this method at least several times when applying an incremental update to an in-cache resource.

void validating(java.net.URL url, java.lang.String version, long entry, long total,int overallPercent) A JNLP client's DownloadService implementation should call this method at least several times during validation of a download.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadServiceListener.html

DownloadServiceListener implementation may display a progress bar and / or update information based on theparameters.

Parameters:url - The URL representing the resource being downloaded.version - The version of the resource being downloaded.readSoFar - The number of bytes downloaded so far.total - The total number of bytes to be downloaded, or -1 if the number is unknown.overallPercent - The percentage of the overall update operation that is complete, or -1 if the percentage isunknown.

validating

void validating(java.net.URL url, java.lang.String version, long entry, long total, int overallPercent)

A JNLP client's DownloadService implementation should call this method at least several times during validation of a download. Validation often includes ensuring that downloaded resources are authentic (appropriately signed). ADownloadServiceListener implementation may display a progress bar and / or update information based on the parameters.

Parameters:url - The URL representing the resource being validated.version - The version of the resource being validated.entry - The number of JAR entries validated so far.total - The total number of entries to be validated.overallPercent - The percentage of the overall update operation that is complete, or -1 if the percentage isunknown.

upgradingArchive

void upgradingArchive(java.net.URL url, java.lang.String version, int patchPercent, int overallPercent)

A JNLP client's DownloadService implementation should call this method at least several times when applying an incremental update to an in-cache resource. A DownloadServiceListener implementation may display a progress barand / or update information based on the parameters.

Parameters:url - The URL representing the resource being patched.version - The version of the resource being patched.patchPercent - The percentage of the patch operation that is complete, or -1 if the percentage is unknown.overallPercent - The percentage of the overall update operation that is complete, or -1 if the percentage isunknown.

downloadFailed


void downloadFailed(java.net.URL url, java.lang.String version)

A JNLP client's DownloadService implementation should call this method if a download fails or aborts unexpectedly. In response, a DownloadServiceListener implementation may display update information to the user to reflect this.

Parameters:url - The URL representing the resource for which the download failed.version - The version of the resource for which the download failed.




javax.jnlp

Interface ExtendedService

public interface ExtendedService

ExtendedService provides additional support to the current JNLP API, which allow applications to open a specific file in the client's file system.

Since:1.5

openFile

FileContents openFile(java.io.File file) throws java.io.IOException

Asks the user the permission to open the specified file if the file has not been opened before. The contents of the file is returned as a FileContents object. The returned FileContents object contains the contents the file.

Parameters:file - the file object

Returns:A FileContent object with information about the opened file

Throws:java.io.IOException - - if there is any I/O error

openFiles

FileContents[] openFiles(java.io.File[] files) throws java.io.IOException


Method Summary FileContents openFile(java.io.File file)

Asks the user the permission to open the specified file if the file has not been opened before. FileContents

[] openFiles(java.io.File[] files) Asks the user the permission to open the specified list of files if any of the files has not been opened before.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtendedService.html

Asks the user the permission to open the specified list of files if any of the files has not been opened before. The contents of each file is returned as a FileContents object in the FileContents array. The returned FileContents object contains the contents the file.

Parameters:files - the array of files

Returns:A FileContent[] object with information about each opened file

Throws:java.io.IOException - - if there is any I/O error



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtendedService.html

javax.jnlp

Interface ExtensionInstallerService

public interface ExtensionInstallerService

The ExtensionInstallerService is used by an extension installer to communicate with the JNLP Client. It provides the following type of functionality:

Access to prefered installation location, and other information about the JNLP Client Manipulation of the JNLP Client's download screen Methods for updating the JNLP Client with the installed code

The normal sequence of events for an installer is:

1. Get service using ServiceManager.lookup("javax.jnlp.ExtensionInstallerService").2. Update status, heading, and progress as install progresses (setStatus, setHeading and updateProgress). 3. Invoke either setJREInfo or setNativeLibraryInfo depending on if a JRE or a library is installed 4. If successful invoke installSucceeded, otherwise invoke installFailed.

Since:1.0


Method Summary java.net.URL getExtensionLocation()

Returns the location of the extension being installed java.lang.String getExtensionVersion()

Returns the version of the extension being installed java.lang.String getInstalledJRE(java.net.URL url, java.lang.String version)

Returns the path to the executable for the given JRE. java.lang.String getInstallPath()

Returns the directory where the installer is recommended to install the extension in. void hideProgressBar()

Hides the progress bar. void hideStatusWindow()

Hides the status window. void installFailed()

This should be invoked if the install fails. void installSucceeded(boolean needsReboot)

Installers should invoke this upon a succesful installation of the extension. void setHeading(java.lang.String heading)

Updates the status of the installer process.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtensionInstallerService.html

getInstallPath

java.lang.String getInstallPath()

Returns the directory where the installer is recommended to install the extension in. It is not required that the installer install in this directory, this is merely a suggested path.

getExtensionVersion

java.lang.String getExtensionVersion()

Returns the version of the extension being installed

getExtensionLocation

java.net.URL getExtensionLocation()

Returns the location of the extension being installed

hideProgressBar

void hideProgressBar()

Hides the progress bar. Any subsequent calls to updateProgress will force it to be visible.

hideStatusWindow

void hideStatusWindow()

Hides the status window. You should only invoke this if you are going to provide your own feedback to the user as to the progress of the install.

void setJREInfo(java.lang.String platformVersion, java.lang.String jrePath) Informs the JNLP Client of the path to the executable for the JRE, if this is an installer for a JRE, and about platform-version this JRE implements.

void setNativeLibraryInfo(java.lang.String path) Informs the JNLP Client of a directory where it should search for native libraries.

void setStatus(java.lang.String status) Updates the status of the installer process.

void updateProgress(int value) Updates the progress bar.

Method Detail


setHeading

void setHeading(java.lang.String heading)


setStatus

void setStatus(java.lang.String status)


updateProgress

void updateProgress(int value)

Updates the progress bar.

Parameters:value - progress bar value - should be between 0 and 100.

installSucceeded

void installSucceeded(boolean needsReboot)

Installers should invoke this upon a succesful installation of the extension. This will cause the JNLP Client to regain control and continue its normal operation.

Parameters:needsReboot - If true, a reboot is needed

installFailed

void installFailed()

This should be invoked if the install fails. The JNLP Client will continue its operation, and inform the user that the install has failed.

setJREInfo

void setJREInfo(java.lang.String platformVersion, java.lang.String jrePath)

Informs the JNLP Client of the path to the executable for the JRE, if this is an installer for a JRE, and about platform-version this JRE implements.


setNativeLibraryInfo

void setNativeLibraryInfo(java.lang.String path)

Informs the JNLP Client of a directory where it should search for native libraries.

getInstalledJRE

java.lang.String getInstalledJRE(java.net.URL url, java.lang.String version)

Returns the path to the executable for the given JRE. This method can be used by extensions that needs to find information in a given JRE, or enhance a given JRE.

Parameters:url - product location of the JREversion - product version of the JRE

Returns:The path to the executable for the given JRE, or null if the JRE is not installed.




javax.jnlp

Interface FileContents

public interface FileContents

FileContents objects encapsulate the name and contents of a file. An implementation of this class is used by the FileOpenService, FileSaveService, and PersistenceService.

The FileContents implementation returned by PersistenceService.get(java.net.URL), FileOpenService, and FileSaveService should never truncate a file if the maximum file length is set to be less that the current file length.

Since:1.0

See Also:FileOpenService, FileSaveService

getName


Method Summary boolean canRead()

Returns whether the file can be read. boolean canWrite()

Returns whether the file can be written to. java.io.InputStream getInputStream()

Gets an InputStream from the file. long getLength()

Gets the length of the file. long getMaxLength()

Gets the maximum file length for the file, as set by the creator of this object. java.lang.String getName()

Gets the file name as a String. java.io.OutputStream getOutputStream(boolean overwrite)

Gets an OutputStream to the file. JNLPRandomAccessFile getRandomAccessFile(java.lang.String mode)

Returns a JNLPRandomAccessFile representing a random access interface to the file's contents. long setMaxLength(long maxlength)

Sets the maximum file length for the file.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileContents.html

java.lang.String getName() throws java.io.IOException

Gets the file name as a String.

Returns:a string containing the file name.

Throws:java.io.IOException - if an I/O exception occurs.

getInputStream

java.io.InputStream getInputStream() throws java.io.IOException

Gets an InputStream from the file.

Returns:an InputStream to the file.


getOutputStream

java.io.OutputStream getOutputStream(boolean overwrite) throws java.io.IOException

Gets an OutputStream to the file. A JNLP client may implement this interface to return an OutputStream subclass which restricts the amount of data that can be written to the stream.

Returns:an OutputStream from the file.


getLength

long getLength() throws java.io.IOException

Gets the length of the file.

Returns:the length of the file as a long.


canRead


boolean canRead() throws java.io.IOException

Returns whether the file can be read.

Returns:true if the file can be read, false otherwise.


canWrite

boolean canWrite() throws java.io.IOException

Returns whether the file can be written to.

Returns:true if the file can be read, false otherwise.


getRandomAccessFile

JNLPRandomAccessFile getRandomAccessFile(java.lang.String mode) throws java.io.IOException

Returns a JNLPRandomAccessFile representing a random access interface to the file's contents. The mode argument must either be equal to "r" or "rw", indicating the file is to be opened for input only or for both input and output, respectively. An IllegalArgumentException will be thrown if the mode is not equal to "r" or "rw".

Parameters:mode - the access mode.

Returns:a JNLPRandomAccessFile.


getMaxLength

long getMaxLength() throws java.io.IOException

Gets the maximum file length for the file, as set by the creator of this object.

Returns:the maximum length of the file.



setMaxLength

long setMaxLength(long maxlength) throws java.io.IOException

Sets the maximum file length for the file. A JNLP client may enforce restrictions on setting the maximum file length. A JNLP client should not truncate a file if the maximum file length is set that is less than the current file size, but it also should not allow further writes to that file.

Parameters:maxlength - the requested new maximum file length.

Returns:the maximum file length that was granted.





javax.jnlp

Interface FileOpenService

public interface FileOpenService

FileOpenService service allows the user to choose a file from the local file system, even for applications that are running in the untrusted execution environment. The JNLP Client is the mediator and is therefore responsible for providing the specificimplementation of this, if any.

This service provides a similar function as the file input field for HTML-based forms.

Since:1.0

See Also:FileSaveService, FileContents

openFileDialog

FileContents openFileDialog(java.lang.String pathHint, java.lang.String[] extensions) throws java.io.IOException

Asks the user to choose a single file. The contents of a potential selected file is returned as a FileContents object. The returned FileContents object contains the contents along with the name of the file. The full path is not returned.

Parameters:pathHint - A hint from the application to the initial directory for the file chooser. This might be ignored by the JNLP Client.extensions - A list of default extensions to show in the file chooser. For example, String[] { "txt","java" }. This might be ignored by the JNLP Client.

Returns:A FileContent object with information about the chosen file, or null if the user did not choose a file.

Throws:IOException - if the request failed in any way other than the user did not choose to select a file.


Method Summary FileContents openFileDialog(java.lang.String pathHint, java.lang.String[] extensions)

Asks the user to choose a single file. FileContents

[] openMultiFileDialog(java.lang.String pathHint, java.lang.String[] extensions) Asks the user to choose one or more files.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileOpenService.html

java.io.IOException

openMultiFileDialog

FileContents[] openMultiFileDialog(java.lang.String pathHint, java.lang.String[] extensions) throws java.io.IOException

Asks the user to choose one or more files. Otherwise similar to openFileDialog(java.lang.String,java.lang.String[])




http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileOpenService.html

javax.jnlp

Interface FileSaveService

public interface FileSaveService

FileSaveService service allows the user to save a file to the local file system, even for applications that are running in the untrusted execution environment. The JNLP Client is the mediator and is therefore responsible for providing the specificimplementation of this, if any.

This service provides similar functionatlity as the Save as... functionality provided by most browsers.

Since:1.0

See Also:FileOpenService, FileContents

saveFileDialog

FileContents saveFileDialog(java.lang.String pathHint, java.lang.String[] extensions, java.io.InputStream stream, java.lang.String name) throws java.io.IOException

Asks the users to save a file.

Parameters:pathHint - A hint from the application to the default directory to be used. This might be ignored by the JNLP Client.extensions - A list of default extensions to show in the file chooser. For example, String[] { "txt","java" }. These might be ignored by the JNLP Client.stream - The content of the file to save along represented as an InputStreamname - The suggested filename, which might be ignored by the JNLP client


Method Summary FileContents saveAsFileDialog(java.lang.String pathHint, java.lang.String[] extensions,

FileContents contents) Asks the users to save a file.

FileContents saveFileDialog(java.lang.String pathHint, java.lang.String[] extensions, java.io.InputStream stream, java.lang.String name) Asks the users to save a file.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileSaveService.html

Returns:A FileContents object for the saved file if the save was successfully, or null if the user canceled the request.

Throws:IOException - if the requested failed in any way other than the user chose not to save the file java.io.IOException

saveAsFileDialog

FileContents saveAsFileDialog(java.lang.String pathHint, java.lang.String[] extensions, FileContents contents) throws java.io.IOException

Asks the users to save a file.

Parameters:pathHint - A hint from the application to the default directory to be used. This might be ignored by the JNLP Client.extensions - A list of default extensions to show in the file chooser. For example, String[] { "txt","java" }. These might be ignored by the JNLP Client.contents - The content of the file to save along with the suggested filename. The suggested filename might be ignored by the JNLP Client.

Returns:A FileContents object for the saved file if the save was successfully, or null if the user canceled the request.

Throws:IOException - if the requested failed in any way other than the user chose not to save the filejava.io.IOException



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileSaveService.html

javax.jnlp

Interface JNLPRandomAccessFile

All Superinterfaces:java.io.DataInput, java.io.DataOutput

public interface JNLPRandomAccessFileextends java.io.DataInput, java.io.DataOutput

Instances of this class support both reading and writing to a random access file. A random access file behaves like a large array of bytes stored in the file system. There is a kind of cursor, or index into the implied array, called the file pointer; input operations read bytes starting at the file pointer and advance the file pointer past the bytes read. If the random access file iscreated in read/write mode, then output operations are also available; output operations write bytes starting at the file pointer and advance the file pointer past the bytes written. Output operations that write past the current end of the implied array cause the array to be extended. The file pointer can be read by the getFilePointer method and set by the seek method.

It is generally true of all the reading routines in this class that if end-of-file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end-of-file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the stream has been closed.

Implementations are encouraged to enforce a maximum amount of data that may be written to a file.

Since:1.0


Method Summary void close()

Closes this random access file stream and releases any system resources associated with the stream. long getFilePointer()

Returns the current offset in this file. long length()

Returns the length of this file. int read()

Reads a byte of data from this file. int read(byte[] b)

Reads up to b.length bytes of data from this file into an array of bytes. int read(byte[] b, int off, int len)

Reads up to len bytes of data from this file into an array of bytes. boolean readBoolean()

Reads a boolean from this file. byte readByte()

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html

Reads a signed eight-bit value from this file. char readChar()

Reads a Unicode character from this file. double readDouble()

Reads a double from this file. float readFloat()

Reads a float from this file. void readFully(byte[] b)

Reads b.length bytes from this file into the byte array, starting at the current file pointer. void readFully(byte[] b, int off, int len)

Reads exactly len bytes from this file into the byte array, starting at the current file pointer. int readInt()

Reads a signed 32-bit integer from this file. java.lang.String readLine()

Reads the next line of text from this file. long readLong()

Reads a signed 64-bit integer from this file. short readShort()

Reads a signed 16-bit number from this file. int readUnsignedByte()

Reads an unsigned eight-bit number from this file. int readUnsignedShort()

Reads an unsigned 16-bit number from this file. java.lang.String readUTF()

Reads in a string from this file. void seek(long pos)

Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.

void setLength(long newLength) Sets the length of this file.

int skipBytes(int n) Attempts to skip over n bytes of input discarding the skipped bytes.

void write(byte[] b) Writes b.length bytes from the specified byte array to this file, starting at the current file pointer.

void write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to this file.

void write(int b) Writes the specified byte to this file.

void writeBoolean(boolean v) Writes a boolean to the file as a one-byte value.

void writeByte(int v) Writes a byte to the file as a one-byte value.

void writeBytes(java.lang.String s) Writes the string to the file as a sequence of bytes.

void writeChar(int v) Writes a char to the file as a two-byte value, high byte first.


close

void close() throws java.io.IOException

Closes this random access file stream and releases any system resources associated with the stream. A closed random access file cannot perform input or output operations and cannot be reopened.

Throws:java.io.IOException - if an I/O error occurs.

length

long length() throws java.io.IOException

Returns the length of this file.

Returns:the length of this file, measured in bytes.


getFilePointer

long getFilePointer() throws java.io.IOException

void writeChars(java.lang.String s) Writes a string to the file as a sequence of characters.

void writeDouble(double v) Converts the double argument to a long using the doubleToLongBits method in class Double, andthen writes that long value to the file as an eight-byte quantity, high byte first.

void writeFloat(float v) Converts the float argument to an int using the floatToIntBits method in class Float, and thenwrites that int value to the file as a four-byte quantity, high byte first.

void writeInt(int v) Writes an int to the file as four bytes, high byte first.

void writeLong(long v) Writes a long to the file as eight bytes, high byte first.

void writeShort(int v) Writes a short to the file as two bytes, high byte first.

void writeUTF(java.lang.String str) Writes a string to the file using UTF-8 encoding in a machine-independent manner.

Method Detail


Returns the current offset in this file.

Returns:the offset from the beginning of the file, in bytes, at which the next read or write occurs.


read

int read() throws java.io.IOException

Reads a byte of data from this file. The byte is returned as an integer in the range 0 to 255 (0x00-0x0ff). This method blocks if no input is yet available.

Although JNLPRandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream.

Returns:the next byte of data, or -1 if the end of the file has been reached.

Throws:java.io.IOException - if an I/O error occurs. Not thrown if end-of-file has been reached.

read

int read(byte[] b, int off, int len) throws java.io.IOException

Reads up to len bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Although JNLPRandomAccessFile is not a subclass of InputStream, this method behaves in the exactly the same way as the read(byte[], int, int) method of InputStream.

Parameters:b - the buffer into which the data is read.off - the start offset of the data.len - the maximum number of bytes read.

Returns:the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.


read

int read(byte[] b) throws java.io.IOException


Reads up to b.length bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Although JNLPRandomAccessFile is not a subclass of InputStream, this method behaves in the exactly the same way as the read(byte[]) method of InputStream.

Parameters:b - the buffer into which the data is read.

Returns:the total number of bytes read into the buffer, or -1 if there is no more data because the end of this file has been reached.


readFully

void readFully(byte[] b) throws java.io.IOException

Reads b.length bytes from this file into the byte array, starting at the current file pointer. This method reads repeatedly from the file until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readFully in interface java.io.DataInput

Parameters:b - the buffer into which the data is read.

Throws:EOFException - if this file reaches the end before reading all the bytes. java.io.IOException - if an I/O error occurs.

readFully

void readFully(byte[] b, int off, int len) throws java.io.IOException

Reads exactly len bytes from this file into the byte array, starting at the current file pointer. This method reads repeatedly from the file until the requested number of bytes are read. This method blocks until the requested number of bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readFully in interface java.io.DataInput

Parameters:b - the buffer into which the data is read.off - the start offset of the data.len - the number of bytes to read.

Throws:EOFException - if this file reaches the end before reading all the bytes. java.io.IOException - if an I/O error occurs.


skipBytes

int skipBytes(int n) throws java.io.IOException

Attempts to skip over n bytes of input discarding the skipped bytes.

This method may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. This method never throws anEOFException. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

Specified by:skipBytes in interface java.io.DataInput

Parameters:n - the number of bytes to be skipped.

Returns:the actual number of bytes skipped.


readBoolean

boolean readBoolean() throws java.io.IOException

Reads a boolean from this file. This method reads a single byte from the file, starting at the current file pointer. A value of 0 represents false. Any other value represents true. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Specified by:readBoolean in interface java.io.DataInput

Returns:the boolean value read.

Throws:EOFException - if this file has reached the end.java.io.IOException - if an I/O error occurs.

readByte

byte readByte() throws java.io.IOException

Reads a signed eight-bit value from this file. This method reads a byte from the file, starting from the current file pointer. If the byte read is b, where 0 <= b <= 255, then the result is:

(byte)(b)

This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Specified by:readByte in interface java.io.DataInput

Returns:


the next byte of this file as a signed eight-bit byte.Throws:

EOFException - if this file has reached the end. java.io.IOException - if an I/O error occurs.

readUnsignedByte

int readUnsignedByte() throws java.io.IOException

Reads an unsigned eight-bit number from this file. This method reads a byte from this file, starting at the current file pointer, and returns that byte.

This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Specified by:readUnsignedByte in interface java.io.DataInput

Returns:the next byte of this file, interpreted as an unsigned eight-bit number.

Throws:EOFException - if this file has reached the end. java.io.IOException - if an I/O error occurs.

readShort

short readShort() throws java.io.IOException

Reads a signed 16-bit number from this file. The method reads two bytes from this file, starting at the current file pointer. If the two bytes read, in order, are b1 and b2, where each of the two values is between 0 and 255, inclusive, then the result is equal to:

(short)((b1 << 8) | b2)

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readShort in interface java.io.DataInput

Returns:the next two bytes of this file, interpreted as a signed 16-bit number.

Throws:EOFException - if this file reaches the end before reading two bytes. java.io.IOException - if an I/O error occurs.

readUnsignedShort

int readUnsignedShort() throws java.io.IOException

Reads an unsigned 16-bit number from this file. This method reads two bytes from the file, starting at the current file


pointer. If the bytes read, in order, are b1 and b2, where 0 <= b1, b2 <= 255, then the result is equal to:

(b1 << 8) | b2


Specified by:readUnsignedShort in interface java.io.DataInput

Returns:the next two bytes of this file, interpreted as an unsigned 16-bit integer.


readChar

char readChar() throws java.io.IOException

Reads a Unicode character from this file. This method reads two bytes from the file, starting at the current file pointer. If the bytes read, in order, are b1 and b2, where 0 <= b1, b2 <= 255, then the result is equal to:

(char)((b1 << 8) | b2)


Specified by:readChar in interface java.io.DataInput

Returns:the next two bytes of this file as a Unicode character.


readInt

int readInt() throws java.io.IOException

Reads a signed 32-bit integer from this file. This method reads 4 bytes from the file, starting at the current file pointer. If the bytes read, in order, are b1, b2, b3, and b4, where 0 <= b1, b2, b3, b4 <= 255, then the result is equal to:

(b1 << 24) | (b2 << 16) + (b3 << 8) + b4

This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readInt in interface java.io.DataInput

Returns:the next four bytes of this file, interpreted as an int.


Throws:EOFException - if this file reaches the end before reading four bytes. java.io.IOException - if an I/O error occurs.

readLong

long readLong() throws java.io.IOException

Reads a signed 64-bit integer from this file. This method reads eight bytes from the file, starting at the current file pointer. If the bytes read, in order, are b1, b2, b3, b4, b5, b6, b7, and b8, where:

0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,

then the result is equal to:

((long)b1 << 56) + ((long)b2 << 48) + ((long)b3 << 40) + ((long)b4 << 32) + ((long)b5 << 24) + ((long)b6 << 16) + ((long)b7 << 8) + b8

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readLong in interface java.io.DataInput

Returns:the next eight bytes of this file, interpreted as a long.

Throws:EOFException - if this file reaches the end before reading eight bytes. java.io.IOException - if an I/O error occurs.

readFloat

float readFloat() throws java.io.IOException

Reads a float from this file. This method reads an int value, starting at the current file pointer, as if by the readIntmethod and then converts that int to a float using the intBitsToFloat method in class Float.

This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readFloat in interface java.io.DataInput

Returns:the next four bytes of this file, interpreted as a float.

Throws:EOFException - if this file reaches the end before reading four bytes. java.io.IOException - if an I/O error occurs.

See Also:readInt()


readDouble

double readDouble() throws java.io.IOException

Reads a double from this file. This method reads a long value, starting at the current file pointer, as if by the readLongmethod and then converts that long to a double using the longBitsToDouble method in class Double.

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readDouble in interface java.io.DataInput

Returns:the next eight bytes of this file, interpreted as a double.

Throws:EOFException - if this file reaches the end before reading eight bytes. java.io.IOException - if an I/O error occurs.

See Also:readLong()

readLine

java.lang.String readLine() throws java.io.IOException

Reads the next line of text from this file. This method successively reads bytes from the file, starting at the current file pointer, until it reaches a line terminator or the end of the file. Each byte is converted into a character by taking the byte's value for the lower eight bits of the character and setting the high eight bits of the character to zero. This method does not, therefore, support the full Unicode character set.

A line of text is terminated by a carriage-return character ('\r'), a newline character ('\n'), a carriage-return character immediately followed by a newline character, or the end of the file. Line-terminating characters are discarded and are not included as part of the string returned.

This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the file is reached, or an exception is thrown.

Specified by:readLine in interface java.io.DataInput

Returns:the next line of text from this file, or null if end of file is encountered before even one byte is read.


readUTF

java.lang.String readUTF() throws java.io.IOException

Reads in a string from this file. The string has been encoded using a modified UTF-8 format.

The first two bytes are read, starting from the current file pointer, as if by readUnsignedShort. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are


then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Specified by:readUTF in interface java.io.DataInput

Returns:a Unicode string.

Throws:EOFException - if this file reaches the end before reading all the bytes.java.io.IOException - if an I/O error occurs.UTFDataFormatException - if the bytes do not represent valid UTF-8 encoding of a Unicode string.

See Also:readUnsignedShort()

seek

void seek(long pos) throws java.io.IOException

Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.

Parameters:pos - the offset position, measured in bytes from the beginning of the file, at which to set the file pointer.

Throws:java.io.IOException - if pos is less than 0 or if an I/O error occurs.

setLength

void setLength(long newLength) throws java.io.IOException

Sets the length of this file.

If the present length of the file as returned by the length method is greater than the newLength argument then the file will be truncated. In this case, if the file offset as returned by the getFilePointer method is greater then newLengththen after this method returns the offset will be equal to newLength.

If the present length of the file as returned by the length method is smaller than the newLength argument then the file will be extended. In this case, the contents of the extended portion of the file are not defined.

Parameters:newLength - The desired length of the file

Throws:java.io.IOException - If an I/O error occurs

write

void write(int b)


throws java.io.IOException

Writes the specified byte to this file. The write starts at the current file pointer.

Specified by:write in interface java.io.DataOutput

Parameters:b - the byte to be written.


write

void write(byte[] b) throws java.io.IOException

Writes b.length bytes from the specified byte array to this file, starting at the current file pointer.


Parameters:b - the data.


write

void write(byte[] b, int off, int len) throws java.io.IOException

Writes len bytes from the specified byte array starting at offset off to this file.


Parameters:b - the data.off - the start offset in the data.len - the number of bytes to write.


writeBoolean

void writeBoolean(boolean v) throws java.io.IOException

Writes a boolean to the file as a one-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0. The write starts at the current position of the file pointer.


Specified by:writeBoolean in interface java.io.DataOutput

Parameters:v - a boolean value to be written.


writeByte

void writeByte(int v) throws java.io.IOException

Writes a byte to the file as a one-byte value. The write starts at the current position of the file pointer.

Specified by:writeByte in interface java.io.DataOutput

Parameters:v - a byte value to be written.


writeShort

void writeShort(int v) throws java.io.IOException

Writes a short to the file as two bytes, high byte first. The write starts at the current position of the file pointer.

Specified by:writeShort in interface java.io.DataOutput

Parameters:v - a short to be written.


writeChar

void writeChar(int v) throws java.io.IOException

Writes a char to the file as a two-byte value, high byte first. The write starts at the current position of the file pointer.

Specified by:writeChar in interface java.io.DataOutput

Parameters:v - a char value to be written.



writeInt

void writeInt(int v) throws java.io.IOException

Writes an int to the file as four bytes, high byte first. The write starts at the current position of the file pointer.

Specified by:writeInt in interface java.io.DataOutput

Parameters:v - an int to be written.


writeLong

void writeLong(long v) throws java.io.IOException

Writes a long to the file as eight bytes, high byte first. The write starts at the current position of the file pointer.

Specified by:writeLong in interface java.io.DataOutput

Parameters:v - a long to be written.


writeFloat

void writeFloat(float v) throws java.io.IOException

Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the file as a four-byte quantity, high byte first. The write starts at the current position of the file pointer.

Specified by:writeFloat in interface java.io.DataOutput

Parameters:v - a float value to be written.


writeDouble

void writeDouble(double v) throws java.io.IOException

Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the file as an eight-byte quantity, high byte first. The write starts at the current position of the file pointer.


Specified by:writeDouble in interface java.io.DataOutput

Parameters:v - a double value to be written.


writeBytes

void writeBytes(java.lang.String s) throws java.io.IOException

Writes the string to the file as a sequence of bytes. Each character in the string is written out, in sequence, by discarding its high eight bits. The write starts at the current position of the file pointer.

Specified by:writeBytes in interface java.io.DataOutput

Parameters:s - a string of bytes to be written.


writeChars

void writeChars(java.lang.String s) throws java.io.IOException

Writes a string to the file as a sequence of characters. Each character is written to the data output stream as if by the writeChar method. The write starts at the current position of the file pointer.

Specified by:writeChars in interface java.io.DataOutput

Parameters:s - a String value to be written.


See Also:writeChar(int)

writeUTF

void writeUTF(java.lang.String str) throws java.io.IOException

Writes a string to the file using UTF-8 encoding in a machine-independent manner.

First, two bytes are written to the file, starting at the current file pointer, as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for each character.

Specified by:


writeUTF in interface java.io.DataOutputParameters:

str - a string to be written. Throws:

java.io.IOException - if an I/O error occurs.




javax.jnlp

Interface PersistenceService

public interface PersistenceService

PersistenceService provides methods for storing data locally on the client system, even for applications that are running in the untrusted execution environment. The service is somewhat similar to that which the cookie mechanism provides to HTML-based applications.

Each entry in the persistence data store is named with a URL. This provides a similar hierarchical structure as a traditional filesystem.

An application is only allowed to access data stored with a URL that is based on its codebase. For example, given the codebasehttp://www.mysite.com/apps/App1/, the application would be allowed to access the data at the associated URLs:

http://www.mysite.com/apps/App1/ http://www.mysite.com/apps/ http://www.mysite.com/

This scheme allows sharing of data between different applications from the same host. For example, if another application is located at http://www.mysite.com/apps/App2/, then they can share data between them in the http://www.mysite.com/and http://www.mysite.com/apps/ directories.

A JNLP client should track the amount of storage that a given application uses. A PersistenceService implementation provides methods to get the current storage usage and limits and to request more storage. Storage is allocated on a per file basis, but a JNLP Client will typically grant or deny the request based on the total storage is use by an application.

Data stored using this mechanism is intended to be a local copy of data stored on a remote server. The individual entries can be tagged as either cached, meaning the server has an up-to-date copy, dirty, meaning the server does not have an up-to-date copy, or temporary, meaning that the file can always be recreated.

Since:1.0


Field Summarystatic int CACHED

static int DIRTY

static int TEMPORARY

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/PersistenceService.html

CACHED

static final int CACHED

See Also:Constant Field Values

TEMPORARY

static final int TEMPORARY


DIRTY

static final int DIRTY


create

long create(java.net.URL url, long maxsize) throws java.net.MalformedURLException, java.io.IOException

Method Summary long create(java.net.URL url, long maxsize)

Creates a new persistent storage entry on the client side named with the given URL. void delete(java.net.URL url)

Removes the stream associated with the given URL from the client-side date persistence store. FileContents get(java.net.URL url)

Returns a FileContents object representing the contents of this file. java.lang.String

[] getNames(java.net.URL url) Returns an array of Strings containing the names of all the entries for a given URL.

int getTag(java.net.URL url) Returns an int corresponding to the current value of the tag for the persistent data store entry associated with the given URL.

void setTag(java.net.URL url, int tag) Tags the persistent data store entry associated with the given URL with the given tag value.

Field Detail

Method Detail


Creates a new persistent storage entry on the client side named with the given URL.

Parameters:url - the URL representing the name of the entry in the persistent data store.maxsize - maximum size of storage that can be written to this entry.

Returns:the maximum size of storage that got granted, in bytes.

Throws:java.net.MalformedURLException - if the application is denied access to the persistent data store represented by the given URL.java.io.IOException - if an I/O exception occurs, or the entry already exists.

get

FileContents get(java.net.URL url) throws java.net.MalformedURLException, java.io.IOException, java.io.FileNotFoundException

Returns a FileContents object representing the contents of this file.

Parameters:url - the URL representing the persistent data store entry.

Returns:the file contents as a FileContents.

Throws:java.io.IOException - if an I/O error occurs.java.net.MalformedURLException - if the application is denied access to the persistent data store represented by the given URL.java.io.FileNotFoundException - if a persistence store for the given URL is not found.

delete

void delete(java.net.URL url) throws java.net.MalformedURLException, java.io.IOException

Removes the stream associated with the given URL from the client-side date persistence store.

Parameters:url - the URL representing the entry to delete from the persistent data store.

Throws:java.net.MalformedURLException - if the application is denied access to the persistent data store represented by the given URL. java.io.IOException - if an I/O exception occurs.

getNames

java.lang.String[] getNames(java.net.URL url) throws java.net.MalformedURLException, java.io.IOException


Returns an array of Strings containing the names of all the entries for a given URL.

Parameters:url - the URL representing the root directory to search for entry names.

Returns:a String array containing the entries names.

Throws:java.net.MalformedURLException - if the application is denied access to the persistent data store representedby the given URL. java.io.IOException - if an I/O exception occurs.

getTag

int getTag(java.net.URL url) throws java.net.MalformedURLException, java.io.IOException

Returns an int corresponding to the current value of the tag for the persistent data store entry associated with the given URL.

Parameters:url - the URL representing the persistent data store entry for which the tag value is requested.

Returns:an int containing one of the following tag values:

CACHED TEMPORARY DIRTY

Throws:java.net.MalformedURLException - if the application is denied access to the persistent data store represented by the given URL. java.io.IOException - if an I/O exception occurs.

setTag

void setTag(java.net.URL url, int tag) throws java.net.MalformedURLException, java.io.IOException

Tags the persistent data store entry associated with the given URL with the given tag value.

Parameters:url - the URL representing the persistent data store entry for which to set the tag value.tag - the tag value to set.

Throws:java.net.MalformedURLException - if the application is denied access to the persistent data store represented by the given URL.java.io.IOException - if an I/O exception occurs.



javax.jnlp

Interface PrintService

public interface PrintService

PrintService provides methods for access to printing functions, even for applications that are running in the untrusted execution environment. Using this service, an application can submit a print job to the JNLP client. The client can then display this request to the user, and if accepted, queue the request to the printer.

Since:1.0

getDefaultPage

java.awt.print.PageFormat getDefaultPage()

Creates a new PageFormat instance and sets it to the default size and orientation.

Returns:a PageFormat set to the default size and orientation.

showPageFormatDialog

java.awt.print.PageFormat showPageFormatDialog(java.awt.print.PageFormat page)

Displays a dialog that allows modification of a PageFormat instance. The page argument is used to initialize controls in the page setup dialog. If the user cancels the dialog then this method returns the original page object unmodified. If the


Method Summary java.awt.print.PageFormat getDefaultPage()

Creates a new PageFormat instance and sets it to the default size and orientation. boolean print(java.awt.print.Pageable document)

Prints a document using the given Pageable object boolean print(java.awt.print.Printable painter)

Prints a document using the given Printable object java.awt.print.PageFormat showPageFormatDialog(java.awt.print.PageFormat page)

Displays a dialog that allows modification of a PageFormat instance.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/PrintService.html

user okays the dialog then this method returns a new PageFormat object with the indicated changes. In either case, the original page object is not modified.

Parameters:page - the default PageFormat presented to the user for modification.

Returns:the original page object if the dialog is cancelled; a new PageFormat object containing the format indicated by the user if the dialog is acknowledged.

print

boolean print(java.awt.print.Pageable document)

Prints a document using the given Pageable object

Parameters:document - the pages to be printed. It can not be null.

Returns:true if printing was successfull, false otherwise.

print

boolean print(java.awt.print.Printable painter)

Prints a document using the given Printable object

Parameters:painter - the Printable called to render each page of the document.

Returns:true if printing was successfull, false otherwise.



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/PrintService.html

javax.jnlp

Interface ServiceManagerStub

public interface ServiceManagerStub

A ServiceManagerStub object implements the particular lookup of JNLP services by the JNLP Client. The object is registered with the ServiceManager using the ServiceManager.setServiceManagerStub(javax.jnlp.ServiceManagerStub) method.

Since:1.0

See Also:ServiceManager

lookup

java.lang.Object lookup(java.lang.String name) throws UnavailableServiceException

See description for ServiceManager.lookup(java.lang.String)

Throws:UnavailableServiceException

getServiceNames

java.lang.String[] getServiceNames()

See description for ServiceManager.getServiceNames()



Method Summary java.lang.String

[] getServiceNames() See description for ServiceManager.getServiceNames()

java.lang.Object lookup(java.lang.String name) See description for ServiceManager.lookup(java.lang.String)

Method Detail


http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ServiceManagerStub.html

javax.jnlp

Interface SingleInstanceListener

public interface SingleInstanceListener

SingleInstanceListener is a interface which should be implemented by a JNLP application if they wish to support single instance behaviour.

Since:1.5

newActivation

void newActivation(java.lang.String[] params)

This method should be implemented by the application to handle the single instance behaviour - how should the application handle the arguments when another instance of the application is invoked with params.

Parameters:params - Array of parameters for the application main (arguments supplied in the jnlp file)



Method Summary void newActivation(java.lang.String[] params)

This method should be implemented by the application to handle the single instance behaviour - how should the application handle the arguments when another instance of the application is invoked with params.

Method Detail


http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceListener.html

javax.jnlp

Interface SingleInstanceService

public interface SingleInstanceService

SingleInstanceService allow applications launched under Java Web Start to register themselves as singletons, and to be passed in new parameter sets when user attempts to launch new instances of them.

Since:1.5

addSingleInstanceListener

void addSingleInstanceListener(SingleInstanceListener sil)

Adds the specified SingleInstanceListener to handle how the application/applet should behave when another instance of the same application/applet is invoked. If SingleInstanceListener sil is null, no exception is thrown and no action isperformed.

Parameters:sil - the SingleInstanceListener object to be added

removeSingleInstanceListener

void removeSingleInstanceListener(SingleInstanceListener sil)

Removes the specified SingleInstanceListener. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to the application/applet. If listener sil is null, no exception is thrown and no action is performed. It is recommended that if an application/applet registered any SingleInstanceListener(s), it should call this method to remove all listeners upon exit of the application/applet.


Method Summary void addSingleInstanceListener(SingleInstanceListener sil)

Adds the specified SingleInstanceListener to handle how the application/applet should behave when another instance of the same application/applet is invoked.

void removeSingleInstanceListener(SingleInstanceListener sil) Removes the specified SingleInstanceListener.

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceService.html

Parameters:sil - the SingleInstanceListener object to be removed



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceService.html

javax.jnlp

Class ServiceManager

java.lang.Object javax.jnlp.ServiceManager

public final class ServiceManagerextends java.lang.Object

The ServiceManager provides static methods to lookup JNLP services. This class is abstract and final and cannot be instantiated.

Requests are delegated to a ServiceManagerStub object. This object must be set by the JNLP Client on startup using the setServiceManagerStub method.

Since:1.0

See Also:ServiceManagerStub

lookup

public static java.lang.Object lookup(java.lang.String name) throws UnavailableServiceException

Asks the JNLP Client for a service with a given name. The lookup must be idempotent, that is return the same object for each invocation with the same name.


Method Summarystatic java.lang.String

[] getServiceNames() Returns the names of all services implemented by the JNLP Client.

static java.lang.Object lookup(java.lang.String name) Asks the JNLP Client for a service with a given name.

static void setServiceManagerStub(ServiceManagerStub stub) Sets the object that all lookup and getServiceNames requests are delegated to.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ServiceManager.html

Parameters:name - Name of service to lookup.

Returns:An object implementing the service. null will never be returned. Instead an exception will be thrown.

Throws:UnavailableServiceException - if the service is not available, or if name is null. UnavailableServiceException

getServiceNames

public static java.lang.String[] getServiceNames()

Returns the names of all services implemented by the JNLP Client.

setServiceManagerStub

public static void setServiceManagerStub(ServiceManagerStub stub)

Sets the object that all lookup and getServiceNames requests are delegated to. The setServiceManagerStub call isignored if the stub has already been set.

This method should be called exactly once by the JNLP Client, and never be called by a launched application.

Parameters:stub - The ServiceManagerStub object to delegate to



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ServiceManager.html

javax.jnlp

Class UnavailableServiceException

java.lang.Object java.lang.Throwable java.lang.Exception javax.jnlp.UnavailableServiceException

All Implemented Interfaces:java.io.Serializable

public class UnavailableServiceExceptionextends java.lang.Exception

The UnavailableServiceException is thrown by the ServiceManager when a non-existing or unavailable service is lookedup.

Since:1.0

See Also:ServiceManager, Serialized Form

UnavailableServiceException


Constructor SummaryUnavailableServiceException() Constructs an UnavailableServiceException with null as its error detail message.

UnavailableServiceException(java.lang.String msg) Constructs an UnavailableServiceException with the specified detail message.

Method Summary

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/UnavailableServiceException.html

public UnavailableServiceException()

Constructs an UnavailableServiceException with null as its error detail message.

UnavailableServiceException

public UnavailableServiceException(java.lang.String msg)

Constructs an UnavailableServiceException with the specified detail message. The error message string s can later be retrieved by the Throwable.getMessage() method of class java.lang.Throwable.

Parameters:msg - the detail message.



http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/UnavailableServiceException.html

javaws Command Line

NAME

javaws - Java Web Start launcher command

SYNOPSIS

javaws [run-options] <jnlp>

javaws [control-options]

PARAMETERS

[run-options]

Command-line run-options. run-options may be in any order. For a discussion of the various run-options, see RUN-OPTIONS below.

<jnlp>

This can be either the path of, or the Uniform Resource Locater (URL) of the JNLP (Java Network Launching Protocol) file.

[control-options]

Command-line control-options. control-options may be in any order. For a discussion of the various control-options, see CONTROL-OPTIONS below.

DESCRIPTION

The javaws command launches Java Web Start, which is the reference implementation of the Java Network Launching Protocol (JNLP). Java Web Start launches Java applications/applets hosted on a network.

If a JNLP file is specified, javaws will launch the Java application/applet specified in the JNLP file.

The javaws launcher has a set of options that are supported in the current release. However, the options may be removed in a future release.

RUN-OPTIONS

-offline

run Java Web Start in offline mode.

-Xnosplash

disable the display of the initial splash screen.

http://java.sun.com/javase/6/docs/technotes/tools/share/javaws.html

-open <arguments>

If specified, replaces the arguments in the jnlp file with -open <arguments>.

-print <arguments>

If specified, replaces the arguments in the jnlp file with -print <arguments>.

-online

run in online mode (default behavior).

-wait

If specified, the javaws process will not exit until the application exits.

-verbose

display additional output.

-J<option>

supply options to the vm.

-system

run the application from the system cache only.

CONTROL-OPTIONS

-viewer

show the Cache Viewer in the java control panel

-userConfig <property name>

clear the specified deployment property.

-userConfig <property name> <property value>

set the specified deployment property to the specified value.

-uninstall

remove all applications from the cache.

-uninstall <jnlp>

remove the application from the cache.

-import [import-options] <jnlp>

import the application to the cache.

IMPORT-OPTIONS

-silent


import silently (with no user interface).

-system

import application to the system cache.

-codebase <url>

retrieve resources from the given codebase.

-shortcut

install shortcuts as if user allowed prompt. This option has no effect unless -silent option is also used.

-association

install associations as if user allowed prompt. This option has no effect unless -silent option is also used.

FILES

For information about the user and system cache and deployment.properties files, see System- and User-Level Properties.

MORE INFORMATION

For more information about Java Web Start, see Java Web Start.


JavaTM Web Start version 6

Frequently Asked Questions (FAQ)

FAQ Update (March 2006)

1. Where can I find the Web Start chat session transcripts from March, 2005? 2. What are some troubleshooting hints for Web Start applications?3. What is the story on auto-downloading jres?4. How do you use the CD install feature?5. How do you use the new Enterprise Configuration features?

General Questions

1. What is Java Web Start?2. Where do I get more information?3. Why should I use Java Web Start?4. How can I launch applications with Java Web Start?5. Does it matter how I launch an application?6. What are the system requirements for Java Web Start?7. What platforms does Java Web Start run on?8. What are the server requirements for Java Web Start?9. Is Java Web Start based on a standard?

10. Can I implement my own Java Web Start?11. What are the supported browsers?12. Is there a comprehensive list of online resources for Java Web Start?13. Can I deploy any application with Java Web Start?14. Is Java Web Start a software distribution mechanism like Marimba and MS SMS?15. Is Java Web Start an application installer?16. What version of the Java platform does Java Web Start work with?17. How does Java Web Start relate to Java Plug-in Technology (applets)?

Technical Questions

1. Do I need to change my application to work with Java Web Start?2. Is there a migration path from applets to applications?3. Is there a way to pass VM arguments to the Java Runtime?4. I don't want to rely on a server timestamp. How can I specify a versioned JAR and how can I get incremental updates of

JARs?5. Are JAR files shared between applications?6. How can I provide my own splash screen?7. How can I save the application state on the local system?8. My application requires a specific version of the JRE. How do I specify this my JNLP file?9. Can I rely on Class-Path in the manifest file?

10. Can I use Java Web Start even if my Application depends on or uses native code?11. How can I load resources within my application using Class.forName and ClassLoader.getSystemClassLoader?12. How can I launch Java Web Start from the command line?13. How do I use multiple JAR files signed by different certificates?14. How do I detect if Java Web Start is installed?

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html

15. Why does my browser shows JNLP file as plain text.16. Why does Java Web Start always reload JAR files from IIS server?17. Can I use Pack200 compression with the JnlpDownloadServlet?18. What is the best way to ensure only one instance of my app is run?19. When will properties set in the jnlp file get set?20. What causes the file not found message for the downloaded jnlp file?21. How can I use signed jars (such as JCE extensions) signed for other purposes?22. Why can't I use the Association feature on some linux platforms with Gnome?23. How do I set up my server to broadcast the jnlp mime type?24. How do I set up my server to use the JnlpDownloadServlet?25. How are Applications uniquely identified?26. How do I create multiple file-extension/mime-type associations with a JNLP application? 27. Why does FindClass() sometimes fail when called from native code?

Security Questions

1. How secure is Java Web Start?2. What is a secure sandbox?3. How is the Java Web Start secure sandbox more flexible than the applet sandbox?4. How can I enable my application to gain unrestricted access to the system?5. Is there support for encrypted download of JAR files?6. Can I use NTLM authentication with Java Web Start?7. Can I use HTTPS protocol with Java Web Start?8. Are there online resources to learn more about the security tools?

Known Bugs

1. 4825415: Web Start desktop integration and security dialogs disappear in 1.4.22. 4491398: Dependent DLL resource problem3. 5008460: Web Start fails if path contains spaces and TraceSecurity is turned on.4. 5074087: If related-content is specified w/o a title on Windows, application cannot start.5. 5074524: First jar of unsigned extension must be downloaded eagerly6. 5047548: Lazy downloading of parts with packages is broken7. 5074526: ExtenededService file APIs show security dialog even if app is signed8. 4925768: No support for system level shortcuts in Gnome.9. 5072969: Startup errors causing Web Start to appear to hang

10. 5074530: Web Start not picking up the correct JRE.

March 2006 Updates:

Where can I find the Web Start chat session transcripts from March, 2005 ?

The chat session transcripts can be seen here.

What are some troubleshooting hints for Web Start applications?See the notes on troubleshooting and debugging here

What is the story on auto-downloading jres?See the notes on auto-download here

How do you use the CD install feature?See the notes on the import feature and CD-Install here

How do you use the Enterprise Configuration features?See the notes on enterprise configuration management here


General Questions

What is Java Web Start?

Java Web Start provides a platform-independent, secure, and robust deployment technology. It enables developers to deploy full-featured applications to end-users by making the applications available on a standard web server. With any web browser, end-users can launch the applications and be confident they always have the most-recent version. Back to top

Where do I get more information?

Look at the online documentation for Java Web Start .

If you are a developer, go to the Developer's Guide for detailed technical information on how to deploy applications using Java Web Start. Back to top

Why should I use Java Web Start?

It's an easy, robust, and secure way to deploy applications directly from the web. Developers can make applications readily available via the web. In addition, Java Web Start provides Java runtime environment (JRE) management capabilities, it's easy to set up, it's browser-independent, and it's an efficient way to deploy web application solutions.

Users can easily access applications much as they would a web page--without a separate installation step. From the desktop, users can access and use Java applications, using a richer and more responsive user interface than is available on a web page. And, once a Java Web Start based application is installed, users simply click to run the application whenever needed.

Users do not need to manually update applications because each time they launch an application, it is transparently updated from the web--so they always use the most recent version available. Back to top

How can I launch applications with Java Web Start?

You initially launch a new application by clicking on a link from a web page.

If you use an application frequently, create a shortcut from your desktop or from the Start Menu by allowing Java Web Start to place an icon on your desktop. Java Web Start may ask if you would like to create shortcuts or an entry in the Start Menu. If you say "yes," all future launches of the application can start without a browser.

Java Web Start also provides an Application Cache Viewer which you can launch from the Java Control Panel. The Cache Viewer enables you to directly launch applications you have downloaded.

You can also launch an application from a command prompt by typing “javaws <jnlp_url>” where <jnlp_url is a url to the jnlp file of the application.Back to top

Does it matter how I launch an application?

No, applications launch in the same manner no matter which method you use: from a web page, from the shortcut on the desktop, from the Start menu, or through the Java Application Cache Viewer.

Java Web Start always checks to see if a newer version of the application is available for use and automatically downloads it if so.

If the application you are using has not been digitally signed, Java Web Start will launch it in a restricted and secure


execution environment. An application that is not signed, or one that you do not trust, will never be run with unrestricted access to your local system or network. Back to top

What are the system requirements for Java Web Start?

Any client system that supports the Java version 1.2.2 or higher can use Java Web Start. Java Web Start works with virtually all browsers. Back to top

What platforms does Java Web Start run on?

Sun Microsystems provides versions for Windows 98/NT/2000/XP/2003, Solaris Operating Environment (SPARC and Intel editions) and Linux/i486. Apple provides a version for their OS X release. Back to top

What are the server requirements for Java Web Start?

Java Web Start uses HTTP for communication between the client and the server. You can use a standard web server to host an application. If you require additional services, such as version-based downloading, incremental updates, or pack200 compression for your applications, the web server will need to support servlets or Java Server Pages. A sample servlet implementing these features is provided in the samples directory of the JDK.Back to top

Is Java Web Start based on a standard?

Yes. Java Web Start 1.5.0 is the product-quality reference implementation of Java Network Launching Protocol (JNLP) technology, which was developed through the Java Community Process. JNLP is specification number JSR 056. Other platform vendors are encouraged to port Java Web Start to their platform or implement the specification.

For more information, see the JNLP specification. Back to top

Can I implement my own Java Web Start?

The underlying technology for Java Web Start, the Java Network Launching Protocol and API is being developed through the Java Community Process, so you can implement this protocol in any product. However additional licensing and terms must be met to implement any JCP technology including the JNLP technology. Back to top

What are the supported browsers?

Java Web Start supports primarily Internet Explorer 4 or higher and Mozilla. However any browser can launch JNLP files if you have set the MIME-type association correctly. Java Web Start uses the browser's settings and may launch a browser to show a URL; this feature may not work with unsupported browsers. Back to top

Is there a comprehensive list of online resources for Java Web Start?

Java Web Start documentation page: http://java.sun.com/j2se/1.5.0/docs/guide/javaws/index.html Developer's Guide: http://java.sun.com/j2se/1.5.0/docs/guide/javaws/developersguide/contents.html Java Web Start Discussion Forums: http://forum.java.sun.com/forum.jsp?forum=38 JSR-56: http://jcp.org/en/jsr/detail?id=56

Back to top


Can I deploy any application with Java Web Start?

Java Web Start is an application launcher for Java applications that are written to be web-deployed.

An application must be delivered in a set of JAR files and all application resources, such as images, configuration files, and native libraries must be included in the JAR files. The resources must be looked up using the method ClassLoader.getResource() or an equivalent method. Java Web Start only transfers JAR files from the web server to the client.

If an application is written to run in a restricted execution environment (sandbox), then access to disk is not permitted and the application may only connect to the host on which it resides. Back to top

Is Java Web Start a software distribution mechanism like Marimba and MS SMS?

Java Web Start is an application launcher for Java applications. It allows easy distribution of full-featured applications based on the Java platform from a web server to a client machine with minimal user interaction.

The software distribution technology is only one aspect of Java Web Start. It also provides security, updates to the applications, ease-of-use for end users, and flexibility for developers when they create the applications. Back to top

Is Java Web Start an application installer?

Java Web Start is an application launcher for Java applications that are written to be web-deployed. Java Web Start caches resources locally on the disk, but also provides a secure execution environment and a virtually transparent updating facility for applications. The end user does not need to manually initiate a software update because the application is updated each time it is used. Back to top

What version of the Java platform does Java Web Start work with?

Java Web Start launches only applications written for the Java platform versions 1.2.2 and higher. Back to top

How does Java Web Start relate to Java Plug-in Technology (applets)?

The two approaches are very similar. The key difference is in the user experience. If the Java application/applet needs to interact with a web page and be tightly bound to a web browser, then applets may be the solution. On the other hand, if browser independence is important, then Java Web Start is the deployment platform of choice. There are a number of other differences, but this is the fundamental difference.

Java Plug-in technology enables users to run Java applets inside a browser.

Java Web Start enables users to download full-featured applications with any browser. Once they have downloaded and launched an application, the browser can be closed, while the application continues working. The application does not depend on an open browser to function. The browser can be shut down or you can go to a different web page and the application will continue running. Back to top

Technical Questions

Do I need to change my application to work with Java Web Start?

If your application is written to the Java 2 platform, and is delivered as a set of JAR files, there should be no need to revise your application. Make sure that your application retrieves all its resources (such as images and resource bundles)


from a JAR file, since Java Web Start launches an application by invoking the public static void main(String[] args) method.

If your application needs unrestricted access to the system, (for example, network or disk access), you will need to sign your code. Back to top

Is there a migration path from applets to applications?

Java Web Start is primarily designed for application deployment. You specify all requirements for your application in the JNLP file, and off you go. It does provide the ability to launch applets in much the same way as the traditional AppletViewer. The built-in AppletViewer provides an easy migration path for existing applets that want to take advantage of Java Web Start. However, it is not intended to be a full implementation of the Plug-In. The Plug-In is the primary launching vehicle for applets. The built-in AppletViewer in Java Web Start has limitations, for example, you cannot specify class files as resources and it does not accept policy files. Back to top

Is there a way to pass VM arguments to the Java Runtime?

Java Web Start allows certain JVM flags to be set with the java-vm-args attribute of the j2se element (see Developer's Guide). Allowing the complete set could compromise security as well as limit portability across different platforms and implementations. You can set the maximum and initial heap size using the initial-heap-size and max-heap-size attributes of the j2se element, for example:

<j2se version="..." max-heap-size="100M"/>

Back to top

I don't want to rely on a server timestamp. How can I specify a versioned JAR and how can I get incremental updates of JARs?

Java Web Start supports versioned JARs and incremental updates. You can specify exact versions of the JAR files you want, instead of relying on timestamp information to determine if an update is available. Using version IDs also allows you to provide incremental updates from one version to another. See the JNLP Specification or the Developer's Guide for details.Back to top

Are JAR files shared between applications?

Each JAR file that a JNLP Client (such as Java Web Start) downloads, is uniquely identified with a URL. If two JNLP files use the same URL, then the resource will only be downloaded once and shared. This is similar to the caching implementations used by web browsers. Back to top

How can I provide my own splash screen?

Java Web Start needs to put up the initial splash screen while Java is loading. For subsequent access, you can specify an image file to use for the splash screen in the JNLP file with the tag

<icon href="mysplash.jpg" kind="splash"/>

where mysplash.jpg is the image file for your splash screen. The first time your application runs, it will use the standard splash screen. After that, it will use the image you provide. Back to top

How can I save the application state on the local system?


A sandboxed application can store state using the PersistenceService API. This API is similar to cookies for HTML pages. Thus, it is a secure way to store persistent information on the client computer. For more information, see:

JNLP Specification Java Web Start Developers Guide

Back to top

My application requires a specific version of the JRE. How do I specify this my JNLP file?

The tag <j2se version="versionNum"> specifies a platform version, where versionNum is 1.2, 1.3, 1.4, or 1.5.

You can request a specific product version by including a vendor URL in the href attribute. For Sun's JREs, the URL is http://java.sun.com/products/autodl/j2se For example, the following J2SE tag will request any Sun 1.3.1 implementation:

<j2se version="1.3.1*" href="http://java.sun.com/products/autodl/j2se"/>

You can see all the versions of the installed JREs in the Java tab of the Java Control Panel. Back to top

Can I rely on Class-Path in the manifest file?

Java Web Start does not support the Class-Path entry in the manifest file. The Class-Path attribute is entirely file-centric, whereas Java Web Start and JNLP is web-centric, i.e., based on URLs. Thus, the two models do not merge easily.

Instead of relying on the Class-Path entry, you can list multiple JAR files in the JNLP file, for example:

<resources> <jar href="A.jar"/> <jar href="B.jar"/></resources>

In a JNLP file, you can factor out dependencies on a set of JAR files to another JNLP file using the <extension... >element. Thus, you can achieve the same kind of re-usability and ease of maintenance as you do with the Class-Path entry. This feature is described in the specification.

JNLP also implements a just-in-time downloading mechanism, similar to applets. For each resource in a JNLP file, you can specify which parts should be eagerly or lazily downloaded. Eagerly loaded resources are loaded before the application is launched, lazily loaded resources later. Default is eager download. Furthermore, the specification includes an API for which you can programatically query Java Web Start about which resources are available and request them to be downloaded. Thus, you can write download/network aware applications.

See the JNLP specification for more information. Back to top

Can I use Java Web Start even if my application depends on or uses native code?

You can use Java Web Start to deploy Java Technology-based applications that depend on native code such as DLLs and SOs. Use the <nativelib ...> element to specify required native libraries. See the Developer's Guide for details.Back to top

How can I load resources within my application using Class.forName and ClassLoader.getSystemClassLoader?

Java Web Start uses a user-level classloader to load all the application resources specified in the JNLP file. This classloader implements the security model and the downloading model defined by the JNLP specification. This is no different than how the AppletViewer or the Java Plug-In works.


This has the, unfortunate, side-effect that Class.forName will not find any resources that are defined in the JNLP file. The same is true for looking up resources and classes using the system class loader (ClassLoader.getSystemClassLoader).

To find application resources in Java Web Start, use the classloader that loaded your application, for example use the following call in the in the application;s main thread:

this.getClass().getClassLoader();

You can also use:

Thread.getCurrent().getContextClassLoader();Back to top

How can I launch Java Web Start from the command line?

You can launch Java Web Start from the command line as follows:

javaws [options] your-app-JNLP-URL

where your-app-JNLP-URL is the location of your application's JNLP file. For example:

javaws http://java.sun.com/products/demos/swingset2.jnlp

For complete command line syntax see: the Developer's GuideBack to top

How do I use multiple JAR files signed by different certificates?

The JNLP 1.0 specification requires all JAR files used in a JNLP file to be signed by the same certificate. This restriction avoids requiring the user to accept multiple certificates from the same source, and enables Java Web Start to know if the user has accepted all certificates used for an application.

However, Java Web Start can use multiple JAR files signed by different certificates, by using the component extension mechanism and multiple JNLP files. The only requirement is that the JAR files contain code from different packages. So, instead of the following:

<jar href="myjar1.jar"/><jar href="jh.jar"/>

Use the following:

<jar href="myjar1.jar"/><extension name="Java Help" href="help.jnlp"/>

Then add a help.jnlp file with the following contents:

<?xml version="1.0" encoding="utf-8"?> <jnlp spec="1.0+"codebase="http://ws503" href="Help.jnlp"> <information><title>JavaHelp</title><vendor>Sun Microsystems, Inc.</vendor> </information><resources><jar href="jh.jar"/></resources> <component-desc/></jnlp>


Back to top

How do I detect if Java Web Start is installed?

You can write a short JavaScript or VBScript to detect if Java Web Start is installed. See the Developer's Guide for details.Back to top

Why does my browser shows JNLP file as plain text ?

This is most likely happening because your web server is not aware of the proper MIME type for JNLP files. Java Web Start requires only one change to your web server, that is creating an association between the file extension, typically jnlp, and the MIME type, application/x-java-jnlp-file. The steps for doing this vary depending upon the web server you are using.

Furthermore, if your corporation uses 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. Back to top

Why does Java Web Start always reload JAR files from IIS server?

If a timestamp of the file on the IIS server is in the future IIS returns current-time as last-modified time. This makes Java Web Start to reload the JARs since time-stamp is always newer. Back to top

Can I use Pack200 compression with the JnlpDownloadServlet?

Yes. The JnlpDownloadServlet distributed in the samples directory of the JDK now supports Pack200. If you deploy yourfile.jar along with yourfile.jar.pack.gz the packed file will be downloaded when the client is running Java Web Start 1.5.0 or later.Back to top

What is the best way to ensure only one instance of my application is run?

Use the SingleInstanceService to register as a singleton as soon as your application starts up. Re-invoking your application before it is registered as a singleton will cause another Java VM to start up.

Make sure to unregister before your program exits.Back to top

When will properties set in the jnlp file get set?

Normally, properties in the jnlp file will not be set until the first resource listed in that jnlp file is loaded. This insures the properties are set before any of your code is run, however some properties need to be set before other packages are loaded. Some properties are considered to be “secure” by Java Web Start, and, when found in the main jnlp file, will be passed as arguments to the invoking VM (-Dname=value).

The list of “secure” properties for this version can be found in the Developer's Guide Back to top

What causes the file not found message for the downloaded jnlp file?

You click on a jnlp file, and Internet Explorer downloads the file, then launches Java Web Start, but you get the message: “Could not load file/URL specified: C:\Documents and Settings\...\application[1].jnlp”.

This problem is specific to Internet Explorer. Although this can be caused by a full cache, or turning off the cache in IE, it


is usually caused by a no-cache directive coming from either the web server or the proxy server. IE will honor this directive, and not write the jnlp file to disk, so Java Web Start cannot find it. This frequently happens when upgrading a tomcat based server. Later versions set the no-cache directive by default for any resource that is within a security-constraint in web.xml. Try taking the relevant URI out of the security constraint in web.xml. Back to top

How can I use signed jars (such as JCE extensions) signed for other purposes?

Beginning with Java Web Start 1.5.0, you can multiply sign the jar, adding code signing certificates over another existing certificate chain. With previous versions, you would either have to run the jar as a component extension w/o all-permissions, or strip the existing certificates before adding code signing certificates. (which in many cases rendered the package inoperable.)Back to top

Why can't I use the Association feature on some linux platforms with Gnome?

The association feature specifically requires libgnomevsf-2.so. If this library is not present, associations are not supported.Back to top

How do I set up my server to broadcast the jnlp mime type?

Each web server has a specific way in which to add MIME types. For example, for the Apache web server you must add the following line to the .mime.types configuration file:

application/x-java-jnlp-file JNLP

Check the documentation for the specifics of your web server. Back to top

How do I set up my server to use the JnlpDownloadServlet?

See the Developers Guide section on configuring the servlet. The application need not be packaged in a Web Archive.Back to top

How are Applications uniquely identified?

An application is normally identified by it's href (the url to it's jnlp file.) If there is no href to the jnlp file, it is identified by the href to it's main jar file. If multiple applications share the same main jar file, they must contain an href, or they will be treated as the same app.

In version 1.5.0 and beyond, the Java Application Cache Viewer, will show all applications, even those w/o an href. The Viewer can only launch an application online, if it has an href. Without an href, it can launch offline if the jnlp file allows (contains <offline-allowed>)

In previous versions, the Application Manager will only show those applications with an href.

The same thing applies to creating shortcuts. In 1.5.0 you can only create a shortcut to launch online if there is an href, and can only create an offline shortcut if <offline-allowed> is specified. In 1.4.2, you can only create shortcuts to applications with an href.Back to top

How do I create multiple file-extension/mime-type associations with a JNLP application?

When creating multiple file-extension/mime-type associations with your JNLP application, it's recommended that you use multiple association tags. Also, both the file-extension and mime-type must be specified for each association tag. For example:


<association extensions="aaa" mime-type="x-application/aaa"/> <association extensions="bbb" mime-type="x-application/bbb"/>

Back to top

Why does FindClass() sometimes fail when called from native code?

When jni code that may be called on the EventDispatch Thread calls findClass() then it may fail. For more information, see JNI documentation.

Security Questions

How secure is Java Web Start?

Security is a key consideration of the Java Web Start design. In Java Web Start all applications are launched by default in a secure "sandbox." Back to top

What is a secure sandbox?

Applications in the secure sandbox have restricted access to local computing resources such as the disk and network. Back to top

How is the Java Web Start secure sandbox more flexible than the applet sandbox?

All applications, by default, are run in a sandboxed environment, similar to the applet sandbox. However, Java Web Start provides a secure API that enables an application to import and export files from the local disk under the user's control. The API includes dialog boxes for operations such as saving a file and opening a file that are actually rendered by Java Web Start, and not by the application itself.

This sandbox design is similar to what you can do with HTML. A file input field in an HTML form enables a user to pick a file from the local disk and submit the name (excluding path) and content to the web server. Similarly, most browsers support the 'Save as...' option. Back to top

How can I enable my application to gain unrestricted access to the system?

An application requesting unrestricted system access must be digitally signed. The first time a user launches such an application, a security dialog box will appear. Before running the application, Java Web Start will prompt the user to accept the digital certificate. After the user has accepted the certificate, subsequent invocations will not show the security dialog box. Back to top

Is there support for encrypted download of JAR files?

Support for encrypting data transferred from the server to the client is very important. This is an important point on our issue list, and we will definitely make sure that HTTPS libraries will work with applications that are launched with Java Web Start. The HTTPS support might be in an optional package that you need to specify that your application depends on.

Encrypting the JAR files transferred from the server to the client may not be necessary. The reason is, even if the class files where encrypted on the wire, they will have to be decrypted on the client side and stored to disk, so the JVM will be able to load the classes. Thus, it could be fairly simple for a cracker to get around the encryption of the JAR files.

Instead, what is important for JAR files is that they can be signed, so the user can be absolutely sure that the application is from the vendor he expect it to be from. This is already supported.


Back to top

Can I use NTLM authentication with Java Web Start?

NTLM support was added to Java 1.4.2 on Windows platforms only. You can use NTLM authentication with Java Web Start in 1.4.2 and beyond. The JAuthenticator dialog may contain some misleading text when using NTLM with Java Web Start 1.4.2, but this is fixed in Java Web Start 1.5.0.Back to top

Can I use HTTPS protocol with Java Web Start?

HTTPS support was added to Java in version 1.4. You can use use HTTPS protocol for Java Web Start resources starting in version 1.2, but may encounter one of several problems that were addressed in Java Web Start 1.4.2. It is recommended to use at least Java Web Start 1.4.2 if using HTTPS protocol.Back to top

Are there other online resources to learn more about the security tools?

See the following:

Netscape object signing tools Signing JAR Files Java Deployment Guide security chapter

Back to top

Known Bugs

4825415: Web Start desktop integration and security dialogs disappear in 1.4.2

In version 1.4.2 only.

This is the problem where the desktop integration dialog fights for focus with a modal dialog displayed by the application, or the dialog is lost behind another application window.

This is fixed in versions 1.4.2_06 and 1.5Back to top

4491398: Dependent DLL resource problem

In all versions.

If you have multiple native libraries, you must load each library with System.LoadLibrary, before loading any other that references it. This may become impossible if libraries have circular dependancies.Back to top

5008460: Web Start fails if path contains spaces and TraceSecurity is turned on.

In versions 1.2 and 1.4.2

If TraceSecurity is turned on, you may get an exception on Windows platforms if there is a space in the path to the cache directory. If you have this problem turn off the TraceSecurity debugging switch (<property name=”javaws.debug.0”name=”-TraceSecurity” />.

This is fixed in version 1.5.Back to top


5074087: If related-content is specified w/o a title on Windows, application cannot start.

In version 1.5.0.

In the specification of the jnlp file, it is legal to specify a related-content element without a title sub-element. However if this is done on windows platforms, an exception will be thrown when the shortcut to the related content is installed, and the program cannot be run. To work around this problem, always include a title for related-content elements.Back to top

5074524: First jar of unsigned extension must be downloaded eagerly.

In all versions.

If a component extension is used, the first jar in it will be download eagerly, even if it is marked lazy.Back to top

5047548: Lazy downloading of parts with packages is broken.

In all versions.

If you use the part and package mechanisms to declare what packages are included in what jar files, you should be able to skip downloading of any lazy jars so declared, when accessing a non-existent resource not in any of the declared packages. This does not work, and without Jar Indexing implemented, there is no way to prevent all jars from being downloaded.Back to top

5074526: ExtenededService file APIs show security dialog even if app is signed.

In version 1.5.0.

When using the FileOpen Service, the security dialog will only show if the application does not have file access permissions. This is not true with the new ExtendedService OpenFile, and OpenFiles methods, the security dialog shows anyway.Back to top

4925768: No support for system level shortcuts in Gnome.

In version 1.5.0.

When importing applications into the system cache with -shortcut, or running the Cache Viewer in system mode and creating shortcuts. The shortcuts should be created for all users. This works in Windows, but not on Unix with Gnome.Back to top

5072969: Startup errors causing Web Start to appear to hang.

In all versions.

If an Exception or other Throwable is not caught by Java Web Start. The main run method may terminate without calling System.exit(). This makes application appear to hang (sometimes with DownloadProgress window showing with no progress).

In 1.4.2 this can happen when the Application or Java Web Start throws an Error (such as a NoSuchMethodError). You may need to turn on logging to a file and run with <property name=”javaws.debug.0”value=”+TraceIgnoredExceptions” /> to see the Error.

In 1.5.0 this is only known to happen if static code in the applications main class throws an Error (such as a


NoSuchMethodError). Back to top

5074530: Web Start not picking up the correct JRE.

In all versions.

When Java Web Start finds multiple JRE's that satisfy the requirements of the j2se elements version attribute in the jnlp file, it should always use the latest matching version.

In 1.4.2 it will usually just use the first matching version found.

In 1.5.0 it will usually use the latest version, but under some specific circumstances will still use an earlier one.Back to top
