JavaDoc for protocol classes.

guacamole-common/src/main/java/net/sourceforge/guacamole/protocol/ConfiguredGuacamoleSocket.java

@@ -25,10 +25,33 @@ import net.sourceforge.guacamole.protocol.GuacamoleInstruction.Operation;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * A GuacamoleSocket which pre-configures the connection based on a given
+ * GuacamoleConfiguration, completing the initial protocol handshake before
+ * accepting data for read or write.
+ *
+ * This is useful for forcing a connection to the Guacamole proxy server with
+ * a specific configuration while disallowing the client that will be using
+ * this GuacamoleSocket from manually controlling the initial protocol
+ * handshake.
+ *
+ * @author Michael Jumper
+ */
 public class ConfiguredGuacamoleSocket implements GuacamoleSocket {
 
     private GuacamoleSocket socket;
 
+    /**
+     * Creates a new ConfiguredGuacamoleSocket which uses the given
+     * GuacamoleConfiguration to complete the initial protocol handshake over
+     * the given GuacamoleSocket.
+     *
+     * @param socket The GuacamoleSocket to wrap.
+     * @param config The GuacamoleConfiguration to use to complete the initial
+     *               protocol handshake.
+     * @throws GuacamoleException If an error occurs while completing the
+     *                            initial protocol handshake.
+     */
     public ConfiguredGuacamoleSocket(GuacamoleSocket socket, GuacamoleConfiguration config) throws GuacamoleException {
 
         this.socket = socket;

guacamole-common/src/main/java/net/sourceforge/guacamole/protocol/GuacamoleConfiguration.java

@@ -21,23 +21,49 @@ import java.util.HashMap;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * All information necessary to complete the initial protocol handshake of a
+ * Guacamole session.
+ *
+ * @author Michael Jumper
+ */
 public class GuacamoleConfiguration {
 
     private String protocol;
     private HashMap<String, String> parameters = new HashMap<String, String>();
 
+    /**
+     * Returns the name of the protocol to be used.
+     * @return The name of the protocol to be used.
+     */
     public String getProtocol() {
         return protocol;
     }
 
+    /**
+     * Sets the name of the protocol to be used.
+     * @param protocol The name of the protocol to be used.
+     */
     public void setProtocol(String protocol) {
         this.protocol = protocol;
     }
 
+    /**
+     * Returns the value set for the parameter with the given name, if any.
+     * @param name The name of the parameter to return the value for.
+     * @return The value of the parameter with the given name, or null if
+     *         that parameter has not been set.
+     */
     public String getParameter(String name) {
         return parameters.get(name);
     }
 
+    /**
+     * Sets the value for the parameter with the given name.
+     *
+     * @param name The name of the parameter to set the value for.
+     * @param value The value to set for the parameter with the given name.
+     */
     public void setParameter(String name, String value) {
         parameters.put(name, value);
     }

guacamole-common/src/main/java/net/sourceforge/guacamole/protocol/GuacamoleInstruction.java

@@ -21,23 +21,55 @@ import java.util.HashMap;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * An abstract representation of a Guacamole instruction, as defined by the
+ * Guacamole protocol.
+ *
+ * @author Michael Jumper
+ */
 public class GuacamoleInstruction {
 
+    /**
+     * The operation performed by a particular Guacamole instruction. Each
+     * Operation is associated with a unique opcode.
+     */
     public enum Operation {
 
+        /**
+         * Message sent from client to server specifying which protocol is
+         * to be used.
+         */
         CLIENT_SELECT("select"),
+
+        /**
+         * Message sent from client to server specifying which argument
+         * values correspond to the arguments required by the selected
+         * protocol.
+         */
         CLIENT_CONNECT("connect"),
 
+        /**
+         * Message sent from server to client specifying which arguments
+         * are required by the selected protocol.
+         */
         SERVER_ARGS("args");
 
         private String opcode;
-        private Operation(String opcode) { this.opcode = opcode; }
+        private Operation(String opcode) {
+            this.opcode = opcode;
+        }
 
+        /**
+         * Returns the unique opcode associated with this Operation.
+         * @return The unique opcode associated with this Operation.
+         */
         public String getOpcode() {
             return opcode;
         }
 
-        // Maintain static hash of all opcodes
+        /**
+         * Static hash of all opcodes and their corresponding Operations.
+         */
         private static final HashMap<String, Operation> opcodeToOperation;
         static {
 
@@ -48,6 +80,13 @@ public class GuacamoleInstruction {
 
         }
 
+        /**
+         * Returns the corresponding Operation having the given opcode, if any.
+         *
+         * @param opcode The unique opcode associated with an Operation.
+         * @return The Operation associated with the given opcode, or null if
+         *         no such Operation is defined.
+         */
         public static Operation fromOpcode(String opcode) {
             return opcodeToOperation.get(opcode);
         }
@@ -57,19 +96,45 @@ public class GuacamoleInstruction {
     private Operation operation;
     private String[] args;
 
+    /**
+     * Creates a new GuacamoleInstruction having the given Operation and
+     * list of arguments values.
+     *
+     * @param operation The Operation of the instruction to create.
+     * @param args The list of argument values to provide in the new
+     *             instruction if any.
+     */
     public GuacamoleInstruction(Operation operation, String... args) {
         this.operation = operation;
         this.args = args;
     }
 
+    /**
+     * Returns the Operation associated with this GuacamoleInstruction.
+     * @return The Operation associated with this GuacamoleInstruction.
+     */
     public Operation getOperation() {
         return operation;
     }
 
+    /**
+     * Returns an array of all argument values specified for this
+     * GuacamoleInstruction.
+     *
+     * @return An array of all argument values specified for this
+     *         GuacamoleInstruction.
+     */
     public String[] getArgs() {
         return args;
     }
 
+    /**
+     * Returns this GuacamoleInstruction in the form it would be sent over the
+     * Guacamole protocol.
+     *
+     * @return This GuacamoleInstruction in the form it would be sent over the
+     *         Guacamole protocol.
+     */
     @Override
     public String toString() {