EventQueueCollection (microBean Kubernetes Controller 0.3.0 API)

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.

Design Notes

This class loosely models the DeltaFIFO type in the Kubernetes Go client tools/cache package.

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.SynchronizationAwaitingPropertyChangeListener` A `PropertyChangeListener` specifically designed for reacting to a change in the synchronization status of an `EventQueueCollection` as represented by the firing of its `synchronized` bound Java Beans property.
`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.

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, Function<? super Throwable,Boolean> errorHandler, int initialCapacity, float loadFactor)` Creates a new `EventQueueCollection`.
`EventQueueCollection(Map<?,? extends T> knownObjects, int initialCapacity, float loadFactor)` Creates a new `EventQueueCollection`.

Method Summary

All Methods Instance Methods Concrete Methods
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 `Event`s 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)` Creates a `SynchronizationEvent` using the supplied raw materials and returns it.
`protected void`	`firePropertyChange(String name, boolean old, boolean newValue)` Fires a `PropertyChangeEvent` to registered `PropertyChangeListener`s 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 `PropertyChangeListener`s 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 `PropertyChangeListener`s if the supplied `old` and `newValue` objects are non-`null` and not equal to each other.
`@Blocking EventQueue<T>`	`get()` Implements the `Supplier.get()` contract by removing and returning an `EventQueue` if one is available, blocking if one is not and returning `null` only if the current thread is interrupted or this `EventQueueCollection` is closing.
`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 `PropertyChangeListener`s that were registered to receive notifications for changes to all bound properties.
`PropertyChangeListener[]`	`getPropertyChangeListeners(String name)` Returns an array of `PropertyChangeListener`s 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 `EventQueue`s 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`.
`@NonBlocking Future<?>`	`start(Consumer<? super EventQueue<? extends T>> eventQueueConsumer)` Starts a new `Thread` that, until `close()` is called, removes `EventQueue`s 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
  - EventQueueCollection
```
public EventQueueCollection(Map<?,? extends T> knownObjects,
                            Function<? super Throwable,Boolean> errorHandler,
                            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
    
    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 ScheduledThreadPoolExecutor; may be null
    
    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>
    
    See Also:
    
    SynchronizationEvent
  - 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.
    SynchronizationEvents of type AbstractEvent.Type.ADDITION are added for every resource present in the incomingResources parameter.
    
    Events of type AbstractEvent.Type.DELETION are added when this EventQueueCollection can determine that the lack of a resource's presence in the incomingResources parameter indicates that it has been deleted from Kubernetes.
    
    (No Events of type AbstractEvent.Type.MODIFICATION are added by this method.)
    
    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; will be synchronized on; 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 but reserved for future use; 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>> eventQueueConsumer)
```
    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 never returns null.
    
    If this method has been called before, then the existing Future representing the task that was scheduled is returned instead.
    
    Invoking this method does not block the calling Thread.
    
    The non-null Future that is returned will not return true from its Future.isDone() method unless it has been cancelled or an exception has occurred. That is, the task represented by the returned Future is never-ending under normal circumstances.
    
    Parameters:
    
    eventQueueConsumer - the Consumer that will process each EventQueue as it becomes ready; must not be null. If this Consumer's Consumer.accept(Object) method throws a EventQueueCollection.TransientException, then the EventQueue that was supplied to it will be re-enqueued and at some point in the future this Consumer will have a chance to re-process it.
    
    Returns:
    
    a Future representing the task that is feeding EventQueues to the supplied Consumer; never null; suitable only for cancellation
    
    Throws:
    
    NullPointerException - if eventQueueConsumer 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()
```
    Implements the Supplier.get() contract by removing and returning an EventQueue if one is available, blocking if one is not and returning null only if the current thread is interrupted or this EventQueueCollection is closing.
    Design Notes
    
    This method calls an internal method that models the Pop function in delta_fifo.go.
    
    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
    
    Throws:
    
    NullPointerException - if any parameter is null
  - createSynchronizationEvent
```
protected SynchronizationEvent<T> createSynchronizationEvent(Object source,
                                                             AbstractEvent.Type eventType,
                                                             T resource)
```
    Creates a SynchronizationEvent 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 SynchronizationEvent with every invocation.
    
    Parameters:
    
    source - the source of the SynchronizationEvent that will be created; must not be null
    
    eventType - the type of SynchronizationEvent that will be created; must not be null
    
    resource - the resource of the SynchronizationEvent that will be created; must not be null
    
    Returns:
    
    the created SynchronizationEvent; never null
    
    Throws:
    
    NullPointerException - if any parameter is null
  - 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

Class EventQueueCollection<T extends HasMetadata>

Thread Safety

Design Notes

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

Constructor Detail

EventQueueCollection

EventQueueCollection

EventQueueCollection

EventQueueCollection

Method Detail

createLogger

isSynchronized

synchronize

replace

getKey

createEventQueue

start

close

get

Design Notes

createEvent

createSynchronizationEvent

add

addPropertyChangeListener

addPropertyChangeListener

removePropertyChangeListener

removePropertyChangeListener

getPropertyChangeListeners

getPropertyChangeListeners

firePropertyChange

firePropertyChange

firePropertyChange