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
019/**
020 * Represents a STOMP session with operations to send messages,
021 * create subscriptions and receive messages on those subscriptions.
022 *
023 * @author Rossen Stoyanchev
024 * @since 4.2
025 */
026public interface StompSession {
027
028        /**
029         * Return the id for the session.
030         */
031        String getSessionId();
032
033        /**
034         * Whether the session is connected.
035         */
036        boolean isConnected();
037
038        /**
039         * When enabled, a receipt header is automatically added to future
040         * {@code send} and {@code subscribe} operations on this session, which
041         * causes the server to return a RECEIPT. An application can then use
042         * the {@link StompSession.Receiptable Receiptable} returned from the
043         * operation to track the receipt.
044         * <p>A receipt header can also be added manually through the overloaded
045         * methods that accept {@code StompHeaders}.
046         */
047        void setAutoReceipt(boolean enabled);
048
049        /**
050         * Send a message to the specified destination, converting the payload to a
051         * {@code byte[]} with the help of a
052         * {@link org.springframework.messaging.converter.MessageConverter MessageConverter}.
053         * @param destination the destination to send a message to
054         * @param payload the message payload
055         * @return a Receiptable for tracking receipts
056         */
057        Receiptable send(String destination, Object payload);
058
059        /**
060         * An overloaded version of {@link #send(String, Object)} with full
061         * {@link StompHeaders} instead of just a destination. The headers must
062         * contain a destination and may also have other headers such as
063         * "content-type" or custom headers for the broker to propagate to
064         * subscribers, or broker-specific, non-standard headers.
065         * @param headers the message headers
066         * @param payload the message payload
067         * @return a Receiptable for tracking receipts
068         */
069        Receiptable send(StompHeaders headers, Object payload);
070
071        /**
072         * Subscribe to the given destination by sending a SUBSCRIBE frame and handle
073         * received messages with the specified {@link StompFrameHandler}.
074         * @param destination the destination to subscribe to
075         * @param handler the handler for received messages
076         * @return a handle to use to unsubscribe and/or track receipts
077         */
078        Subscription subscribe(String destination, StompFrameHandler handler);
079
080        /**
081         * An overloaded version of {@link #subscribe(String, StompFrameHandler)}
082         * with full {@link StompHeaders} instead of just a destination.
083         * @param headers the headers for the subscribe message frame
084         * @param handler the handler for received messages
085         * @return a handle to use to unsubscribe and/or track receipts
086         */
087        Subscription subscribe(StompHeaders headers, StompFrameHandler handler);
088
089        /**
090         * Send an acknowledgement whether a message was consumed or not resulting
091         * in an ACK or NACK frame respectively.
092         * <p><strong>Note:</strong> to use this when subscribing you must set the
093         * {@link StompHeaders#setAck(String) ack} header to "client" or
094         * "client-individual" in order ot use this.
095         * @param messageId the id of the message
096         * @param consumed whether the message was consumed or not
097         * @return a Receiptable for tracking receipts
098         * @since 4.3
099         */
100        Receiptable acknowledge(String messageId, boolean consumed);
101
102        /**
103         * Disconnect the session by sending a DISCONNECT frame.
104         */
105        void disconnect();
106
107
108        /**
109         * A handle to use to track receipts.
110         * @see #setAutoReceipt(boolean)
111         */
112        interface Receiptable {
113
114                /**
115                 * Return the receipt id, or {@code null} if the STOMP frame for which
116                 * the handle was returned did not have a "receipt" header.
117                 */
118                String getReceiptId();
119
120                /**
121                 * Task to invoke when a receipt is received.
122                 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null}
123                 */
124                void addReceiptTask(Runnable runnable);
125
126                /**
127                 * Task to invoke when a receipt is not received in the configured time.
128                 * @throws java.lang.IllegalArgumentException if the receiptId is {@code null}
129                 * @see org.springframework.messaging.simp.stomp.StompClientSupport#setReceiptTimeLimit(long)
130                 */
131                void addReceiptLostTask(Runnable runnable);
132        }
133
134
135        /**
136         * A handle to use to unsubscribe or to track a receipt.
137         */
138        interface Subscription extends Receiptable {
139
140                /**
141                 * Return the id for the subscription.
142                 */
143                String getSubscriptionId();
144
145                /**
146                 * Remove the subscription by sending an UNSUBSCRIBE frame.
147                 */
148                void unsubscribe();
149        }
150
151}