# JNLP File Syntax

This chapter covers the following topics:

- Introduction
- Example
- JNLP Elements
  - `jnlp` Element
  - `information` Element
  - `related_content` Element
  - `security` Element
  - `resources` Element
  - `application-desc` Element
  - `applet-desc` Element

## Introduction

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

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 File for SwingSet2 Demo Application -->
    <jnlp
      spec="1.5+"
      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">
        <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.4.2+" 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 and version 1.5, whereas previous versions support only 1.0. A jnlp file specifying `spec="1.5+"` 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. This element is required.

> `vendor` element: The name of the vendor of the application. This element is required.

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

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

> The `icon` element requires an `href` attribute, specifiying the directory and name of the icon file.

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

### `resources` Element

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

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

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

> `<jar href="myjar.jar"/>`

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

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

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

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

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

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

> By default, `jar` and `nativelib` resources will be downloaded eagerly, i.e., they are downloaded and available locally to the JVM running the application before the application is launched. The `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:

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

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

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

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

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

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

> > or

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

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

> > `<j2se version="1.4+"/>`

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

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

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

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

> >     -client
> >     -server
> >     -verbose
> >     -showversion
> >     -esa
> >     -enablesystemassertions
> >     -dsa
> >     -disablesystemassertions
> >     -Xmixed
> >     -Xint
> >     -Xnoclassgc
> >     -Xincgc
> >     -Xbatch
> >     -Xprof
> >     -Xdebug
> >     -Xrs
> >     -XX:+ForceTimeHighResolution
> >     -XX:-ForceTimeHighResolution

> Plus any argument starting with one of the following:

> >     -ea:
> >     -enableassertions:
> >     -da:
> >     -disableassertions:
> >     -verbose:
> >     -Xms
> >     -Xmx
> >     -Xss
> >     -XX:NewRatio
> >     -XX:NewSize
> >     -XX:MaxNewSize
> >     -XX:PermSize
> >     -XX:MaxPermSize
> >     -XX:MaxHeapFreeRatio
> >     -XX:MinHeapFreeRatio
> >     -XX:UseSerialGC
> >     -XX:ThreadStackSize
> >     -XX:MaxInlineSize
> >     -XX:ReservedCodeCacheSize

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

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

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

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

> >      sun.java2d.noddraw
> >      javaws.cfg.jauthenticator
> >      swing.useSystemFontSettings
> >      swing.metalTheme
> >      http.agent
> >      http.keepAlive

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

For a variety of useful examples, see JNLP API Examples.