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}