GUAC-1161: Generalize protocol parameters into form parameters.

guacamole-ext/src/main/java/org/glyptodon/guacamole/form/Parameter.java

@@ -0,0 +1,283 @@
+/*
+ * Copyright (C) 2013 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.form;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+/**
+ * Represents an arbitrary parameter, such as an HTTP parameter, or the
+ * parameter of a remote desktop protocol.
+ *
+ * @author Michael Jumper
+ */
+public class Parameter {
+
+    /**
+     * All possible types of parameter.
+     */
+    public enum Type {
+
+        /**
+         * A text parameter, accepting arbitrary values.
+         */
+        TEXT,
+
+        /**
+         * A username parameter. This parameter type generally behaves
+         * identically to arbitrary text parameters, but has semantic
+         * differences. If credential pass-through is in use, the value for this
+         * parameter may be automatically provided using the credentials
+         * originally used by the user to authenticate.
+         */
+        USERNAME,
+
+        /**
+         * A password parameter, whose value is sensitive and must be hidden. If
+         * credential pass-through is in use, the value for this parameter may
+         * be automatically provided using the credentials originally used by
+         * the user to authenticate.
+         */
+        PASSWORD,
+
+        /**
+         * A numeric parameter, whose value must contain only digits.
+         */
+        NUMERIC,
+
+        /**
+         * A boolean parameter, whose value is either blank or "true".
+         */
+        BOOLEAN,
+
+        /**
+         * An enumerated parameter, whose legal values are fully enumerated
+         * by a provided, finite list.
+         */
+        ENUM,
+
+        /**
+         * A text parameter that can span more than one line.
+         */
+        MULTILINE
+
+    }
+
+    /**
+     * The unique name that identifies this parameter.
+     */
+    private String name;
+
+    /**
+     * A human-readable name to be presented to the user.
+     */
+    private String title;
+
+    /**
+     * The type of this parameter.
+     */
+    private Type type;
+
+    /**
+     * The value of this parameter, when checked. This is only applicable to
+     * BOOLEAN parameters.
+     */
+    private String value;
+
+    /**
+     * A collection of all associated parameter options.
+     */
+    private Collection<ParameterOption> options;
+
+    /**
+     * Creates a new Parameter with no associated name, title, or type.
+     */
+    public Parameter() {
+        this.options = new ArrayList<ParameterOption>();
+    }
+
+    /**
+     * Creates a new Parameter with the given name, title, and type.
+     *
+     * @param name
+     *     The unique name to associate with this parameter.
+     *
+     * @param title
+     *     The human-readable title to associate with this parameter.
+     *
+     * @param type
+     *     The type of this parameter.
+     */
+    public Parameter(String name, String title, Type type) {
+        this.name    = name;
+        this.title   = title;
+        this.type    = type;
+        this.options = new ArrayList<ParameterOption>();
+    }
+
+    /**
+     * Creates a new BOOLEAN Parameter with the given name, title, and value.
+     *
+     * @param name
+     *     The unique name to associate with this parameter.
+     *
+     * @param title
+     *     The human-readable title to associate with this parameter.
+     *
+     * @param value
+     *     The value that should be assigned to this parameter if enabled.
+     */
+    public Parameter(String name, String title, String value) {
+        this.name    = name;
+        this.title   = title;
+        this.type    = Type.BOOLEAN;
+        this.value   = value;
+        this.options = new ArrayList<ParameterOption>();
+    }
+
+    /**
+     * Creates a new ENUM Parameter with the given name, title, and options.
+     *
+     * @param name
+     *     The unique name to associate with this parameter.
+     *
+     * @param title
+     *     The human-readable title to associate with this parameter.
+     *
+     * @param options
+     *     A collection of all possible valid options for this parameter.
+     */
+    public Parameter(String name, String title, Collection<ParameterOption> options) {
+        this.name    = name;
+        this.title   = title;
+        this.type    = Type.ENUM;
+        this.options = options;
+    }
+
+    /**
+     * Returns the unique name associated with this parameter.
+     *
+     * @return
+     *     The unique name associated with this parameter.
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Sets the unique name associated with this parameter.
+     *
+     * @param name
+     *     The unique name to assign to this parameter.
+     */
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    /**
+     * Returns the human-readable title associated with this parameter.
+     *
+     * @return
+     *     The human-readable title associated with this parameter.
+     */
+    public String getTitle() {
+        return title;
+    }
+
+    /**
+     * Sets the title associated with this parameter. The title must be a
+     * human-readable string which describes accurately this parameter.
+     *
+     * @param title
+     *     A human-readable string describing this parameter.
+     */
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    /**
+     * Returns the value that should be assigned to this parameter if enabled.
+     * This is only applicable to BOOLEAN parameters.
+     *
+     * @return
+     *     The value that should be assigned to this parameter if enabled.
+     */
+    public String getValue() {
+        return value;
+    }
+
+    /**
+     * Sets the value that should be assigned to this parameter if enabled.
+     * This is only applicable to BOOLEAN parameters.
+     *
+     * @param value
+     *     The value that should be assigned to this parameter if enabled.
+     */
+    public void setValue(String value) {
+        this.value = value;
+    }
+
+    /**
+     * Returns the type of this parameter.
+     *
+     * @return
+     *     The type of this parameter.
+     */
+    public Type getType() {
+        return type;
+    }
+
+    /**
+     * Sets the type of this parameter.
+     *
+     * @param type
+     *     The type of this parameter.
+     */
+    public void setType(Type type) {
+        this.type = type;
+    }
+
+    /**
+     * Returns a mutable collection of parameter options. Changes to this
+     * collection directly affect the available options. This is only
+     * applicable to ENUM parameters.
+     *
+     * @return
+     *     A mutable collection of parameter options.
+     */
+    public Collection<ParameterOption> getOptions() {
+        return options;
+    }
+
+    /**
+     * Sets the options available as possible values of this parameter. This
+     * is only applicable to ENUM parameters.
+     *
+     * @param options
+     *     The options to associate with this parameter.
+     */
+    public void setOptions(Collection<ParameterOption> options) {
+        this.options = options;
+    }
+
+}

guacamole-ext/src/main/java/org/glyptodon/guacamole/form/ParameterOption.java

@@ -20,18 +20,17 @@
  * THE SOFTWARE.
  */
 
-package org.glyptodon.guacamole.protocols;
+package org.glyptodon.guacamole.form;
 
 /**
- * Describes an available legal value for an enumerated protocol parameter.
+ * Describes an available legal value for an enumerated parameter.
  *
  * @author Michael Jumper
  */
-public class ProtocolParameterOption {
+public class ParameterOption {
 
     /**
-     * The value that will be sent to the client plugin if this option is
+     * The value that will be assigned if this option is chosen.
-     * chosen.
      */
     private String value;
 
@@ -41,20 +40,40 @@ public class ProtocolParameterOption {
     private String title;
 
     /**
-     * Returns the value that will be sent to the client plugin if this option
+     * Creates a new ParameterOption with no associated value or title.
-     * is chosen.
+     */
+    public ParameterOption() {
+    }
+
+    /**
+     * Creates a new ParameterOption having the given value and title.
      *
-     * @return The value that will be sent if this option is chosen.
+     * @param value
+     *     The value to assign if this option is chosen.
+     *
+     * @param title
+     *     The human-readable title to associate with this option.
+     */
+    public ParameterOption(String value, String title) {
+        this.value = value;
+        this.title = title;
+    }
+    
+    /**
+     * Returns the value that will be assigned if this option is chosen.
+     *
+     * @return
+     *     The value that will be assigned if this option is chosen.
      */
     public String getValue() {
         return value;
     }
 
     /**
-     * Sets the value that will be sent to the client plugin if this option is
+     * Sets the value that will be assigned if this option is chosen.
-     * chosen.
      *
-     * @param value The value to send if this option is chosen.
+     * @param value
+     *     The value to assign if this option is chosen.
      */
     public void setValue(String value) {
         this.value = value;
@@ -62,7 +81,9 @@ public class ProtocolParameterOption {
 
     /**
      * Returns the human-readable title describing the effect of this option.
-     * @return The human-readable title describing the effect of this option.
+     *
+     * @return
+     *     The human-readable title describing the effect of this option.
      */
     public String getTitle() {
         return title;
@@ -70,7 +91,9 @@ public class ProtocolParameterOption {
 
     /**
      * Sets the human-readable title describing the effect of this option.
-     * @param title A human-readable title describing the effect of this option.
+     *
+     * @param title
+     *     A human-readable title describing the effect of this option.
      */
     public void setTitle(String title) {
         this.title = title;

guacamole-ext/src/main/java/org/glyptodon/guacamole/protocols/ProtocolInfo.java

@@ -24,6 +24,7 @@ package org.glyptodon.guacamole.protocols;
 
 import java.util.ArrayList;
 import java.util.Collection;
+import org.glyptodon.guacamole.form.Parameter;
 
 /**
  * Describes a protocol and all parameters associated with it, as required by
@@ -47,8 +48,49 @@ public class ProtocolInfo {
     /**
      * A collection of all associated protocol parameters.
      */
-    private Collection<ProtocolParameter> parameters =
+    private Collection<Parameter> parameters;
-            new ArrayList<ProtocolParameter>();
+
+    /**
+     * Creates a new ProtocolInfo with no associated name, title, or
+     * parameters.
+     */
+    public ProtocolInfo() {
+        this.parameters = new ArrayList<Parameter>();
+    }
+
+    /**
+     * Creates a new ProtocolInfo having the given name and title, but without
+     * any parameters.
+     *
+     * @param name
+     *     The unique name associated with the protocol.
+     *
+     * @param title
+     *     The human-readable title to associate with the protocol.
+     */
+    public ProtocolInfo(String name, String title) {
+        this.name       = name;
+        this.title      = title;
+        this.parameters = new ArrayList<Parameter>();
+    }
+
+    /**
+     * Creates a new ProtocolInfo having the given name, title, and parameters.
+     *
+     * @param name
+     *     The unique name associated with the protocol.
+     *
+     * @param title
+     *     The human-readable title to associate with the protocol.
+     * 
+     * @param parameters
+     *     The parameters to associate with the protocol.
+     */
+    public ProtocolInfo(String name, String title, Collection<Parameter> parameters) {
+        this.name       = name;
+        this.title      = title;
+        this.parameters = parameters;
+    }
 
     /**
      * Returns the human-readable title associated with this protocol.
@@ -95,8 +137,19 @@ public class ProtocolInfo {
      *
      * @return A mutable collection of protocol parameters.
      */
-    public Collection<ProtocolParameter> getParameters() {
+    public Collection<Parameter> getParameters() {
         return parameters;
     }
 
+    /**
+     * Sets the collection of protocol parameters associated with this
+     * protocol.
+     *
+     * @param parameters
+     *     The collection of parameters to associate with this protocol.
+     */
+    public void setParameters(Collection<Parameter> parameters) {
+        this.parameters = parameters;
+    }
+    
 }

guacamole-ext/src/main/java/org/glyptodon/guacamole/protocols/ProtocolParameter.java

@@ -1,192 +0,0 @@
-/*
- * Copyright (C) 2013 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.protocols;
-
-import java.util.ArrayList;
-import java.util.Collection;
-
-/**
- * Represents a parameter of a protocol.
- *
- * @author Michael Jumper
- */
-public class ProtocolParameter {
-
-    /**
-     * All possible types of protocol parameter.
-     */
-    public enum Type {
-
-        /**
-         * A text parameter, accepting arbitrary values.
-         */
-        TEXT,
-
-        /**
-         * A username parameter. This parameter type generally behaves
-         * identically to arbitrary text parameters, but has semantic
-         * differences. If credential pass-through is in use, the value for this
-         * parameter may be automatically provided using the credentials
-         * originally used by the user to authenticate.
-         */
-        USERNAME,
-
-        /**
-         * A password parameter, whose value is sensitive and must be hidden. If
-         * credential pass-through is in use, the value for this parameter may
-         * be automatically provided using the credentials originally used by
-         * the user to authenticate.
-         */
-        PASSWORD,
-
-        /**
-         * A numeric parameter, whose value must contain only digits.
-         */
-        NUMERIC,
-
-        /**
-         * A boolean parameter, whose value is either blank or "true".
-         */
-        BOOLEAN,
-
-        /**
-         * An enumerated parameter, whose legal values are fully enumerated
-         * by a provided, finite list.
-         */
-        ENUM,
-
-        /**
-         * A text parameter that can span more than one line.
-         */
-        MULTILINE
-
-    }
-
-    /**
-     * The unique name that identifies this parameter to the protocol plugin.
-     */
-    private String name;
-
-    /**
-     * A human-readable name to be presented to the user.
-     */
-    private String title;
-
-    /**
-     * The type of this field.
-     */
-    private Type type;
-
-    /**
-     * The value of this parameter, for boolean parameters.
-     */
-    private String value;
-
-    /**
-     * A collection of all associated parameter options.
-     */
-    private Collection<ProtocolParameterOption> options =
-            new ArrayList<ProtocolParameterOption>();
-
-    /**
-     * Returns the name associated with this protocol parameter.
-     * @return The name associated with this protocol parameter.
-     */
-    public String getName() {
-        return name;
-    }
-
-    /**
-     * Sets the name associated with this protocol parameter. This name must
-     * uniquely identify this parameter among the others accepted by the
-     * corresponding protocol.
-     *
-     * @param name The name to assign to this protocol parameter.
-     */
-    public void setName(String name) {
-        this.name = name;
-    }
-
-    /**
-     * Returns the title associated with this protocol parameter.
-     * @return The title associated with this protocol parameter.
-     */
-    public String getTitle() {
-        return title;
-    }
-
-    /**
-     * Sets the title associated with this protocol parameter. The title must
-     * be a human-readable string which describes accurately this parameter.
-     *
-     * @param title A human-readable string describing this parameter.
-     */
-    public void setTitle(String title) {
-        this.title = title;
-    }
-
-    /**
-     * Returns the value associated with this protocol parameter.
-     * @return The value associated with this protocol parameter.
-     */
-    public String getValue() {
-        return value;
-    }
-
-    /**
-     * Sets the value associated with this protocol parameter. The value must
-     * be a human-readable string which describes accurately this parameter.
-     *
-     * @param value A human-readable string describing this parameter.
-     */
-    public void setValue(String value) {
-        this.value = value;
-    }
-
-    /**
-     * Returns the type of this parameter.
-     * @return The type of this parameter.
-     */
-    public Type getType() {
-        return type;
-    }
-
-    /**
-     * Sets the type of this parameter.
-     * @param type The type of this parameter.
-     */
-    public void setType(Type type) {
-        this.type = type;
-    }
-
-    /**
-     * Returns a mutable collection of protocol parameter options. Changes to
-     * this collection directly affect the available options.
-     *
-     * @return A mutable collection of parameter options.
-     */
-    public Collection<ProtocolParameterOption> getOptions() {
-        return options;
-    }
-
-}

guacamole-ext/src/main/java/org/glyptodon/guacamole/xml/protocol/OptionTagHandler.java

@@ -22,7 +22,7 @@
 
 package org.glyptodon.guacamole.xml.protocol;
 
-import org.glyptodon.guacamole.protocols.ProtocolParameterOption;
+import org.glyptodon.guacamole.form.ParameterOption;
 import org.glyptodon.guacamole.xml.TagHandler;
 import org.xml.sax.Attributes;
 import org.xml.sax.SAXException;
@@ -37,7 +37,7 @@ public class OptionTagHandler implements TagHandler {
     /**
      * The option backing this option tag.
      */
-    private ProtocolParameterOption option = new ProtocolParameterOption();
+    private ParameterOption option = new ParameterOption();
 
     @Override
     public void init(Attributes attributes) throws SAXException {
@@ -55,10 +55,10 @@ public class OptionTagHandler implements TagHandler {
     }
 
     /**
-     * Returns the ProtocolParameterOption backing this tag.
+     * Returns the ParameterOption backing this tag.
-     * @return The ProtocolParameterOption backing this tag.
+     * @return The ParameterOption backing this tag.
      */
-    public ProtocolParameterOption asProtocolParameterOption() {
+    public ParameterOption asParameterOption() {
         return option;
     }
 

guacamole-ext/src/main/java/org/glyptodon/guacamole/xml/protocol/ParamTagHandler.java

@@ -22,7 +22,7 @@
 
 package org.glyptodon.guacamole.xml.protocol;
 
-import org.glyptodon.guacamole.protocols.ProtocolParameter;
+import org.glyptodon.guacamole.form.Parameter;
 import org.glyptodon.guacamole.xml.TagHandler;
 import org.xml.sax.Attributes;
 import org.xml.sax.SAXException;
@@ -35,9 +35,9 @@ import org.xml.sax.SAXException;
 public class ParamTagHandler implements TagHandler {
 
     /**
-     * The ProtocolParameter backing this tag handler.
+     * The Parameter backing this tag handler.
      */
-    private ProtocolParameter protocolParameter = new ProtocolParameter();
+    private Parameter protocolParameter = new Parameter();
 
     @Override
     public void init(Attributes attributes) throws SAXException {
@@ -51,31 +51,31 @@ public class ParamTagHandler implements TagHandler {
 
         // Text field
         if ("text".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.TEXT);
+            protocolParameter.setType(Parameter.Type.TEXT);
 
         // Numeric field
         else if ("numeric".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.NUMERIC);
+            protocolParameter.setType(Parameter.Type.NUMERIC);
 
         // Username field
         else if ("username".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.USERNAME);
+            protocolParameter.setType(Parameter.Type.USERNAME);
 
         // Password field
         else if ("password".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.PASSWORD);
+            protocolParameter.setType(Parameter.Type.PASSWORD);
 
         // Enumerated field
         else if ("enum".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.ENUM);
+            protocolParameter.setType(Parameter.Type.ENUM);
 
         // Multiline field
         else if ("multiline".equals(type))
-            protocolParameter.setType(ProtocolParameter.Type.MULTILINE);
+            protocolParameter.setType(Parameter.Type.MULTILINE);
 
         // Boolean field
         else if ("boolean".equals(type)) {
-            protocolParameter.setType(ProtocolParameter.Type.BOOLEAN);
+            protocolParameter.setType(Parameter.Type.BOOLEAN);
 
             if(protocolParameter.getValue() == null)
                 throw new SAXException
@@ -99,7 +99,7 @@ public class ParamTagHandler implements TagHandler {
 
             // Store stub in options collection
             protocolParameter.getOptions().add(
-                tagHandler.asProtocolParameterOption());
+                tagHandler.asParameterOption());
             return tagHandler;
 
         }
@@ -114,10 +114,10 @@ public class ParamTagHandler implements TagHandler {
     }
 
     /**
-     * Returns the ProtocolParameter backing this tag.
+     * Returns the Parameter backing this tag.
-     * @return The ProtocolParameter backing this tag.
+     * @return The Parameter backing this tag.
      */
-    public ProtocolParameter asProtocolParameter() {
+    public Parameter asParameter() {
         return protocolParameter;
     }
 

guacamole-ext/src/main/java/org/glyptodon/guacamole/xml/protocol/ProtocolTagHandler.java

@@ -56,7 +56,7 @@ public class ProtocolTagHandler implements TagHandler {
             ParamTagHandler tagHandler = new ParamTagHandler();
 
             // Store stub in parameters collection
-            info.getParameters().add(tagHandler.asProtocolParameter());
+            info.getParameters().add(tagHandler.asParameter());
             return tagHandler;
 
         }