SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
paper-api/src/main/java/org/bukkit/plugin/messaging/Messenger.java
View File

@@ -5,10 +5,11 @@ import org.bukkit.entity.Player;
import org.bukkit.plugin.Plugin;
/**
* A class responsible for managing the registrations of plugin channels and their
* listeners.
* 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.
*/
@@ -29,8 +30,8 @@ public interface Messenger {
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.
* 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.
@@ -39,18 +40,20 @@ public interface Messenger {
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.
* 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 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.
* 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.
@@ -58,31 +61,36 @@ public interface Messenger {
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.
* 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.
* @return 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.
* @return 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.
* 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.
* @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.
* 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.
@@ -91,7 +99,8 @@ public interface Messenger {
public void unregisterIncomingPluginChannel(Plugin plugin, String channel);
/**
* Unregisters the specific plugin from listening on all plugin channels through all listeners.
* 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.
@@ -106,10 +115,12 @@ public interface Messenger {
public Set<String> getOutgoingChannels();
/**
* Gets a set containing all the outgoing plugin channels that the specified plugin is registered to.
* 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.
* @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);
@@ -122,16 +133,19 @@ public interface Messenger {
public Set<String> getIncomingChannels();
/**
* Gets a set containing all the incoming plugin channels that the specified plugin is registered for.
* 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.
* @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.
* 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.
@@ -140,7 +154,8 @@ public interface Messenger {
public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin);
/**
* Gets a set containing all the incoming plugin channel registrations that are on the requested channel.
* 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.
@@ -149,8 +164,8 @@ public interface Messenger {
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.
* 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.
@@ -162,8 +177,8 @@ public interface Messenger {
/**
* 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.
* 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.
@@ -171,8 +186,8 @@ public interface Messenger {
public boolean isRegistrationValid(PluginMessageListenerRegistration registration);
/**
* Checks if the specified plugin has registered to receive incoming messages through the requested
* channel.
* 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.
@@ -181,8 +196,8 @@ public interface Messenger {
public boolean isIncomingChannelRegistered(Plugin plugin, String channel);
/**
* Checks if the specified plugin has registered to send outgoing messages through the requested
* 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.

1
paper-api/src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java
View File

@@ -4,6 +4,7 @@ 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.
*/

5
paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java
View File

@@ -3,10 +3,11 @@ 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.
* 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 PluginMessageSource sends a plugin
* message on a registered channel.

3
paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageListenerRegistration.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.plugin.messaging;
import org.bukkit.plugin.Plugin;
/**
* Contains information about a {@link Plugin}s registration to a plugin channel.
* Contains information about a {@link Plugin}s registration to a plugin
* channel.
*/
public final class PluginMessageListenerRegistration {
private final Messenger messenger;

20
paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
View File

@@ -8,23 +8,29 @@ import org.bukkit.plugin.Plugin;
*/
public interface PluginMessageRecipient {
/**
* Sends this recipient a Plugin Message on the specified outgoing channel.
* Sends this recipient a Plugin Message on the specified outgoing
* channel.
* <p>
* The message may not be larger than {@link Messenger#MAX_MESSAGE_SIZE} bytes, and the plugin must be registered to send
* messages on the specified channel.
* The message may not be larger than {@link Messenger#MAX_MESSAGE_SIZE}
* bytes, and the plugin must be registered to send messages on the
* specified channel.
*
* @param source The plugin that sent this message.
* @param channel The channel to send this message on.
* @param message The raw message to send.
* @throws IllegalArgumentException Thrown if the source plugin is disabled.
* @throws IllegalArgumentException Thrown if source, channel or message is null.
* @throws IllegalArgumentException Thrown if the source plugin is
* disabled.
* @throws IllegalArgumentException Thrown if source, channel or message
* is null.
* @throws MessageTooLargeException Thrown if the message is too big.
* @throws ChannelNotRegisteredException Thrown if the channel is not registered for this plugin.
* @throws ChannelNotRegisteredException Thrown if the channel is not
* registered for this plugin.
*/
public void sendPluginMessage(Plugin source, String channel, byte[] message);
/**
* Gets a set containing all the Plugin Channels that this client is listening on.
* Gets a set containing all the Plugin Channels that this client is
* listening on.
*
* @return Set containing all the channels that this client may accept.
*/

3
paper-api/src/main/java/org/bukkit/plugin/messaging/ReservedChannelException.java
View File

@@ -1,7 +1,8 @@
package org.bukkit.plugin.messaging;
/**
* Thrown if a plugin attempts to register for a reserved channel (such as "REGISTER")
* Thrown if a plugin attempts to register for a reserved channel (such as
* "REGISTER")
*/
@SuppressWarnings("serial")
public class ReservedChannelException extends RuntimeException {

15
paper-api/src/main/java/org/bukkit/plugin/messaging/StandardMessenger.java
View File

@@ -440,17 +440,22 @@ public class StandardMessenger implements Messenger {
}
/**
* Validates the input of a Plugin Message, ensuring the arguments are all valid.
* Validates the input of a Plugin Message, ensuring the arguments are all
* valid.
*
* @param messenger Messenger to use for validation.
* @param source Source plugin of the Message.
* @param channel Plugin Channel to send the message by.
* @param message Raw message payload to send.
* @throws IllegalArgumentException Thrown if the source plugin is disabled.
* @throws IllegalArgumentException Thrown if source, channel or message is null.
* @throws IllegalArgumentException Thrown if the source plugin is
* disabled.
* @throws IllegalArgumentException Thrown if source, channel or message
* is null.
* @throws MessageTooLargeException Thrown if the message is too big.
* @throws ChannelNameTooLongException Thrown if the channel name is too long.
* @throws ChannelNotRegisteredException Thrown if the channel is not registered for this plugin.
* @throws ChannelNameTooLongException Thrown if the channel name is too
* long.
* @throws ChannelNotRegisteredException Thrown if the channel is not
* registered for this plugin.
*/
public static void validatePluginMessage(Messenger messenger, Plugin source, String channel, byte[] message) {
if (messenger == null) {