GUACAMOLE-641: Allow TokenInjecting* implementations to consider values of existing tokens.

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

@@ -29,7 +29,9 @@ import org.apache.guacamole.protocol.GuacamoleClientInformation;
 /**
  * Connection implementation which overrides the connect() function of an
  * underlying Connection, adding a given set of parameter tokens to the tokens
- * already supplied.
+ * already supplied. If not supplying a static set of tokens at construction
+ * time, implementations should override either {@link #addTokens(java.util.Map)}
+ * or {@link #getTokens()} to provide tokens dynamically.
  */
 public class TokenInjectingConnection extends DelegatingConnection {
 
@@ -41,7 +43,9 @@ public class TokenInjectingConnection extends DelegatingConnection {
     /**
      * Returns the tokens which should be added to an in-progress call to
      * connect(). If not overridden, this function will return the tokens
-     * provided when this instance of TokenInjectingConnection was created.
+     * provided when this instance of TokenInjectingConnection was created. If
+     * the values of existing tokens need to be considered, implementations
+     * should override {@link #addTokens(java.util.Map)} instead.
      *
      * @return
      *     The tokens which should be added to the in-progress call to
@@ -54,6 +58,21 @@ public class TokenInjectingConnection extends DelegatingConnection {
         return tokens;
     }
 
+    /**
+     * Adds tokens to an in-progress call to connect(). If not overridden, this
+     * function will add the tokens returned by {@link #getTokens()}.
+     *
+     * @param tokens
+     *     A modifiable Map containing the tokens already supplied to
+     *     connect().
+     *
+     * @throws GuacamoleException
+     *     If the applicable tokens cannot be generated.
+     */
+    protected void addTokens(Map<String, String> tokens) throws GuacamoleException {
+        tokens.putAll(getTokens());
+    }
+
     /**
      * Wraps the given Connection, automatically adding the given tokens to
      * each invocation of connect(). Any additional tokens which have the same
@@ -73,7 +92,8 @@ public class TokenInjectingConnection extends DelegatingConnection {
 
     /**
      * Wraps the given Connection such that the additional parameter tokens
-     * returned by getTokens() are included with each invocation of connect().
+     * added by {@link #addTokens(java.util.Map)} or returned by
+     * {@link #getTokens()} are included with each invocation of connect().
      * Any additional tokens which have the same name as existing tokens will
      * override the existing values.
      *
@@ -90,7 +110,7 @@ public class TokenInjectingConnection extends DelegatingConnection {
 
         // Apply provided tokens over those given to connect()
         tokens = new HashMap<>(tokens);
-        tokens.putAll(getTokens());
+        addTokens(tokens);
 
         return super.connect(info, tokens);
 

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

@@ -29,7 +29,10 @@ import org.apache.guacamole.protocol.GuacamoleClientInformation;
 /**
  * ConnectionGroup implementation which overrides the connect() function of an
  * underlying ConnectionGroup, adding a given set of parameter tokens to the
- * tokens already supplied.
+ * tokens already supplied. If not supplying a static set of tokens at
+ * construction time, implementations should override either
+ * {@link #addTokens(java.util.Map)} or {@link #getTokens()} to provide tokens
+ * dynamically.
  */
 public class TokenInjectingConnectionGroup extends DelegatingConnectionGroup {
 
@@ -41,8 +44,9 @@ public class TokenInjectingConnectionGroup extends DelegatingConnectionGroup {
     /**
      * Returns the tokens which should be added to an in-progress call to
      * connect(). If not overridden, this function will return the tokens
-     * provided when this instance of TokenInjectingConnectionGroup was
-     * created.
+     * provided when this instance of TokenInjectingConnection was created. If
+     * the values of existing tokens need to be considered, implementations
+     * should override {@link #addTokens(java.util.Map)} instead.
      *
      * @return
      *     The tokens which should be added to the in-progress call to
@@ -55,6 +59,21 @@ public class TokenInjectingConnectionGroup extends DelegatingConnectionGroup {
         return tokens;
     }
 
+    /**
+     * Adds tokens to an in-progress call to connect(). If not overridden, this
+     * function will add the tokens returned by {@link #getTokens()}.
+     *
+     * @param tokens
+     *     A modifiable Map containing the tokens already supplied to
+     *     connect().
+     *
+     * @throws GuacamoleException
+     *     If the applicable tokens cannot be generated.
+     */
+    protected void addTokens(Map<String, String> tokens) throws GuacamoleException {
+        tokens.putAll(getTokens());
+    }
+
     /**
      * Wraps the given ConnectionGroup, automatically adding the given tokens
      * to each invocation of connect(). Any additional tokens which have the
@@ -74,9 +93,10 @@ public class TokenInjectingConnectionGroup extends DelegatingConnectionGroup {
 
     /**
      * Wraps the given ConnectionGroup such that the additional parameter
-     * tokens returned by getTokens() are included with each invocation of
-     * connect(). Any additional tokens which have the same name as existing
-     * tokens will override the existing values.
+     * tokens added by {@link #addTokens(java.util.Map)} or returned by
+     * {@link #getTokens()} are included with each invocation of connect(). Any
+     * additional tokens which have the same name as existing tokens will
+     * override the existing values.
      *
      * @param connectionGroup
      *     The ConnectionGroup to wrap.
@@ -91,7 +111,7 @@ public class TokenInjectingConnectionGroup extends DelegatingConnectionGroup {
 
         // Apply provided tokens over those given to connect()
         tokens = new HashMap<>(tokens);
-        tokens.putAll(getTokens());
+        addTokens(tokens);
 
         return super.connect(info, tokens);
 

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

@@ -32,7 +32,7 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
 
     /**
      * The additional tokens to include with each call to connect() if
-     * getTokens() is not overridden.
+     * getTokens() or addTokens() are not overridden.
      */
     private final Map<String, String> tokens;
 
@@ -42,8 +42,8 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
      * parameter tokens are included. Any additional tokens which have the same
      * name as existing tokens will override the existing values. If tokens
      * specific to a particular connection or connection group need to be
-     * included, getTokens() may be overridden to provide a different set of
-     * tokens.
+     * included, getTokens() or addTokens() may be overridden to provide a
+     * different set of tokens.
      *
      * @param userContext
      *     The UserContext to wrap.
@@ -60,9 +60,9 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
     /**
      * Wraps the given UserContext, overriding the connect() function of each
      * retrieved Connection and ConnectionGroup such that the additional
-     * parameter tokens returned by getTokens() are included. Any additional
-     * tokens which have the same name as existing tokens will override the
-     * existing values.
+     * parameter tokens added by addTokens() or returned by getTokens() are
+     * included. Any additional tokens which have the same name as existing
+     * tokens will override the existing values.
      *
      * @param userContext
      *     The UserContext to wrap.
@@ -75,7 +75,10 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
      * Returns the tokens which should be added to an in-progress call to
      * connect() for the given Connection. If not overridden, this function
      * will return the tokens provided when this instance of
-     * TokenInjectingUserContext was created.
+     * TokenInjectingUserContext was created. If the values of existing tokens
+     * need to be considered, implementations should override
+     * {@link #addTokens(org.apache.guacamole.net.auth.Connection, java.util.Map)}
+     * instead.
      *
      * @param connection
      *     The Connection on which connect() has been called.
@@ -93,11 +96,35 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
         return tokens;
     }
 
+    /**
+     * Adds tokens to an in-progress call to connect() for the given
+     * Connection. If not overridden, this function will add the tokens
+     * returned by {@link #getTokens(org.apache.guacamole.net.auth.Connection)}.
+     *
+     * @param connection
+     *     The Connection on which connect() has been called.
+     *
+     * @param tokens
+     *     A modifiable Map containing the tokens already supplied to
+     *     connect().
+     *
+     * @throws GuacamoleException
+     *     If the tokens applicable to the given connection cannot be
+     *     generated.
+     */
+    protected void addTokens(Connection connection, Map<String, String> tokens)
+            throws GuacamoleException {
+        tokens.putAll(getTokens(connection));
+    }
+
     /**
      * Returns the tokens which should be added to an in-progress call to
      * connect() for the given ConnectionGroup. If not overridden, this
      * function will return the tokens provided when this instance of
-     * TokenInjectingUserContext was created.
+     * TokenInjectingUserContext was created. If the values of existing tokens
+     * need to be considered, implementations should override
+     * {@link #addTokens(org.apache.guacamole.net.auth.ConnectionGroup, java.util.Map)}
+     * instead.
      *
      * @param connectionGroup
      *     The ConnectionGroup on which connect() has been called.
@@ -115,6 +142,27 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
         return tokens;
     }
 
+    /**
+     * Adds tokens to an in-progress call to connect() for the given
+     * ConnectionGroup. If not overridden, this function will add the tokens
+     * returned by {@link #getTokens(org.apache.guacamole.net.auth.ConnectionGroup)}.
+     *
+     * @param connectionGroup
+     *     The ConnectionGroup on which connect() has been called.
+     *
+     * @param tokens
+     *     A modifiable Map containing the tokens already supplied to
+     *     connect().
+     *
+     * @throws GuacamoleException
+     *     If the tokens applicable to the given connection cannot be
+     *     generated.
+     */
+    protected void addTokens(ConnectionGroup connectionGroup,
+            Map<String, String> tokens) throws GuacamoleException {
+        tokens.putAll(getTokens(connectionGroup));
+    }
+
     @Override
     public Directory<ConnectionGroup> getConnectionGroupDirectory()
             throws GuacamoleException {
@@ -125,8 +173,8 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
                 return new TokenInjectingConnectionGroup(object) {
 
                     @Override
-                    protected Map<String, String> getTokens() throws GuacamoleException {
-                        return TokenInjectingUserContext.this.getTokens(object);
+                    protected void addTokens(Map<String, String> tokens) throws GuacamoleException {
+                        TokenInjectingUserContext.this.addTokens(object, tokens);
                     }
 
                 };
@@ -150,8 +198,8 @@ public class TokenInjectingUserContext extends DelegatingUserContext {
                 return new TokenInjectingConnection(object) {
 
                     @Override
-                    protected Map<String, String> getTokens() throws GuacamoleException {
-                        return TokenInjectingUserContext.this.getTokens(object);
+                    protected void addTokens(Map<String, String> tokens) throws GuacamoleException {
+                        TokenInjectingUserContext.this.addTokens(object, tokens);
                     }
 
                 };