Interface StompClient

All Superinterfaces:
AutoCloseable
public interface StompClient extends AutoCloseable

A STOMP client for sending and receiving messages over the STOMP protocol.

This interface defines the core functionalities of a STOMP client, including connecting to a STOMP server, sending messages to destinations, subscribing to destinations to receive messages, and unsubscribing from subscriptions.

To create an instance of a STOMP client, use the builder() method to obtain a StompClientBuilder. This builder allows you to configure the client.

To disconnect and release resources, call the close() method.

You may also consider using the StompSubscriber annotation to define classes that can be registered as subscribers to STOMP destinations, and StompPublisher annotation to define publisher interfaces that can be used to send messages to STOMP destinations.

StompClient implementations are required to be thread-safe.

Since:
1.0.0
See Also:

  • Method Details

    • builder

      static StompClientBuilder builder()

      Creates a new StompClientBuilder for building a STOMP client.

      The builder must be provided with an endpoint URI before building the client.

      Builder instances are not thread-safe and should not be shared between threads.

      Returns:
      a new instance of StompClientBuilder
      Since:
      1.0.0

    • connect

      CompletableFuture<Void> connect() throws ConnectionException

      Connects to the STOMP server.

      This method establishes a connection to the STOMP server specified in the client's configuration. It blocks until the connection is successfully established or fails.

      If the method is called a second time on the same client instance, an IllegalStateException is thrown.

      If the thread is interrupted while waiting for the connection to be established, an ConnectionException is thrown. The interrupt status of the thread is preserved.

      Throws:
      ConnectionException - if the connection fails
      IllegalStateException - if the client has already been connected before
      Since:
      1.0.0

    • connect

      CompletableFuture<Void> connect(String login, String passcode) throws ConnectionException

      Connects to the STOMP server using the provided login and passcode.

      This method establishes a connection to the STOMP server specified in the client's configuration, using the provided login and passcode for authentication in the STOMP CONNECT frame. It returns a CompletableFuture that completes when the connection is established or fails.

      If the method is called a second time on the same client instance, an IllegalStateException is thrown.

      If the thread is interrupted while waiting for the connection to be established, an ConnectionException is thrown. The interrupt status of the thread is preserved.

      This method is a shorthand for calling connect(String, String, AuthenticationMethod) with AuthenticationMethod.STOMP as the authentication method.

      Parameters:
      login - the login username
      passcode - the passcode (password)
      Throws:
      ConnectionException - if the connection fails
      IllegalStateException - if the client has already been connected before
      Since:
      1.0.0

    • connect

      CompletableFuture<Void> connect(String login, String passcode, AuthenticationMethod authenticationMethod) throws ConnectionException

      Connects to the STOMP server using the provided login, passcode and authentication method.

      This method establishes a connection to the STOMP server specified in the client's configuration, using the provided login and passcode for authentication. The AuthenticationMethod determines how the credentials are used. It returns a CompletableFuture that completes when the connection is established or fails.

      If the method is called a second time on the same client instance, an IllegalStateException is thrown.

      If the thread is interrupted while waiting for the connection to be established, an ConnectionException is thrown. The interrupt status of the thread is preserved.

      Parameters:
      login - the login username
      passcode - the passcode (password)
      Throws:
      ConnectionException - if the connection fails
      IllegalStateException - if the client has already been connected before
      Since:
      1.0.0

    • send

      void send(String destination, String body) throws SendException

      Sends a message to the specified destination with the given body. This method does not use the provided message converter. It sends the body directly as a string and indicates a content type of text/plain;charset=UTF-8.

      If the client is not connected, an IllegalStateException is thrown.

      Parameters:
      destination - the destination to end the message to
      body - the body of the message
      Throws:
      IllegalStateException - if the client is not connected
      SendException - if sending the message fails or the message cannot be encoded
      Since:
      1.0.0

    • send

      void send(String destination, Object body) throws SendException

      Sends a message to the specified destination with the given body. The body is converted to a string using the client's configured message converter.

      If the client is not connected, an IllegalStateException is thrown.

      Parameters:
      destination - the destination to send the message to
      body - the body of the message
      Throws:
      IllegalStateException - if the client is not connected
      SendException - if sending the message fails or the message cannot be encoded
      Since:
      1.0.0

    • subscribe

      <T> Subscription subscribe(String destination, Class<T> payloadType, Consumer<T> messageHandler)

      Subscribes to the specified destination to receive messages of the given payload type.

      The provided message handler is invoked for each received message, with the message payload converted to the specified type.

      The returned Subscription can be used to unsubscribe from the destination using the unsubscribe(Subscription) method.

      If the client is not connected, an IllegalStateException is thrown.

      Type Parameters:
      T - the type of the message payload
      Parameters:
      destination - the destination to subscribe to
      payloadType - the type of the message payload
      messageHandler - the handler to process received messages
      Returns:
      a Subscription representing the subscription
      Throws:
      IllegalStateException - if the client is not connected
      Since:
      1.0.0

    • subscribe

      void subscribe(Object subscriber)

      Subscribes all methods annotated with Topic in the given subscriber object. You can unsubscribe all created subscriptions by calling unsubscribe(Object) with the same subscriber instance. To provide more configuration, annotate the class with StompSubscriber.

      After calling this method, the subscriber's annotated methods will be invoked for incoming messages on their respective topics. If you call this method multiple times with the same subscriber instance, an IllegalStateException is thrown.

      If the client is not connected, an IllegalStateException is thrown.

      Parameters:
      subscriber - the subscriber object containing methods annotated with Topic
      Throws:
      IllegalStateException - if the client is not connected
      Since:
      1.0.0

    • unsubscribe

      void unsubscribe(Subscription subscription)

      Unsubscribes from the specified subscription.

      After calling this method, no more messages will be received for the given subscription. If the subscription is already unsubscribed, this method has no effect.

      If the client is not connected, an IllegalStateException is thrown.

      Parameters:
      subscription - the subscription to unsubscribe from
      Throws:
      IllegalStateException - if the client is not connected
      Since:
      1.0.0

    • unsubscribe

      void unsubscribe(Object subscriber)

      Unsubscribes all subscriptions created from the given subscriber object.

      After calling this method, no more messages will be received for any subscriptions created from the specified subscriber. If there are no subscriptions for the given subscriber, this method has no effect.

      If the client is not connected, an IllegalStateException is thrown.

      Parameters:
      subscriber - the subscriber object whose subscriptions should be unsubscribed
      Throws:
      IllegalStateException - if the client is not connected
      Since:
      1.0.0

    • close

      void close()

      Closes the STOMP client and releases all associated resources.

      This method disconnects from the STOMP server if connected and cleans up any resources used by the client. After calling this method, the client instance should not be used anymore.

      Subscriptions created by this client are also unsubscribed and will no longer receive messages.

      Specified by:
      close in interface AutoCloseable
      Since:
      1.0.0

    • getMessageConverter

      MessageConverter getMessageConverter()
      Returns the message converter used by the STOMP client for converting message payloads.
      Returns:
      the message converter
      Since:
      1.0.0