Interface MessagingService

public interface MessagingService
Service for cross-proxy messaging via pub/sub.

Provides publish/subscribe functionality for communication between proxy instances in a distributed deployment. The underlying implementation typically uses Redis, but the API is backend-agnostic.

Thread Safety

All methods are thread-safe. Message handlers are invoked on a dedicated thread pool and should not block.

Connection State

The service handles connection failures gracefully. When disconnected, publish operations fail fast and subscriptions are restored on reconnection.

See Also:

  • Method Details

    • isConnected

      boolean isConnected()
      Check if the messaging service is connected and operational.
      Returns:
      true if connected to the messaging backend

    • publish

      @Nonnull CompletableFuture<Void> publish(@Nonnull MessageChannel channel, @Nonnull ChannelMessage message)
      Publish a message to a channel.
      Parameters:
      channel - the channel to publish to
      message - the message to publish
      Returns:
      a future that completes when the message is sent

    • publishPlugin

      @Nonnull CompletableFuture<Void> publishPlugin(@Nonnull String pluginId, @Nonnull String channel, @Nonnull Object data)
      Publish a plugin-specific message to other proxies.
      Parameters:
      pluginId - your plugin's unique identifier
      channel - the sub-channel within your plugin
      data - the data object to send (will be serialized to JSON)
      Returns:
      a future that completes when the message is sent

    • subscribe

      @Nonnull Subscription subscribe(@Nonnull MessageChannel channel, @Nonnull MessageHandler<ChannelMessage> handler)
      Subscribe to messages on a channel.
      Parameters:
      channel - the channel to subscribe to
      handler - the handler to invoke for each message
      Returns:
      a subscription that can be used to unsubscribe

    • subscribe

      @Nonnull <T extends ChannelMessage> Subscription subscribe(@Nonnull MessageChannel channel, @Nonnull Class<T> messageType, @Nonnull MessageHandler<T> handler)
      Subscribe to messages of a specific type on a channel.
      Type Parameters:
      T - the message type
      Parameters:
      channel - the channel to subscribe to
      messageType - the message type to filter for
      handler - the handler to invoke for matching messages
      Returns:
      a subscription that can be used to unsubscribe

    • subscribeIncludingSelf

      @Nonnull Subscription subscribeIncludingSelf(@Nonnull MessageChannel channel, @Nonnull MessageHandler<ChannelMessage> handler)
      Subscribe to messages on a channel, including messages from the local proxy.
      Parameters:
      channel - the channel to subscribe to
      handler - the handler to invoke for each message
      Returns:
      a subscription that can be used to unsubscribe

    • subscribePlugin

      @Nonnull <T> Subscription subscribePlugin(@Nonnull String pluginId, @Nonnull String channel, @Nonnull Class<T> dataType, @Nonnull PluginMessageHandler<T> handler)
      Subscribe to plugin-specific messages with automatic deserialization.
      Type Parameters:
      T - your custom data type
      Parameters:
      pluginId - the plugin identifier to listen for
      channel - the sub-channel within the plugin
      dataType - the class of your custom data type
      handler - the handler to invoke with deserialized data
      Returns:
      a subscription that can be used to unsubscribe

    • unsubscribeAll

      void unsubscribeAll(@Nonnull MessageChannel channel)
      Unsubscribe all handlers from a channel.
      Parameters:
      channel - the channel to unsubscribe from

    • registerListener

      @Nonnull Subscription registerListener(@Nonnull Object listener)
      Register a listener object containing @Subscribe-annotated methods.
      Parameters:
      listener - the listener object
      Returns:
      a composite subscription that can unsubscribe all methods at once

    • registerListener

      @Nonnull Subscription registerListener(@Nonnull Object listener, @Nonnull Object plugin)
      Register a listener object with explicit plugin context.
      Parameters:
      listener - the listener object
      plugin - the plugin instance (must have @Plugin annotation)
      Returns:
      a composite subscription that can unsubscribe all methods at once

    • unregisterListener

      void unregisterListener(@Nonnull Object listener)
      Unregister a listener previously registered with registerListener(Object).
      Parameters:
      listener - the listener to unregister

    • registerTypeAdapter

      <T> void registerTypeAdapter(@Nonnull TypeAdapter<T> adapter)
      Register a custom type adapter for message serialization.
      Type Parameters:
      T - the type handled by the adapter
      Parameters:
      adapter - the type adapter to register

    • unregisterTypeAdapter

      void unregisterTypeAdapter(@Nonnull Class<?> type)
      Unregister a type adapter.
      Parameters:
      type - the type to unregister the adapter for