JavaDoc for servlet classes.

guacamole-common/src/main/java/net/sourceforge/guacamole/servlet/GuacamoleSession.java

@@ -25,18 +25,31 @@ import javax.servlet.http.HttpSession;
 import net.sourceforge.guacamole.GuacamoleException;
 import net.sourceforge.guacamole.net.GuacamoleTunnel;
 
+/**
+ * Provides abstract access to the tunnels associated with a Guacamole session.
+ *
+ * @author Michael Jumper
+ */
 public class GuacamoleSession {
 
-    private final HttpSession session;
     private ConcurrentMap<String, GuacamoleTunnel> tunnels;
 
+    /**
+     * Creates a new GuacamoleSession, storing and retrieving tunnels from the
+     * given HttpSession. Note that the true Guacamole session is tied to the
+     * HttpSession provided, thus creating a new GuacamoleSession does not
+     * create a new Guacamole session; it merely creates a new object for
+     * accessing the tunnels of an existing Guacamole session represented by
+     * the provided HttpSession.
+     *
+     * @param session The HttpSession to use as tunnel storage.
+     * @throws GuacamoleException If session is null.
+     */
     public GuacamoleSession(HttpSession session) throws GuacamoleException {
 
         if (session == null)
             throw new GuacamoleException("User has no session.");
 
-        this.session = session;
-
         synchronized (session) {
 
             tunnels = (ConcurrentMap<String, GuacamoleTunnel>) session.getAttribute("GUAC_TUNNELS");
@@ -49,18 +62,30 @@ public class GuacamoleSession {
 
     }
 
-    public void invalidate() {
+    /**
-        session.invalidate();
+     * Attaches the given tunnel to this GuacamoleSession.
-    }
+     * @param tunnel The tunnel to attach to this GucacamoleSession.
-
+     */
-    public void attachTunnel(GuacamoleTunnel tunnel) throws GuacamoleException {
+    public void attachTunnel(GuacamoleTunnel tunnel) {
         tunnels.put(tunnel.getUUID().toString(), tunnel);
     }
 
-    public void detachTunnel(GuacamoleTunnel tunnel) throws GuacamoleException {
+    /**
+     * Detaches the given tunnel to this GuacamoleSession.
+     * @param tunnel The tunnel to detach to this GucacamoleSession.
+     */
+    public void detachTunnel(GuacamoleTunnel tunnel) {
         tunnels.remove(tunnel.getUUID().toString());
     }
 
+    /**
+     * Returns the tunnel with the given UUID attached to this GuacamoleSession,
+     * if any.
+     *
+     * @param tunnelUUID The UUID of an attached tunnel.
+     * @return The tunnel corresponding to the given UUID, if attached, or null
+     *         if no such tunnel is attached.
+     */
     public GuacamoleTunnel getTunnel(String tunnelUUID) {
         return tunnels.get(tunnelUUID);
     }

guacamole-common/src/main/java/net/sourceforge/guacamole/servlet/GuacamoleTunnelServlet.java

@@ -33,7 +33,12 @@ import net.sourceforge.guacamole.GuacamoleException;
 import net.sourceforge.guacamole.io.GuacamoleReader;
 import net.sourceforge.guacamole.io.GuacamoleWriter;
 
-
+/**
+ * A HttpServlet implementing and abstracting the operations required by the
+ * JavaScript Guacamole client's tunnel.
+ *
+ * @author Michael Jumper
+ */
 public abstract class GuacamoleTunnelServlet extends HttpServlet {
 
     @Override
@@ -117,8 +122,41 @@ public abstract class GuacamoleTunnelServlet extends HttpServlet {
 
     }
 
+    /**
+     * Called whenever the JavaScript Guacamole client makes a connection
+     * request. It it up to the implementor of this function to define what
+     * conditions must be met for a tunnel to be configured and returned as a
+     * result of this connection request (whether some sort of credentials must
+     * be specified, for example).
+     *
+     * @param request The HttpServletRequest associated with the connection
+     *                request received. Any parameters specified along with
+     *                the connection request can be read from this object.
+     * @return A newly constructed GuacamoleTunnel if successful,
+     *         null otherwise.
+     * @throws GuacamoleException If an error occurs while constructing the
+     *                            GuacamoleTunnel, or if the conditions
+     *                            required for connection are not met.
+     */
     protected abstract GuacamoleTunnel doConnect(HttpServletRequest request) throws GuacamoleException;
 
+    /**
+     * Called whenever the JavaScript Guacamole client makes a read request.
+     * This function should in general not be overridden, as it already
+     * contains a proper implementation of the read operation.
+     *
+     * @param request The HttpServletRequest associated with the read request
+     *                received.
+     * @param response The HttpServletResponse associated with the write request
+     *                 received. Any data to be sent to the client in response
+     *                 to the write request should be written to the response
+     *                 body of this HttpServletResponse.
+     * @param tunnelUUID The UUID of the tunnel to read from, as specified in
+     *                   the write request. This tunnel must be attached to
+     *                   the Guacamole session.
+     * @throws GuacamoleException If an error occurs while handling the read
+     *                            request.
+     */
     protected void doRead(HttpServletRequest request, HttpServletResponse response, String tunnelUUID) throws GuacamoleException {
 
         HttpSession httpSession = request.getSession(false);
@@ -178,6 +216,22 @@ public abstract class GuacamoleTunnelServlet extends HttpServlet {
 
     }
 
+    /**
+     * Called whenever the JavaScript Guacamole client makes a write request.
+     * This function should in general not be overridden, as it already
+     * contains a proper implementation of the write operation.
+     *
+     * @param request The HttpServletRequest associated with the write request
+     *                received. Any data to be written will be specified within
+     *                the body of this request.
+     * @param response The HttpServletResponse associated with the write request
+     *                 received.
+     * @param tunnelUUID The UUID of the tunnel to write to, as specified in
+     *                   the write request. This tunnel must be attached to
+     *                   the Guacamole session.
+     * @throws GuacamoleException If an error occurs while handling the write
+     *                            request.
+     */
     protected void doWrite(HttpServletRequest request, HttpServletResponse response, String tunnelUUID) throws GuacamoleException {
 
         HttpSession httpSession = request.getSession(false);