JavaDoc for network classes.

guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleSocket.java

@@ -23,11 +23,39 @@ import net.sourceforge.guacamole.io.GuacamoleWriter;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * Provides abstract socket-like access to a Guacamole connection.
+ *
+ * @author Michael Jumper
+ */
 public interface GuacamoleSocket {
 
+    /**
+     * Returns a GuacamoleReader which can be used to read from the
+     * Guacamole instruction stream associated with the connection
+     * represented by this GuacamoleSocket.
+     *
+     * @return A GuacamoleReader which can be used to read from the
+     *         Guacamole instruction stream.
+     */
     public GuacamoleReader getReader();
+
+    /**
+     * Returns a GuacamoleWriter which can be used to write to the
+     * Guacamole instruction stream associated with the connection
+     * represented by this GuacamoleSocket.
+     *
+     * @return A GuacamoleWriter which can be used to write to the
+     *         Guacamole instruction stream.
+     */
     public GuacamoleWriter getWriter();
 
+    /**
+     * Releases all resources in use by the connection represented by this
+     * GuacamoleSocket.
+     *
+     * @throws GuacamoleException If an error occurs while releasing resources.
+     */
     public void close() throws GuacamoleException;
 
 }

guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleTunnel.java

@@ -21,10 +21,15 @@ package net.sourceforge.guacamole.net;
 
 import java.util.UUID;
 import java.util.concurrent.locks.ReentrantLock;
-import net.sourceforge.guacamole.GuacamoleException;
 import net.sourceforge.guacamole.io.GuacamoleReader;
 import net.sourceforge.guacamole.io.GuacamoleWriter;
 
+/**
+ * Provides a unique identifier and synchronized access to the GuacamoleReader
+ * and GuacamoleWriter associated with a GuacamoleSocket.
+ *
+ * @author Michael Jumper
+ */
 public class GuacamoleTunnel {
 
     private UUID uuid;
@@ -33,7 +38,13 @@ public class GuacamoleTunnel {
     private ReentrantLock readerLock;
     private ReentrantLock writerLock;
 
-    public GuacamoleTunnel(GuacamoleSocket socket) throws GuacamoleException {
+    /**
+     * Creates a new GuacamoleTunnel which synchronizes access to the
+     * Guacamole instruction stream associated with the given GuacamoleSocket.
+     *
+     * @param socket The GuacamoleSocket to provide synchronized access for.
+     */
+    public GuacamoleTunnel(GuacamoleSocket socket) {
 
         this.socket = socket;
         uuid = UUID.randomUUID();
@@ -43,32 +54,75 @@ public class GuacamoleTunnel {
 
     }
 
+    /**
+     * Acquires exclusive read access to the Guacamole instruction stream
+     * and returns a GuacamoleReader for reading from that stream.
+     *
+     * @return A GuacamoleReader for reading from the Guacamole instruction
+     *         stream.
+     */
     public GuacamoleReader acquireReader() {
         readerLock.lock();
         return socket.getReader();
     }
 
+    /**
+     * Relinquishes exclusive read access to the Guacamole instruction
+     * stream. This function should be called whenever a thread finishes using
+     * a GuacamoleTunnel's GuacamoleReader.
+     */
     public void releaseReader() {
         readerLock.unlock();
     }
 
+    /**
+     * Returns whether there are threads waiting for read access to the
+     * Guacamole instruction stream.
+     *
+     * @return true if threads are waiting for read access the Guacamole
+     *         instruction stream, false otherwise.
+     */
     public boolean hasQueuedReaderThreads() {
         return readerLock.hasQueuedThreads();
     }
 
+    /**
+     * Acquires exclusive write access to the Guacamole instruction stream
+     * and returns a GuacamoleWriter for writing to that stream.
+     *
+     * @return A GuacamoleWriter for writing to the Guacamole instruction
+     *         stream.
+     */
     public GuacamoleWriter acquireWriter() {
         writerLock.lock();
         return socket.getWriter();
     }
 
+    /**
+     * Relinquishes exclusive write access to the Guacamole instruction
+     * stream. This function should be called whenever a thread finishes using
+     * a GuacamoleTunnel's GuacamoleWriter.
+     */
     public void releaseWriter() {
         writerLock.unlock();
     }
 
+    /**
+     * Returns whether there are threads waiting for write access to the
+     * Guacamole instruction stream.
+     *
+     * @return true if threads are waiting for write access the Guacamole
+     *         instruction stream, false otherwise.
+     */
     public boolean hasQueuedWriterThreads() {
         return writerLock.hasQueuedThreads();
     }
 
+    /**
+     * Returns the unique identifier associated with this GuacamoleTunnel.
+     *
+     * @return The unique identifier associated with this GuacamoleTunnel.
+     */
     public UUID getUUID() {
         return uuid;
     }

guacamole-common/src/main/java/net/sourceforge/guacamole/net/InetGuacamoleSocket.java

@@ -35,6 +35,12 @@ import java.net.SocketAddress;
 import net.sourceforge.guacamole.GuacamoleException;
 
 
+/**
+ * Provides abstract socket-like access to a Guacamole connection over a given
+ * hostname and port.
+ *
+ * @author Michael Jumper
+ */
 public class InetGuacamoleSocket implements GuacamoleSocket {
 
     private GuacamoleReader reader;
@@ -43,6 +49,16 @@ public class InetGuacamoleSocket implements GuacamoleSocket {
     private static final int SOCKET_TIMEOUT = 15000;
     private Socket sock;
 
+    /**
+     * Creates a new InetGuacamoleSocket which reads and writes instructions
+     * to the Guacamole instruction stream of the Guacamole proxy server
+     * running at the given hostname and port.
+     *
+     * @param hostname The hostname of the Guacamole proxy server to connect to.
+     * @param port The port of the Guacamole proxy server to connect to.
+     * @throws GuacamoleException If an error occurs while connecting to the
+     *                            Guacamole proxy server.
+     */
     public InetGuacamoleSocket(String hostname, int port) throws GuacamoleException {
 
         try {