1 /*
2 * Copyright 2002-2012 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} 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}, 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} from its 2-arg
36 * {@link #matches(java.lang.reflect.Method, Class)} method and its {@link #isRuntime()} method
37 * returns {@code true}, 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} or if the {@link #isRuntime()} method
53 * returns {@code false}, 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}, 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}?
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} for the given method and target class, and if the
79 * {@link #isRuntime()} method returns {@code true}. 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}, 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 }