From: imilne Date: Thu, 14 Dec 2006 16:15:36 +0000 (+0000) Subject: Updated docs and logging for the picking api. X-Git-Tag: Release_0.2~263 X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=de917169b4dc2bb1afdfd9432ed58c114243f451;p=vamsas.git Updated docs and logging for the picking api. git-svn-id: https://svn.lifesci.dundee.ac.uk/svn/repository/trunk@257 be28352e-c001-0410-b1a7-c7978e42abec --- diff --git a/src/org/vamsas/client/picking/PickManager.java b/src/org/vamsas/client/picking/PickManager.java index e4f4445..c313e25 100644 --- a/src/org/vamsas/client/picking/PickManager.java +++ b/src/org/vamsas/client/picking/PickManager.java @@ -2,9 +2,18 @@ package org.vamsas.client.picking; import java.net.*; import java.util.*; +import java.util.logging.*; +/** + * Manager class that maintains a list of connected clients in addition to + * attempting to run a server to listen for client connections. If the server + * initialization fails, then an attempt to connect (as a client) to another JVM + * that is already a server happens instead. + */ public class PickManager { + private static Logger logger = Logger.getLogger("org.vamsas.client.picking"); + // Maintains a list of client communication objects - each object represents // a way of talking to either: // the server - if this is client side (and in which case, the list will only contain one element @@ -13,6 +22,11 @@ public class PickManager private PickServer server; + /** + * Constructs a new PickManager. This method will return immediately, while + * a looping thread runs that attempts to run the server or connect to an + * existing server. + */ public PickManager() { server = new PickServer(this); @@ -21,29 +35,45 @@ public class PickManager new InitializeThread().start(); } - // Called whenver we try to make a new endpoint<->endpoint connection - boolean addClientConnection(Socket socket) + /** + * Attempts to establish a connection between two client endpoints. This + * method is called in two ways: 1) by the server when it receives a remote + * request (in which case the socket will already be established) and 2) by + * a client that is attempting to connect *to* the server. + * @param socket a socket endpoint for the connection + * @return true if the connection is successfully, false otherwise + */ + boolean addEndPoint(Socket socket) { PickEndPoint client = new PickEndPoint(this, socket); if (client.openConnection()) { clients.add(client); - System.out.println("List now contains " + clients.size() + " client(s)"); + logger.fine("List now contains " + clients.size() + " client(s)"); return true; } return false; } + /** + * Sends a message to other clients. + * @param str the message to send + */ public void sendMessage(String str) { forwardMessage(null, str); } - // Forwards (or sends) a message - // When the server receives a message, it will be resent to all clients, - // but *not* to the client that sent it out in the first place! + /** + * Forwards (or sends) a message. When the server (client A) receives a + * message from client B, it must also forward it to clients C and D (etc), + * but mustn't forward it *back* to client B. + * @param origin the client endpoint that received the message (will be null + * if the message originates from this instance + * @param str the message to send + */ private void forwardMessage(PickEndPoint origin, String str) { ListIterator itor = clients.listIterator(); @@ -56,10 +86,12 @@ public class PickManager } } - // Called by the endpoint code when a message is received - // The manager has to: - // a) hand message to VAMSAS app - // b) forward it to other clients if we're the server + /** + * Handles a received message. If the manager is running in server mode, + * then it must ensure the message is also forwarded to the other clients. + * @param origin the client endpoint that received the message + * @str the message that was received + */ void handleMessage(PickEndPoint origin, String str) { if (server.isServer()) @@ -68,10 +100,15 @@ public class PickManager // TODO: pass message to VAMSAS API } + /** + * Removes a client connection from the list when its connection is no + * longer valid. + * @param client the client endpoint to remove + */ void removeEndPoint(PickEndPoint client) { clients.remove(client); - System.out.println("List now contains " + clients.size() + " client(s)"); + logger.fine("List now contains " + clients.size() + " client(s)"); // If there's no endpoints left, then we've lost all connections and // need to reinitialize @@ -79,11 +116,14 @@ public class PickManager new InitializeThread().start(); } + /** + * Thread extension class to handle the actual initialization + */ private class InitializeThread extends Thread { public void run() { - System.out.println("Initializing connection..."); + logger.fine("Initializing connection..."); boolean connected = false; // Loop until we can get a connection (one way or the other) @@ -99,7 +139,7 @@ public class PickManager connected = true; // If it fails, then attempt to make a client connection... - else if (addClientConnection(null)) + else if (addEndPoint(null)) connected = true; } } diff --git a/src/org/vamsas/client/picking/PickServer.java b/src/org/vamsas/client/picking/PickServer.java index be18c67..abef55e 100644 --- a/src/org/vamsas/client/picking/PickServer.java +++ b/src/org/vamsas/client/picking/PickServer.java @@ -2,24 +2,44 @@ package org.vamsas.client.picking; import java.io.*; import java.net.*; +import java.util.logging.*; +/** + * Server class that listens for incoming connections on a predefined port. + */ class PickServer extends Thread { + private static Logger logger = Logger.getLogger("org.vamsas.client.picking"); + + // The port number we'll listen on static final int PORT = 53782; private ServerSocket serverSocket; + // Set to true once the server is established private boolean isServer = false; private PickManager manager; + /** + * Constructs a new instance of the server (but doesn't start it). + * @param manager a reference to the pick manager that owns this server + */ PickServer(PickManager manager) { this.manager = manager; } + /** + * Returns true if this server instance is running. + * Return true if this server instance is running + */ boolean isServer() { return isServer; } + /** + * Attempts to create the server by opening a server socket on the port. + * @return true if the server was created; false otherwise + */ boolean createServer() { try @@ -31,25 +51,31 @@ class PickServer extends Thread } catch (IOException e) { - // If we fail, just assume another app already has the port - System.out.println("SERVER: " + e); + logger.info("SERVER: " + e); return false; } } + /** + * Thread listening method - loops indefinitely listening for connections. + * When one is received, the socket object is passed to the manager so it + * can make a full client connection for further comms. + */ public void run() { - System.out.println("SERVER: listening on " + PORT + " - SERVER"); + logger.fine("SERVER: listening on " + PORT + " - SERVER"); // Loop forever, accepting connectons from other clients + // TODO: add in the ability to terminate the server if a VAMSAS session + // is ended while (true) { try { Socket socket = serverSocket.accept(); - System.out.println("SERVER: connection detected"); + logger.fine("SERVER: connection detected"); - manager.addClientConnection(socket); + manager.addEndPoint(socket); } catch (IOException e) {} } diff --git a/src/org/vamsas/client/picking/TestApp.java b/src/org/vamsas/client/picking/TestApp.java index 507daea..96924b5 100644 --- a/src/org/vamsas/client/picking/TestApp.java +++ b/src/org/vamsas/client/picking/TestApp.java @@ -1,10 +1,16 @@ package org.vamsas.client.picking; +import java.util.logging.*; + public class TestApp { + private static Logger logger = Logger.getLogger("org.vamsas.client.picking"); + public static void main(String[] args) throws Exception { +// logger.setLevel(Level.INFO); + TestApp app = new TestApp(); PickManager manager = new PickManager();