You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by vn...@apache.org on 2018/04/13 18:36:18 UTC
[3/4] guacamole-client git commit: GUACAMOLE-542: Explicitly document
the behavior of the default implementations provided by AbstractUserContext
and AbstractAuthenticationProvider.
GUACAMOLE-542: Explicitly document the behavior of the default implementations provided by AbstractUserContext and AbstractAuthenticationProvider.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-client/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-client/commit/fa100a88
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-client/tree/fa100a88
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-client/diff/fa100a88
Branch: refs/heads/master
Commit: fa100a888ff28a4cbd0df81bba9102c3e1cf446b
Parents: 57ff8b8
Author: Michael Jumper <mj...@apache.org>
Authored: Wed Apr 11 17:55:39 2018 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Thu Apr 12 14:33:32 2018 -0700
----------------------------------------------------------------------
.../auth/AbstractAuthenticationProvider.java | 78 ++++++++++++-
.../guacamole/net/auth/AbstractUserContext.java | 110 ++++++++++++++++++-
2 files changed, 185 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-client/blob/fa100a88/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java
----------------------------------------------------------------------
diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java
index 991f6a8..81a91d9 100644
--- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java
+++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractAuthenticationProvider.java
@@ -24,35 +24,82 @@ import org.apache.guacamole.GuacamoleException;
/**
* Base implementation of AuthenticationProvider which provides default
* implementations of most functions. Implementations must provide their
- * own {@link getIdentifier()}, but otherwise need only override an implemented
+ * own {@link #getIdentifier()}, but otherwise need only override an implemented
* function if they wish to actually implement the functionality defined for
* that function by the AuthenticationProvider interface.
*/
public abstract class AbstractAuthenticationProvider implements AuthenticationProvider {
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns {@code null}. Implementations that
+ * wish to expose REST resources which are not specific to a user's session
+ * should override this function.
+ */
@Override
public Object getResource() throws GuacamoleException {
return null;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation performs no authentication whatsoever, ignoring
+ * the provided {@code credentials} and simply returning {@code null}. Any
+ * authentication attempt will thus fall through to other
+ * {@link AuthenticationProvider} implementations, perhaps within other
+ * installed extensions, with this {@code AuthenticationProvider} making no
+ * claim regarding the user's identity nor whether the user should be
+ * allowed or disallowed from accessing Guacamole. Implementations that wish
+ * to authenticate users should override this function.
+ */
@Override
public AuthenticatedUser authenticateUser(Credentials credentials)
throws GuacamoleException {
return null;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns the provided
+ * {@code authenticatedUser} without modification. Implementations that
+ * wish to update a user's {@link AuthenticatedUser} object with respect to
+ * new {@link Credentials} received in requests which follow the initial,
+ * successful authentication attempt should override this function.
+ */
@Override
public AuthenticatedUser updateAuthenticatedUser(AuthenticatedUser authenticatedUser,
Credentials credentials) throws GuacamoleException {
return authenticatedUser;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns {@code null}, effectively allowing
+ * authentication to continue but refusing to provide data for the given
+ * user. Implementations that wish to veto the authentication results of
+ * other {@link AuthenticationProvider} implementations or provide data for
+ * authenticated users should override this function.
+ */
@Override
public UserContext getUserContext(AuthenticatedUser authenticatedUser)
throws GuacamoleException {
return null;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns the provided {@code context}
+ * without modification. Implementations that wish to update a user's
+ * {@link UserContext} object with respect to newly-updated
+ * {@link AuthenticatedUser} or {@link Credentials} (such as those received
+ * in requests which follow the initial, successful authentication attempt)
+ * should override this function.
+ */
@Override
public UserContext updateUserContext(UserContext context,
AuthenticatedUser authenticatedUser,
@@ -60,6 +107,15 @@ public abstract class AbstractAuthenticationProvider implements AuthenticationPr
return context;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns the provided {@code context}
+ * without performing any decoration. Implementations that wish to augment
+ * the functionality or data provided by other
+ * {@link AuthenticationProvider} implementations should override this
+ * function.
+ */
@Override
public UserContext decorate(UserContext context,
AuthenticatedUser authenticatedUser,
@@ -67,6 +123,19 @@ public abstract class AbstractAuthenticationProvider implements AuthenticationPr
return context;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply invokes
+ * {@link #decorate(UserContext,AuthenticatedUser,Credentials)} with the
+ * provided {@code context}, {@code authenticatedUser}, and
+ * {@code credentials}. Implementations which override
+ * {@link #decorate(UserContext,AuthenticatedUser,Credentials)} and which
+ * need to update their existing decorated object following possible
+ * updates to the {@link UserContext} or {@link AuthenticatedUser} (rather
+ * than generate an entirely new decorated object) should override this
+ * function.
+ */
@Override
public UserContext redecorate(UserContext decorated, UserContext context,
AuthenticatedUser authenticatedUser,
@@ -74,6 +143,13 @@ public abstract class AbstractAuthenticationProvider implements AuthenticationPr
return decorate(context, authenticatedUser, credentials);
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation does nothing. Implementations that wish to perform
+ * cleanup tasks when the {@link AuthenticationProvider} is being unloaded
+ * should override this function.
+ */
@Override
public void shutdown() {
}
http://git-wip-us.apache.org/repos/asf/guacamole-client/blob/fa100a88/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractUserContext.java
----------------------------------------------------------------------
diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractUserContext.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractUserContext.java
index 25db3d5..e2de612 100644
--- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractUserContext.java
+++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractUserContext.java
@@ -29,8 +29,8 @@ import org.apache.guacamole.net.auth.simple.SimpleDirectory;
/**
* Base implementation of UserContext which provides default implementations of
- * most functions. Implementations must provide their own {@link self()} and
- * {@link getAuthenticationProvider()}, but otherwise need only override an
+ * most functions. Implementations must provide their own {@link #self()} and
+ * {@link #getAuthenticationProvider()}, but otherwise need only override an
* implemented function if they wish to actually implement the functionality
* defined for that function by the UserContext interface.
*/
@@ -42,52 +42,122 @@ public abstract class AbstractUserContext implements UserContext {
*/
protected static final String DEFAULT_ROOT_CONNECTION_GROUP = "ROOT";
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns {@code null}. Implementations that
+ * wish to expose REST resources specific to a user's session should
+ * override this function.
+ */
@Override
public Object getResource() throws GuacamoleException {
return null;
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation returns a {@link Directory} which contains only
+ * the {@link User} returned by {@link #self()} (the current user
+ * associated with this {@link UserContext}. Implementations that wish to
+ * expose the existence of other users should override this function.
+ */
@Override
public Directory<User> getUserDirectory() throws GuacamoleException {
return new SimpleDirectory<User>(self());
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Directory}.
+ * Implementations that wish to expose connections should override this
+ * function.
+ */
@Override
public Directory<Connection> getConnectionDirectory()
throws GuacamoleException {
return new SimpleDirectory<Connection>();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation returns a {@link Directory} which contains only
+ * the root connection group returned by {@link #getRootConnectionGroup()}.
+ * Implementations that wish to provide a structured connection hierarchy
+ * should override this function. If only a flat list of connections will
+ * be used, only {@link #getConnectionDirectory()} needs to be overridden.
+ */
@Override
public Directory<ConnectionGroup> getConnectionGroupDirectory()
throws GuacamoleException {
return new SimpleDirectory<ConnectionGroup>(getRootConnectionGroup());
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Directory}.
+ * Implementations that wish to expose the status of active connections
+ * should override this function.
+ */
@Override
public Directory<ActiveConnection> getActiveConnectionDirectory()
throws GuacamoleException {
return new SimpleDirectory<ActiveConnection>();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Directory}.
+ * Implementations that wish to provide screen sharing functionality
+ * through the use of sharing profiles should override this function.
+ */
@Override
public Directory<SharingProfile> getSharingProfileDirectory()
throws GuacamoleException {
return new SimpleDirectory<SharingProfile>();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link ActivityRecordSet}.
+ * Implementations that wish to expose connection usage history should
+ * override this function.
+ */
@Override
public ActivityRecordSet<ConnectionRecord> getConnectionHistory()
throws GuacamoleException {
return new SimpleActivityRecordSet<ConnectionRecord>();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link ActivityRecordSet}.
+ * Implementations that wish to expose user login/logout history should
+ * override this function.
+ */
@Override
public ActivityRecordSet<ActivityRecord> getUserHistory()
throws GuacamoleException {
return new SimpleActivityRecordSet<ActivityRecord>();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation returns a new {@link ConnectionGroup} with the
+ * identifier defined by {@link #DEFAULT_ROOT_CONNECTION_GROUP} and
+ * containing all connections exposed by the {@link Directory} returned by
+ * {@link #getConnectionDirectory()}. Implementations that wish to provide
+ * a structured connection hierarchy should override this function. If only
+ * a flat list of connections will be used, only
+ * {@link #getConnectionDirectory()} needs to be overridden.
+ */
@Override
public ConnectionGroup getRootConnectionGroup()
throws GuacamoleException {
@@ -99,26 +169,62 @@ public abstract class AbstractUserContext implements UserContext {
);
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Collection}.
+ * Implementations that wish to expose custom user attributes as fields
+ * within user edit screens should override this function.
+ */
@Override
public Collection<Form> getUserAttributes() {
return Collections.<Form>emptyList();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Collection}.
+ * Implementations that wish to expose custom connection attributes as
+ * fields within connection edit screens should override this function.
+ */
@Override
public Collection<Form> getConnectionAttributes() {
return Collections.<Form>emptyList();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Collection}.
+ * Implementations that wish to expose custom connection group attributes
+ * as fields within connection group edit screens should override this
+ * function.
+ */
@Override
public Collection<Form> getConnectionGroupAttributes() {
return Collections.<Form>emptyList();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation simply returns an empty {@link Collection}.
+ * Implementations that wish to expose custom sharing profile attributes as
+ * fields within sharing profile edit screens should override this function.
+ */
@Override
public Collection<Form> getSharingProfileAttributes() {
return Collections.<Form>emptyList();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>This implementation does nothing. Implementations that wish to perform
+ * cleanup tasks when the user associated with this {@link UserContext} is
+ * being logged out should override this function.
+ */
@Override
public void invalidate() {
}