io.vertx.ext.stomp

Interface StompClientConnection

public interface StompClientConnection

Once a connection to the STOMP server has been made, client receives a StompClientConnection, that let send and receive STOMP frames.

Author:

Clement Escoffier

Method Summary

Modifier and Type	Method and Description
Future<Frame>	abort(String id) Aborts a transaction.
StompClientConnection	abort(String id, Handler<AsyncResult<Frame>> receiptHandler) Aborts a transaction.
Future<Frame>	abort(String id, Map<String,String> headers) Aborts a transaction.
StompClientConnection	abort(String id, Map<String,String> headers, Handler<AsyncResult<Frame>> receiptHandler) Aborts a transaction.
Future<Frame>	ack(String id) Sends an acknowledgement for a specific message.
StompClientConnection	ack(String id, Handler<AsyncResult<Frame>> receiptHandler) Sends an acknowledgement for a specific message.
Future<Frame>	ack(String id, String txId) Sends an acknowledgement for the given frame.
StompClientConnection	ack(String id, String txId, Handler<AsyncResult<Frame>> receiptHandler) Sends an acknowledgement for the given frame.
Future<Frame>	beginTX(String id) Begins a transaction.
StompClientConnection	beginTX(String id, Handler<AsyncResult<Frame>> receiptHandler) Begins a transaction.
Future<Frame>	beginTX(String id, Map<String,String> headers) Begins a transaction.
StompClientConnection	beginTX(String id, Map<String,String> headers, Handler<AsyncResult<Frame>> receiptHandler) Begins a transaction.
void	close() Closes the connection without sending the DISCONNECT frame.
StompClientConnection	closeHandler(Handler<StompClientConnection> handler) Sets a handler notified when the STOMP connection is closed.
Future<Frame>	commit(String id) Commits a transaction.
StompClientConnection	commit(String id, Handler<AsyncResult<Frame>> receiptHandler) Commits a transaction.
Future<Frame>	commit(String id, Map<String,String> headers) Commits a transaction.
StompClientConnection	commit(String id, Map<String,String> headers, Handler<AsyncResult<Frame>> receiptHandler) Commits a transaction.
StompClientConnection	connectionDroppedHandler(Handler<StompClientConnection> handler) Sets a handler notified when the server does not respond to a ping request in time.
Future<Frame>	disconnect() Disconnects the client.
Future<Frame>	disconnect(Frame frame) Disconnects the client.
StompClientConnection	disconnect(Frame frame, Handler<AsyncResult<Frame>> receiptHandler) Disconnects the client.
StompClientConnection	disconnect(Handler<AsyncResult<Frame>> receiptHandler) Disconnects the client.
StompClientConnection	errorHandler(Handler<Frame> handler) Sets a handler notified when an ERROR frame is received by the client.
StompClientConnection	exceptionHandler(Handler<Throwable> exceptionHandler) Configures the exception handler notified upon TCP-level errors.
boolean	isConnected() Returns whether or not the `CONNECTED` frame has been receive meaning that the Stomp connection is established.
Future<Frame>	nack(String id) Sends a non-acknowledgement for the given message.
StompClientConnection	nack(String id, Handler<AsyncResult<Frame>> receiptHandler) Sends a non-acknowledgement for the given message.
Future<Frame>	nack(String id, String txId) Sends a non-acknowledgement for the given frame.
StompClientConnection	nack(String id, String txId, Handler<AsyncResult<Frame>> receiptHandler) Sends a non-acknowledgement for the given frame.
StompClientConnection	pingHandler(Handler<StompClientConnection> handler) Sets a handler that let customize the behavior when a ping needs to be sent to the server.
StompClientConnection	receivedFrameHandler(Handler<Frame> handler) Configures a received handler that get notified when a STOMP frame is received by the client.
Future<Frame>	send(Frame frame) Sends the given frame to the server.
StompClientConnection	send(Frame frame, Handler<AsyncResult<Frame>> receiptHandler) Sends the given frame to the server.
Future<Frame>	send(Map<String,String> headers, Buffer body) Sends a SEND frame to the server.
StompClientConnection	send(Map<String,String> headers, Buffer body, Handler<AsyncResult<Frame>> receiptHandler) Sends a SEND frame to the server.
Future<Frame>	send(String destination, Buffer body) Sends a SEND frame to the server to the given destination.
StompClientConnection	send(String destination, Buffer body, Handler<AsyncResult<Frame>> receiptHandler) Sends a SEND frame to the server to the given destination.
Future<Frame>	send(String destination, Map<String,String> headers, Buffer body) Sends a SEND frame to the server to the given destination.
StompClientConnection	send(String destination, Map<String,String> headers, Buffer body, Handler<AsyncResult<Frame>> receiptHandler) Sends a SEND frame to the server to the given destination.
String	server()
String	session()
Future<String>	subscribe(String destination, Handler<Frame> handler) Subscribes to the given destination.
StompClientConnection	subscribe(String destination, Handler<Frame> handler, Handler<AsyncResult<String>> receiptHandler) Subscribes to the given destination.
Future<String>	subscribe(String destination, Map<String,String> headers, Handler<Frame> handler) Subscribes to the given destination.
StompClientConnection	subscribe(String destination, Map<String,String> headers, Handler<Frame> handler, Handler<AsyncResult<String>> receiptHandler) Subscribes to the given destination.
Future<Frame>	unsubscribe(String destination) Un-subscribes from the given destination.
StompClientConnection	unsubscribe(String destination, Handler<AsyncResult<Frame>> receiptHandler) Un-subscribes from the given destination.
Future<Frame>	unsubscribe(String destination, Map<String,String> headers) Un-subscribes from the given destination.
StompClientConnection	unsubscribe(String destination, Map<String,String> headers, Handler<AsyncResult<Frame>> receiptHandler) Un-subscribes from the given destination.
String	version()
StompClientConnection	writingFrameHandler(Handler<Frame> handler) Configures a handler notified when a frame is going to be written on the wire.

Method Detail

session

String session()

Returns:

the session id.

version

String version()

Returns:

the STOMP protocol version negotiated with the server.

close

void close()

Closes the connection without sending the DISCONNECT frame.

See Also:

disconnect(), disconnect(Handler)

server

String server()

Returns:

the server name.

send

Future<Frame> send(Map<String,String> headers,
                   Buffer body)

Sends a SEND frame to the server.

Parameters:

headers - the headers, must not be null

body - the body, may be null

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

send

StompClientConnection send(Map<String,String> headers,
                           Buffer body,
                           Handler<AsyncResult<Frame>> receiptHandler)

Sends a SEND frame to the server.

Parameters:

headers - the headers, must not be null

body - the body, may be null

receiptHandler - the handler invoked when the RECEIPT frame associated with the sent frame has been received. The handler receives the sent frame.

Returns:

the current StompClientConnection

send

Future<Frame> send(String destination,
                   Buffer body)

Sends a SEND frame to the server to the given destination. The message does not have any other header.

Parameters:

destination - the destination, must not be null

body - the body, may be null

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

send

StompClientConnection send(String destination,
                           Buffer body,
                           Handler<AsyncResult<Frame>> receiptHandler)

Sends a SEND frame to the server to the given destination. The message does not have any other header.

Parameters:

destination - the destination, must not be null

body - the body, may be null

receiptHandler - the handler invoked when the RECEIPT frame associated with the sent frame has been received. The handler receives the sent frame.

Returns:

the current StompClientConnection

send

Future<Frame> send(Frame frame)

Sends the given frame to the server.

Parameters:

frame - the frame

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

send

StompClientConnection send(Frame frame,
                           Handler<AsyncResult<Frame>> receiptHandler)

Sends the given frame to the server.

Parameters:

frame - the frame

receiptHandler - the handler invoked when the RECEIPT frame associated with the sent frame has been received. The handler receives the sent frame.

Returns:

the current StompClientConnection

send

Future<Frame> send(String destination,
                   Map<String,String> headers,
                   Buffer body)

Sends a SEND frame to the server to the given destination.

Parameters:

destination - the destination, must not be null

body - the body, may be null

headers - the header. The destination header is replaced by the value given to the destination parameter

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

send

StompClientConnection send(String destination,
                           Map<String,String> headers,
                           Buffer body,
                           Handler<AsyncResult<Frame>> receiptHandler)

Sends a SEND frame to the server to the given destination.

Parameters:

destination - the destination, must not be null

body - the body, may be null

headers - the header. The destination header is replaced by the value given to the destination parameter

receiptHandler - the handler invoked when the RECEIPT frame associated with the sent frame has been received. The handler receives the sent frame.

Returns:

the current StompClientConnection

subscribe

Future<String> subscribe(String destination,
                         Handler<Frame> handler)

Subscribes to the given destination. This destination is used as subscription id.

Parameters:

destination - the destination, must not be null

handler - the handler invoked when a message is received on the given destination. Must not be null.

Returns:

a future resolved with the subscription id when the RECEIPT frame associated with the sent frame has been received

subscribe

StompClientConnection subscribe(String destination,
                                Handler<Frame> handler,
                                Handler<AsyncResult<String>> receiptHandler)

Subscribes to the given destination. This destination is used as subscription id.

Parameters:

destination - the destination, must not be null

handler - the handler invoked when a message is received on the given destination. Must not be null.

receiptHandler - the handler invoked when the RECEIPT frame associated with the subscription has been received. The handler receives the subscription id.

Returns:

the current StompClientConnection

subscribe

Future<String> subscribe(String destination,
                         Map<String,String> headers,
                         Handler<Frame> handler)

Subscribes to the given destination.

Parameters:

destination - the destination, must not be null.

headers - the headers to configure the subscription. It may contain the ack header to configure the acknowledgment policy. If the given set of headers contains the id header, this value is used as subscription id.

handler - the handler invoked when a message is received on the given destination. Must not be null.

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

subscribe

StompClientConnection subscribe(String destination,
                                Map<String,String> headers,
                                Handler<Frame> handler,
                                Handler<AsyncResult<String>> receiptHandler)

Subscribes to the given destination.

Parameters:

destination - the destination, must not be null

headers - the headers to configure the subscription. It may contain the ack header to configure the acknowledgment policy. If the given set of headers contains the id header, this value is used as subscription id.

handler - the handler invoked when a message is received on the given destination. Must not be null.

receiptHandler - the handler invoked when the RECEIPT frame associated with the subscription has been received. The handler receives the subscription id.

Returns:

the current StompClientConnection

unsubscribe

Future<Frame> unsubscribe(String destination)

Un-subscribes from the given destination. This method only works if the subscription did not specifies a subscription id (using the id header).

Parameters:

destination - the destination

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

unsubscribe

StompClientConnection unsubscribe(String destination,
                                  Handler<AsyncResult<Frame>> receiptHandler)

Un-subscribes from the given destination. This method only works if the subscription did not specifies a subscription id (using the id header).

Parameters:

destination - the destination

receiptHandler - the handler invoked when the RECEIPT frame associated with the un-subscription has been received. The handler receives the sent frame (UNSUBSCRIBE).

Returns:

the current StompClientConnection

unsubscribe

Future<Frame> unsubscribe(String destination,
                          Map<String,String> headers)

Un-subscribes from the given destination. This method computes the subscription id as follows. If the given headers contains the id header, the header value is used. Otherwise the destination is used.

Parameters:

destination - the destination

headers - the headers

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

unsubscribe

StompClientConnection unsubscribe(String destination,
                                  Map<String,String> headers,
                                  Handler<AsyncResult<Frame>> receiptHandler)

Un-subscribes from the given destination. This method computes the subscription id as follows. If the given headers contains the id header, the header value is used. Otherwise the destination is used.

Parameters:

destination - the destination

headers - the headers

receiptHandler - the handler invoked when the RECEIPT frame associated with the un-subscription has been received. The handler receives the sent frame (UNSUBSCRIBE).

Returns:

the current StompClientConnection

errorHandler

StompClientConnection errorHandler(Handler<Frame> handler)

Sets a handler notified when an ERROR frame is received by the client. The handler receives the ERROR frame and a reference on the StompClientConnection.

Parameters:

handler - the handler

Returns:

the current StompClientConnection

closeHandler

StompClientConnection closeHandler(Handler<StompClientConnection> handler)

Sets a handler notified when the STOMP connection is closed.

Parameters:

handler - the handler

Returns:

the current StompClientConnection

connectionDroppedHandler

StompClientConnection connectionDroppedHandler(Handler<StompClientConnection> handler)

Sets a handler notified when the server does not respond to a 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.

Parameters:

handler - the handler

Returns:

the current StompClientConnection receiving the dropped connection.

pingHandler

StompClientConnection pingHandler(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.

Parameters:

handler - the handler

Returns:

the current StompClientConnection

beginTX

StompClientConnection beginTX(String id,
                              Handler<AsyncResult<Frame>> receiptHandler)

Begins a transaction.

Parameters:

id - the transaction id, must not be null

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction begin has been processed by the server. The handler receives the sent frame (BEGIN).

Returns:

the current StompClientConnection

beginTX

Future<Frame> beginTX(String id)

Begins a transaction.

Parameters:

id - the transaction id, must not be null

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

beginTX

Future<Frame> beginTX(String id,
                      Map<String,String> headers)

Begins a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

beginTX

StompClientConnection beginTX(String id,
                              Map<String,String> headers,
                              Handler<AsyncResult<Frame>> receiptHandler)

Begins a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction begin has been processed by the server. The handler receives the sent frame (BEGIN).

Returns:

the current StompClientConnection

commit

Future<Frame> commit(String id)

Commits a transaction.

Parameters:

id - the transaction id, must not be null

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

commit

StompClientConnection commit(String id,
                             Handler<AsyncResult<Frame>> receiptHandler)

Commits a transaction.

Parameters:

id - the transaction id, must not be null

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction commit has been processed by the server. The handler receives the sent frame (COMMIT).

Returns:

the current StompClientConnection

commit

Future<Frame> commit(String id,
                     Map<String,String> headers)

Commits a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

commit

StompClientConnection commit(String id,
                             Map<String,String> headers,
                             Handler<AsyncResult<Frame>> receiptHandler)

Commits a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction commit has been processed by the server. The handler receives the sent frame (COMMIT).

Returns:

the current StompClientConnection

abort

Future<Frame> abort(String id)

Aborts a transaction.

Parameters:

id - the transaction id, must not be null

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

abort

StompClientConnection abort(String id,
                            Handler<AsyncResult<Frame>> receiptHandler)

Aborts a transaction.

Parameters:

id - the transaction id, must not be null

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction cancellation has been processed by the server. The handler receives the sent frame (ABORT).

Returns:

the current StompClientConnection

abort

Future<Frame> abort(String id,
                    Map<String,String> headers)

Aborts a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

abort

StompClientConnection abort(String id,
                            Map<String,String> headers,
                            Handler<AsyncResult<Frame>> receiptHandler)

Aborts a transaction.

Parameters:

id - the transaction id, must not be null

headers - additional headers to send to the server. The transaction header is replaced by the value passed in the @{code id} parameter

receiptHandler - the handler invoked when the RECEIPT frame associated with the transaction cancellation has been processed by the server. The handler receives the sent frame (ABORT).

Returns:

the current StompClientConnection

disconnect

Future<Frame> disconnect()

Disconnects the client. Unlike the close() method, this method send the DISCONNECT frame to the server.

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

disconnect

StompClientConnection disconnect(Handler<AsyncResult<Frame>> receiptHandler)

Disconnects the client. Unlike the close() method, this method send the DISCONNECT frame to the server.

Parameters:

receiptHandler - the handler invoked when the RECEIPT frame associated with the disconnection has been processed by the server. The handler receives the sent frame (DISCONNECT).

Returns:

the current StompClientConnection

disconnect

Future<Frame> disconnect(Frame frame)

Disconnects the client. Unlike the close() method, this method send the DISCONNECT frame to the server. This method lets you customize the DISCONNECT frame.

Parameters:

frame - the DISCONNECT frame.

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

disconnect

StompClientConnection disconnect(Frame frame,
                                 Handler<AsyncResult<Frame>> receiptHandler)

Disconnects the client. Unlike the close() method, this method send the DISCONNECT frame to the server. This method lets you customize the DISCONNECT frame.

Parameters:

frame - the DISCONNECT frame.

receiptHandler - the handler invoked when the RECEIPT frame associated with the disconnection has been processed by the server. The handler receives the sent frame (DISCONNECT).

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

ack

Future<Frame> ack(String id)

Sends an acknowledgement for a specific message. It means that the message has been handled and processed by the client. The id parameter is the message id received in the frame.

Parameters:

id - the message id of the message to acknowledge

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

ack

StompClientConnection ack(String id,
                          Handler<AsyncResult<Frame>> receiptHandler)

Sends an acknowledgement for a specific message. It means that the message has been handled and processed by the client. The id parameter is the message id received in the frame.

Parameters:

id - the message id of the message to acknowledge

receiptHandler - the handler invoked when the RECEIPT frame associated with the acknowledgment has been processed by the server. The handler receives the sent frame (ACK).

Returns:

the current StompClientConnection

nack

Future<Frame> nack(String id)

Sends a non-acknowledgement for the given message. It means that the message has not been handled by the client. The id parameter is the message id received in the frame.

Parameters:

id - the message id of the message to acknowledge

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

nack

StompClientConnection nack(String id,
                           Handler<AsyncResult<Frame>> receiptHandler)

Sends a non-acknowledgement for the given message. It means that the message has not been handled by the client. The id parameter is the message id received in the frame.

Parameters:

id - the message id of the message to acknowledge

receiptHandler - the handler invoked when the RECEIPT frame associated with the non-acknowledgment has been processed by the server. The handler receives the sent frame (NACK).

Returns:

the current StompClientConnection

ack

Future<Frame> ack(String id,
                  String txId)

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.

Parameters:

id - the message id of the message to acknowledge

txId - the transaction id

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

ack

StompClientConnection ack(String id,
                          String txId,
                          Handler<AsyncResult<Frame>> receiptHandler)

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.

Parameters:

id - the message id of the message to acknowledge

txId - the transaction id

receiptHandler - the handler invoked when the RECEIPT frame associated with the acknowledgment has been processed by the server. The handler receives the sent frame (ACK).

Returns:

the current StompClientConnection

nack

Future<Frame> nack(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.

Parameters:

id - the message id of the message to acknowledge

txId - the transaction id

Returns:

a future resolved with the sent frame when the RECEIPT frame associated with the sent frame has been received

nack

StompClientConnection nack(String id,
                           String txId,
                           Handler<AsyncResult<Frame>> receiptHandler)

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.

Parameters:

id - the message id of the message to acknowledge

txId - the transaction id

receiptHandler - the handler invoked when the RECEIPT frame associated with the non-acknowledgment has been processed by the server. The handler receives the sent frame (NACK).

Returns:

the current StompClientConnection

receivedFrameHandler

StompClientConnection receivedFrameHandler(Handler<Frame> handler)

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.

Unlike StompClient.receivedFrameHandler(Handler), the given handler won't receive the CONNECTED frame. If a received frame handler is set on the StompClient, it will be used by all clients connection, so calling this method is useless, except if you want to use a different handler.

Parameters:

handler - the handler

Returns:

the current StompClientConnection

writingFrameHandler

StompClientConnection writingFrameHandler(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.

If a writing frame handler is set on the StompClient, it will be used by all clients connection, so calling this method is useless, except if you want to use a different handler.

Parameters:

handler - the handler

Returns:

the current StompClientConnection

exceptionHandler

StompClientConnection exceptionHandler(Handler<Throwable> exceptionHandler)

Configures the exception handler notified upon TCP-level errors.

Parameters:

exceptionHandler - the handler

Returns:

the current StompClientConnection

isConnected

boolean isConnected()

Returns whether or not the `CONNECTED` frame has been receive meaning that the Stomp connection is established.

Returns:

true if the connection is established, false otherwise