This section includes the following topics:
JnlpDownloadServletJnlpDownloadServletJnlpDownloadServlet is a servlet that simplifies
the process of deploying Java Web Start applications on a web
server as well as providing enhanced functionality.
JnlpDownloadServlet is available in the
sample/jnlp/servlet directory of the JDK, both as
compiled JAR files and as source code.
In the simplest case of JNLP deployment, you put your application files and a JNLP file on a web server. After you configure the web server for the JNLP MIME type, you have basic JNLP functionality — the user clicks on a JNLP file link in a browser and your application is downloaded and run.
However, this approach has some drawbacks. First, the explicit URL of the application codebase must appear in the JNLP file. This means it must be changed if you decide to host your application elsewhere, or if you're moving from a local test server to a more public production server. In addition, the file system time stamp on your application files will be used to report the time stamp of your application, which might not be what you want. Finally, only the most basic parts of the JNLP protocol are implemented through HTTP. Versioning and other features are not supported.
JnlpDownloadServlet acts as a liaison between your
application files and the client. It provides the following
features:
To understand the useful features that
JnlpDownloadServlet brings to application deployment,
you must first understand the simplest way an application can be
distributed using JNLP and Java Web Start.
The app1 example (in the
sample/jnlp/servlet directory of the JDK) contains a
simple application and, perhaps more valuable, an Ant build script
that builds the application and bundles it in a WAR file for
distribution on a web server.
The application itself consists of a single class,
Pie, and an image file, key-lime.jpg, which are
packaged into the pie.jar JAR file.
The pie.jar archive is packaged into a web application file, app1.war, which has these contents:
WEB-INF/web.xml index.html pie.jnlp pie.jar
The JNLP file describes the application, assuming it is deployed
on a server at http://localhost:8080/, which works for
a locally installed Tomcat server.
<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="http://localhost:8080/app1">
<information>
<title>Pie</title>
<vendor>Example Vendor</vendor>
</information>
<resources>
<j2se version="1.2+"/>
<jar href="pie.jar" main="true" />
</resources>
<application-desc/>
</jnlp>
Consider the interaction between client and server as a dialog:
[User clicks a link in the browser.]
Client browser: May I please have pie.jnlp?
Server: Yes, here you go.
Client browser: I notice the MIME type is
application/x-java-jnlp-file. Java Web Start, would
you please handle pie.jnlp for me?
Client Java Web Start: Let me see what resources are required for this application. Hey Server, can I please have pie.jar?
Server: Here you go.
Client Java Web Start: Now I'll launch the JAR file using its
Main-class manifest attribute.
[Application appears on the user's screen.]
The app2 example shows how to bundle
JnlpDownloadServlet with an application and how to use
it to perform simple substitutions in a JNLP file.
The app3 example shows how a versioned resource
request is handled by JnlpDownloadServlet.
Both app2 and app3 will be referenced
from the following sections.
JnlpDownloadServletTo take advantage of JnlpDownloadServlet, perform
these steps.
JnlpDownloadServlet in your web
application WAR file. You must use two JAR files to have the full
functionality, jnlp-servlet.jar and
jardiff.jar. These two JAR files are put in the
WEB-INF/lib directory of your WAR file.*.jnlp and *.jar to
JnlpDownloadServlet using your web application's
web.xml file. It must contain lines that identify
JnlpDownloadServlet and makes it the handler for JNLP
and JAR files. Here is a complete example:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<servlet>
<servlet-name>JnlpDownloadServlet</servlet-name>
<servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>JnlpDownloadServlet</servlet-name>
<url-pattern>*.jnlp</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JnlpDownloadServlet</servlet-name>
<url-pattern>*.jar</url-pattern>
</servlet-mapping>
</web-app>
The app2 and app3 examples show how to
package JnlpDownloadServlet in a web application.
Review the Ant build script app2/build.xml or
app3/build.xml for more information.
JnlpDownloadServlet makes convenient substitutions
in your JNLP files. When the client requests a JNLP file, the
servlet reads the original file, substitutes values, and returns
the results.
If the first line of your JNLP file contains a time stamp,
JnlpDownloadServlet uses the value as a time stamp for
your application. If you do not specify a time stamp,
JnlpDownloadServlet uses the last modified time stamp
from the file system.
Using an explicit time stamp is useful if you copy a JNLP file to multiple servers for load balancing. The explicit time stamp ensures that clients see consistent results, regardless of which server they consult.
To use an explicit time stamp, add a line to the top of your
JNLP file. Begin the line with TS:. The rest of the
line must contain a time stamp in ISO 8601 format, which has this
basic format:
YYYY-MM-DD hh:mm:ss
Here is one example:
TS: 2010-08-07 21:19:05
Consult the Reference section for a more complete description of the time stamp string.
JnlpDownloadServlet makes substitutions for strings
that begin with two dollar signs. For example, consider this line
in a JNLP file:
<jnlp spec="1.0+" codebase="$$codebase">
When a client requests the JNLP file,
JnlpDownloadServlet substitutes the correct value for
$$codebase, wherever it is deployed. This is
convenient because you do not have to hardcode this value in the
JNLP file, making it easier to move from server to server.
The full list of substitutions is shown in the following table:
| Name | Substituted value |
|---|---|
$$codebase |
The URL of the request except for the name of the JNLP file |
$$name |
The name of the JNLP file |
$$context |
The base URL of the web application |
$$site |
The web server address |
$$hostname |
The name of the server |
For example, suppose the app2 example is deployed
at example.com. The values of each substitution would
be as follows:
| Name | Substituted value |
|---|---|
$$codebase |
http://example.com/app2/ |
$$name |
pie.jnlp |
$$context |
http://example.com/app2 |
$$site |
http://example.com |
$$hostname |
example.com |
The app2/pie.jnlp and app3/pie.jnlp
examples use only $$codebase.
The JNLP specification supports requesting application resources with explicit version numbers or resources for certain locales, operating systems, and system architectures. This means that you can deploy an application that has different libraries for different operating systems or different resource files for different locales.
JnlpDownloadServlet provides support for special
requests with two different mechanisms. The first is a scheme for
naming resource files where locales, operating systems, and other
parameters are embedded in the file name. The second mechanism
involves an XML file that describes the parameters of resource
files in the same directory.
JnlpDownloadServlet enables you to specify
information about files by embedding it in a file name. If the file
name contains two underscores in a row, the file name is treated as
containing attributes. A prefix letter specifies the attribute
information, as shown here:
| Prefix | Meaning |
|---|---|
V |
Version number |
O |
Operating system |
A |
Architecture |
L |
Locale |
Only one version is allowed per file, but a file can be
associated with multiple operating system, architecture, or locale
attributes. For example, application__V1.2__Len_US__Len.jar
means that the resource application.jar has a version
of 1.2, and associated locales of en_US
and en.
For example, consider a JNLP file that contains this resource line:
<jar href="app-lib.jar" version="2.0" />
When Java Web Start encounters this line in the JNLP file, it
sends a request to the server for version 2.0 of
app-lib.jar. If you have placed a file
app-lib__V2.0.jar in your web application,
JnlpDownloadServlet returns it to the client as
version 2.0 of app-lib.jar. Note how the actual file
name in your web application gets remapped to be visible to the
client as app-lib.jar.
The file naming convention can be cumbersome, especially if you have multiple resource files that each have multiple associations for operating systems, architectures, or locales.
JnlpDownloadServlet supports an alternate
mechanism, where all attributes are described in a separate XML
file. The servlet looks for a version.xml file in the
same directory as the resource. The version.xml file
contains information about the other files in the same
directory.
For example, the following version.xml file
describes a resource that is available to a client as
application.jar. The actual file is stored in the same
directory as application-1_2-us.jar.
<jnlp-versions>
<resource>
<pattern>
<name>application.jar</name>
<version-id>1.2</version-id>
<locale>en_US</locale>
<locale>en</locale>
</pattern>
<file>application-1_2-us.jar</file>
</resource>
</jnlp-versions>
The app3 example shows how to respond to a
versioned request for a resource using the XML version file. In
particular, the JNLP file contains this resource line:
<jar href="app-lib.jar" version="2.0" />
The WAR file contains the library, app-lib.jar, and
this XML version file version.xml that describes the
library:
<jnlp-versions>
<resource>
<pattern>
<name>app-lib.jar</name>
<version-id>2.0</version-id>
</pattern>
<file>app-lib-2.0.jar</file>
</resource>
</jnlp-versions>
Note how the actual name of the file,
app-lib-2.0.jar, is remapped so that the file name
visible from the client is app-lib.jar.
JnlpDownloadServlet generates and returns
incremental updates to JAR files, if possible. If the
current-version-id parameter is included in the
request, and the servlet can find both a match on the
current-version-id and the requested version, and the
request is for a JAR file, then a JARDiff file is generated by the
servlet. The JARDiff file is returned if its size is less than that
of the requested version.
The JARDiff file is generated and stored in a temporary
directory that is specific to the web container. The servlet finds
the temporary working directory using the
javax.servlet.context.tempdir context attribute.
Pack200 is an efficient compression technology for JAR files. Download and installation times for applications are important factors in how users perceive applications. Making your application resources as small as possible reduces the amount of time users must wait for your application to download.
JnlpDownloadServlet can supply resources for
clients, such as Java Web Start, that support GZIP and Pack200
downloads. Place *.jar.pack.gz or
*.jar.gz files together with your original
*.jar files on the server. For example,
JnlpDownloadServlet chooses the best of the following
files, based upon what the client supports:
pie.jar pie.jar.gz pie.jar.pack.gz
You can create Pack200 files using the pack200 tool
that is included with the Java Development Kit. The
app3 example creates a Pack200 version of the
pie.jar file. Look at build.xml to see
how the Pack200 file is created. Because pie.jar is
simple, the Pack200 file is negligibly smaller; however, for a
larger JAR file, the compression is much greater.
JNLP substitutions, Pack200 support, and file attribute support
are the most useful features of JnlpDownloadServlet.
The servlet also supports a logging system and MIME type
mapping.
The servlet has logging capabilities that enable you to monitor its behavior. Logging messages are generated in different categories:
FATAL means a malfunction or internal error
occurred inside the servlet.WARNING indicates an error processing some of the
information in the WAR file or parsing the version.xml
file.INFORMATIONAL logs all requests, replies,
directory scanning, and so on.DEBUG displays detailed internal information about
how a request is processed.Logging output is controlled by two servlet initialization
parameters, logLevel and logPath. The log
level can be set to either NONE, FATAL,
WARNING, INFORMATIONAL, or
DEBUG. The log path specifies a file where the output
is written. If no path is specified, logging is done to the
standard log for servlets (using
ServletContext.log()). Here is an example:
<servlet>
<servlet-name>
JnlpDownloadServlet
</servlet-name>
<servlet-class>
jnlp.sample.servlet.JnlpDownloadServlet
</servlet-class>
<init-param>
<param-name>
logLevel
</param-name>
<param-value>
DEBUG
</param-value>
</init-param>
<init-param>
<param-name>
logPath
</param-name>
<param-value>
/logs/jnlpdownloadservlet.log
</param-value>
</init-param>
</servlet>
The servlet treats JNLP and JAR files specially. Substitutions
are made in JNLP files as desribed in Substitutions. A version-based request for a
JAR file can result in the generation of an incremental update. The
servlet uses extensions to determine if a file is a JNLP or JAR
file. The default extension of JNLP files is .jnlp and
for JAR files is .jar. These default extensions can be
overwritten by the initialization parameters:
jnlp-extension and jar-extension. Here is
an example:
<init-param>
<param-name>
jnlp-extension
</param-name>
<param-value>
.xjnlp
</param-value>
</init-param>
The MIME type that is returned for a file is also based on its extension. The MIME type is looked up in the configuration files for the web container and the WAR file. If no mapping is specified, the default MIME types are assigned:
| Extension | Default MIME Type |
|---|---|
.jnlp |
application/x-java-jnlp-file |
.jar |
application/x-java-archive |
.jardiff |
application/x-java-archive-diff |
To change the MIME type JnlpDownloadServlet
returns, use the <mime-type> element in the
web.xml file. Here is an example:
<web-app>
...
<mime-mapping>
<extension>jnlp</extension>
<mime-type>text/ascii</mime-type>
</mime-mapping>
...
</web-app>
JnlpDownloadServletMost of the time, you will use JnlpDownloadServlet
directly. In rare cases, you might want to add functionality to
JnlpDownloadServlet. The full source code is
available, and the build is relatively straightforward.
You must have GNU make, a Java Development Kit
(JDK), and you must define environment variables. Here is one
example on a Linux system.
$ export CLASS_PATH=/home/edmond/Applications/apache-tomcat-7.0.2/lib/servlet-api.jar $ export FILE_SEPARATOR=: $ export TMPDIR=/tmp $ export SDK_HOME=/home/edmond/jdk1.7.0 $ make . . .
The output of the build is lib/jnlp-servlet.jar and
lib/jardiff.jar.
The general format of a time stamp is:
YYYY-MM-DD hh:mm:ss
The dashes, colons, and seconds are optional:
YYYYMMDDhhmm
The hh is in 24-hour notation. By default, the local time zone is used. Universal Time (UTC), also known as GMT time, can be specified by appending the capital letter Z to a time:
23:59:59Z or 235959Z
The strings +hh:mm, +hhmm, or
+hh can be added to the time to indicate that the
local time zone is hh hours and mm
minutes ahead of UTC. For time zones west of the zero meridian,
which are behind UTC, the notation -hh:mm,
-hhmm, or -hh is used instead. For
example, Central European Time (CET) is +0100 and U.S./Canadian
Eastern Standard Time (EST) is -0500. The following strings all
indicate the same point in time:
12:00Z = 13:00+01:00 = 0700-0500
The complete document type definition (DTD) for the
version.xml file is shown here:
<!ELEMENT jnlp-versions <resource*, platform*)> <!ELEMENT resource (pattern, file)> <!ELEMENT platform (pattern, file, product-version-id)> <!ELEMENT pattern (name, version-id, os*, arch*, locale*)> <!ELEMENT name (#PCDATA)> <!ELEMENT version-id (#PCDATA)> <!ELEMENT os (#PCDATA)> <!ELEMENT arch (#PCDATA)> <!ELEMENT locale (#PCDATA)> <!ELEMENT file (#PCDATA)> <!ELEMENT product-version-id (#PCDATA)>
