App Client Container features in GlassFish v3

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.

Embedded ACC

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.   


Hi Tim, did you have a "complete" guide to deploy an ACC client program to a "fresh" JavaSE installation (without any GF installation on the client side).

Posted by Luca Morettoni on December 16, 2009 at 11:17 PM CST #

Hi, Luca.

The application development guide at has quite a bit of information about using Java Web Start to launch app clients and somewhat less about using the appclient script.

There are two cases:

1. Launching using Java Web Start: GlassFish automatically assigns each deployed client a distinct URL within the GlassFish instance. The developer can specify it in the sun-application.xml descriptor or GlassFish will assign a default one of (appName)/(clientName) if the client is packaged in an EAR (the appName is the name of the EAR app and clientName is the URI of the app client within the EAR, omitting the trailing .jar). If you deploy a stand-alone client the default URL is the client's appName. You can also look in the server.log file; each deployment reports the URLs assigned to the app clients in that application.

You can then launch the client either from a command line using

javaws "http://host:port/path-to-client"

or pointing a browser to http://host:port/path-to-client. GlassFish and Java Web Start will make sure that the necessary files are downloaded to the client.

One nice advantage to this approach is that Java Web Start caches the downloaded files and reuses them for later launches if they are still current. It will automatically download a new copy of any file that becomes obsolete in the local cache, for example if the app is redeployed. Neither the developer nor the administrator nor the user needs to do anything special to cause these update to occur (except to redeploy the app to the server).

2. Launching using the appclient script:

(See the asadmin reference manual at for more information about the appclient and package-appclient commands.)

2a. On the GlassFish system run the ${installDir}/bin/package-appclient script which creates This contains the runtime JAR files as well as some domain-specific information that will be needed on a remote system.

2b. Copy the file to each remote system and unzip it.

2c. On each remote system run

${clientInstallDir}/bin/asadmin get-client-stubs --appname name-of-the-app-on-the-server local-directory

to download the client bits to that remote system.

2d. Run the client using ${clientInstallDir}/bin/appclient any-arguments...

I hope that helps. Please feel free to open a documentation RFE (or bug!) at if you feel that documentation that already exists could be improved.

- Tim

Posted by Timothy Quinn on December 16, 2009 at 11:55 PM CST #

Thanks for the quick hints, just two more info.
I run glassfish v3 under OpenSolaris, the package generated by package-appclient command il specific to OpenSolaris installation or can be used into Windows clients (for examples).
About the step "2c", I haven't any asadmin script on remote clients, but just appclient scripts (under ${clientInstallDir}/glassfish/bin)

I can run my application on clients with this command:

${clientInstallDir}/glassfish/bin/appclient -jar EnterpriseApplication1Client.jar

where EnterpriseApplication1Client.jar is manualy copied to each client...

any hints?

Posted by Luca Morettoni on December 17, 2009 at 12:25 AM CST #

I have read about embedding acc into my application, but I can't seem to find gf-acc.jar anywhere. Is this future functionality or does it exist?

Posted by Justin on December 30, 2009 at 07:52 AM CST #

Luca, sorry for the delay in responding. Happy 2010 to you.

Good point. The package-appclient command does NOT capture the files required to perform the asadmin get-client-stubs action on the remote system. This should probably be recorded as a request-for-enhancement for GlassFish v3.

In the meantime, a word of warning... The "deploy --retrieve localdir ..." and "get-client-stubs" commands will download multiple files, not just one JAR, even for a simple stand-alone app client. To make a full copy of the downloaded client to be used on other systems, you could create a zip file of the localdir - the directory where you downloaded the client files to during deployment or using the get-client-stubs command (of course, on a system where the asadmin files are available!). Then copy the zip to the other systems and unzip it into a directory there.

Posted by Timothy Quinn on January 04, 2010 at 02:25 AM CST #


If you add ${installDir}/glassfish/modules/gf-client.jar to your class path then the embedded ACC should be available.

Is there a reference to gf-acc.jar in the documentation somewhere? If so, that's not right.

Posted by Timothy Quinn on January 04, 2010 at 02:27 AM CST #

Post a Comment:
  • HTML Syntax: NOT allowed

News and musings on the technology I work on at Oracle.

The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.


« July 2016