1 /* 2 * Copyright 2002-2017 the original author or authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 module hunt.stomp.simp.SimpMessageSendingOperations; 18 19 import hunt.collection.Map; 20 21 import hunt.stomp.MessagingException; 22 import hunt.stomp.core.MessagePostProcessor; 23 import hunt.stomp.core.MessageSendingOperations; 24 25 /** 26 * A specialization of {@link MessageSendingOperations} with methods for use with 27 * the Spring Framework support for Simple Messaging Protocols (like STOMP). 28 * 29 * <p>For more on user destinations see 30 * {@link hunt.stomp.simp.user.UserDestinationResolver 31 * UserDestinationResolver}. 32 * 33 * <p>Generally it is expected the user is the one authenticated with the 34 * WebSocket session (or by extension the user authenticated with the 35 * handshake request that started the session). However if the session is 36 * not authenticated, it is also possible to pass the session id (if known) 37 * in place of the user name. Keep in mind though that in that scenario, 38 * you must use one of the overloaded methods that accept headers making sure the 39 * {@link hunt.stomp.simp.SimpMessageHeaderAccessor#setSessionId 40 * sessionId} header has been set accordingly. 41 * 42 * @author Rossen Stoyanchev 43 * @since 4.0 44 */ 45 interface SimpMessageSendingOperations : MessageSendingOperations!(string) { 46 47 /** 48 * Send a message to the given user. 49 * @param user the user that should receive the message. 50 * @param destination the destination to send the message to. 51 * @param payload the payload to send 52 */ 53 void convertAndSendToUser(string user, string destination, Object payload); 54 55 /** 56 * Send a message to the given user. 57 * <p>By default headers are interpreted as native headers (e.g. STOMP) and 58 * are saved under a special key in the resulting Spring 59 * {@link hunt.stomp.Message Message}. In effect when the 60 * message leaves the application, the provided headers are included with it 61 * and delivered to the destination (e.g. the STOMP client or broker). 62 * <p>If the map already contains the key 63 * {@link hunt.stomp.support.NativeMessageHeaderAccessor#NATIVE_HEADERS "nativeHeaders"} 64 * or was prepared with 65 * {@link hunt.stomp.simp.SimpMessageHeaderAccessor SimpMessageHeaderAccessor} 66 * then the headers are used directly. A common expected case is providing a 67 * content type (to influence the message conversion) and native headers. 68 * This may be done as follows: 69 * <pre class="code"> 70 * SimpMessageHeaderAccessor accessor = SimpMessageHeaderAccessor.create(); 71 * accessor.setContentType(MimeTypeUtils.TEXT_PLAIN); 72 * accessor.setNativeHeader("foo", "bar"); 73 * accessor.setLeaveMutable(true); 74 * MessageHeaders headers = accessor.getMessageHeaders(); 75 * messagingTemplate.convertAndSendToUser(user, destination, payload, headers); 76 * </pre> 77 * <p><strong>Note:</strong> if the {@code MessageHeaders} are mutable as in 78 * the above example, implementations of this interface should take notice and 79 * update the headers in the same instance (rather than copy or re-create it) 80 * and then set it immutable before sending the final message. 81 * @param user the user that should receive the message (must not be {@code null}) 82 * @param destination the destination to send the message to (must not be {@code null}) 83 * @param payload the payload to send (may be {@code null}) 84 * @param headers the message headers (may be {@code null}) 85 */ 86 void convertAndSendToUser(string user, string destination, 87 Object payload, Map!(string, Object) headers); 88 89 /** 90 * Send a message to the given user. 91 * @param user the user that should receive the message (must not be {@code null}) 92 * @param destination the destination to send the message to (must not be {@code null}) 93 * @param payload the payload to send (may be {@code null}) 94 * @param postProcessor a postProcessor to post-process or modify the created message 95 */ 96 void convertAndSendToUser(string user, string destination, 97 Object payload, MessagePostProcessor postProcessor); 98 99 /** 100 * Send a message to the given user. 101 * <p>See {@link #convertAndSend(Object, Object, java.util.Map)} for important 102 * notes regarding the input headers. 103 * @param user the user that should receive the message 104 * @param destination the destination to send the message to 105 * @param payload the payload to send 106 * @param headers the message headers 107 * @param postProcessor a postProcessor to post-process or modify the created message 108 */ 109 void convertAndSendToUser(string user, string destination, 110 Object payload, Map!(string, Object) headers, MessagePostProcessor postProcessor); 111 112 }