MethodMatcher (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.aop

## Interface MethodMatcher

- All Known Subinterfaces:
    IntroductionAwareMethodMatcher
  All Known Implementing Classes:
    AbstractRegexpMethodPointcut, AnnotationMethodMatcher, AspectJExpressionPointcut, ControlFlowPointcut, DynamicMethodMatcher, DynamicMethodMatcherPointcut, JdkRegexpMethodPointcut, NameMatchMethodPointcut, StaticMethodMatcher, StaticMethodMatcherPointcut, StaticMethodMatcherPointcutAdvisor

      public interface MethodMatcher

  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(java.lang.reflect.Method, Class, Object[])` method will never be invoked.

  If an implementation returns `true` from its 2-arg `matches(java.lang.reflect.Method, Class)` method and its `isRuntime()` method returns `true`, the 3-arg `matches(java.lang.reflect.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.

  Since:
    11.11.2003
  Author:
    Rod Johnson
  See Also:
    `Pointcut`, `ClassFilter`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static MethodMatcher` | `TRUE` Canonical instance that matches all methods.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isRuntime()` Is this MethodMatcher dynamic, that is, must a final call be made on the `matches(java.lang.reflect.Method, Class, Object[])` method at runtime even if the 2-arg matches method returns `true`?
    `boolean` | `matches(Method method, Class<?> targetClass)` Perform static checking whether the given method matches.
    `boolean` | `matches(Method method, Class<?> targetClass, Object[] args)` Check whether there a runtime (dynamic) match for this method, which must have matched statically.

- - ### Field Detail

    - #### TRUE

          static final MethodMatcher TRUE

      Canonical instance that matches all methods.

  - ### Method Detail

    - #### matches

          boolean matches(Method method,
                        Class<?> targetClass)

      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(java.lang.reflect.Method, Class, Object[])` call) will be made.
      Parameters:
        `method` - the candidate method
        `targetClass` - the target class (may be `null`, in which case the candidate class must be taken to be the method's declaring class)
      Returns:
        whether or not this method matches statically

    - #### isRuntime

          boolean isRuntime()

      Is this MethodMatcher dynamic, that is, must a final call be made on the `matches(java.lang.reflect.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(java.lang.reflect.Method, Class, Object[])` method is required if static matching passed

    - #### matches

          boolean matches(Method method,
                        Class<?> targetClass,
                        Object[] args)

      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.

      Parameters:
        `method` - the candidate method
        `targetClass` - the target class (may be `null`, in which case the candidate class must be taken to be the method's declaring class)
        `args` - arguments to the method
      Returns:
        whether there's a runtime match
      See Also:
        `matches(Method, Class)`