Interface CloudMessenger

public interface CloudMessenger
The main messaging api for communication in any form between components in the CloudNet cluster aside from sending raw packets. The main difference between the raw packet api (network component based) and this api is, that this network point will search the route to the target component rather than only accepting direct writes to a specific target component.

The target component search is only one layer deep, meaning that you can only send a channel message to another component in the network known to the handling node, or its parent component (for services). Any other communication form would break the normal CloudNet cluster structure. Channel messages can get send to:

  1. Services: in this case the handling node tries either to send the message directly to the service (if it is running on the local node) or via the parent node of the service (which must be connected!).
  2. Nodes: in this case the handling node sends the channel message directly to the connected node. There is no second layer check, all nodes must be connected to all nodes (as per the CloudNet cluster contract). This means that if (for example) Node-3 is only connected to Node-2 (which is connected to Node-1), and Node-1 receives a channel message for Node-3 this will not work. This will work:
    1. Node-1 gets a message for Node-2 (or the other way around).
    2. Node-2 gets a message for Node-3 (or the other way around).

A channel message received by a network component should always be acknowledged by the handling participant if it is a query message to prevent possible deadlocks on the sender side.

Since:
4.0
See Also:

  • Method Details

    • sendChannelMessage

      void sendChannelMessage(@NonNull @NonNull ChannelMessage channelMessage)
      Sends the given channel message to all of its targets without waiting for a response from them.
      Parameters:
      channelMessage - the channel message to send.
      Throws:
      NullPointerException - if the given channel message is null.

    • sendChannelMessageQuery

      @NonNull @NonNull Collection<ChannelMessage> sendChannelMessageQuery(@NonNull @NonNull ChannelMessage channelMessage)
      Sends the given channel message to all of its targets and waits for all responses to be present or the query to time out.
      Parameters:
      channelMessage - the channel message to send.
      Returns:
      all responses from all network components which responded in time.
      Throws:
      NullPointerException - if the given channel message is null.

    • sendSingleChannelMessageQuery

      @Nullable @Nullable ChannelMessage sendSingleChannelMessageQuery(@NonNull @NonNull ChannelMessage channelMessage)
      Sends the given channel message to all of its targets and waits for all responses to be present or the query to time out. This method will then peek the first response out of the returned array, or return null if no components answered to the request.
      Parameters:
      channelMessage - the channel message to send.
      Returns:
      the first response to the given channel message, can be null if no target responded.
      Throws:
      NullPointerException - if the given channel message is null.

    • sendChannelMessageAsync

      @NonNull @NonNull CompletableFuture<Void> sendChannelMessageAsync(@NonNull @NonNull ChannelMessage channelMessage)
      Sends the given channel message to all of its targets without waiting for a response from them.
      Parameters:
      channelMessage - the channel message to send.
      Returns:
      a task completed when all channel messages were sent.
      Throws:
      NullPointerException - if the given channel message is null.

    • sendChannelMessageQueryAsync

      @NonNull @NonNull CompletableFuture<Collection<ChannelMessage>> sendChannelMessageQueryAsync(@NonNull @NonNull ChannelMessage message)
      Sends the given channel message to all of its targets and waits for all responses to be present or the query to time out.
      Parameters:
      message - the channel message to send.
      Returns:
      a task completed with all responses from all network components which responded in time.
      Throws:
      NullPointerException - if the given channel message is null.

    • sendSingleChannelMessageQueryAsync

      @NonNull @NonNull CompletableFuture<ChannelMessage> sendSingleChannelMessageQueryAsync(@NonNull @NonNull ChannelMessage channelMessage)
      Sends the given channel message to all of its targets and waits for all responses to be present or the query to time out. This method will then peek the first response out of the returned array, or return null if no components answered to the request.
      Parameters:
      channelMessage - the channel message to send.
      Returns:
      a task completed with the first response to the given channel message, can be null if no target responded.
      Throws:
      NullPointerException - if the given channel message is null.