Add the MatchResult class to MessageMatcher

Closes gh-16766

Signed-off-by: Pat McCusker <patmccusker14@gmail.com>

messaging/src/main/java/org/springframework/security/messaging/util/matcher/MessageMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,9 @@
 
 package org.springframework.security.messaging.util.matcher;
 
+import java.util.Collections;
+import java.util.Map;
+
 import org.springframework.messaging.Message;
 
 /**
@@ -50,4 +53,77 @@ public interface MessageMatcher<T> {
 	 */
 	boolean matches(Message<? extends T> message);
 
+	/**
+	 * Returns a {@link MatchResult} for this {@code MessageMatcher}. The default
+	 * implementation returns {@link Collections#emptyMap()} when
+	 * {@link MatchResult#getVariables()} is invoked.
+	 * @return the {@code MatchResult} from comparing this {@code MessageMatcher} against
+	 * the {@code Message}
+	 * @since 6.5
+	 */
+	default MatchResult matcher(Message<? extends T> message) {
+		boolean match = matches(message);
+		return new MatchResult(match, Collections.emptyMap());
+	}
+
+	/**
+	 * The result of matching against a {@code Message} contains the status, true or
+	 * false, of the match and if present, any variables extracted from the match
+	 *
+	 * @since 6.5
+	 */
+	class MatchResult {
+
+		private final boolean match;
+
+		private final Map<String, String> variables;
+
+		MatchResult(boolean match, Map<String, String> variables) {
+			this.match = match;
+			this.variables = variables;
+		}
+
+		/**
+		 * Return whether the comparison against the {@code Message} produced a successful
+		 * match
+		 */
+		public boolean isMatch() {
+			return this.match;
+		}
+
+		/**
+		 * Returns the extracted variable values where the key is the variable name and
+		 * the value is the variable value
+		 * @return a map containing key-value pairs representing extracted variable names
+		 * and variable values
+		 */
+		public Map<String, String> getVariables() {
+			return this.variables;
+		}
+
+		/**
+		 * Creates an instance of {@link MatchResult} that is a match with no variables
+		 */
+		public static MatchResult match() {
+			return new MatchResult(true, Collections.emptyMap());
+		}
+
+		/**
+		 * Creates an instance of {@link MatchResult} that is a match with the specified
+		 * variables
+		 */
+		public static MatchResult match(Map<String, String> variables) {
+			return new MatchResult(true, variables);
+		}
+
+		/**
+		 * Creates an instance of {@link MatchResult} that is not a match.
+		 * @return a {@code MatchResult} with match set to false
+		 */
+		public static MatchResult notMatch() {
+			return new MatchResult(false, Collections.emptyMap());
+		}
+
+	}
+
 }