View Javadoc

1   /*
2    * Copyright 2004-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package net.sf.morph.context;
17  
18  
19  /**
20   * A context which participates in a context hierarchy (i.e. - a context that
21   * has one or more parents). Hierarchical contexts lookup property values first
22   * in the current context, and then through in any parent context(s). This
23   * allows properties in child context to override properties in parent contexts.
24   * 
25   * @author Matt Sgarlata
26   * @since Nov 21, 2004
27   */
28  public interface HierarchicalContext extends Context {
29  
30  	/**
31  	 * Gets the names of the properties which are currently defined for this
32  	 * context and all parents of this context. It will often be an O(n)
33  	 * operation to list all property names in the context, so callers should
34  	 * avoid frequent calls to this method.
35  	 * 
36  	 * @throws ContextException
37  	 *             if the properties could not be retieved for some reason
38  	 * @return the property names
39  	 */
40  	public String[] getPropertyNames() throws ContextException;
41  
42  	/**
43  	 * Retrieve the property named <code>propertyName</code> from this
44  	 * context, or if it's not found, from the nearest ancestor context.
45  	 * 
46  	 * @param propertyName
47  	 *            the name of the property to be retrieved
48  	 * @throws ContextException
49  	 *             if <code>propertyName</code> is empty or <br>
50  	 *             the property can't be accessed for some reason
51  	 */
52  	public Object get(String propertyName) throws ContextException;
53  
54  	/**
55  	 * Sets <code>propertyName</code> to <code>propertyValue</code> in the
56  	 * current context. No change will be made to the property values in any
57  	 * ancestor contexts.
58  	 * 
59  	 * @param propertyName
60  	 *            the name of the property to set
61  	 * @param propertyValue
62  	 *            the new value for the property
63  	 * @throws ContextExcception
64  	 *             if <code>propertyName</code> is empty or <br>
65  	 *             the property can't be accessed for some reason
66  	 */
67  	public void set(String propertyName, Object propertyValue)
68  		throws ContextException;
69  
70  	/**
71  	 * Retrieves this context's parent context.
72  	 * 
73  	 * @return this context's parent context
74  	 */
75  	public Context getParentContext();
76  	
77  	/**
78  	 * Sets this context's parent context.
79  	 * 
80  	 * @param context this context's parent context
81  	 */
82  	public void setParentContext(Context context);
83  }