avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosu...@apache.org
Subject cvs commit: jakarta-avalon/src/java/org/apache/avalon/framework/context package.html Context.java
Date Tue, 17 Dec 2002 12:26:50 GMT
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>    &lt;entry key="avalon:work" type="java.io.File"/&gt;</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>    &lt;entry alias="work" key="avalon:work" type="java.io.File"/&gt;</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:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message