SPIGOT-6455, SPIGOT-7030, #750: Improve ban API

By: Doc <nachito94@msn.com>

paper-api/src/main/java/org/bukkit/BanEntry.java

@@ -15,8 +15,8 @@ import org.jetbrains.annotations.Nullable;
  *     <th>Property</th>
  *     <th>Description</th>
  * </tr><tr>
- *     <td>Target Name / IP Address</td>
+ *     <td>Target Profile / IP Address</td>
- *     <td>The target name or IP address</td>
+ *     <td>The target profile or IP address</td>
  * </tr><tr>
  *     <td>Creation Date</td>
  *     <td>The creation date of the ban</td>
@@ -40,18 +40,30 @@ import org.jetbrains.annotations.Nullable;
  * <p>
  * Likewise, changes to the associated {@link BanList} or other entries may or
  * may not be reflected in this entry.
+ *
+ * @param <T> The ban target
  */
-public interface BanEntry {
+public interface BanEntry<T> {
 
     /**
      * 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();
 }

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 <T> The ban target
  */
-public interface BanList {
+public interface BanList<T> {
 
     /**
      * 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<T> 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<T> 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<T> 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<T> 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<BanEntry> getBanEntries();
+    public Set<BanEntry<T>> 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);
 }

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.
-     * <p>
-     * 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 <T> The ban target
+     *
      * @return a ban list of the specified type
      */
     @NotNull
-    public static BanList getBanList(@NotNull BanList.Type type) {
+    public static <T extends BanList<?>> T getBanList(@NotNull BanList.Type type) {
         return server.getBanList(type);
     }
 

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<PlayerProfile> ban(@Nullable String reason, @Nullable Date expires, @Nullable String source);
+
     /**
      * Checks if this player is whitelisted or not
      *

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.
-     * <p>
-     * 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 <T> The ban target
+     *
      * @return a ban list of the specified type
      */
     @NotNull
-    public BanList getBanList(@NotNull BanList.Type type);
+    public <T extends BanList<?>> T getBanList(@NotNull BanList.Type type);
 
     /**
      * Gets a set containing all player operators.

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<InetSocketAddress> {
+
+}

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<PlayerProfile> {
+
+    /**
+     * {@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<PlayerProfile> addBan(@NotNull PlayerProfile target, @Nullable String reason, @Nullable Date expires, @Nullable String source);
+
+}

paper-api/src/main/java/org/bukkit/ban/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to bans.
+ */
+package org.bukkit.ban;

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<PlayerProfile> 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<InetSocketAddress> banIp(@Nullable String reason, @Nullable Date expires, @Nullable String source, boolean kickPlayer);
+
     /**
      * Says a message (or runs a command).
      *