GUACAMOLE-364: addressed various documentation issues
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/commit/f8484bef Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/tree/f8484bef Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/diff/f8484bef Branch: refs/heads/master Commit: f8484befaf44fb0e7dfad80a3a07ca96e0f2d959 Parents: 2bdf492 Author: Carl Harris <[email protected]> Authored: Fri Oct 6 10:22:10 2017 -0400 Committer: Carl Harris <[email protected]> Committed: Fri Oct 6 10:22:10 2017 -0400 ---------------------------------------------------------------------- .../listener/AuthenticationFailureListener.java | 17 +++--- .../listener/AuthenticationSuccessListener.java | 21 ++++--- .../guacamole/net/event/listener/Listener.java | 4 +- .../net/event/listener/TunnelCloseListener.java | 25 +++++---- .../event/listener/TunnelConnectListener.java | 37 +++++++------ .../guacamole/extension/ExtensionManifest.java | 2 +- .../guacamole/extension/ExtensionModule.java | 10 ++-- .../guacamole/extension/ListenerFactory.java | 58 ++++++++++++++------ .../guacamole/extension/ProviderFactory.java | 18 ++++-- .../rest/auth/AuthenticationService.java | 15 +++-- .../guacamole/rest/event/ListenerService.java | 8 ++- .../guacamole/tunnel/TunnelRequestService.java | 10 ++-- 12 files changed, 136 insertions(+), 89 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java ---------------------------------------------------------------------- diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java index 1971af8..6e707e6 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java +++ b/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 - * 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; http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java ---------------------------------------------------------------------- diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java index 77a6ed1..29be27c 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java +++ b/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; http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java ---------------------------------------------------------------------- diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java index d21f686..af480b7 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java +++ b/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; http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java ---------------------------------------------------------------------- diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java index 70677b3..82da725 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java +++ b/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 - * 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; } http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java ---------------------------------------------------------------------- diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java index edc144e..e224f74 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java +++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java @@ -27,27 +27,30 @@ 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 { /** - * 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; } http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java b/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java index 1636b03..054d9ef 100644 --- a/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java +++ b/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; http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java b/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java index e7cdedb..a74c4c0 100644 --- a/guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java +++ b/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); } /** http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java b/guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java index c11f00f..8aa6bab 100644 --- a/guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java +++ b/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 { http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java b/guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java index 376b213..01fda57 100644 --- a/guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java +++ b/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 - * 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; http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java b/guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java index bdefc3e..b18f00f 100644 --- a/guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java +++ b/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 { http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java b/guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java index bbff8ee..e92cc8a 100644 --- a/guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java +++ b/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 { http://git-wip-us.apache.org/repos/asf/incubator-guacamole-client/blob/f8484bef/guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java ---------------------------------------------------------------------- diff --git a/guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java b/guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java index d3543d7..b029a30 100644 --- a/guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java +++ b/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.
