org.microbean.kubernetes.controller

Class EventQueueCollection<T extends HasMetadata>

java.lang.Object

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

Type Parameters:

T - a type of Kubernetes resource

All Implemented Interfaces:

AutoCloseable, Supplier<EventQueue<T>>, EventCache<T>

@ThreadSafe
public class EventQueueCollection<T extends HasMetadata>
extends Object
implements EventCache<T>, Supplier<EventQueue<T>>, AutoCloseable

An EventCache that temporarily stores Events in EventQueues, one per named Kubernetes resource, and provides a means for processing those queues.

Thread Safety

This class is safe for concurrent use by multiple Threads.

Author:

Laird Nelson

See Also:

add(Object, AbstractEvent.Type, HasMetadata), replace(Collection, Object), synchronize(), start(Consumer), EventQueue

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EventQueueCollection.TransientException A RuntimeException indicating that a Consumer started by an EventQueueCollection has encountered an error that might not happen if the consumption operation is retried.

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
EventQueueCollection() Creates a new EventQueueCollection with an initial capacity of 16 and a load factor of 0.75 that is not interested in tracking Kubernetes resource deletions.
EventQueueCollection(Map<?,? extends T> knownObjects) Creates a new EventQueueCollection with an initial capacity of 16 and a load factor of 0.75.
EventQueueCollection(Map<?,? extends T> knownObjects, int initialCapacity, float loadFactor) Creates a new EventQueueCollection.

Method Summary

Modifier and Type	Method and Description
Event<T>	add(Object source, AbstractEvent.Type eventType, T resource) Adds a new Event constructed out of the parameters supplied to this method to this EventQueueCollection and returns the Event that was added.
void	addPropertyChangeListener(PropertyChangeListener listener) Adds the supplied PropertyChangeListener to this EventQueueCollection's collection of such listeners so that it will be notified whenever any bound property of this EventQueueCollection changes.
void	addPropertyChangeListener(String name, PropertyChangeListener listener) Adds the supplied PropertyChangeListener to this EventQueueCollection's collection of such listeners so that it will be notified only when the bound property bearing the supplied name changes.
void	close() Semantically closes this EventQueueCollection by detaching any Consumer previously attached via the start(Consumer) method.
protected Event<T>	createEvent(Object source, AbstractEvent.Type eventType, T resource) Creates an Event using the supplied raw materials and returns it.
protected EventQueue<T>	createEventQueue(Object key) Creates a new EventQueue suitable for holding Events matching the supplied key.
protected Logger	createLogger() Returns a Logger for use by this EventQueueCollection.
protected SynchronizationEvent<T>	createSynchronizationEvent(Object source, AbstractEvent.Type eventType, T resource)
protected void	firePropertyChange(String name, boolean old, boolean newValue) Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.
protected void	firePropertyChange(String propertyName, int old, int newValue) Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.
protected void	firePropertyChange(String propertyName, Object old, Object newValue) Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.
@Blocking EventQueue<T>	get() Returns an EventQueue if one is available, blocking if one is not and returning null only if the current thread is interrupted.
protected Object	getKey(T resource) Returns an Object which will be used as the key that will uniquely identify the supplied resource to this EventQueueCollection.
PropertyChangeListener[]	getPropertyChangeListeners() Returns an array of PropertyChangeListeners that were registered to receive notifications for changes to all bound properties.
PropertyChangeListener[]	getPropertyChangeListeners(String name) Returns an array of PropertyChangeListeners that were registered to receive notifications for changes to bound properties bearing the supplied name.
boolean	isSynchronized() Returns true if this EventQueueCollection has been populated via a call to add(Object, AbstractEvent.Type, HasMetadata) at some point, and if there are no EventQueues remaining to be removed.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes the supplied PropertyChangeListener from this EventQueueCollection so that it will no longer be notified of any changes to bound properties.
void	removePropertyChangeListener(String name, PropertyChangeListener listener) Removes the supplied PropertyChangeListener from this EventQueueCollection so that it will no longer be notified of changes to bound properties bearing the supplied name.
void	replace(Collection<? extends T> incomingResources, Object resourceVersion) At a high level, fully replaces the internal state of this EventQueueCollection to reflect only the Kubernetes resources contained in the supplied Collection, notionally firing SynchronizationEvents and Events of type AbstractEvent.Type.DELETION as appropriate.
@NonBlocking Future<?>	start(Consumer<? super EventQueue<? extends T>> siphon) Starts a new Thread that, until close() is called, removes EventQueues from this EventQueueCollection and supplies them to the supplied Consumer, and returns a Future representing this task.
void	synchronize() Synchronizes on the knownObjects object supplied at construction time, if there is one, and, for every Kubernetes resource found within at the time of this call, adds a SynchronizationEvent for it with an AbstractEvent.Type of AbstractEvent.Type.MODIFICATION.

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 EventQueueCollection.

This field is never null.

See Also:

createLogger()

Constructor Detail

EventQueueCollection

public EventQueueCollection()

Creates a new EventQueueCollection with an initial capacity of 16 and a load factor of 0.75 that is not interested in tracking Kubernetes resource deletions.

See Also:

EventQueueCollection(Map, int, float)

EventQueueCollection

public EventQueueCollection(Map<?,? extends T> knownObjects)

Creates a new EventQueueCollection with an initial capacity of 16 and a load factor of 0.75.

Parameters:

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

See Also:

EventQueueCollection(Map, int, float)

EventQueueCollection

public EventQueueCollection(Map<?,? extends T> knownObjects,
                            int initialCapacity,
                            float loadFactor)

Creates a new EventQueueCollection.

Parameters:

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

initialCapacity - the initial capacity of the internal data structure used to house this EventQueueCollection's EventQueues; must be an integer greater than 0

loadFactor - the load factor of the internal data structure used to house this EventQueueCollection's EventQueues; must be a positive number between 0 and 1

Method Detail

createLogger

protected Logger createLogger()

Returns a Logger for use by this EventQueueCollection.

This method never returns null.

Overrides of this method must not return null.

Returns:

a non-null Logger for use by this EventQueueCollection

isSynchronized

public final boolean isSynchronized()

Returns true if this EventQueueCollection has been populated via a call to add(Object, AbstractEvent.Type, HasMetadata) at some point, and if there are no EventQueues remaining to be removed.

This is a bound property.

Returns:

true if this EventQueueCollection has been populated via a call to add(Object, AbstractEvent.Type, HasMetadata) at some point, and if there are no EventQueues remaining to be removed; false otherwise

See Also:

replace(Collection, Object), add(Object, AbstractEvent.Type, HasMetadata), synchronize()

synchronize

public final void synchronize()

Synchronizes on the knownObjects object supplied at construction time, if there is one, and, for every Kubernetes resource found within at the time of this call, adds a SynchronizationEvent for it with an AbstractEvent.Type of AbstractEvent.Type.MODIFICATION.

Specified by:

synchronize in interface EventCache<T extends HasMetadata>

replace

public final void replace(Collection<? extends T> incomingResources,
                          Object resourceVersion)

At a high level, fully replaces the internal state of this EventQueueCollection to reflect only the Kubernetes resources contained in the supplied Collection, notionally firing SynchronizationEvents and Events of type AbstractEvent.Type.DELETION as appropriate.

EventQueues managed by this EventQueueCollection that have not yet been processed are not removed by this operation.

This method synchronizes on the supplied incomingResources Collection while iterating over it.

Specified by:

replace in interface EventCache<T extends HasMetadata>

Parameters:

incomingResources - the Collection of Kubernetes resources with which to replace this EventQueueCollection's internal state; may be null or empty, which will be taken as an indication that this EventQueueCollection should effectively be emptied

resourceVersion - the version of the Kubernetes list resource that contained the incoming resources; currently ignored; may be null

Throws:

IllegalStateException - if the createEvent(Object, AbstractEvent.Type, HasMetadata) method returns null for any reason

See Also:

SynchronizationEvent, createEvent(Object, AbstractEvent.Type, HasMetadata)

getKey

protected Object getKey(T resource)

Returns an Object which will be used as the key that will uniquely identify the supplied resource to this EventQueueCollection.

This method may return null, but only if resource is null or is constructed in such a way that its HasMetadata.getMetadata() method returns null.

Overrides of this method may return null, but only if resource is null.

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

Parameters:

resource - a HasMetadata for which a key should be returned; may be null in which case null may be returned

Returns:

a non-null key for the supplied resource; or null if resource is null

See Also:

HasMetadatas.getKey(HasMetadata)

createEventQueue

protected EventQueue<T> createEventQueue(Object key)

Creates a new EventQueue suitable for holding Events matching the supplied key.

This method never returns null.

Overrides of this method must not return null.

Parameters:

key - the key for the new EventQueue; must not be null

Returns:

the new EventQueue; never null

Throws:

NullPointerException - if key is null

See Also:

EventQueue.EventQueue(Object)

start

@NonBlocking
public final @NonBlocking Future<?> start(Consumer<? super EventQueue<? extends T>> siphon)

Starts a new Thread that, until close() is called, removes EventQueues from this EventQueueCollection and supplies them to the supplied Consumer, and returns a Future representing this task.

This method may return null.

Invoking this method does not block the calling Thread.

Parameters:

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

Returns:

a Future representing the task that is feeding EventQueues to the supplied Consumer, or null if no task was started

Throws:

NullPointerException - if siphon is null

close

public final void close()

Semantically closes this EventQueueCollection by detaching any Consumer previously attached via the start(Consumer) method. Additions, replacements and synchronizations are still possible, but there won't be anything consuming any events generated by or supplied to these operations.

A closed EventQueueCollection may be started again.

Specified by:

close in interface AutoCloseable

See Also:

start(Consumer)

get

@Blocking
public final @Blocking EventQueue<T> get()

Returns an EventQueue if one is available, blocking if one is not and returning null only if the current thread is interrupted.

This method may return null in which case the current Thread has been interrupted.

Specified by:

get in interface Supplier<EventQueue<T extends HasMetadata>>

Returns:

an EventQueue, or null

createEvent

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

Creates an Event using the supplied raw materials and returns it.

This method never returns null.

Implementations of this method must not return null.

Implementations of this method must return a new Event with every invocation.

Parameters:

source - the source of the Event that will be created; must not be null

eventType - the type of Event that will be created; must not be null

resource - the resource of the Event that will be created; must not be null

Returns:

the created Event; never null

createSynchronizationEvent

protected SynchronizationEvent<T> createSynchronizationEvent(Object source,
                                                             AbstractEvent.Type eventType,
                                                             T resource)

add

public final Event<T> add(Object source,
                          AbstractEvent.Type eventType,
                          T resource)

Adds a new Event constructed out of the parameters supplied to this method to this EventQueueCollection and returns the Event that was added.

This method may return null.

This implementation creates an EventQueue if necessary for the Event that will be added, and then adds the new Event to the queue.

Specified by:

add in interface EventCache<T extends HasMetadata>

Parameters:

source - the source of the Event that will be created and added; must not be null

eventType - the type of Event that will be created and added; must not be null

resource - the resource of the Event that will be created and added; must not be null

Returns:

the Event that was created and added, or null if no Event was actually added as a result of this method's invocation

Throws:

NullPointerException - if any of the parameters is null

See Also:

Event

addPropertyChangeListener

public final void addPropertyChangeListener(String name,
                                            PropertyChangeListener listener)

Adds the supplied PropertyChangeListener to this EventQueueCollection's collection of such listeners so that it will be notified only when the bound property bearing the supplied name changes.

Parameters:

name - the name of the bound property whose changes are of interest; may be null in which case all property change notifications will be dispatched to the supplied PropertyChangeListener

listener - the PropertyChangeListener to add; may be null in which case no action will be taken

See Also:

addPropertyChangeListener(PropertyChangeListener)

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener listener)

Adds the supplied PropertyChangeListener to this EventQueueCollection's collection of such listeners so that it will be notified whenever any bound property of this EventQueueCollection changes.

Parameters:

listener - the PropertyChangeListener to add; may be null in which case no action will be taken

See Also:

addPropertyChangeListener(String, PropertyChangeListener)

removePropertyChangeListener

public final void removePropertyChangeListener(String name,
                                               PropertyChangeListener listener)

Removes the supplied PropertyChangeListener from this EventQueueCollection so that it will no longer be notified of changes to bound properties bearing the supplied name.

Parameters:

name - a bound property name; may be null

listener - the PropertyChangeListener to remove; may be null in which case no action will be taken

See Also:

addPropertyChangeListener(String, PropertyChangeListener), removePropertyChangeListener(PropertyChangeListener)

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener listener)

Removes the supplied PropertyChangeListener from this EventQueueCollection so that it will no longer be notified of any changes to bound properties.

Parameters:

listener - the PropertyChangeListener to remove; may be null in which case no action will be taken

See Also:

addPropertyChangeListener(PropertyChangeListener), removePropertyChangeListener(String, PropertyChangeListener)

getPropertyChangeListeners

public final PropertyChangeListener[] getPropertyChangeListeners(String name)

Returns an array of PropertyChangeListeners that were registered to receive notifications for changes to bound properties bearing the supplied name.

This method never returns null.

Parameters:

name - the name of a bound property; may be null in which case an empty array will be returned

Returns:

a non-null array of PropertyChangeListeners

See Also:

getPropertyChangeListeners(), addPropertyChangeListener(String, PropertyChangeListener), removePropertyChangeListener(String, PropertyChangeListener)

getPropertyChangeListeners

public final PropertyChangeListener[] getPropertyChangeListeners()

Returns an array of PropertyChangeListeners that were registered to receive notifications for changes to all bound properties.

This method never returns null.

Returns:

a non-null array of PropertyChangeListeners

See Also:

getPropertyChangeListeners(String), addPropertyChangeListener(PropertyChangeListener), removePropertyChangeListener(PropertyChangeListener)

firePropertyChange

protected final void firePropertyChange(String propertyName,
                                        Object old,
                                        Object newValue)

Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.

Parameters:

propertyName - the name of the bound property that might have changed; may be null (indicating that some unknown set of bound properties has changed)

old - the old value of the bound property in question; may be null

newValue - the new value of the bound property; may be null

firePropertyChange

protected final void firePropertyChange(String propertyName,
                                        int old,
                                        int newValue)

Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.

Parameters:

propertyName - the name of the bound property that might have changed; may be null (indicating that some unknown set of bound properties has changed)

old - the old value of the bound property in question

newValue - the new value of the bound property

firePropertyChange

protected final void firePropertyChange(String name,
                                        boolean old,
                                        boolean newValue)

Fires a PropertyChangeEvent to registered PropertyChangeListeners if the supplied old and newValue objects are non-null and not equal to each other.

Parameters:

name - the name of the bound property that might have changed; may be null (indicating that some unknown set of bound properties has changed)

old - the old value of the bound property in question

newValue - the new value of the bound property