implement PrivateMessagePreSendEvent (#3260)

This PR introduces an event to be called just before a private message is sent to a user. This event provides the message sender, the message recipient, and the contents of the message.

This event provides the possibility for greater customization of private messages, such as playing a sound or displaying a boss bar when a private message is received, or filtering private message content.

Closes #726, closes #2097.

Essentials/src/com/earth2me/essentials/messaging/IMessageRecipient.java

@@ -91,7 +91,9 @@ public interface IMessageRecipient {
         /** States that the message was <b>NOT</b> received as a result of the sender being ignored by the recipient. */
         SENDER_IGNORED,
         /** States that the message was <b>NOT</b> received as a result of the recipient being unreachable. */
-        UNREACHABLE;
+        UNREACHABLE,
+        /** States that the message was <b>NOT</b> received as a result of the message pre-send event being cancelled. */
+        EVENT_CANCELLED;
 
         /**
          * Returns whether this response is a success. In other words equal to {@link #SUCCESS} or {@link #SUCCESS_BUT_AFK}

Essentials/src/com/earth2me/essentials/messaging/SimpleMessageRecipient.java

@@ -3,6 +3,7 @@ package com.earth2me.essentials.messaging;
 import com.earth2me.essentials.IEssentials;
 import com.earth2me.essentials.IUser;
 import com.earth2me.essentials.User;
+import net.ess3.api.events.PrivateMessagePreSendEvent;
 
 import java.lang.ref.WeakReference;
 
@@ -62,6 +63,13 @@ public class SimpleMessageRecipient implements IMessageRecipient {
     }
 
     @Override public MessageResponse sendMessage(IMessageRecipient recipient, String message) {
+        final PrivateMessagePreSendEvent event = new PrivateMessagePreSendEvent(this, recipient, message);
+        ess.getServer().getPluginManager().callEvent(event);
+        if (event.isCancelled()) {
+            return MessageResponse.EVENT_CANCELLED;
+        }
+
+        message = event.getMessage();
         MessageResponse messageResponse = recipient.onReceiveMessage(this.parent, message);
         switch (messageResponse) {
             case UNREACHABLE:

Essentials/src/net/ess3/api/events/PrivateMessagePreSendEvent.java

@@ -0,0 +1,60 @@
+package net.ess3.api.events;
+
+import com.earth2me.essentials.messaging.IMessageRecipient;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called just before a private message is sent to its recipient
+ */
+public class PrivateMessagePreSendEvent extends Event implements Cancellable {
+
+    private static final HandlerList handlers = new HandlerList();
+    private boolean cancelled;
+
+    private IMessageRecipient sender;
+    private IMessageRecipient recipient;
+    private String message;
+
+    public PrivateMessagePreSendEvent(IMessageRecipient sender, IMessageRecipient recipient, String message) {
+        this.sender = sender;
+        this.recipient = recipient;
+        this.message = message;
+    }
+
+    public IMessageRecipient getSender() {
+        return sender;
+    }
+
+    public IMessageRecipient getRecipient() {
+        return recipient;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @Override
+    public void setCancelled(boolean b) {
+        this.cancelled = b;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}