GUACAMOLE-542: Explicitly document the behavior of the default implementations provided by AbstractUserContext and AbstractAuthenticationProvider.

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() {
     }

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
+ * most functions. Implementations must provide their own {@link #self()} and
- * {@link getAuthenticationProvider()}, but otherwise need only override an
+ * {@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() {
     }