/*
* Copyright 2002-2019 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.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.aop;
import java.lang.reflect.Method;
Part of a Pointcut: Checks whether the target method is eligible for advice. A MethodMatcher may be evaluated statically or at runtime (dynamically).
Static matching involves method and (possibly) method attributes. Dynamic matching
also makes arguments for a particular call available, and any effects of running
previous advice applying to the joinpoint.
If an implementation returns false from its isRuntime() method, evaluation can be performed statically, and the result will be the same for all invocations of this method, whatever their arguments. This means that if the isRuntime() method returns false, the 3-arg matches(Method, Class<?>, Object[]) method will never be invoked.
If an implementation returns true from its 2-arg matches(Method, Class<?>) method and its isRuntime() method returns true, the 3-arg matches(Method, Class<?>, Object[]) method will be invoked immediately before each potential execution of the related advice,
to decide whether the advice should run. All previous advice, such as earlier interceptors
in an interceptor chain, will have run, so any state changes they have produced in
parameters or ThreadLocal state will be available at the time of evaluation.
Concrete implementations of this interface typically should provide proper implementations of Object.equals(Object) and Object.hashCode() in order to allow the matcher to be used in caching scenarios — for example, in proxies generated by CGLIB.
Author: Rod Johnson See Also: Since: 11.11.2003
/**
* Part of a {@link Pointcut}: Checks whether the target method is eligible for advice.
*
* <p>A MethodMatcher may be evaluated <b>statically</b> or at <b>runtime</b> (dynamically).
* Static matching involves method and (possibly) method attributes. Dynamic matching
* also makes arguments for a particular call available, and any effects of running
* previous advice applying to the joinpoint.
*
* <p>If an implementation returns {@code false} from its {@link #isRuntime()}
* method, evaluation can be performed statically, and the result will be the same
* for all invocations of this method, whatever their arguments. This means that
* if the {@link #isRuntime()} method returns {@code false}, the 3-arg
* {@link #matches(java.lang.reflect.Method, Class, Object[])} method will never be invoked.
*
* <p>If an implementation returns {@code true} from its 2-arg
* {@link #matches(java.lang.reflect.Method, Class)} method and its {@link #isRuntime()} method
* returns {@code true}, the 3-arg {@link #matches(java.lang.reflect.Method, Class, Object[])}
* method will be invoked <i>immediately before each potential execution of the related advice</i>,
* to decide whether the advice should run. All previous advice, such as earlier interceptors
* in an interceptor chain, will have run, so any state changes they have produced in
* parameters or ThreadLocal state will be available at the time of evaluation.
*
* <p>Concrete implementations of this interface typically should provide proper
* implementations of {@link Object#equals(Object)} and {@link Object#hashCode()}
* in order to allow the matcher to be used in caching scenarios — for
* example, in proxies generated by CGLIB.
*
* @author Rod Johnson
* @since 11.11.2003
* @see Pointcut
* @see ClassFilter
*/
public interface MethodMatcher {
Perform static checking whether the given method matches.
If this returns false or if the isRuntime() method returns false, no runtime check (i.e. no matches(Method, Class<?>, Object[]) call) will be made.
Params: - method – the candidate method
- targetClass – the target class
Returns: whether or not this method matches statically
/**
* Perform static checking whether the given method matches.
* <p>If this returns {@code false} or if the {@link #isRuntime()}
* method returns {@code false}, no runtime check (i.e. no
* {@link #matches(java.lang.reflect.Method, Class, Object[])} call)
* will be made.
* @param method the candidate method
* @param targetClass the target class
* @return whether or not this method matches statically
*/
boolean matches(Method method, Class<?> targetClass);
Is this MethodMatcher dynamic, that is, must a final call be made on the matches(Method, Class<?>, Object[]) method at runtime even if the 2-arg matches method returns true? Can be invoked when an AOP proxy is created, and need not be invoked
again before each method invocation,
Returns: whether or not a runtime match via the 3-arg matches(Method, Class<?>, Object[]) method is required if static matching passed
/**
* Is this MethodMatcher dynamic, that is, must a final call be made on the
* {@link #matches(java.lang.reflect.Method, Class, Object[])} method at
* runtime even if the 2-arg matches method returns {@code true}?
* <p>Can be invoked when an AOP proxy is created, and need not be invoked
* again before each method invocation,
* @return whether or not a runtime match via the 3-arg
* {@link #matches(java.lang.reflect.Method, Class, Object[])} method
* is required if static matching passed
*/
boolean isRuntime();
Check whether there a runtime (dynamic) match for this method,
which must have matched statically.
This method is invoked only if the 2-arg matches method returns true for the given method and target class, and if the isRuntime() method returns true. Invoked immediately before potential running of the advice, after any advice earlier in the advice chain has run.
Params: - method – the candidate method
- targetClass – the target class
- args – arguments to the method
See Also: Returns: whether there's a runtime match
/**
* Check whether there a runtime (dynamic) match for this method,
* which must have matched statically.
* <p>This method is invoked only if the 2-arg matches method returns
* {@code true} for the given method and target class, and if the
* {@link #isRuntime()} method returns {@code true}. Invoked
* immediately before potential running of the advice, after any
* advice earlier in the advice chain has run.
* @param method the candidate method
* @param targetClass the target class
* @param args arguments to the method
* @return whether there's a runtime match
* @see MethodMatcher#matches(Method, Class)
*/
boolean matches(Method method, Class<?> targetClass, Object... args);
Canonical instance that matches all methods.
/**
* Canonical instance that matches all methods.
*/
MethodMatcher TRUE = TrueMethodMatcher.INSTANCE;
}