Permalink
Browse files

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

  • Loading branch information...
Dinnerbone committed Jan 13, 2012
1 parent b96b349 commit 55cc8722c8260939f5f0ea57385e4edd8b70ed0c
@@ -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 ConsoleCommandSender getConsoleSender() {
public static File getWorldContainer() {
return server.getWorldContainer();
}
public static Messenger getMessenger() {
return server.getMessenger();
}
}
@@ -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 @@
* @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();
}
@@ -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
@@ -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.
*
@@ -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
@@ -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 + ".");
}
}
@@ -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 + "'.");
}
}
@@ -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);
}
}
@@ -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);
}
@@ -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
}
@@ -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);
}
Oops, something went wrong.

1 comment on commit 55cc872

@Fishrock123

This comment has been minimized.

Show comment
Hide comment
@Fishrock123

Fishrock123 Jan 13, 2012

So, is there any way to actually use this yet, or do we need to wait for the client API?

Fishrock123 commented on 55cc872 Jan 13, 2012

So, is there any way to actually use this yet, or do we need to wait for the client API?

Please sign in to comment.