Record Class ChannelMessage

java.lang.Object
java.lang.Record
eu.cloudnetservice.driver.channel.ChannelMessage
Record Components:
sendSync - whether sending the message should block the current thread until the message is flushed.
prioritized - whether this channel message should be handled with priority over other channel messages.
channel - the channel to which the channel message gets sent. Mostly for identification reasons.
message - the message key of this channel message. Mostly for identification reasons.
content - the content of this channel message (the actual data to send).
sender - the sender of the channel message. Should be, but must not the current network component.
targets - the targets to which the channel message should get send.
All Implemented Interfaces:
AutoCloseable
public record ChannelMessage(boolean sendSync, boolean prioritized, @NonNull String channel, @NonNull String message, @NonNull DataBuf content, @NonNull ChannelMessageSender sender, @NonNull Collection<ChannelMessageTarget> targets) extends Record implements AutoCloseable
Represents a message object that can be sent over the network with specific targets in mind. Unlike direct packet communication, channel messages are not bound to specific messaging channels but can rather get sent to all components that are somewhere connected in the network. This means that it is possible to send a channel message to a service which is running on another node than the service which is sending the channel message.

A channel message has two main identification points. One is the channel to which the message gets sent. The channel is a string generally used to group channel messages together. This is, for example, useful to identify all channel messages that are sent by a specific module. Further narrowing of the message type is done by using the message key, which should uniquely identify the specific message. Each channel message must be composed of a unique channel and message to distinguish it from other messages being sent in the cluster.

The message contains a DataBuf containing the actual content of the message. There is no real way to identify which types are in the buffer or not, therefore, it is crucial that a channel message gets identified via its channel and message keys.

If targets were given that are not locatable in the network, they will get ignored silently.

Note: there is no guarantee that the sender of a channel message is the actual component sending the message, as the message can be modified on its way to the receiver.

The actual constructor of this class shouldn't get used. Use builder() instead.

Since:
4.0
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • builder

      @Contract(" -> new") @NonNull public static @NonNull ChannelMessage.Builder builder()
      Constructs a new, empty builder for a ChannelMessage.
      Returns:
      a new, empty builder for a ChannelMessage.

    • buildResponseFor

      @Contract("_ -> new") @NonNull public static @NonNull ChannelMessage.Builder buildResponseFor(@NonNull @NonNull ChannelMessage input)
      Constructs a new builder which contains all necessary data to respond to a channel message. As the channel message will get directly handled by the waiting future, there is no need to actually set the channel and message of the returned builder. The new builder will target the sender of the given input and has no data set.
      Parameters:
      input - the channel message to respond to.
      Returns:
      a new builder for a channel message holding all base information to respond to the given source message.
      Throws:
      NullPointerException - if the given input is null.

    • send

      public void send()
      Sends this channel message using the current messenger of the environment. This is a shortcut method for CloudMessenger.sendChannelMessage(ChannelMessage). This method will not wait for the target component to respond (it doesn't even expect a response) but for the handling component to send the message.

      Note: once the channel message was sent, the backing buffer gets released. Therefore, the caller must acquire the content buffer if this channel message is sent multiple times.

    • sendQueryAsync

      @NonNull public @NonNull CompletableFuture<Collection<ChannelMessage>> sendQueryAsync()
      Sends this channel message as a query and returns a future which waits for target component(s) to respond. This method is a shortcut for CloudMessenger.sendChannelMessageQueryAsync(ChannelMessage). The future will be completed when the target component responds or the query future times out.

      Note: it is not possible for CloudNet to detect when a channel message query response was consumed. Therefore, it is crucial that the caller closes the responses to prevent memory leaks. Example: 

      
ChannelMessage message = ...;
message.sendQueryAsync().thenAccept(responses -> {
  for (var response : responses) {
    try (response) {
      // do something with the response
    }
  }
}
      Returns:
      a future completed with all responses of all components targeted by this channel message.

    • sendSingleQueryAsync

      @NonNull public @NonNull CompletableFuture<ChannelMessage> sendSingleQueryAsync()
      Sends this channel message as a query and returns a future which waits for target component(s) to respond. Only the first response of any target will get sent back to this component. This is in particular useful if there is only one target, or you are only expecting one of the target components to respond. This is a shortcut method for CloudMessenger.sendSingleChannelMessageQueryAsync(ChannelMessage). The future will be completed with the first received response of any target component (possibly null if no target responded).

      Note: it is not possible for CloudNet to detect when a channel message query response was consumed. Therefore, it is crucial that the caller closes the response to prevent memory leaks. Example: 

      
ChannelMessage message = ...;
message.sendSingleQueryAsync().thenAccept(response -> {
  if (response != null) {
    try (response) {
      // do something with the response
    }
  }
}
      Returns:
      a future completed with the first received response of any target component or null if no target responded.

    • sendQuery

      @NonNull public @NonNull Collection<ChannelMessage> sendQuery()
      Sends this channel message as a query and blocks until all target components have responded to the query or the timeout of CloudMessenger.SYNC_CHANNEL_MESSAGE_QUERY_TIMEOUT_MS is exceeded. If more control over the timeout is required, an async method with a custom timeout applied must be used instead. This method is a shortcut for CloudMessenger.sendChannelMessageQuery(ChannelMessage).

      Note: it is not possible for CloudNet to detect when a channel message query response was consumed. Therefore, it is crucial that the caller closes the responses to prevent memory leaks. Example: 

      
ChannelMessage message = ...;
Collection<ChannelMessage> responses = message.sendQuery();
for (var response : responses) {
  try (response) {
    // do something with the response
  }
}
      Returns:
      all responses of all components this channel message is targeting.
      Throws:
      CompletionException - if an exception occurred while waiting for the query responses.

    • sendSingleQuery

      @Nullable public @Nullable ChannelMessage sendSingleQuery()
      Sends this channel message as a query and blocks until one of the target component responded to this message or the timeout of CloudMessenger.SYNC_CHANNEL_MESSAGE_QUERY_TIMEOUT_MS is exceeded. If more control over the timeout is required, an async method with a custom timeout applied must be used instead. This is in particular useful if there is only one target, or you are only expecting one of the target components to respond. This is a shortcut method for CloudMessenger.sendSingleChannelMessageQuery(ChannelMessage).

      Note: it is not possible for CloudNet to detect when a channel message query response was consumed. Therefore, it is crucial that the caller closes the response to prevent memory leaks. Example: 

      
ChannelMessage message = ...;
ChannelMessage response = message.sendSingleQuery();
if (response != null) {
  try (response) {
    // do something with the response
  }
}
      Returns:
      the first response of any component this message is targeting, null if no target responded.
      Throws:
      CompletionException - if an exception occurred while waiting for the query response.

    • messenger

      @Internal @NonNull private @NonNull CloudMessenger messenger()
      Util method to get the current messenger of the environment.
      Returns:
      the current messenger of the environment.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • sendSync

      public boolean sendSync()
      Returns the value of the sendSync record component.
      Returns:
      the value of the sendSync record component

    • prioritized

      public boolean prioritized()
      Returns the value of the prioritized record component.
      Returns:
      the value of the prioritized record component

    • channel

      @NonNull public @NonNull String channel()
      Returns the value of the channel record component.
      Returns:
      the value of the channel record component

    • message

      @NonNull public @NonNull String message()
      Returns the value of the message record component.
      Returns:
      the value of the message record component

    • content

      @NonNull public @NonNull DataBuf content()
      Returns the value of the content record component.
      Returns:
      the value of the content record component

    • sender

      @NonNull public @NonNull ChannelMessageSender sender()
      Returns the value of the sender record component.
      Returns:
      the value of the sender record component

    • targets

      @NonNull public @NonNull Collection<ChannelMessageTarget> targets()
      Returns the value of the targets record component.
      Returns:
      the value of the targets record component