org.springframework.messaging.simp.user

## Class UserDestinationMessageHandler

- java.lang.Object
- - org.springframework.messaging.simp.user.UserDestinationMessageHandler

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

      public class UserDestinationMessageHandler
      extends Object
      implements MessageHandler, SmartLifecycle

  `MessageHandler` with support for "user" destinations.

  Listens for messages with "user" destinations, translates their destination to actual target destinations unique to the active session(s) of a user, and then sends the resolved messages to the broker channel to be delivered.

  Since:
    4.0
  Author:
    Rossen Stoyanchev

- - ### Field Summary

    - ### Fields inherited from interface org.springframework.context.SmartLifecycle

      `DEFAULT_PHASE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UserDestinationMessageHandler(SubscribableChannel clientInboundChannel, SubscribableChannel brokerChannel, UserDestinationResolver resolver)` Create an instance with the given client and broker channels subscribing to handle messages from each and then sending any resolved messages to the broker channel.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getBroadcastDestination()` Return the configured destination for unresolved messages.
    `MessageSendingOperations<String>` | `getBrokerMessagingTemplate()` Return the messaging template used to send resolved messages to the broker channel.
    `MessageHeaderInitializer` | `getHeaderInitializer()` Return the configured header initializer.
    `UserDestinationResolver` | `getUserDestinationResolver()` Return the configured `UserDestinationResolver`.
    `void` | `handleMessage(Message<?> message)` Handle the given message.
    `boolean` | `isRunning()` Check whether this component is currently running.
    `void` | `setBroadcastDestination(String destination)` Set a destination to broadcast messages to that remain unresolved because the user is not connected.
    `void` | `setHeaderInitializer(MessageHeaderInitializer headerInitializer)` Configure a custom `MessageHeaderInitializer` to initialize the headers of resolved target messages.
    `void` | `start()` Start this component.
    `void` | `stop()` Stop this component, typically in a synchronous fashion, such that the component is fully stopped upon return of this method.
    `void` | `stop(Runnable callback)` Indicates that a Lifecycle component must stop if it is currently running.
    `String` | `toString()`

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

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

    - ### Methods inherited from interface org.springframework.context.SmartLifecycle

      `getPhase, isAutoStartup`

- - ### Constructor Detail

    - #### UserDestinationMessageHandler

          public UserDestinationMessageHandler(SubscribableChannel clientInboundChannel,
                                               SubscribableChannel brokerChannel,
                                               UserDestinationResolver resolver)

      Create an instance with the given client and broker channels subscribing to handle messages from each and then sending any resolved messages to the broker channel.
      Parameters:
        `clientInboundChannel` - messages received from clients.
        `brokerChannel` - messages sent to the broker.
        `resolver` - the resolver for "user" destinations.

  - ### Method Detail

    - #### getUserDestinationResolver

          public UserDestinationResolver getUserDestinationResolver()

      Return the configured `UserDestinationResolver`.

    - #### setBroadcastDestination

          public void setBroadcastDestination(@Nullable
                                              String destination)

      Set a destination to broadcast messages to that remain unresolved because the user is not connected. In a multi-application server scenario this gives other application servers a chance to try.

      By default this is not set.

      Parameters:
        `destination` - the target destination.

    - #### getBroadcastDestination

          @Nullable
          public String getBroadcastDestination()

      Return the configured destination for unresolved messages.

    - #### getBrokerMessagingTemplate

          public MessageSendingOperations<String> getBrokerMessagingTemplate()

      Return the messaging template used to send resolved messages to the broker channel.

    - #### setHeaderInitializer

          public void setHeaderInitializer(@Nullable
                                           MessageHeaderInitializer headerInitializer)

      Configure a custom `MessageHeaderInitializer` to initialize the headers of resolved target messages.

      By default this is not set.

    - #### getHeaderInitializer

          @Nullable
          public MessageHeaderInitializer getHeaderInitializer()

      Return the configured header initializer.

    - #### start

          public final void start()

      Description copied from interface: `Lifecycle`
      Start this component.

      Should not throw an exception if the component is already running.

      In the case of a container, this will propagate the start signal to all components that apply.

      Specified by:
        `start` in interface `Lifecycle`
      See Also:
        `SmartLifecycle.isAutoStartup()`

    - #### stop

          public final void stop()

      Description copied from interface: `Lifecycle`
      Stop this component, typically in a synchronous fashion, such that the component is fully stopped upon return of this method. Consider implementing `SmartLifecycle` and its `stop(Runnable)` variant when asynchronous stop behavior is necessary.

      Note that this stop notification is not guaranteed to come before destruction: On regular shutdown, `Lifecycle` beans will first receive a stop notification before the general destruction callbacks are being propagated; however, on hot refresh during a context's lifetime or on aborted refresh attempts, a given bean's destroy method will be called without any consideration of stop signals upfront.

      Should not throw an exception if the component is not running (not started yet).

      In the case of a container, this will propagate the stop signal to all components that apply.

      Specified by:
        `stop` in interface `Lifecycle`
      See Also:
        `SmartLifecycle.stop(Runnable)`, `DisposableBean.destroy()`

    - #### stop

          public final void stop(Runnable callback)

      Description copied from interface: `SmartLifecycle`
      Indicates that a Lifecycle component must stop if it is currently running.

      The provided callback is used by the `LifecycleProcessor` to support an ordered, and potentially concurrent, shutdown of all components having a common shutdown order value. The callback must be executed after the `SmartLifecycle` component does indeed stop.

      The `LifecycleProcessor` will call only this variant of the `stop` method; i.e. `Lifecycle.stop()` will not be called for `SmartLifecycle` implementations unless explicitly delegated to within the implementation of this method.

      The default implementation delegates to `Lifecycle.stop()` and immediately triggers the given callback in the calling thread. Note that there is no synchronization between the two, so custom implementations may at least want to put the same steps within their common lifecycle monitor (if any).

      Specified by:
        `stop` in interface `SmartLifecycle`
      See Also:
        `Lifecycle.stop()`, `SmartLifecycle.getPhase()`

    - #### isRunning

          public final boolean isRunning()

      Description copied from interface: `Lifecycle`
      Check whether this component is currently running.

      In the case of a container, this will return `true` only if all components that apply are currently running.

      Specified by:
        `isRunning` in interface `Lifecycle`
      Returns:
        whether the component is currently running

    - #### handleMessage

          public void handleMessage(Message<?> message)
                             throws MessagingException

      Description copied from interface: `MessageHandler`
      Handle the given message.
      Specified by:
        `handleMessage` in interface `MessageHandler`
      Parameters:
        `message` - the message to be handled
      Throws:
        `MessagingException` - if the handler failed to process the message

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`