Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish Javadoc for SpelEvaluationException and Expression

Browse Source
This commit is contained in:
Sam Brannen
2024-01-27 18:26:28 +01:00
parent a7764dc61d
commit 003407a7e3
2 changed files with 58 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
spring-expression/src/main/java/org/springframework/expression/Expression.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -21,8 +21,10 @@ import org.springframework.lang.Nullable;
/**
* An expression capable of evaluating itself against context objects.
* Encapsulates the details of a previously parsed expression string.
* Provides a common abstraction for expression evaluation.
*
* <p>Encapsulates the details of a previously parsed expression string.
*
* <p>Provides a common abstraction for expression evaluation.
*
* @author Keith Donald
* @author Andy Clement
@@ -46,10 +48,10 @@ public interface Expression {
Object getValue() throws EvaluationException;
/**
* Evaluate the expression in the default context. If the result
* Evaluate this expression in the default context. If the result
* of the evaluation does not match (and cannot be converted to)
* the expected result type then an exception will be returned.
* @param desiredResultType the class the caller would like the result to be
* the expected result type then an exception will be thrown.
* @param desiredResultType the type the caller would like the result to be
* @return the evaluation result
* @throws EvaluationException if there is a problem during evaluation
*/
@@ -66,16 +68,17 @@ public interface Expression {
Object getValue(@Nullable Object rootObject) throws EvaluationException;
/**
* Evaluate the expression in the default context against the specified root
* Evaluate this expression in the default context against the specified root
* object. If the result of the evaluation does not match (and cannot be
* converted to) the expected result type then an exception will be returned.
* converted to) the expected result type then an exception will be thrown.
* @param rootObject the root object against which to evaluate the expression
* @param desiredResultType the class the caller would like the result to be
* @param desiredResultType the type the caller would like the result to be
* @return the evaluation result
* @throws EvaluationException if there is a problem during evaluation
*/
@Nullable
<T> T getValue(@Nullable Object rootObject, @Nullable Class<T> desiredResultType) throws EvaluationException;
<T> T getValue(@Nullable Object rootObject, @Nullable Class<T> desiredResultType)
throws EvaluationException;
/**
* Evaluate this expression in the provided context and return the result
@@ -100,27 +103,28 @@ public interface Expression {
Object getValue(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
/**
* Evaluate the expression in a specified context which can resolve references
* Evaluate this expression in the provided context which can resolve references
* to properties, methods, types, etc. The type of the evaluation result is
* expected to be of a particular class and an exception will be thrown if it
* expected to be of a particular type, and an exception will be thrown if it
* is not and cannot be converted to that type.
* @param context the context in which to evaluate the expression
* @param desiredResultType the class the caller would like the result to be
* @param desiredResultType the type the caller would like the result to be
* @return the evaluation result
* @throws EvaluationException if there is a problem during evaluation
*/
@Nullable
<T> T getValue(EvaluationContext context, @Nullable Class<T> desiredResultType) throws EvaluationException;
<T> T getValue(EvaluationContext context, @Nullable Class<T> desiredResultType)
throws EvaluationException;
/**
* Evaluate the expression in a specified context which can resolve references
* Evaluate this expression in the provided context which can resolve references
* to properties, methods, types, etc. The type of the evaluation result is
* expected to be of a particular class and an exception will be thrown if it
* is not and cannot be converted to that type. The supplied root object
* overrides any default specified on the supplied context.
* expected to be of a particular type, and an exception will be thrown if it
* is not and cannot be converted to that type.j
* <p>The supplied root object overrides any specified in the supplied context.
* @param context the context in which to evaluate the expression
* @param rootObject the root object against which to evaluate the expression
* @param desiredResultType the class the caller would like the result to be
* @param desiredResultType the type the caller would like the result to be
* @return the evaluation result
* @throws EvaluationException if there is a problem during evaluation
*/
@@ -129,9 +133,9 @@ public interface Expression {
throws EvaluationException;
/**
* Return the most general type that can be passed to a {@link #setValue}
* method using the default context.
* @return the most general type of value that can be set on this context
* Return the most general type that can be passed to the
* {@link #setValue(EvaluationContext, Object)} method using the default context.
* @return the most general type of value that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
@@ -141,7 +145,7 @@ public interface Expression {
* Return the most general type that can be passed to the
* {@link #setValue(Object, Object)} method using the default context.
* @param rootObject the root object against which to evaluate the expression
* @return the most general type of value that can be set on this context
* @return the most general type of value that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
@@ -151,7 +155,7 @@ public interface Expression {
* Return the most general type that can be passed to the
* {@link #setValue(EvaluationContext, Object)} method for the given context.
* @param context the context in which to evaluate the expression
* @return the most general type of value that can be set on this context
* @return the most general type of value that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
@@ -160,58 +164,61 @@ public interface Expression {
/**
* Return the most general type that can be passed to the
* {@link #setValue(EvaluationContext, Object, Object)} method for the given
* context. The supplied root object overrides any specified in the context.
* context.
* <p>The supplied root object overrides any specified in the supplied context.
* @param context the context in which to evaluate the expression
* @param rootObject the root object against which to evaluate the expression
* @return the most general type of value that can be set on this context
* @return the most general type of value that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
Class<?> getValueType(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
/**
* Return the most general type that can be passed to a {@link #setValue}
* method using the default context.
* @return a type descriptor for values that can be set on this context
* Return a descriptor for the most general type that can be passed to one of
* the {@code setValue(...)} methods using the default context.
* @return a type descriptor for values that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
TypeDescriptor getValueTypeDescriptor() throws EvaluationException;
/**
* Return the most general type that can be passed to the
* Return a descriptor for the most general type that can be passed to the
* {@link #setValue(Object, Object)} method using the default context.
* @param rootObject the root object against which to evaluate the expression
* @return a type descriptor for values that can be set on this context
* @return a type descriptor for values that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
TypeDescriptor getValueTypeDescriptor(@Nullable Object rootObject) throws EvaluationException;
/**
* Return the most general type that can be passed to the
* Return a descriptor for the most general type that can be passed to the
* {@link #setValue(EvaluationContext, Object)} method for the given context.
* @param context the context in which to evaluate the expression
* @return a type descriptor for values that can be set on this context
* @return a type descriptor for values that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
TypeDescriptor getValueTypeDescriptor(EvaluationContext context) throws EvaluationException;
/**
* Return the most general type that can be passed to the
* Return a descriptor for the most general type that can be passed to the
* {@link #setValue(EvaluationContext, Object, Object)} method for the given
* context. The supplied root object overrides any specified in the context.
* context.
* <p>The supplied root object overrides any specified in the supplied context.
* @param context the context in which to evaluate the expression
* @param rootObject the root object against which to evaluate the expression
* @return a type descriptor for values that can be set on this context
* @return a type descriptor for values that can be set in this context
* @throws EvaluationException if there is a problem determining the type
*/
@Nullable
TypeDescriptor getValueTypeDescriptor(EvaluationContext context, @Nullable Object rootObject) throws EvaluationException;
TypeDescriptor getValueTypeDescriptor(EvaluationContext context, @Nullable Object rootObject)
throws EvaluationException;
/**
* Determine if an expression can be written to, i.e. setValue() can be called.
* Determine if this expression can be written to, i.e. setValue() can be called.
* @param rootObject the root object against which to evaluate the expression
* @return {@code true} if the expression is writable; {@code false} otherwise
* @throws EvaluationException if there is a problem determining if it is writable
@@ -219,7 +226,7 @@ public interface Expression {
boolean isWritable(@Nullable Object rootObject) throws EvaluationException;
/**
* Determine if an expression can be written to, i.e. setValue() can be called.
* Determine if this expression can be written to, i.e. setValue() can be called.
* @param context the context in which the expression should be checked
* @return {@code true} if the expression is writable; {@code false} otherwise
* @throws EvaluationException if there is a problem determining if it is writable
@@ -227,8 +234,8 @@ public interface Expression {
boolean isWritable(EvaluationContext context) throws EvaluationException;
/**
* Determine if an expression can be written to, i.e. setValue() can be called.
* The supplied root object overrides any specified in the context.
* Determine if this expression can be written to, i.e. setValue() can be called.
* <p>The supplied root object overrides any specified in the supplied context.
* @param context the context in which the expression should be checked
* @param rootObject the root object against which to evaluate the expression
* @return {@code true} if the expression is writable; {@code false} otherwise
@@ -254,12 +261,13 @@ public interface Expression {
/**
* Set this expression in the provided context to the value provided.
* The supplied root object overrides any specified in the context.
* <p>The supplied root object overrides any specified in the supplied context.
* @param context the context in which to set the value of the expression
* @param rootObject the root object against which to evaluate the expression
* @param value the new value
* @throws EvaluationException if there is a problem during evaluation
*/
void setValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Object value) throws EvaluationException;
void setValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Object value)
throws EvaluationException;
}

11
spring-expression/src/main/java/org/springframework/expression/spel/SpelEvaluationException.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2018 the original author or authors.
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -19,9 +19,12 @@ package org.springframework.expression.spel;
import org.springframework.expression.EvaluationException;
/**
* Root exception for Spring EL related exceptions. Rather than holding a hard coded
* string indicating the problem, it records a message key and the inserts for the
* message. See {@link SpelMessage} for the list of all possible messages that can occur.
* Root exception for Spring EL related exceptions.
*
* <p>Rather than holding a hard-coded string indicating the problem, it records
* a message key and the inserts for the message.
*
* <p>See {@link SpelMessage} for the list of all possible messages that can occur.
*
* @author Andy Clement
* @author Juergen Hoeller