Download the JDK
Search the Tutorials
Hide the TOC
Trail: Deployment
Lesson: Java Web Start
Java Web Start
Running Java Web Start Applications
Deploying Java Web Start Applications
Developing Java Web Start Applications
The JNLP API
Java Web Start and Security
Common Java Web Start Problems
Questions and Exercises
Home Page > Deployment > Java Web Start
« Previous • Trail • Next »
Deploying Java Web Start Applications

> This section describes the basics of deploying an application using Java Web Start. Deploying an application involves the following steps:
> 1. Setting up the Web Server
> 2. Creating the JNLP File
> 3. Placing the Application on the Web Server
> 4. Creating the Web Page
> This section uses the Notepad example application to demonstrate Java Web Start technology. You can find all the source files for the Notepad application example in the `\demo\plugin\jfc\Notepad` directory within the JDK installation directory.

### Setting up the Web Server

> Before you can deploy an application with Java Web Start over the Web, you must ensure that the Web server you are using can handle JNLP files.

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

> How you set the JNLP MIME type depends on the Web server you are using. For example, for the Apache Web server, you simply add the line

> >     application/x-java-jnlp-file JNLP

> to the `mime.types` file.

> For other Web servers, check the documentation for instructions on setting MIME types.

### Creating the JNLP File

> The key to running an application with Java Web Start is the Java Network Launching Protocol, or JNLP, file. The JNLP file is an XML file that contains elements and attributes that tell Java Web Start how to run the application.

> #### An Example JNLP File

> Following is the JNLP file for the Notepad demo:

> >     <?xml version="1.0" encoding="utf-8"?>
> >     <!-- JNLP File for Notepad -->

> >     <jnlp spec="1.0+"
> >           codebase="http://java.sun.com/docs/books/tutorialJWS/deployment/webstart/ex5/"
> >           href="Notepad.jnlp">
> >        <information>
> >           <title>Notepad Demo</title>
> >           <vendor>The Java(tm) Tutorial: Sun Microsystems, Inc.</vendor>
> >           <description>Notepad Demo</description>
> >           <homepage href="http://java.sun.com/docs/books/tutorial/deployment/webstart/running.html"/>
> >           <description kind="short">ClickMeApp uses 3 custom classes plus several
> >            standard ones</description>
> >           <offline-allowed/>
> >        </information>
> >        <resources>
> >        	<jar href="Notepad.jar"/>
> >     	<j2se version="1.3+"
> >     	      href="http://java.sun.com/products/autodl/j2se"/>
> >        </resources>
> >        <application-desc main-class="Notepad"/>
> >     </jnlp>

> If you click this link to the `Notepad.jnlp` file, you open and run the Notepad application.

> #### JNLP File Contents

> The following table describes the elements and attributes in the sample JNLP file.

> > Note: This table does not include all possible contents of the JNLP file. For more information, see the Java Network Launching Protocol & API Specification (JSR-56).

> Elements and Attributes of a JNLP file
> Element | Attributes | Description | Since | Required
> --- | --- | --- | --- | ---
> jnlp |  | This is the main xml element for a jnlp file. Everything is contained within the jnlp element. | 1.0 | yes
> | spec | The spec attribute can be 1.0, 1.5.0, or 1.6.0 or can use the wildcards such as 1.0+. It denoted the minimum version of the JNLP Specification that this jnlp file can work with. | 1.0 |
> | codebase | The codebase attribute specifies the base location for all relative URLs specified in href attributes in the JNLP file. | 1.0 |
> | href | The href specifies the URL of the JNLP file itself. | 1.0 |
> | version | The version of the application being launched, as well as the version of the JNLP file itself. | 1.0 |
> information |  | The information element contains other elements that describe the application and it's source. | 1.0 | yes
> | os | Specifies the operating system for which this information element should be considered. | 1.5.0 |
> | arch | Specifies the architecture for which this information element should be considered | 1.5.0 |
> | platform | Specifies the platform for which this information element should be considered. | 1.5.0 |
> | locale | Specifies the locale for which this information element should be considered. | 1.5.0 |
> title |  | The title element specifies the title of the application. | 1.0 | yes
> vendor |  | The vendor element specifies the provider of the application. | 1.0 | yes
> homepage |  | The homepage of the application. | 1.0 |
> | href | A URL pointing to where more information on this application can be found. | 1.0 | yes
> description |  | A short statement describing the application. | 1.0 |
> | kind | An indicator as to what type of description this is, legal values are one-line, short, and tooltip. | 1.0 |
> icon |  | Describes an icon that can be used to identify the application to the user. | 1.0 |
> | href | A URL pointing to the icon file, may be in one of the following formats: gif, jpg, png, ico. | 1.0 | yes
> | kind | Indicates the suggested use of the icon, can be: default, selected, disabled, rollover, splash, or shortcut. | 1.0 |
> | width | Can be used to indicate the resolution of the image. | 1.0 |
> | height | Can be used to indicate the resolution of the image. | 1.0 |
> | depth | Can be used to indicate the resolution of the image. | 1.0 |
> offline-allowed |  | Indicates that this application can operate when the client system is disconnected from the network. | 1.0 |
> shortcut |  | The shortcut element can be used to indicate an application's preferences for desktop integration. | 1.5.0 |
> | online | Can be used to describe the application's preference for creating a shortcut to run online or offline. | 1.5.0 |
> desktop |  | Can be used to indicate an application's preference for putting a shortcut on the users desktop. | 1.5.0 |
> menu |  | Can be used to indicate an application's preference for putting a menu item in the users start menus. | 1.5.0 |
> | sub-menu | Can be used to indicate an application's preference for where to place the menu item. | 1.5.0 |
> association |  | Can be used to hint to the JNLP client that it wishes to be registered with the operating system as the primary handler of certain extensions and a certain mime-type. | 1.5.0 |
> | extensions | Contains a list of file extensions (separated by spaces) that the application requests it be registered to handle. | 1.5.0 |
> | mime-type | Contains the mime-type that the application requests it be registered to handle. | 1.5.0 |
> related-content |  | Describes an additional piece of related content that may be integrated with the application. | 1.5.0 |
> | href | A URL pointing to the related content. | 1.5.0 | yes
> update |  | The update element is used to indicate the preferences for how application updates should be handled by the JNLP Client. | 1.6.0 |
> | check | Indicates the preference for when the JNLP Client should check for updates. It can be always, timeout, or background.. | 1.6.0 |
> | policy | 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. It can be always, prompt-update, or prompt-run. | 1.6.0 |
> |  |  | 1.0 |
> security |  | This element can be used to request enhanced permissions. | 1.0 |
> all-permissions |  | Requests that the application be run with all permissions. | 1.0 |
> j2ee-application-client-permissions |  | Requests that the application be run with a permission set that meets the security specifications of the J2EE Application Client environment. | 1.0 |
> |  |  | 1.0 |
> resources |  | Describes all the resources that are needed for an application. | 1.0 | yes
> | os | Specifies the operating system for which the resources element should be considered. | 1.0 |
> | arch | Specifies the architecture for which the resources element should be considered. | 1.0 |
> | locale | Specifies that the locales for which the resources element should be considered. |  |
> java (or java se) |  | Specifies what version(s) of Java to run the application with. | 1.6.0 (java) |
> | version | Describes an ordered list of version ranges to use. | 1.0 | yes
> | href | The URL denoting the supplier of this version of java, and where it may be downloaded from. | 1.0 |
> | java-vm-args | Indicates an additional set of standard and non-standard virtual machine arguments that the application would prefer the JNLP Client to use when launching Java. | 1.0 |
> | initial-heap-size | Indicates the initial size of the Java heap. | 1.0 |
> | max-heap-size | Indicates the maximum size of the Java heap. | 1.0 |
> jar |  | Specifies a JAR file that is part of the application's classpath. | 1.0 | yes
> | href | The URL of the jar file. | 1.0 | yes
> | version | The requested version of the jar file. Requires using the version-based download protocol | 1.0 |
> | main | Indicates if this jar contains the class containing the main method of the application. | 1.0 |
> | download | Can be used to indicate this jar may be downloaded lazily, or when needed. | 1.0 |
> | size | Indicates the downloadable size of the jar file in bytes. | 1.0 |
> | part | Can be used to group resources together so they will be downloaded at the same time. | 1.0 |
> nativelib |  | Specifies a JAR file that contains native libraries in it's root directory. | 1.0 |
> | href | The URL of the jar file. | 1.0 | yes
> | version | The requested version of the jar file. Requires using the version-based download protocol | 1.0 |
> | download | Can be used to indicate this jar may be downloaded lazily. | 1.0 |
> | size | Indicates the downloadable size of the jar file in bytes. | 1.0 |
> | part | Can be used to group resources together so they will be downloaded at the same time. | 1.0 |
> extension |  | Contains pointer to an additional component-desc or installer-desc to be used with this application. | 1.0 |
> | href | The URL to the additional extension jnlp file. | 1.0 | yes
> | version | The version of the additional extension jnlp file. | 1.0 |
> | name | The name of the additional extension jnlp file | 1.0 |
> ext-download |  | Can be used in an extension element to denote the parts contained in a component-extension. | 1.0 |
> | ext-part | Describes the name of a part that can be expected to be found in the extension. | 1.0 | yes
> | download | Can be used to indicate this extension may be downloaded eagerly or lazily. | 1.0 |
> | part | Denotes the name of a part in this jnlp file to include the extension in. | 1.0 |
> package |  | Can be used to indicate to the JNLP Client which packages are implemented in which JAR files. | 1.0 |
> | name | Package name contained in the jar files of the given part. | 1.0 | yes
> | part | Part name containing the jar files that include the given package name. | 1.0 | yes
> | recursive | Can be used to indicated that all package names beginning with the given name, can be found in the given part. | 1.0 |
> property |  | Defines a system property that will be available through the System.getProperty and System.getProperties methods. | 1.0 |
> | name | Name of the system property. | 1.0 | yes
> | value | Value it will be set to. | 1.0 | yes
> |  |  | 1.0 |
> |  | Note: A jnlp file must contain one of application-desc, applet-desc, component-desc, or installer-desc | 1.0 | yes
> applicaation-desc |  | Denotes this is the jnlp file for an application. | 1.0 |
> | main-class | The name of the class containing the public static void main(String[]) method of the application. | 1.0 | yes
> argument |  | Each argument contains (in order) an additional argument to be passed to main. | 1.0 |
> applet-desc |  | Denotes this is the jnlp file for an applet. | 1.0 |
> | main-class | This is the name of the main Applet class. | 1.0 | yes
> | documentbase | The document base for the Applet as a URL. | 1.0 |
> | name | Name of the Applet. | 1.0 | yes
> | width | The width of the applet in pixels. | 1.0 | yes
> | height | The height of the applet in pixels | 1.0 | yes
> param |  | A set of parameters that can be passed into the applet. | 1.0 |
> | name | The name of this parameter | 1.0 | yes
> | value | The value of this parameter | 1.0 | yes
> component-desc |  | Denotes this is the jnlp file for a component extension. | 1.0 |
> installer-desc |  | Denotes this is the jnlp file for an installed extension. | 1.0 |
> | main-class | The name of the class containing the public static void main(String[]) method of the installer. | 1.0 | yes

> #### Encoding JNLP Files

> Java Web Start supports encoding of JNLP files in any character encoding supported by the Java platform. For more information on character encoding in Java, see the Supported Encodings Guide. To encode a JNLP file, specify an encoding in the XML prolog of that file. For example, the following line indicates that the JNLP file is encoded in UTF-16.

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

> > Note: The XML prolog itself must be UTF-8-encoded.

### Placing the Application on the Web Server

> The next step in deploying your application with Java Web Start is as simple as placing all the application's JAR files and the JNLP file on the Web server. You must ensure the JAR files are in the locations specified by the `href` attribute of the `jar` element in the JNLP file.

### Creating the Web Page

> Once you've completed to preceding steps, you are ready to write a Web page that gives users access to your application. Adding a link to your application in a Web page for users with Java Web Start already installed is simple; however, you must also design your Web page for users that might not have Java Web Start installed.

> #### Adding the Basic Link to the JNLP File

> In order to enable your users to launch the application from a Web page, you must include a link to the application's JNLP file from that Web page. To add this link, you use the standard HTML link syntax, with the `href` attribute specifying the location of the JNLP file:

> >     <a href="Notepad.jnlp">Launch Notepad Application</a>

> Assuming Java Web Start is installed on the client computer, when the user clicks this link, Java Web Start executes the application based on the instructions in the JNLP file.

> #### Adding the Link when Java Web Start is not Installed

> For users who might not have Java Web Start installed, you must write scripts in your Web page to:
> 1. Detect which browser the user has.
> 2. Detect whether Java Web Start is installed.
> 3. If Java Web Start is not installed, either auto-install it, or direct the user to a download page.
> For more information and sample scripts to use for these steps, see the Java Web Start Guide.

« Previous • Trail • Next »
Previous page: Running Java Web Start Applications
Next page: Developing Java Web Start Applications