org.glassfish.appclient.client.acc
Class AppClientContainer

java.lang.Object
  org.glassfish.appclient.client.acc.AppClientContainer

@Service
@Scoped(value=PerLookup.class)
public class AppClientContainer
extends Object

Embeddable Glassfish app client container (ACC).

Allows Java programs to:

• create a new builder for an ACC (see newBuilder(org.glassfish.appclient.client.acc.config.TargetServer[]) and AppClientContainerBuilder),
• optionally modify the configuration by invoking various builder methods,
• create an embedded instance of the ACC from the builder using AppClientContainerBuilder#newContainer() ,
• startClient the client using startClient(String[]), and
• stop the container using stop().

Each instance of the TargetServer class passed to the newBuilder method represents one server, conveying its host and port number, which the ACC can use to "bootstrap" into the server-side ORB(s). The calling program can request to use secured communication to a server by also passing an instance of the Security configuration class when it creates the TargetServer object. Note that the caller prepares the TargetServer array completely before passing it to one of the newConfig factory methods. The Builder implementation does not override or augment the list of target servers using system property values, property settings in the container configuration, etc. If such work is necessary to find additional target servers the calling program should do it and prepare the array of TargetServer objects accordingly.

The calling program also passes either a File or URI for the app client archive to be run or a Class object for the main class to be run as an app client.

After the calling program has created a new AppClientContainer.Builder instance it can set optional information to control the ACC's behavior, such as

• setting the authentication realm
• setting client credentials (and optionally setting an authentication realm in which the username and password are valid)
• setting the callback handler class
• adding one or more MessageSecurityConfig objects

Once the calling program has used the builder to configure the ACC to its liking it invokes the builder's newContainer() method. The return type is an AppClientContainer, and by the time newContainer returns the AppClientContainer has invoked the app client's main method and that method has returned to the ACC. Any new thread the client creates or any GUI work it triggers on the AWT dispatcher thread continues independently from the thread that called newContainer.

If needed, the calling program can invoke the stop method on the AppClientContainer to shut down the ACC-provided services. Invoking stop does not stop any threads the client might have started. If the calling program needs to control such threads it should do so itself, outside the AppClientContainer API. If the calling program does not invoke stop the ACC will clean up automatically as the JVM exits.

A simple case in which the calling program provides an app client JAR file and a single TargetServer might look like this:

import org.glassfish.appclient.client.acc.AppClientContainer;
import org.glassfish.appclient.client.acc.config.TargetServer;

AppClientContainerBuilder builder = AppClientContainer.newBuilder(
new TargetServer("localhost", 3700));

AppClientContainer acc = builder.newContainer(new File("myAC.jar").toURI());

(or, alternatively)

AppClientContainer acc = builder.newContainer(MyClient.class);

Then,

acc.startClient(clientArgs);
// The newContainer method returns as soon as the client's main method returns,
// even if the client has started another thread or is using the AWT event
// dispatcher thread
// At some later point, the program can synchronize with the app client in
// a user-specified way at which point it could invoke

acc.stop();



Public methods on the Builder interfaces which set configuration information return the Builder object itself. This allows the calling program to chain together several method invocations, such as

AppClientContainerBuilder builder = AppClientContainer.newBuilder(...);
builder.clientCredentials(myUser, myPass).logger(myLogger);


Nested Class Summary

static interface

AppClientContainer.Builder Prescribes the exposed behavior of ACC configuration that can be set up further, and can be used to newContainer an ACC.

Field Summary

static String

APPCLIENT_RETAIN_TEMP_FILES_PROPERTYNAME Prop name for keeping temporary files

Constructor Summary

AppClientContainer()

Method Summary

protected ClassLoader	getClassLoader()
void	launch(String[] args)
protected Class	loadClass(String className)
static AppClientContainer.Builder	newBuilder(TargetServer[] targetServers) Creates a new ACC builder object, preset with the specified target servers.
void	prepare(Instrumentation inst)
void	setClientMainClassName(String clientMainClassName) Sets the name of the main class to be executed.
void	startClient(String[] args)
void	stop() Stops the app client container.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

APPCLIENT_RETAIN_TEMP_FILES_PROPERTYNAME

public static final String APPCLIENT_RETAIN_TEMP_FILES_PROPERTYNAME

Prop name for keeping temporary files

See Also:

Constant Field Values

Constructor Detail

AppClientContainer

public AppClientContainer()

Method Detail

newBuilder

public static AppClientContainer.Builder newBuilder(TargetServer[] targetServers)

Creates a new ACC builder object, preset with the specified target servers.

Parameters:

targetServers - server(s) to contact during ORB bootstrapping

Returns:

AppClientContainer.Builder object

startClient

public void startClient(String[] args)
                 throws Exception,
                        UserError

Throws:

Exception

UserError

prepare

public void prepare(Instrumentation inst)
             throws NamingException,
                    IOException,
                    InstantiationException,
                    IllegalAccessException,
                    InjectionException,
                    ClassNotFoundException,
                    SAXParseException,
                    NoSuchMethodException,
                    UserError

Throws:

NamingException

IOException

InstantiationException

IllegalAccessException

InjectionException

ClassNotFoundException

SAXParseException

NoSuchMethodException

UserError

loadClass

protected Class loadClass(String className)
                   throws ClassNotFoundException

Throws:

ClassNotFoundException

getClassLoader

protected ClassLoader getClassLoader()

launch

public void launch(String[] args)
            throws NoSuchMethodException,
                   ClassNotFoundException,
                   IllegalAccessException,
                   IllegalArgumentException,
                   InvocationTargetException,
                   IOException,
                   SAXParseException,
                   InjectionException,
                   UserError

Throws:

NoSuchMethodException

ClassNotFoundException

IllegalAccessException

IllegalArgumentException

InvocationTargetException

IOException

SAXParseException

InjectionException

UserError

stop

public void stop()

Stops the app client container.

Note that the calling program should not stop the ACC if there might be other threads running, such as the Swing event dispatcher thread. Stopping the ACC can shut down various services that those continuing threads might try to use.

Also note that stopping the ACC will have no effect on any thread that the app client itself might have created. If the calling program needs to control such threads it and the client code running in the threads should agree on how they will communicate with each other. The ACC cannot help with this.

setClientMainClassName

public void setClientMainClassName(String clientMainClassName)
                            throws ClassNotFoundException

Sets the name of the main class to be executed.

Normally the ACC reads the app client JAR's manifest to get the Main-Class attribute. The calling program can override that value by invoking this method. The main class name is also useful if the calling program provides an EAR that contains multiple app clients as submodules within it; the ACC needs the calling program to specify which of the possibly several app client modules is the one to execute.

Parameters:

mainClassName -

Throws:

ClassNotFoundException