1 module hunt.stomp.annotation; 2 3 4 /** 5 * Annotation for mapping a {@link Message} onto message-handling methods by matching 6 * to the message destination. This annotation can also be used on the type-level in 7 * which case it defines a common destination prefix or pattern for all method-level 8 * annotations including method-level 9 * {@link org.springframework.messaging.simp.annotation.SubscribeMapping @SubscribeMapping} 10 * annotations. 11 * 12 * <p>Handler methods which are annotated with this annotation are allowed to have 13 * flexible signatures. They may have arguments of the following types, in arbitrary 14 * order: 15 * <ul> 16 * <li>{@link Message} to get access to the complete message being processed.</li> 17 * <li>{@link Payload}-annotated method arguments to extract the payload of 18 * a message and optionally convert it using a 19 * {@link org.springframework.messaging.converter.MessageConverter}. 20 * The presence of the annotation is not required since it is assumed by default 21 * for method arguments that are not annotated. Payload method arguments annotated 22 * with Validation annotations (like 23 * {@link org.springframework.validation.annotation.Validated}) will be subject to 24 * JSR-303 validation.</li> 25 * <li>{@link Header}-annotated method arguments to extract a specific 26 * header value along with type conversion with a 27 * {@link org.springframework.core.convert.converter.Converter} if necessary.</li> 28 * <li>{@link Headers}-annotated argument that must also be assignable to 29 * {@link java.util.Map} for getting access to all headers.</li> 30 * <li>{@link org.springframework.messaging.MessageHeaders} arguments for 31 * getting access to all headers.</li> 32 * <li>{@link org.springframework.messaging.support.MessageHeaderAccessor} or 33 * with STOMP over WebSocket support also sub-classes such as 34 * {@link org.springframework.messaging.simp.SimpMessageHeaderAccessor} 35 * for convenient access to all method arguments.</li> 36 * <li>{@link DestinationVariable}-annotated arguments for access to template 37 * variable values extracted from the message destination (e.g. /hotels/{hotel}). 38 * Variable values will be converted to the declared method argument type.</li> 39 * <li>{@link java.security.Principal} method arguments are supported with 40 * STOMP over WebSocket messages. It reflects the user logged in to the 41 * WebSocket session on which the message was received. Regular HTTP-based 42 * authentication (e.g. Spring Security based) can be used to secure the 43 * HTTP handshake that initiates WebSocket sessions.</li> 44 * </ul> 45 * 46 * <p>A return value will get wrapped as a message and sent to a default response 47 * destination or to a custom destination specified with an {@link SendTo @SendTo} 48 * method-level annotation. Such a response may also be provided asynchronously 49 * via a {@link org.springframework.util.concurrent.ListenableFuture} return type 50 * or a corresponding JDK 8 {@link java.util.concurrent.CompletableFuture} / 51 * {@link java.util.concurrent.CompletionStage} handle. 52 * 53 * <h3>STOMP over WebSocket</h3> 54 * <p>An {@link SendTo @SendTo} annotation is not strictly required — by default 55 * the message will be sent to the same destination as the incoming message but with 56 * an additional prefix ({@code "/topic"} by default). It is also possible to use the 57 * {@link org.springframework.messaging.simp.annotation.SendToUser} annotation to 58 * have the message directed to a specific user if connected. The return value is 59 * converted with a {@link org.springframework.messaging.converter.MessageConverter}. 60 * 61 * <p><b>NOTE:</b> When using controller interfaces (e.g. for AOP proxying), 62 * make sure to consistently put <i>all</i> your mapping annotations - such as 63 * {@code @MessageMapping} and {@code @SubscribeMapping} - on 64 * the controller <i>interface</i> rather than on the implementation class. 65 * 66 * @author Rossen Stoyanchev 67 * @see hunt.stomp.simp.annotation.support.SimpAnnotationMethodMessageHandler 68 */ 69 struct MessageMapping { 70 string[] values; 71 } 72 73 74 /** 75 * Annotation that indicates a method's return value should be converted to 76 * a {@link Message} if necessary and sent to the specified destination. 77 * 78 * <p>In a typical request/reply scenario, the incoming {@link Message} may 79 * convey the destination to use for the reply. In that case, that destination 80 * should take precedence. 81 * 82 * <p>The annotation may also be placed at class-level if the provider supports 83 * it to indicate that all related methods should use this destination if none 84 * is specified otherwise. 85 * 86 * @author Rossen Stoyanchev 87 * @author Stephane Nicoll 88 */ 89 struct SendTo { 90 string[] values; 91 } 92 93 /** 94 */ 95 struct SendToUser { 96 string[] values; 97 }