|
1 | 1 | /* |
2 | | - * Copyright 2002-2019 the original author or authors. |
| 2 | + * Copyright 2002-2023 the original author or authors. |
3 | 3 | * |
4 | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
5 | 5 | * you may not use this file except in compliance with the License. |
|
21 | 21 | /** |
22 | 22 | * Part of a {@link Pointcut}: Checks whether the target method is eligible for advice. |
23 | 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. |
| 24 | + * <p>A {@code MethodMatcher} may be evaluated <b>statically</b> or at <b>runtime</b> |
| 25 | + * (dynamically). Static matching involves a method and (possibly) method attributes. |
| 26 | + * Dynamic matching also makes arguments for a particular call available, and any |
| 27 | + * effects of running previous advice applying to the joinpoint. |
28 | 28 | * |
29 | 29 | * <p>If an implementation returns {@code false} from its {@link #isRuntime()} |
30 | 30 | * method, evaluation can be performed statically, and the result will be the same |
31 | 31 | * for all invocations of this method, whatever their arguments. This means that |
32 | 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. |
| 33 | + * {@link #matches(Method, Class, Object[])} method will never be invoked. |
34 | 34 | * |
35 | 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. |
| 36 | + * {@link #matches(Method, Class)} method and its {@link #isRuntime()} method |
| 37 | + * returns {@code true}, the 3-arg {@link #matches(Method, Class, Object[])} |
| 38 | + * method will be invoked <i>immediately before each potential execution of the |
| 39 | + * related advice</i> to decide whether the advice should run. All previous advice, |
| 40 | + * such as earlier interceptors in an interceptor chain, will have run, so any |
| 41 | + * state changes they have produced in parameters or {@code ThreadLocal} state will |
| 42 | + * be available at the time of evaluation. |
42 | 43 | * |
43 | 44 | * <p>Concrete implementations of this interface typically should provide proper |
44 | 45 | * implementations of {@link Object#equals(Object)} and {@link Object#hashCode()} |
|
53 | 54 | public interface MethodMatcher { |
54 | 55 |
|
55 | 56 | /** |
56 | | - * Perform static checking whether the given method matches. |
57 | | - * <p>If this returns {@code false} or if the {@link #isRuntime()} |
58 | | - * method returns {@code false}, no runtime check (i.e. no |
59 | | - * {@link #matches(java.lang.reflect.Method, Class, Object[])} call) |
60 | | - * will be made. |
| 57 | + * Perform static checking to determine whether the given method matches. |
| 58 | + * <p>If this method returns {@code false} or if {@link #isRuntime()} |
| 59 | + * returns {@code false}, no runtime check (i.e. no |
| 60 | + * {@link #matches(Method, Class, Object[])} call) will be made. |
61 | 61 | * @param method the candidate method |
62 | 62 | * @param targetClass the target class |
63 | 63 | * @return whether this method matches statically |
64 | 64 | */ |
65 | 65 | boolean matches(Method method, Class<?> targetClass); |
66 | 66 |
|
67 | 67 | /** |
68 | | - * Is this MethodMatcher dynamic, that is, must a final call be made on the |
69 | | - * {@link #matches(java.lang.reflect.Method, Class, Object[])} method at |
70 | | - * runtime even if the 2-arg matches method returns {@code true}? |
| 68 | + * Is this {@code MethodMatcher} dynamic, that is, must a final check be made |
| 69 | + * via the {@link #matches(Method, Class, Object[])} method at runtime even |
| 70 | + * if {@link #matches(Method, Class)} returns {@code true}? |
71 | 71 | * <p>Can be invoked when an AOP proxy is created, and need not be invoked |
72 | | - * again before each method invocation, |
73 | | - * @return whether a runtime match via the 3-arg |
74 | | - * {@link #matches(java.lang.reflect.Method, Class, Object[])} method |
| 72 | + * again before each method invocation. |
| 73 | + * @return whether a runtime match via {@link #matches(Method, Class, Object[])} |
75 | 74 | * is required if static matching passed |
76 | 75 | */ |
77 | 76 | boolean isRuntime(); |
78 | 77 |
|
79 | 78 | /** |
80 | | - * Check whether there a runtime (dynamic) match for this method, |
81 | | - * which must have matched statically. |
82 | | - * <p>This method is invoked only if the 2-arg matches method returns |
83 | | - * {@code true} for the given method and target class, and if the |
84 | | - * {@link #isRuntime()} method returns {@code true}. Invoked |
85 | | - * immediately before potential running of the advice, after any |
| 79 | + * Check whether there is a runtime (dynamic) match for this method, which |
| 80 | + * must have matched statically. |
| 81 | + * <p>This method is invoked only if {@link #matches(Method, Class)} returns |
| 82 | + * {@code true} for the given method and target class, and if |
| 83 | + * {@link #isRuntime()} returns {@code true}. |
| 84 | + * <p>Invoked immediately before potential running of the advice, after any |
86 | 85 | * advice earlier in the advice chain has run. |
87 | 86 | * @param method the candidate method |
88 | 87 | * @param targetClass the target class |
89 | 88 | * @param args arguments to the method |
90 | 89 | * @return whether there's a runtime match |
91 | | - * @see MethodMatcher#matches(Method, Class) |
| 90 | + * @see #matches(Method, Class) |
92 | 91 | */ |
93 | 92 | boolean matches(Method method, Class<?> targetClass, Object... args); |
94 | 93 |
|
95 | 94 |
|
96 | 95 | /** |
97 | | - * Canonical instance that matches all methods. |
| 96 | + * Canonical instance of a {@code MethodMatcher} that matches all methods. |
98 | 97 | */ |
99 | 98 | MethodMatcher TRUE = TrueMethodMatcher.INSTANCE; |
100 | 99 |
|
|
0 commit comments