org.microbean.kubernetes.controller

Class Reflector<T extends HasMetadata>

java.lang.Object

org.microbean.kubernetes.controller.Reflector<T>

Type Parameters:

T - a type of Kubernetes resource

All Implemented Interfaces:

Closeable, AutoCloseable

@ThreadSafe
public class Reflector<T extends HasMetadata>
extends Object
implements Closeable

A pump of sorts that continuously "pulls" logical events out of Kubernetes and adds them to an EventCache so as to logically "reflect" the contents of Kubernetes into the cache.

Thread Safety

Instances of this class are safe for concurrent use by multiple Threads.

Design Notes

This class loosely models the Reflector type in the tools/cache package of the client-go subproject of Kubernetes.

Author:

Laird Nelson

See Also:

EventCache

Field Summary

Fields

Modifier and Type	Field and Description
protected Logger	logger A Logger for use by this Reflector.

Constructor Summary

Constructors

Constructor and Description
Reflector(X operation, EventCache<T> eventCache) Creates a new Reflector.
Reflector(X operation, EventCache<T> eventCache, Duration synchronizationInterval) Creates a new Reflector.
Reflector(X operation, EventCache<T> eventCache, ScheduledExecutorService synchronizationExecutorService, Duration synchronizationInterval) Creates a new Reflector.
Reflector(X operation, EventCache<T> eventCache, ScheduledExecutorService synchronizationExecutorService, Duration synchronizationInterval, Function<? super Throwable,Boolean> synchronizationErrorHandler) Creates a new Reflector.

Method Summary

Modifier and Type	Method and Description
void	close() Notionally closes this Reflector by terminating any Threads that it has started and invoking the onClose() method while holding this Reflector's monitor.
protected Logger	createLogger() Returns a Logger that will be used for this Reflector.
protected void	onClose() Invoked when close() is invoked.
protected boolean	shouldSynchronize() Returns whether, at any given moment, this Reflector should cause its EventCache to synchronize.
@NonBlocking Future<?>	start() Using the operation supplied at construction time, lists appropriate Kubernetes resources, and then, on a separate Thread, sets up a watch on them, calling EventCache.replace(Collection, Object) and EventCache.add(Object, AbstractEvent.Type, HasMetadata) methods as appropriate.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final Logger logger

A Logger for use by this Reflector.

This field is never null.

See Also:

createLogger()

Constructor Detail

Reflector

public Reflector(X operation,
                 EventCache<T> eventCache)

Creates a new Reflector.

Type Parameters:

X - a type that is both an appropriate kind of Listable and VersionWatchable, such as the kind of operation returned by DefaultKubernetesClient.configMaps() and the like

Parameters:

operation - a Listable and a VersionWatchable that can report information from a Kubernetes cluster; must not be null

eventCache - an EventCache that will be synchronized on and into which Events will be logically "reflected"; must not be null

Throws:

NullPointerException - if operation or eventCache is null

IllegalStateException - if the createLogger() method returns null

See Also:

Reflector(Listable, EventCache, ScheduledExecutorService, Duration, Function), start()

Reflector

public Reflector(X operation,
                 EventCache<T> eventCache,
                 Duration synchronizationInterval)

Creates a new Reflector.

Type Parameters:

X - a type that is both an appropriate kind of Listable and VersionWatchable, such as the kind of operation returned by DefaultKubernetesClient.configMaps() and the like

Parameters:

operation - a Listable and a VersionWatchable that can report information from a Kubernetes cluster; must not be null

eventCache - an EventCache that will be synchronized on and into which Events will be logically "reflected"; must not be null

synchronizationInterval - a Duration representing the time in between one synchronization operation and another; interpreted with a granularity of seconds; may be null or semantically equal to 0 seconds in which case no synchronization will occur

Throws:

NullPointerException - if operation or eventCache is null

IllegalStateException - if the createLogger() method returns null

See Also:

Reflector(Listable, EventCache, ScheduledExecutorService, Duration, Function), start()

Reflector

public Reflector(X operation,
                 EventCache<T> eventCache,
                 ScheduledExecutorService synchronizationExecutorService,
                 Duration synchronizationInterval)

Creates a new Reflector.

Type Parameters:

X - a type that is both an appropriate kind of Listable and VersionWatchable, such as the kind of operation returned by DefaultKubernetesClient.configMaps() and the like

Parameters:

operation - a Listable and a VersionWatchable that can report information from a Kubernetes cluster; must not be null

eventCache - an EventCache that will be synchronized on and into which Events will be logically "reflected"; must not be null

synchronizationExecutorService - a ScheduledExecutorService to be used to tell the supplied EventCache to synchronize on a schedule; may be null in which case no synchronization will occur

synchronizationInterval - a Duration representing the time in between one synchronization operation and another; may be null in which case no synchronization will occur

Throws:

NullPointerException - if operation or eventCache is null

IllegalStateException - if the createLogger() method returns null

See Also:

Reflector(Listable, EventCache, ScheduledExecutorService, Duration, Function), start()

Reflector

public Reflector(X operation,
                 EventCache<T> eventCache,
                 ScheduledExecutorService synchronizationExecutorService,
                 Duration synchronizationInterval,
                 Function<? super Throwable,Boolean> synchronizationErrorHandler)

Creates a new Reflector.

Type Parameters:

X - a type that is both an appropriate kind of Listable and VersionWatchable, such as the kind of operation returned by DefaultKubernetesClient.configMaps() and the like

Parameters:

operation - a Listable and a VersionWatchable that can report information from a Kubernetes cluster; must not be null

eventCache - an EventCache that will be synchronized on and into which Events will be logically "reflected"; must not be null

synchronizationExecutorService - a ScheduledExecutorService to be used to tell the supplied EventCache to synchronize on a schedule; may be null in which case no synchronization will occur

synchronizationInterval - a Duration representing the time in between one synchronization operation and another; may be null in which case no synchronization will occur

synchronizationErrorHandler - a Function that consumes a Throwable and returns a Boolean indicating whether the error represented by the Throwable in question was handled or not; may be null

Throws:

NullPointerException - if operation or eventCache is null

IllegalStateException - if the createLogger() method returns null

See Also:

start()

Method Detail

createLogger

protected Logger createLogger()

Returns a Logger that will be used for this Reflector.

This method never returns null.

Overrides of this method must not return null.

Returns:

a non-null Logger

close

public final void close()
                 throws IOException

Notionally closes this Reflector by terminating any Threads that it has started and invoking the onClose() method while holding this Reflector's monitor.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if an error occurs

See Also:

onClose()

shouldSynchronize

protected boolean shouldSynchronize()

Returns whether, at any given moment, this Reflector should cause its EventCache to synchronize.

The default implementation of this method returns true if this Reflector was constructed with an explicit synchronization interval or ScheduledExecutorService or both.

Design Notes

This code follows the Go code in the Kubernetes client-go/tools/cache package. One thing that becomes clear when looking at all of this through an object-oriented lens is that it is the EventCache (the delta_fifo, in the Go code) that is ultimately in charge of synchronizing. It is not clear why in the Go code this is a function of a reflector. In an object-oriented world, perhaps the EventCache itself should be in charge of resynchronization schedules, but we choose to follow the Go code's division of responsibilities here.

Returns:

true if this Reflector should cause its EventCache to synchronize; false otherwise

start

@NonBlocking
public final @NonBlocking Future<?> start()
                                                throws IOException

Using the operation supplied at construction time, lists appropriate Kubernetes resources, and then, on a separate Thread, sets up a watch on them, calling EventCache.replace(Collection, Object) and EventCache.add(Object, AbstractEvent.Type, HasMetadata) methods as appropriate.

For convenience only, this method returns a Future representing any scheduled synchronization task created as a result of the user's having supplied a Duration at construction time. The return value may be (and usually is) safely ignored. Invoking Future.cancel(boolean) on the returned Future will result in the scheduled synchronization task being cancelled irrevocably. Notably, invoking Future.cancel(boolean) on the returned Future will not close this Reflector.

This method never returns null.

The calling Thread is not blocked by invocations of this method.

Implementation Notes

This method loosely models the Run function in reflector.go together with the ListAndWatch function in the same file.

Returns:

a Future representing a scheduled synchronization operation; never null

Throws:

IOException - if a watch has previously been established and could not be closed

KubernetesClientException - if the initial attempt to list Kubernetes resources fails

See Also:

close()

onClose

protected void onClose()

Invoked when close() is invoked.

The default implementation of this method does nothing.

Overrides of this method must consider that they will be invoked with this Reflector's monitor held.

Overrides of this method must not call the close() method.

See Also:

close()