001/* 002 * Copyright 2002-2019 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.messaging.simp.stomp; 018 019import org.springframework.lang.Nullable; 020 021/** 022 * Represents a STOMP session with operations to send messages, 023 * create subscriptions and receive messages on those subscriptions. 024 * 025 * @author Rossen Stoyanchev 026 * @since 4.2 027 */ 028public interface StompSession { 029 030 /** 031 * Return the id for the session. 032 */ 033 String getSessionId(); 034 035 /** 036 * Whether the session is connected. 037 */ 038 boolean isConnected(); 039 040 /** 041 * When enabled, a receipt header is automatically added to future 042 * {@code send} and {@code subscribe} operations on this session, which 043 * causes the server to return a RECEIPT. An application can then use 044 * the {@link StompSession.Receiptable Receiptable} returned from the 045 * operation to track the receipt. 046 * <p>A receipt header can also be added manually through the overloaded 047 * methods that accept {@code StompHeaders}. 048 */ 049 void setAutoReceipt(boolean enabled); 050 051 /** 052 * Send a message to the specified destination, converting the payload to a 053 * {@code byte[]} with the help of a 054 * {@link org.springframework.messaging.converter.MessageConverter MessageConverter}. 055 * @param destination the destination to send a message to 056 * @param payload the message payload 057 * @return a Receiptable for tracking receipts 058 */ 059 Receiptable send(String destination, Object payload); 060 061 /** 062 * An overloaded version of {@link #send(String, Object)} with full 063 * {@link StompHeaders} instead of just a destination. The headers must 064 * contain a destination and may also have other headers such as 065 * "content-type" or custom headers for the broker to propagate to 066 * subscribers, or broker-specific, non-standard headers. 067 * @param headers the message headers 068 * @param payload the message payload 069 * @return a Receiptable for tracking receipts 070 */ 071 Receiptable send(StompHeaders headers, Object payload); 072 073 /** 074 * Subscribe to the given destination by sending a SUBSCRIBE frame and handle 075 * received messages with the specified {@link StompFrameHandler}. 076 * @param destination the destination to subscribe to 077 * @param handler the handler for received messages 078 * @return a handle to use to unsubscribe and/or track receipts 079 */ 080 Subscription subscribe(String destination, StompFrameHandler handler); 081 082 /** 083 * An overloaded version of {@link #subscribe(String, StompFrameHandler)} 084 * with full {@link StompHeaders} instead of just a destination. 085 * @param headers the headers for the subscribe message frame 086 * @param handler the handler for received messages 087 * @return a handle to use to unsubscribe and/or track receipts 088 */ 089 Subscription subscribe(StompHeaders headers, StompFrameHandler handler); 090 091 /** 092 * Send an acknowledgement whether a message was consumed or not resulting 093 * in an ACK or NACK frame respectively. 094 * <p><strong>Note:</strong> to use this when subscribing you must set the 095 * {@link StompHeaders#setAck(String) ack} header to "client" or 096 * "client-individual" in order ot use this. 097 * @param messageId the id of the message 098 * @param consumed whether the message was consumed or not 099 * @return a Receiptable for tracking receipts 100 * @since 4.3 101 */ 102 Receiptable acknowledge(String messageId, boolean consumed); 103 104 /** 105 * An overloaded version of {@link #acknowledge(String, boolean)} with 106 * full {@link StompHeaders} instead of just a {@code messageId}. 107 * @param headers the headers for the ACK or NACK message frame 108 * @param consumed whether the message was consumed or not 109 * @return a Receiptable for tracking receipts 110 * @since 5.0.5 111 */ 112 Receiptable acknowledge(StompHeaders headers, boolean consumed); 113 114 /** 115 * Disconnect the session by sending a DISCONNECT frame. 116 */ 117 void disconnect(); 118 119 /** 120 * Variant of {@link #disconnect()} with headers. 121 * @param headers the headers for the disconnect message frame 122 * @since 5.2.2 123 */ 124 void disconnect(StompHeaders headers); 125 126 127 /** 128 * A handle to use to track receipts. 129 * @see #setAutoReceipt(boolean) 130 */ 131 interface Receiptable { 132 133 /** 134 * Return the receipt id, or {@code null} if the STOMP frame for which 135 * the handle was returned did not have a "receipt" header. 136 */ 137 @Nullable 138 String getReceiptId(); 139 140 /** 141 * Task to invoke when a receipt is received. 142 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} 143 */ 144 void addReceiptTask(Runnable runnable); 145 146 /** 147 * Task to invoke when a receipt is not received in the configured time. 148 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null} 149 * @see org.springframework.messaging.simp.stomp.StompClientSupport#setReceiptTimeLimit(long) 150 */ 151 void addReceiptLostTask(Runnable runnable); 152 } 153 154 155 /** 156 * A handle to use to unsubscribe or to track a receipt. 157 */ 158 interface Subscription extends Receiptable { 159 160 /** 161 * Return the id for the subscription. 162 */ 163 @Nullable 164 String getSubscriptionId(); 165 166 /** 167 * Return the headers used on the SUBSCRIBE frame. 168 * @since 5.0 169 */ 170 StompHeaders getSubscriptionHeaders(); 171 172 /** 173 * Remove the subscription by sending an UNSUBSCRIBE frame. 174 */ 175 void unsubscribe(); 176 177 /** 178 * Alternative to {@link #unsubscribe()} with additional custom headers 179 * to send to the server. 180 * <p><strong>Note:</strong> There is no need to set the subscription id. 181 * @param headers the custom headers, if any 182 * @since 5.0 183 */ 184 void unsubscribe(@Nullable StompHeaders headers); 185 } 186 187}