You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avalon.apache.org by Leo Sutic <le...@inspireinfrastructure.com> on 2002/12/13 17:06:02 UTC
[Avalon4:PROPOSAL] Context Consensus (version 4)
All,
after even more feedback from Leo Simons and Stephen, I have cut
out some redundant parts. The note about dynamic proxies have been
completely removed from this proposal - I intend to submit it as
a separate proposal. As it was now it wasn't enough to make any
sense to a reader not familiar with it, but just enough to confuse
the hell out of that person. I still think an implementation note
is of value, as many people have objected to the castable context
on the grounds that it would appear that the container should have
to spontaneously sprout new code on demand, and therefore it may
be valuable to give an overview of *one* way of doing it. But those
docs can and should be voted on separately.
As the proposal now has changes to the package summary in addition
to changes to the Context docs, I have split it in two parts.
-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.html#meta">Context Meta-Info
Specification</a>
NOTE: It is our intent to specify common context entries and
associated contracts as part of the Framework documentation.
This step has not been taken yet.
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.
-oOo-
/LS
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Avalon4:PROPOSAL] Context Consensus (version 4)
Posted by Leo Sutic <le...@inspireinfrastructure.com>.
> From: Stephen McConnell [mailto:mcconnell@apache.org]
>
> Suggestion - replace "package.html#meta" with "package-summary#meta"
> (otherise it won't work when you convert to javadoc).
Seems like a worthwhile change...
> > NOTE: It is our intent to specify common context entries and
> > associated contracts as part of the Framework documentation.
> > This step has not been taken yet.
> >
>
> I would replace the above note with the following:
>
> 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>
>
>
> Plus:
>
> <a name="attributes"/>
> Standard Avalon Context Entries Specification
> ---------------------------------------------
> Specification of standard attribute entries related to
> context and is currently under discussion.
>
Incorporated.
/LS
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [Avalon4:PROPOSAL] Context Consensus (version 4)
Posted by Stephen McConnell <mc...@apache.org>.
It's looking good!
A couple of improvement are suggested in-line. Nothing that changes
content, just some structural adjustments ... Steve can hear Leo
groaning :-)
Leo Sutic wrote:
>All,
>
>after even more feedback from Leo Simons and Stephen, I have cut
>out some redundant parts. The note about dynamic proxies have been
>completely removed from this proposal - I intend to submit it as
>a separate proposal. As it was now it wasn't enough to make any
>sense to a reader not familiar with it, but just enough to confuse
>the hell out of that person. I still think an implementation note
>is of value, as many people have objected to the castable context
>on the grounds that it would appear that the container should have
>to spontaneously sprout new code on demand, and therefore it may
>be valuable to give an overview of *one* way of doing it. But those
>docs can and should be voted on separately.
>
>As the proposal now has changes to the package summary in addition
>to changes to the Context docs, I have split it in two parts.
>
> -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.html#meta">Context Meta-Info
> Specification</a>
>
Suggestion - replace "package.html#meta" with "package-summary#meta"
(otherise it won't work when you convert to javadoc).
>
> NOTE: It is our intent to specify common context entries and
> associated contracts as part of the Framework documentation.
> This step has not been taken yet.
>
I would replace the above note with the following:
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.
>
>
Plus:
<a name="attributes"/>
Standard Avalon Context Entries Specification
---------------------------------------------
Specification of standard attribute entries related to context and
is currently under discussion.
Cheers, Steve.
--
Stephen J. McConnell
OSM SARL
digital products for a global economy
mailto:mcconnell@osm.net
http://www.osm.net
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>