GUAC-586: Add convenience methods for retrieving objects directly from session.

guacamole/src/main/java/org/glyptodon/guacamole/net/basic/rest/ObjectRetrievalService.java

@@ -25,6 +25,7 @@ package org.glyptodon.guacamole.net.basic.rest;
 import java.util.List;
 import org.glyptodon.guacamole.GuacamoleException;
 import org.glyptodon.guacamole.GuacamoleResourceNotFoundException;
+import org.glyptodon.guacamole.net.auth.AuthenticationProvider;
 import org.glyptodon.guacamole.net.auth.Connection;
 import org.glyptodon.guacamole.net.auth.ConnectionGroup;
 import org.glyptodon.guacamole.net.auth.Directory;
@@ -48,7 +49,7 @@ public class ObjectRetrievalService {
      * @param session
      *     The GuacamoleSession to retrieve the UserContext from.
      *
-     * @param identifier
+     * @param authProviderIdentifier
      *     The unique identifier of the AuthenticationProvider that created the
      *     UserContext being retrieved. Only one UserContext per
      *     AuthenticationProvider can exist.
@@ -62,7 +63,7 @@ public class ObjectRetrievalService {
      *     UserContext does not exist.
      */
     public UserContext retrieveUserContext(GuacamoleSession session,
-            String identifier) throws GuacamoleException {
+            String authProviderIdentifier) throws GuacamoleException {
 
         // Get list of UserContexts
         List<UserContext> userContexts = session.getUserContexts();
@@ -70,11 +71,17 @@ public class ObjectRetrievalService {
         // Locate and return the UserContext associated with the
         // AuthenticationProvider having the given identifier, if any
         for (UserContext userContext : userContexts) {
-            if (userContext.getAuthenticationProvider().getIdentifier().equals(identifier))
+
+            // Get AuthenticationProvider associated with current UserContext
+            AuthenticationProvider authProvider = userContext.getAuthenticationProvider();
+
+            // If AuthenticationProvider identifier matches, done
+            if (authProvider.getIdentifier().equals(authProviderIdentifier))
                 return userContext;
+
         }
 
-        throw new GuacamoleResourceNotFoundException("Session not associated with authentication provider \"" + identifier + "\".");
+        throw new GuacamoleResourceNotFoundException("Session not associated with authentication provider \"" + authProviderIdentifier + "\".");
 
     }
 
@@ -109,6 +116,35 @@ public class ObjectRetrievalService {
 
     }
 
+    /**
+     * Retrieves a single user from the given GuacamoleSession.
+     *
+     * @param session
+     *     The GuacamoleSession to retrieve the user from.
+     *
+     * @param authProviderIdentifier
+     *     The unique identifier of the AuthenticationProvider that created the
+     *     UserContext from which the user should be retrieved. Only one
+     *     UserContext per AuthenticationProvider can exist.
+     *
+     * @param identifier
+     *     The identifier of the user to retrieve.
+     *
+     * @return
+     *     The user having the given identifier.
+     *
+     * @throws GuacamoleException 
+     *     If an error occurs while retrieving the user, or if the
+     *     user does not exist.
+     */
+    public User retrieveUser(GuacamoleSession session, String authProviderIdentifier,
+            String identifier) throws GuacamoleException {
+
+        UserContext userContext = retrieveUserContext(session, authProviderIdentifier);
+        return retrieveUser(userContext, identifier);
+
+    }
+
     /**
      * Retrieves a single connection from the given user context.
      *
@@ -140,6 +176,36 @@ public class ObjectRetrievalService {
 
     }
 
+    /**
+     * Retrieves a single connection from the given GuacamoleSession.
+     *
+     * @param session
+     *     The GuacamoleSession to retrieve the connection from.
+     *
+     * @param authProviderIdentifier
+     *     The unique identifier of the AuthenticationProvider that created the
+     *     UserContext from which the connection should be retrieved. Only one
+     *     UserContext per AuthenticationProvider can exist.
+     *
+     * @param identifier
+     *     The identifier of the connection to retrieve.
+     *
+     * @return
+     *     The connection having the given identifier.
+     *
+     * @throws GuacamoleException 
+     *     If an error occurs while retrieving the connection, or if the
+     *     connection does not exist.
+     */
+    public Connection retrieveConnection(GuacamoleSession session,
+            String authProviderIdentifier, String identifier)
+            throws GuacamoleException {
+
+        UserContext userContext = retrieveUserContext(session, authProviderIdentifier);
+        return retrieveConnection(userContext, identifier);
+
+    }
+
     /**
      * Retrieves a single connection group from the given user context. If
      * the given identifier the REST API root identifier, the root connection
@@ -178,4 +244,37 @@ public class ObjectRetrievalService {
 
     }
 
+    /**
+     * Retrieves a single connection group from the given GuacamoleSession. If
+     * the given identifier the REST API root identifier, the root connection
+     * group will be returned. The underlying authentication provider may
+     * additionally use a different identifier for root.
+     *
+     * @param session
+     *     The GuacamoleSession to retrieve the connection group from.
+     *
+     * @param authProviderIdentifier
+     *     The unique identifier of the AuthenticationProvider that created the
+     *     UserContext from which the connection group should be retrieved.
+     *     Only one UserContext per AuthenticationProvider can exist.
+     *
+     * @param identifier
+     *     The identifier of the connection group to retrieve.
+     *
+     * @return
+     *     The connection group having the given identifier, or the root
+     *     connection group if the identifier the root identifier.
+     *
+     * @throws GuacamoleException 
+     *     If an error occurs while retrieving the connection group, or if the
+     *     connection group does not exist.
+     */
+    public ConnectionGroup retrieveConnectionGroup(GuacamoleSession session,
+            String authProviderIdentifier, String identifier) throws GuacamoleException {
+
+        UserContext userContext = retrieveUserContext(session, authProviderIdentifier);
+        return retrieveConnectionGroup(userContext, identifier);
+
+    }
+
 }

guacamole/src/main/java/org/glyptodon/guacamole/net/basic/rest/auth/APIAuthenticationResponse.java

@@ -0,0 +1,105 @@
+/*
+ * Copyright (C) 2014 Glyptodon LLC
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package org.glyptodon.guacamole.net.basic.rest.auth;
+
+/**
+ * A simple object to represent an auth token/username pair in the API.
+ * 
+ * @author James Muehlner
+ */
+public class APIAuthenticationResponse {
+    
+    /**
+     * The auth token.
+     */
+    private final String authToken;
+    
+    
+    /**
+     * The username of the user that authenticated.
+     */
+    private final String username;
+
+    /**
+     * The unique identifier of the data source from which this user account
+     * came. Although this user account may exist across several data sources
+     * (AuthenticationProviders), this will be the unique identifier of the
+     * AuthenticationProvider that authenticated this user for the current
+     * session.
+     */
+    private final String dataSource;
+
+    /**
+     * Returns the unique authentication token which identifies the current
+     * session.
+     *
+     * @return
+     *     The user's authentication token.
+     */
+    public String getAuthToken() {
+        return authToken;
+    }
+    
+    /**
+     * Returns the user identified by the authentication token associated with
+     * the current session.
+     *
+     * @return
+     *      The user identified by this authentication token.
+     */
+    public String getUsername() {
+        return username;
+    }
+
+    /**
+     * Returns the unique identifier of the data source associated with the user
+     * account associated with this auth token.
+     * 
+     * @return 
+     *     The unique identifier of the data source associated with the user
+     *     account associated with this auth token.
+     */
+    public String getDataSource() {
+        return dataSource;
+    }
+    
+    /**
+     * Create a new APIAuthToken Object with the given auth token.
+     *
+     * @param dataSource
+     *     The unique identifier of the AuthenticationProvider which
+     *     authenticated the user.
+     *
+     * @param authToken
+     *     The auth token to create the new APIAuthToken with.
+     *
+     * @param username
+     *     The username of the user owning the given token.
+     */
+    public APIAuthenticationResponse(String dataSource, String authToken, String username) {
+        this.dataSource = dataSource;
+        this.authToken = authToken;
+        this.username = username;
+    }
+
+}