Refine destination semantics for msg-handling methods

After this change, annotated message handling methods configured to use
a destination prefix (e.g. "/app") no longer have to include the prefix
in their mapping. For example if a client sends a message to "/app/foo"
the annotated methods should be mapped with @MessageMapping("/foo").

Author: rstoyanchev

spring-messaging/src/main/java/org/springframework/messaging/MessageHeaders.java

@@ -25,6 +25,7 @@
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -149,7 +150,10 @@ public boolean equals(Object object) {
 
 	@Override
 	public String toString() {
-		return this.headers.toString();
+		Map<String, Object> map = new LinkedHashMap<String, Object>(this.headers);
+		map.put(ID,  map.remove(ID)); // remove and add again at the end
+		map.put(TIMESTAMP, map.remove(TIMESTAMP));
+		return map.toString();
 	}
 
 	/*

spring-messaging/src/main/java/org/springframework/messaging/handler/method/HandlerMethodReturnValueHandlerComposite.java

@@ -19,6 +19,8 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
 import org.springframework.core.MethodParameter;
 import org.springframework.messaging.Message;
 import org.springframework.util.Assert;
@@ -30,6 +32,8 @@
  */
 public class HandlerMethodReturnValueHandlerComposite implements HandlerMethodReturnValueHandler {
 
+	private static Log logger = LogFactory.getLog(HandlerMethodReturnValueHandlerComposite.class);
+
 	private final List<HandlerMethodReturnValueHandler> returnValueHandlers = new ArrayList<HandlerMethodReturnValueHandler>();
 
 
@@ -61,6 +65,9 @@ public boolean supportsReturnType(MethodParameter returnType) {
 	private HandlerMethodReturnValueHandler getReturnValueHandler(MethodParameter returnType) {
 		for (HandlerMethodReturnValueHandler handler : this.returnValueHandlers) {
 			if (handler.supportsReturnType(returnType)) {
+				if (logger.isTraceEnabled()) {
+					logger.trace("Processing return value with " + handler);
+				}
 				return handler;
 			}
 		}
@@ -72,7 +79,7 @@ public void handleReturnValue(Object returnValue, MethodParameter returnType, Me
 			throws Exception {
 
 		HandlerMethodReturnValueHandler handler = getReturnValueHandler(returnType);
-		Assert.notNull(handler, "Unknown return value type [" + returnType.getParameterType().getName() + "]");
+		Assert.notNull(handler, "No handler for return value type [" + returnType.getParameterType().getName() + "]");
 		handler.handleReturnValue(returnValue, returnType, message);
 	}
 

spring-messaging/src/main/java/org/springframework/messaging/handler/method/InvocableHandlerMethod.java

@@ -104,16 +104,17 @@ public final Object invoke(Message<?> message, Object... providedArgs) throws Ex
 		Object[] args = getMethodArgumentValues(message, providedArgs);
 
 		if (logger.isTraceEnabled()) {
-			StringBuilder builder = new StringBuilder("Invoking [");
-			builder.append(this.getMethod().getName()).append("] method with arguments ");
-			builder.append(Arrays.asList(args));
-			logger.trace(builder.toString());
+			StringBuilder sb = new StringBuilder("Invoking [");
+			sb.append(this.getBeanType().getSimpleName()).append(".");
+			sb.append(this.getMethod().getName()).append("] method with arguments ");
+			sb.append(Arrays.asList(args));
+			logger.trace(sb.toString());
 		}
 
 		Object returnValue = invoke(args);
 
 		if (logger.isTraceEnabled()) {
-			logger.trace("Method [" + this.getMethod().getName() + "] returned [" + returnValue + "]");
+			logger.trace("Method returned [" + returnValue + "]");
 		}
 
 		return returnValue;

spring-messaging/src/main/java/org/springframework/messaging/simp/annotation/support/ReplyToMethodReturnValueHandler.java

@@ -16,7 +16,10 @@
 
 package org.springframework.messaging.simp.annotation.support;
 
+import java.lang.annotation.Annotation;
+
 import org.springframework.core.MethodParameter;
+import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.messaging.Message;
 import org.springframework.messaging.MessageChannel;
 import org.springframework.messaging.core.MessagePostProcessor;
@@ -27,6 +30,7 @@
 import org.springframework.messaging.simp.annotation.ReplyToUser;
 import org.springframework.messaging.support.MessageBuilder;
 import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
 
 
 /**
@@ -46,17 +50,23 @@ public class ReplyToMethodReturnValueHandler implements HandlerMethodReturnValue
 
 	private final SimpMessageSendingOperations messagingTemplate;
 
+	private final boolean annotationRequired;
+
 
-	public ReplyToMethodReturnValueHandler(SimpMessageSendingOperations messagingTemplate) {
+	public ReplyToMethodReturnValueHandler(SimpMessageSendingOperations messagingTemplate, boolean annotationRequired) {
 		Assert.notNull(messagingTemplate, "messagingTemplate is required");
 		this.messagingTemplate = messagingTemplate;
+		this.annotationRequired = annotationRequired;
 	}
 
 
 	@Override
 	public boolean supportsReturnType(MethodParameter returnType) {
-		return ((returnType.getMethodAnnotation(ReplyTo.class) != null)
-				|| (returnType.getMethodAnnotation(ReplyToUser.class) != null));
+		if ((returnType.getMethodAnnotation(ReplyTo.class) != null) ||
+				(returnType.getMethodAnnotation(ReplyToUser.class) != null)) {
+			return true;
+		}
+		return (!this.annotationRequired);
 	}
 
 	@Override
@@ -72,23 +82,32 @@ public void handleReturnValue(Object returnValue, MethodParameter returnType, Me
 		String sessionId = inputHeaders.getSessionId();
 		MessagePostProcessor postProcessor = new SessionHeaderPostProcessor(sessionId);
 
-		ReplyTo replyTo = returnType.getMethodAnnotation(ReplyTo.class);
-		if (replyTo != null) {
-			for (String destination : replyTo.value()) {
-				this.messagingTemplate.convertAndSend(destination, returnValue, postProcessor);
-			}
-		}
-
 		ReplyToUser replyToUser = returnType.getMethodAnnotation(ReplyToUser.class);
 		if (replyToUser != null) {
 			if (inputHeaders.getUser() == null) {
 				throw new MissingSessionUserException(inputMessage);
 			}
 			String user = inputHeaders.getUser().getName();
-			for (String destination : replyToUser.value()) {
+			for (String destination : getDestinations(replyToUser, inputHeaders.getDestination())) {
 				this.messagingTemplate.convertAndSendToUser(user, destination, returnValue, postProcessor);
 			}
+			return;
+		}
+
+		ReplyTo replyTo = returnType.getMethodAnnotation(ReplyTo.class);
+		if (replyTo != null) {
+			for (String destination : getDestinations(replyTo, inputHeaders.getDestination())) {
+				this.messagingTemplate.convertAndSend(destination, returnValue, postProcessor);
+			}
+			return;
 		}
+
+		this.messagingTemplate.convertAndSend(inputHeaders.getDestination(), returnValue, postProcessor);
+	}
+
+	private String[] getDestinations(Annotation annot, String inputDestination) {
+		String[] destinations = (String[]) AnnotationUtils.getValue(annot);
+		return ObjectUtils.isEmpty(destinations) ? new String[] { inputDestination } : destinations;
 	}
 
 
@@ -107,4 +126,10 @@ public Message<?> postProcessMessage(Message<?> message) {
 			return MessageBuilder.withPayloadAndHeaders(message.getPayload(), headers).build();
 		}
 	}
+
+	@Override
+	public String toString() {
+		return "ReplyToMethodReturnValueHandler [annotationRequired=" + annotationRequired + "]";
+	}
+
 }

spring-messaging/src/main/java/org/springframework/messaging/simp/config/MessageBrokerConfigurer.java

@@ -47,16 +47,37 @@ public MessageBrokerConfigurer(MessageChannel webSocketResponseChannel) {
 		this.webSocketResponseChannel = webSocketResponseChannel;
 	}
 
+	/**
+	 * Enable a simple message broker and configure one or more prefixes to filter
+	 * destinations targeting the broker (e.g. destinations prefixed with "/topic").
+	 */
 	public SimpleBrokerRegistration enableSimpleBroker(String... destinationPrefixes) {
 		this.simpleBroker = new SimpleBrokerRegistration(this.webSocketResponseChannel, destinationPrefixes);
 		return this.simpleBroker;
 	}
 
+	/**
+	 * Enable a STOMP broker relay and configure the destination prefixes supported by the
+	 * message broker. Check the STOMP documentation of the message broker for supported
+	 * destinations.
+	 */
 	public StompBrokerRelayRegistration enableStompBrokerRelay(String... destinationPrefixes) {
 		this.stompRelay = new StompBrokerRelayRegistration(this.webSocketResponseChannel, destinationPrefixes);
 		return this.stompRelay;
 	}
 
+	/**
+	 * Configure one or more prefixes to filter destinations targeting annotated
+	 * application methods. For example destinations prefixed with "/app" may be processed
+	 * by annotated application methods while other destinations may target the message
+	 * broker (e.g. "/topic", "/queue").
+	 * <p>
+	 * When messages are processed, the matching prefix is removed from the destination in
+	 * order to form the lookup path. This means annotations should not contain the
+	 * destination prefix.
+	 * <p>
+	 * Prefixes that do not have a trailing slash will have one automatically appended.
+	 */
 	public MessageBrokerConfigurer setAnnotationMethodDestinationPrefixes(String... destinationPrefixes) {
 		this.annotationMethodDestinationPrefixes = destinationPrefixes;
 		return this;

spring-messaging/src/main/java/org/springframework/messaging/simp/handler/AbstractBrokerMessageHandler.java

@@ -141,7 +141,7 @@ public final void handleMessage(Message<?> message) {
 		}
 
 		if (logger.isTraceEnabled()) {
-			logger.trace("Processing message: " + message);
+			logger.trace("Message " + message);
 		}
 
 		handleMessageInternal(message);

spring-messaging/src/main/java/org/springframework/messaging/simp/handler/AbstractSubscriptionRegistry.java

@@ -56,7 +56,8 @@ public final void registerSubscription(Message<?> message) {
 			return;
 		}
 		if (logger.isDebugEnabled()) {
-			logger.debug("Subscribe request: " + message);
+			logger.debug("Adding subscription id=" + headers.getSubscriptionId()
+					+ ", destination=" + headers.getDestination());
 		}
 		addSubscriptionInternal(sessionId, subscriptionId, destination, message);
 	}