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—i.e. for each that is not currently being 113 * processed— 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}