0% found this document useful (0 votes)

2K views

Java Web Start Guide

Uploaded by

api-3804031

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

2K views

Java Web Start Guide

Uploaded by

api-3804031

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 116

Java Web Start Guide

Note: There are two ways to navigate this guide: Related Documents

 Search the guide
 Select from the contents below:

Overview
Java Web Start Technology
Where to Find Java Web Start Technology
Using Java Web Start Software
Requirements

Setting up the Web Site

Introduction
Basic Steps

Creating the Web Page That Launches the Application

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

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

JnlpDownloadServlet Guide
Introduction
Examples
Servlet Configuration
Specifying Resources
Mapping Requests to Resources
Processing of JNLP Files

JNLP File Syntax

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/contents.html
Introduction
The jnlp Element
The information Element
The security Element
The resources Element
The application-desc Element
The applet-desc Element

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 an ExtendedService Service

The javaws Command Line Interface

Appendices:
FAQ
JNLP API (JavaDoc)

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

Select a Chapter/Topic

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 Warning

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

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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/overview.html
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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/overview.html
Setting Up the Web Site

Select a Chapter/Topic

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 next
If 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:

Browser javawsInstalled javaws142Installed javaws150Installed javaws160Installed

1 if any version of
Internet 1 if Java Web Start 1.4.2 is 1 if Java Web Start 1.5.0 is 1 if Java Web Start 1.6.0 is
Java Web Start is
Explorer installed; 0 otherwise. installed; 0 otherwise. installed; 0 otherwise.
installed; 0 otherwise.
1 if any version of
Netscape 1 if any version of Java Web 1 if any version of Java Web 1 if any version of Java Web
Java Web Start is
Navigator Start is installed; 0 otherwise. Start is installed; 0 otherwise. Start is installed; 0 otherwise.
installed; 0 otherwise.

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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/launch.html
 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:

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.

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 PluginBrowserCheck
program 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 PluginBrowserCheck
determines 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

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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/launch.html
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.

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

Select a Chapter/Topic

This chapter includes the following topics:

 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.gif
images/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 :

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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/development.html
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: jks
Keystore 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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/development.html
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.

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

Select a Chapter/Topic

Table of Contents
Introduction
Examples
Servlet Configuration
Specifying Resources
Mapping Requests to Resources
Processing of JNLP Files
Pack200 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.jar
file, 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/lib
directory. 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
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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.

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/lib
directory. 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,
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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>

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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 . ext

options ::= 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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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 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
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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:

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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-id
parameter 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
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/downloadservletguide.html
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.

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

Select a Chapter/Topic

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
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
spec 1.0
minimum version of the JNLP Specification that this jnlp file can work woth.
The codebase attribute specifies the base location for all relative URLs specified in href attributes
codebase 1.0
in the JNLP file.
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
1.5.0
os Specifies the operating system for which this information element should be considered.

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
Indicates the suggested use of the icon, can be: default, selected, disabled, rollover, splash, or
kind 1.0
shortcut.
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
Can be used to hint to the JNLP client that it wishes to be registered with the operating system as
association 1.5.0
the primary handler of certain extensions and a certain mime-type.
Contains a list of file extensions (separated by spaces) that the application requests it be registered
extensions 1.5.0
to handle.

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

The update element is used to indicate the preferences for how application updates should be
update 6.0
handled by the JNLP Client.
Indicates the preference for when the JNLP Client should check for updates. It can be always,
check 6.0
timeout, or background..
Indicates the preference for how the JNLP Client should handle an application update when it is
policy known an update is available before the application is launched. It can be always, prompt-update, 6.0
or prompt-run.
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- Requests that the application be run with a permission set that meets the security specifications of
1.0
client-permissions the J2EE Application Client environment.
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
Indicates an additional set of standard and non-standard virtual machine arguments that the
java-vm-args 1.0
application would prefer the JNLP Client to use when launching Java.
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
Can be used to indicated that all package names beginning with the given name, can be found in
recursive 1.0
the given part.
Defines a system property that will be available through the System.getProperty and
property 1.0
System.getProperties methods.
name Name of the system property. 1.0 yes
value Value it will be set to. 1.0 yes
1.0

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html
Note: A jnlp file must contain one of application-desc, applet-desc, component-desc, or installer-
1.0 yes
desc
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

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:

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html
 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:

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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html
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:

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:

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:

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 jar
and 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:

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:

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"/

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

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.

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 */

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html
-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:

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.

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

Select a Chapter/Topic

This chapter includes the following topics:

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

import javax.jnlp.*;
...

DownloadService ds;

    try {
        ds = (DownloadService)ServiceManager.lookup("javax.jnlp.DownloadService");
    } catch (UnavailableServiceException e) {
        ds = null;
    }
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html
    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.

import javax.jnlp.*;
...

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.

import javax.jnlp.*;
...

FileSaveService fss;

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

    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.

import javax.jnlp.*;
...

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

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

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

import javax.jnlp.*;
...

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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html
            // 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();

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

   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:

import javax.jnlp.*;
...

FileOpenService fos;

//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);
            }

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

Using a JNLPRandomAccessFile
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html
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 JNLPRandomAccessFile
can be used to write to a random access file:

import javax.jnlp.*;
...

FileOpenService fos;

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

import javax.jnlp.*;
...

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

...

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

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

import javax.jnlp.*;
...

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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html
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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/examples.html
Package Class Tree Index
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

Package javax.jnlp

Interface Summary
The BasicService interface provides access to the codebase of the application, if an application
BasicService
is run in offline mode, and simple interaction with the native browser on the given platform.
ClipboardService provides methods for accessing the shared system-wide clipboard, even for
ClipboardService
applications that are running in the untrusted execution environment.
DownloadService service allows an application to control how its own resources are cached, to
DownloadService determine which of its resources are currently cached, to force resources to be cached, and to
remove resources from the cache.
The DownloadServiceListener provides an interface for a callback object implementation,
DownloadServiceListener
which may be used by a DownloadService implementation.
ExtendedService provides additional support to the current JNLP API, which allow
ExtendedService
applications to open a specific file in the client's file system.
The ExtensionInstallerService is used by an extension installer to communicate with the
ExtensionInstallerService
JNLP Client.
FileContents FileContents objects encapsulate the name and contents of a file.
FileOpenService service allows the user to choose a file from the local file system, even for
FileOpenService
applications that are running in the untrusted execution environment.
FileSaveService service allows the user to save a file to the local file system, even for
FileSaveService
applications that are running in the untrusted execution environment.
JNLPRandomAccessFile Instances of this class support both reading and writing to a random access file.
PersistenceService provides methods for storing data locally on the client system, even for
PersistenceService
applications that are running in the untrusted execution environment.
PrintService provides methods for access to printing functions, even for applications that are
PrintService
running in the untrusted execution environment.
A ServiceManagerStub object implements the particular lookup of JNLP services by the JNLP
ServiceManagerStub
Client.
SingleInstanceListener is a interface which should be implemented by a JNLP application if
SingleInstanceListener
they wish to support single instance behaviour.
SingleInstanceService allow applications launched under Java Web Start to register
SingleInstanceService themselves as singletons, and to be passed in new parameter sets when user attempts to launch
new instances of them.

Class Summary
ServiceManager 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
The UnavailableServiceException is thrown by the ServiceManager when a non-
UnavailableServiceException
existing or unavailable service is looked up.

Package Class Tree Index

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

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

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
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()

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 to
ascertain 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

Package Class Tree Index

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

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

Package Class Tree Index

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 load
method, 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
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
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
http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html
application.

Parameters:
part - The name of the part.
Returns:
true if the above conditions are met, and false otherwise.

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.
Returns:
true if the above conditions are met, and false otherwise.

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.
Returns:
true if the above conditions are met, and false otherwise.

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.
Returns:
true if the above conditions are met, and false otherwise.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html
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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

loadExtensionPart

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html
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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.

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

removePart

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html
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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.

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

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadService.html
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.

Package Class Tree Index

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

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

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

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

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). A
DownloadServiceListener 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 is
unknown.

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 bar
and / 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 is
unknown.

downloadFailed

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadServiceListener.html
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.

Package Class Tree Index

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/DownloadServiceListener.html
Package Class Tree Index
PREV CLASS NEXT CLASS FRAMES NO FRAMES All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

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

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

Package Class Tree Index

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

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtensionInstallerService.html
setHeading
void setHeading(java.lang.String heading)

Updates the status of the installer process.

setStatus
void setStatus(java.lang.String status)

Updates the status of the installer process.

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtensionInstallerService.html
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 JRE
version - product version of the JRE
Returns:
The path to the executable for the given JRE, or null if the JRE is not installed.

Package Class Tree Index

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/ExtensionInstallerService.html
Package Class Tree Index
PREV CLASS NEXT CLASS FRAMES NO FRAMES All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

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
getName
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.
Throws:
java.io.IOException - if an I/O exception occurs.

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.
Throws:
java.io.IOException - if an I/O exception occurs.

getLength
long getLength()
throws java.io.IOException

Gets the length of the file.

Returns:
the length of the file as a long.
Throws:
java.io.IOException - if an I/O exception occurs.

canRead

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileContents.html
boolean canRead()
throws java.io.IOException

Returns whether the file can be read.

Returns:
true if the file can be read, false otherwise.
Throws:
java.io.IOException - if an I/O exception occurs.

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.
Throws:
java.io.IOException - if an I/O exception occurs.

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.
Throws:
java.io.IOException - if an I/O exception occurs.

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.
Throws:
java.io.IOException - if an I/O exception occurs.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/FileContents.html
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.
Throws:
java.io.IOException - if an I/O exception occurs.

Package Class Tree Index

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 specific
implementation 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

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
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:
- A hint from the application to the initial directory for the file chooser. This might be ignored by the
pathHint
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.

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[])

Throws:
java.io.IOException

Package Class Tree Index

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 specific
implementation 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

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

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 file
java.io.IOException

Package Class Tree Index

javax.jnlp
Interface JNLPRandomAccessFile
All Superinterfaces:
java.io.DataInput, java.io.DataOutput

public interface JNLPRandomAccessFile
extends 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 is
created 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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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, and
then 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 then
writes 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
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.
Throws:
java.io.IOException - if an I/O error occurs.

getFilePointer
long getFilePointer()
throws java.io.IOException

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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.
Throws:
java.io.IOException - if an I/O error 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.
Throws:
java.io.IOException - if an I/O error occurs.

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

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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.
Throws:
java.io.IOException - if an I/O error occurs.

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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 an
EOFException. 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.
Throws:
java.io.IOException - if an I/O error occurs.

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:

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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

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

Specified by:
readUnsignedShort in interface java.io.DataInput
Returns:
the next two bytes of this file, interpreted as an unsigned 16-bit integer.
Throws:
EOFException - if this file reaches the end before reading two bytes.
java.io.IOException - if an I/O error occurs.

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)

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

Specified by:
readChar in interface java.io.DataInput
Returns:
the next two bytes of this file as a Unicode character.
Throws:
EOFException - if this file reaches the end before reading two bytes.
java.io.IOException - if an I/O error occurs.

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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 readInt
method 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()

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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 readLong

method 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.
Throws:
java.io.IOException - if an I/O error occurs.

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
http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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 newLength
then 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)

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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.
Throws:
java.io.IOException - if an I/O error occurs.

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.

Specified by:
write in interface java.io.DataOutput
Parameters:
b - the data.
Throws:
java.io.IOException - if an I/O error occurs.

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.

Specified by:
write in interface java.io.DataOutput
Parameters:
b - the data.
off - the start offset in the data.
len - the number of bytes to write.
Throws:
java.io.IOException - if an I/O error occurs.

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
Specified by:
writeBoolean in interface java.io.DataOutput
Parameters:
v - a boolean value to be written.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
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.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
Specified by:
writeDouble in interface java.io.DataOutput
Parameters:
v - a double value to be written.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.

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.
Throws:
java.io.IOException - if an I/O error occurs.
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:

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
writeUTF in interface java.io.DataOutput
Parameters:
str - a string to be written.
Throws:
java.io.IOException - if an I/O error occurs.

Package Class Tree Index

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/JNLPRandomAccessFile.html
Package Class Tree Index
PREV CLASS NEXT CLASS FRAMES NO FRAMES All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

An application is only allowed to access data stored with a URL that is based on its codebase. For example, given the codebase
http://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 Summary
static int
CACHED

static int
DIRTY

static int
TEMPORARY

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/PersistenceService.html
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
CACHED
static final int CACHED

Package Class Tree Index

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

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

Package Class Tree Index

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

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
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()

Package Class Tree Index

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

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

Package Class Tree Index

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceListener.html
Package Class Tree Index
PREV CLASS NEXT CLASS FRAMES NO FRAMES All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

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

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.

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceService.html
Parameters:
sil - the SingleInstanceListener object to be removed

Package Class Tree Index

http://java.sun.com/javase/6/docs/jre/api/javaws/jnlp/javax/jnlp/SingleInstanceService.html
Package Class Tree Index
PREV CLASS NEXT CLASS FRAMES NO FRAMES All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.jnlp
Class ServiceManager
java.lang.Object
javax.jnlp.ServiceManager

public final class ServiceManager
extends 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

Method Summary
static 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
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.

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 is
ignored 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

Package Class Tree Index

javax.jnlp
Class UnavailableServiceException
java.lang.Object
   java.lang.Throwable
       java.lang.Exception
           javax.jnlp.UnavailableServiceException

All Implemented Interfaces:

java.io.Serializable

public class UnavailableServiceException
extends java.lang.Exception

The UnavailableServiceException is thrown by the ServiceManager when a non-existing or unavailable service is looked

up.

Since:
1.0
See Also:
ServiceManager, Serialized Form

Constructor Summary
UnavailableServiceException()
          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
UnavailableServiceException
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.

Package Class Tree Index

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

http://java.sun.com/javase/6/docs/technotes/tools/share/javaws.html
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.

http://java.sun.com/javase/6/docs/technotes/tools/share/javaws.html
Java Web Start version 6
TM

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.2
2. 4491398: Dependent DLL resource problem
3. 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 eagerly
6. 5047548: Lazy downloading of parts with packages is broken
7. 5074526: ExtenededService file APIs show security dialog even if app is signed
8. 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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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)

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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:

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?

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

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:

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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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 Guide
Back 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:

Use the following:

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>

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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:

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
<association extensions="aaa" mime-type="x-application/aaa"/>
<association extensions="bbb" mime-type="x-application/bbb"/>

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.

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

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.5
Back 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
http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/faq.html
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

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