Class ConnectionStateMachine

java.lang.Object
express.mvp.myra.transport.lifecycle.ConnectionStateMachine
public final class ConnectionStateMachine extends Object
Thread-safe state machine for managing connection lifecycle.

This class enforces valid state transitions and notifies listeners of state changes. It provides a robust foundation for connection management with proper state validation.

Valid Transitions

NEW        → CONNECTING, CLOSED
CONNECTING → CONNECTED, FAILED, CLOSING
CONNECTED  → CLOSING, FAILED
FAILED     → CONNECTING, CLOSED
CLOSING    → CLOSED
CLOSED     → (terminal, no transitions)

Usage Example

ConnectionStateMachine state = new ConnectionStateMachine();

// Add listener for state changes
state.addListener((prev, curr, cause) -> {
    logger.info("State: {} -> {}", prev, curr);
});

// Connection flow
state.transitionTo(ConnectionState.CONNECTING);     // Start connection
state.transitionTo(ConnectionState.CONNECTED);      // Success

// ... later ...
state.transitionTo(ConnectionState.CLOSING);        // Graceful close
state.transitionTo(ConnectionState.CLOSED);         // Complete

Thread Safety

All methods are thread-safe. State transitions use atomic operations to ensure consistency even with concurrent access.

See Also:

  • Constructor Details

    • ConnectionStateMachine

      public ConnectionStateMachine()
      Creates a new state machine in ConnectionState.NEW state.

    • ConnectionStateMachine

      public ConnectionStateMachine(String connectionId)
      Creates a new state machine with an identifier.
      Parameters:
      connectionId - identifier for this connection

  • Method Details

    • getState

      public ConnectionState getState()
      Returns the current state.
      Returns:
      the current connection state

    • getConnectionId

      public String getConnectionId()
      Returns the connection identifier.
      Returns:
      the connection ID, or null if not set

    • setConnectionId

      public void setConnectionId(String connectionId)
      Sets the connection identifier.
      Parameters:
      connectionId - the identifier

    • isActive

      public boolean isActive()
      Checks if the connection is active.
      Returns:
      true if in ConnectionState.CONNECTED state

    • isClosedOrClosing

      public boolean isClosedOrClosing()
      Checks if the connection is closed or closing.
      Returns:
      true if in CLOSING or CLOSED state

    • isClosed

      public boolean isClosed()
      Checks if the connection is fully closed.
      Returns:
      true if in CLOSED state

    • addListener

      public void addListener(ConnectionStateListener listener)
      Registers a listener for state change events.
      Parameters:
      listener - the listener to register

    • removeListener

      public boolean removeListener(ConnectionStateListener listener)
      Removes a previously registered listener.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed

    • transitionTo

      public boolean transitionTo(ConnectionState newState)
      Attempts to transition to a new state.

      The transition succeeds only if it's a valid transition from the current state. Listeners are notified on successful transition.

      Parameters:
      newState - the desired new state
      Returns:
      true if the transition was successful

    • transitionTo

      public boolean transitionTo(ConnectionState newState, Throwable cause)
      Attempts to transition to a new state with a cause.

      The cause is passed to listeners and is typically used for failure transitions.

      Parameters:
      newState - the desired new state
      cause - the reason for the transition (may be null)
      Returns:
      true if the transition was successful

    • transitionFrom

      public boolean transitionFrom(ConnectionState expectedState, ConnectionState newState)
      Attempts to transition from a specific expected state.

      This is useful for conditional transitions where you want to ensure the current state hasn't changed since you checked it.

      Parameters:
      expectedState - the expected current state
      newState - the desired new state
      Returns:
      true if transition successful, false if current state doesn't match

    • transitionFrom

      public boolean transitionFrom(ConnectionState expectedState, ConnectionState newState, Throwable cause)
      Attempts to transition from a specific expected state with a cause.
      Parameters:
      expectedState - the expected current state
      newState - the desired new state
      cause - the reason for the transition (may be null)
      Returns:
      true if transition successful

    • forceState

      public void forceState(ConnectionState newState, Throwable cause)
      Forces a transition to a state, bypassing validation.

      Warning: This should only be used in exceptional circumstances, such as error recovery. Normal code should use transitionTo(ConnectionState).

      Parameters:
      newState - the state to force
      cause - the reason for forced transition

    • isValidTransition

      public static boolean isValidTransition(ConnectionState from, ConnectionState to)
      Checks if a transition from one state to another is valid.
      Parameters:
      from - the source state
      to - the target state
      Returns:
      true if the transition is allowed

    • getValidTransitions

      public static Set<ConnectionState> getValidTransitions(ConnectionState from)
      Returns the set of valid target states from a given state.
      Parameters:
      from - the source state
      Returns:
      set of valid target states

    • toString

      public String toString()
      Overrides:
      toString in class Object