Document pattern matching support in NameMatchMethodPointcut

Closes gh-31500

spring-aop/src/main/java/org/springframework/aop/support/NameMatchMethodPointcut.java

@@ -26,59 +26,68 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.PatternMatchUtils;
 
 /**
- * Pointcut bean for simple method name matches, as an alternative to regexp patterns.
+ * Pointcut bean for simple method name matches, as an alternative to regular
+ * expression patterns.
+ *
+ * <p>Each configured method name can be an exact method name or a method name
+ * pattern (see {@link #isMatch(String, String)} for details on the supported
+ * pattern styles).
  *
  * <p>Does not handle overloaded methods: all methods with a given name will be eligible.
  *
  * @author Juergen Hoeller
  * @author Rod Johnson
  * @author Rob Harrop
+ * @author Sam Brannen
  * @since 11.02.2004
  * @see #isMatch
+ * @see JdkRegexpMethodPointcut
  */
 @SuppressWarnings("serial")
 public class NameMatchMethodPointcut extends StaticMethodMatcherPointcut implements Serializable {
 
-	private List<String> mappedNames = new ArrayList<>();
+	private List<String> mappedNamePatterns = new ArrayList<>();
 
 
 	/**
-	 * Convenience method when we have only a single method name to match.
+	 * Convenience method for configuring a single method name pattern.
-	 * Use either this method or {@code setMappedNames}, not both.
+	 * <p>Use either this method or {@link #setMappedNames(String...)}, but not both.
 	 * @see #setMappedNames
 	 */
-	public void setMappedName(String mappedName) {
+	public void setMappedName(String mappedNamePattern) {
-		setMappedNames(mappedName);
+		setMappedNames(mappedNamePattern);
 	}
 
 	/**
-	 * Set the method names defining methods to match.
+	 * Set the method name patterns defining methods to match.
-	 * Matching will be the union of all these; if any match,
+	 * <p>Matching will be the union of all these; if any match, the pointcut matches.
-	 * the pointcut matches.
+	 * @see #setMappedName(String)
 	 */
-	public void setMappedNames(String... mappedNames) {
+	public void setMappedNames(String... mappedNamePatterns) {
-		this.mappedNames = new ArrayList<>(Arrays.asList(mappedNames));
+		this.mappedNamePatterns = new ArrayList<>(Arrays.asList(mappedNamePatterns));
 	}
 
 	/**
-	 * Add another eligible method name, in addition to those already named.
+	 * Add another method name pattern, in addition to those already configured.
-	 * Like the set methods, this method is for use when configuring proxies,
+	 * <p>Like the "set" methods, this method is for use when configuring proxies,
 	 * before a proxy is used.
-	 * <p><b>NB:</b> This method does not work after the proxy is in
+	 * <p><b>NOTE:</b> This method does not work after the proxy is in use, since
-	 * use, as advice chains will be cached.
+	 * advice chains will be cached.
-	 * @param name the name of the additional method that will match
+	 * @param mappedNamePattern the additional method name pattern
-	 * @return this pointcut to allow for multiple additions in one line
+	 * @return this pointcut to allow for method chaining
+	 * @see #setMappedNames(String...)
+	 * @see #setMappedName(String)
 	 */
-	public NameMatchMethodPointcut addMethodName(String name) {
+	public NameMatchMethodPointcut addMethodName(String mappedNamePattern) {
-		this.mappedNames.add(name);
+		this.mappedNamePatterns.add(mappedNamePattern);
 		return this;
 	}
 
 
 	@Override
 	public boolean matches(Method method, Class<?> targetClass) {
-		for (String mappedName : this.mappedNames) {
+		for (String mappedNamePattern : this.mappedNamePatterns) {
-			if (mappedName.equals(method.getName()) || isMatch(method.getName(), mappedName)) {
+			if (mappedNamePattern.equals(method.getName()) || isMatch(method.getName(), mappedNamePattern)) {
 				return true;
 			}
 		}
@@ -86,33 +95,34 @@ public class NameMatchMethodPointcut extends StaticMethodMatcherPointcut impleme
 	}
 
 	/**
-	 * Return if the given method name matches the mapped name.
+	 * Determine if the given method name matches the mapped name pattern.
-	 * <p>The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches,
+	 * <p>The default implementation checks for {@code xxx*}, {@code *xxx},
-	 * as well as direct equality. Can be overridden in subclasses.
+	 * {@code *xxx*}, and {@code xxx*yyy} matches, as well as direct equality.
-	 * @param methodName the method name of the class
+	 * <p>Can be overridden in subclasses.
-	 * @param mappedName the name in the descriptor
+	 * @param methodName the method name to check
-	 * @return if the names match
+	 * @param mappedNamePattern the method name pattern
-	 * @see org.springframework.util.PatternMatchUtils#simpleMatch(String, String)
+	 * @return {@code true} if the method name matches the pattern
+	 * @see PatternMatchUtils#simpleMatch(String, String)
 	 */
-	protected boolean isMatch(String methodName, String mappedName) {
+	protected boolean isMatch(String methodName, String mappedNamePattern) {
-		return PatternMatchUtils.simpleMatch(mappedName, methodName);
+		return PatternMatchUtils.simpleMatch(mappedNamePattern, methodName);
 	}
 
 
 	@Override
 	public boolean equals(@Nullable Object other) {
 		return (this == other || (other instanceof NameMatchMethodPointcut that &&
-				this.mappedNames.equals(that.mappedNames)));
+				this.mappedNamePatterns.equals(that.mappedNamePatterns)));
 	}
 
 	@Override
 	public int hashCode() {
-		return this.mappedNames.hashCode();
+		return this.mappedNamePatterns.hashCode();
 	}
 
 	@Override
 	public String toString() {
-		return getClass().getName() + ": " + this.mappedNames;
+		return getClass().getName() + ": " + this.mappedNamePatterns;
 	}
 
 }