org.springframework.messaging.simp.stomp

## Class StompBrokerRelayMessageHandler

- java.lang.Object
- - org.springframework.messaging.simp.broker.AbstractBrokerMessageHandler
  - - org.springframework.messaging.simp.stomp.StompBrokerRelayMessageHandler

- All Implemented Interfaces:
    Aware, ApplicationEventPublisherAware, Lifecycle, Phased, SmartLifecycle, MessageHandler

      public class StompBrokerRelayMessageHandler
      extends AbstractBrokerMessageHandler

  A `MessageHandler` that handles messages by forwarding them to a STOMP broker. For each new `CONNECT` message, an independent TCP connection to the broker is opened and used exclusively for all messages from the client that originated the CONNECT message. Messages from the same client are identified through the session id message header. Reversely, when the STOMP broker sends messages back on the TCP connection, those messages are enriched with the session id of the client and sent back downstream through the `MessageChannel` provided to the constructor.

  This class also automatically opens a default "system" TCP connection to the message broker that is used for sending messages that originate from the server application (as opposed to from a client). Such messages are are not associated with any client and therefore do not have a session id header. The "system" connection is effectively shared and cannot be used to receive messages. Several properties are provided to configure the "system" connection including:

  - `setSystemLogin(String)`
  - `setSystemPasscode(String)`
  - `setSystemHeartbeatSendInterval(long)`
  - `setSystemHeartbeatReceiveInterval(long)`
  Since:
    4.0
  Author:
    Rossen Stoyanchev, Andy Wilkinson

- - ### Field Summary

    - ### Fields inherited from class org.springframework.messaging.simp.broker.AbstractBrokerMessageHandler

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StompBrokerRelayMessageHandler(SubscribableChannel clientInChannel, MessageChannel clientOutChannel, SubscribableChannel brokerChannel, Collection<String> destinationPrefixes)` Create a StompBrokerRelayMessageHandler instance with the given message channels and destination prefixes.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getClientLogin()`
    `String` | `getClientPasscode()`
    `String` | `getRelayHost()`
    `int` | `getRelayPort()`
    `long` | `getSystemHeartbeatReceiveInterval()`
    `long` | `getSystemHeartbeatSendInterval()`
    `String` | `getSystemLogin()`
    `String` | `getSystemPasscode()`
    `TcpOperations<byte[]>` | `getTcpClient()` Get the configured TCP client.
    `String` | `getVirtualHost()`
    `protected void` | `handleMessageInternal(Message<?> message)`
    `void` | `setClientLogin(String clientLogin)` Set the login to use when creating connections to the STOMP broker on behalf of connected clients.
    `void` | `setClientPasscode(String clientPasscode)` Set the clientPasscode to use to create connections to the STOMP broker on behalf of connected clients.
    `void` | `setRelayHost(String relayHost)` Set the STOMP message broker host.
    `void` | `setRelayPort(int relayPort)` Set the STOMP message broker port.
    `void` | `setSystemHeartbeatReceiveInterval(long heartbeatReceiveInterval)` Set the maximum interval, in milliseconds, at which the "system" connection expects, in the absence of any other data, to receive a heartbeat from the STOMP broker.
    `void` | `setSystemHeartbeatSendInterval(long systemHeartbeatSendInterval)` Set the interval, in milliseconds, at which the "system" connection will, in the absence of any other data being sent, send a heartbeat to the STOMP broker.
    `void` | `setSystemLogin(String systemLogin)` Set the login for the shared "system" connection used to send messages to the STOMP broker from within the application, i.e.
    `void` | `setSystemPasscode(String systemPasscode)` Set the passcode for the shared "system" connection used to send messages to the STOMP broker from within the application, i.e.
    `void` | `setTcpClient(TcpOperations<byte[]> tcpClient)` Configure a TCP client for managing TCP connections to the STOMP broker.
    `void` | `setVirtualHost(String virtualHost)` Set the value of the "host" header to use in STOMP CONNECT frames.
    `protected void` | `startInternal()`
    `protected void` | `stopInternal()`

    - ### Methods inherited from class org.springframework.messaging.simp.broker.AbstractBrokerMessageHandler

      `checkDestinationPrefix, getApplicationEventPublisher, getDestinationPrefixes, getPhase, handleMessage, isAutoStartup, isBrokerAvailable, isRunning, publishBrokerAvailableEvent, publishBrokerUnavailableEvent, setApplicationEventPublisher, setAutoStartup, start, stop, stop`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### StompBrokerRelayMessageHandler

          public StompBrokerRelayMessageHandler(SubscribableChannel clientInChannel,
                                                MessageChannel clientOutChannel,
                                                SubscribableChannel brokerChannel,
                                                Collection<String> destinationPrefixes)

      Create a StompBrokerRelayMessageHandler instance with the given message channels and destination prefixes.
      Parameters:
        `clientInChannel` - the channel for receiving messages from clients (e.g. WebSocket clients)
        `clientOutChannel` - the channel for sending messages to clients (e.g. WebSocket clients)
        `brokerChannel` - the channel for the application to send messages to the broker
        `destinationPrefixes` - the broker supported destination prefixes; destinations that do not match the given prefix are ignored.

  - ### Method Detail

    - #### setRelayHost

          public void setRelayHost(String relayHost)

      Set the STOMP message broker host.

    - #### getRelayHost

          public String getRelayHost()

      Returns:
        the STOMP message broker host.

    - #### setRelayPort

          public void setRelayPort(int relayPort)

      Set the STOMP message broker port.

    - #### getRelayPort

          public int getRelayPort()

      Returns:
        the STOMP message broker port.

    - #### setSystemHeartbeatSendInterval

          public void setSystemHeartbeatSendInterval(long systemHeartbeatSendInterval)

      Set the interval, in milliseconds, at which the "system" connection will, in the absence of any other data being sent, send a heartbeat to the STOMP broker. A value of zero will prevent heartbeats from being sent to the broker.

      The default value is 10000.

      See class-level documentation for more information on the "system" connection.

    - #### getSystemHeartbeatSendInterval

          public long getSystemHeartbeatSendInterval()

      Returns:
        The interval, in milliseconds, at which the "system" connection will send heartbeats to the STOMP broker.

    - #### setSystemHeartbeatReceiveInterval

          public void setSystemHeartbeatReceiveInterval(long heartbeatReceiveInterval)

      Set the maximum interval, in milliseconds, at which the "system" connection expects, in the absence of any other data, to receive a heartbeat from the STOMP broker. A value of zero will configure the connection to expect not to receive heartbeats from the broker.

      The default value is 10000.

      See class-level documentation for more information on the "system" connection.

    - #### getSystemHeartbeatReceiveInterval

          public long getSystemHeartbeatReceiveInterval()

      Returns:
        The interval, in milliseconds, at which the "system" connection expects to receive heartbeats from the STOMP broker.

    - #### setClientLogin

          public void setClientLogin(String clientLogin)

      Set the login to use when creating connections to the STOMP broker on behalf of connected clients.

      By default this is set to "guest".

      See Also:
        `setSystemLogin(String)`

    - #### getClientLogin

          public String getClientLogin()

      Returns:
        the configured login to use for connections to the STOMP broker on behalf of connected clients.
      See Also:
        `getSystemLogin()`

    - #### setClientPasscode

          public void setClientPasscode(String clientPasscode)

      Set the clientPasscode to use to create connections to the STOMP broker on behalf of connected clients.

      By default this is set to "guest".

      See Also:
        `setSystemPasscode(String)`

    - #### getClientPasscode

          public String getClientPasscode()

      Returns:
        the configured passocde to use for connections to the STOMP broker on behalf of connected clients.
      See Also:
        `getSystemPasscode()`

    - #### setSystemLogin

          public void setSystemLogin(String systemLogin)

      Set the login for the shared "system" connection used to send messages to the STOMP broker from within the application, i.e. messages not associated with a specific client session (e.g. REST/HTTP request handling method).

      By default this is set to "guest".

    - #### getSystemLogin

          public String getSystemLogin()

      Returns:
        the login used for the shared "system" connection to the STOMP broker

    - #### setSystemPasscode

          public void setSystemPasscode(String systemPasscode)

      Set the passcode for the shared "system" connection used to send messages to the STOMP broker from within the application, i.e. messages not associated with a specific client session (e.g. REST/HTTP request handling method).

      By default this is set to "guest".

    - #### getSystemPasscode

          public String getSystemPasscode()

      Returns:
        the passcode used for the shared "system" connection to the STOMP broker

    - #### setVirtualHost

          public void setVirtualHost(String virtualHost)

      Set the value of the "host" header to use in STOMP CONNECT frames. When this property is configured, a "host" header will be added to every STOMP frame sent to the STOMP broker. This may be useful for example in a cloud environment where the actual host to which the TCP connection is established is different from the host providing the cloud-based STOMP service.

      By default this property is not set.

    - #### getVirtualHost

          public String getVirtualHost()

      Returns:
        the configured virtual host value.

    - #### setTcpClient

          public void setTcpClient(TcpOperations<byte[]> tcpClient)

      Configure a TCP client for managing TCP connections to the STOMP broker. By default `ReactorTcpClient` is used.

    - #### getTcpClient

          public TcpOperations<byte[]> getTcpClient()

      Get the configured TCP client. Never `null` unless not configured invoked and this method is invoked before the handler is started and hence a default implementation initialized.

    - #### startInternal

          protected void startInternal()

      Overrides:
        `startInternal` in class `AbstractBrokerMessageHandler`

    - #### stopInternal

          protected void stopInternal()

      Overrides:
        `stopInternal` in class `AbstractBrokerMessageHandler`

    - #### handleMessageInternal

          protected void handleMessageInternal(Message<?> message)

      Specified by:
        `handleMessageInternal` in class `AbstractBrokerMessageHandler`