AbstractMonitoringConnectionHandler (aws-advanced-jdbc-wrapper 4.3.0 API)

java.lang.Object
- software.amazon.jdbc.hostlistprovider.AbstractMonitoringConnectionHandler<P>

Type Parameters:

P - the concrete priority type (e.g., MonitoringConnectionPriority or GdbMonitoringConnectionPriority). The type's toString() should return a stable human-readable label for snapshot logging.

All Implemented Interfaces:

MonitoringConnectionHandler, StateSnapshotProvider

Direct Known Subclasses:

AuroraMonitoringConnectionHandler, GdbMonitoringConnectionHandler
```
public abstract class AbstractMonitoringConnectionHandler<P>
extends java.lang.Object
implements MonitoringConnectionHandler
```
Base implementation of MonitoringConnectionHandler that handles the connection-priority lifecycle (accept, batch-accept, async upgrade, close). Concrete subclasses provide the priority-evaluation hooks specific to their priority model (Aurora vs. Global Aurora).

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`currentPriorityIndex`
`protected AtomicConnection`	`monitoringConnection`
`protected java.util.Properties`	`monitoringProperties`
`protected PluginService`	`pluginService`
`protected java.util.List<P>`	`priorities`
`protected TopologyUtils`	`topologyUtils`
`protected @Nullable HostSpec`	`upgradeConnectedHost`
`protected AtomicConnection`	`upgradeConnection`
`protected @Nullable java.util.concurrent.ExecutorService`	`upgradeExecutor`
`protected @Nullable java.util.concurrent.Future<?>`	`upgradeFuture`
`protected @Nullable java.lang.Runnable`	`upgradeReadyNotifier`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractMonitoringConnectionHandler(AtomicConnection monitoringConnection, PluginService pluginService, TopologyUtils topologyUtils, java.util.Properties monitoringProperties, java.util.List<P> priorities, @Nullable java.lang.Runnable upgradeReadyNotifier)`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`acceptConnection(java.sql.Connection conn, boolean isWriter, HostSpec hostSpec)` Called when a connection is offered to the handler (e.g., a writer connection found during panic mode).
`@Nullable HostSpec`	`acceptConnections(java.util.Map<HostSpec,AtomicConnection> connections, @Nullable HostSpec writerHostSpec, @Nullable java.util.List<HostSpec> topology)` Offers a batch of harvested connections (e.g., from node monitoring threads after panic mode resolves) to the handler.
`void`	`attemptConnectionUpgrade(java.util.List<HostSpec> currentTopology)` Non-blocking attempt to upgrade the monitoring connection to a higher-priority node.
`void`	`close()` Cleans up resources: cancels pending upgrade attempts and closes any connections held by the handler.
`protected static int`	`effectiveIndex(int priorityIndex)`
`protected abstract java.util.List<HostSpec>`	`findHostsForPriority(int priorityIndex, java.util.List<HostSpec> hosts)` Returns all hosts in `hosts` that match the priority at `priorityIndex` of `priorities`.
`protected java.util.List<java.util.List<HostSpec>>`	`findUpgradeCandidates(java.util.List<HostSpec> hosts)` Returns candidates grouped by priority, with the highest priority bucket first.
`protected static java.lang.String`	`formatPriorityIndex(int index)` Formats a priority index for logging.
`protected @Nullable java.util.List<Pair<java.lang.String,java.lang.Object>>`	`getAdditionalSnapshotState()` Hook for subclasses to publish additional snapshot state (e.g., GDB primary region).
`protected abstract int`	`getPriorityIndex(HostSpec host, boolean isWriter)` Returns the index into `priorities` that the given host satisfies, or `-1` if no priority matches.
`java.util.List<Pair<java.lang.String,java.lang.Object>>`	`getSnapshotState()`
`protected abstract java.lang.String`	`getUpgradeThreadName()` Returns the thread-name prefix used for the async upgrade executor (e.g., `"atmu"` or `"gatmu"`).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - monitoringConnection
```
protected final AtomicConnection monitoringConnection
```
  - upgradeConnection
```
protected final AtomicConnection upgradeConnection
```
  - pluginService
```
protected final PluginService pluginService
```
  - topologyUtils
```
protected final TopologyUtils topologyUtils
```
  - monitoringProperties
```
protected final java.util.Properties monitoringProperties
```
  - priorities
```
protected final java.util.List<P> priorities
```
  - upgradeReadyNotifier
```
protected final @Nullable java.lang.Runnable upgradeReadyNotifier
```
  - currentPriorityIndex
```
protected int currentPriorityIndex
```
  - upgradeFuture
```
protected volatile @Nullable java.util.concurrent.Future<?> upgradeFuture
```
  - upgradeConnectedHost
```
protected volatile @Nullable HostSpec upgradeConnectedHost
```
  - upgradeExecutor
```
protected @Nullable java.util.concurrent.ExecutorService upgradeExecutor
```
- Constructor Detail
  - AbstractMonitoringConnectionHandler
```
protected AbstractMonitoringConnectionHandler(AtomicConnection monitoringConnection,
                                              PluginService pluginService,
                                              TopologyUtils topologyUtils,
                                              java.util.Properties monitoringProperties,
                                              java.util.List<P> priorities,
                                              @Nullable java.lang.Runnable upgradeReadyNotifier)
```
- Method Detail
  - getPriorityIndex
```
protected abstract int getPriorityIndex(HostSpec host,
                                        boolean isWriter)
```
    Returns the index into priorities that the given host satisfies, or -1 if no priority matches. The lowest-index match wins.
    
    Parameters:
    
    host - the host being considered
    
    isWriter - whether the connection is to a writer
  - findHostsForPriority
```
protected abstract java.util.List<HostSpec> findHostsForPriority(int priorityIndex,
                                                                 java.util.List<HostSpec> hosts)
```
    Returns all hosts in hosts that match the priority at priorityIndex of priorities.
  - getUpgradeThreadName
```
protected abstract java.lang.String getUpgradeThreadName()
```
    Returns the thread-name prefix used for the async upgrade executor (e.g., "atmu" or "gatmu").
  - getAdditionalSnapshotState
```
protected @Nullable java.util.List<Pair<java.lang.String,java.lang.Object>> getAdditionalSnapshotState()
```
    Hook for subclasses to publish additional snapshot state (e.g., GDB primary region). Returns null when none.
  - formatPriorityIndex
```
protected static java.lang.String formatPriorityIndex(int index)
```
    Formats a priority index for logging. Integer.MAX_VALUE is shown as <none> to avoid confusing users with a 10-digit number.
  - effectiveIndex
```
protected static int effectiveIndex(int priorityIndex)
```
  - acceptConnection
```
public boolean acceptConnection(java.sql.Connection conn,
                                boolean isWriter,
                                HostSpec hostSpec)
```
    Description copied from interface: MonitoringConnectionHandler
    
    Called when a connection is offered to the handler (e.g., a writer connection found during panic mode). The handler decides whether to accept it as the monitoring connection or open a different one that better matches the configured priority.
    
    Specified by:
    
    acceptConnection in interface MonitoringConnectionHandler
    
    Parameters:
    
    conn - the offered connection
    
    isWriter - true if the connection is to a writer instance
    
    hostSpec - the host spec of the connection
    
    Returns:
    
    true if the connection was accepted and set as the monitoring connection, false if the connection was rejected (caller should close it)
  - acceptConnections
```
public @Nullable HostSpec acceptConnections(java.util.Map<HostSpec,AtomicConnection> connections,
                                            @Nullable HostSpec writerHostSpec,
                                            @Nullable java.util.List<HostSpec> topology)
```
    Description copied from interface: MonitoringConnectionHandler
    
    Offers a batch of harvested connections (e.g., from node monitoring threads after panic mode resolves) to the handler. The handler picks the best one according to its priority list and sets it as the monitoring connection. Connections that were not selected are returned in the result so the caller can dispose of them appropriately.
    The handler determines each connection's role from the topology (the writer host is known) — readers are everything else. The handler may also use the host's region for region-aware priorities.
    
    Specified by:
    
    acceptConnections in interface MonitoringConnectionHandler
    
    Parameters:
    
    connections - a map of host -> connection harvested from node threads
    
    writerHostSpec - the host spec of the writer (if known)
    
    topology - the current topology, used for region/role context
    
    Returns:
    
    the host of the connection that was selected and set as the monitoring connection, or null if no connection was selected
  - attemptConnectionUpgrade
```
public void attemptConnectionUpgrade(java.util.List<HostSpec> currentTopology)
```
    Description copied from interface: MonitoringConnectionHandler
    
    Non-blocking attempt to upgrade the monitoring connection to a higher-priority node. If the current connection already satisfies the highest priority, this is a no-op. Otherwise, it checks for completed async upgrade attempts and submits new ones as needed.
    
    Specified by:
    
    attemptConnectionUpgrade in interface MonitoringConnectionHandler
    
    Parameters:
    
    currentTopology - the current cluster topology
  - close
```
public void close()
```
    Description copied from interface: MonitoringConnectionHandler
    
    Cleans up resources: cancels pending upgrade attempts and closes any connections held by the handler.
    
    Specified by:
    
    close in interface MonitoringConnectionHandler
  - findUpgradeCandidates
```
protected java.util.List<java.util.List<HostSpec>> findUpgradeCandidates(java.util.List<HostSpec> hosts)
```
    Returns candidates grouped by priority, with the highest priority bucket first. The caller is responsible for shuffling each bucket before iterating, so that different hosts within the same priority are tried first on different upgrade cycles.
  - getSnapshotState
```
public java.util.List<Pair<java.lang.String,java.lang.Object>> getSnapshotState()
```
    Specified by:
    
    getSnapshotState in interface StateSnapshotProvider

Class AbstractMonitoringConnectionHandler<P>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

monitoringConnection

upgradeConnection

pluginService

topologyUtils

monitoringProperties

priorities

upgradeReadyNotifier

currentPriorityIndex

upgradeFuture

upgradeConnectedHost

upgradeExecutor

Constructor Detail

AbstractMonitoringConnectionHandler

Method Detail

getPriorityIndex

findHostsForPriority

getUpgradeThreadName

getAdditionalSnapshotState

formatPriorityIndex

effectiveIndex

acceptConnection

acceptConnections

attemptConnectionUpgrade

close

findUpgradeCandidates

getSnapshotState