From 87ffb1ac2f3fd47708c9aba7e232f699a2891df8 Mon Sep 17 00:00:00 2001 From: Andrew Steinborn Date: Fri, 24 Aug 2018 21:50:56 -0400 Subject: [PATCH] Add even more Javadoc. --- .../api/proxy/ServerConnection.java | 8 ++++++++ .../api/proxy/messages/ChannelMessageSink.java | 8 ++++++++ .../proxy/messages/ChannelMessageSource.java | 3 +++ .../api/proxy/messages/ChannelRegistrar.java | 9 +++++++++ .../api/proxy/messages/ChannelSide.java | 9 +++++++++ .../api/proxy/messages/MessageHandler.java | 18 ++++++++++++++++++ .../messages/MinecraftChannelIdentifier.java | 12 ++++++++++++ .../api/scheduler/ScheduledTask.java | 12 ++++++++++++ .../api/scheduler/TaskStatus.java | 9 +++++++++ .../velocitypowered/api/util/GameProfile.java | 15 +++++++++------ 10 files changed, 97 insertions(+), 6 deletions(-) diff --git a/api/src/main/java/com/velocitypowered/api/proxy/ServerConnection.java b/api/src/main/java/com/velocitypowered/api/proxy/ServerConnection.java index 080930c89..5fb44a44a 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/ServerConnection.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/ServerConnection.java @@ -8,7 +8,15 @@ import com.velocitypowered.api.server.ServerInfo; * Represents a connection to a backend server from the proxy for a client. */ public interface ServerConnection extends ChannelMessageSource, ChannelMessageSink { + /** + * Returns the server that this connection is connected to. + * @return the server this connection is connected to + */ ServerInfo getServerInfo(); + /** + * Returns the player that this connection is associated with. + * @return the player for this connection + */ Player getPlayer(); } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSink.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSink.java index d813c4edc..57ebe4ea6 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSink.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSink.java @@ -1,5 +1,13 @@ package com.velocitypowered.api.proxy.messages; +/** + * Represents something that can send plugin messages. + */ public interface ChannelMessageSink { + /** + * Sends a plugin message to this target. + * @param identifier the channel identifier to send the message on + * @param data the data to send + */ void sendPluginMessage(ChannelIdentifier identifier, byte[] data); } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSource.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSource.java index 1aaeae943..8cb85ef1c 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSource.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelMessageSource.java @@ -1,4 +1,7 @@ package com.velocitypowered.api.proxy.messages; +/** + * A marker interface that indicates a source of plugin messages. + */ public interface ChannelMessageSource { } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelRegistrar.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelRegistrar.java index 412e172df..2d77988b5 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelRegistrar.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelRegistrar.java @@ -5,7 +5,16 @@ package com.velocitypowered.api.proxy.messages; * the client or the server. */ public interface ChannelRegistrar { + /** + * Registers the specified message handler to listen for plugin messages on the specified channels. + * @param handler the handler to register + * @param identifiers the channel identifiers to register + */ void register(MessageHandler handler, ChannelIdentifier... identifiers); + /** + * Unregisters the handler for the specified channel. + * @param identifiers the identifiers to unregister + */ void unregister(ChannelIdentifier... identifiers); } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelSide.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelSide.java index f27faf71b..12256f432 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelSide.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/ChannelSide.java @@ -1,6 +1,15 @@ package com.velocitypowered.api.proxy.messages; +/** + * Represents from "which side" of the proxy the plugin message came from. + */ public enum ChannelSide { + /** + * The plugin message came from a server that a client was connected to. + */ FROM_SERVER, + /** + * The plugin message came from the client. + */ FROM_CLIENT } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/MessageHandler.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/MessageHandler.java index 52f4b4e1a..70a7e5fa7 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/MessageHandler.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/MessageHandler.java @@ -1,10 +1,28 @@ package com.velocitypowered.api.proxy.messages; +/** + * Represents a handler for handling plugin messages. + */ public interface MessageHandler { + /** + * Handles an incoming plugin message. + * @param source the source of the plugin message + * @param side from where the plugin message originated + * @param identifier the channel on which the message was sent + * @param data the data inside the plugin message + * @return a {@link ForwardStatus} indicating whether or not to forward this plugin message on + */ ForwardStatus handle(ChannelMessageSource source, ChannelSide side, ChannelIdentifier identifier, byte[] data); enum ForwardStatus { + /** + * Forwards this plugin message on to the client or server, depending on the {@link ChannelSide} it originated + * from. + */ FORWARD, + /** + * Discard the plugin message and do not forward it on. + */ HANDLED } } diff --git a/api/src/main/java/com/velocitypowered/api/proxy/messages/MinecraftChannelIdentifier.java b/api/src/main/java/com/velocitypowered/api/proxy/messages/MinecraftChannelIdentifier.java index c171fee66..1355ed239 100644 --- a/api/src/main/java/com/velocitypowered/api/proxy/messages/MinecraftChannelIdentifier.java +++ b/api/src/main/java/com/velocitypowered/api/proxy/messages/MinecraftChannelIdentifier.java @@ -20,10 +20,22 @@ public final class MinecraftChannelIdentifier implements ChannelIdentifier { this.name = name; } + /** + * Creates an identifier in the default namespace ({@code minecraft}). Plugins are strongly encouraged to provide + * their own namespace. + * @param name the name in the default namespace to use + * @return a new channel identifier + */ public static MinecraftChannelIdentifier forDefaultNamespace(String name) { return new MinecraftChannelIdentifier("minecraft", name); } + /** + * Creates an identifier in the specified namespace. + * @param namespace the namespace to use + * @param name the channel name inside the specified namespace + * @return a new channel identifier + */ public static MinecraftChannelIdentifier create(String namespace, String name) { Preconditions.checkArgument(!Strings.isNullOrEmpty(namespace), "namespace is null or empty"); Preconditions.checkArgument(!Strings.isNullOrEmpty(name), "namespace is null or empty"); diff --git a/api/src/main/java/com/velocitypowered/api/scheduler/ScheduledTask.java b/api/src/main/java/com/velocitypowered/api/scheduler/ScheduledTask.java index 58596c684..2ee41380f 100644 --- a/api/src/main/java/com/velocitypowered/api/scheduler/ScheduledTask.java +++ b/api/src/main/java/com/velocitypowered/api/scheduler/ScheduledTask.java @@ -4,9 +4,21 @@ package com.velocitypowered.api.scheduler; * Represents a task that is scheduled to run on the proxy. */ public interface ScheduledTask { + /** + * Returns the plugin that scheduled this task. + * @return the plugin that scheduled this task + */ Object plugin(); + /** + * Returns the current status of this task. + * @return the current status of this task + */ TaskStatus status(); + /** + * Cancels this task. If the task is already running, the thread in which it is running will be interrupted. + * If the task is not currently running, Velocity will terminate it safely. + */ void cancel(); } diff --git a/api/src/main/java/com/velocitypowered/api/scheduler/TaskStatus.java b/api/src/main/java/com/velocitypowered/api/scheduler/TaskStatus.java index b5830fa51..e86f56e12 100644 --- a/api/src/main/java/com/velocitypowered/api/scheduler/TaskStatus.java +++ b/api/src/main/java/com/velocitypowered/api/scheduler/TaskStatus.java @@ -1,7 +1,16 @@ package com.velocitypowered.api.scheduler; public enum TaskStatus { + /** + * The task is scheduled and is currently running. + */ SCHEDULED, + /** + * The task was cancelled with {@link ScheduledTask#cancel()}. + */ CANCELLED, + /** + * The task has run to completion. This is applicable only for tasks without a repeat. + */ FINISHED } diff --git a/api/src/main/java/com/velocitypowered/api/util/GameProfile.java b/api/src/main/java/com/velocitypowered/api/util/GameProfile.java index f77b991f3..237939ef1 100644 --- a/api/src/main/java/com/velocitypowered/api/util/GameProfile.java +++ b/api/src/main/java/com/velocitypowered/api/util/GameProfile.java @@ -7,14 +7,17 @@ import org.checkerframework.checker.nullness.qual.NonNull; import java.util.List; import java.util.UUID; +/** + * Represents a Mojang game profile. + */ public class GameProfile { private final String id; private final String name; private final List properties; public GameProfile(@NonNull String id, @NonNull String name, @NonNull List properties) { - this.id = id; - this.name = name; + this.id = Preconditions.checkNotNull(id, "id"); + this.name = Preconditions.checkNotNull(name, "name"); this.properties = ImmutableList.copyOf(properties); } @@ -31,7 +34,7 @@ public class GameProfile { } public List getProperties() { - return ImmutableList.copyOf(properties); + return properties; } public static GameProfile forOfflinePlayer(@NonNull String username) { @@ -55,9 +58,9 @@ public class GameProfile { private final String signature; public Property(@NonNull String name, @NonNull String value, @NonNull String signature) { - this.name = name; - this.value = value; - this.signature = signature; + this.name = Preconditions.checkNotNull(name, "name"); + this.value = Preconditions.checkNotNull(value, "value"); + this.signature = Preconditions.checkNotNull(signature, "signature"); } public String getName() {