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

[Stephen McConnell]

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




--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>