software.amazon.jdbc.util.monitoring

Interface MonitorService

All Superinterfaces:

StateSnapshotProvider

All Known Implementing Classes:

MonitorServiceImpl

public interface MonitorService
extends StateSnapshotProvider

Method Summary

Modifier and Type	Method and Description
<T extends Monitor> T	get(java.lang.Class<T> monitorClass, @NonNull java.lang.Object key) Gets the monitor stored at the given key.
<T extends Monitor> void	registerMonitorTypeIfAbsent(java.lang.Class<T> monitorClass, long expirationTimeoutNanos, long heartbeatTimeoutNanos, java.util.EnumSet<MonitorErrorResponse> errorResponses, @Nullable java.lang.Class<?> producedDataClass) Registers a new monitor type with the monitor service.
void	releaseResources() Releases any resources opened by the monitor service, stops all monitors, and removes all monitors from the monitor service.
<T extends Monitor> T	remove(java.lang.Class<T> monitorClass, java.lang.Object key) Removes the monitor stored at the given key.
<T extends Monitor> T	runIfAbsent(java.lang.Class<T> monitorClass, java.lang.Object key, FullServicesContainer servicesContainer, java.util.Properties originalProps, MonitorInitializer initializer) Creates and starts the given monitor if it does not already exist and stores it under the given monitor type and key.
<T extends Monitor> T	runIfAbsent(java.lang.Class<T> monitorClass, java.lang.Object key, StorageService storageService, EventPublisher eventPublisher, TelemetryFactory telemetryFactory, ConnectionProvider defaultConnectionProvider, java.lang.String originalUrl, java.lang.String driverProtocol, TargetDriverDialect driverDialect, Dialect dbDialect, java.util.Properties originalProps, @Nullable ConfigurationProfile configurationProfile, MonitorInitializer initializer) Creates and starts the given monitor if it does not already exist and stores it under the given monitor type and key.
<T extends Monitor> void	stopAndRemove(java.lang.Class<T> monitorClass, java.lang.Object key) Stops the given monitor and removes it from the monitor service.
void	stopAndRemoveAll() Stops all monitors and removes them from the monitor service.
<T extends Monitor> void	stopAndRemoveMonitors(java.lang.Class<T> monitorClass) Stops all monitors for the given type and removes them from the monitor service.

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

getSnapshotState

Method Detail

registerMonitorTypeIfAbsent

<T extends Monitor> void registerMonitorTypeIfAbsent(java.lang.Class<T> monitorClass,
                                                     long expirationTimeoutNanos,
                                                     long heartbeatTimeoutNanos,
                                                     java.util.EnumSet<MonitorErrorResponse> errorResponses,
                                                     @Nullable java.lang.Class<?> producedDataClass)

Registers a new monitor type with the monitor service. This method needs to be called before adding new types of monitors to the monitor service, so that the monitor service knows when to dispose of a monitor. Expected monitor types will be added automatically during driver initialization, but this method can be called by users if they want to add a new monitor type.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the class of the monitor, eg `CustomEndpointMonitorImpl.class`.

expirationTimeoutNanos - how long a monitor should be stored without use before being considered expired, in nanoseconds. Expired monitors may be removed and stopped.

heartbeatTimeoutNanos - a duration in nanoseconds defining the maximum amount of time that a monitor should take between updating its last-updated timestamp. If a monitor has not updated its last-updated timestamp within this duration it will be considered stuck.

errorResponses - a EnumSet defining actions to take if the monitor is stuck or in an error state.

producedDataClass - the class of data produced by the monitor.

runIfAbsent

<T extends Monitor> T runIfAbsent(java.lang.Class<T> monitorClass,
                                  java.lang.Object key,
                                  FullServicesContainer servicesContainer,
                                  java.util.Properties originalProps,
                                  MonitorInitializer initializer)
                           throws java.sql.SQLException

Creates and starts the given monitor if it does not already exist and stores it under the given monitor type and key. If the monitor already exists, its expiration time will be renewed, even if it was already expired.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the concrete class of the monitor, eg `CustomEndpointMonitorImpl.class`.

key - the key for the monitor, eg "custom-endpoint.cluster-custom-XYZ.us-east-2.rds.amazonaws.com:5432".

servicesContainer - the source service container for the monitor. The new monitor will create its own service container but will reuse some components from the source container.

originalProps - the properties of the original database connection.

initializer - an initializer function to use to create the monitor if it does not already exist.

Returns:

the new or existing monitor.

Throws:

java.sql.SQLException - if an error occurs while trying to create the monitor.

runIfAbsent

<T extends Monitor> T runIfAbsent(java.lang.Class<T> monitorClass,
                                  java.lang.Object key,
                                  StorageService storageService,
                                  EventPublisher eventPublisher,
                                  TelemetryFactory telemetryFactory,
                                  ConnectionProvider defaultConnectionProvider,
                                  java.lang.String originalUrl,
                                  java.lang.String driverProtocol,
                                  TargetDriverDialect driverDialect,
                                  Dialect dbDialect,
                                  java.util.Properties originalProps,
                                  @Nullable ConfigurationProfile configurationProfile,
                                  MonitorInitializer initializer)
                           throws java.sql.SQLException

Creates and starts the given monitor if it does not already exist and stores it under the given monitor type and key. If the monitor already exists, its expiration time will be renewed, even if it was already expired.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the concrete class of the monitor, eg `CustomEndpointMonitorImpl.class`.

key - the key for the monitor, eg "custom-endpoint.cluster-custom-XYZ.us-east-2.rds.amazonaws.com:5432".

storageService - the storage service for the monitor to use.

eventPublisher - the event publisher for the monitor to use.

telemetryFactory - the telemetry factory for creating telemetry data.

defaultConnectionProvider - the connection provider to use to create new connections if the monitor requires it.

originalUrl - the URL of the original database connection.

driverProtocol - the protocol for the underlying target driver.

driverDialect - the target driver dialect.

dbDialect - the database dialect.

originalProps - the properties of the original database connection.

configurationProfile - the configuration profile to use for the monitor.

initializer - an initializer function to use to create the monitor if it does not already exist.

Returns:

the new or existing monitor.

Throws:

java.sql.SQLException - if an error occurs while trying to create the monitor.

get

<T extends Monitor> T get(java.lang.Class<T> monitorClass,
                          @NonNull java.lang.Object key)

Gets the monitor stored at the given key.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the expected class of the monitor.

key - the key for the monitor.

Returns:

the monitor stored at the given key.

remove

<T extends Monitor> T remove(java.lang.Class<T> monitorClass,
                             java.lang.Object key)

Removes the monitor stored at the given key. If the expected monitor class does not match the actual monitor class no action will be performed.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the expected class of the monitor.

key - the key for the monitor.

Returns:

the monitor that was removed. Returns null if there was no monitor at the given key or the expected monitor class did not match the actual monitor class.

stopAndRemove

<T extends Monitor> void stopAndRemove(java.lang.Class<T> monitorClass,
                                       java.lang.Object key)

Stops the given monitor and removes it from the monitor service.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the class of the monitor, eg `CustomEndpointMonitorImpl.class`.

key - the key for the monitor, eg "custom-endpoint.cluster-custom-XYZ.us-east-2.rds.amazonaws.com:5432".

stopAndRemoveMonitors

<T extends Monitor> void stopAndRemoveMonitors(java.lang.Class<T> monitorClass)

Stops all monitors for the given type and removes them from the monitor service.

Type Parameters:

T - the type of the monitor.

Parameters:

monitorClass - the class of the monitor, eg `CustomEndpointMonitorImpl.class`.

stopAndRemoveAll

void stopAndRemoveAll()

Stops all monitors and removes them from the monitor service.

releaseResources

void releaseResources()

Releases any resources opened by the monitor service, stops all monitors, and removes all monitors from the monitor service.