GUAC-800: Provide access via REST to attribute information. Move protocol descriptions into common REST service.

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

@@ -31,9 +31,9 @@ import org.glyptodon.guacamole.net.basic.rest.auth.TokenRESTService;
 import org.glyptodon.guacamole.net.basic.rest.clipboard.ClipboardRESTService;
 import org.glyptodon.guacamole.net.basic.rest.connection.ConnectionRESTService;
 import org.glyptodon.guacamole.net.basic.rest.connectiongroup.ConnectionGroupRESTService;
-import org.glyptodon.guacamole.net.basic.rest.protocol.ProtocolRESTService;
 import org.glyptodon.guacamole.net.basic.rest.activeconnection.ActiveConnectionRESTService;
 import org.glyptodon.guacamole.net.basic.rest.language.LanguageRESTService;
+import org.glyptodon.guacamole.net.basic.rest.schema.SchemaRESTService;
 import org.glyptodon.guacamole.net.basic.rest.user.UserRESTService;
 
 /**
@@ -62,7 +62,7 @@ public class RESTServletModule extends ServletModule {
         bind(ConnectionGroupRESTService.class);
         bind(ConnectionRESTService.class);
         bind(LanguageRESTService.class);
-        bind(ProtocolRESTService.class);
+        bind(SchemaRESTService.class);
         bind(TokenRESTService.class);
         bind(UserRESTService.class);
 

guacamole/src/main/java/org/glyptodon/guacamole/net/basic/rest/protocol/ProtocolRESTService.java

@@ -1,88 +0,0 @@
-/*
- * 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.protocol;
-
-import com.google.inject.Inject;
-import java.util.Map;
-import javax.ws.rs.GET;
-import javax.ws.rs.Path;
-import javax.ws.rs.Produces;
-import javax.ws.rs.QueryParam;
-import javax.ws.rs.core.MediaType;
-import org.glyptodon.guacamole.GuacamoleException;
-import org.glyptodon.guacamole.environment.Environment;
-import org.glyptodon.guacamole.environment.LocalEnvironment;
-import org.glyptodon.guacamole.net.basic.rest.AuthProviderRESTExposure;
-import org.glyptodon.guacamole.net.basic.rest.auth.AuthenticationService;
-import org.glyptodon.guacamole.protocols.ProtocolInfo;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-/**
- * A REST Service for handling the listing of protocols.
- * 
- * @author James Muehlner
- */
-@Path("/protocols")
-@Produces(MediaType.APPLICATION_JSON)
-public class ProtocolRESTService {
-
-    /**
-     * Logger for this class.
-     */
-    private static final Logger logger = LoggerFactory.getLogger(ProtocolRESTService.class);
-    
-    /**
-     * A service for authenticating users from auth tokens.
-     */
-    @Inject
-    private AuthenticationService authenticationService;
-    
-    /**
-     * Gets a map of protocols defined in the system - protocol name to protocol.
-     * 
-     * @param authToken
-     *     The authentication token that is used to authenticate the user
-     *     performing the operation.
-     *
-     * @return
-     *     A map of protocol information, where each key is the unique name
-     *     associated with that protocol.
-     *
-     * @throws GuacamoleException
-     *     If an error occurs while retrieving the available protocols.
-     */
-    @GET
-    @AuthProviderRESTExposure
-    public Map<String, ProtocolInfo> getProtocols(@QueryParam("token") String authToken) throws GuacamoleException {
-        
-        // Verify the given auth token is valid
-        authenticationService.getUserContext(authToken);
-
-        // Get and return a map of all protocols.
-        Environment env = new LocalEnvironment();
-        return env.getProtocols();
-
-    }
-
-}

guacamole/src/main/java/org/glyptodon/guacamole/net/basic/rest/schema/SchemaRESTService.java

@@ -0,0 +1,163 @@
+/*
+ * Copyright (C) 2015 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.schema;
+
+import com.google.inject.Inject;
+import java.util.Collection;
+import java.util.Map;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.MediaType;
+import org.glyptodon.guacamole.GuacamoleException;
+import org.glyptodon.guacamole.environment.Environment;
+import org.glyptodon.guacamole.environment.LocalEnvironment;
+import org.glyptodon.guacamole.form.Parameter;
+import org.glyptodon.guacamole.net.auth.UserContext;
+import org.glyptodon.guacamole.net.basic.rest.AuthProviderRESTExposure;
+import org.glyptodon.guacamole.net.basic.rest.auth.AuthenticationService;
+import org.glyptodon.guacamole.protocols.ProtocolInfo;
+
+/**
+ * A REST service which provides access to descriptions of the properties,
+ * attributes, etc. of objects used within the Guacamole REST API.
+ *
+ * @author Michael Jumper
+ */
+@Path("/schema")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class SchemaRESTService {
+
+    /**
+     * A service for authenticating users from auth tokens.
+     */
+    @Inject
+    private AuthenticationService authenticationService;
+
+    /**
+     * Retrieves the possible attributes of a user object.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @return
+     *     A collection of form parameters which describe the possible
+     *     attributes of a user object.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while retrieving the possible attributes.
+     */
+    @GET
+    @Path("/users/attributes")
+    @AuthProviderRESTExposure
+    public Collection<Parameter> getUserAttributes(@QueryParam("token") String authToken) throws GuacamoleException {
+
+        // Retrieve all possible user attributes
+        UserContext userContext = authenticationService.getUserContext(authToken);
+        return userContext.getUserAttributes();
+
+    }
+
+    /**
+     * Retrieves the possible attributes of a connection object.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @return
+     *     A collection of form parameters which describe the possible
+     *     attributes of a connection object.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while retrieving the possible attributes.
+     */
+    @GET
+    @Path("/connections/attributes")
+    @AuthProviderRESTExposure
+    public Collection<Parameter> getConnectionAttributes(@QueryParam("token") String authToken) throws GuacamoleException {
+
+        // Retrieve all possible connection attributes
+        UserContext userContext = authenticationService.getUserContext(authToken);
+        return userContext.getConnectionAttributes();
+
+    }
+
+    /**
+     * Retrieves the possible attributes of a connection group object.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @return
+     *     A collection of form parameters which describe the possible
+     *     attributes of a connection group object.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while retrieving the possible attributes.
+     */
+    @GET
+    @Path("/connectionGroups/attributes")
+    @AuthProviderRESTExposure
+    public Collection<Parameter> getConnectionGroupAttributes(@QueryParam("token") String authToken) throws GuacamoleException {
+
+        // Retrieve all possible connection group attributes
+        UserContext userContext = authenticationService.getUserContext(authToken);
+        return userContext.getConnectionGroupAttributes();
+
+    }
+
+    /**
+     * Gets a map of protocols defined in the system - protocol name to protocol.
+     *
+     * @param authToken
+     *     The authentication token that is used to authenticate the user
+     *     performing the operation.
+     *
+     * @return
+     *     A map of protocol information, where each key is the unique name
+     *     associated with that protocol.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while retrieving the available protocols.
+     */
+    @GET
+    @Path("/protocols")
+    @AuthProviderRESTExposure
+    public Map<String, ProtocolInfo> getProtocols(@QueryParam("token") String authToken) throws GuacamoleException {
+
+        // Verify the given auth token is valid
+        authenticationService.getUserContext(authToken);
+
+        // Get and return a map of all protocols.
+        Environment env = new LocalEnvironment();
+        return env.getProtocols();
+
+    }
+
+}

guacamole/src/main/java/org/glyptodon/guacamole/net/basic/rest/schema/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Glyptodon LLC
+ * Copyright (C) 2015 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
@@ -21,7 +21,7 @@
  */
 
 /**
- * Classes related to the protocol retrieval aspect of the Guacamole REST API.
+ * Classes related to the self-description of the Guacamole REST API, such as
+ * the attributes or parameters applicable to specific objects.
  */
-package org.glyptodon.guacamole.net.basic.rest.protocol;
+package org.glyptodon.guacamole.net.basic.rest.schema;
-

guacamole/src/main/webapp/app/manage/controllers/manageConnectionController.js

@@ -41,7 +41,7 @@ angular.module('manage').controller('manageConnectionController', ['$scope', '$i
     var connectionService        = $injector.get('connectionService');
     var connectionGroupService   = $injector.get('connectionGroupService');
     var permissionService        = $injector.get('permissionService');
-    var protocolService          = $injector.get('protocolService');
+    var schemaService            = $injector.get('schemaService');
     var translationStringService = $injector.get('translationStringService');
 
     /**
@@ -205,7 +205,7 @@ angular.module('manage').controller('manageConnectionController', ['$scope', '$i
     });
    
     // Get protocol metadata
-    protocolService.getProtocols().success(function protocolsReceived(protocols) {
+    schemaService.getProtocols().success(function protocolsReceived(protocols) {
         $scope.protocols = protocols;
     });
 

guacamole/src/main/webapp/app/rest/services/cacheService.js

@@ -49,11 +49,11 @@ angular.module('rest').factory('cacheService', ['$injector',
     service.languages = $cacheFactory('API-LANGUAGES');
 
     /**
-     * Cache used by protocolService.
+     * Cache used by schemaService.
      *
      * @type $cacheFactory.Cache
      */
-    service.protocols = $cacheFactory('API-PROTOCOLS');
+    service.schema = $cacheFactory('API-SCHEMA');
 
     /**
      * Shared cache used by both userService and permissionService.
@@ -68,7 +68,7 @@ angular.module('rest').factory('cacheService', ['$injector',
     service.clearCaches = function clearCaches() {
         service.connections.removeAll();
         service.languages.removeAll();
-        service.protocols.removeAll();
+        service.schema.removeAll();
         service.users.removeAll();
     };
 

guacamole/src/main/webapp/app/rest/services/protocolService.js

@@ -1,64 +0,0 @@
-/*
- * 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.
- */
-
-/**
- * Service for operating on protocol metadata via the REST API.
- */
-angular.module('rest').factory('protocolService', ['$injector',
-        function protocolService($injector) {
-
-    // Required services
-    var $http                 = $injector.get('$http');
-    var authenticationService = $injector.get('authenticationService');
-    var cacheService          = $injector.get('cacheService');
-
-    var service = {};
-    
-    /**
-     * Makes a request to the REST API to get the list of protocols, returning
-     * a promise that provides a map of @link{Protocol} objects by protocol
-     * name if successful.
-     *                          
-     * @returns {Promise.<Object.<String, Protocol>>}
-     *     A promise which will resolve with a map of @link{Protocol}
-     *     objects by protocol name upon success.
-     */
-    service.getProtocols = function getProtocols() {
-
-        // Build HTTP parameters set
-        var httpParameters = {
-            token : authenticationService.getCurrentToken()
-        };
-
-        // Retrieve available protocols
-        return $http({
-            cache   : cacheService.protocols,
-            method  : 'GET',
-            url     : 'api/protocols',
-            params  : httpParameters
-        });
-
-    };
-    
-    return service;
-
-}]);

guacamole/src/main/webapp/app/rest/services/schemaService.js

@@ -0,0 +1,145 @@
+/*
+ * Copyright (C) 2015 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.
+ */
+
+/**
+ * Service for operating on metadata via the REST API.
+ */
+angular.module('rest').factory('schemaService', ['$injector',
+        function schemaService($injector) {
+
+    // Required services
+    var $http                 = $injector.get('$http');
+    var authenticationService = $injector.get('authenticationService');
+    var cacheService          = $injector.get('cacheService');
+
+    var service = {};
+
+    /**
+     * Makes a request to the REST API to get the list of available attributes
+     * for user objects, returning a promise that provides an array of
+     * @link{Field} objects if successful. Each element of the array describes
+     * a possible attribute.
+     *
+     * @returns {Promise.<Field[]>}
+     *     A promise which will resolve with an array of @link{Field}
+     *     objects, where each @link{Field} describes a possible attribute.
+     */
+    service.getUserAttributes = function getUserAttributes() {
+
+        // Build HTTP parameters set
+        var httpParameters = {
+            token : authenticationService.getCurrentToken()
+        };
+
+        // Retrieve available user attributes
+        return $http({
+            cache   : cacheService.schema,
+            method  : 'GET',
+            url     : 'api/schema/users/attributes',
+            params  : httpParameters
+        });
+
+    };
+
+    /**
+     * Makes a request to the REST API to get the list of available attributes
+     * for connection objects, returning a promise that provides an array of
+     * @link{Field} objects if successful. Each element of the array describes
+     * a possible attribute.
+     *
+     * @returns {Promise.<Field[]>}
+     *     A promise which will resolve with an array of @link{Field}
+     *     objects, where each @link{Field} describes a possible attribute.
+     */
+    service.getConnectionAttributes = function getConnectionAttributes() {
+
+        // Build HTTP parameters set
+        var httpParameters = {
+            token : authenticationService.getCurrentToken()
+        };
+
+        // Retrieve available connection attributes
+        return $http({
+            cache   : cacheService.schema,
+            method  : 'GET',
+            url     : 'api/schema/connections/attributes',
+            params  : httpParameters
+        });
+
+    };
+
+    /**
+     * Makes a request to the REST API to get the list of available attributes
+     * for connection group objects, returning a promise that provides an array
+     * of @link{Field} objects if successful. Each element of the array
+     * describes a possible attribute.
+     *
+     * @returns {Promise.<Field[]>}
+     *     A promise which will resolve with an array of @link{Field}
+     *     objects, where each @link{Field} describes a possible attribute.
+     */
+    service.getConnectionGroupAttributes = function getConnectionGroupAttributes() {
+
+        // Build HTTP parameters set
+        var httpParameters = {
+            token : authenticationService.getCurrentToken()
+        };
+
+        // Retrieve available connection group attributes
+        return $http({
+            cache   : cacheService.schema,
+            method  : 'GET',
+            url     : 'api/schema/connectionGroups/attributes',
+            params  : httpParameters
+        });
+
+    };
+
+    /**
+     * Makes a request to the REST API to get the list of protocols, returning
+     * a promise that provides a map of @link{Protocol} objects by protocol
+     * name if successful.
+     *
+     * @returns {Promise.<Object.<String, Protocol>>}
+     *     A promise which will resolve with a map of @link{Protocol}
+     *     objects by protocol name upon success.
+     */
+    service.getProtocols = function getProtocols() {
+
+        // Build HTTP parameters set
+        var httpParameters = {
+            token : authenticationService.getCurrentToken()
+        };
+
+        // Retrieve available protocols
+        return $http({
+            cache   : cacheService.schema,
+            method  : 'GET',
+            url     : 'api/schema/protocols',
+            params  : httpParameters
+        });
+
+    };
+
+    return service;
+
+}]);