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   * A context is an object that can be passed between tiers of an application
20   * without exposing the APIs that are particular to any given tier. For example,
21   * in a web application the information submitted by a user in an HttpRequest
22   * object could be exposed to a business object through the Context interface.
23   * This leaves objects in the business tier independent of the servlet API and
24   * thus testable outside a Servlet container.
25   * 
26   * @author Matt Sgarlata
27   * @since Nov 19, 2004
28   */
29  public interface Context {
30  
31  	/**
32  	 * Gets the names of the properties which are currently defined for this
33  	 * context. It will often be an O(n) operation to list all property names in
34  	 * the context, so callers should avoid frequent calls to this method. This
35  	 * method should always include {@link Context#PROPERTY_NAMES_PROPERTY} as
36  	 * one of the properties in the returned array.
37  	 * 
38  	 * @return the property names
39  	 * @throws ContextException
40  	 *             if the properties could not be retieved for some reason
41  	 */
42  	public String[] getPropertyNames() throws ContextException;
43  
44  	/**
45  	 * Retrieve the property named <code>propertyName</code>. The property
46  	 * {@link Context#PROPERTY_NAMES_PROPERTY} has special symantics. Unless a
47  	 * value for this property has already been explicitly specified for the
48  	 * context, <code>context.get(PROPERTY_NAMES_PROPERTY)</code> will return
49  	 * the same result as {@link Context#getPropertyNames()}.
50  	 * 
51  	 * @param propertyName
52  	 *            the name of the property to be retrieved, if the property has
53  	 *            been defined or <br>
54  	 *            <code>null</code>, if the property is not defined
55  	 * @return the value of the property
56  	 * @throws ContextException
57  	 *             if <code>propertyName</code> is empty or <br>
58  	 *             an error occurrs when accessing the property
59  	 */
60  	public Object get(String propertyName) throws ContextException;
61  
62  	/**
63  	 * Sets <code>propertyName</code> to <code>propertyValue</code>.
64  	 * 
65  	 * @param propertyName
66  	 *            the name of the property to set
67  	 * @param propertyValue
68  	 *            the new value for the property
69  	 * @throws ContextException
70  	 *             if <code>propertyName</code> is empty or <br>
71  	 *             the property can't be set for some reason
72  	 */
73  	public void set(String propertyName, Object propertyValue)
74  		throws ContextException;
75  }