Class ChannelMessage.Builder

java.lang.Object
eu.cloudnetservice.driver.channel.ChannelMessage.Builder
Enclosing class:
ChannelMessage
public static final class ChannelMessage.Builder extends Object
A builder for a channel message. This class should be used over direct constructor access as allows better customization and validation of a channel message which gets created. Required properties are:
  • channel, can be empty
  • message, can be empty
  • at least one target for the message

If no sender for the message is given, the current network component will be used as the sender of the message. The build() method can only be called once for a channel message builder instance.

Since:
4.0

  • Field Details

  • Constructor Details

  • Method Details

    • sender

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder sender(@NonNull @NonNull ChannelMessageSender sender)
      Sets the sender of this message. If no sender is given, the current component will be used as the sender.
      Parameters:
      sender - the sender of this message.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given sender is null.

    • channel

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder channel(@NonNull @NonNull String channel)
      Sets the channel of this message. The channel is primarily intended to group channel message of, for example, the same module. This makes it much easier for receivers to assess whether a message should get handled by them. It can be empty but should be unique to identify for the receiver.
      Parameters:
      channel - the channel of this message.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given channel is null.

    • message

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder message(@NonNull @NonNull String message)
      Sets the message key of this message. The key is primarily intended to uniquely identify one specific message to the receiver. It can be empty but should be unique to identify for the receiver.
      Parameters:
      message - the message key.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given message is null.

    • sendSync

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder sendSync(boolean sync)
      Sets if the channel message should get send sync, blocking the sending thread until the message was written and flushed through the network layer.
      Parameters:
      sync - if the message should get send sync.
      Returns:
      the same builder as used to call the method, for chaining.

    • prioritized

      @Contract("_ -> this") @Experimental @NonNull public @NonNull ChannelMessage.Builder prioritized(boolean prioritized)
      Sets if the channel message should get prioritized processing on the receiving components.

      USE WITH CAUTION! This can cause other lags and delays in the network handling of the receivers. Use this option only if you know what you're doing and are sure that the packet is urgent for CloudNet to work for as expected. Otherwise, don't touch this method.

      Parameters:
      prioritized - if the channel message should get prioritized processing on the receiving components.
      Returns:
      the same builder as used to call the method, for chaining.

    • target

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder target(@NonNull @NonNull ChannelMessageTarget target)
      Adds the given channel message target as a target of this message.
      Parameters:
      target - the target to add.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given target is null.

    • targetAll

      @Contract(" -> this") @NonNull public @NonNull ChannelMessage.Builder targetAll()
      Targets all components within the network.
      Returns:
      the same builder as used to call the method, for chaining.

    • targetNodes

      @Contract(" -> this") @NonNull public @NonNull ChannelMessage.Builder targetNodes()
      Targets all nodes within the network.
      Returns:
      the same builder as used to call the method, for chaining.

    • targetServices

      @Contract(" -> this") @NonNull public @NonNull ChannelMessage.Builder targetServices()
      Targets all services within the network.
      Returns:
      the same builder as used to call the method, for chaining.

    • targetNode

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetNode(@NonNull @NonNull String nodeId)
      Targets a specific node within the network.
      Parameters:
      nodeId - the id of the node to target.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given node id is null.

    • targetService

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetService(@NonNull @NonNull String serviceName)
      Targets a specific service in the network.
      Parameters:
      serviceName - the name of the service to target.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given service name is null.

    • targetServicesOfTask

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetServicesOfTask(@NonNull @NonNull String taskName)
      Targets all services of the given task within the network.
      Parameters:
      taskName - the name of the task to target.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given task name is null.

    • targetServicesOfGroup

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetServicesOfGroup(@NonNull @NonNull String groupName)
      Targets all services of the given group within the network.
      Parameters:
      groupName - the name of the group to target.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given group name is null.

    • targetServicesOfEnvironment

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetServicesOfEnvironment(@NonNull @NonNull String environmentName)
      Targets all services with the given environment within the network.
      Parameters:
      environmentName - the name of the environment to target.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given environment name is null.

    • targetServicesWithProperty

      @Contract("_ -> this") @NonNull public @NonNull ChannelMessage.Builder targetServicesWithProperty(@NonNull @NonNull String propertyKey)
      Targets all services that have the given property key associated with any value within the network.
      Parameters:
      propertyKey - the key of the property that must be associated on target services.
      Returns:
      the same builder as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given property key is null.

    • build

      @Contract(" -> new") @NonNull public @NonNull ChannelMessage build()
      Builds a channel message from this builder, using an empty buffer as the content.
      Returns:
      the created channel message from this builder.
      Throws:
      NullPointerException - if no message or channel is provided.
      IllegalArgumentException - if no target was specified.
      IllegalStateException - if this method was called previously.

    • build

      @Contract("_ -> new") @NonNull public @NonNull ChannelMessage build(@NonNull @NonNull DataBuf content)
      Builds a channel message from this builder, using the given buffer as the content of it.
      Parameters:
      content - the buffer containing the content of the channel message.
      Returns:
      the created channel message from this builder.
      Throws:
      NullPointerException - if the given content buffer is null, or no channel/message was provided.
      IllegalArgumentException - if an invalid argument was provided to this builder.

    • build

      @Contract("_ -> new") @NonNull public @NonNull ChannelMessage build(@NonNull @NonNull UnaryOperator<DataBuf.Mutable> contentDecorator)
      Builds a channel message from this builder, using the given decorator function to write the content of the channel message into the buffer before building.

      Note: the decorator function is NOT allowed to return a different buffer instance than the one passed to it. This is only a function, as it makes it easier to use compared to a consumer.

      Parameters:
      contentDecorator - decorator function that writes the content of the channel message into the buffer.
      Returns:
      the created channel message from this builder.
      Throws:
      NullPointerException - if the given decorator function is null.
      IllegalStateException - if the decorator returns a different buffer or releases the given buffer.