JnlpDownloadServlet is a servlet that simplifies the
deploying Java Web Start applications on a web server as well as providing
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
To understand the useful features that
brings to application deployment, you must first
understand the simplest way an application can be distributed using JNLP and
Java Web Start.
app1 example (in the
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
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
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.]
app2 example shows how to bundle
JnlpDownloadServlet with an application and how to use it to
perform simple substitutions in a JNLP file.
app3 example shows how a versioned resource request is
app3 will be referenced from the
To take advantage of
JnlpDownloadServlet, perform these steps.
JnlpDownloadServletin your web application WAR file. You must use two JAR files to have the full functionality,
jardiff.jar. These two JAR files are put in the
WEB-INF/libdirectory of your WAR file.
JnlpDownloadServletusing your web application's web.xml file. It must contain lines that identify
JnlpDownloadServletand 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>
app3 examples show how to package
JnlpDownloadServlet in a web application. Review the Ant build
app3/build.xml for more
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,
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
TS:. The rest of the line must contain a
time stamp in ISO 8601 format, which has this basic format:
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 spec="1.0+" codebase="$$codebase">
When a client requests the JNLP file,
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:
||The URL of the request except for the name of the JNLP file|
||The name of the JNLP file|
||The base URL of the web application|
||The web server address|
||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:
app3/pie.jnlp examples use only
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:
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
1.2, and associated locales of
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
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
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
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
<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>
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
<jar href="app-lib.jar" version="2.0" />
The WAR file contains the library,
app-lib.jar, and this XML version
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
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.
*.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
to see how the Pack200 file is created.
pie.jar is simple, the Pack200
file is negligibly smaller; however, for a larger JAR file, the compression is
JNLP substitutions, Pack200 support, and file attribute support are the
most useful features of
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:
FATALmeans a malfunction or internal error occurred inside the servlet.
WARNINGindicates an error processing some of the information in the WAR file or parsing the
INFORMATIONALlogs all requests, replies, directory scanning, and so on.
DEBUGdisplays detailed internal information about how a request is processed.
Logging output is controlled by two servlet initialization
logPath. The log level
can be set to either
The log path specifies a file where the output is written.
If no path is specified, logging is done to the standard log for
ServletContext.log()). Here is an
<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:
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|
To change the MIME type
<mime-type> element in the
web.xml file. Here is
<web-app> ... <mime-mapping> <extension>jnlp</extension> <mime-type>text/ascii</mime-type> </mime-mapping> ... </web-app>
Most of the time, you will use
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
The general format of a time stamp is:
The dashes, colons, and seconds are optional:
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
can be added to the time to indicate that the local time
hh hours and
mm minutes ahead of UTC. For time zones west
of the zero meridian, which are behind UTC, the notation
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)>