7 JNLP File Syntax

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 omitted. Note that the JDK 9 version of Java Web Start supports all versions of the spec through version 9.  Previous versions of Java Web Start support only those versions of the specification (spec) that were available at the time of the JDK release. A JNLP file specifying spec="9+" 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: If present, this attribute points to the JNLP file that is used to download and run the application. If not present, then depending on the method used to start the application, Java Web Start might not know where the JNLP file came from, which can affect the security dialog boxes.

os attribute: This attribute contains a list of operating system names for this element. Read the discussion of the resources element later for a full discussion of the os attribute.

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. The following values are valid for kind:

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

Only one description element of each kind can be specified. A description element without a kind attribute 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, JPEG, ICO, or PNG format. The icons are used to represent the application:

• During the 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 the 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 attribute can have one of the following values:

• default: The specified image is used in the Java Application Cache Viewer. It is also used if an icon element with a particular kind attribute has not been specified. Not specifying the kind attribute is the same as specifying it with the default value.
• splash: The specified image is used as the splash image on the second and subsequent launches of the application. During the initial launch of the application, before resources are downloaded, the default splash image is used.
• shortcut: The specified image is used in desktop shortcuts.

A JNLP file can contain multiple icon elements that differ by their kind attribute. This enables you to specify different icon images for your 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 that launch the application offline.

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

The offline-allowed element also controls how Java Web Start checks for an update to an application. If the element is not specified—that is, the application is required to be online to run—Java Web Start checks for an updated version before launching the application. If an update is found, then the new application is 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, then Java Web Start also checks if an update is available. However, if the application is already downloaded, the check times out after a few seconds, in which case the cached application is launched instead. Given a reasonably fast server connection, the latest version of the application is usually 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 its subelements provide hints that the JNLP client may or may not use. The shortcut element can contain the optional online and install attributes, and the two optional subelements, desktop and menu.

association element: The optional association element is a hint to the JNLP client that it wants 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. If the association element is included, then either the offline-allowed element must also be included, or the href attribute must be set for the jnlp element to ensure that the application can be located and run.

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

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

Each sandbox application is 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, then the application has full access to the client machine and local network. All JAR files must be signed. The user is prompted to accept the certificate and agree to run the application.

The update element indicates the preferences for how application updates are 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. The following values are valid:

• always: Check for updates before launching the application.

• timeout (default): means to check for updates until the timeout before launching the application. If the update check is not completed before the timeout, then the application is launched, and the update check continues in the background.

• background: Launch the application while checking for updates in the background.

policy attribute: The policy attribute indicates the preference for how the JNLP client handles an application update when it is known an update is available before the application is launched. The following values are valid:

• always (default): Download updates without any prompt.

• prompt-update: Ask users if they want to download and run the updated version, or launch the cached version.

• prompt-run: Ask users if they want to download and run the updated version, or cancel and stop running the application.

For example:

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

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

The os attribute contains a list of operating system names for a resource. For example, you could use multiple resources definitions with different os attributes to supply a native library for multiple operating systems.

The os attribute contains a list of operating system names separated by spaces. At runtime, the os values are compared with the beginning of the os.name system property to find a match. For example, an os attribute value of "Windows" matches both "Windows 8" and "Windows 10" operating systems.

If you want to list an operating system whose name contains a space, then use a backslash to indicate that the space is part of the operating system name. The following example specifically matches "Windows 8" and "Windows 10":

    <resources os="Windows\ 8 Windows\ 10">
      <jar href="hello.jar"/>
    </resources>

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.

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

      <jar href="myjar.jar"/>

The jar file is loaded into the JVM using a ClassLoader object.  The jar file typically contains 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, for example, *.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"/>
    </resources>

By default, jar and nativelib resources are downloaded eagerly, that is, 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, lazily, or contains a custom progress implementation, for example:

    <jarhref="sound.jar" download="lazy"/>
    <nativelibhref="native-sound.jar" download="eager"/>

    <jarhref="progress.jar" download="progress"/>

A JAR file denoted with download="progress" is downloaded eagerly, and can be used to indicate progress while downloading other resources.

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

       <j2se version="9" initial-heap-size="64m" max-heap-size="128m"/>
      <j2se version="1.8.0_101+" 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 Platform Standard Edition. Currently defined platform versions are 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, and 9. (A platform version does not usually contain a micro version number; for example 1.4.2.)

Exact product versions (implementation versions) can also be specified by including the href attribute, such as 1.7.0_111, or 1.8.0_92, for example:

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

or

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

If a platform version is specified (that is, no href attribute is provided), Java Web Start does not consider an installed non-General Availability (GA milestone) JRE as a match. For example, a request in the following the form does not consider an installed 9-ea JRE as a match for the request:

<j2se version="9+"/>

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

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

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

 -d32,                                                          /* use a 32-bit data model if available (unix platforms only) */
 -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) */
-XX:+PrintGCDetails,          /* Gives some details about the GCs */
-XX:+PrintGCTimeStamps,       /* Prints GCs times happen to the start of the application */
-XX:+PrintHeapAtGC,           /* Prints detailed GC info including heap occupancy */
-XX:+PrintTenuringDistribution,  /* Gives the aging distribution of the allocated objects */
-XX:+TraceClassUnloading,     /* Display classes as they are unloaded */
-XX:+CMSClassUnloadingEnabled,/* It needs to be combined with -XX:+CMSPermGenSweepingEnabled */
-XX:+CMSIncrementalPacing,    /* Automatic adjustment of the incremental mode duty cycle */
-XX:+UseConcMarkSweepGC,      /* Turns on concurrent garbage collection */
-XX:-ParallelRefProcEnabled,
-XX:+DisableExplicitGC,       /* Disable calls to System.gc() */
-XX:+UseG1GC,
-XX:+HeapDumpOnOutOfMemoryError,
-XstartOnFirstThread,
-XX:+UseG1GC,
-XX:+UseStringDeduplication,
-XX:+PrintStringDeduplicationStatistics,
-XX:+UseParallelOldGC,
-XX:-UseParallelOldGC",
-XX:+UseParallelOldGCCompacting",
-XX:-UseParallelOldGCCompacting",
-XX:+UseParallelGC,
-XX:-UseParallelGC,
-XX:+UseGCTimeLimit,
-XX:-UseGCTimeLimit,
-XX:+UseGCOverheadLimit,
-XX:-UseGCOverheadLimit,
-XX:+ScavengeBeforeFullGC,
-XX:-ScavengeBeforeFullGC,
-XX:+UseParallelScavenge,
-XX:-UseParallelScavenge,
-XX:-TransmitErrorReport,

Also supported are any arguments that start with one of the following strings:

-ea,                          /* enable assertions for classes */
-enableassertions,            /* enable assertions for classes */
-da,                          /* disable assertions for classes */
-disableassertions,           /* disable assertions for classes */
-verbose,                     /* enable verbose output */
-Xms,                         /* set initial Java heap size */
-Xmx,                         /* set maximum Java heap size */
-Xss,                         /* set java thread stack size */
-XX:NewRatio,                 /* set Ratio of new/old gen sizes */
-XX:NewSize,                  /* set initial size of new generation */
-XX:MaxNewSize,               /* set max size of new generation */
-XX:PermSize,                 /* set initial size of permanent gen */
-XX:MaxPermSize,              /* set max size of permanent gen */
-XX:MaxHeapFreeRatio,         /* heap free percentage (default 70) */
-XX:MinHeapFreeRatio,         /* heap free percentage (default 40) */
-XX:UseSerialGC,              /* use serial garbage collection */
-XX:ThreadStackSize,          /* thread stack size (in KB) */
-XX:MaxInlineSize,            /* set max num of bytecodes to inline */
-XX:ReservedCodeCacheSize,    /* Reserved code cache size (bytes) */
-XX:MaxDirectMemorySize,
-XX:PrintCMSStatistics,               /* If > 0, Print statistics about the concurrent collections */
-XX:SurvivorRatio,                    /* Sets the ratio of the survivor spaces */
-XX:MaxTenuringThreshold,             /* Determines how much the objects may age */
-XX:CMSMarkStackSize,
-XX:CMSMarkStackSizeMax,
-XX:CMSIncrementalDutyCycleMin,       /* The percentage which is the lower bound on the duty cycle */
-XX:ParallelCMSThreads,
-XX:ParallelGCThreads,                /* Sets the number of parallel GC threads */
-XX:CMSInitiatingOccupancyFraction,   /* Sets the threshold percentage of the used heap */
-XX:+UseCompressedOops,               /* Enables compressed references in 64-bit JVMs */
-XX:GCPauseIntervalMillis,
-XX:MaxGCPauseMillis,                 /* A hint to the virtual machine to pause times */
-XX:+CMSIncrementalMode,              /* Enables the incremental mode */
-XX:StringDeduplicationAgeThreshold,
-XX:GCTimeLimit",
-XX:GCHeapFreeLimit",
-XX:MarkStackSize,
-XX:MarkStackSizeMax,
-XX:ConcGCThreads,

The property element defines a system property that is 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 that are considered secure are set by Java Web Start after the VM is started but before the application is invoked. These properties are passed as -Dkey=value arguments to the java command when invoked. The following properties are considered secure:

• Properties set in a signed JNLP file

• Properties set in an unsigned JNLP file that are prefixed with one of the following strings: jnlp., javaws., or javapi.

• Predefined secure properties:

      sun.java2d.noddraw,
      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,
      sun.awt.keepWorkingSetOnMinimize,
      swing.noxp,
      swing.boldMetal,
      awt.useSystemAAFontSettings,
      sun.java2d.dpiaware,
      sun.awt.disableMixing,
      sun.lang.ClassLoader.allowArraySyntax,
      java.awt.smartInvalidate"
      apple.laf.useScreenMenuBar,
      java.net.preferIPv4Stack,
      java.util.Arrays.useLegacyMergeSort",
      sun.locale.formatasdefault,
      sun.awt.enableExtraMouseButtons,
      com.sun.management.jmxremote.local.only,
      sun.nio.ch.bugLevel,
      sun.nio.ch.disableSystemWideOverlappingFileLockCheck,
      jdk.map.althashing.threshold
  

The application-desc element indicates that the JNLP file is launching an application (as opposed to an applet). The application element has an optional attribute, main-class, for specifying the name of the application's main class, which is the class where execution must begin:

• For Java applications, the main class is the class that contains the public static void main(String argv[]) method.

• For JavaFX applications, the main class is the class that extends javafx.application.Application.

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

The optional type attribute can be used to indicate the type of application, either Java, which is the default, or JavaFX. Java Web Start must know if it is a JavaFX application to know how to invoke it.

Arguments can be specified for 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>

Parameters can be added to applications with the type attribute set to JavaFX just as in applets by including one or more param elements, for example:

<application-desc type="JavaFX" main-class="fxApp">
    <param name="key1" value="value1"/>
    <param name="key2" value="value2"/>
</application-desc>

The (optional) progress-class attribute can be used to indicate that the class of this name implements the javax.jnlp.DownloadServiceListener interface. This class can be loaded first and used to indicate the progress of other resources being downloaded and verified.

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, the same as for applications. The documentBase must be provided explicitly because 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.

The (optional) progress-class attribute can be used to indicate that the class of this name implements the javax.jnlp.DownloadServiceListener interface. This class can be loaded first and used to indicate the progress of other resources being downloaded and verified.

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 among multiple applications or that have separate security needs.

The (optional) progress-class attribute can be used to indicate that the class of this name implements the javax.jnlp.DownloadServiceListener interface. This class can be loaded first and used to indicate the progress of other resources being downloaded and verified.

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.