Return-Path: Delivered-To: apmail-jakarta-avalon-cvs-archive@apache.org Received: (qmail 57239 invoked from network); 17 Dec 2002 12:27:06 -0000 Received: from exchange.sun.com (HELO nagoya.betaversion.org) (192.18.33.10) by daedalus.apache.org with SMTP; 17 Dec 2002 12:27:06 -0000 Received: (qmail 526 invoked by uid 97); 17 Dec 2002 12:28:14 -0000 Delivered-To: qmlist-jakarta-archive-avalon-cvs@jakarta.apache.org Received: (qmail 479 invoked by uid 97); 17 Dec 2002 12:28:12 -0000 Mailing-List: contact avalon-cvs-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Avalon CVS List" Reply-To: "Avalon Developers List" Delivered-To: mailing list avalon-cvs@jakarta.apache.org Received: (qmail 360 invoked by uid 98); 17 Dec 2002 12:28:08 -0000 X-Antivirus: nagoya (v4218 created Aug 14 2002) Date: 17 Dec 2002 12:26:50 -0000 Message-ID: <20021217122650.97881.qmail@icarus.apache.org> From: leosutic@apache.org To: jakarta-avalon-cvs@apache.org Subject: cvs commit: jakarta-avalon/src/java/org/apache/avalon/framework/context package.html Context.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 @@ -Interfaces and implementation of the Context model through which runtime context can be applied by a manager to a component. +

Interfaces and implementation of the Context model through which runtime context + can be applied by a manager to a component.

+ + +

Meta Specification

+

Specification of meta-information related to context and + context entries is currently under discussion.

+ + +

Standard Context Entries Specification

+

Specification of standard attribute entries related to context + is currently under discussion.

+ + 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. - * - *

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.

- * - *

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.

- * - *

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.)

- * - *

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;

+ *

+ * The context is the interface through which the component and its + * container communicate. + *

+ * + *

+ * 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. + *

+ * + *

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. World Context / Per-Application context: This describes application - * wide settings/context. An example may be the working directory of the - * application.
    2. - * - *
  2. Person Context / Per-Component context: This contains context - * information specific to the component. An example may be the name of - * the component.
    3. - * - *
  3. 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.
    4. - * - *
  4. 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.
    5. - * + *
  5. + *

    + * 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. + *

    + *
    6. + * + *
  6. + *

    + * 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: Context Meta-Info + * Specification + *

    + * + *

    + * Standard Avalon context entries, their keys, types and and + * associated semantics are defined under the framework standard + * attributes table. + *

    + * + *

    + * See: + * Avalon Standard Context Entries Specification + *

    + * + *

    Examples, where the data is specified in a sample XML format:

    + * + *
    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" );
    + *
    7. *
- * - *

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).

- * - *

(4) is usually passed into a service() style method as parameters. Often it will - * named something like RequestObject. So you may have something like:

- * - * 
  - * void doMagic( int param1, int param2, Context otherParamsInHere );
  - *
- * - *

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).

* * @author Avalon Development Team */ -- To unsubscribe, e-mail: For additional commands, e-mail: