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.
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.
-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:
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).
Here is a revised version of the above:
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;
}
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;
}
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.
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.
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.
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"/>
Here is suggested replacement:
<entry key="urn:avalon:work" type="java.io.File"/>
<entry key="work" alias="urn:avalon:work" type="java.io.File"/>
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.
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.
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
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
