GUACAMOLE-364: addressed various documentation issues

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

@@ -28,7 +28,7 @@ import org.apache.guacamole.net.event.AuthenticationFailureEvent;
  * be used to cancel the authentication failure.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface AuthenticationFailureListener {
@@ -37,12 +37,15 @@ public interface AuthenticationFailureListener {
      * Event hook which fires immediately after a user's authentication attempt
      * fails.
      *
-     * @param e The AuthenticationFailureEvent describing the authentication
+     * @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
+     * @throws GuacamoleException
-     *                            throwing an exception will NOT cause the
+     *      If an error occurs while handling the authentication failure event.
-     *                            authentication failure to be canceled.
+     *      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

@@ -39,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
+     * @param e
+     *      The AuthenticationFailureEvent describing the authentication
      *      failure that just occurred.
-     * @return true if the successful authentication attempt should be
+     *
+     * @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
+     * @throws GuacamoleException
-     *                            exception will also cancel the authentication
+     *      If an error occurs while handling the authentication success event.
-     *                            success.
+     *      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

@@ -39,12 +39,12 @@ public interface Listener {
      * details.
      *
      * @param event
-     *     an object that describes the subject 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
+     *     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

@@ -27,7 +27,7 @@ import org.apache.guacamole.net.event.TunnelCloseEvent;
  * existing tunnel is closed.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface TunnelCloseListener {
@@ -37,16 +37,19 @@ public interface TunnelCloseListener {
      * 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
+     * @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
+     *
+     * @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
+     * @throws GuacamoleException
-     *                            will also stop the tunnel from being closed.
+     *      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)
+    boolean tunnelClosed(TunnelCloseEvent e) throws GuacamoleException;
-            throws GuacamoleException;
 
 }

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

@@ -27,7 +27,7 @@ import org.apache.guacamole.net.event.TunnelConnectEvent;
  * tunnel is connected.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface TunnelConnectListener {
@@ -37,17 +37,20 @@ public interface TunnelConnectListener {
     * 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
+    * @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
+    *
+    * @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
+    * @throws GuacamoleException
-     *                            will also stop the tunnel from being made
+    *       If an error occurs while handling the tunnel connect event. Throwing
-     *                            visible to the session.
+    *       an exception will also stop the tunnel from being made visible to the
+    *       session.
     */
-    boolean tunnelConnected(TunnelConnectEvent e)
+    boolean tunnelConnected(TunnelConnectEvent e) throws GuacamoleException;
-            throws GuacamoleException;
 
 }

guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java

@@ -380,7 +380,7 @@ public class ExtensionManifest {
      * class name.
      *
      * @param listeners
-     *      a collection of classnames for all listeners within the extension
+     *      A collection of classnames for all listeners within the extension.
      */
     public void setListeners(Collection<String> listeners) {
         this.listeners = listeners;

guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java

@@ -198,13 +198,13 @@ public class ExtensionModule extends ServletModule {
      * Binds the given provider class such that a listener is bound for each
      * listener interface implemented by the provider and such that all bound
      * listener instances can be obtained via injection.
-     * *
+     *
      * @param providerClass
-     *     The listener provider class to bind
+     *     The listener class to bind.
      */
-    private void bindListeners(Class<?> providerClass) {
+    private void bindListener(Class<?> providerClass) {
 
-        logger.debug("[{}] Binding listeners \"{}\".",
+        logger.debug("[{}] Binding listener \"{}\".",
                 boundListeners.size(), providerClass.getName());
         boundListeners.addAll(ListenerFactory.createListeners(providerClass));
 
@@ -222,7 +222,7 @@ public class ExtensionModule extends ServletModule {
 
         // Bind each listener within extension
         for (Class<?> listener : listeners)
-            bindListeners(listener);
+            bindListener(listener);
     }
 
     /**

guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java

@@ -45,10 +45,10 @@ class ListenerFactory {
      * objects that adapt the legacy listener interfaces will be returned.
      *
      * @param providerClass
-     *      a class that represents a listener provider
+     *      A class that represents a listener.
      *
      * @return
-     *      list of listeners represented by the given provider class
+     *      The list of listeners represented by the given provider class.
      */
     static List<Listener> createListeners(Class<?> providerClass) {
 
@@ -62,6 +62,16 @@ class ListenerFactory {
 
     }
 
+    /**
+     * Creates a list of adapters for the given object, based on the legacy
+     * listener interfaces it implements.
+     *
+     * @param provider
+     *      An object that implements zero or more legacy listener interfaces.
+     *
+     * @return
+     *      The list of listeners represented by the given provider class.
+     */
     @SuppressWarnings("deprecation")
     private static List<Listener> createListenerAdapters(Object provider) {
 
@@ -98,13 +108,16 @@ class ListenerFactory {
     @SuppressWarnings("deprecation")
     private static class AuthenticationSuccessListenerAdapter implements Listener {
 
+        /**
+         * The delegate listener for this adapter.
+         */
         private final AuthenticationSuccessListener delegate;
 
         /**
-         * Constructs a new adapter.
+         * Constructs a new adapter that delivers events to the given delegate.
          *
          * @param delegate
-         *      the delegate listener
+         *      The delegate listener.
          */
         AuthenticationSuccessListenerAdapter(AuthenticationSuccessListener delegate) {
             this.delegate = delegate;
@@ -116,10 +129,10 @@ class ListenerFactory {
          * to veto the authentication success event. All other event types are ignored.
          *
          * @param event
-         *     an object that describes the subject event
+         *     An object that describes the event that occurred.
          *
          * @throws GuacamoleException
-         *      if thrown by the delegate listener
+         *      If thrown by the delegate listener.
          */
         @Override
         public void handleEvent(Object event) throws GuacamoleException {
@@ -140,13 +153,16 @@ class ListenerFactory {
     @SuppressWarnings("deprecation")
     private static class AuthenticationFailureListenerAdapter implements Listener {
 
+        /**
+         * The delegate listener for this adapter.
+         */
         private final AuthenticationFailureListener delegate;
 
         /**
-         * Constructs a new adapter.
+         * Constructs a new adapter that delivers events to the given delegate.
          *
          * @param delegate
-         *      the delegate listener
+         *      The delegate listener.
          */
         AuthenticationFailureListenerAdapter(AuthenticationFailureListener delegate) {
             this.delegate = delegate;
@@ -157,10 +173,10 @@ class ListenerFactory {
          * listener. All other event types are ignored.
          *
          * @param event
-         *     an object that describes the subject event
+         *     An object that describes the event that occurred.
          *
          * @throws GuacamoleException
-         *      if thrown by the delegate listener
+         *      If thrown by the delegate listener.
          */
         @Override
         public void handleEvent(Object event) throws GuacamoleException {
@@ -178,13 +194,16 @@ class ListenerFactory {
     @SuppressWarnings("deprecation")
     private static class TunnelConnectListenerAdapter implements Listener {
 
+        /**
+         * The delegate listener for this adapter.
+         */
         private final TunnelConnectListener delegate;
 
         /**
-         * Constructs a new adapter.
+         * Constructs a new adapter that delivers events to the given delegate.
          *
          * @param delegate
-         *      the delegate listener
+         *      The delegate listener.
          */
         TunnelConnectListenerAdapter(TunnelConnectListener delegate) {
             this.delegate = delegate;
@@ -196,10 +215,10 @@ class ListenerFactory {
          * to veto the tunnel connect event. All other event types are ignored.
          *
          * @param event
-         *     an object that describes the subject event
+         *     An object that describes the event that occurred.
          *
          * @throws GuacamoleException
-         *      if thrown by the delegate listener
+         *      If thrown by the delegate listener.
          */
         @Override
         public void handleEvent(Object event) throws GuacamoleException {
@@ -219,13 +238,16 @@ class ListenerFactory {
     @SuppressWarnings("deprecation")
     private static class TunnelCloseListenerAdapter implements Listener {
 
+        /**
+         * The delegate listener for this adapter.
+         */
         private final TunnelCloseListener delegate;
 
         /**
-         * Constructs a new adapter.
+         * Constructs a new adapter that delivers events to the given delegate.
          *
          * @param delegate
-         *      the delegate listener
+         *      The delegate listener.
          */
         TunnelCloseListenerAdapter(TunnelCloseListener delegate) {
             this.delegate = delegate;
@@ -237,10 +259,10 @@ class ListenerFactory {
          * to veto the tunnel connect event. All other event types are ignored.
          *
          * @param event
-         *     an object that describes the subject event
+         *     An object that describes the event that occurred.
          *
          * @throws GuacamoleException
-         *      if thrown by the delegate listener
+         *      If thrown by the delegate listener.
          */
         @Override
         public void handleEvent(Object event) throws GuacamoleException {

guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java

@@ -26,24 +26,30 @@ import org.slf4j.LoggerFactory;
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Static factory method for creating provider instances and logging unexpected outcomes
+ * A utility for creating provider instances and logging unexpected outcomes
- * with sufficient detail to allow user/developer debugging.
+ * with sufficient detail to allow debugging.
  */
 class ProviderFactory {
 
+    /**
+     * Logger used to log unexpected outcomes.
+     */
     private static final Logger logger = LoggerFactory.getLogger(ProviderFactory.class);
 
     /**
      * Creates an instance of the specified provider class using the no-arg constructor.
      *
      * @param typeName
-     *      The provider type name used for log messages (e.g. "authentication provider")
+     *      The provider type name used for log messages; e.g. "authentication provider".
+     *
      * @param providerClass
-     *      The provider class to instantiate
+     *      The provider class to instantiate.
+     *
      * @param <T>
-     *      The provider type
+     *      The provider type.
+     *
      * @return
-     *      A provider instance or null if no instance was created due to error
+     *      A provider instance or null if no instance was created due to error.
      */
     static <T> T newInstance(String typeName, Class<? extends T> providerClass) {
         T instance = null;

guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java

@@ -79,7 +79,7 @@ public class AuthenticationService {
     private AuthTokenGenerator authTokenGenerator;
 
     /**
-     * The service to use to notify registered authentication listeners
+     * The service to use to notify registered authentication listeners.
      */
     @Inject
     private ListenerService listenerService;
@@ -222,11 +222,13 @@ public class AuthenticationService {
      * has occurred.
      *
      * @param authenticatedUser
-     *      The user that was successfully authenticated
+     *      The user that was successfully authenticated.
+     *
      * @param session
-     *      Existing session for the user (if any)
+     *      The existing session for the user (if any).
+     *
      * @throws GuacamoleException
-     *      If thrown by a listener
+     *      If thrown by a listener.
      */
     private void fireAuthenticationSuccessEvent(
             AuthenticatedUser authenticatedUser, GuacamoleSession session)
@@ -246,9 +248,10 @@ public class AuthenticationService {
      * Notify all bound listeners that an authentication attempt has failed.
      *
      * @param credentials
-     *      The credentials that failed to authenticate
+     *      The credentials that failed to authenticate.
+     *
      * @throws GuacamoleException
-     *      If thrown by a listener
+     *      If thrown by a listener.
      */
     private void fireAuthenticationFailedEvent(Credentials credentials)
             throws GuacamoleException {

guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java

@@ -30,6 +30,9 @@ import org.apache.guacamole.net.event.listener.Listener;
  */
 public class ListenerService implements Listener {
 
+    /**
+     * The collection of registered listeners.
+     */
     @Inject
     private List<Listener> listeners;
 
@@ -39,9 +42,10 @@ public class ListenerService implements Listener {
      * until all listeners have been notified.
      *
      * @param event
-     *     an object that describes the subject event
+     *      An object that describes the event that has occurred.
      *
-     * @throws GuacamoleException if a registered listener throws a GuacamoleException
+     * @throws GuacamoleException
+     *      If a registered listener throws a GuacamoleException.
      */
     @Override
     public void handleEvent(Object event) throws GuacamoleException {

guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java

@@ -76,13 +76,13 @@ public class TunnelRequestService {
      *      being created.
      *
      * @param credentials
-     *      Credentials that authenticate the user
+     *      Credentials that authenticate the user.
      *
      * @param tunnel
-     *      The tunnel that was connected
+     *      The tunnel that was connected.
      *
      * @throws GuacamoleException
-     *     If thrown by a listener or if any listener vetoes the connected tunnel
+     *     If thrown by a listener or if any listener vetoes the connected tunnel.
      */
     private void fireTunnelConnectEvent(UserContext userContext,
             Credentials credentials, GuacamoleTunnel tunnel) throws GuacamoleException {
@@ -99,10 +99,10 @@ public class TunnelRequestService {
      *      being created.
      *
      * @param credentials
-     *      Credentials that authenticate the user
+     *      Credentials that authenticate the user.
      *
      * @param tunnel
-     *      The tunnel that was connected
+     *      The tunnel that was connected.
      *
      * @throws GuacamoleException
      *     If thrown by a listener.