From 003407a7e3796a1c665bce0a682254518e6d257d Mon Sep 17 00:00:00 2001 From: Sam Brannen <104798+sbrannen@users.noreply.github.com> Date: Sat, 27 Jan 2024 18:26:28 +0100 Subject: [PATCH] Polish Javadoc for SpelEvaluationException and Expression --- .../expression/Expression.java | 94 ++++++++++--------- .../spel/SpelEvaluationException.java | 11 ++- 2 files changed, 58 insertions(+), 47 deletions(-) diff --git a/spring-expression/src/main/java/org/springframework/expression/Expression.java b/spring-expression/src/main/java/org/springframework/expression/Expression.java index 8babd78243..97e89ab671 100644 --- a/spring-expression/src/main/java/org/springframework/expression/Expression.java +++ b/spring-expression/src/main/java/org/springframework/expression/Expression.java @@ -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. + * + *

Encapsulates the details of a previously parsed expression string. + * + *

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 getValue(@Nullable Object rootObject, @Nullable Class desiredResultType) throws EvaluationException; + T getValue(@Nullable Object rootObject, @Nullable Class 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 getValue(EvaluationContext context, @Nullable Class desiredResultType) throws EvaluationException; + T getValue(EvaluationContext context, @Nullable Class 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 + *

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. + *

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. + *

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. + *

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. + *

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; } diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/SpelEvaluationException.java b/spring-expression/src/main/java/org/springframework/expression/spel/SpelEvaluationException.java index c55fe0b6e3..c6b49c6fae 100644 --- a/spring-expression/src/main/java/org/springframework/expression/spel/SpelEvaluationException.java +++ b/spring-expression/src/main/java/org/springframework/expression/spel/SpelEvaluationException.java @@ -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. + * + *

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. * * @author Andy Clement * @author Juergen Hoeller