This is the main xml element for a jnlp file. Everything is
contained within the jnlp element.
1.0
yes
spec
The spec attribute can be 1.0, 1.5.0, or 6.0 or can use the
wildcards such as 1.0+. It denoted the minimum version of the JNLP
Specification that this jnlp file can work woth.
1.0
codebase
The codebase attribute specifies the base location for all
relative URLs specified in href attributes in the JNLP file.
1.0
href
The href specifies the URL of the JNLP file itself.
1.0
version
The version of the application being launched, as well as the
version of the JNLP file itself.
1.0
information
The information element contains other elements that describe
the application and it's source.
1.0
yes
os
Specifies the operating system for which this information
element should be considered.
1.5.0
arch
Specifies the architecture for which this information element
should be considered
1.5.0
platform
Specifies the platform for which this information element should
be considered.
1.5.0
locale
Specifies the locale for which this information element should
be considered.
1.5.0
title
The title element specifies the title of the application.
1.0
yes
vendor
The vendor element specifies the provider of the
application.
1.0
yes
homepage
The homepage of the application.
1.0
href
A URL pointing to where more information on this application can
be found.
1.0
yes
description
A short statement describing the application.
1.0
kind
An indicator as to what type of description this is, legal
values are one-line, short, and tooltip.
1.0
icon
Describes an icon that can be used to identify the application
to the user.
1.0
href
A URL pointing to the icon file, may be in one of the following
formats: gif, jpg, png, ico.
1.0
yes
kind
Indicates the suggested use of the icon, can be: default,
selected, disabled, rollover, splash, or shortcut.
1.0
width
Can be used to indicate the resolution of the image.
1.0
height
Can be used to indicate the resolution of the image.
1.0
depth
Can be used to indicate the resolution of the image.
1.0
offline-allowed
Indicates that this application can operate when the client
system is disconnected from the network.
1.0
shortcut
The shortcut element can be used to indicate an application's
preferences for desktop integration.
1.5.0
online
Can be used to describe the application's preference for
creating a shortcut to run online or offline.
1.5.0
desktop
Can be used to indicate an application's preference for putting
a shortcut on the users desktop.
1.5.0
menu
Can be used to indicate an application's preference for putting
a menu item in the users start menus.
1.5.0
sub-menu
Can be used to indicate an application's preference for where to
place the menu item.
1.5.0
association
Can be used to hint to the JNLP client that it wishes to be
registered with the operating system as the primary handler of
certain extensions and a certain mime-type.
1.5.0
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.
6.0
check
Indicates the preference for when the JNLP Client should check
for updates. It can be always, timeout, or background..
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.
6.0
1.0
security
This element can be used to request enhanced permissions.
1.0
all-permissions
Requests that the application be run with all permissions.
1.0
j2ee-application-client-permissions
Requests that the application be run with a permission set that
meets the security specifications of the J2EE Application Client
environment.
1.0
1.0
resources
Describes all the resources that are needed for an
application.
1.0
yes
os
Specifies the operating system for which the resources element
should be considered.
1.0
arch
Specifies the architecture for which the resources element
should be considered.
1.0
locale
Specifies that the locales for which the resources element
should be considered.
java (or j2se)
Specifies what version(s) of Java to run the application
with.
6.0 (java)
version
Describes an ordered list of version ranges to use.
1.0
yes
href
The URL denoting the supplier of this version of java, and where
it may be downloaded from.
1.0
java-vm-args
Indicates an additional set of standard and non-standard virtual
machine arguments that the application would prefer the JNLP Client
to use when launching Java.
1.0
initial-heap-size
Indicates the initial size of the Java heap.
1.0
max-heap-size
Indicates the maximum size of the Java heap.
1.0
jar
Specifies a JAR file that is part of the application's
classpath.
1.0
yes
href
The URL of the jar file.
1.0
yes
version
The requested version of the jar file. Requires using the
version-based download protocol
1.0
main
Indicates if this jar contains the class containing the main
method of the application.
1.0
download
Can be used to indicate this jar may be downloaded eagerly,
lazily, or for progress indication.
1.0 (6.0.18)
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
application-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
progress-class
The name of the class containing the implementation of
DownloadServiceListener, that may be used to indicate download
progress.
6.0.18
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
progress-class
The name of the class containing the implementation of
DownloadServiceListener, that may be used to indicate download
progress.
6.0.18
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
progress-class
The name of the class containing the implementation of
DownloadServiceListener, that may be used to indicate download
progress.
6.0.18
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
<?xmlversion="1.0" encoding="utf-8"?> <!-- JNLP File for SwingSet2 Demo Application --> <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> <homepagehref="docs/help.html"/> <description>SwingSet2 Demo Application</description> <descriptionkind="short">A demo of the capabilities
of the Swing Graphical User Interface.</description> <iconhref="images/swingset2.jpg"/> <iconkind="splash" href="images/splash.gif"/> <offline-allowed/> <associationmime-type="application-x/swingset2-file" extensions="swingset2"/> <shortcutonline="false"> <desktop/> <menusubmenu="My Corporation Apps"/> </shortcut> </information> <informationos="linux"> <title> SwingSet2 Demo on Linux </title> <homepage href="docs/linuxhelp.html"> </information> <security> <all-permissions/> </security> <resources> <j2seversion="1.6+" java-vm-args="-esa -Xnoclassgc"/> <jar href="lib/SwingSet2.jar"/> </resources> <application-descmain-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:
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.
shortcutelement:
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.
associationelement: 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-contentelement: 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-permissionselement 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 running
the application.
For example:
<update check="always"
policy="prompt-update">
resources
Element
The resourceselement
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.
A jarelement
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 nativelibelement
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:
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 downloadattribute is used to control whether a resource is
downloaded eagerly, lazily, or contains a custom progress
implementation. For example:
A jar denoted with download="progress" will be downloaded
eagerly, and may be used to indicate progress while downloading
other resources.
The j2seelement
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 versionattribute 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,
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-argsattribute of the j2se element specifies a
preferred set of virtual machine arguments to use when launching
java.
<j2se version="1.4+"
java-vm-args="-ea -Xincgc"/>
The following java-vm-args are supported by this version:
-d32, /* use a 32-bit data model if available (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) */
Plus any argument starting with one of the following:
-ea, /* enable assertions for classes */
-enableassertions, /* enable assertions for classes */
-da, /* disable assertions for classes */
-disableassertions, /* disable assertions for classes */
-verbose, /* enable verbose output */
-Xms, /* set initial Java heap size */
-Xmx, /* set maximum Java heap size */
-Xss, /* set java thread stack size */
-XX:NewRatio, /* set Ratio of new/old gen sizes */
-XX:NewSize, /* set initial size of new generation */
-XX:MaxNewSize, /* set max size of new generation */
-XX:PermSize, /* set initial size of permanent gen */
-XX:MaxPermSize, /* set max size of permanent gen */
-XX:MaxHeapFreeRatio, /* heap free percentage (default 70) */
-XX:MinHeapFreeRatio, /* heap free percentage (default 40) */
-XX:UseSerialGC, /* use serial garbage collection */
-XX:ThreadStackSize, /* thread stack size (in KB) */
-XX:MaxInlineSize, /* set max num of bytecodes to inline */
-XX:ReservedCodeCacheSize, /* Reserved code cache size (bytes) */
-XX:MaxDirectMemorySize,
The property element defines a system property that will be
available through the System.getProperty and System.setProperties
methods. It has two required attributes: name and value. For
example:
<property name="key"
value="overwritten"/>
Properties set in the jnlp file will normally be set by Java Web
Start after the VM is started but before the application is
invoked. Some properties are considered "secure" properties and can
be passed as -Dkey=value arguments on the java invocation command
line.
The following properties, as well as properties beginning with
either "javaws." or "jnlp.", are considered "secure" and will be
passed to the VM in this way:
The applicationelement 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-classattribute 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:
The (optional) progress-classattribute can be used to indicate that the class
of this name implements the javax.jnlp.DownloadServiceListener
interface. This class may be loaded first and used to indicate the
progress of other resources being downloaded and verified.
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-descelement
instead of the application-desc element. For example:
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-classattribute 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-classattribute can be used to indicate that the class
of this name implements the javax.jnlp.DownloadServiceListener
interface. This class may be loaded first and used to indicate the
progress of other resources being downloaded and verified.
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.
The (optional) progress-classattribute can be used to indicate that the class
of this name implements the javax.jnlp.DownloadServiceListener
interface. This class may be loaded first and used to indicate the
progress of other resources being downloaded and verified.
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.