Update @MessageMapping Javadoc

spring-messaging/src/main/java/org/springframework/messaging/handler/annotation/MessageMapping.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -23,63 +23,60 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.springframework.messaging.Message;
+import org.springframework.messaging.simp.annotation.SendToUser;
 
 /**
- * Annotation for mapping a {@link Message} onto message-handling methods by matching
- * to the message destination. This annotation can also be used on the type-level in
- * which case it defines a common destination prefix or pattern for all method-level
- * annotations including method-level
- * {@link org.springframework.messaging.simp.annotation.SubscribeMapping @SubscribeMapping}
- * annotations.
+ * Annotation for mapping a {@link Message} onto a message-handling method by
+ * matching the declared {@link #value() patterns} to a destination extracted
+ * from the message. The annotation is supported at the type-level too, as a
+ * way of declaring a pattern prefix (or prefixes) across all class methods.
  *
- * <p>Handler methods which are annotated with this annotation are allowed to have
- * flexible signatures. They may have arguments of the following types, in arbitrary
- * order:
+ * <p>{@code @MessageMapping} methods support the following arguments:
  * <ul>
- * <li>{@link Message} to get access to the complete message being processed.</li>
- * <li>{@link Payload}-annotated method arguments to extract the payload of
- * a message and optionally convert it using a
- * {@link org.springframework.messaging.converter.MessageConverter}.
- * The presence of the annotation is not required since it is assumed by default
- * for method arguments that are not annotated. Payload method arguments annotated
- * with Validation annotations (like
- * {@link org.springframework.validation.annotation.Validated}) will be subject to
- * JSR-303 validation.</li>
- * <li>{@link Header}-annotated method arguments to extract a specific
- * header value along with type conversion with a
- * {@link org.springframework.core.convert.converter.Converter} if necessary.</li>
- * <li>{@link Headers}-annotated argument that must also be assignable to
- * {@link java.util.Map} for getting access to all headers.</li>
- * <li>{@link org.springframework.messaging.MessageHeaders} arguments for
- * getting access to all headers.</li>
- * <li>{@link org.springframework.messaging.support.MessageHeaderAccessor} or
- * with STOMP over WebSocket support also sub-classes such as
- * {@link org.springframework.messaging.simp.SimpMessageHeaderAccessor}
- * for convenient access to all method arguments.</li>
- * <li>{@link DestinationVariable}-annotated arguments for access to template
- * variable values extracted from the message destination (e.g. /hotels/{hotel}).
- * Variable values will be converted to the declared method argument type.</li>
- * <li>{@link java.security.Principal} method arguments are supported with
- * STOMP over WebSocket messages. It reflects the user logged in to the
- * WebSocket session on which the message was received. Regular HTTP-based
- * authentication (e.g. Spring Security based) can be used to secure the
- * HTTP handshake that initiates WebSocket sessions.</li>
+ * <li>{@link Payload @Payload} method argument to extract the payload of a
+ * message and have it de-serialized to the declared target type.
+ * {@code @Payload} arguments may also be annotated with Validation annotations
+ * such as {@link org.springframework.validation.annotation.Validated @Validated}
+ * and will then have JSR-303 validation applied. Keep in mind the annotation
+ * is not required to be present as it is assumed by default for arguments not
+ * handled otherwise. </li>
+ * <li>{@link DestinationVariable @DestinationVariable} method argument for
+ * access to template variable values extracted from the message destination,
+ * e.g. {@code /hotels/{hotel}}. Variable values may also be converted from
+ * String to the declared method argument type, if needed.</li>
+ * <li>{@link Header @Header} method argument to extract a specific message
+ * header value and have a
+ * {@link org.springframework.core.convert.converter.Converter Converter}
+ * applied to it to convert the value to the declared target type.</li>
+ * <li>{@link Headers @Headers} method argument that is also assignable to
+ * {@link java.util.Map} for access to all headers.</li>
+ * <li>{@link org.springframework.messaging.MessageHeaders MessageHeaders}
+ * method argument for access to all headers.</li>
+ * <li>{@link org.springframework.messaging.support.MessageHeaderAccessor
+ * MessageHeaderAccessor} method argument for access to all headers.
+ * In some processing scenarios, like STOMP over WebSocket, this may also be
+ * a specialization such as
+ * {@link org.springframework.messaging.simp.SimpMessageHeaderAccessor
+ * SimpMessageHeaderAccessor}.</li>
+ * <li>{@link Message Message<T>} for access to body and headers with the body
+ * de-serialized if necessary to match the declared type.</li>
+ * <li>{@link java.security.Principal} method arguments are supported in
+ * some processing scenarios such as STOMP over WebSocket. It reflects the
+ * authenticated user.</li>
  * </ul>
  *
- * <p>A return value will get wrapped as a message and sent to a default response
- * destination or to a custom destination specified with an {@link SendTo @SendTo}
- * method-level annotation. Such a response may also be provided asynchronously
- * via a {@link org.springframework.util.concurrent.ListenableFuture} return type
- * or a corresponding JDK 8 {@link java.util.concurrent.CompletableFuture} /
- * {@link java.util.concurrent.CompletionStage} handle.
+ * <p>How the return value is handled depends on the processing scenario.
+ * For STOMP over WebSocket, it is turned into a message and sent to a default
+ * response destination or to a custom destination specified with an
+ * {@link SendTo @SendTo} or {@link SendToUser @SendToUser} annotation.
+ * For RSocket, the response is used to reply to the stream request.
  *
- * <h3>STOMP over WebSocket</h3>
- * <p>An {@link SendTo @SendTo} annotation is not strictly required &mdash; by default
- * the message will be sent to the same destination as the incoming message but with
- * an additional prefix ({@code "/topic"} by default). It is also possible to use the
- * {@link org.springframework.messaging.simp.annotation.SendToUser} annotation to
- * have the message directed to a specific user if connected. The return value is
- * converted with a {@link org.springframework.messaging.converter.MessageConverter}.
+ * <p>Specializations of this annotation including
+ * {@link org.springframework.messaging.simp.annotation.SubscribeMapping @SubscribeMapping} or
+ * {@link org.springframework.messaging.rsocket.annotation.ConnectMapping @ConnectMapping}
+ * further narrow the mapping by message type. Both can be combined with a
+ * type-level {@code @MessageMapping} for declaring a common pattern prefix
+ * (or prefixes).
  *
  * <p><b>NOTE:</b> When using controller interfaces (e.g. for AOP proxying),
  * make sure to consistently put <i>all</i> your mapping annotations - such as
@@ -89,6 +86,7 @@ import org.springframework.messaging.Message;
  * @author Rossen Stoyanchev
  * @since 4.0
  * @see org.springframework.messaging.simp.annotation.support.SimpAnnotationMethodMessageHandler
+ * @see org.springframework.messaging.rsocket.annotation.support.RSocketMessageHandler
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
@@ -97,10 +95,15 @@ public @interface MessageMapping {
 
 	/**
 	 * Destination-based mapping expressed by this annotation.
-	 * <p>For STOMP over WebSocket messages: this is the destination of the
-	 * STOMP message (e.g. {@code "/positions"}). Ant-style path patterns
-	 * (e.g. {@code "/price.stock.*"}) and path template variables (e.g.
-	 * <code>"/price.stock.{ticker}"</code>) are also supported.
+	 * <p>For STOMP over WebSocket messages this is
+	 * {@link org.springframework.util.AntPathMatcher AntPathMatcher}-style
+	 * patterns matched against the STOMP destination of the message.
+	 * <p>for RSocket this is either
+	 * {@link org.springframework.util.AntPathMatcher AntPathMatcher} or
+	 * {@link org.springframework.web.util.pattern.PathPattern PathPattern}
+	 * based pattern, depending on which is configured, matched to the route of
+	 * the stream request.
+	 * <p>If no patterns are configured, the mapping matches all destinations.
 	 */
 	String[] value() default {};
 

spring-messaging/src/main/java/org/springframework/messaging/rsocket/annotation/ConnectMapping.java

@@ -59,7 +59,7 @@ public @interface ConnectMapping {
 	 * <p>Depending on the configured
 	 * {@link org.springframework.util.RouteMatcher RouteMatcher} the pattern may be
 	 * {@link org.springframework.util.AntPathMatcher AntPathMatcher} or
-	 * {@link org.springframework.web.util.pattern.PathPattern PathPattern} based
+	 * {@link org.springframework.web.util.pattern.PathPattern PathPattern} based.
 	 *
 	 * <p>By default this is an empty array in which case it matches all
 	 * {@link ConnectionSetupPayload} and metadata pushes.