avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject Re: [A4:Fortress/Merlin] Coming to grips with terminology
Date Tue, 28 Jan 2003 15:21:36 GMT
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.
> 
> http://www.osm.net/doc/assembly/api/org/apache/avalon/assembly/appliance/DefaultAppliance.html


short answer: no.

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:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>


Mime
View raw message