Add banning API and resolve associated command issues. Adds BUKKIT-3535.

Fixes BUKKIT-5371 and BUKKIT-4285

Prior to this commit, ban reasons were not supported by banning commands.
Additionally, the player(s) affected by the ban-ip command would not have
been removed from the server via a kick.

The Bukkit API lacked support for modifying various attributes associated
with bans, such as the reason and expiration date. This caused various plugins
to use external or other means to store a ban reason, making the built-in
banning system on the server partially useless.

Now the ban commands will accept reasons for the bans as well as kick the
player from the server once banned. That means that if an IP is banned
that all players using that IP will be removed from the server.

The API provided now supports editing the ban reason, creation date,
expiration date and source. The ban list has also been created to
provide this information more easily. Editing the data requires an
implementing plugin to manually save the information with the provided
method in BanEntry or BanList once changes have been made.

The addition of this API has deprecated the use of OfflinePlayer#setBanned()
as it has been replaced by BanList#addBan().

src/main/java/org/bukkit/BanEntry.java

@@ -0,0 +1,97 @@
+package org.bukkit;
+
+import java.util.Date;
+
+/**
+ * A single entry from the ban list. This may represent either a player ban or an
+ * IP ban.<br />
+ * Ban entries include the following properties:
+ * <ul>
+ *     <li><b>Target Name/IP Address</b> - The target name or IP address
+ *     <li><b>Creation Date</b> - The creation date of the ban
+ *     <li><b>Source</b> - The source of the ban, such as a player, console, plugin, etc
+ *     <li><b>Expiration Date</b> - The expiration date of the ban
+ *     <li><b>Reason</b> - The reason for the ban
+ * </ul>
+ * Unsaved information is not automatically written to the implementation's ban list, instead,
+ * the {@link #save()} method must be called to write the changes to the ban list. If this ban
+ * entry has expired (such as from an unban) and is no longer found in the list, the {@link #save()}
+ * call will re-add it to the list, therefore banning the victim specified.
+ */
+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
+     */
+    public String getTarget();
+
+    /**
+     * Gets the date this ban entry was created.
+     *
+     * @return The creation date
+     */
+    public Date getCreated();
+
+    /**
+     * Sets the date this ban entry was created.<br />
+     * Use {@link #save()} to save the changes.
+     *
+     * @param created The new created date, cannot be null
+     */
+    public void setCreated(Date created);
+
+    /**
+     * Gets the source of this ban.<br />
+     * A source is considered any String, although this is generally a player name.
+     *
+     * @return The source of the ban
+     */
+    public String getSource();
+
+    /**
+     * Sets the source of this ban.<br />
+     * A source is considered any String, although this is generally a player name.<br />
+     * Use {@link #save()} to save the changes.
+     *
+     * @param source The new source where null values become empty strings
+     */
+    public void setSource(String source);
+
+    /**
+     * Gets the date this ban expires on, or null for no defined end date.
+     *
+     * @return The expiration date
+     */
+    public Date getExpiration();
+
+    /**
+     * Sets the date this ban expires on. Null values are considered "infinite" bans.<br />
+     * Use {@link #save()} to save the changes.
+     *
+     * @param expiry The new expiration date, or null to indicate an eternity
+     */
+    public void setExpiration(Date expiration);
+
+    /**
+     * Gets the reason for this ban.
+     *
+     * @return The ban reason or null if not set
+     */
+    public String getReason();
+
+    /**
+     * Sets the reason for this ban. Reasons must not be null.<br />
+     * Use {@link #save()} to save the changes.
+     *
+     * @param reason The new reason, null values assume the implementation default
+     */
+    public void setReason(String reason);
+
+    /**
+     * Saves the ban entry, overwriting any previous data in the ban list.<br />
+     * Saving the ban entry of an unbanned player will cause the player to be banned once again.
+     */
+    public void save();
+
+}

src/main/java/org/bukkit/BanList.java

@@ -0,0 +1,66 @@
+package org.bukkit;
+
+import java.util.Date;
+import java.util.Set;
+
+/**
+ * A ban list, containing bans of type {@link org.bukkit.BanList.Type}
+ */
+public interface BanList {
+    /**
+     * Gets a {@link BanEntry} by target.
+     *
+     * @param target Entry parameter to search for
+     * @return BanEntry for the submitted query, or null if none found
+     */
+    public BanEntry getBanEntry(String target);
+
+    /**
+     * Adds a ban to the ban list. If a previous ban exists, this will overwrite the previous
+     * entry.
+     *
+     * @param target The target of the ban
+     * @param reason Reason for the ban. If null, the implementation default is assumed
+     * @param expires Expiration Date of the ban. If null, "infinity" is assumed
+     * @param source Source of the ban. If null, the implementation default is assumed
+     * @return The BanEntry of the added ban
+     */
+    public BanEntry addBan(String target, String reason, Date expires, String source);
+
+    /**
+     * Gets a set containing every {@link BanEntry} in the BanList.
+     *
+     * @return an immutable set containing every BanEntry tracked by the BanList
+     */
+    public Set<BanEntry> getBanEntries();
+
+    /**
+     * Gets if a {@link BanEntry} exists for the target, indicating ban status
+     *
+     * @param target Entry target to lookup
+     * @return true if a {@link BanEntry} exists for the name, indicating ban status
+     */
+    public boolean isBanned(String target);
+
+    /**
+     * Removes the specified target from the list, therefore indicating a "not banned" status.
+     *
+     * @param target The target to remove from the list
+     */
+    public void pardon(String target);
+
+    /**
+     * Represents the various types a {@link BanList} may track.
+     */
+    public enum Type {
+        /**
+         * Banned player names
+         */
+        NAME,
+        /**
+         * Banned player IP addresses
+         */
+        IP;
+    }
+
+}

src/main/java/org/bukkit/Bukkit.java

@@ -447,6 +447,13 @@ public static Set<OfflinePlayer> getBannedPlayers() {
         return server.getBannedPlayers();
     }
 
+    /**
+     * @see Server#getBanList(BanList.Type)
+     */
+    public static BanList getBanList(BanList.Type type){
+    	return server.getBanList(type);
+    }
+
     /**
      * @see Server#setWhitelist(boolean value)
      */

src/main/java/org/bukkit/OfflinePlayer.java

@@ -32,7 +32,9 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * Bans or unbans this player
      *
      * @param banned true if banned
+     * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, java.util.Date, String)} or {@link org.bukkit.BanList#unban(String)} to enhance functionality
      */
+    @Deprecated
     public void setBanned(boolean banned);
 
     /**

src/main/java/org/bukkit/Server.java

@@ -572,6 +572,14 @@ public interface Server extends PluginMessageRecipient {
      */
     public Set<OfflinePlayer> getBannedPlayers();
 
+    /**
+     * Gets a BanList for the supplied BanList Type
+     *
+     * @param type The BanList Type to fetch, cannot be null
+     * @return the BanList of the specified type
+     */
+    public BanList getBanList(BanList.Type type);
+
     /**
      * Gets a set containing all player operators
      *

src/main/java/org/bukkit/command/defaults/BanCommand.java

@@ -2,7 +2,9 @@
 
 import java.util.List;
 
+import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.Validate;
+import org.bukkit.BanList;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.command.Command;
@@ -27,8 +29,8 @@ public boolean execute(CommandSender sender, String currentAlias, String[] args)
             return false;
         }
 
-        // TODO: Ban Reason support
-        Bukkit.getOfflinePlayer(args[0]).setBanned(true);
+        String reason = args.length > 0 ? StringUtils.join(args, ' ', 1, args.length) : null;
+        Bukkit.getBanList(BanList.Type.NAME).addBan(args[0], reason, null, sender.getName());
 
         Player player = Bukkit.getPlayer(args[0]);
         if (player != null) {

src/main/java/org/bukkit/command/defaults/BanIpCommand.java

@@ -3,7 +3,9 @@
 import java.util.List;
 import java.util.regex.Pattern;
 
+import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.Validate;
+import org.bukkit.BanList;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.command.Command;
@@ -30,9 +32,10 @@ public boolean execute(CommandSender sender, String currentAlias, String[] args)
             return false;
         }
 
-        // TODO: Ban Reason support
+        String reason = args.length > 0 ? StringUtils.join(args, ' ', 1, args.length) : null;
+
         if (ipValidity.matcher(args[0]).matches()) {
-            processIPBan(args[0], sender);
+            processIPBan(args[0], sender, reason);
         } else {
             Player player = Bukkit.getPlayer(args[0]);
 
@@ -41,15 +44,21 @@ public boolean execute(CommandSender sender, String currentAlias, String[] args)
                 return false;
             }
 
-            processIPBan(player.getAddress().getAddress().getHostAddress(), sender);
+            processIPBan(player.getAddress().getAddress().getHostAddress(), sender, reason);
         }
 
         return true;
     }
 
-    private void processIPBan(String ip, CommandSender sender) {
-        // TODO: Kick on ban
-        Bukkit.banIP(ip);
+    private void processIPBan(String ip, CommandSender sender, String reason) {
+        Bukkit.getBanList(BanList.Type.IP).addBan(ip, reason, null, sender.getName());
+
+        // Find all matching players and kick
+        for (Player player : Bukkit.getOnlinePlayers()) {
+            if (player.getAddress().getAddress().getHostAddress().equals(ip)) {
+                player.kickPlayer("You have been IP banned.");
+            }
+        }
 
         Command.broadcastCommandMessage(sender, "Banned IP Address " + ip);
     }

src/main/java/org/bukkit/command/defaults/BanListCommand.java

@@ -4,8 +4,10 @@
 import java.util.List;
 
 import org.apache.commons.lang.Validate;
+import org.bukkit.BanEntry;
+import org.bukkit.BanList;
 import org.bukkit.Bukkit;
-import org.bukkit.OfflinePlayer;
+import org.bukkit.ChatColor;
 import org.bukkit.command.CommandSender;
 import org.bukkit.util.StringUtil;
 
@@ -25,9 +27,18 @@ public BanListCommand() {
     public boolean execute(CommandSender sender, String currentAlias, String[] args) {
         if (!testPermission(sender)) return true;
 
-        // TODO: ips support
+        BanList.Type banType = BanList.Type.NAME;
+        if (args.length > 0) {
+            if (args[0].equalsIgnoreCase("ips")) {
+                banType = BanList.Type.IP;
+            } else if (!args[0].equalsIgnoreCase("players")) {
+                sender.sendMessage(ChatColor.RED + "Usage: " + usageMessage);
+                return false;
+            }
+        }
+
         StringBuilder message = new StringBuilder();
-        OfflinePlayer[] banlist = Bukkit.getServer().getBannedPlayers().toArray(new OfflinePlayer[0]);
+        BanEntry[] banlist = Bukkit.getBanList(banType).getBanEntries().toArray(new BanEntry[0]);
 
         for (int x = 0; x < banlist.length; x++) {
             if (x != 0) {
@@ -37,7 +48,7 @@ public boolean execute(CommandSender sender, String currentAlias, String[] args)
                     message.append(", ");
                 }
             }
-            message.append(banlist[x].getName());
+            message.append(banlist[x].getTarget());
         }
 
         sender.sendMessage("There are " + banlist.length + " total banned players:");

src/main/java/org/bukkit/command/defaults/PardonCommand.java

@@ -4,6 +4,7 @@
 import java.util.List;
 
 import org.apache.commons.lang.Validate;
+import org.bukkit.BanList;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.OfflinePlayer;
@@ -29,7 +30,7 @@ public boolean execute(CommandSender sender, String currentAlias, String[] args)
             return false;
         }
 
-        Bukkit.getOfflinePlayer(args[0]).setBanned(false);
+        Bukkit.getBanList(BanList.Type.NAME).pardon(args[0]);
         Command.broadcastCommandMessage(sender, "Pardoned " + args[0]);
         return true;
     }