Attached is a document I worked up a couple of hours ago containing a consilidation of this in a non-email document.
Based on the last set of emails - it looks like only the first part if relevant - but I figured it would be helpful to post anyway.
Chers, Steve.
Context ------- 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 interface derived from Context, and (2) a set of context entries. Both parameters may be declared using metainfo.
1. Context target interface
A container shall ensure that a context object supplied
to a component shall be castable to a target interface (T).
The default target interface is Context. A target interface
must be derived from the Context interface.
Usage:
public void contextualize( Context context )
throws ContextException
{
T tContext = (T) context;
}
2. The second parameter is a set of entries accessible via the
Context.get( key ) method and their types. The 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 name that the canonical key should be
remapped from, and expected type of the keyed value.
Example XML Description
-----------------------
For an example, where the data is specified in XML:
Example 1:
The following example declares that the context instance supplied
to a component shall implement the Context interface and shall
contain two keyed context entries. The first entry shall be of
the default type java.lang.String and the second entry shall be
of the type java.io.File.
<context>
<entry key="urn:demo:name"/>
<entry key="urn:avalon:home.dir" type="java.io.File"/>
</context>
Example 2:
The following example declares that the context instance supplied
to a component shall implement a BlockContext interface and shall
contain an additional keyed context entry.
<context type="org.apache.avalon.phoneix.BlockContext">
<entry key="urn:demo:work" alais="urn:avalon:work.dir"/>
</context>
Example 3:
The following example declares context crieria containing an
optional context entry. A container is not required to provide
a context entry marked as optional.
<context>
<entry key="urn:demo:name" optional="true"/>
</context>
Example 4:
The following example declares context criteria that references
a versioned context interface specification. A container shall
ensure that the supplied context instance implements the
StandardContext interface and shall ensure that the context
implementation is consitent with the requested version.
<context type="org.demo.StandardContext:1.2" />
Standard Context Key Entries
----------------------------
All standard context key entries shall conform to URN naming
conventions specificed under RFC 2141 where the format of a
URN is "urn:" <NID> ":" <NSS>. NID is Namespace IDentifier,
and NSS is Namspace Specific String. The NID applied to
standard context keys is the string "avalon".
The following table lists the Namespace Specific String (NSS)
keys used within the "avalon" NID.
NID Description
name The name of the component.
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 The name of the partition withing which the
component is executing.
application.name The name of the application that the
component is a part of.
home.dir The location in which the component to store
persistent data relevent to the component. A
container shall ensure that the value of the
home directory is equivalent across mutliple
deployments.
work.dir This directory in which to store temporary or
working information. A container shall be
responsible for the disposal of the directory
on disposal of the component.
Recommended form for Context Meta Information in XML
----------------------------------------------------
Context criteria covering context type and entry criteria may
be expressed in XML. The following description is the recommended
structure of context criteria.
The "context" element:
The "context" element shall declare a context type as an
attribute, and may container context multiple "entry"
elements.
Defintion:
<!ELEMENT context (entry*) >
<!ATTLIST context type CDATA #IMPLIED >
Attributes:
Attribute Description
--------- -----------
type An interface, or versioned equivalent
in the form "classname[:version]" derived from
the Context interface.
Structure:
Element Occurance Description
------- --------- -----------
entry n Declaration of a context entry.
The "entry" element:
The entry element defines a single context entry accessible
throgh the Context.get( key ) method.
Defintion:
<!ELEMENT entry EMPTY >
<!ATTLIST entry
key CDATA #REQUIRED
type CDATA #REQUIRED
optional CDATA #IMPLIED
>
Attributes:
Attribute Value
--------- -----
key A URN that uniquely identied the entry within the
scope of a context instance.
type A classname, interface, or versioned equivalent
in the form "classname[:version]".
Examples:
java.io.File
org.apache.examples.ComponentClassLoader:1.2
optional A value of "true" or "false" indicating if the
context entry is optional or required. The
default value is "false".
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
