1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
/*
* Copyright 2002-2019 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.messaging.simp.stomp;
/**
* Represents a STOMP session with operations to send messages,
* create subscriptions and receive messages on those subscriptions.
*
* @author Rossen Stoyanchev
* @since 4.2
*/
public interface StompSession {
/**
* Return the id for the session.
*/
String getSessionId();
/**
* Whether the session is connected.
*/
boolean isConnected();
/**
* When enabled, a receipt header is automatically added to future
* {@code send} and {@code subscribe} operations on this session, which
* causes the server to return a RECEIPT. An application can then use
* the {@link StompSession.Receiptable Receiptable} returned from the
* operation to track the receipt.
* <p>A receipt header can also be added manually through the overloaded
* methods that accept {@code StompHeaders}.
*/
void setAutoReceipt(boolean enabled);
/**
* Send a message to the specified destination, converting the payload to a
* {@code byte[]} with the help of a
* {@link org.springframework.messaging.converter.MessageConverter MessageConverter}.
* @param destination the destination to send a message to
* @param payload the message payload
* @return a Receiptable for tracking receipts
*/
Receiptable send(String destination, Object payload);
/**
* An overloaded version of {@link #send(String, Object)} with full
* {@link StompHeaders} instead of just a destination. The headers must
* contain a destination and may also have other headers such as
* "content-type" or custom headers for the broker to propagate to
* subscribers, or broker-specific, non-standard headers.
* @param headers the message headers
* @param payload the message payload
* @return a Receiptable for tracking receipts
*/
Receiptable send(StompHeaders headers, Object payload);
/**
* Subscribe to the given destination by sending a SUBSCRIBE frame and handle
* received messages with the specified {@link StompFrameHandler}.
* @param destination the destination to subscribe to
* @param handler the handler for received messages
* @return a handle to use to unsubscribe and/or track receipts
*/
Subscription subscribe(String destination, StompFrameHandler handler);
/**
* An overloaded version of {@link #subscribe(String, StompFrameHandler)}
* with full {@link StompHeaders} instead of just a destination.
* @param headers the headers for the subscribe message frame
* @param handler the handler for received messages
* @return a handle to use to unsubscribe and/or track receipts
*/
Subscription subscribe(StompHeaders headers, StompFrameHandler handler);
/**
* Send an acknowledgement whether a message was consumed or not resulting
* in an ACK or NACK frame respectively.
* <p><strong>Note:</strong> to use this when subscribing you must set the
* {@link StompHeaders#setAck(String) ack} header to "client" or
* "client-individual" in order ot use this.
* @param messageId the id of the message
* @param consumed whether the message was consumed or not
* @return a Receiptable for tracking receipts
* @since 4.3
*/
Receiptable acknowledge(String messageId, boolean consumed);
/**
* Disconnect the session by sending a DISCONNECT frame.
*/
void disconnect();
/**
* A handle to use to track receipts.
* @see #setAutoReceipt(boolean)
*/
interface Receiptable {
/**
* Return the receipt id, or {@code null} if the STOMP frame for which
* the handle was returned did not have a "receipt" header.
*/
String getReceiptId();
/**
* Task to invoke when a receipt is received.
* @throws java.lang.IllegalArgumentException if the receiptId is {@code null}
*/
void addReceiptTask(Runnable runnable);
/**
* Task to invoke when a receipt is not received in the configured time.
* @throws java.lang.IllegalArgumentException if the receiptId is {@code null}
* @see org.springframework.messaging.simp.stomp.StompClientSupport#setReceiptTimeLimit(long)
*/
void addReceiptLostTask(Runnable runnable);
}
/**
* A handle to use to unsubscribe or to track a receipt.
*/
interface Subscription extends Receiptable {
/**
* Return the id for the subscription.
*/
String getSubscriptionId();
/**
* Remove the subscription by sending an UNSUBSCRIBE frame.
*/
void unsubscribe();
}
}
|
