Context
Date: 2016-02-08

org.apache.avalon.framework.context

## Interface Context

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

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `get(java.lang.Object key)` Retrieve an object from Context.

- - ### Method Detail

    - #### get

          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.