safebox/guacamole-client
4
0
Fork 0
mirror of https://github.com/gyurix1968/guacamole-client.git synced 2025-09-05 20:57:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

GUACAMOLE-364: addressed various documentation issues

Browse Source
This commit is contained in:
Carl Harris
2017-10-06 10:22:10 -04:00
parent 2bdf49205c
commit f8484befaf
12 changed files with 136 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

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

@@ -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;
}

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

@@ -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;
}

2
guacamole/src/main/java/org/apache/guacamole/extension/ExtensionManifest.java
View File

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

10
guacamole/src/main/java/org/apache/guacamole/extension/ExtensionModule.java
View File

@@ -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);
}
/**

58
guacamole/src/main/java/org/apache/guacamole/extension/ListenerFactory.java
View File

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

18
guacamole/src/main/java/org/apache/guacamole/extension/ProviderFactory.java
View File

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

15
guacamole/src/main/java/org/apache/guacamole/rest/auth/AuthenticationService.java
View File

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

8
guacamole/src/main/java/org/apache/guacamole/rest/event/ListenerService.java
View File

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

10
guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequestService.java
View File

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