GUACAMOLE-364: Merge changes restoring extension support for event listeners.

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,19 +26,26 @@ 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  {
+@Deprecated
+public interface AuthenticationFailureListener {
 
     /**
      * Event hook which fires immediately after a user's authentication attempt
      * fails.
      *
-     * @param e The AuthenticationFailureEvent describing the authentication
-     *          failure that just occurred.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            authentication failure event. Note that
-     *                            throwing an exception will NOT cause the
-     *                            authentication failure to be canceled.
+     * @param e
+     *      The AuthenticationFailureEvent describing the authentication
+     *      failure that just occurred.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the authentication failure event.
+     *      Note that throwing an exception will NOT cause the authentication
+     *      failure to be canceled (which makes no sense), but it will prevent
+     *      subsequent listeners from receiving the notification.
      */
     void authenticationFailed(AuthenticationFailureEvent e)
             throws GuacamoleException;

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

@@ -27,7 +27,11 @@ 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.
  */
+@Deprecated
 public interface AuthenticationSuccessListener {
 
     /**
@@ -35,15 +39,18 @@ public interface AuthenticationSuccessListener {
      * succeeds. The return value of this hook dictates whether the
      * successful authentication attempt is canceled.
      *
-     * @param e The AuthenticationFailureEvent describing the authentication
-     *          failure that just occurred.
-     * @return true if the successful authentication attempt should be
-     *         allowed, or false if the attempt should be denied, causing
-     *         the attempt to effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            authentication success event. Throwing an
-     *                            exception will also cancel the authentication
-     *                            success.
+     * @param e
+     *      The AuthenticationFailureEvent describing the authentication
+     *      failure that just occurred.
+     *
+     * @return
+     *      true if the successful authentication attempt should be
+     *      allowed, or false if the attempt should be denied, causing
+     *      the attempt to effectively fail.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the authentication success event.
+     *      Throwing an exception will also cancel the authentication success.
      */
     boolean authenticationSucceeded(AuthenticationSuccessEvent e)
             throws GuacamoleException;

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

@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+
+package org.apache.guacamole.net.event.listener;
+
+import org.apache.guacamole.GuacamoleException;
+
+/**
+ * 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 event that has occurred.
+     *
+     * @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

@@ -23,26 +23,33 @@ import org.apache.guacamole.GuacamoleException;
 import org.apache.guacamole.net.event.TunnelCloseEvent;
 
 /**
- * A listener whose tunnelClosed() hook will fire immediately after an
+ * A listener whose tunnelClosed() hook will fire immediately before an
  * existing tunnel is closed.
+ *
+ * @deprecated
+ *      Listeners should instead implement the {@link Listener} interface.
  */
+@Deprecated
 public interface TunnelCloseListener {
 
     /**
-     * Event hook which fires immediately after an existing tunnel is closed.
+     * Event hook which fires immediately before an existing tunnel is closed.
      * The return value of this hook dictates whether the tunnel is allowed to
      * be closed.
      *
-     * @param e The TunnelCloseEvent describing the tunnel being closed and
-     *          any associated credentials.
-     * @return true if the tunnel should be allowed to be closed, or false
-     *         if the attempt should be denied, causing the attempt to
-     *         effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            tunnel close event. Throwing an exception
-     *                            will also stop the tunnel from being closed.
+     * @param e
+     *      The TunnelCloseEvent describing the tunnel being closed and
+     *      any associated credentials.
+     *
+     * @return
+     *      true if the tunnel should be allowed to be closed, or false
+     *      if the attempt should be denied, causing the attempt to
+     *      effectively fail.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the tunnel close event. Throwing
+     *      an exception will also stop the tunnel from being closed.
      */
-    boolean tunnelClosed(TunnelCloseEvent e)
-            throws GuacamoleException;
+    boolean tunnelClosed(TunnelCloseEvent e) throws GuacamoleException;
 
 }

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

@@ -25,25 +25,32 @@ 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.
  */
+@Deprecated
 public interface TunnelConnectListener {
 
    /**
-     * Event hook which fires immediately after a new tunnel is connected.
-     * The return value of this hook dictates whether the tunnel is made visible
-     * to the session.
-     *
-     * @param e The TunnelConnectEvent describing the tunnel being connected and
-     *          any associated credentials.
-     * @return true if the tunnel should be allowed to be connected, or false
-     *         if the attempt should be denied, causing the attempt to
-     *         effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            tunnel connect event. Throwing an exception
-     *                            will also stop the tunnel from being made
-     *                            visible to the session.
-     */
-    boolean tunnelConnected(TunnelConnectEvent e)
-            throws GuacamoleException;
+    * Event hook which fires immediately after a new tunnel is connected.
+    * The return value of this hook dictates whether the tunnel is made visible
+    * to the session.
+    *
+    * @param e
+    *      The TunnelConnectEvent describing the tunnel being connected and
+    *      any associated credentials.
+    *
+    * @return
+    *      true if the tunnel should be allowed to be connected, or false
+    *      if the attempt should be denied, causing the attempt to
+    *      effectively fail.
+    *
+    * @throws GuacamoleException
+    *       If an error occurs while handling the tunnel connect event. Throwing
+    *       an exception will also stop the tunnel from being made visible to the
+    *       session.
+    */
+    boolean tunnelConnected(TunnelConnectEvent e) throws GuacamoleException;
 
 }