App Client Container One Pager

[

|(TableOfContentstitle='AppClientContainer')]

1. Introduction

1.1. Project/Component Working Name:

App Client Container

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

Tim Quinn (timothy.quinn@sun.com)

1.3. Date of This Document:

12/15/2008
rev. 2/4/2009
rev. 4/17/2009

2. Project Summary

2.1. Project Description:

This one-pager focuses on changes in the ACC from v2 which result from P2 or higher requirements. (The ACC was not part of the v3 prelude release.) Further, it includes brief mentions of internal changes but concentrates on external interface changes.

Also, there is a P2 requirement not addressed here for Java Web Start (user-influence and customization of the generated JNLP). For scheduling reasons we are currently planning to address all Java Web Start improvements in the planned 3.1 release. Ideally those improvements would be available for early access well before the release of 3.1.

2.2. Risks and Assumptions:

The main risk is the dependency on other components' readiness in v3, such as remote naming, the ORB, transactions.

A related risk is that to improve server start-up performance we are trying to reduce the number of modules. This has the risk of including server-only classes and resources into JARs that also contain classes and resources which the ACC needs, possibly expanding the footprint.

3. Problem Summary

3.1. Problem Area:

• JavaFX Script support
• Smaller footprint (externally observable but not truly an interface)
• Embeddable ACC
• Allow users to specify ORB endpoints on the appclient command
• Splash screen support
• Traditional command-line processing
• Enhancements to the

  deploy

  and

  get-client-stubs

  commands and their admin console counterparts.

3.2. Justification:

• JavaFX Script support - We want to make it as easy as possible for application developers to take advantage of JavaFX from rich app clients.

• Smaller footprint - Especially using the Java Web Start support it takes too long to download the required GlassFish bits to end-user systems.

• Embeddable ACC - Users want more control over when and how the ACC runs their app clients.

• Current mechanisms for specifying the server ORB endpoints to which to connect are in sun-acc.xml or system property settings and are viewed as sometimes too cumbersome to change there.

• Splash screen support - End-users have a better user experience, especially with network applications such as app clients, if they see a splash screen that reinforces that their application is indeed starting.

• Traditional command-line processing - Allow end-users to run app clients using the normal

  java

  command syntax.

• Enhancements to

  deploy

  and

  get-client-stubs

  commands and their admin console counterparts - Required to support fully the splash screen and

  java

  command line features.

4. Technical Description:

4.1. Details:

JavaFX Script support

We will remove the existing v2 technology preview of JavaFX Script support.

In v2 we added a technology preview of support for JavaFX interpreted scripting. In that implementation if the user's app client includes a .jfx file with the same name (excluding file type) as the value of the

-mainclass

We will drop this from v3 because JavaFX has moved very strongly towards compilation and away from interpreted execution. JavaFX classes can be included in app clients just as any Java class can. Plus, the v2 implementation for client-side scripting in app clients overloads the

-mainclass

Except in blog entries we have never publicized this feature. We have never mentioned it in our formal product documentation. Also, John Clingan is OK with dropping this.

Smaller footprint

As a side-effect of the overall modularization of GlassFish v3, the ACC should shrink appreciably. We may be able to compress it further by identifying modules which might be split into a small client (or server-and-client) submodule and a server-only submodule. The ACC would require only the client module.

In connection with this, GlassFish will deliver a new, separate JAR file gf-client.jar containing the main ACC bits. Its manifest's Class-Path entry will list the various other JARs on which the ACC depends. Although many of these will be OSGi modules, the ACC itself will not execute as an OSGi module nor will it require an OSGi implementation such as Felix to run.

The change in JAR name and contents will be hidden inside the appclient scripts.

Embeddable ACC

Developers will be able to embed the ACC into their client applications. By placing the gf-appclient.jar file on their runtime classpath their applications will be able to create the ACC after their application code has started and request that the ACC start the "application client" portion of their application.

The basic model is that developers will create a builder object, operate on the builder to configure the ACC, obtain a new ACC instance from the builder, present a client archive or class ot the ACC instance, and then start the client running within the newly-created ACC instance. The ACC will load the app client's main class, perform any required injection, then transfer control to main class's static main method, then return to the calling application. (This is equivalent to how the v2 ACC behaves.) As before, if the app client starts any asynchronous activity then that work will continue after the ACC returns.

A developer's program would follow this general pattern:

// one TargetServer for each ORB endpoint for bootstrapping
TargetServer[] servers = ...;

// Get a builder to set up the ACC
AppClientContainer.Builder builder = AppClientContainer.newBuilder(servers);

// Fine-tune the ACC's configuration.  Note ability to "chain" invocations.
builder.callbackHandler("com.acme.MyHandler").authRealm("myRealm"); // Modify the config

// Get a container for a client.  
URI clientURI = ...; // URI to the client JAR
AppClientContainer acc = builder.newContainer(clientURI);

or

Class mainClass = ...;
AppClientContainer acc = builder.newContainer(mainClass);

// In either case, start the client running.
String[] appArgs = ...;
acc.startClient(appArgs); // Start the client

...

acc.close(); // close the ACC(optional)

The ACC will invoke the client's main method, which itself could cause async behavior (other threads, GUI) and then the ACC's run method will return to the calling app as soon as the client's main method returns to the ACC. Any async behavior triggered by the client's main method will continue after the ACC returns to the embedding application. If the client causes work on threads other than the calling thread and if the embedding application needs to know when the client's async work completes then the embedding app and the client need to agree on how that will happen. The ACC itself has no knowledge of whether the client's main method triggers asynchronous work.

The ACC's current shutdown handling will be invoked from the close() method on ACC. The calling application can invoke acc.close() to close down any services started by the ACC. If the app client code started any asynchronous activity that might still depend on those ACC services, invoking close() before that async activity completes could cause unpredictable and undesirable results. The shutdown handling will also be run automatically at VM shutdown if the user's code has not invoked stop before then.

The ACC itself will not prevent the calling application from creating or running more than one ACC instance during a single execution of the application, even running more than one ACC instance at a time. But, other services used from the ACC (transaction manager, security, ORB, etc.) might or might not support such reentrancy at the time v3 is released. If one or more of them do not, the behavior will be unpredictable and users should make sure that their embedding apps use only one ACC at a time. Our long-term goal should be for all the services to support concurrent and serial reuse so the ACC API will remain most stable if it does not enforce restrictions now, only to have to lift them later.

Specifying Server ORB Endpoints on Command Line

The

appclient

-targetserver host[:port][,host[:port]...]

where

host[:port]

Values for -targetserver from the command line override those in the ORB-related system properties or in the

<target-server>

java

-like

appclient

command-line processing

We can support traditional

java

appclient

appclient

In v3 the generated app client facade JAR file (the "cooked" JAR file) will be nearly empty except that:

• GlassFish will add GlassFish-specific manifest entries to record the main class which the developer specified and the URI to the developer's original app client JAR, and
• GlassFish will set the Main-Class manifest entry to refer to an ACC-provided main class.

Similarly, the facade JAR file for an EAR containing app clients will be nearly empty except that:

• GlassFish will add GlassFish-specific manifest entries to record the URIs of the facades for each nested app client

The

appclient

appclient (jvm and acc options) -jar myClient.jar (args to the client)

in addition to the v2 syntax

appclient -client myClient.jar (acc options) (args to the client)

Splash Screen Support

Java SE 6 offers splash screen support, either via a Java command-line option or a manifest entry in the program's JAR file. To take advantage of this Java SE feature, developers of Java EE app clients can

1. Use the new

   appclient ... -jar

   launch format, using the

   java

   -splash

   command-line option at runtime or (preferably) the

   SplashScreen-Image

   manifest entry at development-time.
2. In the command environment that will run the appclient script set the VMOPTS environment variable to include the

   -splash

   Java command-line option before invoking the appclient script to launch the client.
3. Build a Java app which uses the embeddable ACC and specify the splash screen image using

   -splash

   or

   SplashScreen-Image

   .

Note that the

appclient

appclient

Enhancements to

deploy

and

get-client-stubs

(not for EA)

In v2 the "cooked" JAR for an EAR that contained multiple app clients contained all the app clients packaged in the EAR, along with supporting library JARs. In v3 GlassFish will prepare a separate cooked JAR for each app client. This will allow us to support, in a straightforward way, the

java

In v2 the

deploy --retrieve

get-client-stubs

In v3 users will be able to, optionally, specify which client(s) they want to retrieve as part of deployment or when separately retrieving the client stubs. These two commands will gain the

--client

The

deploy --retrieve

get-client-stubs

--client

The contents of the local directory has never been identified as a public interface. Nevertheless, this proposal would change what we store there. Users might be accustomed to finding a single downloaded file in the local directory and copying that file elsewhere. That practice will not continue to work unless the user's procedure copies the entire contents of the download directory. If we make this change we will need to include a release note highlighting the change to our usage of the directory.

Similarly, some users might have launched app clients by referring directly to the generated JAR file in the app server's internal

generated

deploy --retrieve

get-client-stubs

The change in download directory format will also let the v3 ACC launch app clients faster. In v2 the first thing the ACC must do is expand the current, single downloaded JAR file into a temporary directory so the contents can be examined and, most importantly, added to a class loader's classpath. (Java classloaders do not support adding JARs nested inside an outer JAR to the class path.) In v3 the constituent files will not have been packed into a single file and, therefore, no expansion step would be needed.

(Such a change is also in line with improvements planned for the Java Web Start support (to be described in a later one-pager). Briefly, I plan to have Java Web Start download the app client JAR and its supporting JARs individually, rather than download the (existing v2) cooked JAR and have to expand it. Not only will this avoid the expansion step (as in the

appclient

4.2. Bug/RFE Number(s):

JavaFX Script support

Feature Issue 4108

Footprint

Feature Issue 4109

Embedded ACC

Feature Issue 4111

Specify server on command line

Feature Issue 4110

Splash screen support

Feature Issue 4115

4.3. In Scope:

as described above

4.4. Out of Scope:

• Java Web Start improvements

4.5. Interfaces:

4.5.1 Exported Interfaces

JavaFX Script support - no new exported interfaces

Footprint - no new exported interfaces

Embedded ACC

• Interface: gf-acc.jar file name
• Stability: evolving
• Former Stability (if changing):
• Comments: Developers will include this JAR in the compile-time and runtime class paths.

• Interface: org.glassfish.appclient.ACC class
• Stability: evolving
• Former Stability (if changing):
• Comments: Developers will refer to this class and its methods to create, configure, start, and stop an embedded ACC.

Specify server on command line

• Interface: appclient command
• Stability: evolving
• Former Stability (if changing):
• Comments: New -targetserver

  host[:port][,...]

  option

Splash screen support - no new exported interfaces; doc to suggest using VMOPTS variable to add the Java SE 6 -splash option and value.

4.5.2 Imported interfaces

JavaFX Script support - no new imported interfaces

Footprint

• Interface: JAR names of other modules which ACC must rely on
• Stability: evolving
• Exporting Project: transactions, injection, ORB, naming
• Comments:

Embedded ACC - no new imported interfaces

Specify server on command line - no new imported interfaces

Splash screen support - no new imported interfaces

4.5.3 Other interfaces (Optional)

n/a

4.6. Doc Impact:

JavaFX Script support

No impact.

We do not currently document this feature. I propose we do not do so because of JavaFX's strategic emphasis on compiled, not interpreted, execution.

Footprint

No impact.

Embedded ACC

Developer's Guide should describe the new ACC API.

Specify server on command line

Administrator's Guide - describe the new option
Administrator's Reference - describe the new option

Splash screen support

Developer's Guide should describe setting the VMOPTS environment variable before invoking appclient to use the Java SE 6 support directly.

4.7. Admin/Config Impact:

No impact.

4.8. HA Impact:

None

4.9. I18N/L10N Impact:

None

4.10. Packaging & Delivery:

New JAR file gf-acc.jar.

4.11. Security Impact:

None

4.12. Compatibility Impact

There are no incompatible changes from v3 prelude to v3/JavaOne. The introduction of the new gf-acc.jar will be hidden in the appclient script.

The new -targetserver option is optional and will not affect existing usages of the appclient scripts.

4.13. Dependencies:

Security, transaction, naming, ORB modules (all used from the ACC).

5. Reference Documents:

6. Schedule:

6.1. Projected Availability:

GlassFish v3/JavaOne release (May '09)

Java Web Start improvements planned for the proposed 3.1 release