Package io.github.flink.gcp.connector.base.source

Class StartPositionResolver

java.lang.Object

io.github.flink.gcp.connector.base.source.StartPositionResolver

@Internal
public final class StartPositionResolver
extends Object

Resolves change-stream start positions against one startup instant and one retention window.

The retention lookup is lazy: a fresh StartPosition.latest() needs no retention permission or service call. Every other fresh position and every restored position needs the computed earliest instant, so the lookup runs once and its result is reused. The one-minute safety margin keeps the first read away from a retention boundary that continues moving between resolution and admission by the service.

A connector creates one resolver when its enumerator starts and passes the enumerator class as the log owner. Warnings then remain under the connector's logger category rather than this shared helper's category.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	StartPositionResolver.RestoreExpiry	The retained-window evidence for one expired restored partition.
static interface	StartPositionResolver.RetentionLookup	Discovers how long a connector's change stream retains records.

Method Summary

Modifier and Type	Method	Description
static StartPositionResolver	create(Class<?> logOwner, StartPositionResolver.RetentionLookup retentionLookup)	Creates a resolver whose startup instant is the current UTC instant.
Optional<StartPositionResolver.RestoreExpiry>	inspectRestored(String partition, Instant restoredPosition)	Inspects one restored partition without choosing how the connector recovers from expiry.
Instant	resolve(StartPosition requested)	Resolves the position configured for a fresh start.
Instant	resolveFallback(StartPosition fallback)	Resolves an explicitly configured restore fallback without emitting a fresh-start warning.
Optional<Instant>	resolveRestored(String partition, Instant restoredPosition, StartPosition fallback)	Checks one restored partition against the retained window.
static void	validateRetention(Duration retention, String name)	Validates a retention duration against the resolver's moving-boundary safety margin.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

validateRetention

public static void validateRetention(Duration retention,
 String name)

Validates a retention duration against the resolver's moving-boundary safety margin.

create

public static StartPositionResolver create(Class<?> logOwner,
 StartPositionResolver.RetentionLookup retentionLookup)

Creates a resolver whose startup instant is the current UTC instant.

Parameters:

logOwner - the connector class whose logger should carry resolution warnings

retentionLookup - the connector-specific retention lookup

Returns:

a resolver for one enumerator startup

resolve

public Instant resolve(StartPosition requested)
                throws Exception

Resolves the position configured for a fresh start.

An absolute position in the future is rejected. A position before the computed earliest is clamped to the earliest and reported as a warning naming the unavailable range.

Parameters:

requested - the configured start position

Returns:

the absolute instant to start reading at

Throws:

Exception - if retention discovery fails

resolveRestored

public Optional<Instant> resolveRestored(String partition,
 Instant restoredPosition,
 @Nullable
 StartPosition fallback)
                                  throws Exception

Checks one restored partition against the retained window.

An empty result means the restored state remains valid and must win over the configured fresh-start position. A present result means the state expired and the affected partition must restart at the returned, resolved fallback position. Without a fallback, expiry fails the job rather than silently advancing over unavailable records.

Parameters:

partition - the connector's stable description of the restored partition

restoredPosition - the partition's checkpointed read position or low watermark

fallback - the explicitly configured fallback, or null when none was configured

Returns:

empty to retain restored state, or the fallback instant to restart from

Throws:

Exception - if retention discovery fails

inspectRestored

public Optional<StartPositionResolver.RestoreExpiry> inspectRestored(String partition,
 Instant restoredPosition)
                                                              throws Exception

Inspects one restored partition without choosing how the connector recovers from expiry.

Most connectors can use resolveRestored(java.lang.String, java.time.Instant, io.github.flink.gcp.connector.base.source.StartPosition) directly. A connector whose partition topology must be restarted as one unit can inspect every unfinished partition first and then make one recovery decision for the whole ledger.

Parameters:

partition - the connector's stable description of the restored partition

restoredPosition - the partition's checkpointed read position or low watermark

Returns:

the expiry details, or empty when the position remains retained

Throws:

Exception - if retention discovery fails

resolveFallback

public Instant resolveFallback(StartPosition fallback)
                        throws Exception

Resolves an explicitly configured restore fallback without emitting a fresh-start warning.

Throws:

Exception