Implemented new Plugin Message API - see http://dinnerbone.com/blog/2…

…012/01/13/minecraft-plugin-channels-messaging/

src/main/java/org/bukkit/Bukkit.java

@@ -17,6 +17,7 @@
 import org.bukkit.map.MapView;
 import org.bukkit.plugin.PluginManager;
 import org.bukkit.plugin.ServicesManager;
+import org.bukkit.plugin.messaging.Messenger;
 import org.bukkit.scheduler.BukkitScheduler;
 
 /**
@@ -286,4 +287,8 @@ public static Set<OfflinePlayer> getOperators() {
     public static File getWorldContainer() {
         return server.getWorldContainer();
     }
+
+    public static Messenger getMessenger() {
+        return server.getMessenger();
+    }
 }

src/main/java/org/bukkit/Server.java

@@ -20,12 +20,14 @@
 import org.bukkit.map.MapView;
 import org.bukkit.plugin.PluginManager;
 import org.bukkit.plugin.ServicesManager;
+import org.bukkit.plugin.messaging.Messenger;
+import org.bukkit.plugin.messaging.PluginMessageRecipient;
 import org.bukkit.scheduler.BukkitScheduler;
 
 /**
  * Represents a server implementation
  */
-public interface Server {
+public interface Server extends PluginMessageRecipient {
     /**
      * Used for all administrative messages, such as an operator using a command.
      *
@@ -533,4 +535,11 @@ public interface Server {
      * @return Array containing all players
      */
     public OfflinePlayer[] getOfflinePlayers();
+
+    /**
+     * Gets the {@link Messenger} responsible for this server.
+     *
+     * @return Messenger responsible for this server.
+     */
+    public Messenger getMessenger();
 }

src/main/java/org/bukkit/World.java

@@ -12,12 +12,13 @@
 import org.bukkit.entity.*;
 import org.bukkit.generator.BlockPopulator;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.plugin.messaging.PluginMessageRecipient;
 import org.bukkit.util.Vector;
 
 /**
  * Represents a world, which may contain entities, chunks and blocks
  */
-public interface World {
+public interface World extends PluginMessageRecipient {
 
     /**
      * Gets the {@link Block} at the given coordinates

src/main/java/org/bukkit/entity/Player.java

@@ -12,12 +12,13 @@
 import org.bukkit.Statistic;
 import org.bukkit.command.CommandSender;
 import org.bukkit.map.MapView;
+import org.bukkit.plugin.messaging.PluginMessageRecipient;
 
 /**
  * Represents a player, connected or not
  *
  */
-public interface Player extends HumanEntity, CommandSender, OfflinePlayer {
+public interface Player extends HumanEntity, CommandSender, OfflinePlayer, PluginMessageRecipient {
     /**
      * Gets the "friendly" name to display of this player. This may include color.
      *

src/main/java/org/bukkit/plugin/PluginManager.java

@@ -8,6 +8,7 @@
 import org.bukkit.event.Listener;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.permissions.Permission;
+import org.bukkit.plugin.messaging.PluginMessageListener;
 
 /**
  * Handles all plugin management from the Server

src/main/java/org/bukkit/plugin/messaging/ChannelNameTooLongException.java

@@ -0,0 +1,14 @@
+package org.bukkit.plugin.messaging;
+
+/**
+ * Thrown if a Plugin Channel is too long.
+ */
+public class ChannelNameTooLongException extends RuntimeException {
+    public ChannelNameTooLongException() {
+        super("Attempted to send a Plugin Message to a channel that was too large. The maximum length a channel may be is " + Messenger.MAX_CHANNEL_SIZE + " chars.");
+    }
+
+    public ChannelNameTooLongException(String channel) {
+        super("Attempted to send a Plugin Message to a channel that was too large. The maximum length a channel may be is " + Messenger.MAX_CHANNEL_SIZE + " chars (attempted " + channel.length() + " - '" + channel + ".");
+    }
+}

src/main/java/org/bukkit/plugin/messaging/ChannelNotRegisteredException.java

@@ -0,0 +1,14 @@
+package org.bukkit.plugin.messaging;
+
+/**
+ * Thrown if a Plugin attempts to send a message on an unregistered channel.
+ */
+public class ChannelNotRegisteredException extends RuntimeException {
+    public ChannelNotRegisteredException() {
+        this("Attempted to send a plugin message through an unregistered channel.");
+    }
+
+    public ChannelNotRegisteredException(String channel) {
+        super("Attempted to send a plugin message through an unregistered channel ('" + channel + "'.");
+    }
+}

src/main/java/org/bukkit/plugin/messaging/MessageTooLargeException.java

@@ -0,0 +1,22 @@
+package org.bukkit.plugin.messaging;
+
+/**
+ * Thrown if a Plugin Message is sent that is too large to be sent.
+ */
+public class MessageTooLargeException extends RuntimeException {
+    public MessageTooLargeException() {
+        this("Attempted to send a plugin message that was too large. The maximum length a plugin message may be is " + Messenger.MAX_MESSAGE_SIZE + " bytes.");
+    }
+
+    public MessageTooLargeException(byte[] message) {
+        this(message.length);
+    }
+
+    public MessageTooLargeException(int length) {
+        this("Attempted to send a plugin message that was too large. The maximum length a plugin message may be is " + Messenger.MAX_MESSAGE_SIZE + " bytes (tried to send one that is " + length + " bytes long).");
+    }
+
+    public MessageTooLargeException(String msg) {
+        super(msg);
+    }
+}

src/main/java/org/bukkit/plugin/messaging/Messenger.java

@@ -0,0 +1,201 @@
+package org.bukkit.plugin.messaging;
+
+import java.util.Set;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+
+/**
+ * A class responsible for managing the registrations of plugin channels and their
+ * listeners.
+ */
+public interface Messenger {
+    /**
+     * Represents the largest size that an individual Plugin Message may be.
+     */
+    public static final int MAX_MESSAGE_SIZE = 32766;
+
+    /**
+     * Represents the largest size that a Plugin Channel may be.
+     */
+    public static final int MAX_CHANNEL_SIZE = 16;
+
+    /**
+     * Checks if the specified channel is a reserved name.
+     *
+     * @param channel Channel name to check.
+     * @return True if the channel is reserved, otherwise false.
+     * @throws IllegalArgumentException Thrown if channel is null.
+     */
+    public boolean isReservedChannel(String channel);
+
+    /**
+     * Registers the specific plugin to the requested outgoing plugin channel, allowing it
+     * to send messages through that channel to any clients.
+     *
+     * @param plugin Plugin that wishes to send messages through the channel.
+     * @param channel Channel to register.
+     * @throws IllegalArgumentException Thrown if plugin or channel is null.
+     */
+    public void registerOutgoingPluginChannel(Plugin plugin, String channel);
+
+    /**
+     * Unregisters the specific plugin from the requested outgoing plugin channel, no longer
+     * allowing it to send messages through that channel to any clients.
+     *
+     * @param plugin Plugin that no longer wishes to send messages through the channel.
+     * @param channel Channel to unregister.
+     * @throws IllegalArgumentException Thrown if plugin or channel is null.
+     */
+    public void unregisterOutgoingPluginChannel(Plugin plugin, String channel);
+
+    /**
+     * Unregisters the specific plugin from all outgoing plugin channels, no longer allowing
+     * it to send any plugin messages.
+     *
+     * @param plugin Plugin that no longer wishes to send plugin messages.
+     * @throws IllegalArgumentException Thrown if plugin is null.
+     */
+    public void unregisterOutgoingPluginChannel(Plugin plugin);
+
+    /**
+     * Registers the specific plugin for listening on the requested incoming plugin channel,
+     * allowing it to act upon any plugin messages.
+     *
+     * @param plugin Plugin that wishes to register to this channel.
+     * @param channel Channel to register.
+     * @param listener Listener to receive messages on.
+     * @returns The resulting registration that was made as a result of this method.
+     * @throws IllegalArgumentException Thrown if plugin, channel or listener is null, or the listener is already registered for this channel.
+     */
+    public PluginMessageListenerRegistration registerIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);
+
+    /**
+     * Unregisters the specific plugin's listener from listening on the requested incoming plugin channel,
+     * no longer allowing it to act upon any plugin messages.
+     *
+     * @param plugin Plugin that wishes to unregister from this channel.
+     * @param channel Channel to unregister.
+     * @param listener Listener to stop receiving messages on.
+     * @throws IllegalArgumentException Thrown if plugin, channel or listener is null.
+     */
+    public void unregisterIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);
+
+    /**
+     * Unregisters the specific plugin from listening on the requested incoming plugin channel,
+     * no longer allowing it to act upon any plugin messages.
+     *
+     * @param plugin Plugin that wishes to unregister from this channel.
+     * @param channel Channel to unregister.
+     * @throws IllegalArgumentException Thrown if plugin or channel is null.
+     */
+    public void unregisterIncomingPluginChannel(Plugin plugin, String channel);
+
+    /**
+     * Unregisters the specific plugin from listening on all plugin channels through all listeners.
+     *
+     * @param plugin Plugin that wishes to unregister from this channel.
+     * @throws IllegalArgumentException Thrown if plugin is null.
+     */
+    public void unregisterIncomingPluginChannel(Plugin plugin);
+
+    /**
+     * Gets a set containing all the outgoing plugin channels.
+     *
+     * @return List of all registered outgoing plugin channels.
+     */
+    public Set<String> getOutgoingChannels();
+
+    /**
+     * Gets a set containing all the outgoing plugin channels that the specified plugin is registered to.
+     *
+     * @param plugin Plugin to retrieve channels for.
+     * @return List of all registered outgoing plugin channels that a plugin is registered to.
+     * @throws IllegalArgumentException Thrown if plugin is null.
+     */
+    public Set<String> getOutgoingChannels(Plugin plugin);
+
+    /**
+     * Gets a set containing all the incoming plugin channels.
+     *
+     * @return List of all registered incoming plugin channels.
+     */
+    public Set<String> getIncomingChannels();
+
+    /**
+     * Gets a set containing all the incoming plugin channels that the specified plugin is registered for.
+     *
+     * @param plugin Plugin to retrieve channels for.
+     * @return List of all registered incoming plugin channels that the plugin is registered for.
+     * @throws IllegalArgumentException Thrown if plugin is null.
+     */
+    public Set<String> getIncomingChannels(Plugin plugin);
+
+    /**
+     * Gets a set containing all the incoming plugin channel registrations that the specified plugin has.
+     *
+     * @param plugin Plugin to retrieve registrations for.
+     * @return List of all registrations that the plugin has.
+     * @throws IllegalArgumentException Thrown if plugin is null.
+     */
+    public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin);
+
+    /**
+     * Gets a set containing all the incoming plugin channel registrations that are on the requested channel.
+     *
+     * @param channel Channel to retrieve registrations for.
+     * @return List of all registrations that are on the channel.
+     * @throws IllegalArgumentException Thrown if channel is null.
+     */
+    public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(String channel);
+
+    /**
+     * Gets a set containing all the incoming plugin channel registrations that the specified plugin has
+     * on the requested channel.
+     *
+     * @param plugin Plugin to retrieve registrations for.
+     * @param channel Channel to filter registrations by.
+     * @return List of all registrations that the plugin has.
+     * @throws IllegalArgumentException Thrown if plugin or channel is null.
+     */
+    public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin, String channel);
+
+    /**
+     * Checks if the specified plugin message listener registration is valid.
+     * <p>
+     * A registration is considered valid if it has not be unregistered and that the plugin
+     * is still enabled.
+     * 
+     * @param registration Registration to check.
+     * @return True if the registration is valid, otherwise false.
+     */
+    public boolean isRegistrationValid(PluginMessageListenerRegistration registration);
+
+    /**
+     * Checks if the specified plugin has registered to receive incoming messages through the requested
+     * channel.
+     *
+     * @param plugin Plugin to check registration for.
+     * @param channel Channel to test for.
+     * @return True if the channel is registered, else false.
+     */
+    public boolean isIncomingChannelRegistered(Plugin plugin, String channel);
+
+    /**
+     * Checks if the specified plugin has registered to send outgoing messages through the requested
+     * channel.
+     *
+     * @param plugin Plugin to check registration for.
+     * @param channel Channel to test for.
+     * @return True if the channel is registered, else false.
+     */
+    public boolean isOutgoingChannelRegistered(Plugin plugin, String channel);
+
+    /**
+     * Dispatches the specified incoming message to any registered listeners.
+     *
+     * @param source Source of the message.
+     * @param channel Channel that the message was sent by.
+     * @param message Raw payload of the message.
+     */
+    public void dispatchIncomingMessage(Player source, String channel, byte[] message);
+}

src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java

@@ -0,0 +1,16 @@
+package org.bukkit.plugin.messaging;
+
+/**
+ * Represents the different directions a plugin channel may go.
+ */
+public enum PluginChannelDirection {
+    /**
+     * The plugin channel is being sent to the server from a client.
+     */
+    INCOMING,
+
+    /**
+     * The plugin channel is being sent to a client from the server.
+     */
+    OUTGOING
+}

src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java

@@ -0,0 +1,19 @@
+package org.bukkit.plugin.messaging;
+
+import org.bukkit.entity.Player;
+
+/**
+ * A listener for a specific Plugin Channel, which will receive notifications of messages sent
+ * from a client.
+ */
+public interface PluginMessageListener {
+    /**
+     * A method that will be thrown when a {@link PluginMessageSource} sends a plugin
+     * message on a registered channel.
+     *
+     * @param channel Channel that the message was sent through.
+     * @param player Source of the message.
+     * @param message The raw message that was sent.
+     */
+    public void onPluginMessageReceived(String channel, Player player, byte[] message);
+}