Context


1   /* ====================================================================
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5    * reserved.
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *    "This product includes software developed by the
22   *    Apache Software Foundation (http://www.apache.org/)."
23   *    Alternately, this acknowledgment may appear in the software
24   *    itself, if and wherever such third-party acknowledgments
25   *    normally appear.
26   *
27   * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28   *    must not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation. For more
52   * information on the Apache Software Foundation, please see
53   * <http://www.apache.org/>.
54   */
55  package org.apache.avalon.framework.context;
56  
57  /**
58   * <p>
59   * The context is the interface through which the component and its
60   * container communicate.
61   * </p>
62   * 
63   * <p>
64   * <i><b>Note:</b> In the text below there are several requirements that a
65   * component may set up for a container. It is understood that a container 
66   * does not have to satisfy those requirements in order to be Avalon-compliant. 
67   * If a component says "I require X to run" a container may reply with "I don't 
68   * have any X, so I'm not running you". The requirements here are the maximum
69   * that a component may ask for, not the minimum a container must deliver. 
70   * However, a container should document what it is and isn't capable of 
71   * delivering.</i>
72   * </p>
73   * 
74   * <p>Each Container-Component relationship involves defining a contract 
75   * between the two entities. A Context contract is defined by (1) an optional 
76   * target class, and (2) a set of context entries.
77   * </p>
78   *
79   * <ol>
80   *     <li>
81   *     <p>
82   *     The optional target class is an interface, called <code>T</code> below. 
83   *     It is required that the component should be able to perform 
84   *     the following operation:
85   *     </p>
86   *     
87   *     <pre><code>    public void contextualize( Context context )
88   *         throws ContextException
89   *     {
90   *         T tContext = (T) context;
91   *     }</code></pre>
92   *     
93   *     <p>
94   *     The container may choose any method to supply the component
95   *     with a context instance cast-able to <code>T</code>.
96   *     </p>
97   *     
98   *     <p>
99   *     There is no requirement for <code>T</code> to extend the <code>Context</code>
100  *     interface.
101  *     </p>
102  *     
103  *     <p>
104  *     <i><b>Warning:</b> A component that specifies this requirement will not
105  *     be as portable as one that doesn't. Few containers
106  *     support it. It is therefore discouraged for components
107  *     to require a castable context.</i>
108  *     </p>
109  *     </li>
110  *     
111  *     <li>
112  *     <p>
113  *     The second part of the context contract defines the set
114  *     of entries the component can access via the <code>Context.get()</code>
115  *     method, where an entry consists of the key passed to <code>get()</code>
116  *     and the expected return type (the class or interface).
117  *     Optionally, an alias for the key name can be specified. The
118  *     contract associated with a particular entry is defined in the
119  *     container documentation.
120  *     </p>
121  *     
122  *     <p>
123  *     The class/interface <code>T</code> above may also have associated 
124  *     meta-info that specifies entries, in which case these entries must 
125  *     be supplied by the container in addition to any entries the
126  *     component itself requires.
127  *     </p>
128  *     
129  *     <p>
130  *     See: <a HREF="package-summary.html#meta">Context Meta-Info
131  *         Specification</a>
132  *     </p>
133  *     
134  *     <p>
135  *     Standard Avalon context entries, their keys, types and and
136  *     associated semantics are defined under the framework standard
137  *     attributes table.
138  *     </p>
139  *     
140  *     <p>
141  *     See: <a HREF="package-summary.html#attributes">
142  *         Avalon Standard Context Entries Specification</a>
143  *     </p>
144  *     
145  *     <h4>Examples, where the data is specified in a sample XML format:</h4>
146  *     
147  *     <h5>Example 1: Specification of Canonical Key</h5>
148  *     
149  *     <p>
150  *     When a component specifies:
151  *     </p>
152  *
153  *     <pre><code>    &lt;entry key="avalon:work" type="java.io.File"/&gt;</code></pre>
154  *
155  *     <p>
156  *     It should be able to do:
157  *     </p>
158  *
159  *     <pre><code>    File workDirectory = (File) context.get( "avalon:work" );</code></pre>
160  *
161  *     <p>
162  *     in order to obtain the value.
163  *     </p>
164  *     
165  *     <h5>Example 2: Specification of Canonical Key With Aliasing</h5>
166  *     
167  *     <p>
168  *     When a component specifies:
169  *     </p>
170  *     
171  *     <pre><code>    &lt;entry alias="work" key="avalon:work" type="java.io.File"/&gt;</code></pre>
172  *     
173  *     <p>
174  *     It should be able to do:
175  *     </p>
176  *     
177  *     <pre><code>    File workDirectory = (File) context.get( "work" ); </code></pre>
178  *     </li>
179  * </ol>
180  *
181  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
182  * @version CVS $Revision: 1.16 $ $Date: 2003/02/11 15:58:40 $
183  */
184 public interface Context
185 {
186     /**
187      * Retrieve an object from Context.
188      *
189      * @param key the key into context
190      * @return the object
191      * @throws ContextException if object not found. Note that this
192      *            means that either Component is asking for invalid entry
193      *            or the Container is not living up to contract.
194      */
195     Object   get( Object   key )
196         throws ContextException;
197 }
198
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags