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.
-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:
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;
}
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.
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"/>
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.
The current list of canonical keys are (taken from
http://jakarta.apache.org/avalon/excalibur/info/context.html):
component.name java.lang.String
This entry defines the name of the component.
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.
partition.name java.lang.String
This entry defines the name of the partition.
application.name java.lang.String
This entry defines the name of the application.
component.home java.io.File
The location in which the component to store persistent data
relevent to the component.
component.work java.io.File
This directory in which to store temporary or working
information. It may not persist over restarts of the component.
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.
/LS
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
