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

Leo Sutic wrote:

>All,
>
>I hope I have incorporated all comments. Here's the latest draft
>of the proposal. I'd like to go for a vote on this next Tuesday,
>and I would appreciate if anyone not satisfied with it could say
>so now, so the concerns can be addressed while it is still a 
>[PROPOSAL] and not a [VOTE]. I know that the proposal as it
>stands is less-than-optimal for everyone, but it is my gut
>feeling that it is also at least acceptable to everyone, which
>is why I'm going forward with it.
>

Leo:

More notes in-line.

>
>                           -oOo-
>
>Proposal: The following text should (after being HTML-ized) replace
>the current documentation for the Context interface:
>
>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 two parameters, both of which are requirements the component
>set up for the container in its metadata:
>

I making the assumption here that the two entities refered to in the 
above paragraph are (a) context type, and (b) context entries. While I 
can read on to confirm this, I think we can improve the wording so that 
this is clear in the summary.

Here is a suggested replacement of the above paragraph:

   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.

There are two changes I have made - firstly the explicit statement of the two parameters that define the context contract, and secondly, stating that this information may be declared in metainfo (not metadata).


>
>1. The first is an interface or a class, called T below. It is 
>   required that the component should be able to perform the 
>   following operation:
>
>    public void contextualize( Context context ) 
>        throws ContextException 
>    {
>        T tContext = (T) context;
>    }
>

Here is a revised version of the above:

   1. Context target class or interface

      A container shall ensure that a context object supplied 
      to a component shall be castable to a target class or 
      interface (T).  The default target class is Context. A 
      target class must be derived from or implement the 
      Context interface.
      
      Usage:

      public void contextualize( Context context ) 
        throws ContextException 
      {
         T tContext = (T) context;
      }


>
>   This case has two variants:
>
>    a. T is an interface. In this case, the container may choose
>       any method to supply the component with a context instance
>       cast-able to T.
>
>       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. The set of methods that a container must 
>       support is defined by the standard context interfaces in 
>       Framework (currently none).
>
>    b. T is a class. In this case, the class must be instantiated 
>       with the T(Map,Context) constructor, and the instance 
>       then be passed to the component's contextualize method.
>
>   WARNING: A component that specifies this requirement will not
>            be as portable as one that doesn't. Few containers 
>            support it. It is therefore discouraged for components 
>            to require a castable context.
>

I think all of the text related to the "two variants" should be removed. 
 Point (a) is simply saying that this is a container implemetation issue 
and that the object must respect the interface.  Both of these are 
implicit if (a) is removed.  Point (b) is convention that can be used by 
a container to create a context implementation - it has nothing to do 
with the T parameter as far as the context interface is concerned. 
 Secondly, it mixes the notion of T as a cast criteria with the notion 
of T as a directive for context creation.  T as a criteria is 
appropriate within the scope of metainfo.  T as a directive is 
appropriate within the scope of metadata. I don't think we should 
documeting directive under Context interface specification as directives 
are related to implemetation, not contract.  However, I do think we can 
provide a link to this sort of information - for example, it would be 
appropriate to include this under the DefaultContext implementation spec 
or as part of a metadata for context specification included in the 
context package documentation.

>
>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 a name that the canonical key should be remapped to, 
>   and must specify the expected type of the value:
>
>   For an example, where the data is specified in XML:
>
>    <entry intent="avalon:work" type="java.io.File"/>
>
>    <entry key="work" intent="avalon:work" type="java.io.File"/>
>

No too happy with the example XML.  For me "intent" does not convey the 
semntics here.  I would suggest "alias".  Secondly, I think the example 
should use full URN naming convensions. Thirdly, the example shows a 
entry without a key which does not compute from my understanding of the 
example.

Here is suggested replacement:


    <entry key="urn:avalon:work" type="java.io.File"/>

    <entry key="work" alias="urn:avalon:work" type="java.io.File"/>

>
>   NOTE: The proposal does not cover the DTD, nor does it require 
>         that the entries are defined in XML. However, it does 
>         require that the above three things *can* be specified.
>

I think we are so close to being able to close the defintion of 
<context/> that it would be worth doing this as part of the proposal. 
 The two thing not addressed in the above. One is the "optional" 
attribute that is available in both the meta and info packages, and the 
second is semantics that can be applied to the "type" attibute value 
concerning interface/class version.

E.g.:

    <entry key="urn:avalon:classloader" type="ComponentClassLoader:1.2"/>

Doing a DTD for <context/> allows us to be precise about the meaning of "type", "alias", "key", and "optional".


>
>   The current list of canonical keys are (taken from
>   http://jakarta.apache.org/avalon/excalibur/info/context.html):
>

This needs to be normalized with the context keys defined under:

  http://jakarta.apache.org/avalon/excalibur/container/attributes.html

>
>   component.name         java.lang.String  
>   This entry defines the name of the component.  
>

Suggestion:

     urn:avalon:name

>
>   component.classloader  java.lang.ClassLoader  
>   The classloader via which the component was loaded. May differ 
>   from the ClassLoader returned by getClass().getClassLoader() if 
>   the component was loaded from parent classloader.  
>

Suggestion:

     urn:avalon:classloader
 

>
>   partition.name         java.lang.String  
>   This entry defines the name of the partition.  
>

Suggestion:

     urn:avalon:partition.name

>
>   application.name       java.lang.String  
>   This entry defines the name of the application.  
>
Suggestion:

     urn:avalon:application.name

>
>   component.home         java.io.File  
>   The location in which the component to store persistent data 
>   relevent to the component.  
>
Suggestion:

     urn:avalon:home

or:

     urn:avalon:home.directory

>
>
>   component.work         java.io.File  
>   This directory in which to store temporary or working 
>   information. It may not persist over restarts of the component.
>

Suggestion:

     urn:avalon:work

or:

     urn:avalon:work.directory

>   
>   The values placed in the context are runtime values that 
>   can only be provided by the container. The Context should 
>   NOT be used to retrieve configuration values or services 
>   that can be provided by peer components.
>

I think the last sentense should be removed.  If a container provides a 
classloader that is a full component - its in conflict with the notion 
that a  standard avalon context entry included classloader.  I do not 
think we should be introducing statements that are implemetation 
concerns.  If I supply a context entry value that meets the entry 
contract, the client should not know or be concerned about the 
mechansisms used to construct that value.  The "configuration values" 
and "services provided by peers" are mechanisms - and that's orthoginal 
to the contract.

Cheers, Steve.

-- 

Stephen J. McConnell

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