After feedback from Paul and Stephen, I have made some edits to
the text. Most edits are cuts:
+ The type being casted-to is restricted to an interface.
+ Examples of entry specification updated.
+ Removed the common key list as there is no consensus on
it.
-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 (1) an optional target class, and (2) a set
of context entries. Both parameters may be declared using metainfo.
1. The first 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.
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).
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 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.
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" );
/LS
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
