-
Notifications
You must be signed in to change notification settings - Fork 27
/
StompClientConnection.java
327 lines (289 loc) · 13.2 KB
/
StompClientConnection.java
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
/*
* Copyright (c) 2011-2015 The original author or authors
* ------------------------------------------------------
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Apache License v2.0 which accompanies this distribution.
*
* The Eclipse Public License is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* The Apache License v2.0 is available at
* http://www.opensource.org/licenses/apache2.0.php
*
* You may elect to redistribute this code under either of these licenses.
*/
package io.vertx.ext.stomp;
import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.buffer.Buffer;
import java.util.Map;
/**
* Once a connection to the STOMP server has been made, client receives a {@link StompClientConnection}, that let
* send and receive STOMP frames.
*
* @author <a href="http://escoffier.me">Clement Escoffier</a>
*/
@VertxGen
public interface StompClientConnection {
/**
* @return the session id.
*/
String session();
/**
* @return the STOMP protocol version negotiated with the server.
*/
String version();
/**
* Closes the connection without sending the {@code DISCONNECT} frame.
*
* @see #disconnect()
*/
void close();
/**
* @return the server name.
*/
String server();
/**
* Sends a {@code SEND} frame to the server.
*
* @param headers the headers, must not be {@code null}
* @param body the body, may be {@code null}
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> send(Map<String, String> headers, Buffer body);
/**
* Sends a {@code SEND} frame to the server to the given destination. The message does not have any other header.
*
* @param destination the destination, must not be {@code null}
* @param body the body, may be {@code null}
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> send(String destination, Buffer body);
/**
* Sends the given frame to the server.
*
* @param frame the frame
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> send(Frame frame);
/**
* Sends a {@code SEND} frame to the server to the given destination.
*
* @param destination the destination, must not be {@code null}
* @param body the body, may be {@code null}
* @param headers the header. The {@code destination} header is replaced by the value given to the {@code
* destination} parameter
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> send(String destination, Map<String, String> headers, Buffer body);
/**
* Subscribes to the given destination. This destination is used as subscription id.
*
* @param destination the destination, must not be {@code null}
* @param handler the handler invoked when a message is received on the given destination. Must not be {@code null}.
* @return a future resolved with the subscription id when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<String> subscribe(String destination, Handler<Frame> handler);
/**
* Subscribes to the given destination.
*
* @param destination the destination, must not be {@code null}.
* @param headers the headers to configure the subscription. It may contain the {@code ack}
* header to configure the acknowledgment policy. If the given set of headers contains the
* {@code id} header, this value is used as subscription id.
* @param handler the handler invoked when a message is received on the given destination. Must not be {@code null}.
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<String> subscribe(String destination, Map<String, String> headers, Handler<Frame> handler);
/**
* Un-subscribes from the given destination. This method only works if the subscription did not specifies a
* subscription id (using the {@code id} header).
*
* @param destination the destination
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> unsubscribe(String destination);
/**
* Un-subscribes from the given destination. This method computes the subscription id as follows. If the given
* headers contains the {@code id} header, the header value is used. Otherwise the destination is used.
*
* @param destination the destination
* @param headers the headers
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> unsubscribe(String destination, Map<String, String> headers);
/**
* Sets a handler notified when an {@code ERROR} frame is received by the client. The handler receives the {@code
* ERROR} frame and a reference on the {@link StompClientConnection}.
*
* @param handler the handler
* @return the current {@link StompClientConnection}
*/
StompClientConnection errorHandler(Handler<Frame> handler);
/**
* Sets a handler notified when the STOMP connection is closed.
*
* @param handler the handler
* @return the current {@link StompClientConnection}
*/
@Fluent
StompClientConnection closeHandler(Handler<StompClientConnection> handler);
/**
* Sets a handler notified when the server does not respond to a {@code ping} request in time. In other
* words, this handler is invoked when the heartbeat has detected a connection failure with the server.
* The handler can decide to reconnect to the server.
*
* @param handler the handler
* @return the current {@link StompClientConnection} receiving the dropped connection.
*/
@Fluent
StompClientConnection connectionDroppedHandler(Handler<StompClientConnection> handler);
/**
* Sets a handler that let customize the behavior when a ping needs to be sent to the server. Be aware that
* changing the default behavior may break the compliance with the STOMP specification.
*
* @param handler the handler
* @return the current {@link StompClientConnection}
*/
@Fluent
StompClientConnection pingHandler(Handler<StompClientConnection> handler);
/**
* Begins a transaction.
*
* @param id the transaction id, must not be {@code null}
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> beginTX(String id);
/**
* Begins a transaction.
*
* @param id the transaction id, must not be {@code null}
* @param headers additional headers to send to the server. The {@code transaction} header is replaced by the value
* passed in the @{code id} parameter
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> beginTX(String id, Map<String, String> headers);
/**
* Commits a transaction.
*
* @param id the transaction id, must not be {@code null}
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> commit(String id);
/**
* Commits a transaction.
*
* @param id the transaction id, must not be {@code null}
* @param headers additional headers to send to the server. The {@code transaction} header is replaced by the
* value passed in the @{code id} parameter
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> commit(String id, Map<String, String> headers);
/**
* Aborts a transaction.
*
* @param id the transaction id, must not be {@code null}
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> abort(String id);
/**
* Aborts a transaction.
*
* @param id the transaction id, must not be {@code null}
* @param headers additional headers to send to the server. The {@code transaction} header is replaced by the
* value passed in the @{code id} parameter
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> abort(String id, Map<String, String> headers);
/**
* Disconnects the client. Unlike the {@link #close()} method, this method send the {@code DISCONNECT} frame to the
* server.
*
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> disconnect();
/**
* Disconnects the client. Unlike the {@link #close()} method, this method send the {@code DISCONNECT} frame to the
* server. This method lets you customize the {@code DISCONNECT} frame.
*
* @param frame the {@code DISCONNECT} frame.
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> disconnect(Frame frame);
/**
* Sends an acknowledgement for a specific message. It means that the message has been handled and processed by the
* client. The {@code id} parameter is the message id received in the frame.
*
* @param id the message id of the message to acknowledge
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> ack(String id);
/**
* Sends a non-acknowledgement for the given message. It means that the message has not been handled by the client.
* The {@code id} parameter is the message id received in the frame.
*
* @param id the message id of the message to acknowledge
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> nack(String id);
/**
* Sends an acknowledgement for the given frame. It means that the frame has been handled and processed by the
* client. The sent acknowledgement is part of the transaction identified by the given id.
*
* @param id the message id of the message to acknowledge
* @param txId the transaction id
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> ack(String id, String txId);
/**
* Sends a non-acknowledgement for the given frame. It means that the frame has not been handled by the client.
* The sent non-acknowledgement is part of the transaction identified by the given id.
*
* @param id the message id of the message to acknowledge
* @param txId the transaction id
* @return a future resolved with the sent frame when the {@code RECEIPT} frame associated with the sent frame has been received
*/
Future<Frame> nack(String id, String txId);
/**
* Configures a received handler that get notified when a STOMP frame is received by the client.
* This handler can be used for logging, debugging or ad-hoc behavior. The frame can still be modified by the handler.
* <p>
* Unlike {@link StompClient#receivedFrameHandler(Handler)}, the given handler won't receive the {@code
* CONNECTED} frame. If a received frame handler is set on the {@link StompClient}, it will be used by all
* clients connection, so calling this method is useless, except if you want to use a different handler.
*
* @param handler the handler
* @return the current {@link StompClientConnection}
*/
@Fluent
StompClientConnection receivedFrameHandler(Handler<Frame> handler);
/**
* Configures a handler notified when a frame is going to be written on the wire. This handler can be used from
* logging, debugging. The handler can modify the received frame.
* <p>
* If a writing frame handler is set on the {@link StompClient}, it will be used by all
* clients connection, so calling this method is useless, except if you want to use a different handler.
*
* @param handler the handler
* @return the current {@link StompClientConnection}
*/
@Fluent
StompClientConnection writingFrameHandler(Handler<Frame> handler);
/**
* Configures the exception handler notified upon TCP-level errors.
*
* @param exceptionHandler the handler
* @return the current {@link StompClientConnection}
*/
@Fluent
StompClientConnection exceptionHandler(Handler<Throwable> exceptionHandler);
/**
* Returns whether or not the `CONNECTED` frame has been receive meaning that the Stomp connection is established.
*
* @return {@code true} if the connection is established, {@code false} otherwise
*/
boolean isConnected();
}