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.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/> </information> <security> <all-permissions/> </security> <resources> <j2se version="1.4.2"/> <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.
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. Java Web Start requires this attribute to be set
in order for the application to be included in the Application Manager.
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
Application Manager 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 Application Manager;
in desktop shortcuts.
A 64x64 icon is shown during download; in the Application Manager 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 a kind="splash" attribute, but does contain another icon
tag, Java Web Start will display a splash screen consisting of the image specified
by the icon element on the left and the application's title and vendor
on the right.
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.
A splash image will be surrounded by a border defined by Java Web Start.
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.
Applications not marked offline in the JNLP file will not be launched by
the Application Manager. By default Application Manager only launches an application
if the client system is online.
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 reasonable fast
server connection, the lastest version of the application will usually be
run, but it is not guaranteed. The application, however, can be run offline.
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 and API (JNLP) Specification v1.0.1 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:
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 2 SE Runtime Environment (JRE)
versions an application is supported on, as well as standard parameters to
the Java Virtual Machine. If several JREs can 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 (specification)
version of the Java 2 platform. Currently defined platform version are 1.2,
1.3, and 1.4. (A platform version may optionally contain a micro version number;
e.g., 1.4.2.)
Exact product versions (implementation versions) may also be specified—e.g.,
1.3.1_01 or 1.4.2-beta by Sun Microsystems, Inc.—by including the href
attribute. E.g.,
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 property element defines a system property that will be available
through the System.getProperty and System.getProperties methods.
It has two required attributes: name and value.
For example:
<property name="key" value="overwritten"/>
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:
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.