org.microbean.kubernetes.controller

Class Controller<T extends HasMetadata>

java.lang.Object

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

Type Parameters:

T - a Kubernetes resource type

All Implemented Interfaces:

Closeable, AutoCloseable

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

A convenient combination of a Reflector, a VersionWatchable and Listable implementation, an (internal) EventQueueCollection, a Map of known Kubernetes resources and an EventQueue Consumer that mirrors Kubernetes cluster events into a collection of EventQueues and arranges for their consumption and processing.

Starting a Controller starts the Consumer supplied at construction time, and starts the embedded Reflector. Closing a Controller closes its embedded Reflector and causes the Consumer supplied at construction time to stop receiving Events.

Several protected methods in this class exist to make customization easier; none require overriding and their default behavior is usually just fine.

Thread Safety

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

Design Notes

This class loosely models a combination of a Controller type and a SharedIndexInformer type as found in controller.go and shared_informer.go respectively.

Author:

Laird Nelson

See Also:

Reflector, EventQueueCollection, ResourceTrackingEventQueueConsumer, start(), close()

Field Summary

Fields

Modifier and Type	Field and Description
protected Logger	logger A Logger used by this Controller.

Constructor Summary

Constructors

Constructor and Description
Controller(X operation, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.
Controller(X operation, Duration synchronizationInterval, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.
Controller(X operation, Duration synchronizationInterval, Map<Object,T> knownObjects, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.
Controller(X operation, Map<Object,T> knownObjects, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.
Controller(X operation, ScheduledExecutorService synchronizationExecutorService, Duration synchronizationInterval, Function<? super Throwable,Boolean> errorHandler, Map<Object,T> knownObjects, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.
Controller(X operation, ScheduledExecutorService synchronizationExecutorService, Duration synchronizationInterval, Map<Object,T> knownObjects, Consumer<? super EventQueue<? extends T>> eventQueueConsumer) Creates a new Controller but does not start it.

Method Summary

Modifier and Type	Method and Description
void	awaitEventCacheSynchronization() Blocks until the EventQueueCollection affiliated with this Controller has synchronized.
@Blocking boolean	awaitEventCacheSynchronization(long timeout, TimeUnit timeUnit) Blocks for the desired amount of time until the EventQueueCollection affiliated with this Controller has synchronized or the amount of time has elapsed.
void	close() Closes the embedded Reflector and then closes the embedded EventQueueCollection, handling exceptions appropriately.
protected Event<T>	createEvent(Object source, AbstractEvent.Type eventType, T resource) Creates a new Event when invoked.
protected EventQueue<T>	createEventQueue(Object key) Creates a new EventQueue when invoked.
protected Logger	createLogger() Returns a Logger for use by this Controller.
protected Object	getKey(T resource) Returns a key that can be used to identify the supplied HasMetadata.
protected void	onClose() Invoked after the embedded Reflector closes.
protected boolean	shouldSynchronize() Returns if the embedded Reflector should synchronize.
void	start() Starts the embedded EventQueueCollection consumption machinery and then starts the embedded Reflector.

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 used by this Controller.

This field is never null.

See Also:

createLogger()

Constructor Detail

Controller

public Controller(X operation,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

Controller(Listable, ScheduledExecutorService, Duration, Map, Consumer), start()

Controller

public Controller(X operation,
                  Map<Object,T> knownObjects,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

knownObjects - a Map containing the last known state of Kubernetes resources the embedded EventQueueCollection is caching events for; may be null if this Controller is not interested in tracking deletions of objects; if non-null will be synchronized on by this class during retrieval and traversal operations

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

Controller(Listable, ScheduledExecutorService, Duration, Map, Consumer), start()

Controller

public Controller(X operation,
                  Duration synchronizationInterval,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

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

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

Controller(Listable, ScheduledExecutorService, Duration, Map, Consumer), start()

Controller

public Controller(X operation,
                  Duration synchronizationInterval,
                  Map<Object,T> knownObjects,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

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

knownObjects - a Map containing the last known state of Kubernetes resources the embedded EventQueueCollection is caching events for; may be null if this Controller is not interested in tracking deletions of objects; if non-null will be synchronized on by this class during retrieval and traversal operations

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

Controller(Listable, ScheduledExecutorService, Duration, Map, Consumer), start()

Controller

public Controller(X operation,
                  ScheduledExecutorService synchronizationExecutorService,
                  Duration synchronizationInterval,
                  Map<Object,T> knownObjects,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

synchronizationExecutorService - the ScheduledExecutorService that will be passed to the Reflector constructor; may be null in which case a default ScheduledExecutorService may be used instead

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

knownObjects - a Map containing the last known state of Kubernetes resources the embedded EventQueueCollection is caching events for; may be null if this Controller is not interested in tracking deletions of objects; if non-null will be synchronized on by this class during retrieval and traversal operations

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

start()

Controller

public Controller(X operation,
                  ScheduledExecutorService synchronizationExecutorService,
                  Duration synchronizationInterval,
                  Function<? super Throwable,Boolean> errorHandler,
                  Map<Object,T> knownObjects,
                  Consumer<? super EventQueue<? extends T>> eventQueueConsumer)

Creates a new Controller but does not start it.

Type Parameters:

X - a Listable and VersionWatchable that will be used by the embedded Reflector; must not be null

Parameters:

operation - a Listable and a VersionWatchable that produces Kubernetes events; must not be null

synchronizationExecutorService - the ScheduledExecutorService that will be passed to the Reflector constructor; may be null in which case a default ScheduledExecutorService may be used instead

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

errorHandler - a Function that accepts a Throwable and returns a Boolean indicating whether the error was handled or not; used to handle truly unanticipated errors from within a ScheduledExecutorService used during synchronization and event consumption activities; may be null

knownObjects - a Map containing the last known state of Kubernetes resources the embedded EventQueueCollection is caching events for; may be null if this Controller is not interested in tracking deletions of objects; if non-null will be synchronized on by this class during retrieval and traversal operations

eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null

Throws:

NullPointerException - if operation or eventQueueConsumer is null

See Also:

start()

Method Detail

createLogger

protected Logger createLogger()

Returns a Logger for use by this Controller.

This method never returns null.

Overrides of this method must not return null.

Returns:

a non-null Logger

awaitEventCacheSynchronization

@Blocking
public final void awaitEventCacheSynchronization()
                                                    throws InterruptedException

Blocks until the EventQueueCollection affiliated with this Controller has synchronized.

Throws:

InterruptedException - if the current Thread was interrupted

awaitEventCacheSynchronization

@Blocking
public final @Blocking boolean awaitEventCacheSynchronization(long timeout,
                                                                        TimeUnit timeUnit)
                                                                 throws InterruptedException

Blocks for the desired amount of time until the EventQueueCollection affiliated with this Controller has synchronized or the amount of time has elapsed.

Parameters:

timeout - the amount of time to wait

timeUnit - the TimeUnit designating the amount of time to wait; must not be null

Returns:

false if the waiting time elapsed before the event cache synchronized; true otherwise

Throws:

InterruptedException - if the current Thread was interrupted

NullPointerException - if timeUnit is null

See Also:

EventQueueCollection.SynchronizationAwaitingPropertyChangeListener

start

@NonBlocking
public final void start()
                              throws IOException

Starts the embedded EventQueueCollection consumption machinery and then starts the embedded Reflector.

Throws:

IOException - if Reflector.start() throws an IOException

KubernetesClientException - if the embedded Reflector could not be started

See Also:

EventQueueCollection.start(Consumer), Reflector.start()

close

public final void close()
                 throws IOException

Closes the embedded Reflector and then closes the embedded EventQueueCollection, handling exceptions appropriately.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if the Reflector could not close properly

See Also:

Reflector.close(), EventQueueCollection.close()

shouldSynchronize

protected boolean shouldSynchronize()

Returns if the embedded Reflector should synchronize.

This implementation returns true.

Returns:

true if the embedded Reflector should synchronize; false otherwise

onClose

protected void onClose()

Invoked after the embedded Reflector closes.

This implementation does nothing.

See Also:

Reflector.close(), Reflector.onClose()

getKey

protected Object getKey(T resource)

Returns a key that can be used to identify the supplied HasMetadata.

This method never returns null.

Overrides of this method must not return null.

The default implementation of this method returns the return value of invoking the HasMetadatas.getKey(HasMetadata) method.

Parameters:

resource - the Kubernetes resource for which a key is desired; must not be null

Returns:

a non-null key for the supplied HasMetadata

Throws:

NullPointerException - if resource is null

createEvent

protected Event<T> createEvent(Object source,
                               AbstractEvent.Type eventType,
                               T resource)

Creates a new Event when invoked.

This method never returns null.

Overrides of this method must not return null.

Overrides of this method must return a new Event or subclass with each invocation.

Parameters:

source - the source of the new Event; must not be null

eventType - the Event.Type for the new Event; must not be null

resource - the HasMetadata that the new Event concerns; must not be null

Returns:

a new, non-null Event

Throws:

NullPointerException - if any of the parameters is null

createEventQueue

protected EventQueue<T> createEventQueue(Object key)

Creates a new EventQueue when invoked.

This method never returns null.

Overrides of this method must not return null.

Overrides of this method must return a new EventQueue or subclass with each invocation.

Parameters:

key - the key to create the new EventQueue with; must not be null

Returns:

a new, non-null EventQueue

Throws:

NullPointerException - if key is null