[Avalon4:VOTE] Context Consensus

Vote remains open to Tuesday, 1200 CET.

                             -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-summary.html#meta">Context Meta-Info
         Specification</a>

    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.

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

                             -oOo-

Here's my +1.

/LS