BREAKING: replace defunct PlayerChatEvent with async chat. Addresses BUKKIT-2064

PlayerChatEvent is now Deprecated. It should be fired asynchronously, but
has not been so traditionally. To do so would massively break plugins that
rely on it.

AsyncPlayerChatEvent now replaces PlayerChatEvent. It uses comparable
functionality, but can be fired without synchronizing to the event manager.
The event will sometimes fire synchronously if triggered by a plugin.

Because PlayerChatEvent is now deprecated, PlayerCommandPreprocessEvent will
no longer extend PlayerChatEvent. This is almost completely source and
binary compatible, bar plugins that downcast to PlayerChatEvent.
Additionally, some methods that are non-functional have been marked
deprecated and indicate such.

Additionally, new constructors are now provided to allow for lazier
initialization of the receiving player set. A note has been added stating
plugins should be prepared for UnsupportedOperationExceptions if the caller
provides an unmodifiable collection.

4 files changed, 241 insertions, 3 deletions

diff --git a/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java
new file mode 100644
index 00000000..e5011391
--- /dev/null
+++ b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java
@@ -0,0 +1,115 @@
+package org.bukkit.event.player;
+
+import java.util.IllegalFormatException;
+import java.util.Set;
+
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * This event will sometimes fire synchronously, depending on how it was triggered.
+ * The constructor provides a boolean to indicate if the event was fired synchronously or asynchronously.
+ * If a plugin causes a Player to chat with {@link Player#chat(String)} or by other general means, this event will be synchronous.<br>
+ * <br>
+ * <b>Care should be taken to check {@link #isAsynchronous()} and treat the event appropriately.</b>
+ */
+public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private boolean cancel = false;
+    private String message;
+    private String format = "<%1$s> %2$s";
+    private final Set<Player> recipients;
+
+    /**
+     *
+     * @param async This changes the event to a synchronous state.
+     * @param who the chat sender
+     * @param message the message sent
+     * @param players the players to receive the message. This may be a lazy or unmodifiable collection.
+     */
+    public AsyncPlayerChatEvent(final boolean async, final Player who, final String message, final Set<Player> players) {
+        super(who, async);
+        this.message = message;
+        recipients = players;
+    }
+
+    /**
+     * Gets the message that the player is attempting to send. This message will be used with {@link #getFormat()}.
+     *
+     * @return Message the player is attempting to send
+     */
+    public String getMessage() {
+        return message;
+    }
+
+    /**
+     * Sets the message that the player will send. This message will be used with {@link #getFormat()}.
+     *
+     * @param message New message that the player will send
+     */
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    /**
+     * Gets the format to use to display this chat message.
+     * When this event finishes execution, the first format parameter is the {@link Player#getDisplayName()} and the second parameter is {@link #getMessage()}
+     *
+     * @return {@link String#format(String, Object...)} compatible format string
+     */
+    public String getFormat() {
+        return format;
+    }
+
+    /**
+     * Sets the format to use to display this chat message.
+     * When this event finishes execution, the first format parameter is the {@link Player#getDisplayName()} and the second parameter is {@link #getMessage()}
+     *
+     * @param format {@link String#format(String, Object...)} compatible format string
+     * @throws IllegalFormatException if the underlying API throws the exception
+     * @throws NullPointerException if format is null
+     * @see String#format(String, Object...)
+     */
+    public void setFormat(final String format) throws IllegalFormatException, NullPointerException {
+        // Oh for a better way to do this!
+        try {
+            String.format(format, player, message);
+        } catch (RuntimeException ex) {
+            ex.fillInStackTrace();
+            throw ex;
+        }
+
+        this.format = format;
+    }
+
+    /**
+     * Gets a set of recipients that this chat message will be displayed to.
+     * The set returned is not guaranteed to be mutable and may auto-populate on access.
+     * Any listener accessing the returned set should be aware that it may reduce performance for a lazy set implementation.<br>
+     * <br>
+     * <b>Listeners should be aware that modifying the list may throw {@link UnsupportedOperationException} if the event caller provides an unmodifiable set.</b>
+     *
+     * @return All Players who will see this chat message
+     */
+    public Set<Player> getRecipients() {
+        return recipients;
+    }
+
+    public boolean isCancelled() {
+        return cancel ;
+    }
+
+    public void setCancelled(boolean cancel) {
+        this.cancel = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}
diff --git a/src/main/java/org/bukkit/event/player/PlayerChatEvent.java b/src/main/java/org/bukkit/event/player/PlayerChatEvent.java
index 1856c187..481dbaaa 100644
--- a/src/main/java/org/bukkit/event/player/PlayerChatEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerChatEvent.java
@@ -4,24 +4,37 @@ import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
 
+import org.apache.commons.lang.Validate;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
 /**
  * Holds information for player chat and commands
+ * @deprecated This event was broken in 1.3, where chat should be asynchronous.
+ * It is deprecated because listening for it is detrimental to server performance.
+ * {@link AsyncPlayerChatEvent} is the encouraged alternative.
  */
+@Deprecated
 public class PlayerChatEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private boolean cancel = false;
     private String message;
-    private String format = "<%1$s> %2$s";
+    private String format;
     private final Set<Player> recipients;
 
     public PlayerChatEvent(final Player player, final String message) {
         super(player);
+        this.message = message;
+        this.format = "<%1$s> %2$s";
         this.recipients = new HashSet<Player>(Arrays.asList(player.getServer().getOnlinePlayers()));
+    }
+
+    public PlayerChatEvent(final Player player, final String message, final String format, final Set<Player> recipients) {
+        super(player);
         this.message = message;
+        this.format = format;
+        this.recipients = recipients;
     }
 
     public boolean isCancelled() {
@@ -57,6 +70,7 @@ public class PlayerChatEvent extends PlayerEvent implements Cancellable {
      * @param player New player which this event will execute as
      */
     public void setPlayer(final Player player) {
+        Validate.notNull(player, "Player cannot be null");
         this.player = player;
     }
 
diff --git a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
index ffb5d43c..4fbfc666 100644
--- a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
@@ -1,17 +1,120 @@
 package org.bukkit.event.player;
 
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+import org.apache.commons.lang.Validate;
 import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
 /**
  * Called early in the command handling process. This event is only
  * for very exceptional cases and you should not normally use it.
  */
-public class PlayerCommandPreprocessEvent extends PlayerChatEvent {
+public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
+    private boolean cancel = false;
+    private String message;
+    private String format = "<%1$s> %2$s";
+    private final Set<Player> recipients;
 
     public PlayerCommandPreprocessEvent(final Player player, final String message) {
-        super(player, message);
+        super(player);
+        this.recipients = new HashSet<Player>(Arrays.asList(player.getServer().getOnlinePlayers()));
+        this.message = message;
+    }
+
+    public PlayerCommandPreprocessEvent(final Player player, final String message, final Set<Player> recipients) {
+        super(player);
+        this.recipients = recipients;
+        this.message = message;
+    }
+
+    public boolean isCancelled() {
+        return cancel;
+    }
+
+    public void setCancelled(boolean cancel) {
+        this.cancel = cancel;
+    }
+
+    /**
+     * Gets the command that the player is attempting to send.
+     * All commands begin with a special character; implementations do not consider the first character when executing the content.
+     *
+     * @return Message the player is attempting to send
+     */
+    public String getMessage() {
+        return message;
+    }
+
+    /**
+     * Sets the command that the player will send.
+     * All commands begin with a special character; implementations do not consider the first character when executing the content.
+     *
+     * @param command New message that the player will send
+     * @throws IllegalArgumentException if command is null or empty
+     */
+    public void setMessage(String command) throws IllegalArgumentException {
+        Validate.notNull(command, "Command cannot be null");
+        Validate.notEmpty(command, "Command cannot be empty");
+        this.message = command;
+    }
+
+    /**
+     * Sets the player that this command will be executed as.
+     *
+     * @param player New player which this event will execute as
+     * @throws IllegalArgumentException if the player provided is null
+     */
+    public void setPlayer(final Player player) throws IllegalArgumentException {
+        Validate.notNull(player, "Player cannot be null");
+        this.player = player;
+    }
+
+    /**
+     * Gets the format to use to display this chat message
+     *
+     * @deprecated This method is provided for backward compatibility with no guarantee to the use of the format.
+     * @return String.Format compatible format string
+     */
+    @Deprecated
+    public String getFormat() {
+        return format;
+    }
+
+    /**
+     * Sets the format to use to display this chat message
+     *
+     * @deprecated This method is provided for backward compatibility with no guarantee to the effect of modifying the format.
+     * @param format String.Format compatible format string
+     */
+    @Deprecated
+    public void setFormat(final String format) {
+        // Oh for a better way to do this!
+        try {
+            String.format(format, player, message);
+        } catch (RuntimeException ex) {
+            ex.fillInStackTrace();
+            throw ex;
+        }
+
+        this.format = format;
+    }
+
+    /**
+     * Gets a set of recipients that this chat message will be displayed to.
+     * The set returned is not guaranteed to be mutable and may auto-populate on access.
+     * Any listener accessing the returned set should be aware that it may reduce performance for a lazy set implementation.
+     * Listeners should be aware that modifying the list may throw {@link UnsupportedOperationException} if the event caller provides an unmodifiable set.
+     * @deprecated This method is provided for backward compatibility with no guarantee to the effect of viewing or modifying the set.
+     * @return All Players who will see this chat message
+     */
+    @Deprecated
+    public Set<Player> getRecipients() {
+        return recipients;
     }
 
     @Override
diff --git a/src/main/java/org/bukkit/event/player/PlayerEvent.java b/src/main/java/org/bukkit/event/player/PlayerEvent.java
index 1301ac29..0d4833f6 100644
--- a/src/main/java/org/bukkit/event/player/PlayerEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerEvent.java
@@ -13,6 +13,12 @@ public abstract class PlayerEvent extends Event {
         player = who;
     }
 
+    PlayerEvent(final Player who, boolean async) {
+        super(async);
+        player = who;
+
+    }
+
     /**
      * Returns the player involved in this event
      *