GUACAMOLE-364: addressed various documentation issues

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

@@ -28,7 +28,7 @@
  * 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
-     *          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

@@ -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
-     *          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

@@ -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 @@
  * 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
-     *          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

@@ -27,27 +27,30 @@
  * tunnel is connected.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      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;
 
 }

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

@@ -380,7 +380,7 @@ public Collection<String> getListeners() {
      * 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 List<AuthenticationProvider> getAuthenticationProviders() {
      * 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 @@ private void bindListeners(Collection<Class<?>> listeners) {
 
         // 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 @@ static List<Listener> createListeners(Class<?> providerClass) {
 
     }
 
+    /**
+     * 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 @@ private static List<Listener> createListenerAdapters(Object provider) {
     @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 @@ private static class AuthenticationSuccessListenerAdapter implements Listener {
          * 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 @@ public void handleEvent(Object event) throws GuacamoleException {
     @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 @@ private static class AuthenticationFailureListenerAdapter implements Listener {
          * 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 @@ public void handleEvent(Object event) throws GuacamoleException {
     @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 @@ private static class TunnelConnectListenerAdapter implements Listener {
          * 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 @@ public void handleEvent(Object event) throws GuacamoleException {
     @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 @@ private static class TunnelCloseListenerAdapter implements Listener {
          * 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 java.lang.reflect.InvocationTargetException;
 
 /**
- * Static factory method for creating provider instances and logging unexpected outcomes
- * with sufficient detail to allow user/developer debugging.
+ * A utility for creating provider instances and logging unexpected outcomes
+ * 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;