Package me.croabeast.takion.message

Class MessageSender

java.lang.Object
me.croabeast.takion.message.MessageSender
All Implemented Interfaces:
Copyable<MessageSender>
public class MessageSender extends Object implements Copyable<MessageSender>
A versatile message sender that formats and dispatches messages to players or external services.

MessageSender is designed for use in Minecraft plugins to process messages before sending. It supports dynamic message formatting, placeholder replacement, function-based text modifications, and conditional logging. Messages are formatted based on a chain of text appliers, and can be sent to one or more target players or even via webhook if no target is provided.

Key features:

  • Manage a collection of Placeholder objects that are dynamically replaced in messages.
  • Support for custom PlayerFormatter functions to alter messages based on player context.
  • Flexible target setting: messages can be sent to individual players, collections of players, or broadcast as system messages.
  • Flag filtering using Channel.Flag to control which message types are sent.
  • Automatic logging of messages if enabled, with an error prefix for unsent messages.

Example usage: 


 TakionLib lib = TakionLib.fromPlugin(plugin);

 MessageSender sender = new MessageSender(lib, player);
 sender.addPlaceholder("{player}", player.getName())
       .addFunctions(s -> s.toUpperCase())
       .setFlags(Channel.Flag.CHAT)
       .setLogger(true)
       .setErrorPrefix("invalid input: '&c'[ERROR]invalid input: '&'7 ");

 // Send a message to the player
 sender.send("Hello, {player}! Welcome to the server.");

See Also:

  • Constructor Details

    • MessageSender

      public MessageSender(TakionLib lib, Collection<? extends org.bukkit.entity.Player> targets, org.bukkit.entity.Player parser)
      Constructs a new MessageSender with the specified library instance, target players, and parser.
      Parameters:
      lib - the TakionLib instance (must not be null)
      targets - the collection of target players; may be null or empty
      parser - the player used as the formatting context; may be null

    • MessageSender

      public MessageSender(TakionLib lib, Collection<? extends org.bukkit.entity.Player> targets)
      Constructs a new MessageSender with the specified library instance and target players.
      Parameters:
      lib - the TakionLib instance
      targets - the collection of target players

    • MessageSender

      public MessageSender(TakionLib lib, org.bukkit.entity.Player player)
      Constructs a new MessageSender with the specified library instance and a single player.
      Parameters:
      lib - the TakionLib instance
      player - the player to target (if null, no target is set)

    • MessageSender

      public MessageSender(TakionLib lib)
      Constructs a new MessageSender with the specified library instance and no target players.
      Parameters:
      lib - the TakionLib instance

    • MessageSender

      public MessageSender(MessageSender sender)
      Copy constructor to create a new MessageSender from an existing instance.
      Parameters:
      sender - the MessageSender to copy

  • Method Details

    • setTargets

      public MessageSender setTargets(Collection<? extends org.bukkit.entity.Player> targets)
      Sets the target players for message sending.

      If the provided collection is null or empty, the targets are not modified.

      Parameters:
      targets - the collection of players to set as targets
      Returns:
      this MessageSender instance for chaining

    • setTargets

      public MessageSender setTargets(org.bukkit.command.CommandSender... senders)
      Sets the target players from an array of CommandSender objects.

      Only those that are instances of Player are retained.

      Parameters:
      senders - an array of command senders
      Returns:
      this MessageSender instance for chaining

    • setTargets

      public MessageSender setTargets(org.bukkit.entity.Player... targets)
      Sets the target players from an array of Player objects.
      Parameters:
      targets - an array of players
      Returns:
      this MessageSender instance for chaining

    • addFunctions

      public MessageSender addFunctions(PlayerFormatter... functions)
      Adds one or more PlayerFormatter functions to modify messages.
      Parameters:
      functions - an array of player formatters
      Returns:
      this MessageSender instance for chaining

    • addFunctions

      @SafeVarargs public final MessageSender addFunctions(UnaryOperator<String>... operators)
      Adds one or more UnaryOperator functions to modify messages.

      Each operator is wrapped as a PlayerFormatter that ignores the player parameter.

      Parameters:
      operators - an array of unary operators to modify messages
      Returns:
      this MessageSender instance for chaining

    • setFlags

      public MessageSender setFlags(Channel.Flag... flags)
      Sets the flags that determine which types of messages are allowed to be sent.
      Parameters:
      flags - an array of Channel.Flag values
      Returns:
      this MessageSender instance for chaining

    • addPlaceholder

      public <T> MessageSender addPlaceholder(Placeholder<T> placeholder)
      Adds a Placeholder to be applied in the message.
      Type Parameters:
      T - the type of the placeholder value
      Parameters:
      placeholder - the placeholder to add (its sensitive flag is updated to match this sender)
      Returns:
      this MessageSender instance for chaining

    • addPlaceholder

      public <T> MessageSender addPlaceholder(String key, T value)
      Adds a placeholder with a constant value.
      Type Parameters:
      T - the type of the placeholder value
      Parameters:
      key - the placeholder key
      value - the constant value for the placeholder
      Returns:
      this MessageSender instance for chaining

    • addPlaceholders

      public MessageSender addPlaceholders(Collection<? extends Placeholder<?>> placeholders)
      Adds multiple placeholders from a collection.
      Parameters:
      placeholders - a collection of placeholders to add
      Returns:
      this MessageSender instance for chaining

    • addPlaceholders

      public MessageSender addPlaceholders(Placeholder<?>... placeholders)
      Adds multiple placeholders from an array.
      Parameters:
      placeholders - an array of placeholders to add
      Returns:
      this MessageSender instance for chaining

    • addPlaceholders

      @SafeVarargs public final <T> MessageSender addPlaceholders(String[] keys, T... values)
      Adds placeholders using parallel arrays of keys and values.

      Both arrays must have the same length and be applicable for replacement.

      Type Parameters:
      T - the type of the placeholder values
      Parameters:
      keys - an array of placeholder keys
      values - an array of placeholder values
      Returns:
      this MessageSender instance for chaining
      Throws:
      NullPointerException - if keys and values are not applicable for replacement

    • copy

      @NotNull public @NotNull MessageSender copy()
      Creates a copy of this MessageSender.
      Specified by:
      copy in interface Copyable<MessageSender>
      Returns:
      a new MessageSender instance with the same configuration

    • send

      public boolean send(List<String> strings)
      Sends a list of messages to the target players.

      Each message is processed through formatting (placeholder replacement, function application, etc.) and then sent individually. If no target players are defined, messages are logged or sent via webhook if allowed.

      Parameters:
      strings - a list of raw message strings
      Returns:
      true if at least one message was sent successfully; false otherwise

    • send

      public boolean send(String... strings)
      Sends an array of messages to the target players.
      Parameters:
      strings - an array of raw message strings
      Returns:
      true if at least one message was sent successfully; false otherwise