Menu
pushmode

Class ShutdownListener

PushMode » API Reference » pushmode



  • public class ShutdownListener
    extends Object
    System-wide single instance lock. This class ensures shutdown of previous instance of the application before new instance is launched. It uses exclusive ownership of a TCP port for cross-platform locking and inter-process signaling.
    ShutdownListener is particularly useful during development. In Eclipse, for example, it is sufficient to press Ctrl+F11 to have an old instance terminated and a new one launched.
    Thread-safety:
    All methods of ShutdownListener are safe to call from multiple threads.
    Lifecycle:
    ShutdownListener goes through multiple stages: inactive, signaled, waiting, exclusive, and shutdown. It is initially created in inactive state where no lock is held and no signaling to other instances of the application is performed. In signaled state, the previous instance of the application has been signaled and it is shutting down. Application can perform non-conflicting initialization at this stage. In waiting state, application's main thread is blocking until the previous instance of the application terminates. Once the previous instance of the application terminates, ShutdownListener enters exclusive state and application is free to allocate exclusive resources, notably the listening port of PushServer. Finally, ShutdownListener enters shutdown state when signaled by new instance of the application or when current instance of the application wishes to terminate. In this state, application is expected to release exclusive resources (notably ports) before returning from main().
    Security:
    ShutdownListener binds to localhost (127.0.0.1). It therefore cannot be signaled to shut down remotely. Where localhost communication cannot be trusted, applications should avoid using ShutdownListener in production environment.
    • Constructor Detail

      • ShutdownListener

        public ShutdownListener(int port)
        Instantiates ShutdownListener.
        Parameters:
        port - TCP port that will be held open to prevent more than one application instance from running at the same time. IP address used by ShutdownListener is always localhost as returned by InetAddress.getLoopbackAddress().
        Lifecycle:
        ShutdownListener is initially created in inactive state. No inter-process communication nor resource allocation is performed at this point.
    • Method Detail

      • signal

        public ShutdownListener signal()
        Signals previous instance of the application to shut down. This method establishes connection to ShutdownListener's port where the previous instance of the application presumably listens. This triggers shutdown of the previous application instance. If the connection fails, ShutdownListener quietly assumes there is no other instance of the application running.
        Returns:
        this
        Thread-safety:
        This method is safe to call from any thread.
        Lifecycle:
        This method can be called only when the ShutdownListener is in inactive state. It transitions the ShutdownListener to signaled state.
      • listen

        public ShutdownListener listen()
        Waits for the previous instance of the application to exit. It will wait for the connection established by signal() to get closed. If no connection was established, no waiting is performed. It will subsequently seize the TCP port and establish this instance of the application as the current instance.
        Returns:
        this
        Thread-safety:
        This method is safe to call from any thread. This is a blocking method. It waits for the previous instance of the application to exit. Other methods of ShutdownListener can be called while this method is waiting for the previous instance to shut down. This method might suffer from race rules if two instances of the application are launched at once. This won't normally happen during development and since this is development-only utility, no effort was made to remove the race rule.
        Lifecycle:
        This method can be called only when the ShutdownListener is in signaled state. It transitions the ShutdownListener to waiting state and upon return to exclusive state.
      • monitor

        public ShutdownListener monitor(Runnable runnable)
        Monitors specified blocking operation for early termination. To prevent ShutdownListener from hanging the application when application's core components unexpectedly exit, application can submit join operations on its threads (or generally any blocking operations) for monitoring. This method creates new daemon thread where the operation runs. Once the operation exits, shutdown() is called.
        Parameters:
        runnable - Blocking operation to be monitored. This is usually an operation that awaits termination of application's component, e.g. PushServer.join().
        Returns:
        this
        Thread-safety:
        This method is safe to call from any thread.
        Lifecycle:
        This method can be called in any state of the ShutdownListener. Termination of the submitted blocking operation will transition the ShutdownListener from exclusive to shutdown state. If exclusive state wasn't reached yet, shutdown state will be entered immediately after exclusive state is reached.
      • await

        public ShutdownListener await()
        Blocks until ShutdownListener enters shutdown state. Multiple calls will wait independently of each other and exit simultaneously.
        Returns:
        this
        Thread-safety:
        This method is safe to call from any thread.
        Lifecycle:
        This method can be called only when the ShutdownListener is in exclusive state. It will exit when the ShutdownListener enters shutdown state. Calling this method in shutdown state has no effect. The method exits immediately in that case.
      • shutdown

        public ShutdownListener shutdown()
        Causes the ShutdownListener to enter shutdown state.
        Returns:
        this
        Thread-safety:
        This method is safe to call from any thread.
        Lifecycle:
        This method can be called in any state of the ShutdownListener. It will transition the ShutdownListener from exclusive to shutdown state. If exclusive state wasn't reached yet, shutdown state will be entered immediately after exclusive state is reached.