net.sf.cuf.singleapp

Class StartupSocketCommunicator

java.lang.Object

net.sf.cuf.singleapp.StartupSocketCommunicator

public class StartupSocketCommunicator
extends Object

This class allows a simple, one time socket communication between instances of the same application. This is intended for:

• Ensuring only instance of the application is run at the same time.
• Passing a data object from a newly started instance to the first instance started so that the first instance may do the work while the newly started instance quits.

It is not intended for:

• Continuous communication between processes.
• A robust or fast server implementation.
• Making ice cream and other things that may be on your mind.

To use:

1. Create an instance with StartupSocketCommunicator(String, int, ContactHandler, Serializable).
2. Determine which mode we entered by evaluating isServerMode().
3. If you are in server mode (first instance of the application), you will receive calls on ContactHandler.handleContactFromOtherInstance(Serializable). If you are in client mode (not first instance of the application), you have to check if the communication was successful (getException() is null) and then get the result that was returned from the server by calling getClientResult().

See StartupSocketCommunicator(String, int, ContactHandler, Serializable) for further details.

This implementation is meant to be thread safe and may be used from any thread.

Constructor Summary

Constructors

Constructor and Description
StartupSocketCommunicator(String pApplicationId, int pPort, ContactHandler pContactHandler, Serializable pData) Initiates the communication for this application instance.

Method Summary

Modifier and Type	Method and Description
Serializable	getClientResult()
Throwable	getException()
boolean	isServerMode()
boolean	isServerStopped()
void	stopServer() stops the server and frees the port.
void	waitServerStopped() stops the server, frees the port and waits until that happens.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StartupSocketCommunicator

public StartupSocketCommunicator(String pApplicationId,
                                 int pPort,
                                 ContactHandler pContactHandler,
                                 Serializable pData)

Initiates the communication for this application instance. After the object has been created you can query the result of the communication attempt.

First, we attempt to register a server socket on the given port. If the socket is successfully registered, we are the first instance of the application and act as server to other instances. Otherwise we are an additional instance of the application and act as client.

The following situations may happen:

• First instance - Server mode (isServerMode() is true)
  If we are the first to register the socket, other application instances will call the given ContactHandler. The calls will happen in arbitrary threads.

  If an exception in server mode occurs, you can access it with the getException(). If that value is null in server mode, then the server is running (or ran) without problem.

  If you want to stop the server explicitly, call stopServer(). Otherwise the server will be stopped when the shutdown handlers are executed (see Runtime.addShutdownHook(Thread)).

• Not first instance - Client mode (isServerMode() is true)
  If we can not register the socket, we try to contact the application instance that has registered the socket. The protocol that is used is described in the private inner class ClientContactHandlerThread.

  If an exception in client mode occurs, you can access it with the getException() - it will not be thrown!. If that value is null in client mode, then the request ran without problems and we have a result stored in getClientResult().

Note that the various threads started by the StartupSocketCommunicator are all daemon threads, i.e. they will not stop the application from exiting, even if a client is already connected. The client will notice that by an exception in its communication attempts.

Parameters:

pApplicationId - an id that is compared when two instances create contact. If the application id does not match, we assume that a different application that uses the same technique is configured to use the same port.

pPort - the port to use for communication

pContactHandler - the contact handler that is called by other instances, must not be null. This handler is only used when this application instance is the one that gets the port and thus acts as a server. Otherwise it is ignored.

pData - the data to pass to the first application instance if we are not the first. This may be any Serializable but you should certain that either both application instances are using the same code base or that the objects have custom serialization mechanisms that allow communication across different versions.

Method Detail

isServerMode

public boolean isServerMode()

Returns:

true if we have entered the server mode, see StartupSocketCommunicator(String, int, ContactHandler, Serializable) for details

isServerStopped

public boolean isServerStopped()

Returns:

true if the server has been stopped, makes only sense if isServerMode() is true

getException

public Throwable getException()

Returns:

the last exception (if any) that occurred

getClientResult

public Serializable getClientResult()

Returns:

the result returned from the server when it called ContactHandler.handleContactFromOtherInstance(Serializable) with our data (only meaningfull if isServerMode() is false).

stopServer

public void stopServer()

stops the server and frees the port. If we are not in server mode, we ignore this call. When this method returns, the server may not be stopped, yet, but it will be on its way.

waitServerStopped

public void waitServerStopped()
                       throws InterruptedException

stops the server, frees the port and waits until that happens. If we are not in server mode, we ignore this call. When this method returns, the server is stopped.

Throws:

InterruptedException - if we get interrupted during sleep