I have posted a part of the JavaDoc for the updated embedded ACC API here:
http://wiki.glassfish.java.net/attach/Gfv3AppclientcontainerOnepager/AppClientContainer.html
The links from that page to other classes do not work, but this class
(and its JavaDoc page) contain all the top-level entry points and also
includes a discussion of how to use the API.
To summarize briely:
I have been able to avoid the entire state management issue by crafting
an API in which the calling program:
1. Uses a static factory method AppClientContainer.newConfig to get the
appropriate type of Config object (SingleClassConfig vs. ArchiveConfig).
2. Invokes methods on the Config object to refine the settings in the
config. Method invocation chaining as Roberto described works.
3. Invokes the static AppClientContainer.startContainer(Config config)
which returns an AppClientContainer instance.
4. The AppClientContainer exposes a stop method.
In spirit this approach accomplishes what I think Roberto was striving
towards - using the compiler to enforce correct usage rather than
throwing exceptions at runtime upon detecting improper usage. In
practice this approach achieves this goal without having to resort to
separate classes to represent separate states of the container.
I am in the process of greatly revising the one-pager itself, so do not
expect to see this discussed there yet.
- Tim