Using the Embeddable ACC

You can embed the ACC into your application client. If you place the as-install/modules/gf-client.jar file in your runtime classpath, your application creates the ACC after your application code has started, then requests that the ACC start the application client portion. The basic model for coding is as follows:

1. Create a builder object.

2. Operate on the builder to configure the ACC.

3. Obtain a new ACC instance from the builder.

4. Present a client archive or class to the ACC instance.

5. Start the client running within the newly created ACC instance.

Your code should 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 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 loads the application client's main class, performs any required injection, and transfers control to the static main method. The ACC's run method returns to the calling application as soon as the client's main method returns to the ACC.

If the application client's main method starts any asynchronous activity, that work continues after the ACC returns. The ACC has no knowledge of whether the client's main method triggers asynchronous work. Therefore, if the client causes work on threads other than the calling thread, and if the embedding application needs to know when the client's asynchronous work completes, the embedding application and the client must agree on how this happens.

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

The ACC does not prevent the calling application from creating or running more than one ACC instance during a single execution of the application either serially or concurrently. However, other services used by the ACC (transaction manager, security, ORB, and so on) might or might not support such serial or concurrent reuse.