001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.expression;
018
019import org.springframework.core.convert.TypeDescriptor;
020import org.springframework.lang.Nullable;
021
022/**
023 * An expression capable of evaluating itself against context objects.
024 * Encapsulates the details of a previously parsed expression string.
025 * Provides a common abstraction for expression evaluation.
026 *
027 * @author Keith Donald
028 * @author Andy Clement
029 * @author Juergen Hoeller
030 * @since 3.0
031 */
032public interface Expression {
033
034        /**
035         * Return the original string used to create this expression (unmodified).
036         * @return the original expression string
037         */
038        String getExpressionString();
039
040        /**
041         * Evaluate this expression in the default standard context.
042         * @return the evaluation result
043         * @throws EvaluationException if there is a problem during evaluation
044         */
045        @Nullable
046        Object getValue() throws EvaluationException;
047
048        /**
049         * Evaluate the expression in the default context. If the result
050         * of the evaluation does not match (and cannot be converted to)
051         * the expected result type then an exception will be returned.
052         * @param desiredResultType the class the caller would like the result to be
053         * @return the evaluation result
054         * @throws EvaluationException if there is a problem during evaluation
055         */
056        @Nullable
057        <T> T getValue(@Nullable Class<T> desiredResultType) throws EvaluationException;
058
059        /**
060         * Evaluate this expression against the specified root object.
061         * @param rootObject the root object against which to evaluate the expression
062         * @return the evaluation result
063         * @throws EvaluationException if there is a problem during evaluation
064         */
065        @Nullable
066        Object getValue(@Nullable Object rootObject) throws EvaluationException;
067
068        /**
069         * Evaluate the expression in the default context against the specified root
070         * object. If the result of the evaluation does not match (and cannot be
071         * converted to) the expected result type then an exception will be returned.
072         * @param rootObject the root object against which to evaluate the expression
073         * @param desiredResultType the class the caller would like the result to be
074         * @return the evaluation result
075         * @throws EvaluationException if there is a problem during evaluation
076         */
077        @Nullable
078        <T> T getValue(@Nullable Object rootObject, @Nullable Class<T> desiredResultType) throws EvaluationException;
079
080        /**
081         * Evaluate this expression in the provided context and return the result
082         * of evaluation.
083         * @param context the context in which to evaluate the expression
084         * @return the evaluation result
085         * @throws EvaluationException if there is a problem during evaluation
086         */
087        @Nullable
088        Object getValue(EvaluationContext context) throws EvaluationException;
089
090        /**
091         * Evaluate this expression in the provided context and return the result
092         * of evaluation, but use the supplied root context as an override for any
093         * default root object specified in the context.
094         * @param context the context in which to evaluate the expression
095         * @param rootObject the root object against which to evaluate the expression
096         * @return the evaluation result
097         * @throws EvaluationException if there is a problem during evaluation
098         */
099        @Nullable
100        Object getValue(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
101
102        /**
103         * Evaluate the expression in a specified context which can resolve references
104         * to properties, methods, types, etc. The type of the evaluation result is
105         * expected to be of a particular class and an exception will be thrown if it
106         * is not and cannot be converted to that type.
107         * @param context the context in which to evaluate the expression
108         * @param desiredResultType the class the caller would like the result to be
109         * @return the evaluation result
110         * @throws EvaluationException if there is a problem during evaluation
111         */
112        @Nullable
113        <T> T getValue(EvaluationContext context, @Nullable Class<T> desiredResultType) throws EvaluationException;
114
115        /**
116         * Evaluate the expression in a specified context which can resolve references
117         * to properties, methods, types, etc. The type of the evaluation result is
118         * expected to be of a particular class and an exception will be thrown if it
119         * is not and cannot be converted to that type. The supplied root object
120         * overrides any default specified on the supplied context.
121         * @param context the context in which to evaluate the expression
122         * @param rootObject the root object against which to evaluate the expression
123         * @param desiredResultType the class the caller would like the result to be
124         * @return the evaluation result
125         * @throws EvaluationException if there is a problem during evaluation
126         */
127        @Nullable
128        <T> T getValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Class<T> desiredResultType)
129                        throws EvaluationException;
130
131        /**
132         * Return the most general type that can be passed to a {@link #setValue}
133         * method using the default context.
134         * @return the most general type of value that can be set on this context
135         * @throws EvaluationException if there is a problem determining the type
136         */
137        @Nullable
138        Class<?> getValueType() throws EvaluationException;
139
140        /**
141         * Return the most general type that can be passed to the
142         * {@link #setValue(Object, Object)} method using the default context.
143         * @param rootObject the root object against which to evaluate the expression
144         * @return the most general type of value that can be set on this context
145         * @throws EvaluationException if there is a problem determining the type
146         */
147        @Nullable
148        Class<?> getValueType(@Nullable Object rootObject) throws EvaluationException;
149
150        /**
151         * Return the most general type that can be passed to the
152         * {@link #setValue(EvaluationContext, Object)} method for the given context.
153         * @param context the context in which to evaluate the expression
154         * @return the most general type of value that can be set on this context
155         * @throws EvaluationException if there is a problem determining the type
156         */
157        @Nullable
158        Class<?> getValueType(EvaluationContext context) throws EvaluationException;
159
160        /**
161         * Return the most general type that can be passed to the
162         * {@link #setValue(EvaluationContext, Object, Object)} method for the given
163         * context. The supplied root object overrides any specified in the context.
164         * @param context the context in which to evaluate the expression
165         * @param rootObject the root object against which to evaluate the expression
166         * @return 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        @Nullable
170        Class<?> getValueType(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
171
172        /**
173         * Return the most general type that can be passed to a {@link #setValue}
174         * method using the default context.
175         * @return a type descriptor for values that can be set on this context
176         * @throws EvaluationException if there is a problem determining the type
177         */
178        @Nullable
179        TypeDescriptor getValueTypeDescriptor() throws EvaluationException;
180
181        /**
182         * Return the most general type that can be passed to the
183         * {@link #setValue(Object, Object)} method using the default context.
184         * @param rootObject the root object against which to evaluate the expression
185         * @return a type descriptor for values that can be set on this context
186         * @throws EvaluationException if there is a problem determining the type
187         */
188        @Nullable
189        TypeDescriptor getValueTypeDescriptor(@Nullable Object rootObject) throws EvaluationException;
190
191        /**
192         * Return the most general type that can be passed to the
193         * {@link #setValue(EvaluationContext, Object)} method for the given context.
194         * @param context the context in which to evaluate the expression
195         * @return a type descriptor for values that can be set on this context
196         * @throws EvaluationException if there is a problem determining the type
197         */
198        @Nullable
199        TypeDescriptor getValueTypeDescriptor(EvaluationContext context) throws EvaluationException;
200
201        /**
202         * Return the most general type that can be passed to the
203         * {@link #setValue(EvaluationContext, Object, Object)} method for the given
204         * context. The supplied root object overrides any specified in the context.
205         * @param context the context in which to evaluate the expression
206         * @param rootObject the root object against which to evaluate the expression
207         * @return a type descriptor for values that can be set on this context
208         * @throws EvaluationException if there is a problem determining the type
209         */
210        @Nullable
211        TypeDescriptor getValueTypeDescriptor(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
212
213        /**
214         * Determine if an expression can be written to, i.e. setValue() can be called.
215         * @param rootObject the root object against which to evaluate the expression
216         * @return {@code true} if the expression is writable; {@code false} otherwise
217         * @throws EvaluationException if there is a problem determining if it is writable
218         */
219        boolean isWritable(@Nullable Object rootObject) throws EvaluationException;
220
221        /**
222         * Determine if an expression can be written to, i.e. setValue() can be called.
223         * @param context the context in which the expression should be checked
224         * @return {@code true} if the expression is writable; {@code false} otherwise
225         * @throws EvaluationException if there is a problem determining if it is writable
226         */
227        boolean isWritable(EvaluationContext context) throws EvaluationException;
228
229        /**
230         * Determine if an expression can be written to, i.e. setValue() can be called.
231         * The supplied root object overrides any specified in the context.
232         * @param context the context in which the expression should be checked
233         * @param rootObject the root object against which to evaluate the expression
234         * @return {@code true} if the expression is writable; {@code false} otherwise
235         * @throws EvaluationException if there is a problem determining if it is writable
236         */
237        boolean isWritable(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
238
239        /**
240         * Set this expression in the provided context to the value provided.
241         * @param rootObject the root object against which to evaluate the expression
242         * @param value the new value
243         * @throws EvaluationException if there is a problem during evaluation
244         */
245        void setValue(@Nullable Object rootObject, @Nullable Object value) throws EvaluationException;
246
247        /**
248         * Set this expression in the provided context to the value provided.
249         * @param context the context in which to set the value of the expression
250         * @param value the new value
251         * @throws EvaluationException if there is a problem during evaluation
252         */
253        void setValue(EvaluationContext context, @Nullable Object value) throws EvaluationException;
254
255        /**
256         * Set this expression in the provided context to the value provided.
257         * The supplied root object overrides any specified in the context.
258         * @param context the context in which to set the value of the expression
259         * @param rootObject the root object against which to evaluate the expression
260         * @param value the new value
261         * @throws EvaluationException if there is a problem during evaluation
262         */
263        void setValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Object value) throws EvaluationException;
264
265}