Customizing generated Java Web Start JNLP for app clients in GlassFish Server 3.1
By Tim Quinn-Oracle on Feb 27, 2011
For some time, GlassFish has allowed you to deploy application clients to the server - either by themselves or as part of an EAR - and then launch them using Java Web Start. Every Java Web Start application must be described by a Java Network Launch Protocol (JNLP) document, and GlassFish generates this JNLP document automatically for any application client you deploy.
In past releases, you could customize very few parts of the generated JNLP: the vendor name and the download and icon images, for example. But the rest of the JNLP was off-limits.
GlassFish Server 3.1 changes that radically. Now you can customize the generated JNLP almost completely by following a few simple steps:
- Write a JNLP fragment which contains the customizations you want to use and package it into your application.
- Add a reference to that fragment in your glassfish-application-client.xml (formerly sun-application-client.xml) descriptor.
- Deploy the application.
There are some parts of the JNLP which GlassFish still has to control, but most of the document is open to your customization. GlassFish will combine its generated content with your fragment to come up with the JNLP it will use to launch the app client.
You can put your JNLP fragment almost anywhere you want in your application. Then adjust your glassfish-application-client.xml descriptor to include the new <jnlp-doc> element like this
if your fragment is in the app client module itself, or like this
if your fragment is in another JAR (other/myLib.jar in this example) that's in the same EAR as the app client module.
GlassFish will combine each part of your fragment with its own generated JNLP in one of three ways, depending on the specific part of the JNLP document:
- replace the generated content with your content (called "defaulted" content because GlassFish provides defaults which you can override)
- merge the generated content with your content (called "merged" content because GlassFish merges your content with its own)
- use only the generated content (called "owned" content because GlassFish owns those parts and ignores anything you provide)
It's fairly involved to describe unambiguously what the rules are for which parts of your content are used and how (mostly because of the bits that GlassFish still needs to control). The complete discussion is part of the "one-pager" describing this feature which I won't repeat here. But there are a few parts of the document you might especially want to customize.
JNLP documents contain <information> sections which define the vendor name and images which Java Web Start will display while it downloads the application or creates a desktop icon for it. There can be multiple <information> elements so you can use different data for different operating systems, computer architectures, platforms, and locales. GlassFish generates default settings for the <information> data with none of these special settings assigned. So, here are two key types of customizations:
- Override, for <information> elements with no attribute settings for os, arch, platform, and locale, the GlassFish defaults for child elements. (These children can be <title>, <vendor>, <description>, <icon>, etc.)
- Add <information> elements with os, arch, platform, or locale settings and children of such <information> elements.
- Add child elements under the GlassFish-provided <resources> element. (The GlassFish-provided <resources> element does not specify os, arch, or locale.)
- Add new <resources> elements that specify at least one of os, arch, or locale and children under such <resources> elements.
In particular, this flexibility allows you to add JARs to the
application (including platform-specific native libraries) and set
properties to control the behavior of your clients. Note that you do not need to spell out all the JARs your client needs. GlassFish will automatically include the ones listed in the app client JAR's manifest Class-Path setting and any JARs from the EAR's library directory, plus the JARs from GlassFish itself needed to run app clients.
As you write your JNLP fragment, keep in mind that you need to include surrounding XML elements to place your custom content correctly in the resulting document. For example, suppose your client relies on a platform-specific native library when run on Windows and that's the only customization you need to supply. You need to write your JNLP fragment like this
so that GlassFish knows where in the resulting JNLP to "plug in" your content. If you just included the <nativelib> element by itself GlassFish would not know where to insert it into the final JNLP.
As in previous releases of GlassFish, you won't find the resulting JNLP document anywhere on -disk. The document is generated in-memory when you deploy the application or when the server restarts. So if you want to change your JNLP customizations you just edit your fragment file, repackage your application, and redeploy it. The customizations live with the application, not as a separate file or step you need to apply after you deploy the application.