GUAC-932: Add types for all JSON responses. Ensure default values are documented.

guacamole/src/main/webapp/app/rest/types/Connection.js

@@ -75,6 +75,7 @@ angular.module('rest').factory('Connection', [function defineConnection() {
          * associated users.
          *
          * @type ConnectionHistoryEntry[]
+         * @default []
          */
         this.history = template.history || [];
 
@@ -86,6 +87,7 @@ angular.module('rest').factory('Connection', [function defineConnection() {
          * read and use the connection.
          *
          * @type Object.<String, String>
+         * @default {}
          */
         this.parameters = template.parameters || {};
 

guacamole/src/main/webapp/app/rest/types/ConnectionGroup.js

@@ -0,0 +1,109 @@
+/*
+ * 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 which defines the ConnectionGroup class.
+ */
+angular.module('rest').factory('ConnectionGroup', [function defineConnectionGroup() {
+            
+    /**
+     * The object returned by REST API calls when representing the data
+     * associated with a connection group.
+     * 
+     * @constructor
+     * @param {ConnectionGroup|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     ConnectionGroup.
+     */
+    var ConnectionGroup = function ConnectionGroup(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * The unique identifier associated with this connection group.
+         *
+         * @type String
+         */
+        this.identifier = template.identifier;
+
+        /**
+         * The unique identifier of the connection group that contains this
+         * connection group.
+         * 
+         * @type String
+         * @default ConnectionGroup.ROOT_IDENTIFIER
+         */
+        this.parentIdentifier = template.parentIdentifier || ConnectionGroup.ROOT_IDENTIFIER;
+
+        /**
+         * The human-readable name of this connection group, which is not
+         * necessarily unique.
+         * 
+         * @type String
+         */
+        this.name = template.name;
+
+        /**
+         * The type of this connection group, which may be either
+         * ConnectionGroup.Type.ORGANIZATIONAL or
+         * ConnectionGroup.Type.BALANCING.
+         * 
+         * @type String
+         * @default ConnectionGroup.Type.ORGANIZATIONAL
+         */
+        this.type = template.type || ConnectionGroup.Type.ORGANIZATIONAL;
+
+    };
+
+    /**
+     * The reserved identifier which always represents the root connection
+     * group.
+     * 
+     * @type String
+     */
+    ConnectionGroup.ROOT_IDENTIFIER = "ROOT";
+
+    /**
+     * All valid connection group types.
+     */
+    ConnectionGroup.Type = {
+
+        /**
+         * The type string associated with balancing connection groups.
+         *
+         * @type String
+         */
+        BALANCING : "BALANCING",
+
+        /**
+         * The type string associated with organizational connection groups.
+         *
+         * @type String
+         */
+        ORGANIZATIONAL : "ORGANIZATIONAL"
+
+    };
+
+    return ConnectionGroup;
+
+}]);

guacamole/src/main/webapp/app/rest/types/Permission.js

@@ -0,0 +1,153 @@
+/*
+ * 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 which defines the Permission class.
+ */
+angular.module('rest').factory('Permission', [function definePermission() {
+            
+    /**
+     * The object returned by REST API calls when representing the data
+     * associated with a supported remote desktop protocol.
+     * 
+     * @constructor
+     * @param {Permission|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     Permission.
+     */
+    var Permission = function Permission(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * The type of object associated with this permission.
+         *
+         * @type String
+         */
+        this.objectType = template.objectType;
+
+        /**
+         * The identifier of the specific object associated with this
+         * permission. If the objectType is Permission.ObjectType.SYSTEM, this
+         * property is not applicable.
+         * 
+         * @type String
+         */
+        this.objectIdentifier = template.objectIdentifier;
+
+        /**
+         * The type of this permission, representing the actions granted if
+         * this permission is present, such as the ability to read or update
+         * specific objects. Legal values are specified within
+         * Permission.Type and depend on this permission's objectType.
+         *
+         * @type String
+         */
+        this.permissionType = template.permissionType;
+
+    };
+
+    /**
+     * Valid object type strings.
+     */
+    Permission.ObjectType = {
+
+        /**
+         * The permission refers to a specific connection, identified by the
+         * value of objectIdentifier.
+         */
+        CONNECTION : "CONNECTION",
+
+        /**
+         * The permission refers to a specific connection group, identified by
+         * the value of objectIdentifier.
+         */
+        CONNECTION_GROUP : "CONNECTION_GROUP",
+
+        /**
+         * The permission refers to a specific user, identified by the value of
+         * objectIdentifier.
+         */
+        USER : "USER",
+
+        /**
+         * The permission refers to the system as a whole, and the
+         * objectIdentifier propery is not applicable.
+         */
+        SYSTEM : "SYSTEM"
+
+    };
+
+    /**
+     * Valid permission type strings.
+     */
+    Permission.Type = {
+
+        /**
+         * Permission to read from the specified object. This permission type
+         * does not apply to SYSTEM permissions.
+         */
+        READ : "READ",
+
+        /**
+         * Permission to update the specified object. This permission type does
+         * not apply to SYSTEM permissions.
+         */
+        UPDATE : "UPDATE",
+
+        /**
+         * Permission to delete the specified object. This permission type does
+         * not apply to SYSTEM permissions.
+         */
+        DELETE : "DELETE",
+
+        /**
+         * Permission to administer the specified object or, if the permission
+         * refers to the system as a whole, permission to administer the entire
+         * system.
+         */
+        ADMINISTER : "ADMINISTER",
+
+        /**
+         * Permission to create new users. This permission type may only be
+         * applied to the system as a whole.
+         */
+        CREATE_USER : "CREATE_USER",
+
+        /**
+         * Permission to create new connections. This permission type may only
+         * be applied to the system as a whole.
+         */
+        CREATE_CONNECTION : "CREATE_CONNECTION",
+
+        /**
+         * Permission to create new connection groups. This permission type may
+         * only be applied to the system as a whole.
+         */
+        CREATE_CONNECTION_GROUP : "CREATE_CONNECTION_GROUP"
+
+    };
+
+    return Permission;
+
+}]);

guacamole/src/main/webapp/app/rest/types/Protocol.js

@@ -0,0 +1,69 @@
+/*
+ * 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 which defines the Protocol class.
+ */
+angular.module('rest').factory('Protocol', [function defineProtocol() {
+            
+    /**
+     * The object returned by REST API calls when representing the data
+     * associated with a supported remote desktop protocol.
+     * 
+     * @constructor
+     * @param {Protocol|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     Protocol.
+     */
+    var Protocol = function Protocol(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * The name which uniquely identifies this protocol.
+         *
+         * @type String
+         */
+        this.name = template.name;
+
+        /**
+         * A human-readable name for this protocol.
+         *
+         * @type String
+         */
+        this.title = template.title;
+
+        /**
+         * An array of all known parameters for this protocol, their types,
+         * and other information.
+         *
+         * @type ProtocolParameter[]
+         * @default []
+         */
+        this.parameters = template.parameters || [];
+
+    };
+
+    return Protocol;
+
+}]);

guacamole/src/main/webapp/app/rest/types/ProtocolParameter.js

@@ -0,0 +1,152 @@
+/*
+ * 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 which defines the ProtocolParameter class.
+ */
+angular.module('rest').factory('ProtocolParameter', [function defineProtocolParameter() {
+            
+    /**
+     * The object returned by REST API calls when representing the data
+     * associated with a configuration parameter of a remote desktop protocol.
+     * 
+     * @constructor
+     * @param {ProtocolParameter|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     ProtocolParameter.
+     */
+    var ProtocolParameter = function ProtocolParameter(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * The name which uniquely identifies this parameter.
+         *
+         * @type String
+         */
+        this.name = template.name;
+
+        /**
+         * A human-readable name for this parameter.
+         *
+         * @type String
+         */
+        this.title = template.title;
+
+        /**
+         * The type string defining which values this parameter may contain,
+         * as well as what properties are applicable. Valid types are listed
+         * within ProtocolParameter.Type.
+         *
+         * @type String
+         * @default ProtocolParameter.Type.TEXT
+         */
+        this.type = template.type || ProtocolParameter.Type.TEXT;
+
+        /**
+         * The value to set the parameter to, in the case of a BOOLEAN
+         * parameter, to enable that parameter's effect.
+         *
+         * @type String
+         */
+        this.value = template.value;
+
+        /**
+         * All possible legal values for this parameter. This property is only
+         * applicable to ENUM type parameters.
+         *
+         * @type ProtocolParameterOption[]
+         */
+        this.options = template.options;
+
+    };
+
+    /**
+     * All valid protocol parameter types.
+     */
+    ProtocolParameter.Type = {
+
+        /**
+         * The type string associated with parameters that may contain a single
+         * line of arbitrary text.
+         *
+         * @type String
+         */
+        TEXT : "TEXT",
+
+        /**
+         * The type string associated with parameters that may contain an
+         * arbitrary string, where that string represents the username of the
+         * user authenticating with the remote desktop service.
+         * 
+         * @type string
+         */
+        USERNAME : "USERNAME",
+
+        /**
+         * The type string associated with parameters that may contain an
+         * arbitrary string, where that string represents the password of the
+         * user authenticating with the remote desktop service.
+         * 
+         * @type string
+         */
+        PASSWORD : "PASSWORD",
+
+        /**
+         * The type string associated with parameters that may contain only
+         * numeric values.
+         * 
+         * @type string
+         */
+        NUMERIC : "NUMERIC",
+
+        /**
+         * The type string associated with parameters that may contain only a
+         * single possible value, where that value enables the parameter's
+         * effect.
+         * 
+         * @type String
+         */
+        BOOLEAN : "BOOLEAN",
+
+        /**
+         * The type string associated with parameters that may contain a
+         * strictly-defined set of possible values.
+         * 
+         * @type String
+         */
+        ENUM : "ENUM",
+
+        /**
+         * The type string associated with parameters that may contain any
+         * number of lines of arbitrary text.
+         *
+         * @type String
+         */
+        MULTILINE : "MULTILINE"
+
+    };
+
+    return ProtocolParameter;
+
+}]);

guacamole/src/main/webapp/app/rest/types/ProtocolParameterOption.js

@@ -0,0 +1,61 @@
+/*
+ * 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 which defines the ProtocolParameterOption class.
+ */
+angular.module('rest').factory('ProtocolParameterOption', [function defineProtocolParameterOption() {
+            
+    /**
+     * The object returned by REST API calls when representing a single possible
+     * legal value of a configuration parameter of a remote desktop protocol.
+     * 
+     * @constructor
+     * @param {ProtocolParameterOption|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     ProtocolParameterOption.
+     */
+    var ProtocolParameterOption = function ProtocolParameterOption(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * A human-readable name for this parameter value.
+         *
+         * @type String
+         */
+        this.title = template.title;
+
+        /**
+         * The actual value to set the parameter to, if this option is
+         * selected.
+         *
+         * @type String
+         */
+        this.value = template.value;
+
+    };
+
+    return ProtocolParameterOption;
+
+}]);

guacamole/src/main/webapp/app/rest/types/User.js

@@ -0,0 +1,63 @@
+/*
+ * 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 which defines the User class.
+ */
+angular.module('rest').factory('User', [function defineUser() {
+            
+    /**
+     * The object returned by REST API calls when representing the data
+     * associated with a user.
+     * 
+     * @constructor
+     * @param {User|Object} [template={}]
+     *     The object whose properties should be copied within the new
+     *     User.
+     */
+    var User = function User(template) {
+
+        // Use empty object by default
+        template = template || {};
+
+        /**
+         * The name which uniquely identifies this user.
+         *
+         * @type String
+         */
+        this.username = template.username;
+
+        /**
+         * This user's password. Note that the REST API may not populate this
+         * property for the sake of security. In most cases, it's not even
+         * possible for the authentication layer to retrieve the user's true
+         * password.
+         * 
+         * @type String
+         */
+        this.password = template.password;
+
+    };
+
+    return User;
+
+}]);