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

It's looking good!

A couple of improvement are suggested in-line. Nothing that changes 
content, just some structural adjustments ... Steve can hear Leo 
groaning :-)


Leo Sutic wrote:

>All,
>
>after even more feedback from Leo Simons and Stephen, I have cut
>out some redundant parts. The note about dynamic proxies have been
>completely removed from this proposal - I intend to submit it as
>a separate proposal. As it was now it wasn't enough to make any
>sense to a reader not familiar with it, but just enough to confuse
>the hell out of that person. I still think an implementation note
>is of value, as many people have objected to the castable context
>on the grounds that it would appear that the container should have
>to spontaneously sprout new code on demand, and therefore it may
>be valuable to give an overview of *one* way of doing it. But those
>docs can and should be voted on separately.
>
>As the proposal now has changes to the package summary in addition
>to changes to the Context docs, I have split it in two parts.
>
>                            -oOo-
>
>PROPOSAL PART 1/2
>
>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 (1) an optional target class, and (2) a set 
>of context entries. 
>
>1. The optional target class is an interface, 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;
>    }
>   
>   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.
>
>   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.
>
>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 (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 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. 
>
>   See: <a href="package.html#meta">Context Meta-Info 
>        Specification</a>
>

Suggestion - replace "package.html#meta" with "package-summary#meta" 
(otherise it won't work when you convert to javadoc).

>
>   NOTE: It is our intent to specify common context entries and 
>         associated contracts as part of the Framework documentation.
>         This step has not been taken yet.
>

I would replace the above note with the following:

     Standard Avalon context entries, their keys, types and and
     associated semantics are defined under the framework standard
     attributes table.

     See: <a href="package-summary.html#attributes">
     Avalon Standard Context Entries Specification</a>

>
>
>   Examples, where the data is specified in a sample XML format:
>
>   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.
>
>   Example 1: Specification of Canonical Key
>
>   When a component specifies:
>
>    <entry key="avalon:work" type="java.io.File"/>
>
>   It should be able to do:
>
>    File workDirectory = (File) context.get( "avalon:work" );
>
>   in order to obtain the value.
>
>
>   Example 2: Specification of Canonical Key With Aliasing
>
>   When a component specifies:
>
>    <entry alias="work" key="avalon:work" type="java.io.File"/>
>
>   It should be able to do:
>
>    File workDirectory = (File) context.get( "work" );
>
>                            -oOo-
>
>PROPOSAL PART 2/2
>
>The following text should (after being HTML-ized) be added to the
>package summary for org.apache.avalon.framework.context:
>
><a name="meta"/>
>Meta Specification
>------------------
>Specification of meta-information related to context and
>context entries is currently under discussion.
>  
>

Plus:

<a name="attributes"/>
Standard Avalon Context Entries Specification
---------------------------------------------
Specification of standard attribute entries related to context and
is currently under discussion.

Cheers, Steve.

-- 

Stephen J. McConnell

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