software.amazon.jdbc.hostlistprovider

Interface MonitoringConnectionHandler

All Superinterfaces:

StateSnapshotProvider

All Known Implementing Classes:

AbstractMonitoringConnectionHandler, AuroraMonitoringConnectionHandler, GdbMonitoringConnectionHandler

public interface MonitoringConnectionHandler
extends StateSnapshotProvider

Handles monitoring connection lifecycle: accepting connections offered by the monitor, and asynchronously upgrading to a higher-priority connection when possible.

Method Summary

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.

Methods inherited from interface software.amazon.jdbc.util.StateSnapshotProvider

getSnapshotState

Method Detail

acceptConnection

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). The handler decides whether to accept it as the monitoring connection or open a different one that better matches the configured priority.

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

@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. 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.

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

void attemptConnectionUpgrade(java.util.List<HostSpec> currentTopology)

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.

Parameters:

currentTopology - the current cluster topology

close

void close()

Cleans up resources: cancels pending upgrade attempts and closes any connections held by the handler.