1 /*
2 * Copyright 2002-2013 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of 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,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.expression;
18
19 import org.springframework.core.convert.TypeDescriptor;
20
21 /**
22 * An expression capable of evaluating itself against context objects. Encapsulates the
23 * details of a previously parsed expression string. Provides a common abstraction for
24 * expression evaluation independent of any language like OGNL or the Unified EL.
25 *
26 * @author Keith Donald
27 * @author Andy Clement
28 * @since 3.0
29 */
30 public interface Expression {
31
32 /**
33 * Evaluate this expression in the default standard context.
34 * @return the evaluation result
35 * @throws EvaluationException if there is a problem during evaluation
36 */
37 Object getValue() throws EvaluationException;
38
39 /**
40 * Evaluate this expression against the specified root object
41 * @param rootObject the root object against which properties/etc will be resolved
42 * @return the evaluation result
43 * @throws EvaluationException if there is a problem during evaluation
44 */
45 Object getValue(Object rootObject) throws EvaluationException;
46
47 /**
48 * Evaluate the expression in the default context. If the result of the evaluation does not match (and
49 * cannot be converted to) the expected result type then an exception will be returned.
50 * @param desiredResultType the class the caller would like the result to be
51 * @return the evaluation result
52 * @throws EvaluationException if there is a problem during evaluation
53 */
54 <T> T getValue(Class<T> desiredResultType) throws EvaluationException;
55
56 /**
57 * Evaluate the expression in the default context against the specified root object. If the
58 * result of the evaluation does not match (and cannot be converted to) the expected result type
59 * then an exception will be returned.
60 * @param rootObject the root object against which properties/etc will be resolved
61 * @param desiredResultType the class the caller would like the result to be
62 * @return the evaluation result
63 * @throws EvaluationException if there is a problem during evaluation
64 */
65 <T> T getValue(Object rootObject, Class<T> desiredResultType) throws EvaluationException;
66
67 /**
68 * Evaluate this expression in the provided context and return the result of evaluation.
69 * @param context the context in which to evaluate the expression
70 * @return the evaluation result
71 * @throws EvaluationException if there is a problem during evaluation
72 */
73 Object getValue(EvaluationContext context) throws EvaluationException;
74
75 /**
76 * Evaluate this expression in the provided context and return the result of evaluation, but use
77 * the supplied root context as an override for any default root object specified in the context.
78 * @param context the context in which to evaluate the expression
79 * @param rootObject the root object against which properties/etc will be resolved
80 * @return the evaluation result
81 * @throws EvaluationException if there is a problem during evaluation
82 */
83 Object getValue(EvaluationContext context, Object rootObject) throws EvaluationException;
84
85 /**
86 * Evaluate the expression in a specified context which can resolve references to properties, methods, types, etc -
87 * the type of the evaluation result is expected to be of a particular class and an exception will be thrown if it
88 * is not and cannot be converted to that type.
89 * @param context the context in which to evaluate the expression
90 * @param desiredResultType the class the caller would like the result to be
91 * @return the evaluation result
92 * @throws EvaluationException if there is a problem during evaluation
93 */
94 <T> T getValue(EvaluationContext context, Class<T> desiredResultType) throws EvaluationException;
95
96 /**
97 * Evaluate the expression in a specified context which can resolve references to properties, methods, types, etc -
98 * the type of the evaluation result is expected to be of a particular class and an exception will be thrown if it
99 * is not and cannot be converted to that type. The supplied root object overrides any default specified on the
100 * supplied context.
101 * @param context the context in which to evaluate the expression
102 * @param rootObject the root object against which properties/etc will be resolved
103 * @param desiredResultType the class the caller would like the result to be
104 * @return the evaluation result
105 * @throws EvaluationException if there is a problem during evaluation
106 */
107 <T> T getValue(EvaluationContext context, Object rootObject, Class<T> desiredResultType) throws EvaluationException;
108
109 /**
110 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
111 * method using the default context.
112 * @return the most general type of value that can be set on this context
113 * @throws EvaluationException if there is a problem determining the type
114 */
115 Class<?> getValueType() throws EvaluationException;
116
117 /**
118 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
119 * method using the default context.
120 * @param rootObject the root object against which to evaluate the expression
121 * @return the most general type of value that can be set on this context
122 * @throws EvaluationException if there is a problem determining the type
123 */
124 Class<?> getValueType(Object rootObject) throws EvaluationException;
125
126 /**
127 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
128 * method for the given context.
129 * @param context the context in which to evaluate the expression
130 * @return the most general type of value that can be set on this context
131 * @throws EvaluationException if there is a problem determining the type
132 */
133 Class<?> getValueType(EvaluationContext context) throws EvaluationException;
134
135 /**
136 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
137 * method for the given context. The supplied root object overrides any specified in the context.
138 * @param context the context in which to evaluate the expression
139 * @param rootObject the root object against which to evaluate the expression
140 * @return the most general type of value that can be set on this context
141 * @throws EvaluationException if there is a problem determining the type
142 */
143 Class<?> getValueType(EvaluationContext context, Object rootObject) throws EvaluationException;
144
145 /**
146 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
147 * method using the default context.
148 * @return a type descriptor for the most general type of value that can be set on this context
149 * @throws EvaluationException if there is a problem determining the type
150 */
151 TypeDescriptor getValueTypeDescriptor() throws EvaluationException;
152
153 /**
154 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
155 * method using the default context.
156 * @param rootObject the root object against which to evaluate the expression
157 * @return a type descriptor for the most general type of value that can be set on this context
158 * @throws EvaluationException if there is a problem determining the type
159 */
160 TypeDescriptor getValueTypeDescriptor(Object rootObject) throws EvaluationException;
161
162 /**
163 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)}
164 * method for the given context.
165 * @param context the context in which to evaluate the expression
166 * @return a type descriptor for the most general type of value that can be set on this context
167 * @throws EvaluationException if there is a problem determining the type
168 */
169 TypeDescriptor getValueTypeDescriptor(EvaluationContext context) throws EvaluationException;
170
171 /**
172 * Returns the most general type that can be passed to the {@link #setValue(EvaluationContext, Object)} method for
173 * the given context. The supplied root object overrides any specified in the context.
174 * @param context the context in which to evaluate the expression
175 * @param rootObject the root object against which to evaluate the expression
176 * @return a type descriptor for the most general type of value that can be set on this context
177 * @throws EvaluationException if there is a problem determining the type
178 */
179 TypeDescriptor getValueTypeDescriptor(EvaluationContext context, Object rootObject) throws EvaluationException;
180
181 /**
182 * Determine if an expression can be written to, i.e. setValue() can be called.
183 * @param context the context in which the expression should be checked
184 * @return true if the expression is writable
185 * @throws EvaluationException if there is a problem determining if it is writable
186 */
187 boolean isWritable(EvaluationContext context) throws EvaluationException;
188
189 /**
190 * Determine if an expression can be written to, i.e. setValue() can be called.
191 * The supplied root object overrides any specified in the context.
192 * @param context the context in which the expression should be checked
193 * @param rootObject the root object against which to evaluate the expression
194 * @return true if the expression is writable
195 * @throws EvaluationException if there is a problem determining if it is writable
196 */
197 boolean isWritable(EvaluationContext context, Object rootObject) throws EvaluationException;
198
199 /**
200 * Determine if an expression can be written to, i.e. setValue() can be called.
201 * @param rootObject the root object against which to evaluate the expression
202 * @return true if the expression is writable
203 * @throws EvaluationException if there is a problem determining if it is writable
204 */
205 boolean isWritable(Object rootObject) throws EvaluationException;
206
207 /**
208 * Set this expression in the provided context to the value provided.
209 *
210 * @param context the context in which to set the value of the expression
211 * @param value the new value
212 * @throws EvaluationException if there is a problem during evaluation
213 */
214 void setValue(EvaluationContext context, Object value) throws EvaluationException;
215
216 /**
217 * Set this expression in the provided context to the value provided.
218 * @param rootObject the root object against which to evaluate the expression
219 * @param value the new value
220 * @throws EvaluationException if there is a problem during evaluation
221 */
222 void setValue(Object rootObject, Object value) throws EvaluationException;
223
224 /**
225 * Set this expression in the provided context to the value provided.
226 * The supplied root object overrides any specified in the context.
227 * @param context the context in which to set the value of the expression
228 * @param rootObject the root object against which to evaluate the expression
229 * @param value the new value
230 * @throws EvaluationException if there is a problem during evaluation
231 */
232 void setValue(EvaluationContext context, Object rootObject, Object value) throws EvaluationException;
233
234 /**
235 * Returns the original string used to create this expression, unmodified.
236 * @return the original expression string
237 */
238 String getExpressionString();
239
240 }