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}