From ba835793ed2b2305512d008735a8cb7c09ec0693 Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Sat, 1 Jul 2023 13:55:59 +1000 Subject: [PATCH] SPIGOT-6455, SPIGOT-7030, #750: Improve ban API By: Doc --- .../src/main/java/org/bukkit/BanEntry.java | 23 +++++- .../src/main/java/org/bukkit/BanList.java | 74 +++++++++++++++++-- .../src/main/java/org/bukkit/Bukkit.java | 32 +++++++- .../main/java/org/bukkit/OfflinePlayer.java | 18 ++++- .../src/main/java/org/bukkit/Server.java | 28 ++++++- .../main/java/org/bukkit/ban/IpBanList.java | 11 +++ .../java/org/bukkit/ban/ProfileBanList.java | 30 ++++++++ .../java/org/bukkit/ban/package-info.java | 4 + .../main/java/org/bukkit/entity/Player.java | 37 ++++++++++ 9 files changed, 238 insertions(+), 19 deletions(-) create mode 100644 paper-api/src/main/java/org/bukkit/ban/IpBanList.java create mode 100644 paper-api/src/main/java/org/bukkit/ban/ProfileBanList.java create mode 100644 paper-api/src/main/java/org/bukkit/ban/package-info.java diff --git a/paper-api/src/main/java/org/bukkit/BanEntry.java b/paper-api/src/main/java/org/bukkit/BanEntry.java index 2cf11ca4f6..fc4da11c9d 100644 --- a/paper-api/src/main/java/org/bukkit/BanEntry.java +++ b/paper-api/src/main/java/org/bukkit/BanEntry.java @@ -15,8 +15,8 @@ import org.jetbrains.annotations.Nullable; * Property * Description * - * Target Name / IP Address - * The target name or IP address + * Target Profile / IP Address + * The target profile or IP address * * Creation Date * The creation date of the ban @@ -40,18 +40,30 @@ import org.jetbrains.annotations.Nullable; *

* Likewise, changes to the associated {@link BanList} or other entries may or * may not be reflected in this entry. + * + * @param The ban target */ -public interface BanEntry { +public interface BanEntry { /** * Gets the target involved. This may be in the form of an IP or a player * name. * * @return the target name or IP address + * @deprecated See {@link #getBanTarget()} */ + @Deprecated @NotNull public String getTarget(); + /** + * Gets the target involved. + * + * @return the target profile or IP address + */ + @NotNull + public T getBanTarget(); + /** * Gets the date this ban entry was created. * @@ -132,4 +144,9 @@ public interface BanEntry { * banned once again. */ public void save(); + + /** + * Removes this ban entry from the appropriate ban list. + */ + public void remove(); } diff --git a/paper-api/src/main/java/org/bukkit/BanList.java b/paper-api/src/main/java/org/bukkit/BanList.java index 96ef22fe87..87f4925235 100644 --- a/paper-api/src/main/java/org/bukkit/BanList.java +++ b/paper-api/src/main/java/org/bukkit/BanList.java @@ -7,8 +7,10 @@ import org.jetbrains.annotations.Nullable; /** * A ban list, containing bans of some {@link Type}. + * + * @param The ban target */ -public interface BanList { +public interface BanList { /** * Represents a ban-type that a {@link BanList} may track. @@ -16,12 +18,19 @@ public interface BanList { public enum Type { /** * Banned player names + * + * @deprecated deprecated in favor of {@link #PROFILE} */ + @Deprecated NAME, /** - * Banned player IP addresses + * Banned IP addresses */ IP, + /** + * Banned player profiles + */ + PROFILE, ; } @@ -30,12 +39,40 @@ public interface BanList { * * @param target entry parameter to search for * @return the corresponding entry, or null if none found + * @deprecated see {@link #getBanEntry(Object)} */ + @Deprecated @Nullable - public BanEntry getBanEntry(@NotNull String target); + public BanEntry getBanEntry(@NotNull String target); /** - * Adds a ban to the this list. If a previous ban exists, this will + * Gets a {@link BanEntry} by target. + * + * @param target entry parameter to search for + * @return the corresponding entry, or null if none found + */ + @Nullable + public BanEntry getBanEntry(@NotNull T target); + + /** + * Adds a ban to this list. If a previous ban exists, this will + * update the previous entry. + * + * @param target the target of the ban + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + * @deprecated see {@link #addBan(Object, String, Date, String)} + */ + @Deprecated + @Nullable + public BanEntry addBan(@NotNull String target, @Nullable String reason, @Nullable Date expires, @Nullable String source); + + /** + * Adds a ban to this list. If a previous ban exists, this will * update the previous entry. * * @param target the target of the ban @@ -47,7 +84,7 @@ public interface BanList { * (updated) previous ban */ @Nullable - public BanEntry addBan(@NotNull String target, @Nullable String reason, @Nullable Date expires, @Nullable String source); + public BanEntry addBan(@NotNull T target, @Nullable String reason, @Nullable Date expires, @Nullable String source); /** * Gets a set containing every {@link BanEntry} in this list. @@ -55,16 +92,28 @@ public interface BanList { * @return an immutable set containing every entry tracked by this list */ @NotNull - public Set getBanEntries(); + public Set> getBanEntries(); /** * Gets if a {@link BanEntry} exists for the target, indicating an active * ban status. * * @param target the target to find - * @return true if a {@link BanEntry} exists for the name, indicating an + * @return true if a {@link BanEntry} exists for the target, indicating an * active ban status, false otherwise */ + public boolean isBanned(@NotNull T target); + + /** + * Gets if a {@link BanEntry} exists for the target, indicating an active + * ban status. + * + * @param target the target to find + * @return true if a {@link BanEntry} exists for the target, indicating an + * active ban status, false otherwise + * @deprecated see {@link #isBanned(Object)} + */ + @Deprecated public boolean isBanned(@NotNull String target); /** @@ -73,5 +122,16 @@ public interface BanList { * * @param target the target to remove from this list */ + public void pardon(@NotNull T target); + + /** + * Removes the specified target from this list, therefore indicating a + * "not banned" status. + * + * @param target the target to remove from this list + * + * @deprecated see {@link #pardon(Object)} + */ + @Deprecated public void pardon(@NotNull String target); } diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index e395a8299c..3ee2874c7d 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/paper-api/src/main/java/org/bukkit/Bukkit.java @@ -4,6 +4,7 @@ import com.google.common.collect.ImmutableList; import java.awt.image.BufferedImage; import java.io.File; import java.io.Serializable; +import java.net.InetSocketAddress; import java.util.Collection; import java.util.Collections; import java.util.Iterator; @@ -1206,7 +1207,10 @@ public final class Bukkit { * Bans the specified address from the server. * * @param address the IP address to ban + * + * @deprecated see {@link #banIP(InetSocketAddress)} */ + @Deprecated public static void banIP(@NotNull String address) { server.banIP(address); } @@ -1215,11 +1219,32 @@ public final class Bukkit { * Unbans the specified address from the server. * * @param address the IP address to unban + * + * @deprecated see {@link #unbanIP(InetSocketAddress)} */ + @Deprecated public static void unbanIP(@NotNull String address) { server.unbanIP(address); } + /** + * Bans the specified address from the server. + * + * @param address the IP address to ban + */ + public static void banIP(@NotNull InetSocketAddress address) { + server.banIP(address); + } + + /** + * Unbans the specified address from the server. + * + * @param address the IP address to unban + */ + public static void unbanIP(@NotNull InetSocketAddress address) { + server.unbanIP(address); + } + /** * Gets a set containing all banned players. * @@ -1232,15 +1257,14 @@ public final class Bukkit { /** * Gets a ban list for the supplied type. - *

- * Bans by name are no longer supported and this method will return - * null when trying to request them. The replacement is bans by UUID. * * @param type the type of list to fetch, cannot be null + * @param The ban target + * * @return a ban list of the specified type */ @NotNull - public static BanList getBanList(@NotNull BanList.Type type) { + public static > T getBanList(@NotNull BanList.Type type) { return server.getBanList(type); } diff --git a/paper-api/src/main/java/org/bukkit/OfflinePlayer.java b/paper-api/src/main/java/org/bukkit/OfflinePlayer.java index 5acb0d36a0..f000d706bd 100644 --- a/paper-api/src/main/java/org/bukkit/OfflinePlayer.java +++ b/paper-api/src/main/java/org/bukkit/OfflinePlayer.java @@ -1,6 +1,8 @@ package org.bukkit; +import java.util.Date; import java.util.UUID; +import org.bukkit.ban.ProfileBanList; import org.bukkit.configuration.serialization.ConfigurationSerializable; import org.bukkit.entity.AnimalTamer; import org.bukkit.entity.EntityType; @@ -58,12 +60,26 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio PlayerProfile getPlayerProfile(); /** - * Checks if this player is banned or not + * Checks if this player has had their profile banned. * * @return true if banned, otherwise false */ public boolean isBanned(); + /** + * Adds this user to the {@link ProfileBanList}. If a previous ban exists, this will + * update the entry. + * + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + */ + @Nullable + public BanEntry ban(@Nullable String reason, @Nullable Date expires, @Nullable String source); + /** * Checks if this player is whitelisted or not * diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index 62969fbc55..32528060b9 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/paper-api/src/main/java/org/bukkit/Server.java @@ -4,6 +4,7 @@ import com.google.common.collect.ImmutableList; import java.awt.image.BufferedImage; import java.io.File; import java.io.Serializable; +import java.net.InetSocketAddress; import java.util.Collection; import java.util.Collections; import java.util.Iterator; @@ -1026,16 +1027,36 @@ public interface Server extends PluginMessageRecipient { * Bans the specified address from the server. * * @param address the IP address to ban + * + * @deprecated see {@link #banIP(InetSocketAddress)} */ + @Deprecated public void banIP(@NotNull String address); /** * Unbans the specified address from the server. * * @param address the IP address to unban + * + * @deprecated see {@link #unbanIP(InetSocketAddress)} */ + @Deprecated public void unbanIP(@NotNull String address); + /** + * Bans the specified address from the server. + * + * @param address the IP address to ban + */ + public void banIP(@NotNull InetSocketAddress address); + + /** + * Unbans the specified address from the server. + * + * @param address the IP address to unban + */ + public void unbanIP(@NotNull InetSocketAddress address); + /** * Gets a set containing all banned players. * @@ -1046,15 +1067,14 @@ public interface Server extends PluginMessageRecipient { /** * Gets a ban list for the supplied type. - *

- * Bans by name are no longer supported and this method will return - * null when trying to request them. The replacement is bans by UUID. * * @param type the type of list to fetch, cannot be null + * @param The ban target + * * @return a ban list of the specified type */ @NotNull - public BanList getBanList(@NotNull BanList.Type type); + public > T getBanList(@NotNull BanList.Type type); /** * Gets a set containing all player operators. diff --git a/paper-api/src/main/java/org/bukkit/ban/IpBanList.java b/paper-api/src/main/java/org/bukkit/ban/IpBanList.java new file mode 100644 index 0000000000..b17bba82ff --- /dev/null +++ b/paper-api/src/main/java/org/bukkit/ban/IpBanList.java @@ -0,0 +1,11 @@ +package org.bukkit.ban; + +import java.net.InetSocketAddress; +import org.bukkit.BanList; + +/** + * A {@link BanList} targeting IP bans. + */ +public interface IpBanList extends BanList { + +} diff --git a/paper-api/src/main/java/org/bukkit/ban/ProfileBanList.java b/paper-api/src/main/java/org/bukkit/ban/ProfileBanList.java new file mode 100644 index 0000000000..e805e629ce --- /dev/null +++ b/paper-api/src/main/java/org/bukkit/ban/ProfileBanList.java @@ -0,0 +1,30 @@ +package org.bukkit.ban; + +import java.util.Date; +import org.bukkit.BanEntry; +import org.bukkit.BanList; +import org.bukkit.profile.PlayerProfile; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * A {@link BanList} targeting player profile bans. + */ +public interface ProfileBanList extends BanList { + + /** + * {@inheritDoc} + * + * @param target the target of the ban + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + * @throws IllegalArgumentException if ProfilePlayer has an invalid UUID + */ + @Nullable + public BanEntry addBan(@NotNull PlayerProfile target, @Nullable String reason, @Nullable Date expires, @Nullable String source); + +} diff --git a/paper-api/src/main/java/org/bukkit/ban/package-info.java b/paper-api/src/main/java/org/bukkit/ban/package-info.java new file mode 100644 index 0000000000..946b72ad7e --- /dev/null +++ b/paper-api/src/main/java/org/bukkit/ban/package-info.java @@ -0,0 +1,4 @@ +/** + * Classes relevant to bans. + */ +package org.bukkit.ban; diff --git a/paper-api/src/main/java/org/bukkit/entity/Player.java b/paper-api/src/main/java/org/bukkit/entity/Player.java index 1c5c88fdba..b41503ab1d 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Player.java +++ b/paper-api/src/main/java/org/bukkit/entity/Player.java @@ -2,7 +2,9 @@ package org.bukkit.entity; import java.net.InetSocketAddress; import java.util.Collection; +import java.util.Date; import java.util.Map; +import org.bukkit.BanEntry; import org.bukkit.DyeColor; import org.bukkit.Effect; import org.bukkit.GameMode; @@ -19,6 +21,8 @@ import org.bukkit.WeatherType; import org.bukkit.WorldBorder; import org.bukkit.advancement.Advancement; import org.bukkit.advancement.AdvancementProgress; +import org.bukkit.ban.IpBanList; +import org.bukkit.ban.ProfileBanList; import org.bukkit.block.Block; import org.bukkit.block.BlockState; import org.bukkit.block.Sign; @@ -35,6 +39,7 @@ import org.bukkit.inventory.ItemStack; import org.bukkit.map.MapView; import org.bukkit.plugin.Plugin; import org.bukkit.plugin.messaging.PluginMessageRecipient; +import org.bukkit.profile.PlayerProfile; import org.bukkit.scoreboard.Scoreboard; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.NotNull; @@ -169,6 +174,38 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM */ public void kickPlayer(@Nullable String message); + /** + * Adds this user to the {@link ProfileBanList}. If a previous ban exists, this will + * update the entry. + * + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @param kickPlayer if the player need to be kick + * + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + */ + @Nullable + public BanEntry ban(@Nullable String reason, @Nullable Date expires, @Nullable String source, boolean kickPlayer); + + /** + * Adds this user's current IP address to the {@link IpBanList}. If a previous ban exists, this will + * update the entry. If {@link #getAddress()} is null this method will throw an exception. + * + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @param kickPlayer if the player need to be kick + * + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + */ + @Nullable + public BanEntry banIp(@Nullable String reason, @Nullable Date expires, @Nullable String source, boolean kickPlayer); + /** * Says a message (or runs a command). *