T
- a type of Kubernetes resource@ThreadSafe public class EventQueueCollection<T extends HasMetadata> extends Object implements EventCache<T>, Supplier<EventQueue<T>>, AutoCloseable
EventCache
that temporarily stores Event
s in
EventQueue
s, one per named Kubernetes resource, and
provides a means for processing those
queues.
This class is safe for concurrent use by multiple Thread
s.
This class loosely models the DeltaFIFO
type in the Kubernetes Go client tools/cache
package.
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. |
Modifier and Type | Field and Description |
---|---|
protected Logger |
logger
A
Logger used by this EventQueueCollection . |
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)
|
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 . |
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)
|
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 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()
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 . |
protected final Logger logger
createLogger()
public EventQueueCollection()
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, int, float)
public EventQueueCollection(Map<?,? extends T> knownObjects)
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 operationsEventQueueCollection(Map, int, float)
public EventQueueCollection(Map<?,? extends T> knownObjects, int initialCapacity, float loadFactor)
EventQueueCollection
.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 operationsinitialCapacity
- the initial capacity of the internal data
structure used to house this EventQueueCollection
's
EventQueue
s; must be an integer greater than 0
loadFactor
- the load factor of the internal data structure
used to house this EventQueueCollection
's EventQueue
s; must be a positive number between 0
and
1
public EventQueueCollection(Map<?,? extends T> knownObjects, Function<? super Throwable,Boolean> errorHandler, int initialCapacity, float loadFactor)
EventQueueCollection
.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 operationserrorHandler
- 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
EventQueue
s; must be an integer greater than 0
loadFactor
- the load factor of the internal data structure
used to house this EventQueueCollection
's EventQueue
s; must be a positive number between 0
and
1
protected Logger createLogger()
Logger
for use by this EventQueueCollection
.
This method never returns null
.
Overrides of this method must not return null
.
null
Logger
for use by this EventQueueCollection
public final boolean isSynchronized()
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.
This is a bound property.
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; false
otherwisereplace(Collection, Object)
,
add(Object, AbstractEvent.Type, HasMetadata)
,
synchronize()
public final void synchronize()
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
.synchronize
in interface EventCache<T extends HasMetadata>
SynchronizationEvent
public final void replace(Collection<? extends T> incomingResources, Object resourceVersion)
EventQueueCollection
to reflect only the Kubernetes resources
contained in the supplied Collection
.
SynchronizationEvent
s of type AbstractEvent.Type.ADDITION
are added for every resource present
in the incomingResources
parameter.
Event
s 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 Event
s of type AbstractEvent.Type.MODIFICATION
are added by this method.)
EventQueue
s 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.
replace
in interface EventCache<T extends HasMetadata>
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
emptiedresourceVersion
- the version of the Kubernetes list
resource that contained the incoming resources; currently
ignored but reserved for future use; may be null
IllegalStateException
- if the createEvent(Object, AbstractEvent.Type, HasMetadata)
method returns
null
for any reasonSynchronizationEvent
,
createEvent(Object, AbstractEvent.Type, HasMetadata)
protected Object getKey(T resource)
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.
resource
- a HasMetadata
for which a key should be
returned; may be null
in which case null
may be
returnednull
key for the supplied resource
;
or null
if resource
is null
HasMetadatas.getKey(HasMetadata)
protected EventQueue<T> createEventQueue(Object key)
EventQueue
suitable for holding Event
s matching the supplied key
.
This method never returns null
.
Overrides of this method must not return null
.
key
- the key for the new
EventQueue
; must not be null
EventQueue
; never null
NullPointerException
- if key
is null
EventQueue.EventQueue(Object)
@NonBlocking public final @NonBlocking Future<?> start(Consumer<? super EventQueue<? extends T>> eventQueueConsumer)
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.
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.
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.Future
representing the task that is feeding
EventQueue
s to the supplied Consumer
; never
null
; suitable only for cancellationNullPointerException
- if eventQueueConsumer
is
null
public final void close()
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.
close
in interface AutoCloseable
start(Consumer)
@Blocking public final @Blocking EventQueue<T> get()
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.
This method calls an internal method that models the Pop
function in delta_fifo.go
.
get
in interface Supplier<EventQueue<T extends HasMetadata>>
EventQueue
, or null
protected Event<T> createEvent(Object source, AbstractEvent.Type eventType, T resource)
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.
source
- the source of the
Event
that will be created; must not be nulleventType
- 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
Event
; never null
NullPointerException
- if any parameter is null
protected SynchronizationEvent<T> createSynchronizationEvent(Object source, AbstractEvent.Type eventType, T resource)
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.
source
- the source of the SynchronizationEvent
that will be created;
must not be nulleventType
- 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
SynchronizationEvent
; never null
NullPointerException
- if any parameter is null
public final Event<T> add(Object source, AbstractEvent.Type eventType, T resource)
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.
add
in interface EventCache<T extends HasMetadata>
source
- the source of the
Event
that will be created and added; must not be nulleventType
- 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
Event
that was created and added, or null
if no Event
was actually added as a result of this
method's invocationNullPointerException
- if any of the parameters is
null
Event
public final void addPropertyChangeListener(String name, PropertyChangeListener listener)
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.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 takenaddPropertyChangeListener(PropertyChangeListener)
public final void addPropertyChangeListener(PropertyChangeListener listener)
PropertyChangeListener
to this EventQueueCollection
's collection of such listeners so that it
will be notified whenever any bound property of this EventQueueCollection
changes.listener
- the PropertyChangeListener
to add; may be
null
in which case no action will be takenaddPropertyChangeListener(String, PropertyChangeListener)
public final void removePropertyChangeListener(String name, PropertyChangeListener listener)
PropertyChangeListener
from this
EventQueueCollection
so that it will no longer be
notified of changes to bound properties bearing the supplied
name
.name
- a bound property name; may be null
listener
- the PropertyChangeListener
to remove; may
be null
in which case no action will be takenaddPropertyChangeListener(String, PropertyChangeListener)
,
removePropertyChangeListener(PropertyChangeListener)
public final void removePropertyChangeListener(PropertyChangeListener listener)
PropertyChangeListener
from this
EventQueueCollection
so that it will no longer be
notified of any changes to bound properties.listener
- the PropertyChangeListener
to remove; may
be null
in which case no action will be takenaddPropertyChangeListener(PropertyChangeListener)
,
removePropertyChangeListener(String, PropertyChangeListener)
public final PropertyChangeListener[] getPropertyChangeListeners(String name)
PropertyChangeListener
s that were
registered to receive notifications for
changes to bound properties bearing the supplied name
.
This method never returns null
.
name
- the name of a bound property; may be null
in
which case an empty array will be returnednull
array of PropertyChangeListener
sgetPropertyChangeListeners()
,
addPropertyChangeListener(String, PropertyChangeListener)
,
removePropertyChangeListener(String,
PropertyChangeListener)
public final PropertyChangeListener[] getPropertyChangeListeners()
PropertyChangeListener
s that were
registered to receive notifications for
changes to all bound properties.
This method never returns null
.
null
array of PropertyChangeListener
sgetPropertyChangeListeners(String)
,
addPropertyChangeListener(PropertyChangeListener)
,
removePropertyChangeListener(PropertyChangeListener)
protected final void firePropertyChange(String propertyName, Object old, Object newValue)
PropertyChangeEvent
to registered PropertyChangeListeners if the supplied
old
and newValue
objects are non-null
and
not equal to each other.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
protected final void firePropertyChange(String propertyName, int old, int newValue)
PropertyChangeEvent
to registered PropertyChangeListeners if the supplied
old
and newValue
objects are non-null
and
not equal to each other.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 questionnewValue
- the new value of the bound propertyprotected final void firePropertyChange(String name, boolean old, boolean newValue)
PropertyChangeEvent
to registered PropertyChangeListeners if the supplied
old
and newValue
objects are non-null
and
not equal to each other.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 questionnewValue
- the new value of the bound propertyCopyright © 2017–2021, microBean™. All rights reserved.