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  import java.util.Locale;
19  
20  /**
21   * <p>Adds the capabilities of a Language and a Converter to a Context to expose
22   * additional functionality.</p>
23   * 
24   * <p>
25   * <em>You should not directly implement this interface, because additional
26   * methods may be introduced in later versions of Morph.  Instead, implement the
27   * Context interface and use the ContextDecorator to expose this interface.</em>
28   * </p>
29   * 
30   * @author Matt Sgarlata
31   * @since Dec 5, 2004
32   */
33  public interface DecoratedContext extends Context {
34  
35  	/**
36  	 * Retrieve the property named <code>propertyName</code>. The property
37  	 * named {@link Context#PROPERTY_NAMES_PROPERTY}has special symantics.
38  	 * Unless a value for this property has already been explicitly specified
39  	 * for the context, <code>context.get(PROPERTY_NAMES_PROPERTY)</code>
40  	 * should return the same result as {@link Context#getPropertyNames()}.
41  	 * 
42  	 * @param expression
43  	 *            an expression in a language that defines the property to be
44  	 *            retrieved
45  	 * @return the requested value
46  	 * @throws ContextException
47  	 *             if the expression is invalid or an error occurrs while
48  	 *             attempting to retrieve the requested information
49  	 */
50  	public Object get(String expression) throws ContextException;
51  
52  	/**
53  	 * Retrieve the information indicated by <code>expression</code> as the
54  	 * type indicated by <code>destinationClass</code>.
55  	 * 
56  	 * @param expression
57  	 *            an expression specifying which information to retrieve
58  	 * @param destinationClass
59  	 *            indicates the type that should be returned by this method
60  	 * @return the requested value
61  	 * @throws ContextException
62  	 *             if the expression is invalid or an error occurrs while
63  	 *             attempting to retrieve the requested information
64  	 */
65  	public Object get(String expression, Class destinationClass)
66  		throws ContextException;
67  
68  	/**
69  	 * Retrieve the information indicated by <code>expression</code> as the
70  	 * type indicated by <code>destinationClass</code>.
71  	 * 
72  	 * @param expression
73  	 *            an expression specifying which information to retrieve
74  	 * @param destinationClass
75  	 *            indicates the type that should be returned by this method
76  	 * @param locale
77  	 *            indicates the locale in which the conversion to type
78  	 *            <code>destinationClass</code> should be performed, if
79  	 *            applicable
80  	 * @return the requested value
81  	 * @throws ContextException
82  	 *             if the expression is invalid or an error occurrs while
83  	 *             attempting to retrieve the requested information
84  	 */
85  	public Object get(String expression, Class destinationClass, Locale locale)
86  		throws ContextException;
87  
88  	/**
89  	 * Retrieve the information indicated by <code>expression</code> as the
90  	 * type indicated by <code>destinationClass</code>.
91  	 * 
92  	 * @param expression
93  	 *            an expression specifying which information to retrieve
94  	 * @param locale
95  	 *            indicates the locale in which the conversion to type
96  	 *            <code>destinationClass</code> should be performed, if
97  	 *            applicable
98  	 * @param destinationClass
99  	 *            indicates the type that should be returned by this method
100 	 * @return the requested value
101 	 * @throws ContextException
102 	 *             if the expression is invalid or an error occurred while
103 	 *             attempting to retrieve the requested information
104 	 */
105 	public Object get(String expression, Locale locale, Class destinationClass)
106 		throws ContextException;
107 
108 	/**
109 	 * Sets the information indicated by <code>expression</code> to
110 	 * <code>value</code>, which will be automatically converted to a type
111 	 * appropriate for the given <code>expression</code>.
112 	 * 
113 	 * @param expression
114 	 *            an expression specifying which information will be modified
115 	 * @param value
116 	 *            the information to be changed
117 	 * @throws ContextException
118 	 *             if the given expression is invalid or an error occurred while
119 	 *             attempting to set the given value
120 	 */
121 	public void set(String expression, Object value) throws ContextException;
122 
123 	/**
124 	 * Sets the information indicated by <code>expression</code> on
125 	 * <code>target</code>. <code>value</code> will be automatically
126 	 * converted to a type appropriate for the given <code>expression</code>.
127 	 * 
128 	 * @param expression
129 	 *            an expression specifying which information will be modified
130 	 * @param value
131 	 *            the information to be changed
132 	 * @param locale
133 	 *            indicates the locale in which the conversion to type
134 	 *            <code>destinationClass</code> should be performed, if
135 	 *            applicable
136 	 * @throws ContextException
137 	 *             if the given expression is invalid or an error occurred while
138 	 *             attempting to set the given value
139 	 */
140 	public void set(String expression, Object value, Locale locale)
141 		throws ContextException;
142 
143 }