001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2017-2018 microBean.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.kubernetes.controller;
018
019import java.util.Collection;
020
021import io.fabric8.kubernetes.api.model.HasMetadata;
022
023/**
024 * A minimalistic interface indicating that its implementations cache
025 * {@link Event}s representing Kubernetes resources.
026 *
027 * <h2>Thread Safety</h2>
028 *
029 * <p><strong>Instances of implementations of this interface must be
030 * safe for concurrent usage by multiple {@link Thread}s.</strong></p>
031 *
032 * @param <T> a type of Kubernetes resource
033 *
034 * @author <a href="https://about.me/lairdnelson"
035 * target="_parent">Laird Nelson</a>
036 *
037 * @see Event
038 *
039 * @see EventQueueCollection
040 */
041public interface EventCache<T extends HasMetadata> {
042
043  /**
044   * Adds a new {@link Event} constructed out of the parameters
045   * supplied to this method to this {@link EventCache} implementation
046   * and returns the {@link Event} that was added.
047   *
048   * <p>Implementations of this method may return {@code null} to
049   * indicate that for whatever reason no {@link Event} was actually
050   * added.</p>
051   *
052   * @param source the {@linkplain Event#getSource() source} of the
053   * {@link Event} that will be created and added; must not be {@code
054   * null}
055   *
056   * @param eventType the {@linkplain Event#getType() type} of {@link
057   * Event} that will be created and added; must not be {@code null}
058   *
059   * @param resource the {@linkplain Event#getResource() resource} of
060   * the {@link Event} that will be created and added must not be
061   * {@code null}
062   *
063   * @return the {@link Event} that was created and added, or {@code
064   * null} if no {@link Event} was actually added as a result of this
065   * method's invocation
066   *
067   * @exception NullPointerException if any of the parameters is
068   * {@code null}
069   *
070   * @see Event
071   */
072  public Event<T> add(final Object source, final Event.Type eventType, final T resource);
073
074  /**
075   * A "full replace" operation that atomically replaces all internal
076   * state with new state derived from the supplied {@link Collection}
077   * of resources.
078   *
079   * @param incomingResources the resources comprising the new state;
080   * must not be {@code null}; <strong>must be synchronized
081   * on</strong> when accessing
082   *
083   * @param resourceVersion the notional version of the supplied
084   * {@link Collection}; may be {@code null}; often ignored by
085   * implementations
086   *
087   * @exception NullPointerException if {@code incomingResources} is
088   * {@code null}
089   */
090  public void replace(final Collection<? extends T> incomingResources, final Object resourceVersion);
091
092  /**
093   * Synchronizes this {@link EventCache} implementation's state with
094   * its downstream consumers, if any.
095   *
096   * <p>Not all {@link EventCache} implementations need support
097   * synchronization.  An implementation of this method that does
098   * nothing is explicitly permitted.</p>
099   *
100   * <p>Implementations of this method must expect to be called on a
101   * fixed schedule.</p>
102
103   * <h2>Design Notes</h2>
104   *
105   * <p>This method emulates the <a
106   * href="https://github.com/kubernetes/client-go/blob/master/tools/cache/delta_fifo.go#L529">{@code
107   * Resync} function in the Go code's {@code DeltaFifo} construct</a>
108   * Specifically, it is anticipated that an implementation of this
109   * method that does not simply return will go through the internal
110   * resources that this {@link EventCache} knows about, and, for each
111   * that does not have an event queue set up for it
112   * already&mdash;i.e. for each that is not currently being
113   * processed&mdash; will fire a {@link SynchronizationEvent}.  This
114   * will have the effect of "heartbeating" the current desired state
115   * of the system "downstream" to processors that may wish to alter
116   * the actual state of the system to conform to it.</p>
117   *
118   * @see SynchronizationEvent
119   */
120  public void synchronize();
121  
122}