ParameterNameDiscoverer implementation that tries to deduce parameter names for an advice method from the pointcut expression, returning, and throwing clauses. If an unambiguous interpretation is not available, it returns null.

Algorithm Summary

If an unambiguous binding can be deduced, then it is. If the advice requirements cannot possibly be satisfied, then null is returned. By setting the raiseExceptions property to true, descriptive exceptions will be thrown instead of returning null in the case that the parameter names cannot be discovered.

Algorithm Details

This class interprets arguments in the following way:

If the first parameter of the method is of type JoinPoint or ProceedingJoinPoint, it is assumed to be for passing thisJoinPoint to the advice, and the parameter name will be assigned the value "thisJoinPoint".
If the first parameter of the method is of type JoinPoint.StaticPart, it is assumed to be for passing "thisJoinPointStaticPart" to the advice, and the parameter name will be assigned the value "thisJoinPointStaticPart".
If a throwingName has been set, and there are no unbound arguments of type Throwable+, then an IllegalArgumentException is raised. If there is more than one unbound argument of type Throwable+, then an AmbiguousBindingException is raised. If there is exactly one unbound argument of type Throwable+, then the corresponding parameter name is assigned the value <throwingName>.
If there remain unbound arguments, then the pointcut expression is examined. Let a be the number of annotation-based pointcut expressions (@annotation, @this, @target, @args, @within, @withincode) that are used in binding form. Usage in binding form has itself to be deduced: if the expression inside the pointcut is a single string literal that meets Java variable name conventions it is assumed to be a variable name. If a is zero we proceed to the next stage. If a > 1 then an AmbiguousBindingException is raised. If a == 1, and there are no unbound arguments of type Annotation+, then an IllegalArgumentException is raised. If there is exactly one such argument, then the corresponding parameter name is assigned the value from the pointcut expression.
If a returningName has been set, and there are no unbound arguments then an IllegalArgumentException is raised. If there is more than one unbound argument then an AmbiguousBindingException is raised. If there is exactly one unbound argument then the corresponding parameter name is assigned the value of the returningName.
If there remain unbound arguments, then the pointcut expression is examined once more for this, target, and args pointcut expressions used in the binding form (binding forms are deduced as described for the annotation based pointcuts). If there remains more than one unbound argument of a primitive type (which can only be bound in args) then an AmbiguousBindingException is raised. If there is exactly one argument of a primitive type, then if exactly one args bound variable was found, we assign the corresponding parameter name the variable name. If there were no args bound variables found an IllegalStateException is raised. If there are multiple args bound variables, an AmbiguousBindingException is raised. At this point, if there remains more than one unbound argument we raise an AmbiguousBindingException. If there are no unbound arguments remaining, we are done. If there is exactly one unbound argument remaining, and only one candidate variable name unbound from this, target, or args, it is assigned as the corresponding parameter name. If there are multiple possibilities, an AmbiguousBindingException is raised.

The behavior on raising an IllegalArgumentException or AmbiguousBindingException is configurable to allow this discoverer to be used as part of a chain-of-responsibility. By default the condition will be logged and the getParameterNames(Method) method will simply return null. If the raiseExceptions property is set to true, the conditions will be thrown as IllegalArgumentException and AmbiguousBindingException, respectively.

Modifier and Type	Class and Description
public static class	AspectJAdviceParameterNameDiscoverer.AmbiguousBindingException Thrown in response to an ambiguous binding being detected when trying to resolve a method's parameter names.
private static record	AspectJAdviceParameterNameDiscoverer.PointcutBody Simple record to hold the extracted text from a pointcut body, together with the number of tokens consumed in extracting it.

Field Summary

Modifier and Type	Field and Description
private Class<?>[]	argumentTypes
private static final Set<String>	nonReferencePointcutTokens
private int	numberOfRemainingUnboundArguments
private String[]	parameterNameBindings
private final String	pointcutExpression The pointcut expression associated with the advice, as a simple String.
private boolean	raiseExceptions
private String	returningName If the advice is afterReturning, and binds the return value, this is the parameter name used.
private static final Set<String>	singleValuedAnnotationPcds
private static final int	STEP_ANNOTATION_BINDING
private static final int	STEP_FINISHED
private static final int	STEP_JOIN_POINT_BINDING
private static final int	STEP_PRIMITIVE_ARGS_BINDING
private static final int	STEP_REFERENCE_PCUT_BINDING
private static final int	STEP_RETURNING_BINDING
private static final int	STEP_THIS_TARGET_ARGS_BINDING
private static final int	STEP_THROWING_BINDING
private static final String	THIS_JOIN_POINT
private static final String	THIS_JOIN_POINT_STATIC_PART
private String	throwingName If the advice is afterThrowing, and binds the thrown value, this is the parameter name used.

Access	Constructor and Description
public	AspectJAdviceParameterNameDiscoverer(String pointcutExpression) Create a new discoverer that attempts to discover parameter names.

Method Summary

Modifier and Type	Method and Description
private boolean	alreadyBound(String varName)
private void	bindAnnotationsFromVarNames(List<String> varNames) Match the given list of extracted variable names to argument slots.
private void	bindParameterName(int index, String name)
private int	countNumberOfUnboundAnnotationArguments()
private int	countNumberOfUnboundPrimitiveArguments()
private void	findAndBind(Class<?> argumentType, String varName) Find the argument index with the given type, and bind the given `varName` in that position.
public String[]	Returns: the parameter names getParameterNames(Method the target `Method` method) Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames. Deduce the parameter names for an advice method.
public String[]	Returns: `null` getParameterNames(Constructor<?> the constructor to find parameter names for ctor) Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames. An advice method can never be a constructor in Spring.
private AspectJAdviceParameterNameDiscoverer.PointcutBody	getPointcutBody(String[] tokens, int startIndex) We've found the start of a binding pointcut at the given index into the token array.
private boolean	isSubtypeOf(Class<?> supertype, int argumentNumber) Return `true` if the given argument type is a subclass of the given supertype.
private boolean	isUnbound(int i)
private void	maybeBindAnnotationsFromPointcutExpression() Parse the string pointcut expression looking for: @this, @target, @args, @within, @withincode, @annotation.
private void	maybeBindPrimitiveArgsFromPointcutExpression() Match up args against unbound arguments of primitive types.
private void	maybeBindReferencePointcutParameter()
private void	maybeBindReturningVariable() If a returning variable was specified and there is only one choice remaining, bind it.
private boolean	maybeBindThisJoinPoint() If the first parameter is of type JoinPoint or ProceedingJoinPoint, bind "thisJoinPoint" as parameter name and return true, else return false.
private void	maybeBindThisJoinPointStaticPart()
private void	maybeBindThisOrTargetOrArgsFromPointcutExpression() Parse the string pointcut expression looking for this(), target() and args() expressions.
private void	maybeBindThrowingVariable() If a throwing name was specified and there is exactly one choice remaining (argument that is a subtype of Throwable) then bind it.
private String	maybeExtractVariableName(String candidateToken) If the token starts meets Java identifier conventions, it's in.
private void	maybeExtractVariableNamesFromArgs(String argsSpec, List<String> varNames) Given an args pointcut body (could be `args` or `at_args`), add any candidate variable names to the given list.
public void	setRaiseExceptions(boolean `true` if exceptions are to be thrown raiseExceptions) Indicate whether `IllegalArgumentException` and `AmbiguousBindingException` must be thrown as appropriate in the case of failing to deduce advice parameter names.
public void	setReturningName(String the name of the returning variable returningName) If `afterReturning` advice binds the return value, the `returning` variable name must be specified.
public void	setThrowingName(String the name of the throwing variable throwingName) If `afterThrowing` advice binds the thrown value, the `throwing` variable name must be specified.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

argumentTypes	back to summary
private Class<?>[] argumentTypes

nonReferencePointcutTokens	back to summary
private static final Set<String> nonReferencePointcutTokens

numberOfRemainingUnboundArguments	back to summary
private int numberOfRemainingUnboundArguments

parameterNameBindings	back to summary
private String[] parameterNameBindings

pointcutExpression	back to summary
private final String pointcutExpression The pointcut expression associated with the advice, as a simple String. Annotations @Nullable

raiseExceptions	back to summary
private boolean raiseExceptions

returningName	back to summary
private String returningName If the advice is afterReturning, and binds the return value, this is the parameter name used. Annotations @Nullable

singleValuedAnnotationPcds	back to summary
private static final Set<String> singleValuedAnnotationPcds

STEP_ANNOTATION_BINDING	back to summary
private static final int STEP_ANNOTATION_BINDING

STEP_FINISHED	back to summary
private static final int STEP_FINISHED

STEP_JOIN_POINT_BINDING	back to summary
private static final int STEP_JOIN_POINT_BINDING

STEP_PRIMITIVE_ARGS_BINDING	back to summary
private static final int STEP_PRIMITIVE_ARGS_BINDING

STEP_REFERENCE_PCUT_BINDING	back to summary
private static final int STEP_REFERENCE_PCUT_BINDING

STEP_RETURNING_BINDING	back to summary
private static final int STEP_RETURNING_BINDING

STEP_THIS_TARGET_ARGS_BINDING	back to summary
private static final int STEP_THIS_TARGET_ARGS_BINDING

STEP_THROWING_BINDING	back to summary
private static final int STEP_THROWING_BINDING

THIS_JOIN_POINT	back to summary
private static final String THIS_JOIN_POINT

THIS_JOIN_POINT_STATIC_PART	back to summary
private static final String THIS_JOIN_POINT_STATIC_PART

throwingName	back to summary
private String throwingName If the advice is afterThrowing, and binds the thrown value, this is the parameter name used. Annotations @Nullable

AspectJAdviceParameterNameDiscoverer	back to summary
public AspectJAdviceParameterNameDiscoverer(String pointcutExpression) Create a new discoverer that attempts to discover parameter names. from the given pointcut expression.

Method Detail

alreadyBound	back to summary
private boolean alreadyBound(String varName)

bindAnnotationsFromVarNames	back to summary
private void bindAnnotationsFromVarNames(List<String> varNames) Match the given list of extracted variable names to argument slots.

bindParameterName	back to summary
private void bindParameterName(int index, String name)

countNumberOfUnboundAnnotationArguments	back to summary
private int countNumberOfUnboundAnnotationArguments()

countNumberOfUnboundPrimitiveArguments	back to summary
private int countNumberOfUnboundPrimitiveArguments()

findAndBind	back to summary
private void findAndBind(Class<?> argumentType, String varName) Find the argument index with the given type, and bind the given `varName` in that position.

getParameterNames back to summary

getParameterNames	back to summary
public String[] getParameterNames(Method method) Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames. Deduce the parameter names for an advice method. See the `class-level javadoc` for this class for details on the algorithm used. Parameters method:Method the target `Method` Returns:String[] the parameter names Annotations @Override @Nullable

public String[] getParameterNames(Method method)

Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames.

Deduce the parameter names for an advice method.

See the class-level javadoc for this class for details on the algorithm used.

Parameters

method:Method: the target Method

Returns:String[]

the parameter names

Annotations

@Override
@Nullable

getParameterNames back to summary

getParameterNames	back to summary
public String[] getParameterNames(Constructor<?> ctor) Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames. An advice method can never be a constructor in Spring. Parameters ctor:Constructor<?> Doc from org.springframework.core.ParameterNameDiscoverer.getParameterNames. the constructor to find parameter names for Returns:String[] `null` Annotations @Override @Nullable Exceptions UnsupportedOperationException: if `raiseExceptions` has been set to `true`

public String[] getParameterNames(Constructor<?> ctor)

Implements org.springframework.core.ParameterNameDiscoverer.getParameterNames.

An advice method can never be a constructor in Spring.

Parameters

ctor:Constructor<?>

Doc from org.springframework.core.ParameterNameDiscoverer.getParameterNames.

the constructor to find parameter names for

Returns:String[]

null

Annotations

@Override
@Nullable

Exceptions

UnsupportedOperationException:: if raiseExceptions has been set to true

getPointcutBody	back to summary
private AspectJAdviceParameterNameDiscoverer.PointcutBody getPointcutBody(String[] tokens, int startIndex) We've found the start of a binding pointcut at the given index into the token array. Now we need to extract the pointcut body and return it.

isSubtypeOf	back to summary
private boolean isSubtypeOf(Class<?> supertype, int argumentNumber) Return `true` if the given argument type is a subclass of the given supertype.

isUnbound	back to summary
private boolean isUnbound(int i)

maybeBindAnnotationsFromPointcutExpression	back to summary
private void maybeBindAnnotationsFromPointcutExpression() Parse the string pointcut expression looking for: @this, @target, @args, @within, @withincode, @annotation. If we find one of these pointcut expressions, try and extract a candidate variable name (or variable names, in the case of args). Some more support from AspectJ in doing this exercise would be nice... :)

maybeBindAnnotationsFromPointcutExpression

back to summary

private void maybeBindAnnotationsFromPointcutExpression()

Parse the string pointcut expression looking for: @this, @target, @args, @within, @withincode, @annotation. If we find one of these pointcut expressions, try and extract a candidate variable name (or variable names, in the case of args).

Some more support from AspectJ in doing this exercise would be nice... :)

maybeBindPrimitiveArgsFromPointcutExpression	back to summary
private void maybeBindPrimitiveArgsFromPointcutExpression() Match up args against unbound arguments of primitive types.

maybeBindReferencePointcutParameter	back to summary
private void maybeBindReferencePointcutParameter()

maybeBindReturningVariable	back to summary
private void maybeBindReturningVariable() If a returning variable was specified and there is only one choice remaining, bind it.

maybeBindThisJoinPoint	back to summary
private boolean maybeBindThisJoinPoint() If the first parameter is of type JoinPoint or ProceedingJoinPoint, bind "thisJoinPoint" as parameter name and return true, else return false.

maybeBindThisJoinPointStaticPart	back to summary
private void maybeBindThisJoinPointStaticPart()

maybeBindThisOrTargetOrArgsFromPointcutExpression	back to summary
private void maybeBindThisOrTargetOrArgsFromPointcutExpression() Parse the string pointcut expression looking for this(), target() and args() expressions. If we find one, try and extract a candidate variable name and bind it.

maybeBindThrowingVariable	back to summary
private void maybeBindThrowingVariable() If a throwing name was specified and there is exactly one choice remaining (argument that is a subtype of Throwable) then bind it.

maybeExtractVariableName	back to summary
private String maybeExtractVariableName(String candidateToken) If the token starts meets Java identifier conventions, it's in. Annotations @Nullable

maybeExtractVariableName

back to summary

private String maybeExtractVariableName(String candidateToken)

If the token starts meets Java identifier conventions, it's in.

Annotations

@Nullable

maybeExtractVariableNamesFromArgs	back to summary
private void maybeExtractVariableNamesFromArgs(String argsSpec, List<String> varNames) Given an args pointcut body (could be `args` or `at_args`), add any candidate variable names to the given list.

setRaiseExceptions back to summary

setRaiseExceptions	back to summary
public void setRaiseExceptions(boolean raiseExceptions) Indicate whether `IllegalArgumentException` and `AmbiguousBindingException` must be thrown as appropriate in the case of failing to deduce advice parameter names. Parameters raiseExceptions:boolean `true` if exceptions are to be thrown

public void setRaiseExceptions(boolean raiseExceptions)

Indicate whether IllegalArgumentException and AmbiguousBindingException must be thrown as appropriate in the case of failing to deduce advice parameter names.

Parameters

raiseExceptions:boolean: true if exceptions are to be thrown

setReturningName back to summary

setReturningName	back to summary
public void setReturningName(String returningName) If `afterReturning` advice binds the return value, the `returning` variable name must be specified. Parameters returningName:String the name of the returning variable

public void setReturningName(String returningName)

If afterReturning advice binds the return value, the returning variable name must be specified.

Parameters

returningName:String: the name of the returning variable

setThrowingName back to summary

setThrowingName	back to summary
public void setThrowingName(String throwingName) If `afterThrowing` advice binds the thrown value, the `throwing` variable name must be specified. Parameters throwingName:String the name of the throwing variable

public void setThrowingName(String throwingName)

If afterThrowing advice binds the thrown value, the throwing variable name must be specified.

Parameters

throwingName:String: the name of the throwing variable

Access	Constructor and Description
public	AmbiguousBindingException(String the detail message msg) Construct a new AmbiguousBindingException with the specified message.

AmbiguousBindingException	back to summary
public AmbiguousBindingException(String msg) Construct a new AmbiguousBindingException with the specified message. Parameters msg:String the detail message

org.springframework.aop.aspectj back to summary

private final Record AspectJAdviceParameterNameDiscoverer.PointcutBody

Class Inheritance

extends Record

java.lang.Object
java.lang.Record
org.springframework.aop.aspectj.AspectJAdviceParameterNameDiscoverer.PointcutBody

Record Components

numTokensConsumed:int
text:String

Simple record to hold the extracted text from a pointcut body, together with the number of tokens consumed in extracting it.

Field Summary

Modifier and Type	Field and Description
private final int	numTokensConsumed Record Component accessed by numTokensConsumed().
private final String	text Record Component accessed by text().

Constructor Summary

Access	Constructor and Description
private	PointcutBody(int numTokensConsumed, String text)

Method Summary

Modifier and Type	Method and Description
public final boolean	equals(Object the reference object with which to compare. o) Implements abstract java.lang.Record.equals. Indicates whether some other object is "equal to" this one.
public final int	hashCode() Implements abstract java.lang.Record.hashCode. Returns a hash code value for the record.
public int	numTokensConsumed() Record Component getter of numTokensConsumed.
public String	text() Record Component getter of text.
public final String	toString() Implements abstract java.lang.Record.toString. Returns a string representation of the record.

Field Detail

numTokensConsumed	back to summary
private final int numTokensConsumed Record Component accessed by numTokensConsumed().

text	back to summary
private final String text Record Component accessed by text(). Annotations @Nullable

Constructor Detail

PointcutBody	back to summary
private PointcutBody(int numTokensConsumed, String text)

Method Detail

equals back to summary

public final boolean equals(Object o)

Implements abstract java.lang.Record.equals.

Doc from java.lang.Record.equals.

Indicates whether some other object is "equal to" this one. In addition to the general contract of Object.equals, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows:

    R copy = new R(r.c1(), r.c2(), ..., r.cn());

then it must be the case that r.equals(copy).

Parameters

o:Object: the reference object with which to compare.

Returns:boolean

true if this record is equal to the argument; false otherwise.

hashCode back to summary

public final int hashCode()

Implements abstract java.lang.Record.hashCode.

Doc from java.lang.Record.hashCode.

Returns a hash code value for the record. Obeys the general contract of Object.hashCode. For records, hashing behavior is constrained by the refined contract of Record.equals, so that any two records created from the same components must have the same hash code.

Returns:int: a hash code value for this record.

numTokensConsumed	back to summary
public int numTokensConsumed() Record Component getter of numTokensConsumed.

text

back to summary

public String text()

Record Component getter of text.

Annotations

@Nullable

toString back to summary

public final String toString()

Implements abstract java.lang.Record.toString.

Doc from java.lang.Record.toString.

Returns a string representation of the record. In accordance with the general contract of Object#toString(), the toString method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read.

In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

Returns:String: a string representation of the object.

public Class AspectJAdviceParameterNameDiscoverer

Algorithm Summary

Algorithm Details

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class AspectJAdviceParameterNameDiscoverer.AmbiguousBindingException

Constructor Summary

Constructor Detail

private final Record AspectJAdviceParameterNameDiscoverer.PointcutBody

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail