App Client Container features in GlassFish v3
By Tim Quinn-Oracle on Dec 10, 2009
Today marks the release of GlassFish v3.0 which complies with the Java EE 6 specification! Other postings highlight a number of other areas. I'll talk briefly about the app client container (ACC) in v3. Much of this information appears in the release notes accessible from the main v3 page as well, but here it's all focused on the ACC.
The v3 ACC is feature-compatible with the v2 ACC. You should see no difference in functionality, whether you launch using the appclient script or the built-in Java Web Start support...except for some exceptions I've described below. Below I've noted a few highlights that users might find useful or interesting: stricter access from clients to other JARs in the EAR, a change in the downloaded file format, and the new embeddable ACC.
Stricter JAR Access
The Java EE 6 spec imposes stricter rules than Java EE 5 about what JARs in an EAR an app client should have access to. In v2 an app client would see EJB modules as well as any JARs at the top level of the same EAR. In v3 this is no longer true by default when you deploy an EAR. You can add elements to the client manifest's Class-Path to refer to such JARs, or for library JARs move them to the library directory in the EAR (/lib by default or settable using the <library-directory> element in the application.xml).
You can request the older, v2 behavior by specifying --property compatibility=v2 on the deploy command when you deploy an app. Note that if you have deployed an app under v2 and then use the upgrade tool then v2 compatibility happens automatically.
Downloaded File Changes
When you deploy an app and specify --retrieve localdir, or use the get-client-stubs command, GlassFish downloads not just the app client but other application files the client needs -- such as library JARs and some files GlassFish generates. In v2 GlassFish would group all of these files into a single, large JAR file and download that. Then, as the first step in any app client launch, the ACC had to expand that large JAR file into a temporary directory before it could start the client. GlassFish v3 does not package all these files into a single large JAR. Instead, GlassFish downloads these files individually into a subdirectory below the directory you specify on the deploy or get-client-stubs command.
This helps the ACC launch the client faster, because there's no need to expand any files first.
You still launch the client using the exact same command as in v2. For example, if you deploy myApp.ear which contains the app client myClient.jar, then in v3 as in v2 you launch the client using
appclient -client downloaddir/myAppClient.jar
Note: We have never officially published or documented the format or content of the downloaded directory, but in v2 some users have copied downloaded app clients by simply copying the single downloaded myAppClient.jar file. This no longer works in v3. Instead, use the get-client-stubs command to download the client files to the new location.
Beginning in v3 you can "call" the ACC from inside a running Java application of your own. (For many users the appclient command or the built-in Java Web Start support will continue to meet their needs.) The functional spec for the v3 ACC described the API, as does the published javadoc, but the basic programming model is that your application creates an app client container builder, invokes methods on that builder to configure the app client container (security, etc.) then gets the app client container from the builder. Your application can then pass the app client to be run to the just-configured ACC's launch method, and the client class starts with the full support of the ACC behind it.
In fact, the appclient command implementation itself uses the embedded ACC API.