From 3fe4aab695a961904a8178a0e58eceea025c837e Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Sat, 14 May 2011 00:18:33 -0700 Subject: [PATCH] JavaDoc for network classes. --- .../guacamole/net/GuacamoleSocket.java | 28 +++++++++ .../guacamole/net/GuacamoleTunnel.java | 58 ++++++++++++++++++- .../guacamole/net/InetGuacamoleSocket.java | 16 +++++ 3 files changed, 100 insertions(+), 2 deletions(-) diff --git a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleSocket.java b/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleSocket.java index 2ad5af5a4..bb6b58722 100644 --- a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleSocket.java +++ b/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 . */ +/** + * 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; } diff --git a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleTunnel.java b/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleTunnel.java index f03492e7c..438a8c03e 100644 --- a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/GuacamoleTunnel.java +++ b/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; } diff --git a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/InetGuacamoleSocket.java b/guacamole-common/src/main/java/net/sourceforge/guacamole/net/InetGuacamoleSocket.java index 5f56c695a..d966f2c2b 100644 --- a/guacamole-common/src/main/java/net/sourceforge/guacamole/net/InetGuacamoleSocket.java +++ b/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 {