I've just completed the process of writing, with the able help of Rick Palkovic, a new article on Java Web Start support for app clients in GlassFish and publishing it in the technical articles section of java.sun.com.
Those of you who have read this blog routinely probably won't find much that is new there, but as always we're trying to reach a broader audience and promote the use of app clients in general and the Java Web Start launch feature in particular. This article should help!
Java Web Start allows the developer to specify his or her own files to use for the icon and splash screen images. The GlassFish support for launching app clients using Java Web Start now allows the app client developer the same ability.
[Read More]How does GlassFish know how to respond to the Java Web Start URLs?
If you have used or read about the new Java Web Start support for app clients in GlassFish, then you know about the URLs you use to launch app clients via Java Web Start. You know that the app server provides defaults for the URL paths for each app client, and that developers can override those defaults in the runtime deployment descriptor for the app client. Those URLs specify regular http requests, which you might (correctly) expect are handled by the web container in the app server.
But how? The application you built and deployed contains no web component to respond to such requests.
The answer is that the Java Web Start support uses a new enhancement to the web container known as the ad hoc servlet mechanism. Jan Luehe has blogged about this and he describes very nicely how this works from the web container's perspective. Briefly, this feature provides an API that allows the app server to create servlets in the web container at runtime, without a developer building a web app or an administrator deploying one. Servlets created this way can also be removed using calls to the API. This ability is an absolute necessity for Java Web Start support. This blog gives a quick look at how the Java Web Start support uses this feature.
When you deploy an application that is an app client or contains one, the app server checks to see if the developer wants the app client to be eligible for Java Web Start support. If so, the app server then checks to see if the developer specified a URL path to be used to access the app client. Both of these optional settings are in the runtime deployment descriptor (sun-application-client.xml) for the app client. Unless you specify otherwise, the app server marks all app clients eligible for Java Web Start support and builds default URL paths for each.
Now that it has either your specified URL path or the default one, the app server needs to ask the web container to respond to that path and route requests for that URL to a Java Web Start support system servlet – one that GlassFish provides automatically as part of the app server. (Just to be clear, this servlet is part of GlassFish, not part of the Java Web Start technology itself that is part of Java SE.) The app server does this by using the ad hoc registration API that com.sun.enterprise.web.WebContainer provides. From that point on, the web container will route requests addressed to the Java Web Start path for the app client to the Java Web Start support system servlet.
This app server registers the URL path when you deploy an app client or when the app server starts up and initializes a previously-deployed app client. Similarly when you shut down the app server or undeploy an app client, the app server uses the ad hoc registration API to unregister the path for that app client. By asking the web container to unregister the app client's path, we break the connection between that path and the app client. From then on, requests to that URL will follow the normal web container processing which will typically result in a 404 error because the web container will no longer recognize that URL as one that it should respond to.
The good news is that you don't need to know any of this to use the Java Web Start support for app clients in GlassFish. Perhaps the even better news is that this feature of the web container is generic and is already being used not only for Java Web Start support for also for web services support. Jan's blog tells more about that and about the inner workings of the ad hoc mechanism itself. But we thought some people might be interested in learning how this actually works behind the scenes.
Some of the details of the Java Web Start support in GlassFish have changed. You can still launch any app client you deploy using Java Web Start, so that this outward behavior has not changed. But what happens inside the app server has evolved, and you have some new options for controlling some of that processing.
Basically, we are trying to help end-users protect themselves even more vigorously from the risks of downloading programs over the network, which is after all what the Java Web Start feature of GlassFish does. Very briefly, two types of jar files downloaded via Java Web Start from the app server are now always delivered in signed form:
the appserv-jwsacc.jar (which contains key parts of the app client container that actually executes an app client), and
the generated app client jar files (which contain the contents of the original app client jar from the developer plus some additional information needed to run the client correctly).
The app server will sign them automatically for you using a self-signed certificate that is created any time you create a new app server domain. This auto-signing behavior is very convenient in a development environment since it requires you to do no additional set-up. But the default auto-signing behavior it is not very secure, because anyone can create a self-signed cert claiming to be anyone. In fact, this is why Java Web Start warns you, when it downloads a jar signed with a self-signed certificate, that the cert is invalid. The end-user can still choose to run the downloaded code, but at his or her own risk.
If you have your own certificate, you can arrange for the app server to use it instead of the domain's self-signed certificate in this auto-signing mechanism. If your certificate is in a trusted chain to a certificate authority, then your end-users can be much more confident that the code is trustworthy.
In either case, the auto-signing behavior signs every jar file with the same cert. If you want to, you can manually sign individual jars with different certs.
The steps to trigger the non-default behavior – either to have the app server auto-sign the jars with your cert or for you to sign the jars manually – are actually fairly simple, but there's some important background information that you'd need. I have written up this rough document that tries to explain this. The content will probably form the basis for the product documentation for this aspect of the Java Web Start feature, so I would very much appreciate any feedback people have on the description as well as the feature itself. I already know of several ways in which I would like to improve the overall process, but I'd love to hear what others have to say.
Today is our launch of the Sun Java System Application Server 9.0 Platform Edition beta. Download this software and use it to build and deploy enterprise applications that conform to the latest Java EE 5.0 specification.
This is one of Sun's products based on the GlassFish project. As such, it is the first of our app server product downloads (other than the GlassFish builds themselves) to support launching app clients using Java Web Start technology. I've written quite a bit about this lately, and below are some links to those notes. There are many other new features in this download. Go to the download page to find out much more. And I'll be adding new entries to the blog about the Java Web Start feature soon.
Getting started with the default settings
Customizing the Java Web Start splash screen users see
Customizing the URL which launches an app client
Passing command-line arguments and property settings
Turning Off Java Web Start support
Some app clients may accept command-line arguments or use certain property settings. This post describes how you use the GlassFish Java Web Start feature to pass them to your app client.
You are probably used to just putting these settings on the appclient command line like this:
appclient -client myclient.jar -Dcolor=red -shape rectangle
It's not quite that simple when you launch the client using the Java Web Start feature in GlassFish. But it's not too bad.
You can specify arguments and properties by adding a query expression to the URL you use to launch your app client. Any query parameter with the name arg is passed exactly as-is as a command-line argument to the app client. If your client expects arguments like this:
-shape rectangle
then you will pass two arguments like this:
http://<host>:<port>/<launch-url>?arg=-shape&arg=rectangle
(See my earlier posts about the default URL path and how you can customize the path.) Note that the minus sign that introduces the “shape” keyword is included in the first query parameter value. It's your client – not any GlassFish code – that interprets the minus sign as a keyword introducer, just as with any Java application you might write that deals with command-line arguments. That's why you set “-shape” and “rectangle” up as two separate arguments in the query string.
Suppose your client works with a property that you might normally specify on a Java command line using
-Dcolor=red
for example. You can specify properties via the Java Web Start feature using prop query parameters in the URL:
http://<host>:<port>/<launch-url>?prop=color=red
Notice that the GlassFish Java Web Start feature will interpret everything after the first equals sign in the “prop” expression as <property-name>=<value>. So in this example the property “color” will be set to the value “red.” The setting ?prop=equation=y=2*x would set the property “equation” to the value “y=2*x” when your client is started. The setting ?prop=xyz would set the property “xyz” to the empty string.
You can combine arguments and properties in any order. Your client will receive the arguments in the order they appear in the query string. Here is an example that assigns the arguments and properties from the earlier examples in one URL:
http://<host>:<port>/<launch-url>?arg=-shape&arg=rectangle&prop=color=red
You probably do not want end-users to have to type such URLs into their browsers to launch the app client. Consider building a web page with a link that includes the query string. Or perhaps a dynamic page would gather some input and prepare the URL for the user accordingly.
We think most users will welcome the ability in the GlassFish project to launch app clients using Java Web Start technology, but it may not be for everyone. Developers and administrators can control for each individual app client whether end-users can use this feature or not.
Before the app server starts Java Web Start support for an app client it makes sure that the developer has declared the app client eligible for Java Web Start access. Before the app server actually responds to requests for an eligible app client it makes sure that the administrator has enabled the app client for Java Web Start access. Both conditions must be true, and both are true by default.
In earlier posts I have described some additions to the sun-application-client.xml runtime descriptor. The new element eligible lets developers set whether the app server should support Java Web Start launches of that app client. Here's an example:
<?xml version="1.0" encoding="UTF-8"?>
<sun-application-client>
<java-web-start-access>
<eligible>false</eligible>
</java-web-start-access>
</sun-application-client>The default is “true,” but in the example the developer has chosen to turn off Java Web Start launching for this app client. End-users will still be able to use the appclient script to launch the app client as in prior releases of the app server but they cannot launch it using the Java Web Start feature.
Redeploy the app client if you decide to change its “eligible” setting.
The administrator can control which eligible app clients actually can be launched using the Java Web Start feature. The administrator cannot make an app client accessible to Java Web Start if the developer marked it as ineligible. But the admin can enable or disable eligible app clients. In the current release of GlassFish administrators enable or disable this support at the application level. This means that an administrator enables or disables all app clients within an application together. If you deploy an app client by itself, then the administrator can control it individually. App clients deployed as submodules inside an EAR are all enabled or disabled as a unit.
Administrator use the asadmin command to control this setting and use the set command and “dotted notation” to do so. An example works best here. Support you deploy an application using
asadmin deploy –name MyTestApp testapp.ear
The administrator can use
asadmin set domain.applications.j2ee-application.MyTestApp.java-web-start-enabled="false"
where domain is the name of the domain in which the EAR was deployed. Whatever value you assign governs all app clients in that application.
On the other hand, if you deployed an app client in its own module like this
asadmin deploy -name MyClient testclient.jar
then you can use
asadmin set domain.applications.appclient-module.MyClient.java-web-start-enabled="false"
to control that app client's setting.
If you disable Java Web Start support you can reenable it later by setting the value to “true” in these commands. Keep in mind that if you undeploy an application or an app client, the app server discards such settings. When you deploy the application or app client again later the Java Web Start feature will be enabled by default for the relevant app clients unless and until you change it again.
As we planned the Java Web Start feature we expected that developers and administrators would want some level of control like this. We're very curious to hear from the community what use people are making of the Java Web Start feature, whether we have provided the right type of control for developers and administrators, and what changes you might want to see – or implement yourself. Let us know!
An earlier post explained the default URL that the GlassFish project's Java Web Start feature app server recognizes for launching a particular app client. Today I'll describe how you can control what that URL will be.
Actually, what you can control is the path part of the URL. The host and port will just be those of the running app server. Yesterday I explained how to customize the splash screen which end-users see when they launch an app client using the Java Web Start feature – simply by setting some values in the sun-application-client.xml runtime deployment descriptor for the app client. That's how you set the URL path as well. This example shows setting the path (using the context-root element) and the vendor:
<?xml version="1.0" encoding="UTF-8"?>
<sun-application-client>
<java-web-start-access>
<context-root>/InventoryClient</context-root>
<vendor>Sun Microsystems, Inc.</vendor>
</java-web-start-access>
</sun-application-client>Once you deploy the app client with this runtime descriptor your end-users can use http://host:port/InventoryClient to launch it.
That's all you need to do!
Every app client you deploy using the GlassFish project automatically benefits from Java Web Start support, but you may want to change some of the default behavior.
If you have deployed an app client and then launched it using Java Web Start technology, you may have noticed a splash screen something like this (this one is from a very simple test that displays the values of command-line arguments):
(Sorry if you see empty space above - it's an artifact of the page display. You're not missing anything!)
Java Web Start refers to the first line (“Application Client showArgs-client) as the title of the Java Web Start application and the second line (“Application Client”) as the vendor. For GlassFish app clients launched via the Java Web Start feature, the default title includes the file name of the module that contains the app client. If the app client is contained inside an EAR, then the title is from the name of the app client's submodule within the EAR. The vendor defaults to the value “Application Client.” While these values are accurate, they probably do not help your end-users understand what they are running.
The Java EE standard deployment descriptor for app clients allows you to set a display name for the app client. The GlassFish Java Web Start support uses the app client display name – if you specify one – as the Java Web Start title.
<?xml version="1.0" encoding="UTF-8"?> <application-client xmlns='http://java.sun.com/xml/ns/javaee' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application-client_5.xsd' version="5"> <display-name>Show Arguments</display-name> </application-client>
You can change the vendor by setting a value in the sun-application-client.xml deployment descriptor in the app client module.
<?xml version="1.0" encoding="UTF-8"?>
<sun-application-client>
<java-web-start-access>
<vendor>Sun Microsystems, Inc.</vendor>
</java-web-start-access>
</sun-application-client>
With these changes, the splash screen becomes this:
Probably more what you – and your users – have in mind.
Earlier I referred to a signed jar that is part of the GlassFish project's Java Web Start support. When the Java Web Start client downloads a signed jar, it prompts the user to accept (or reject) the certificate that was used to sign the jar file. This is true of one of the GlassFish jars that supports launching app clients using Java Web Start. The current GlassFish build creates a self-signed certificate that might make end-users nervous.
If you have a certificate backed by an authority, then you can use it to create a replacement signed jar that's functionally identical to the one in the GlassFish build but bears the name of your enterprise—which your end-users will probably feel more comfortable trusting. Thanks to Vince for his entry that nudged me to get this entry written.
(The process I'm about to describe will work just fine, although we would like to make it a little easier for you to do this. Stay tuned for any breaking news.)
After you build or install GlassFish, look in the lib subdirectory below the installation directory. Note the two files appserv-jwsacc.jar and appserv-jwsacc-signed.jar. The second is the first but signed with the GlassFish self-signed cert. If you have your own cert in a keystore, you can follow these steps to prepare your owned copy of the signed jar:
cd to the lib subdirectory of the GlassFish installation directory.
Copy the current signed jar to a safe alternate name.
Use the jarsigner utility (part of Java SE) to sign the jar file with your cert, supplying the arguments relevant for your keystore in place of the terms in italics (all of this would be on a single line):
jarsigner
-keystore your-keystore-filepath
-storepass password-for-the-keystore
-keypass password-for-your-secret-key
-signedjar appserv-jwsacc-signed.jar
appserv-jwsacc.jar alias-for-your-cert
Now, the Java Web Start client software will prompt your end-users to accept your own certificate when they launch an app client.
This is a good place to look for more information about managing keystores and certificates.
So, suppose you have an existing application or are developing a new one that includes one or more app clients. In this post I try to answer the first few questions you may have about using the new Java Web Start feature in the GlassFish project app server. This post assumes you'll take all the defaults. In later entries I'll talk about how you can override those.
What do developers and administrators have to do so end-users can launch those app clients using Java Web Start technology?
Nothing, other than deploy the application.
How do end-users use the Java Web Start feature to launch app clients?
Do any of the following:
Use a browser and enter the URL for the app client.
Use the Java Web Start utility javaws and specify the app client's URL as a command-line argument.
Place a link to the app client's URL on a web page in the application so end-users can simply click on it.
What's the URL for launching an app client?
For a stand-alone app client in the file MyClient.jar: http://host:port/MyClient
For the app client MyClient embedded in the ear file MyApp.ear: http://host:port/MyApp/MyClient
What happens during the launch?
You'll see some screens about files being downloaded. Don't panic the first time you launch an app client! Remember from my earlier post that there is a lot to bring down to the client. But once it's there all the infrastructure will be reused.
What about the certificate?You'll also be prompted to accept a certificate.
Briefly, the GlassFish build uses
what's called a self-signed certificate which means the build
created the cert and there is no trustworthy authority backing up the
fact that it was really GlassFish who created it. I'll have more to
say on this later. For now, if you have just built or downloaded the
app server and have not allowed others to tamper with your
installation, you can accept the cert.
What about System.in, System.out, and System.err?
If the app client uses a GUI to display and gather information, then end-users can work with the GUI just as if they had started the app client using the appclient script as in earlier releases of the app server.
On
the other hand, if the app client uses System.in to collect input and uses System.out to display output then
things are more complicated. To see output you can open the Java
Control Panel and in the advanced tab:
Open the
Debugging group and enable tracing. Each Java Web Start app will
create a new trace file in
/your-home-dir/.java/deployment/log
or
C:\Documents
and Settings\your-username\Application
Data\Sun\Java\Deployment\log
Open Java console group and cliek Show console. Each Java Web Start application will automatically open a console output window.
There is currently no way to provide keyboard input via System.in to any Java Web Start application, including app clients. If your app clients requires this, launch the app client using the old reliable appclient script.
GlassFish java web startDuring 2005 I spent time adding a feature to the GlassFish implementation that allows end users to launch app clients using the Java Web Start technology included with the Java runtime. I had a great time doing it, partly because I got to learn and apply some new technology and partly because I got to work closely with many different people in Sun's app server group and other organizations as well. But more importantly, the addition of this new feature may help reinvigorate interest in rich clients as part of enterprise apps.
I'll say right off that we consciously chose to implement a subset of all the features we could think of, so we're eager for you in the community to try the feature out, say what else you'd like to see, and even contribute to the implementation.
Here's some background on app clients and why the new feature seemed like such a good idea...
In Java EE, an application client is a rich-client component of an enterprise app that runs in a lightweight container on the end-user's client system. This app client container (ACC) takes care of a number of details common to many app clients (such as security, dependency injection, and annotations) so the developer can concentrate on the key business elements of the overall application - including the rich client piece.
In earlier versions of the app server, an administrator or an end-user would install the ACC and supporting jar files on remote clients manually or using their own automated procedures. This infrastructure supports any number of app clients from the same or different enterprise apps. Then, either during the deployment of an app or as a separate step later, the user would retrieve the generated app client archive from the server. (The generated app client jar contains the app client code which the developer created as well as other classes and files generated by the app server specifically for that app client.) With the ACC infrastructure in place and the generated app client jar file downloaded to the remote client system, the user would run the appclient script that is part of the ACC infrastructure, specifying which app client should be launched.
That may sound like a lot of work - at least the first time or so you have to do it. After that it begins to become second-nature, but someone still needs to set up new remote client systems and keep the bits on the clients synchronized with new versions of the app on the server.
The whole problem of
downloading and launching applications from a central server to possibly many clients,
caching and reusing bits locally on the clients, and
keeping the downloaded bits up-to-date with what's on the server
is precisely what Java Web Start technology aims to solve. So in the GlassFish project we've kept the original way of working with app clients but we've also added a feature that allows end-users to do all of that by using Java Web Start technology instead of the manual set-up and the appclient script. By visiting a single URL in their browsers - or clicking on a link that's on a Web page in an app they're using - end-users can very easily retrieve the needed files and start the app client.
This is already longer than it should be, but it should give you an idea of the issue we wanted to address and the benefits to admins, developers, and end-users of doing so. I'll be devoting other entries to more aspects of this feature: how end-users use it, how developers can take advantage of it, how we've implemented it, and so on.
GlassFish java web start