GUACAMOLE-96: Add API support for augmenting functionality of other extensions.

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AuthenticationProvider.java

@@ -168,6 +168,40 @@ public interface AuthenticationProvider {
             AuthenticatedUser authenticatedUser,
             Credentials credentials) throws GuacamoleException;
 
+    /**
+     * Given a UserContext which originates from a different
+     * AuthenticationProvider, returns a UserContext instance which decorates
+     * (wraps) that UserContext, delegating and overriding implemented
+     * functions as necessary. Each UserContext created via getUserContext()
+     * or updateUserContext() will be passed to the decorate() functions of all
+     * other AuthenticationProviders, allowing those AuthenticationProviders
+     * to augment (or perhaps even limit) the functionality or data provided.
+     *
+     * @param context
+     *     An existing UserContext generated by a different
+     *     AuthenticationProvider.
+     *
+     * @param authenticatedUser
+     *     The AuthenticatedUser object representing the user associated with
+     *     the given UserContext.
+     *
+     * @param credentials
+     *     The credentials which were most recently submitted for the given
+     *     AuthenticatedUser. These are not guaranteed to be the same as the
+     *     credentials associated with the AuthenticatedUser object, which are
+     *     the credentials provided when the user originally authenticated.
+     *
+     * @return
+     *     A decorated (wrapped) UserContext object, or the original,
+     *     undecorated UserContext.
+     *
+     * @throws GuacamoleException
+     *     If the UserContext cannot be decorated due to an error.
+     */
+    UserContext decorate(UserContext context,
+            AuthenticatedUser authenticatedUser,
+            Credentials credentials) throws GuacamoleException;
+
     /**
      * Frees all resources associated with this AuthenticationProvider. This
      * function will be automatically invoked when the Guacamole server is

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/simple/SimpleAuthenticationProvider.java

@@ -260,6 +260,16 @@ public abstract class SimpleAuthenticationProvider
         
     }
 
+    @Override
+    public UserContext decorate(UserContext context,
+            AuthenticatedUser authenticatedUser, Credentials credentials)
+            throws GuacamoleException {
+
+        // Simply return the given context, decorating nothing
+        return context;
+
+    }
+
     @Override
     public void shutdown() {
         // Do nothing