Package 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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Future<Frame>` | `abort​(String id)` | Aborts a transaction.
    `Future<Frame>` | `abort​(String id, Map<String,​String> headers)` | Aborts a transaction.
    `Future<Frame>` | `ack​(String id)` | Sends an acknowledgement for a specific message.
    `Future<Frame>` | `ack​(String id, String txId)` | Sends an acknowledgement for the given frame.
    `Future<Frame>` | `beginTX​(String id)` | Begins a transaction.
    `Future<Frame>` | `beginTX​(String id, Map<String,​String> headers)` | 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.
    `Future<Frame>` | `commit​(String id, Map<String,​String> headers)` | 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` | `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.
    `Future<Frame>` | `nack​(String id, String txId)` | 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.
    `Future<Frame>` | `send​(String destination, Buffer body)` | 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.
    `Future<Frame>` | `send​(Map<String,​String> headers, Buffer body)` | Sends a `SEND` frame to the server.
    `String` | `server()` |
    `String` | `session()` |
    `Future<String>` | `subscribe​(String destination, Handler<Frame> handler)` | Subscribes to the given destination.
    `Future<String>` | `subscribe​(String destination, Map<String,​String> headers, Handler<Frame> handler)` | Subscribes to the given destination.
    `Future<Frame>` | `unsubscribe​(String destination)` | Un-subscribes from the given destination.
    `Future<Frame>` | `unsubscribe​(String destination, Map<String,​String> headers)` | 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()`

    - #### 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

          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

          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

          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

    - #### 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

          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

    - #### 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

          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

    - #### 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

          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

    - #### 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

          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

    - #### 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

          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

    - #### 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

          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

    - #### 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

    - #### 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

    - #### 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

    - #### 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

    - #### 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