Stephen McConnell wrote:
Take a look at the JavaDoc for Appliance at the following URL and let me know if it's understandable. Sorry - no pictures just yet. Maybe later.short answer: no.
http://www.osm.net/doc/assembly/api/org/apache/avalon/assembly/appliance/DefaultAppliance.html
long answer:
"The DefaultAppliance class manages the establishment of a component type relative to a deployment criteria. Once established, an appliance provides support for the deployment of component instances..."
and that is just about where I got lost. What I'm looking for is something like:
=========Readable=Documentation=Sample=Follows===========================
What is an appliance?
---------------------
An appliance is a piece of code internal to the container. It is used to manage one or more related components, including their metadata, metainfo, and any other deployment information. It may also do things like dynamic proxying and pooling.
Any class which implements the Appliance interface can be provided to the container's Kernel to do component management. It is even possible to supply the Kernel with different Appliances for different components and blocks.
(go on about cocoon blocks, phoenix blocks, granularity, ..., available appliance implementations, etc etc etc etc)
Analogy
-------
Think of yourself as a client in a restaurant. You communicate with the restaurant through a protocol, usually by uttering some human language against a waiter. Let's say you order a steak dinner. The waiter translates your request for food to the chef, who then sets off to satisfy your request. To do so, he uses lots of different kitchen appliances, like a microwave or a frying pan.
In this analogy, you are client code, the protocol might be SOAP, the waiter is a RequestHandler, the chef is the Kernel, and the appliances we call "appliances" :D The Avalon Components used to create your dinner include potatoes, cow meat, and a few tomatoes. Appliances are responsible for management of these components, and they chop, fry, etc, on Kernel request.
How do I use an appliance?
--------------------------
You normally use an appliance by specifying which class to use in the kernel.xml file:
<kernel>
<appliance class="foo.bla.MyAppliance"/>
</kernel>
How do I create an appliance?
-----------------------------
Extend AbstractAppliance and override foo() and blah() to customize the behaviour. Take a look at DefaultAppliance for a simple implementation.
How does the container use an appliance?
----------------------------------------
the appliance is presented with a context containing information on which components it is to manage, then start()ed. Once running, the appliance has to respond to 'get( String ROLE )' requests by returning an instance of a service or service proxy satisfying the ROLE contract.
Typically, the following happens
MyComponent Appliance Container Appliance OtherComponent
| |<-setup---| | |
| |<-start---| | |
| | |--setup->| |
| | |--start->| |
|<-compose-| | | |
| | | | |
|--get()-->|--get()-->|--get()->|-new()->|
| | | | |
|-provide--|-provide--|-provide-| |
| | | | |
|<-dispose-| | | |
| |-release--|-release-| |
| | | |-dispose|
IE, the container sets up the initial appliance on startup. The appliance happily runs on its own until a component is requested which it cannot provide itself. The container then finds another appliance that can provide that particular component, and passes the result on to the first appliance, which provides it to the component.
When the component is disposed, it no longer needs the service provided, so the appliance notifies the container, which notifies the appliance, and the service is released.
=========Readable=Documentation=Sample=Ends==============================
That is somewhat more understandable. I think it is also wrong....getting an analogy right is real difficult :D It is important to write docs this way though; it forces you to be real clear about the contracts imposed, the assumptions made. If the code cannot be explained, the code is bad code :D
cheers,
- Leo
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
