leosutic 2002/12/17 04:26:50
Modified: src/java/org/apache/avalon/framework/context package.html
Context.java
Log:
Changes and definition of the context contract. Changes involve Javadocs only
(no change in the interface code).
Revision Changes Path
1.2 +14 -1
jakarta-avalon/src/java/org/apache/avalon/framework/context/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/context/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 12 Feb 2002 05:36:58 -0000 1.1
+++ package.html 17 Dec 2002 12:26:50 -0000 1.2
@@ -1,3 +1,16 @@
<body>
-Interfaces and implementation of the Context model through which runtime
context can be applied by a manager to a component.
+ <p>Interfaces and implementation of the Context model through which
runtime context
+ can be applied by a manager to a component. </p>
+
+ <a name="meta"/>
+ <h3>Meta Specification</h3>
+ <p>Specification of meta-information related to context and
+ context entries is currently under discussion.</p>
+
+ <a name="attributes"/>
+ <h3>Standard Context Entries Specification</h3>
+ <p>Specification of standard attribute entries related to context
+ is currently under discussion.</p>
+
+
</body>
1.13 +119 -55
jakarta-avalon/src/java/org/apache/avalon/framework/context/Context.java
Index: Context.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/context/Context.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- Context.java 23 Nov 2002 08:58:59 -0000 1.12
+++ Context.java 17 Dec 2002 12:26:50 -0000 1.13
@@ -55,64 +55,128 @@
package org.apache.avalon.framework.context;
/**
- * The context is the interface through which the Component
- * and it's Container communicate.
- *
- * <p>Each Container-Component relationship will also involve defining
- * a contract between two entities. This contract will specify the
- * services, settings and information that is supplied by the
- * Container to the Component.</p>
- *
- * <p>The values placed in the context are runtime values that can
- * only be provided by the container. The Context should <b>NOT</b> be
- * used to retrieve configuration values or services that can be provided
- * by peer components.</p>
- *
- * <p>This relationship should be documented in a well known place.
- * It is sometimes convenient to derive from Context to provide
- * a particular style of Context for your Component-Container
- * relationship. The documentation for required entries in context
- * can then be defined there. (examples include MailetContext,
- * BlockContext etc.)</p>
- *
- * <p>There are traditionally four differet types of Context that may be
- * used in a system. These ideas are partially derived from linguistic theory
- * and partially from tradition computer science;</p>
+ * <p>
+ * The context is the interface through which the component and its
+ * container communicate.
+ * </p>
+ *
+ * <p>
+ * <i><b>Note:</b> 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.</i>
+ * </p>
+ *
+ * <p>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.
+ * </p>
*
* <ol>
- * <li>World Context / Per-Application context: This describes application
- * wide settings/context. An example may be the working directory of the
- * application.</li>
- *
- * <li>Person Context / Per-Component context: This contains context
- * information specific to the component. An example may be the name of
- * the component.</li>
- *
- * <li>Conversation Context / Per-Session context: This contains context
- * information specific to the component. An example may be the IP address
- * of the entity who you are talking to.</li>
- *
- * <li>Speach Act Context / Per-Request context: This contains information
- * about a specific request in component. Example may include the parameter
- * submitted to a particular web form or whatever.</li>
- *
+ * <li>
+ * <p>
+ * The optional target class is an interface, called <code>T</code>
below.
+ * It is required that the component should be able to perform
+ * the following operation:
+ * </p>
+ *
+ * <pre><code> public void contextualize( Context context )
+ * throws ContextException
+ * {
+ * T tContext = (T) context;
+ * }</code></pre>
+ *
+ * <p>
+ * The container may choose any method to supply the component
+ * with a context instance cast-able to <code>T</code>.
+ * </p>
+ *
+ * <p>
+ * There is no requirement for <code>T</code> to extend the
<code>Context</code>
+ * interface.
+ * </p>
+ *
+ * <p>
+ * <i><b>Warning:</b> 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.</i>
+ * </p>
+ * </li>
+ *
+ * <li>
+ * <p>
+ * The second part of the context contract defines the set
+ * of entries the component can access via the <code>Context.get()</code>
+ * method, where an entry consists of the key passed to
<code>get()</code>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * The class/interface <code>T</code> 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.
+ * </p>
+ *
+ * <p>
+ * See: <a href="package-summary.html#meta">Context Meta-Info
+ * Specification</a>
+ * </p>
+ *
+ * <p>
+ * Standard Avalon context entries, their keys, types and and
+ * associated semantics are defined under the framework standard
+ * attributes table.
+ * </p>
+ *
+ * <p>
+ * See: <a href="package-summary.html#attributes">
+ * Avalon Standard Context Entries Specification</a>
+ * </p>
+ *
+ * <h4>Examples, where the data is specified in a sample XML format:</h4>
+ *
+ * <h5>Example 1: Specification of Canonical Key</h5>
+ *
+ * <p>
+ * When a component specifies:
+ * </p>
+ *
+ * <pre><code> <entry key="avalon:work"
type="java.io.File"/></code></pre>
+ *
+ * <p>
+ * It should be able to do:
+ * </p>
+ *
+ * <pre><code> File workDirectory = (File) context.get( "avalon:work"
);</code></pre>
+ *
+ * <p>
+ * in order to obtain the value.
+ * </p>
+ *
+ * <h5>Example 2: Specification of Canonical Key With Aliasing</h5>
+ *
+ * <p>
+ * When a component specifies:
+ * </p>
+ *
+ * <pre><code> <entry alias="work" key="avalon:work"
type="java.io.File"/></code></pre>
+ *
+ * <p>
+ * It should be able to do:
+ * </p>
+ *
+ * <pre><code> File workDirectory = (File) context.get( "work" );
</code></pre>
+ * </li>
* </ol>
- *
- * <p>When we implement this (1) and (2) are generally merged into one
interface.
- * For instance in the Pheonix Application Server there is a BlockContext.
Part
- * of the BlockContext consists of two methods. One is getHomeDirectory()
and that
- * belongs to (1) while the other is getName() which belongs to (2).</p>
- *
- * <p>(4) is usually passed into a service() style method as parameters.
Often it will
- * named something like RequestObject. So you may have something like:</p>
- *
- * <pre>
- * void doMagic( int param1, int param2, Context otherParamsInHere );
- * </pre>
- *
- * <p>When (3) is needed in the system it is usually also passed into the a
serice method
- * method, along with the request context (4). Alternatively it is made
available via the
- * context representing (4).</p>
*
* @author <a href="mailto:avalon-dev@jakarta.apache.org";>Avalon Development
Team</a>
*/
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
