Re: [Avalon4:PROPOSAL] Context Consensus (version 3)

On Fri, 2002-12-13 at 12:05, Leo Sutic wrote:
>                             -oOo-
> 
> Proposal: The following text should (after being HTML-ized) replace the
> current documentation for the Context interface:

The main thing I notice is a reference to a "metadata" concept. Avalon
Framework as of now does not have such a concept, even if its developers
do. It's muddying the waters a little I think. Below some "patches" with
a "reduce to the max" idea behind them. No change in meaning.

> NOTE: In the text below there are several requirements that a 
>       component may set up for a container. It is understood that 
>       a container does not have to satisfy those requirements in 
>       order to be Avalon-compliant. If a component says "I require 
>       X to run" a container may reply with "I don't have any X, so 
>       I'm not running you". The requirements here are the maximum 
>       that a component may ask for, not the minimum a container must
>       deliver. However, a container should document what it is and
>       isn't capable of delivering.
> 
> The context is the interface through which the component and its
> container communicate. Each Container-Component relationship 
> involves defining a contract between the two entities. A Context 
> contract is defined by (1) an optional target class, and (2) a set 
> of context entries. Both parameters may be declared using metainfo.

suggestion: remove the last sentence above.

> 1. The first is an interface, called T below. It is required that 

suggestion: change to
"1. The first part of the context contract is an interface,"

>    the component should be able to perform the following operation:
> 
>     public void contextualize( Context context ) 
>         throws ContextException 
>     {
>         T tContext = (T) context;
>     }
>    
>    The container may choose any method to supply the component 
>    with a context instance cast-able to T.
> 
>    There is no requirement for T to extend the Context interface.
> 
>    The container must supply an implementation for all methods 
>    in the interface. This may be done via a dynamic proxy 
>    that routes calls to appropriate handlers or by any 
>    other method.

suggestion: remove the above sentence.

>    The set of methods that a container must 
>    support is defined by the standard context interfaces in 
>    Framework (currently none).

"a" container or "any" container? Regardless of the answer, if there are
no standard context interfaces I'd say there should not be a reference
to them either. So again, I suggest removing that sentence.

> 2. The second parameter is a set of entries accessible via the
>    Context.get() method and their types. The class/interface T 
>    above may also have associated metadata that specifies entries,
>    in which case these entries must be supplied by the container 
>    in addition to any entries the component itself requires.
>    Each entry requirement must specify the canonical key name, may
>    specify an alias for the canonical key and must specify the 
>    expected type of the value.

suggestion: change the above paragraph to
"2. The second part of the context contract defines the set of entries
the component can access via the Context.get() method, where an entry
consists of the key passed to get() and the expected return type (ie
the class or interface). Optionally, an alias for the key name can
be specified. The contract associated with a particular
entry is defined in the container documentation.

 NOTE: It is our intend to specify common context entries and associated
       contracts as part of the framework documentation. This step
       have not been taken yet."

cheers,

- Leo