Package org.dellroad.stuff.net

Class PersistentConnection<C>

java.lang.Object
org.dellroad.stuff.net.PersistentConnection<C>
Type Parameters:
C - connection context type
Direct Known Subclasses:
PersistentSocketConnection
public abstract class PersistentConnection<C> extends Object
Support superclass for clients that want to maintain a persistent connection to some server.

This class is suitable for use with any abstract notion of "client", "server", and "connection". Typically it would be used to maintain a persistent connection to a remote server over the network. This class mainly serves to implement the connection state machine, including an exponential back-off retry timer, subclass notifications for state transitions, and guaranteed thread safety.

Each instance has a dedicated thread that manages the connection and performs any required work while connected. The lifecycle of a connection is delimited by calls (by this thread) to the subclass methods createConnection() and cleanupConnection(). The actual per-connection work is performed by handleConnection(). Each connection has an associated connection context (defined by the subclass) and passed to these methods.

The subclass is also notified of state machine transitions via the state transition methods started(), stopped(), connectionSuccessful(), connectionFailed(), and connectionEnded(); all of these methods are invoked by the background thread.

  • Field Details

  • Constructor Details

    • PersistentConnection

      public PersistentConnection()

  • Method Details

    • setMinRestartDelay

      public void setMinRestartDelay(long minRestartDelay)
      Set the minimum restart delay after being disconnected from the server. Default is DEFAULT_MIN_RESTART_DELAY (10000L}ms).
      Parameters:
      minRestartDelay - minimum restart delay in milliseconds

    • getMinRestartDelay

      public long getMinRestartDelay()

    • setMaxRestartDelay

      public void setMaxRestartDelay(long maxRestartDelay)
      Set the maximum restart delay after being disconnected from the server. Default is DEFAULT_MAX_RESTART_DELAY (600000L}ms).
      Parameters:
      maxRestartDelay - maximum restart delay in milliseconds

    • getMaxRestartDelay

      public long getMaxRestartDelay()

    • getThreadName

      protected String getThreadName()
      Get the name to use for the network client thread.

      The implementation in PersistentConnection returns this.toString() + " thread".

      Returns:
      network client thread name

    • start

      public void start()
      Start this instance. This starts the background thread, which initiates the first connection attempt.

      If this instance is already started, nothing happens.

    • stop

      public void stop()
      Stop this client.

      This method simply interrupts the background thread, if any.

    • isRunning

      public final boolean isRunning()
      Determine if this instance is started.
      Returns:
      true if this instance is currently running

    • createConnection

      protected abstract C createConnection() throws InterruptedException, IOException
      Create a new server connection.

      If this method throws an unchecked exception, stopped() will be invoked with the exception and this instance will be automatically stopped.

      Returns:
      context for the connection, which will be supplied to handleConnection() and cleanupConnection()
      Throws:
      InterruptedException - if interrupted
      IOException - if there is a problem establishing the connection

    • handleConnection

      protected abstract void handleConnection(C connectionContext) throws InterruptedException, IOException
      Handle one server connection.

      This method may either throw an exception or return normally; the only difference is whether connectionEnded() is invoked with a non-null parameter or not.

      Ideally this method should never return normally. However, in practice there are legitimate reasons to do so, for example, if there is an application-level error that indicates the particular connection is no longer usable.

      If this method throws an unchecked exception, stopped() will be invoked with the exception and this instance will be automatically stopped.

      Parameters:
      connectionContext - connection context returned from createConnection() when this connection was created
      Throws:
      InterruptedException - if interrupted
      IOException - if there is a problem during the connection or the connection fails

    • cleanupConnection

      protected void cleanupConnection(C connectionContext)
      Perform cleanup after a server connection ends. This method should close any open sockets, etc.

      For each successful invocation of createConnection() there is guaranteed be exactly one invocation of this method.

      The exception parameter indicates either a normal return (if null) or thrown exception (if not null) from handleConnection(). In any case, this instance will automatically begin attempting to reconnect when this method returns.

      If this method throws an unchecked exception, stopped() will be invoked with the exception and this instance will be automatically stopped.

      The implementation in PersistentConnection does nothing. Subclasses should override if necessary.

      Parameters:
      connectionContext - connection context returned from createConnection() when this connection was created

    • started

      protected void started()
      State machine transition: this instance was started via start().

      The implementation in PersistentConnection does nothing; subclasses may override.

    • stopped

      protected void stopped(Throwable t)
      State machine transition: this instance was stopped via stop() of because or an unchecked exception was thrown by one of the subclass methods.

      The implementation in PersistentConnection does nothing; subclasses may override.

      Parameters:
      t - unexpected exception, or null if this instance was stopped via stop().

    • connectionSuccessful

      protected void connectionSuccessful()
      State machine transition: initialization of a new connection via createConnection() was successful and we are connected to the server.

      The implementation in PersistentConnection does nothing; subclasses may override.

    • connectionFailed

      protected void connectionFailed(Exception e)
      State machine transition: initialization of a new connection via createConnection() failed due to an exception. This instance will automatically attempt to retry.

      The implementation in PersistentConnection does nothing; subclasses may override.

      Parameters:
      e - Exception thrown by createConnection().

    • connectionEnded

      protected void connectionEnded(Exception e)
      State machine transition: an established connection to the server has ended. This indicates either normal return or a thrown an exception from handleConnection(). This instance will automatically attempt to reconnect.

      The implementation in PersistentConnection does nothing; subclasses may override.

      Parameters:
      e - Exception thrown by handleConnection(), or null if handleConnection() returned normally