MethodMatcher


1   /*
2    * Copyright 2002-2007 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.aop;
18  
19  import java.lang.reflect.Method  ;
20  
21  /**
22   * Part of a {@link Pointcut}: Checks whether the target method is eligible for advice.
23   *
24   * <p>A MethodMatcher may be evaluated <b>statically</b> or at <b>runtime</b> (dynamically).
25   * Static matching involves method and (possibly) method attributes. Dynamic matching
26   * also makes arguments for a particular call available, and any effects of running
27   * previous advice applying to the joinpoint.
28   *
29   * <p>If an implementation returns <code>false</code> from its {@link #isRuntime()}
30   * method, evaluation can be performed statically, and the result will be the same
31   * for all invocations of this method, whatever their arguments. This means that
32   * if the {@link #isRuntime()} method returns <code>false</code>, the 3-arg
33   * {@link #matches(java.lang.reflect.Method, Class, Object[])} method will never be invoked.
34   *
35   * <p>If an implementation returns <code>true</code> from its 2-arg
36   * {@link #matches(java.lang.reflect.Method, Class)} method and its {@link #isRuntime()} method
37   * returns <code>true</code>, the 3-arg {@link #matches(java.lang.reflect.Method, Class, Object[])}
38   * method will be invoked <i>immediately before each potential execution of the related advice</i>,
39   * to decide whether the advice should run. All previous advice, such as earlier interceptors
40   * in an interceptor chain, will have run, so any state changes they have produced in
41   * parameters or ThreadLocal state will be available at the time of evaluation.
42   *
43   * @author Rod Johnson
44   * @since 11.11.2003
45   * @see Pointcut
46   * @see ClassFilter
47   */
48  public interface MethodMatcher {
49  
50      /**
51       * Perform static checking whether the given method matches. If this
52       * returns <code>false</code> or if the {@link #isRuntime()} method
53       * returns <code>false</code>, no runtime check (i.e. no.
54       * {@link #matches(java.lang.reflect.Method, Class, Object[])} call) will be made.
55       * @param method the candidate method
56       * @param targetClass the target class (may be <code>null</code>, in which case
57       * the candidate class must be taken to be the method's declaring class)
58       * @return whether or not this method matches statically
59       */
60      boolean matches(Method   method, Class   targetClass);
61  
62      /**
63       * Is this MethodMatcher dynamic, that is, must a final call be made on the
64       * {@link #matches(java.lang.reflect.Method, Class, Object[])} method at
65       * runtime even if the 2-arg matches method returns <code>true</code>?
66       * <p>Can be invoked when an AOP proxy is created, and need not be invoked
67       * again before each method invocation,
68       * @return whether or not a runtime match via the 3-arg
69       * {@link #matches(java.lang.reflect.Method, Class, Object[])} method
70       * is required if static matching passed
71       */
72      boolean isRuntime();
73  
74      /**
75       * Check whether there a runtime (dynamic) match for this method,
76       * which must have matched statically.
77       * <p>This method is invoked only if the 2-arg matches method returns
78       * <code>true</code> for the given method and target class, and if the
79       * {@link #isRuntime()} method returns <code>true</code>. Invoked
80       * immediately before potential running of the advice, after any
81       * advice earlier in the advice chain has run.
82       * @param method the candidate method
83       * @param targetClass the target class (may be <code>null</code>, in which case
84       * the candidate class must be taken to be the method's declaring class)
85       * @param args arguments to the method
86       * @return whether there's a runtime match
87       * @see MethodMatcher#matches(Method, Class)
88       */
89      boolean matches(Method   method, Class   targetClass, Object  [] args);
90  
91  
92      /**
93       * Canonical instance that matches all methods.
94       */
95      MethodMatcher TRUE = TrueMethodMatcher.INSTANCE;
96  
97  }
98
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags