GUACAMOLE-364: declare and implement new listener API

This commit also deprecates the existing listener API and
includes support for adapting existing listener implementations
to the new API.

guacamole-ext/src/main/java/org/apache/guacamole/net/event/AuthenticationSuccessEvent.java

@@ -26,6 +26,11 @@ import org.apache.guacamole.net.auth.UserContext;
  * An event which is triggered whenever a user's credentials pass
  * authentication. The credentials that passed authentication are included
  * within this event, and can be retrieved using getCredentials().
+ * <p>
+ * If a {@link org.apache.guacamole.net.event.listener.Listener} throws
+ * a GuacamoleException when handling an event of this type, successful authentication
+ * is effectively <em>vetoed</em> and will be subsequently processed as though the
+ * authentication failed.
  */
 public class AuthenticationSuccessEvent implements UserEvent, CredentialEvent {
 

guacamole-ext/src/main/java/org/apache/guacamole/net/event/TunnelCloseEvent.java

@@ -28,6 +28,10 @@ import org.apache.guacamole.net.auth.UserContext;
  * being closed can be accessed through getTunnel(), and the UserContext
  * associated with the request which is closing the tunnel can be retrieved
  * with getUserContext().
+ * <p>
+ * If a {@link org.apache.guacamole.net.event.listener.Listener} throws
+ * a GuacamoleException when handling an event of this type, the request to close
+ * the tunnel is effectively <em>vetoed</em> and will remain connected.
  */
 public class TunnelCloseEvent implements UserEvent, CredentialEvent, TunnelEvent {
 

guacamole-ext/src/main/java/org/apache/guacamole/net/event/TunnelConnectEvent.java

@@ -28,6 +28,10 @@ import org.apache.guacamole.net.auth.UserContext;
  * being connected can be accessed through getTunnel(), and the UserContext
  * associated with the request which is connecting the tunnel can be retrieved
  * with getUserContext().
+ * <p>
+ * If a {@link org.apache.guacamole.net.event.listener.Listener} throws
+ * a GuacamoleException when handling an event of this type, the tunnel connection
+ * is effectively <em>vetoed</em> and will be subsequently closed.
  */
 public class TunnelConnectEvent implements UserEvent, CredentialEvent, TunnelEvent {
 

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java

@@ -26,8 +26,12 @@ import org.apache.guacamole.net.event.AuthenticationFailureEvent;
  * A listener whose authenticationFailed() hook will fire immediately
  * after a user's authentication attempt fails. Note that this hook cannot
  * be used to cancel the authentication failure.
+ *
+ * @deprecated
+ *      Listeners should instead implement the {@link Listener} interface
  */
-public interface AuthenticationFailureListener extends Listener {
+@Deprecated
+public interface AuthenticationFailureListener {
 
     /**
      * Event hook which fires immediately after a user's authentication attempt

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java

@@ -27,8 +27,12 @@ import org.apache.guacamole.net.event.AuthenticationSuccessEvent;
  * authentication attempt succeeds. If a user successfully authenticates,
  * the authenticationSucceeded() hook has the opportunity to cancel the
  * authentication and force it to fail.
+ *
+ * @deprecated
+ *      Listeners should instead implement the {@link Listener} interface
  */
-public interface AuthenticationSuccessListener extends Listener {
+@Deprecated
+public interface AuthenticationSuccessListener {
 
     /**
      * Event hook which fires immediately after a user's authentication attempt

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java

@@ -19,10 +19,33 @@
 
 package org.apache.guacamole.net.event.listener;
 
+import org.apache.guacamole.GuacamoleException;
+
 /**
- * A marker interface extended by all listener types. This interface is used
- * simply to validate that a listener class identified in an extension
- * actually implements some listener interface.
+ * A listener for events that occur in handing various Guacamole requests
+ * such as authentication, tunnel connect/close, etc. Listeners are registered
+ * through the extension manifest mechanism. When an event occurs, listeners
+ * are notified in the order in which they are declared in the manifest and
+ * continues until either all listeners have been notified or with the first
+ * listener that throws a GuacamoleException or other runtime exception.
  */
 public interface Listener {
+
+    /**
+     * Notifies the recipient that an event has occurred.
+     * <p>
+     * Throwing an exception from an event listener can act to veto an action in
+     * progress for some event types. See the Javadoc for specific event types for
+     * details.
+     *
+     * @param event
+     *     an object that describes the subject event
+     *
+     * @throws GuacamoleException
+     *     If the listener wishes to stop notification of the event to subsequent
+     *     listeners. For some event types, this acts to veto an action in progress;
+     *     e.g. treating a successful authentication as though it failed
+     */
+    void handleEvent(Object event) throws GuacamoleException;
+
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java

@@ -25,8 +25,12 @@ import org.apache.guacamole.net.event.TunnelCloseEvent;
 /**
  * A listener whose tunnelClosed() hook will fire immediately after an
  * existing tunnel is closed.
+ *
+ * @deprecated
+ *      Listeners should instead implement the {@link Listener} interface
  */
-public interface TunnelCloseListener extends Listener {
+@Deprecated
+public interface TunnelCloseListener {
 
     /**
      * Event hook which fires immediately before an existing tunnel is closed.

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java

@@ -25,8 +25,12 @@ import org.apache.guacamole.net.event.TunnelConnectEvent;
 /**
  * A listener whose tunnelConnected() hook will fire immediately after a new
  * tunnel is connected.
+ *
+ * @deprecated
+ *      Listeners should instead implement the {@link Listener} interface
  */
-public interface TunnelConnectListener extends Listener {
+@Deprecated
+public interface TunnelConnectListener {
 
    /**
      * Event hook which fires immediately after a new tunnel is connected.