Package org.glassfish.appclient.client.acc

Class AppClientContainer

  • @Service
@PerLookup
public class AppClientContainer
extends Object
    Embeddable Glassfish app client container (ACC).

    Allows Java programs to:

    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);

    Author:
    tjquinn