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> <entry key="avalon:work" type="java.io.File"/></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> <entry alias="work" key="avalon:work" type="java.io.File"/></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