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.

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.

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.
void	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), 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), 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:

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.

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 this is a function of a reflector. In an object-oriented world, perhaps the EventCache itself should be in charge of resynchronization schedules.

Returns:

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

start

@NonBlocking
public final void 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.

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

See Also:

close()

onClose

protected void onClose()

Invoked when close() is invoked.

The default implementation of this method does nothing.