GlassFish Wiki : Gfv3AppclientcontainerOnepagerDraft

App Client Container One Pager

[

Unknown macro: {TableOfContents title='App Client Container'}

|(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

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.

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

command line option then the ACC will start the JavaFX script engine and have it interpret the .jfx file.

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

option to identify the main "script" if one by the specified name is found on the classpath. (Typically that option specifies the main class. I suspect very few people would use the interpreted script support for JavaFX vs. compiling FX to .class files and packaging them into their app clients.

Except in blog entries we have never publicized this feature. We have never mentioned it in our formal product documentation. John Clingan has agreed we can drop 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 (name to be determined: gf-acc.jar is one possibility and the rest of this one-pager refers to that name) 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-acc.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 new ACC instance, passing configuration information to identify the app client main class and control the ACC's behavior, and then run 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.

The client code will first create a new ACC instance:

 
        org.glassfish.appclient.AppClientContainer myACC = AppClientContainer.newContainer(
	Map<String,Object> options,
	String[] argsToClient); 
       

The 'options' argument is a Map from the option name (drawn from a subset of the appclient command-line options) to the value for that option. Each option name is a constant defined on AppClientContainer of the form XXX_OPTION where 'XXX' is the upper-cased command-line option text - for example, AppClientContainer.XML_OPTION.

Key	Value
xml	InputStream providing the sun-acc.xml content - required
mainclass	Name of the app client's main class
name	display name of the app client, located within the JAR specified by 'client'
client	String or File object for the app client or the EAR containing an app client. The value can refer to either a JAR file or a directory. If this is omitted then the embedding application must make sure that all required classes are accessible via the current thread's context class loader and must specify 'mainclass' (not 'name')
server	String[] of server expressions host[:port] . The array must contain at least one String.
user	String for the username to use for authentication - optional
password	String or char[] to use for authentication - optional

The 'mainclass' option overrides 'name.' At least one of 'mainclass' or 'name' is required. If 'client' is not specified then 'mainclass' is required.

Command-line options that are excluded from the Map:

Option	Notes
textauth	The embedding app can prompt for username and password however it wants, if at all, and pass the values via the 'user' and 'password' values in the Map
passwordfile	The embedding app can implement this functionality itself and then pass the 'user' and 'password' options in the Map.

The ACC class implements Runnable. The embedding application can either use myACC.run() to execute the ACC synchronously or create a new thread with myACC as its Runnable instance.

Note that it is the ACC itself that is being run synchronously or asynchronously. 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 stop() method on ACC. The calling application can invoke myACC.stop() to shut 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 stop() 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.

A single ACC instance may not be started or run more than once. The run method will throw an exception in such cases.

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 command-line ACC (and, as noted above, the callable API) will accept a new option:

appclient -server host[:port][,host[:port]...]

where

host:[port]

indicates the server host and ORB port to use during ORB bootstrapping. If the user omits the port then the ACC uses the default ORB port of 3700.

Values for -server that are assigned on the command line override those in the ORB-related system properties or in the

<target-server>

element in the sun-acc.xml configuration.

Traditional command-line processing

We can support traditional

java

command-line processing by relying on a number of internal changes in how app clients are processed and by allowing users to specify a GlassFish-supplied ACC agent on the command line. The generated app client JAR file (or the "cooked" JAR file) will be almost identical to the developer's original except that:

GlassFish will add a GlassFish-specific manifest entry to record the main class which the developer specified.
GlassFish will set the Main-Class manifest entry to refer to the ACC's main class.

The challenge is to let the user launch the app client using

java -jar cookedJar.jar [client-args...]

and yet also make sure the VM can find the GlassFish ACC JARs. GlassFish cannot add the ACC JAR to the cooked JAR's Class-Path manifest entry because (1) such a reference would need to be relative to the cooked JAR's runtime location, (2) GlassFish does not know where the end-user will place the cooked JAR, and (3) GlassFish does not know where the end-user will have placed the ACC JARs. Plus, the end-user cannot use the

-classpath

option or the

CLASSPATH

environment variable because the behavior of

java -jar

is to ignore those two settings.

To solve this, the user will specify

-javaagent:path-to-ACC-agent.JAR

on the

java

command line. The ACC agent JAR's own Class-Path manifest entry can specify accurate relative paths to the other GlassFish JARs that are needed because they will be in a known location relative to the ACC agent's JAR. This also allows the end-user a way to pass options to the ACC while preserving the normal Java launcher processing for "normal" command-line arguments. That is, the user could launch an app client this way:

 
        java -javaagent:path-to-ACC-agent.JAR=server=foo:3700,bar:3700 -jar cookedJar.jar args-to-the-client... 
       

and the app client's main method would receive as arguments only the args-to-the-client values, not the ACC options.

(Note that the agent itself does not transform any byte code. It's presence simply provides a way to establish where the local installation of the GlassFish ACC JARs reside and to capture any ACC options the user might want to pass.)

(Note also that I do not plan for the

appclient

script to translate all of the user's ACC-related options to agent options and to prepare a

java -jar

-style command to launch the app client and the ACC. This would complicate the scripts and would require that they be kept synchronized with the Java code in the ACC as the command option set evolves. While not impossible to do this would be error-prone. Instead there will be one entry point into the ACC to support the

appclient

script and another to support the

java -jar

syntax. I may revisit this as engineering work continues. See the discussion of splash screen support for a notable exception.)

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

Use the new
```
java -jar
```
launch format, using the Java
```
-splash
```
command-line option at runtime or the
```
SplashScreen-Image
```
manifest entry at development-time.
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.
Build a Java app which uses the embeddable ACC and specify the splash screen image using
```
-splash
```
or
```
SplashScreen-Image
```
.
(under consideration) Launch using the
```
appclient
```
script and specify a new option
```
-splash path-to-splash-image
```
. The platform-specific scripts would need to search for and detect this option and convert it into the
```
java -splash
```
option.

To support the proposed new

-splash

option on the

appclient

script invocation, the scripts will need to detect that option and place it (and the associated value) in the right place on the

java -jar

command line. This is because Java SE displays the splash screen before it even starts the VM. We would not be able to take advantage of the fast splash screen handling that Java now provides if the ACC had to process the

-splash

option itself.

Enhancements to

deploy

and

get-client-stubs

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

command and splash screen support.

In v2 the

deploy --retrieve

option and the

get-client-stubs

command download the single cooked JAR to the specified directory on the local system.

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

option which requires a single client name or a comma-separated list of client names.

The

deploy --retrieve

option and the

get-client-stubs

command will then retrieve the identified cooked JARs (and any required supporting library JARs) to the local directory. If the user omits the optional

--client

option then the commands will behave functionally as in v2 by downloading all the app clients that were packaged in the EAR.

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.

This change 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

case) but it will allow Java Web Start to optimize downloads better. If a developer changes a small app client which depends on a large library JAR, then in v2 the cooked JAR is rebuilt and Java Web Start must download the entire cooked JAR again. In v3 Java Web Start will be able to download only the updated app client JAR and continue to use the cached copy of the previously-downloaded large library JAR.)

4.2. Bug/RFE Number(s):

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 -server
```
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 -server 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