twin/paper-mc
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-08-11 18:22:08 -07:00
Code Issues 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

9
paper-api/src/main/java/org/bukkit/plugin/IllegalPluginAccessException.java
View File

@@ -1,18 +1,21 @@
package org.bukkit.plugin;
/**
* Thrown when a plugin attempts to interact with the server when it is not enabled
* Thrown when a plugin attempts to interact with the server when it is not
* enabled
*/
@SuppressWarnings("serial")
public class IllegalPluginAccessException extends RuntimeException {
/**
* Creates a new instance of <code>IllegalPluginAccessException</code> without detail message.
* Creates a new instance of <code>IllegalPluginAccessException</code>
* without detail message.
*/
public IllegalPluginAccessException() {}
/**
* Constructs an instance of <code>IllegalPluginAccessException</code> with the specified detail message.
* Constructs an instance of <code>IllegalPluginAccessException</code>
* with the specified detail message.
*
* @param msg the detail message.
*/

6
paper-api/src/main/java/org/bukkit/plugin/InvalidDescriptionException.java
View File

@@ -7,7 +7,8 @@ public class InvalidDescriptionException extends Exception {
private static final long serialVersionUID = 5721389122281775896L;
/**
* Constructs a new InvalidDescriptionException based on the given Exception
* Constructs a new InvalidDescriptionException based on the given
* Exception
*
* @param message Brief message explaining the cause of the exception
* @param cause Exception that triggered this Exception
@@ -17,7 +18,8 @@ public class InvalidDescriptionException extends Exception {
}
/**
* Constructs a new InvalidDescriptionException based on the given Exception
* Constructs a new InvalidDescriptionException based on the given
* Exception
*
* @param cause Exception that triggered this Exception
*/

16
paper-api/src/main/java/org/bukkit/plugin/InvalidPluginException.java
View File

@@ -23,19 +23,25 @@ public class InvalidPluginException extends Exception {
}
/**
* Constructs a new InvalidPluginException with the specified detail message and cause.
* Constructs a new InvalidPluginException with the specified detail
* message and cause.
*
* @param message the detail message (which is saved for later retrieval by the getMessage() method).
* @param cause the cause (which is saved for later retrieval by the getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
* @param message the detail message (which is saved for later retrieval
* by the getMessage() method).
* @param cause the cause (which is saved for later retrieval by the
* getCause() method). (A null value is permitted, and indicates that
* the cause is nonexistent or unknown.)
*/
public InvalidPluginException(final String message, final Throwable cause) {
super(message, cause);
}
/**
* Constructs a new InvalidPluginException with the specified detail message
* Constructs a new InvalidPluginException with the specified detail
* message
*
* @param message TThe detail message is saved for later retrieval by the getMessage() method.
* @param message TThe detail message is saved for later retrieval by the
* getMessage() method.
*/
public InvalidPluginException(final String message) {
super(message);

52
paper-api/src/main/java/org/bukkit/plugin/Plugin.java
View File

@@ -33,10 +33,11 @@ public interface Plugin extends TabExecutor {
public PluginDescriptionFile getDescription();
/**
* Gets a {@link FileConfiguration} for this plugin, read through "config.yml"
* Gets a {@link FileConfiguration} for this plugin, read through
* "config.yml"
* <p>
* If there is a default config.yml embedded in this plugin, it will be provided
* as a default for this Configuration.
* If there is a default config.yml embedded in this plugin, it will be
* provided as a default for this Configuration.
*
* @return Plugin configuration
*/
@@ -56,20 +57,26 @@ public interface Plugin extends TabExecutor {
public void saveConfig();
/**
* Saves the raw contents of the default config.yml file to the location retrievable by {@link #getConfig()}.
* If there is no default config.yml embedded in the plugin, an empty config.yml file is saved.
* This should fail silently if the config.yml already exists.
* Saves the raw contents of the default config.yml file to the location
* retrievable by {@link #getConfig()}. If there is no default config.yml
* embedded in the plugin, an empty config.yml file is saved. This should
* fail silently if the config.yml already exists.
*/
public void saveDefaultConfig();
/**
* Saves the raw contents of any resource embedded with a plugin's .jar file assuming it can be found using
* {@link #getResource(String)}. The resource is saved into the plugin's data folder using the same hierarchy
* as the .jar file (subdirectories are preserved).
* Saves the raw contents of any resource embedded with a plugin's .jar
* file assuming it can be found using {@link #getResource(String)}.
* <p>
* The resource is saved into the plugin's data folder using the same
* hierarchy as the .jar file (subdirectories are preserved).
*
* @param resourcePath the embedded resource path to look for within the plugin's .jar file. (No preceding slash).
* @param replace if true, the embedded resource will overwrite the contents of an existing file.
* @throws IllegalArgumentException if the resource path is null, empty, or points to a nonexistent resource.
* @param resourcePath the embedded resource path to look for within the
* plugin's .jar file. (No preceding slash).
* @param replace if true, the embedded resource will overwrite the
* contents of an existing file.
* @throws IllegalArgumentException if the resource path is null, empty,
* or points to a nonexistent resource.
*/
public void saveResource(String resourcePath, boolean replace);
@@ -93,7 +100,8 @@ public interface Plugin extends TabExecutor {
public Server getServer();
/**
* Returns a value indicating whether or not this plugin is currently enabled
* Returns a value indicating whether or not this plugin is currently
* enabled
*
* @return true if this plugin is enabled, otherwise false
*/
@@ -106,7 +114,9 @@ public interface Plugin extends TabExecutor {
/**
* Called after a plugin is loaded but before it has been enabled.
* When mulitple plugins are loaded, the onLoad() for all plugins is called before any onEnable() is called.
* <p>
* When mulitple plugins are loaded, the onLoad() for all plugins is
* called before any onEnable() is called.
*/
public void onLoad();
@@ -148,17 +158,20 @@ public interface Plugin extends TabExecutor {
public EbeanServer getDatabase();
/**
* Gets a {@link ChunkGenerator} for use in a default world, as specified in the server configuration
* Gets a {@link ChunkGenerator} for use in a default world, as specified
* in the server configuration
*
* @param worldName Name of the world that this will be applied to
* @param id Unique ID, if any, that was specified to indicate which generator was requested
* @param id Unique ID, if any, that was specified to indicate which
* generator was requested
* @return ChunkGenerator for use in the default world generation
*/
public ChunkGenerator getDefaultWorldGenerator(String worldName, String id);
/**
* Returns the primary logger associated with this server instance. The returned logger automatically
* tags all log messages with the plugin's name.
* Returns the primary logger associated with this server instance. The
* returned logger automatically tags all log messages with the plugin's
* name.
*
* @return Logger associated with this server
*/
@@ -167,7 +180,8 @@ public interface Plugin extends TabExecutor {
/**
* Returns the name of the plugin.
* <p>
* This should return the bare name of the plugin and should be used for comparison.
* This should return the bare name of the plugin and should be used for
* comparison.
*
* @return name of the plugin
*/

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

@@ -3,7 +3,8 @@ package org.bukkit.plugin;
/**
* Represents a base {@link Plugin}
* <p>
* Extend this class if your plugin is not a {@link org.bukkit.plugin.java.JavaPlugin}
* Extend this class if your plugin is not a {@link
* org.bukkit.plugin.java.JavaPlugin}
*/
public abstract class PluginBase implements Plugin {
@Override

4
paper-api/src/main/java/org/bukkit/plugin/PluginLoadOrder.java
View File

@@ -4,12 +4,14 @@ package org.bukkit.plugin;
* Represents the order in which a plugin should be initialized and enabled
*/
public enum PluginLoadOrder {
/**
* Indicates that the plugin will be loaded at startup
*/
STARTUP,
/**
* Indicates that the plugin will be loaded after the first/default world was created
* Indicates that the plugin will be loaded after the first/default world
* was created
*/
POSTWORLD
}

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

@@ -19,9 +19,11 @@ public interface PluginLoader {
*
* @param file File to attempt to load
* @return Plugin that was contained in the specified file, or null if
* unsuccessful
* @throws InvalidPluginException Thrown when the specified file is not a plugin
* @throws UnknownDependencyException If a required dependency could not be found
* unsuccessful
* @throws InvalidPluginException Thrown when the specified file is not a
* plugin
* @throws UnknownDependencyException If a required dependency could not
* be found
*/
public Plugin loadPlugin(File file) throws InvalidPluginException, UnknownDependencyException;
@@ -29,8 +31,10 @@ public interface PluginLoader {
* Loads a PluginDescriptionFile from the specified file
*
* @param file File to attempt to load from
* @return A new PluginDescriptionFile loaded from the plugin.yml in the specified file
* @throws InvalidDescriptionException If the plugin description file could not be created
* @return A new PluginDescriptionFile loaded from the plugin.yml in the
* specified file
* @throws InvalidDescriptionException If the plugin description file
* could not be created
*/
public PluginDescriptionFile getPluginDescription(File file) throws InvalidDescriptionException;
@@ -42,7 +46,8 @@ public interface PluginLoader {
public Pattern[] getPluginFileFilters();
/**
* Creates and returns registered listeners for the event classes used in this listener
* Creates and returns registered listeners for the event classes used in
* this listener
*
* @param listener The object that will handle the eventual call back
* @param plugin The plugin to use when creating registered listeners
@@ -53,7 +58,8 @@ public interface PluginLoader {
/**
* Enables the specified plugin
* <p>
* Attempting to enable a plugin that is already enabled will have no effect
* Attempting to enable a plugin that is already enabled will have no
* effect
*
* @param plugin Plugin to enable
*/

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

@@ -5,8 +5,9 @@ import java.util.logging.LogRecord;
import java.util.logging.Logger;
/**
* The PluginLogger class is a modified {@link Logger} that prepends all logging calls with the name of the
* plugin doing the logging. The API for PluginLogger is exactly the same as {@link Logger}.
* The PluginLogger class is a modified {@link Logger} that prepends all
* logging calls with the name of the plugin doing the logging. The API for
* PluginLogger is exactly the same as {@link Logger}.
*
* @see Logger
*/

63
paper-api/src/main/java/org/bukkit/plugin/PluginManager.java
View File

@@ -18,7 +18,8 @@ public interface PluginManager {
* Registers the specified plugin loader
*
* @param loader Class name of the PluginLoader to register
* @throws IllegalArgumentException Thrown when the given Class is not a valid PluginLoader
* @throws IllegalArgumentException Thrown when the given Class is not a
* valid PluginLoader
*/
public void registerInterface(Class<? extends PluginLoader> loader) throws IllegalArgumentException;
@@ -64,9 +65,12 @@ public interface PluginManager {
*
* @param file File containing the plugin to load
* @return The Plugin loaded, or null if it was invalid
* @throws InvalidPluginException Thrown when the specified file is not a valid plugin
* @throws InvalidDescriptionException Thrown when the specified file contains an invalid description
* @throws UnknownDependencyException If a required dependency could not be resolved
* @throws InvalidPluginException Thrown when the specified file is not a
* valid plugin
* @throws InvalidDescriptionException Thrown when the specified file
* contains an invalid description
* @throws UnknownDependencyException If a required dependency could not
* be resolved
*/
public Plugin loadPlugin(File file) throws InvalidPluginException, InvalidDescriptionException, UnknownDependencyException;
@@ -92,9 +96,11 @@ public interface PluginManager {
* Calls an event with the given details
*
* @param event Event details
* @throws IllegalStateException Thrown when an asynchronous event is fired from synchronous code.<br>
* <i>Note: This is best-effort basis, and should not be used to test synchronized state. This
* is an indicator for flawed flow logic.</i>
* @throws IllegalStateException Thrown when an asynchronous event is
* fired from synchronous code.
* <p>
* <i>Note: This is best-effort basis, and should not be used to test
* synchronized state. This is an indicator for flawed flow logic.</i>
*/
public void callEvent(Event event) throws IllegalStateException;
@@ -132,7 +138,8 @@ public interface PluginManager {
/**
* Enables the specified plugin
* <p>
* Attempting to enable a plugin that is already enabled will have no effect
* Attempting to enable a plugin that is already enabled will have no
* effect
*
* @param plugin Plugin to enable
*/
@@ -158,20 +165,23 @@ public interface PluginManager {
/**
* Adds a {@link Permission} to this plugin manager.
* <p>
* If a permission is already defined with the given name of the new permission,
* an exception will be thrown.
* If a permission is already defined with the given name of the new
* permission, an exception will be thrown.
*
* @param perm Permission to add
* @throws IllegalArgumentException Thrown when a permission with the same name already exists
* @throws IllegalArgumentException Thrown when a permission with the same
* name already exists
*/
public void addPermission(Permission perm);
/**
* Removes a {@link Permission} registration from this plugin manager.
* <p>
* If the specified permission does not exist in this plugin manager, nothing will happen.
* If the specified permission does not exist in this plugin manager,
* nothing will happen.
* <p>
* Removing a permission registration will <b>not</b> remove the permission from any {@link Permissible}s that have it.
* Removing a permission registration will <b>not</b> remove the
* permission from any {@link Permissible}s that have it.
*
* @param perm Permission to remove
*/
@@ -180,9 +190,11 @@ public interface PluginManager {
/**
* Removes a {@link Permission} registration from this plugin manager.
* <p>
* If the specified permission does not exist in this plugin manager, nothing will happen.
* If the specified permission does not exist in this plugin manager,
* nothing will happen.
* <p>
* Removing a permission registration will <b>not</b> remove the permission from any {@link Permissible}s that have it.
* Removing a permission registration will <b>not</b> remove the
* permission from any {@link Permissible}s that have it.
*
* @param name Permission to remove
*/
@@ -199,16 +211,19 @@ public interface PluginManager {
/**
* Recalculates the defaults for the given {@link Permission}.
* <p>
* This will have no effect if the specified permission is not registered here.
* This will have no effect if the specified permission is not registered
* here.
*
* @param perm Permission to recalculate
*/
public void recalculatePermissionDefaults(Permission perm);
/**
* Subscribes the given Permissible for information about the requested Permission, by name.
* Subscribes the given Permissible for information about the requested
* Permission, by name.
* <p>
* If the specified Permission changes in any form, the Permissible will be asked to recalculate.
* If the specified Permission changes in any form, the Permissible will
* be asked to recalculate.
*
* @param permission Permission to subscribe to
* @param permissible Permissible subscribing
@@ -216,7 +231,8 @@ public interface PluginManager {
public void subscribeToPermission(String permission, Permissible permissible);
/**
* Unsubscribes the given Permissible for information about the requested Permission, by name.
* Unsubscribes the given Permissible for information about the requested
* Permission, by name.
*
* @param permission Permission to unsubscribe from
* @param permissible Permissible subscribing
@@ -224,7 +240,8 @@ public interface PluginManager {
public void unsubscribeFromPermission(String permission, Permissible permissible);
/**
* Gets a set containing all subscribed {@link Permissible}s to the given permission, by name
* Gets a set containing all subscribed {@link Permissible}s to the given
* permission, by name
*
* @param permission Permission to query for
* @return Set containing all subscribed permissions
@@ -234,7 +251,8 @@ public interface PluginManager {
/**
* Subscribes to the given Default permissions by operator status
* <p>
* If the specified defaults change in any form, the Permissible will be asked to recalculate.
* If the specified defaults change in any form, the Permissible will be
* asked to recalculate.
*
* @param op Default list to subscribe to
* @param permissible Permissible subscribing
@@ -250,7 +268,8 @@ public interface PluginManager {
public void unsubscribeFromDefaultPerms(boolean op, Permissible permissible);
/**
* Gets a set containing all subscribed {@link Permissible}s to the given default list, by op status
* Gets a set containing all subscribed {@link Permissible}s to the given
* default list, by op status
*
* @param op Default list to query for
* @return Set containing all subscribed permissions

4
paper-api/src/main/java/org/bukkit/plugin/ServicesManager.java
View File

@@ -4,8 +4,8 @@ import java.util.Collection;
import java.util.List;
/**
* Manages services and service providers. Services are an interface specifying
* a list of methods that a provider must implement. Providers are
* Manages services and service providers. Services are an interface
* specifying a list of methods that a provider must implement. Providers are
* implementations of these services. A provider can be queried from the
* services manager in order to use a service (if one is available). If
* multiple plugins register a service, then the service with the highest

18
paper-api/src/main/java/org/bukkit/plugin/SimplePluginManager.java
View File

@@ -62,7 +62,8 @@ public final class SimplePluginManager implements PluginManager {
* Registers the specified plugin loader
*
* @param loader Class name of the PluginLoader to register
* @throws IllegalArgumentException Thrown when the given Class is not a valid PluginLoader
* @throws IllegalArgumentException Thrown when the given Class is not a
* valid PluginLoader
*/
public void registerInterface(Class<? extends PluginLoader> loader) throws IllegalArgumentException {
PluginLoader instance;
@@ -284,8 +285,10 @@ public final class SimplePluginManager implements PluginManager {
*
* @param file File containing the plugin to load
* @return The Plugin loaded, or null if it was invalid
* @throws InvalidPluginException Thrown when the specified file is not a valid plugin
* @throws UnknownDependencyException If a required dependency could not be found
* @throws InvalidPluginException Thrown when the specified file is not a
* valid plugin
* @throws UnknownDependencyException If a required dependency could not
* be found
*/
public synchronized Plugin loadPlugin(File file) throws InvalidPluginException, UnknownDependencyException {
Validate.notNull(file, "File cannot be null");
@@ -443,7 +446,8 @@ public final class SimplePluginManager implements PluginManager {
}
/**
* Calls an event with the given details.<br>
* Calls an event with the given details.
* <p>
* This method only synchronizes when the event is not asynchronous.
*
* @param event Event details
@@ -510,14 +514,16 @@ public final class SimplePluginManager implements PluginManager {
}
/**
* Registers the given event to the specified listener using a directly passed EventExecutor
* Registers the given event to the specified listener using a directly
* passed EventExecutor
*
* @param event Event class to register
* @param listener PlayerListener to register
* @param priority Priority of this event
* @param executor EventExecutor to register
* @param plugin Plugin to register
* @param ignoreCancelled Do not call executor if event was already cancelled
* @param ignoreCancelled Do not call executor if event was already
* cancelled
*/
public void registerEvent(Class<? extends Event> event, Listener listener, EventPriority priority, EventExecutor executor, Plugin plugin, boolean ignoreCancelled) {
Validate.notNull(listener, "Listener cannot be null");

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

@@ -75,8 +75,7 @@ public class TimedRegisteredListener extends RegisteredListener {
* multiple classes of event, the closest shared superclass will be
* returned, such that for any event this listener has handled,
* <code>this.getEventClass().isAssignableFrom(event.getClass())</code>
* and no class
* <code>this.getEventClass().isAssignableFrom(clazz)
* and no class <code>this.getEventClass().isAssignableFrom(clazz)
* && this.getEventClass() != clazz &&
* event.getClass().isAssignableFrom(clazz)</code> for all handled events.
*

6
paper-api/src/main/java/org/bukkit/plugin/UnknownDependencyException.java
View File

@@ -8,7 +8,8 @@ public class UnknownDependencyException extends RuntimeException {
private static final long serialVersionUID = 5721389371901775895L;
/**
* Constructs a new UnknownDependencyException based on the given Exception
* Constructs a new UnknownDependencyException based on the given
* Exception
*
* @param throwable Exception that triggered this Exception
*/
@@ -26,7 +27,8 @@ public class UnknownDependencyException extends RuntimeException {
}
/**
* Constructs a new UnknownDependencyException based on the given Exception
* Constructs a new UnknownDependencyException based on the given
* Exception
*
* @param message Brief message explaining the cause of the exception
* @param throwable Exception that triggered this Exception

6
paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
View File

@@ -80,7 +80,8 @@ public abstract class JavaPlugin extends PluginBase {
}
/**
* Returns a value indicating whether or not this plugin is currently enabled
* Returns a value indicating whether or not this plugin is currently
* enabled
*
* @return true if this plugin is enabled, otherwise false
*/
@@ -228,7 +229,8 @@ public abstract class JavaPlugin extends PluginBase {
*
* @param loader PluginLoader that is responsible for this plugin
* @param server Server instance that is running this plugin
* @param description PluginDescriptionFile containing metadata on this plugin
* @param description PluginDescriptionFile containing metadata on this
* plugin
* @param dataFolder Folder containing the plugin's data
* @param file File containing this plugin
* @param classLoader ClassLoader which holds this plugin

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) {