org.apache.avalon.framework.context
Interface Context

All Known Implementing Classes:

DefaultContext

public interface Context

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

Version:

$Id: Context.java 30977 2004-07-30 08:57:54Z niclas $

Author:

Avalon Development Team

Method Summary

java.lang.Object

get(java.lang.Object key) Retrieve an object from Context.

Method Detail

get

public java.lang.Object get(java.lang.Object key)
                     throws ContextException

Retrieve an object from Context.

Parameters:

key - the key into context

Returns:

the object

Throws:

ContextException - if object not found. Note that this means that either Component is asking for invalid entry or the Container is not living up to contract.