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

Leo Sutic wrote:

>  
>
>>From: Leo Simons [mailto:[email protected]] 
>>
>>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,"
>>    
>>
>
>"1. The optional target class 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.
>>    
>>
>
>I want to specify that this is container-specific. Unless this is
>specified, we get into abiguity:
>
>1. It is container-specific.
>
>2. It isn't, but the contracts are somewhere else.
>  
>

I agree with Leo Simon;s suggestion to remove the last paragraph above. 
 This does not conflict with the statement that implementation is 
container specific (which it is).  The paragraph in question is 
basically nothing more that a note concerning technical implementation 
which is really not part of the context contract.  However, it could be 
included in the package documentation as a implementation note.

>>>   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.
>>    
>>
>
>As above, I want it explicitly noted that there are none. The
>absence of a statement to that effect can mean:
>
>1. That there aren't any.
>
>2. That there are some, but we've just not decided to mention them
>   here.
> 
>

This is somewhat ambigouse.  We have already stated that if the 
container is going to deploy a component it must do it in accordance 
with the context contract - and the default for the context type is 
org.apache.avalon.framework.context.Context unless otherwise specificed. 
 The class Context has no entry declarations - as such it is already 
defined.  The existance of the above paragraph makes this less clear.

I.e. I would follow Leo Simons's suggestion to remove it.

>  
>
>>>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."
>>
>>    
>>
>
>"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.
>
>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.
>
>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."
>
>Common metainfo/data is about to be introduced. I see no reason
>not to include it here.
>  
>
I think we can address the concern of referencing meta while its undefined by including a reference to the Meta Specification on the Context javadoc that simply points to the a section in the context package documentation.

If we are going to mention meta then the description should be updated to replace meta-data with meta-info.  Here is an example within the appropriate package summary link.

  The context interface T above may also have associated meta-info 
  that specifies entries, in which case these entries must be supplied 
  by the container in addition to any entries the component itself 
  requires. Refer <a href="package-summary.html#meta">Context 
  Meta-Info Specification.</a>


The package documentation would contain the following:

  <body>
  <a name="meta"/>
  <h3>Meta Specification</h3>
  <p> 
  Specification of meta-information relating to context and context enties 
  is currently under discussion.
  </p>
  <h3>Implementation Notes</h3>
  <p>
  <!-- stick stuff here concerning container implementation approaches -->
  </p>
  </body>

Cheers, Steve.


-- 

Stephen J. McConnell

OSM SARL
digital products for a global economy
mailto:[email protected]
http://www.osm.net