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; 020 021/** 022 * An expression capable of evaluating itself against context objects. 023 * Encapsulates the details of a previously parsed expression string. 024 * Provides a common abstraction for expression evaluation. 025 * 026 * @author Keith Donald 027 * @author Andy Clement 028 * @author Juergen Hoeller 029 * @since 3.0 030 */ 031public interface Expression { 032 033 /** 034 * Return the original string used to create this expression (unmodified). 035 * @return the original expression string 036 */ 037 String getExpressionString(); 038 039 /** 040 * Evaluate this expression in the default standard context. 041 * @return the evaluation result 042 * @throws EvaluationException if there is a problem during evaluation 043 */ 044 Object getValue() throws EvaluationException; 045 046 /** 047 * Evaluate the expression in the default context. If the result 048 * of the evaluation does not match (and cannot be converted to) 049 * the expected result type then an exception will be returned. 050 * @param desiredResultType the class the caller would like the result to be 051 * @return the evaluation result 052 * @throws EvaluationException if there is a problem during evaluation 053 */ 054 <T> T getValue(Class<T> desiredResultType) throws EvaluationException; 055 056 /** 057 * Evaluate this expression against the specified root object. 058 * @param rootObject the root object against which to evaluate the expression 059 * @return the evaluation result 060 * @throws EvaluationException if there is a problem during evaluation 061 */ 062 Object getValue(Object rootObject) throws EvaluationException; 063 064 /** 065 * Evaluate the expression in the default context against the specified root 066 * object. If the result of the evaluation does not match (and cannot be 067 * converted to) the expected result type then an exception will be returned. 068 * @param rootObject the root object against which to evaluate the expression 069 * @param desiredResultType the class the caller would like the result to be 070 * @return the evaluation result 071 * @throws EvaluationException if there is a problem during evaluation 072 */ 073 <T> T getValue(Object rootObject, Class<T> desiredResultType) throws EvaluationException; 074 075 /** 076 * Evaluate this expression in the provided context and return the result 077 * of evaluation. 078 * @param context the context in which to evaluate the expression 079 * @return the evaluation result 080 * @throws EvaluationException if there is a problem during evaluation 081 */ 082 Object getValue(EvaluationContext context) throws EvaluationException; 083 084 /** 085 * Evaluate this expression in the provided context and return the result 086 * of evaluation, but use the supplied root context as an override for any 087 * default root object specified in the context. 088 * @param context the context in which to evaluate the expression 089 * @param rootObject the root object against which to evaluate the expression 090 * @return the evaluation result 091 * @throws EvaluationException if there is a problem during evaluation 092 */ 093 Object getValue(EvaluationContext context, Object rootObject) throws EvaluationException; 094 095 /** 096 * Evaluate the expression in a specified context which can resolve references 097 * to properties, methods, types, etc. The type of the evaluation result is 098 * expected to be of a particular class and an exception will be thrown if it 099 * is not and cannot be converted to that type. 100 * @param context the context in which to evaluate the expression 101 * @param desiredResultType the class the caller would like the result to be 102 * @return the evaluation result 103 * @throws EvaluationException if there is a problem during evaluation 104 */ 105 <T> T getValue(EvaluationContext context, Class<T> desiredResultType) throws EvaluationException; 106 107 /** 108 * Evaluate the expression in a specified context which can resolve references 109 * to properties, methods, types, etc. The type of the evaluation result is 110 * expected to be of a particular class and an exception will be thrown if it 111 * is not and cannot be converted to that type. The supplied root object 112 * overrides any default specified on the supplied context. 113 * @param context the context in which to evaluate the expression 114 * @param rootObject the root object against which to evaluate the expression 115 * @param desiredResultType the class the caller would like the result to be 116 * @return the evaluation result 117 * @throws EvaluationException if there is a problem during evaluation 118 */ 119 <T> T getValue(EvaluationContext context, Object rootObject, Class<T> desiredResultType) 120 throws EvaluationException; 121 122 /** 123 * Return the most general type that can be passed to a {@link #setValue} 124 * method using the default context. 125 * @return the most general type of value that can be set on this context 126 * @throws EvaluationException if there is a problem determining the type 127 */ 128 Class<?> getValueType() throws EvaluationException; 129 130 /** 131 * Return the most general type that can be passed to the 132 * {@link #setValue(Object, Object)} method using the default context. 133 * @param rootObject the root object against which to evaluate the expression 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 Class<?> getValueType(Object rootObject) throws EvaluationException; 138 139 /** 140 * Return the most general type that can be passed to the 141 * {@link #setValue(EvaluationContext, Object)} method for the given context. 142 * @param context the context in which to evaluate the expression 143 * @return the most general type of value that can be set on this context 144 * @throws EvaluationException if there is a problem determining the type 145 */ 146 Class<?> getValueType(EvaluationContext context) throws EvaluationException; 147 148 /** 149 * Return the most general type that can be passed to the 150 * {@link #setValue(EvaluationContext, Object, Object)} method for the given 151 * context. The supplied root object overrides any specified in the context. 152 * @param context the context in which to evaluate the expression 153 * @param rootObject the root object against 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 Class<?> getValueType(EvaluationContext context, Object rootObject) throws EvaluationException; 158 159 /** 160 * Return the most general type that can be passed to a {@link #setValue} 161 * method using the default context. 162 * @return a type descriptor for values that can be set on this context 163 * @throws EvaluationException if there is a problem determining the type 164 */ 165 TypeDescriptor getValueTypeDescriptor() throws EvaluationException; 166 167 /** 168 * Return the most general type that can be passed to the 169 * {@link #setValue(Object, Object)} method using the default context. 170 * @param rootObject the root object against which to evaluate the expression 171 * @return a type descriptor for values that can be set on this context 172 * @throws EvaluationException if there is a problem determining the type 173 */ 174 TypeDescriptor getValueTypeDescriptor(Object rootObject) throws EvaluationException; 175 176 /** 177 * Return the most general type that can be passed to the 178 * {@link #setValue(EvaluationContext, Object)} method for the given context. 179 * @param context the context in which to evaluate the expression 180 * @return a type descriptor for values that can be set on this context 181 * @throws EvaluationException if there is a problem determining the type 182 */ 183 TypeDescriptor getValueTypeDescriptor(EvaluationContext context) throws EvaluationException; 184 185 /** 186 * Return the most general type that can be passed to the 187 * {@link #setValue(EvaluationContext, Object, Object)} method for the given 188 * context. The supplied root object overrides any specified in the context. 189 * @param context the context in which to evaluate the expression 190 * @param rootObject the root object against which to evaluate the expression 191 * @return a type descriptor for values that can be set on this context 192 * @throws EvaluationException if there is a problem determining the type 193 */ 194 TypeDescriptor getValueTypeDescriptor(EvaluationContext context, Object rootObject) throws EvaluationException; 195 196 /** 197 * Determine if an expression can be written to, i.e. setValue() can be called. 198 * @param rootObject the root object against which to evaluate the expression 199 * @return {@code true} if the expression is writable; {@code false} otherwise 200 * @throws EvaluationException if there is a problem determining if it is writable 201 */ 202 boolean isWritable(Object rootObject) throws EvaluationException; 203 204 /** 205 * Determine if an expression can be written to, i.e. setValue() can be called. 206 * @param context the context in which the expression should be checked 207 * @return {@code true} if the expression is writable; {@code false} otherwise 208 * @throws EvaluationException if there is a problem determining if it is writable 209 */ 210 boolean isWritable(EvaluationContext context) throws EvaluationException; 211 212 /** 213 * Determine if an expression can be written to, i.e. setValue() can be called. 214 * The supplied root object overrides any specified in the context. 215 * @param context the context in which the expression should be checked 216 * @param rootObject the root object against which to evaluate the expression 217 * @return {@code true} if the expression is writable; {@code false} otherwise 218 * @throws EvaluationException if there is a problem determining if it is writable 219 */ 220 boolean isWritable(EvaluationContext context, Object rootObject) throws EvaluationException; 221 222 /** 223 * Set this expression in the provided context to the value provided. 224 * @param rootObject the root object against which to evaluate the expression 225 * @param value the new value 226 * @throws EvaluationException if there is a problem during evaluation 227 */ 228 void setValue(Object rootObject, Object value) throws EvaluationException; 229 230 /** 231 * Set this expression in the provided context to the value provided. 232 * @param context the context in which to set the value of the expression 233 * @param value the new value 234 * @throws EvaluationException if there is a problem during evaluation 235 */ 236 void setValue(EvaluationContext context, Object value) throws EvaluationException; 237 238 /** 239 * Set this expression in the provided context to the value provided. 240 * The supplied root object overrides any specified in the context. 241 * @param context the context in which to set the value of the expression 242 * @param rootObject the root object against which to evaluate the expression 243 * @param value the new value 244 * @throws EvaluationException if there is a problem during evaluation 245 */ 246 void setValue(EvaluationContext context, Object rootObject, Object value) throws EvaluationException; 247 248}