Thanks for the notes. Some added comments inserted...
Bill Shannon wrote:
> I think Roberto and I disagree on this.
>
> I like the builder pattern with static factory methods that return a
> builder object, from which you get an object representing the running
> app client container.
>
> I think having different builder (config) classes for the different
> cases is overkill. If some methods really need to be prohibited in
> certain cases, I think IllegalStateException is fine.
Easily changed.
>
> I definitely don't like having "startContainer" be a static method that
> operates on a config, rather than being a method *of* the config
> (builder).
I have changed this so the start() method is on the builder class and
returns the running AppClientContainer. I would propose to rename the
"Config" to "Builder" because, I would not normally expect something
called a config object to able to construct an ACC whereas I would
expect that of a builder object.
>
> Also, while our current implementation may limit your ability to start
> a container more than once, I can imagine that we might want to remove
> that limitation in the future, and I wouldn't want to have to redesign
> these classes at that point. (I don't think your proposal has that
> limitation, but I think Roberto's proposal did.)
Yes, there is nothing in this design that would prevent that. A single
builder object's start() method could conceivably be invoked repeatedly
to create multiple app clients. As we've talked about, we would
probably add logic to prevent that for now until we were confident that
the ACC and the modules on which it depends would work with multiple
ACCs active in a single VM. Permitting this later on would require
removing a line or two from the start() method but that's all.
I have updated the partial Javadoc to reflect the proposed changes:
http://wiki.glassfish.java.net/attach/Gfv3AppclientcontainerOnepager/AppClientContainer.html
- Tim
>
>
> Tim Quinn wrote:
>> 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
>