This field can be—and often is—{@code null}.
66 | * 67 | * @see #getKey() 68 | * 69 | * @see #setKey(Object) 70 | */ 71 | private volatile Object key; 72 | 73 | /** 74 | * The {@link Type} describing the type of this {@link 75 | * AbstractEvent}. 76 | * 77 | *This field is never {@code null}.
78 | * 79 | * @see #getType() 80 | */ 81 | private final Type type; 82 | 83 | /** 84 | * A Kubernetes resource representing the prior state of 85 | * the resource returned by this {@link AbstractEvent}'s {@link 86 | * #getResource()} method. 87 | * 88 | *This field may be {@code null}.
89 | * 90 | *The prior state of a given Kubernetes resource is often not 91 | * known, so this field is often {@code null}.
92 | * 93 | * @see #getResource() 94 | */ 95 | private final T priorResource; 96 | 97 | /** 98 | * A Kubernetes resource representing its state at the time of this 99 | * event. 100 | * 101 | *This field is never {@code null}.
102 | * 103 | * @see #getResource() 104 | */ 105 | private final T resource; 106 | 107 | 108 | /* 109 | * Constructors. 110 | */ 111 | 112 | 113 | /** 114 | * A private zero-argument constructor to reinforce to readers and 115 | * subclassers alike that this is not only an {@code abstract} 116 | * class, but one with a finite, known number of subclasses. 117 | * 118 | * @exception NullPointerException when invoked 119 | * 120 | * @see #AbstractEvent(Object, Type, HasMetadata, HasMetadata) 121 | */ 122 | private AbstractEvent() { 123 | this(null, null, null, null); 124 | } 125 | 126 | /** 127 | * Creates a new {@link AbstractEvent}. 128 | * 129 | * @param source the creator; must not be {@code null} 130 | * 131 | * @param type the {@link Type} of this {@link AbstractEvent}; must not be 132 | * {@code null} 133 | * 134 | * @param priorResource a {@link HasMetadata} representing the 135 | * prior state of the {@linkplain #getResource() Kubernetes 136 | * resource thisAbstractEvent primarily concerns}; may
137 | * be—and often is—null
138 | *
139 | * @param resource a {@link HasMetadata} representing a Kubernetes
140 | * resource; must not be {@code null}
141 | *
142 | * @exception NullPointerException if {@code source}, {@code type}
143 | * or {@code resource} is {@code null}
144 | *
145 | * @exception IllegalStateException if somehow a subclass invoking
146 | * this constructor manages illicitly to be neither an instance of
147 | * {@link Event} nor an instance of {@link SynchronizationEvent}
148 | *
149 | * @see Type
150 | *
151 | * @see EventObject#getSource()
152 | */
153 | AbstractEvent(final Object source, final Type type, final T priorResource, final T resource) {
154 | super(source);
155 | if (!(Event.class.isAssignableFrom(this.getClass()) || SynchronizationEvent.class.isAssignableFrom(this.getClass()))) {
156 | throw new IllegalStateException("Unexpected subclass");
157 | }
158 | this.type = Objects.requireNonNull(type);
159 | this.priorResource = priorResource;
160 | this.resource = Objects.requireNonNull(resource);
161 | }
162 |
163 |
164 | /*
165 | * Instance methods.
166 | */
167 |
168 |
169 | /**
170 | * Returns a {@link Type} representing the type of this {@link
171 | * AbstractEvent}.
172 | *
173 | * This method never returns {@code null}.
174 | * 175 | * @return a non-{@code null} {@link Type} 176 | * 177 | * @see Type 178 | */ 179 | public final Type getType() { 180 | return this.type; 181 | } 182 | 183 | /** 184 | * Returns a {@link HasMetadata} representing the prior 185 | * state of the Kubernetes resource this {@link AbstractEvent} 186 | * primarily concerns. 187 | * 188 | *This method may return {@code null}, and often does.
189 | * 190 | *The prior state of a Kubernetes resource is often not known at
191 | * {@link AbstractEvent} construction time so it is common for this method
192 | * to return {@code null}.
193 | *
194 | * @return a {@link HasMetadata} representing the prior
195 | * state of the {@linkplain #getResource() Kubernetes resource
196 | * this AbstractEvent primarily concerns}, or {@code null}
197 | *
198 | * @see #getResource()
199 | */
200 | public final T getPriorResource() {
201 | return this.priorResource;
202 | }
203 |
204 | /**
205 | * Returns a {@link HasMetadata} representing the Kubernetes
206 | * resource this {@link AbstractEvent} concerns.
207 | *
208 | *
This method never returns {@code null}.
209 | * 210 | * @return a non-{@code null} Kubernetes resource 211 | */ 212 | public final T getResource() { 213 | return this.resource; 214 | } 215 | 216 | /** 217 | * Returns {@code true} if this {@link AbstractEvent}'s {@linkplain 218 | * #getResource() resource} is an accurate representation of its 219 | * last known state. 220 | * 221 | *This should only return {@code true} for some, but not all, 222 | * deletion scenarios. Any other behavior should be considered to 223 | * be an error.
224 | * 225 | * @return {@code true} if this {@link AbstractEvent}'s {@linkplain 226 | * #getResource() resource} is an accurate representation of its 227 | * last known state; {@code false} otherwise 228 | */ 229 | public final boolean isFinalStateKnown() { 230 | return this.key == null; 231 | } 232 | 233 | /** 234 | * Sets the key identifying the Kubernetes resource this {@link 235 | * AbstractEvent} describes. 236 | * 237 | * @param key the new key; may be {@code null} 238 | * 239 | * @see #getKey() 240 | */ 241 | final void setKey(final Object key) { 242 | this.key = key; 243 | } 244 | 245 | /** 246 | * Returns a key that can be used to unambiguously identify this 247 | * {@link AbstractEvent}'s {@linkplain #getResource() resource}. 248 | * 249 | *This method may return {@code null} in exceptional cases, but 250 | * normally does not.
251 | * 252 | *Overrides of this method must not return {@code null} except 253 | * in exceptional cases.
254 | * 255 | *The default implementation of this method returns the return 256 | * value of the {@link HasMetadatas#getKey(HasMetadata)} method.
257 | * 258 | * @return a key for this {@link AbstractEvent}, or {@code null} 259 | * 260 | * @see HasMetadatas#getKey(HasMetadata) 261 | */ 262 | public Object getKey() { 263 | Object returnValue = this.key; 264 | if (returnValue == null) { 265 | returnValue = HasMetadatas.getKey(this.getResource()); 266 | } 267 | return returnValue; 268 | } 269 | 270 | /** 271 | * Returns a hashcode for this {@link AbstractEvent}. 272 | * 273 | * @return a hashcode for this {@link AbstractEvent} 274 | */ 275 | @Override 276 | public int hashCode() { 277 | int hashCode = 37; 278 | 279 | final Object source = this.getSource(); 280 | int c = source == null ? 0 : source.hashCode(); 281 | hashCode = hashCode * 17 + c; 282 | 283 | final Object key = this.getKey(); 284 | c = key == null ? 0 : key.hashCode(); 285 | hashCode = hashCode * 17 + c; 286 | 287 | final Object type = this.getType(); 288 | c = type == null ? 0 : type.hashCode(); 289 | hashCode = hashCode * 17 + c; 290 | 291 | final Object resource = this.getResource(); 292 | c = resource == null ? 0 : resource.hashCode(); 293 | hashCode = hashCode * 17 + c; 294 | 295 | final Object priorResource = this.getPriorResource(); 296 | c = priorResource == null ? 0 : priorResource.hashCode(); 297 | hashCode = hashCode * 17 + c; 298 | 299 | return hashCode; 300 | } 301 | 302 | /** 303 | * Returns {@code true} if the supplied {@link Object} is also an 304 | * {@link AbstractEvent} and is equal in every respect to this one. 305 | * 306 | * @param other the {@link Object} to test; may be {@code null} in 307 | * which case {@code false} will be returned 308 | * 309 | * @return {@code true} if the supplied {@link Object} is also an 310 | * {@link AbstractEvent} and is equal in every respect to this one; {@code 311 | * false} otherwise 312 | */ 313 | @Override 314 | public boolean equals(final Object other) { 315 | if (other == this) { 316 | return true; 317 | } else if (other instanceof AbstractEvent) { 318 | 319 | final AbstractEvent her = (AbstractEvent)other; 320 | 321 | final Object source = this.getSource(); 322 | if (source == null) { 323 | if (her.getSource() != null) { 324 | return false; 325 | } 326 | } else if (!source.equals(her.getSource())) { 327 | return false; 328 | } 329 | 330 | final Object key = this.getKey(); 331 | if (key == null) { 332 | if (her.getKey() != null) { 333 | return false; 334 | } 335 | } else if (!key.equals(her.getKey())) { 336 | return false; 337 | } 338 | 339 | final Object type = this.getType(); 340 | if (type == null) { 341 | if (her.getType() != null) { 342 | return false; 343 | } 344 | } else if (!type.equals(her.getType())) { 345 | return false; 346 | } 347 | 348 | final Object resource = this.getResource(); 349 | if (resource == null) { 350 | if (her.getResource() != null) { 351 | return false; 352 | } 353 | } else if (!resource.equals(her.getResource())) { 354 | return false; 355 | } 356 | 357 | final Object priorResource = this.getPriorResource(); 358 | if (priorResource == null) { 359 | if (her.getPriorResource() != null) { 360 | return false; 361 | } 362 | } else if (!priorResource.equals(her.getPriorResource())) { 363 | return false; 364 | } 365 | 366 | 367 | return true; 368 | } else { 369 | return false; 370 | } 371 | } 372 | 373 | /** 374 | * Returns a {@link String} representation of this {@link AbstractEvent}. 375 | * 376 | *This method never returns {@code null}.
377 | * 378 | *Overrides of this method must not return {@code null}.
379 | * 380 | * @return a non-{@code null} {@link String} representation of this 381 | * {@link AbstractEvent} 382 | */ 383 | @Override 384 | public String toString() { 385 | final StringBuilder sb = new StringBuilder().append(this.getType()).append(": "); 386 | final Object priorResource = this.getPriorResource(); 387 | if (priorResource != null) { 388 | sb.append(priorResource).append(" --> "); 389 | } 390 | sb.append(this.getResource()); 391 | return sb.toString(); 392 | } 393 | 394 | 395 | /* 396 | * Inner and nested classes. 397 | */ 398 | 399 | 400 | /** 401 | * The type of an {@link AbstractEvent}. 402 | * 403 | * @author Laird Nelson 405 | */ 406 | public static enum Type { 407 | 408 | /** 409 | * A {@link Type} representing the addition of a resource. 410 | */ 411 | ADDITION, 412 | 413 | /** 414 | * A {@link Type} representing the modification of a resource. 415 | */ 416 | MODIFICATION, 417 | 418 | /** 419 | * A {@link Type} representing the deletion of a resource. 420 | */ 421 | DELETION 422 | 423 | } 424 | 425 | } 426 | -------------------------------------------------------------------------------- /src/main/java/org/microbean/kubernetes/controller/Controller.java: -------------------------------------------------------------------------------- 1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 2 | * 3 | * Copyright © 2017-2018 microBean. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 | * implied. See the License for the specific language governing 15 | * permissions and limitations under the License. 16 | */ 17 | package org.microbean.kubernetes.controller; 18 | 19 | import java.io.Closeable; 20 | import java.io.IOException; 21 | 22 | import java.time.Duration; 23 | 24 | import java.util.Map; 25 | import java.util.Objects; 26 | 27 | import java.util.concurrent.Future; 28 | import java.util.concurrent.ScheduledExecutorService; 29 | import java.util.concurrent.TimeUnit; 30 | 31 | import java.util.function.Consumer; 32 | import java.util.function.Function; 33 | 34 | import java.util.logging.Level; 35 | import java.util.logging.Logger; 36 | 37 | import io.fabric8.kubernetes.api.model.HasMetadata; 38 | import io.fabric8.kubernetes.api.model.KubernetesResourceList; 39 | 40 | import io.fabric8.kubernetes.client.KubernetesClientException; // for javadoc only 41 | import io.fabric8.kubernetes.client.Watcher; 42 | 43 | import io.fabric8.kubernetes.client.dsl.Listable; 44 | import io.fabric8.kubernetes.client.dsl.VersionWatchable; 45 | 46 | import net.jcip.annotations.Immutable; 47 | import net.jcip.annotations.ThreadSafe; 48 | 49 | import org.microbean.development.annotation.Blocking; 50 | import org.microbean.development.annotation.NonBlocking; 51 | 52 | /** 53 | * A convenient combination of a {@link Reflector}, a {@link 54 | * VersionWatchable} and {@link Listable} implementation, an 55 | * (internal) {@link EventQueueCollection}, a {@link Map} of known 56 | * Kubernetes resources and an {@link EventQueue} {@link Consumer} 57 | * that {@linkplain Reflector#start() mirrors Kubernetes cluster 58 | * events} into a {@linkplain EventQueueCollection collection of 59 | *EventQueues} and {@linkplain
60 | * EventQueueCollection#start(Consumer) arranges for their consumption
61 | * and processing}.
62 | *
63 | * {@linkplain #start() Starting} a {@link Controller} {@linkplain
64 | * EventQueueCollection#start(Consumer) starts the
65 | * Consumer} supplied at construction time, and
66 | * {@linkplain Reflector#start() starts the embedded
67 | * Reflector}. {@linkplain #close() Closing} a {@link
68 | * Controller} {@linkplain Reflector#close() closes its embedded
69 | * Reflector} and {@linkplain
70 | * EventQueueCollection#close() causes the Consumer
71 | * supplied at construction time to stop receiving
72 | * Events}.
Several {@code protected} methods in this class exist to make 75 | * customization easier; none require overriding and their default 76 | * behavior is usually just fine.
77 | * 78 | *Instances of this class are safe for concurrent use by multiple 81 | * threads.
82 | * 83 | *This class loosely models a combination of a {@code 87 | * Controller} type and a {@code 89 | * SharedIndexInformer} type as found in {@code 91 | * controller.go} and {@code 93 | * shared_informer.go} respectively.
94 | * 95 | * @paramThis field is never {@code null}.
124 | * 125 | * @see #createLogger() 126 | */ 127 | protected final Logger logger; 128 | 129 | /** 130 | * The {@link Reflector} used by this {@link Controller} to mirror 131 | * Kubernetes events. 132 | * 133 | *This field is never {@code null}.
134 | */ 135 | private final ReflectorThis field is never {@code null}.
143 | * 144 | * @see EventQueueCollection#add(Object, AbstractEvent.Type, 145 | * HasMetadata) 146 | * 147 | * @see EventQueueCollection#replace(Collection, Object) 148 | * 149 | * @see EventQueueCollection#synchronize() 150 | * 151 | * @see EventQueueCollection#start(Consumer) 152 | */ 153 | private final EventQueueCollectionThis field is never {@code null}.
163 | */ 164 | private final Consumer> eventQueueConsumer; 165 | 166 | 167 | /* 168 | * Constructors. 169 | */ 170 | 171 | 172 | /** 173 | * Creates a new {@link Controller} but does not {@linkplain 174 | * #start() start it}. 175 | * 176 | * @paramThis method never returns {@code null}.
461 | * 462 | *Overrides of this method must not return {@code null}.
463 | * 464 | * @return a non-{@code null} {@link Logger} 465 | */ 466 | protected Logger createLogger() { 467 | return Logger.getLogger(this.getClass().getName()); 468 | } 469 | 470 | /** 471 | * Blocks until the {@link EventQueueCollection} affiliated with 472 | * this {@link Controller} {@linkplain 473 | * EventQueueCollection#isSynchronized() has synchronized}. 474 | * 475 | * @exception InterruptedException if the current {@link Thread} was 476 | * interrupted 477 | */ 478 | @Blocking 479 | public final void awaitEventCacheSynchronization() throws InterruptedException { 480 | this.synchronizationAwaiter.await(); 481 | } 482 | 483 | /** 484 | * Blocks for the desired amount of time until the {@link 485 | * EventQueueCollection} affiliated with this {@link Controller} 486 | * {@linkplain EventQueueCollection#isSynchronized() has 487 | * synchronized} or the amount of time has elapsed. 488 | * 489 | * @param timeout the amount of time to wait 490 | * 491 | * @param timeUnit the {@link TimeUnit} designating the amount of 492 | * time to wait; must not be {@code null} 493 | * 494 | * @return {@code false} if the waiting time elapsed before the 495 | * event cache synchronized; {@code true} otherwise 496 | * 497 | * @exception InterruptedException if the current {@link Thread} was 498 | * interrupted 499 | * 500 | * @exception NullPointerException if {@code timeUnit} is {@code 501 | * null} 502 | * 503 | * @see EventQueueCollection.SynchronizationAwaitingPropertyChangeListener 504 | */ 505 | @Blocking 506 | public final boolean awaitEventCacheSynchronization(final long timeout, final TimeUnit timeUnit) throws InterruptedException { 507 | return this.synchronizationAwaiter.await(timeout, timeUnit); 508 | } 509 | 510 | /** 511 | * {@linkplain EventQueueCollection#start(Consumer) Starts the 512 | * embeddedEventQueueCollection consumption machinery}
513 | * and then {@linkplain Reflector#start() starts the embedded
514 | * Reflector}.
515 | *
516 | * @exception IOException if {@link Reflector#start()} throws an
517 | * {@link IOException}
518 | *
519 | * @exception KubernetesClientException if the {@linkplain Reflector
520 | * embedded Reflector} could not be started
521 | *
522 | * @see EventQueueCollection#start(Consumer)
523 | *
524 | * @see Reflector#start()
525 | */
526 | @NonBlocking
527 | public final void start() throws IOException {
528 | final String cn = this.getClass().getName();
529 | final String mn = "start";
530 | if (this.logger.isLoggable(Level.FINER)) {
531 | this.logger.entering(cn, mn);
532 | }
533 |
534 | // Start the consumer that is going to drain our associated
535 | // EventQueueCollection.
536 | if (this.logger.isLoggable(Level.INFO)) {
537 | this.logger.logp(Level.INFO, cn, mn, "Starting {0}", this.eventQueueConsumer);
538 | }
539 | final Future eventQueueConsumerTask = this.eventQueueCollection.start(this.eventQueueConsumer);
540 | assert eventQueueConsumerTask != null;
541 |
542 | // Start the Reflector--the machinery that is going to connect to
543 | // Kubernetes and "reflect" its (relevant) contents into the
544 | // EventQueueCollection.
545 | if (this.logger.isLoggable(Level.INFO)) {
546 | this.logger.logp(Level.INFO, cn, mn, "Starting {0}", this.reflector);
547 | }
548 | try {
549 | this.reflector.start();
550 | } catch (final IOException | RuntimeException | Error reflectorStartFailure) {
551 | try {
552 | // TODO: this is problematic, I think; reflector.close() means
553 | // that (potentially) it will never be able to restart it.
554 | // The Go code appears to make some feints in the direction of
555 | // restartability, and then just basically gives up. I think
556 | // we can do better here.
557 | this.reflector.close();
558 | } catch (final Throwable suppressMe) {
559 | reflectorStartFailure.addSuppressed(suppressMe);
560 | }
561 | eventQueueConsumerTask.cancel(true);
562 | assert eventQueueConsumerTask.isDone();
563 | try {
564 | this.eventQueueCollection.close();
565 | } catch (final Throwable suppressMe) {
566 | reflectorStartFailure.addSuppressed(suppressMe);
567 | }
568 | throw reflectorStartFailure;
569 | }
570 |
571 | if (this.logger.isLoggable(Level.FINER)) {
572 | this.logger.exiting(cn, mn);
573 | }
574 | }
575 |
576 | /**
577 | * {@linkplain Reflector#close() Closes the embedded
578 | * Reflector} and then {@linkplain
579 | * EventQueueCollection#close() closes the embedded
580 | * EventQueueCollection}, handling exceptions
581 | * appropriately.
582 | *
583 | * @exception IOException if the {@link Reflector} could not
584 | * {@linkplain Reflector#close() close} properly
585 | *
586 | * @see Reflector#close()
587 | *
588 | * @see EventQueueCollection#close()
589 | */
590 | @Override
591 | public final void close() throws IOException {
592 | final String cn = this.getClass().getName();
593 | final String mn = "close";
594 | if (this.logger.isLoggable(Level.FINER)) {
595 | this.logger.entering(cn, mn);
596 | }
597 | Exception throwMe = null;
598 | try {
599 | if (this.logger.isLoggable(Level.INFO)) {
600 | this.logger.logp(Level.INFO, cn, mn, "Closing {0}", this.reflector);
601 | }
602 | this.reflector.close();
603 | } catch (final Exception everything) {
604 | throwMe = everything;
605 | }
606 |
607 | try {
608 | if (this.logger.isLoggable(Level.INFO)) {
609 | this.logger.logp(Level.INFO, cn, mn, "Closing {0}", this.eventQueueCollection);
610 | }
611 | this.eventQueueCollection.close();
612 | } catch (final RuntimeException | Error runtimeException) {
613 | if (throwMe == null) {
614 | throw runtimeException;
615 | }
616 | throwMe.addSuppressed(runtimeException);
617 | }
618 |
619 | if (throwMe instanceof IOException) {
620 | throw (IOException)throwMe;
621 | } else if (throwMe instanceof RuntimeException) {
622 | throw (RuntimeException)throwMe;
623 | } else if (throwMe != null) {
624 | throw new IllegalStateException(throwMe.getMessage(), throwMe);
625 | }
626 |
627 | if (this.logger.isLoggable(Level.FINER)) {
628 | this.logger.exiting(cn, mn);
629 | }
630 | }
631 |
632 | /**
633 | * Returns if the embedded {@link Reflector} should {@linkplain
634 | * Reflector#shouldSynchronize() synchronize}.
635 | *
636 | * This implementation returns {@code true}.
637 | * 638 | * @return {@code true} if the embedded {@link Reflector} should 639 | * {@linkplain Reflector#shouldSynchronize() synchronize}; {@code 640 | * false} otherwise 641 | */ 642 | protected boolean shouldSynchronize() { 643 | final String cn = this.getClass().getName(); 644 | final String mn = "shouldSynchronize"; 645 | if (this.logger.isLoggable(Level.FINER)) { 646 | this.logger.entering(cn, mn); 647 | } 648 | final boolean returnValue = true; 649 | if (this.logger.isLoggable(Level.FINER)) { 650 | this.logger.exiting(cn, mn, Boolean.valueOf(returnValue)); 651 | } 652 | return returnValue; 653 | } 654 | 655 | /** 656 | * Invoked after the embedded {@link Reflector} {@linkplain 657 | * Reflector#onClose() closes}. 658 | * 659 | *This implementation does nothing.
660 | * 661 | * @see Reflector#close() 662 | * 663 | * @see Reflector#onClose() 664 | */ 665 | protected void onClose() { 666 | 667 | } 668 | 669 | /** 670 | * Returns a key that can be used to identify the supplied {@link 671 | * HasMetadata}. 672 | * 673 | *This method never returns {@code null}.
674 | * 675 | *Overrides of this method must not return {@code null}.
676 | * 677 | *The default implementation of this method returns the return 678 | * value of invoking the {@link HasMetadatas#getKey(HasMetadata)} 679 | * method.
680 | * 681 | * @param resource the Kubernetes resource for which a key is 682 | * desired; must not be {@code null} 683 | * 684 | * @return a non-{@code null} key for the supplied {@link 685 | * HasMetadata} 686 | * 687 | * @exception NullPointerException if {@code resource} is {@code 688 | * null} 689 | */ 690 | protected Object getKey(final T resource) { 691 | final String cn = this.getClass().getName(); 692 | final String mn = "getKey"; 693 | if (this.logger.isLoggable(Level.FINER)) { 694 | this.logger.entering(cn, mn, resource); 695 | } 696 | final Object returnValue = HasMetadatas.getKey(Objects.requireNonNull(resource)); 697 | if (this.logger.isLoggable(Level.FINER)) { 698 | this.logger.exiting(cn, mn, returnValue); 699 | } 700 | return returnValue; 701 | } 702 | 703 | /** 704 | * Creates a new {@link Event} when invoked. 705 | * 706 | *This method never returns {@code null}.
707 | * 708 | *Overrides of this method must not return {@code null}.
709 | * 710 | *Overrides of this method must return a new {@link Event} or 711 | * subclass with each invocation.
712 | * 713 | * @param source the source of the new {@link Event}; must not be 714 | * {@code null} 715 | * 716 | * @param eventType the {@link Event.Type} for the new {@link 717 | * Event}; must not be {@code null} 718 | * 719 | * @param resource the {@link HasMetadata} that the new {@link 720 | * Event} concerns; must not be {@code null} 721 | * 722 | * @return a new, non-{@code null} {@link Event} 723 | * 724 | * @exception NullPointerException if any of the parameters is 725 | * {@code null} 726 | */ 727 | protected EventThis method never returns {@code null}.
744 | * 745 | *Overrides of this method must not return {@code null}.
746 | * 747 | *Overrides of this method must return a new {@link EventQueue} 748 | * or subclass with each invocation.
749 | * 750 | * @param key the key to create the new {@link EventQueue} with; 751 | * must not be {@code null} 752 | * 753 | * @return a new, non-{@code null} {@link EventQueue} 754 | * 755 | * @exception NullPointerException if {@code key} is {@code null} 756 | */ 757 | protected EventQueueEvent primarily concerns}; may
70 | * be—and often is—null
71 | *
72 | * @param resource a {@link HasMetadata} representing a Kubernetes
73 | * resource; must not be {@code null}
74 | *
75 | * @exception NullPointerException if {@code source}, {@code type}
76 | * or {@code resource} is {@code null}
77 | *
78 | * @see Type
79 | *
80 | * @see EventObject#getSource()
81 | */
82 | public Event(final Object source, final Type type, final T priorResource, final T resource) {
83 | super(source, type, priorResource, resource);
84 | }
85 |
86 |
87 | /*
88 | * Instance methods.
89 | */
90 |
91 |
92 | /**
93 | * Returns {@code true} if the supplied {@link Object} is also an
94 | * {@link Event} and is equal in every respect to this one.
95 | *
96 | * @param other the {@link Object} to test; may be {@code null} in
97 | * which case {@code false} will be returned
98 | *
99 | * @return {@code true} if the supplied {@link Object} is also an
100 | * {@link Event} and is equal in every respect to this one; {@code
101 | * false} otherwise
102 | */
103 | @Override
104 | public boolean equals(final Object other) {
105 | if (other == this) {
106 | return true;
107 | } else if (other instanceof Event) {
108 |
109 | final boolean superEquals = super.equals(other);
110 | if (!superEquals) {
111 | return false;
112 | }
113 |
114 | return true;
115 | } else {
116 | return false;
117 | }
118 | }
119 |
120 | }
121 |
--------------------------------------------------------------------------------
/src/main/java/org/microbean/kubernetes/controller/EventCache.java:
--------------------------------------------------------------------------------
1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
2 | *
3 | * Copyright © 2017-2018 microBean.
4 | *
5 | * Licensed under the Apache License, Version 2.0 (the "License");
6 | * you may not use this file except in compliance with the License.
7 | * You may obtain a copy of the License at
8 | *
9 | * http://www.apache.org/licenses/LICENSE-2.0
10 | *
11 | * Unless required by applicable law or agreed to in writing, software
12 | * distributed under the License is distributed on an "AS IS" BASIS,
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
14 | * implied. See the License for the specific language governing
15 | * permissions and limitations under the License.
16 | */
17 | package org.microbean.kubernetes.controller;
18 |
19 | import java.util.Collection;
20 |
21 | import io.fabric8.kubernetes.api.model.HasMetadata;
22 |
23 | /**
24 | * A minimalistic interface indicating that its implementations cache
25 | * {@link Event}s representing Kubernetes resources.
26 | *
27 | * Instances of implementations of this interface must be 30 | * safe for concurrent usage by multiple {@link Thread}s.
31 | * 32 | * @paramImplementations of this method may return {@code null} to 49 | * indicate that for whatever reason no {@link Event} was actually 50 | * added.
51 | * 52 | * @param source the {@linkplain Event#getSource() source} of the 53 | * {@link Event} that will be created and added; must not be {@code 54 | * null} 55 | * 56 | * @param eventType the {@linkplain Event#getType() type} of {@link 57 | * Event} that will be created and added; must not be {@code null} 58 | * 59 | * @param resource the {@linkplain Event#getResource() resource} of 60 | * the {@link Event} that will be created and added must not be 61 | * {@code null} 62 | * 63 | * @return the {@link Event} that was created and added, or {@code 64 | * null} if no {@link Event} was actually added as a result of this 65 | * method's invocation 66 | * 67 | * @exception NullPointerException if any of the parameters is 68 | * {@code null} 69 | * 70 | * @see Event 71 | */ 72 | public EventNot all {@link EventCache} implementations need support 97 | * synchronization. An implementation of this method that does 98 | * nothing is explicitly permitted.
99 | * 100 | *Implementations of this method must expect to be called on a 101 | * fixed schedule.
102 | 103 | *This method emulates the {@code 107 | * Resync} function in the Go code's {@code DeltaFifo} construct 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.
117 | * 118 | * @see SynchronizationEvent 119 | */ 120 | public void synchronize(); 121 | 122 | } 123 | -------------------------------------------------------------------------------- /src/main/java/org/microbean/kubernetes/controller/EventDistributor.java: -------------------------------------------------------------------------------- 1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 2 | * 3 | * Copyright © 2017-2018 microBean. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 | * implied. See the License for the specific language governing 15 | * permissions and limitations under the License. 16 | */ 17 | package org.microbean.kubernetes.controller; 18 | 19 | import java.io.IOException; 20 | 21 | import java.time.Duration; 22 | import java.time.Instant; 23 | 24 | import java.util.ArrayList; 25 | import java.util.Collection; 26 | import java.util.Iterator; 27 | import java.util.Map; 28 | import java.util.Objects; 29 | 30 | import java.util.concurrent.BlockingQueue; 31 | import java.util.concurrent.CancellationException; 32 | import java.util.concurrent.ExecutionException; 33 | import java.util.concurrent.Executor; 34 | import java.util.concurrent.Executors; 35 | import java.util.concurrent.ExecutorService; 36 | import java.util.concurrent.Future; 37 | import java.util.concurrent.CopyOnWriteArrayList; 38 | import java.util.concurrent.LinkedBlockingQueue; 39 | import java.util.concurrent.ScheduledExecutorService; 40 | import java.util.concurrent.ScheduledThreadPoolExecutor; 41 | import java.util.concurrent.ThreadFactory; 42 | import java.util.concurrent.TimeUnit; 43 | 44 | import java.util.concurrent.atomic.AtomicInteger; 45 | 46 | import java.util.concurrent.locks.Lock; 47 | import java.util.concurrent.locks.ReadWriteLock; 48 | import java.util.concurrent.locks.ReentrantReadWriteLock; 49 | 50 | import java.util.function.Consumer; 51 | import java.util.function.Function; 52 | 53 | import java.util.logging.Level; 54 | import java.util.logging.Logger; 55 | 56 | import io.fabric8.kubernetes.api.model.HasMetadata; 57 | 58 | import net.jcip.annotations.Immutable; 59 | import net.jcip.annotations.GuardedBy; 60 | import net.jcip.annotations.ThreadSafe; 61 | 62 | /** 63 | * A {@link ResourceTrackingEventQueueConsumer} that {@linkplain 64 | * ResourceTrackingEventQueueConsumer#accept(EventQueue) consumes 65 | * EventQueue instances} by feeding each {@link 66 | * AbstractEvent} in the {@link EventQueue} being consumed to {@link 67 | * Consumer}s of {@link AbstractEvent}s that have been {@linkplain 68 | * #addConsumer(Consumer) registered}. 69 | * 70 | *{@link EventDistributor} instances must be {@linkplain #close() 71 | * closed} and discarded after use.
72 | * 73 | * @paramThe supplied {@link Consumer}'s {@link 163 | * Consumer#accept(Object)} method may be called later on a separate 164 | * thread of execution.
165 | * 166 | * @param consumer a {@link Consumer} of {@link AbstractEvent}s; may 167 | * be {@code null} in which case no action will be taken 168 | * 169 | * @see #addConsumer(Consumer, Function) 170 | * 171 | * @see #removeConsumer(Consumer) 172 | */ 173 | public final void addConsumer(final Consumer> consumer) { 174 | this.addConsumer(consumer, null); 175 | } 176 | 177 | /** 178 | * Adds the supplied {@link Consumer} to this {@link 179 | * EventDistributor} as a listener that will be notified of each 180 | * {@link AbstractEvent} this {@link EventDistributor} receives. 181 | * 182 | *The supplied {@link Consumer}'s {@link 183 | * Consumer#accept(Object)} method may be called later on a separate 184 | * thread of execution.
185 | * 186 | * @param consumer a {@link Consumer} of {@link AbstractEvent}s; may 187 | * be {@code null} in which case no action will be taken 188 | * 189 | * @param errorHandler a {@link Function} to handle any {@link 190 | * Throwable}s encountered; may be {@code null} in which case a 191 | * default error handler will be used instead 192 | * 193 | * @see #removeConsumer(Consumer) 194 | */ 195 | public final void addConsumer(final Consumer> consumer, final Function errorHandler) { 196 | if (consumer != null) { 197 | this.writeLock.lock(); 198 | try { 199 | final PumpThe Kubernetes {@code tools/cache} package spreads 265 | * synchronization out among the reflector, controller, event cache 266 | * and event processor constructs for no seemingly good reason. 267 | * They should probably be consolidated, particularly in an 268 | * object-oriented environment such as Java.
269 | * 270 | * @return {@code true} if synchronization should occur; {@code 271 | * false} otherwise 272 | * 273 | * @see EventCache#synchronize() 274 | */ 275 | public final boolean shouldSynchronize() { 276 | boolean returnValue = false; 277 | this.writeLock.lock(); 278 | try { 279 | this.synchronizingPumps.clear(); 280 | final Instant now = Instant.now(); 281 | this.pumps.stream() 282 | .filter(pump -> pump.shouldSynchronize(now)) 283 | .forEach(pump -> { 284 | this.synchronizingPumps.add(pump); 285 | pump.determineNextSynchronizationInterval(now); 286 | }); 287 | returnValue = !this.synchronizingPumps.isEmpty(); 288 | } finally { 289 | this.writeLock.unlock(); 290 | } 291 | return returnValue; 292 | } 293 | 294 | /** 295 | * Consumes the supplied {@link AbstractEvent} by forwarding it to 296 | * the {@link Consumer#accept(Object)} method of each {@link 297 | * Consumer} {@linkplain #addConsumer(Consumer) registered} with 298 | * this {@link EventDistributor}. 299 | * 300 | * @param event the {@link AbstractEvent} to forward; may be {@code 301 | * null} in which case no action is taken 302 | * 303 | * @see #addConsumer(Consumer) 304 | * 305 | * @see ResourceTrackingEventQueueConsumer#accept(AbstractEvent) 306 | */ 307 | @Override 308 | protected final void accept(final AbstractEvent event) { 309 | if (event != null) { 310 | if (event instanceof SynchronizationEvent) { 311 | this.accept((SynchronizationEvent)event); 312 | } else if (event instanceof Event) { 313 | this.accept((Event)event); 314 | } else { 315 | assert false : "Unexpected event type: " + event.getClass(); 316 | } 317 | } 318 | } 319 | 320 | private final void accept(final SynchronizationEvent event) { 321 | this.readLock.lock(); 322 | try { 323 | if (!this.synchronizingPumps.isEmpty()) { 324 | this.synchronizingPumps.stream() 325 | .forEach(pump -> pump.accept(event)); 326 | } 327 | } finally { 328 | this.readLock.unlock(); 329 | } 330 | } 331 | 332 | private final void accept(final Event event) { 333 | this.readLock.lock(); 334 | try { 335 | if (!this.pumps.isEmpty()) { 336 | this.pumps.stream() 337 | .forEach(pump -> pump.accept(event)); 338 | } 339 | } finally { 340 | this.readLock.unlock(); 341 | } 342 | } 343 | 344 | 345 | /* 346 | * Inner and nested classes. 347 | */ 348 | 349 | 350 | /** 351 | * A {@link Consumer} of {@link AbstractEvent} instances that puts 352 | * them on an internal queue and, in a separate thread, removes them 353 | * from the queue and forwards them to the "real" {@link Consumer} 354 | * supplied at construction time. 355 | * 356 | *A {@link Pump} differs from a simple {@link Consumer} of 357 | * {@link AbstractEvent} instances in that it has its own 358 | * {@linkplain #getSynchronizationInterval() synchronization 359 | * interval}, and interposes a blocking queue in between the 360 | * reception of an {@link AbstractEvent} and its eventual broadcast.
361 | * 362 | * @author Laird Nelson 364 | */ 365 | private static final class PumpThreads} with sane names.
685 | *
686 | * @author Laird Nelson
688 | */
689 | private static final class PumpThreadFactory implements ThreadFactory {
690 |
691 | private final ThreadGroup group;
692 |
693 | private final AtomicInteger threadNumber = new AtomicInteger(1);
694 |
695 | private PumpThreadFactory() {
696 | final SecurityManager s = System.getSecurityManager();
697 | if (s == null) {
698 | this.group = Thread.currentThread().getThreadGroup();
699 | } else {
700 | this.group = s.getThreadGroup();
701 | }
702 | }
703 |
704 | @Override
705 | public final Thread newThread(final Runnable runnable) {
706 | final Thread returnValue = new Thread(this.group, runnable, "event-pump-thread-" + this.threadNumber.getAndIncrement(), 0);
707 | if (returnValue.isDaemon()) {
708 | returnValue.setDaemon(false);
709 | }
710 | if (returnValue.getPriority() != Thread.NORM_PRIORITY) {
711 | returnValue.setPriority(Thread.NORM_PRIORITY);
712 | }
713 | return returnValue;
714 | }
715 | }
716 |
717 | }
718 |
719 | }
720 |
--------------------------------------------------------------------------------
/src/main/java/org/microbean/kubernetes/controller/EventQueue.java:
--------------------------------------------------------------------------------
1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
2 | *
3 | * Copyright © 2017-2018 microBean.
4 | *
5 | * Licensed under the Apache License, Version 2.0 (the "License");
6 | * you may not use this file except in compliance with the License.
7 | * You may obtain a copy of the License at
8 | *
9 | * http://www.apache.org/licenses/LICENSE-2.0
10 | *
11 | * Unless required by applicable law or agreed to in writing, software
12 | * distributed under the License is distributed on an "AS IS" BASIS,
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
14 | * implied. See the License for the specific language governing
15 | * permissions and limitations under the License.
16 | */
17 | package org.microbean.kubernetes.controller;
18 |
19 | import java.util.AbstractCollection;
20 | import java.util.Collection;
21 | import java.util.Collections;
22 | import java.util.Iterator;
23 | import java.util.LinkedList;
24 | import java.util.NoSuchElementException; // for javadoc only
25 | import java.util.Objects;
26 |
27 | import java.util.function.Consumer;
28 |
29 | import java.util.logging.Level;
30 | import java.util.logging.Logger;
31 |
32 | import io.fabric8.kubernetes.api.model.HasMetadata;
33 |
34 | import net.jcip.annotations.GuardedBy;
35 | import net.jcip.annotations.ThreadSafe;
36 |
37 | /**
38 | * A publicly-unmodifiable {@link AbstractCollection} of {@link
39 | * AbstractEvent}s produced by an {@link EventQueueCollection}.
40 | *
41 | * All {@link AbstractEvent}s in an {@link EventQueue} describe the 42 | * life of a single {@linkplain HasMetadata resource} in 43 | * Kubernetes.
44 | * 45 | *This class is safe for concurrent use by multiple {@link 48 | * Thread}s. Some operations, like the usage of the {@link 49 | * #iterator()} method, require that callers synchronize on the {@link 50 | * EventQueue} directly. This class' internals synchronize on {@code 51 | * this} when locking is needed.
52 | * 53 | *Overrides of this class must also be safe for concurrent use by 54 | * multiple {@link Thread}s.
55 | * 56 | * @paramThis field is never {@code null}.
76 | * 77 | * @see #createLogger() 78 | */ 79 | protected final Logger logger; 80 | 81 | /** 82 | * The key identifying the Kubernetes resource to which all of the 83 | * {@link AbstractEvent}s managed by this {@link EventQueue} apply. 84 | * 85 | *This field is never {@code null}.
86 | */ 87 | private final Object key; 88 | 89 | /** 90 | * The actual underlying queue of {@link AbstractEvent}s. 91 | * 92 | *This field is never {@code null}.
93 | */ 94 | @GuardedBy("this") 95 | private final LinkedListThis method never returns {@code null}.
143 | * 144 | *Overrides of this method must not return {@code null}.
145 | * 146 | * @return a non-{@code null} {@link Logger} 147 | */ 148 | protected Logger createLogger() { 149 | return Logger.getLogger(this.getClass().getName()); 150 | } 151 | 152 | /** 153 | * Returns the key identifying the Kubernetes resource to which all 154 | * of the {@link AbstractEvent}s managed by this {@link EventQueue} 155 | * apply. 156 | * 157 | *This method never returns {@code null}.
158 | * 159 | * @return a non-{@code null} {@link Object} 160 | * 161 | * @see #EventQueue(Object) 162 | */ 163 | public final Object getKey() { 164 | final String cn = this.getClass().getName(); 165 | final String mn = "getKey"; 166 | if (this.logger.isLoggable(Level.FINER)) { 167 | this.logger.entering(cn, mn); 168 | } 169 | final Object returnValue = this.key; 170 | if (this.logger.isLoggable(Level.FINER)) { 171 | this.logger.entering(cn, mn, returnValue); 172 | } 173 | return returnValue; 174 | } 175 | 176 | /** 177 | * Returns {@code true} if this {@link EventQueue} is empty. 178 | * 179 | * @return {@code true} if this {@link EventQueue} is empty; {@code 180 | * false} otherwise 181 | * 182 | * @see #size() 183 | */ 184 | public synchronized final boolean isEmpty() { 185 | final String cn = this.getClass().getName(); 186 | final String mn = "isEmpty"; 187 | if (this.logger.isLoggable(Level.FINER)) { 188 | this.logger.entering(cn, mn); 189 | } 190 | final boolean returnValue = this.events.isEmpty(); 191 | if (this.logger.isLoggable(Level.FINER)) { 192 | this.logger.exiting(cn, mn, Boolean.valueOf(returnValue)); 193 | } 194 | return returnValue; 195 | } 196 | 197 | /** 198 | * Returns the size of this {@link EventQueue}. 199 | * 200 | *This method never returns an {@code int} less than {@code 201 | * 0}.
202 | * 203 | * @return the size of this {@link EventQueue}; never negative 204 | * 205 | * @see #isEmpty() 206 | */ 207 | @Override 208 | public synchronized final int size() { 209 | final String cn = this.getClass().getName(); 210 | final String mn = "size"; 211 | if (this.logger.isLoggable(Level.FINER)) { 212 | this.logger.entering(cn, mn); 213 | } 214 | final int returnValue = this.events.size(); 215 | if (this.logger.isLoggable(Level.FINER)) { 216 | this.logger.exiting(cn, mn, Integer.valueOf(returnValue)); 217 | } 218 | return returnValue; 219 | } 220 | 221 | /** 222 | * Adds the supplied {@link AbstractEvent} to this {@link 223 | * EventQueue} under certain conditions. 224 | * 225 | *The supplied {@link AbstractEvent} is added to this {@link 226 | * EventQueue} if:
227 | * 228 | *This method never returns {@code null}.
316 | * 317 | * @return the last {@link AbstractEvent} in this {@link 318 | * EventQueue}; never {@code null} 319 | * 320 | * @exception NoSuchElementException if this {@link EventQueue} is 321 | * {@linkplain #isEmpty() empty} 322 | */ 323 | synchronized final AbstractEventThis method never returns {@code null}.
358 | * 359 | * @return a non-{@code null} unmodifiable {@link Iterator} of 360 | * {@link AbstractEvent}s 361 | */ 362 | @Override 363 | public synchronized final IteratorThis method is called only by the {@link #addEvent(AbstractEvent)} 376 | * method.
377 | * 378 | * @see #addEvent(AbstractEvent) 379 | */ 380 | private synchronized final void deduplicate() { 381 | final String cn = this.getClass().getName(); 382 | final String mn = "deduplicate"; 383 | if (this.logger.isLoggable(Level.FINER)) { 384 | this.logger.entering(cn, mn); 385 | } 386 | final int size = this.size(); 387 | if (size > 2) { 388 | final AbstractEventAbstractEvent in this EventQueue} is a
410 | * {@linkplain AbstractEvent.Type#DELETION deletion event}.
411 | *
412 | * @return {@code true} if this {@link EventQueue} currently
413 | * logically represents the deletion of a resource, {@code false}
414 | * otherwise
415 | */
416 | synchronized final boolean resultsInDeletion() {
417 | final String cn = this.getClass().getName();
418 | final String mn = "resultsInDeletion";
419 | if (this.logger.isLoggable(Level.FINER)) {
420 | this.logger.entering(cn, mn);
421 | }
422 | final boolean returnValue = !this.isEmpty() && this.getLast().getType().equals(AbstractEvent.Type.DELETION);
423 | if (this.logger.isLoggable(Level.FINER)) {
424 | this.logger.exiting(cn, mn, Boolean.valueOf(returnValue));
425 | }
426 | return returnValue;
427 | }
428 |
429 | /**
430 | * Performs a compression operation on the supplied {@link
431 | * Collection} of {@link AbstractEvent}s and returns the result of that
432 | * operation.
433 | *
434 | * This method may return {@code null}, which will result in the 435 | * emptying of this {@link EventQueue}.
436 | * 437 | *This method is called while holding this {@link EventQueue}'s 438 | * monitor.
439 | * 440 | *This method is called when an {@link EventQueueCollection} (or 441 | * some other {@link AbstractEvent} producer with access to 442 | * package-protected methods of this class) adds an {@link AbstractEvent} to 443 | * this {@link EventQueue} and provides the {@link EventQueue} 444 | * implementation with the ability to eliminate duplicates or 445 | * otherwise compress the event stream it represents.
446 | * 447 | *This implementation simply returns the supplied {@code events} 448 | * {@link Collection}; i.e. no compression is performed.
449 | * 450 | * @param events an {@link 451 | * Collections#unmodifiableCollection(Collection) unmodifiable 452 | * Collection} of {@link AbstractEvent}s representing the 453 | * current state of this {@link EventQueue}; will never be {@code 454 | * null} 455 | * 456 | * @return the new state that this {@link EventQueue} should assume; 457 | * may be {@code null}; may simply be the supplied {@code events} 458 | * {@link Collection} if compression is not desired or implemented 459 | */ 460 | protected CollectionThis method never returns {@code null}.
545 | * 546 | * @return a non-{@code null} {@link String} representation of this 547 | * {@link EventQueue} 548 | */ 549 | @Override 550 | public synchronized final String toString() { 551 | return new StringBuilder().append(this.getKey()).append(": ").append(this.events).toString(); 552 | } 553 | 554 | } 555 | -------------------------------------------------------------------------------- /src/main/java/org/microbean/kubernetes/controller/HasMetadatas.java: -------------------------------------------------------------------------------- 1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 2 | * 3 | * Copyright © 2017-2018 microBean. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 | * implied. See the License for the specific language governing 15 | * permissions and limitations under the License. 16 | */ 17 | package org.microbean.kubernetes.controller; 18 | 19 | import java.util.logging.Level; 20 | import java.util.logging.Logger; 21 | 22 | import io.fabric8.kubernetes.api.model.HasMetadata; 23 | import io.fabric8.kubernetes.api.model.ObjectMeta; 24 | 25 | /** 26 | * A utility class for working with {@link HasMetadata} resources. 27 | * 28 | * @author Laird Nelson 30 | * 31 | * @see #getKey(HasMetadata) 32 | * 33 | * @see HasMetadata 34 | */ 35 | public final class HasMetadatas { 36 | 37 | 38 | /* 39 | * Constructors. 40 | */ 41 | 42 | 43 | /** 44 | * Creates a new {@link HasMetadatas}. 45 | */ 46 | private HasMetadatas() { 47 | super(); 48 | } 49 | 50 | 51 | /* 52 | * Static methods. 53 | */ 54 | 55 | 56 | /** 57 | * Returns a key for the supplied {@link HasMetadata} 58 | * derived from its {@linkplain ObjectMeta#getName() name} and 59 | * {@linkplain ObjectMeta#getNamespace() namespace}. 60 | * 61 | *This method may return {@code null}.
62 | * 63 | * @param resource the {@link HasMetadata} for which a key should be 64 | * returned; may be {@code null} in which case {@code null} will be 65 | * returned 66 | * 67 | * @return a key for the supplied {@link HasMetadata} 68 | * 69 | * @exception IllegalStateException if the supplied {@link 70 | * HasMetadata}'s {@linkplain ObjectMeta metadata}'s {@link 71 | * ObjectMeta#getName()} method returns {@code null} or an 72 | * {@linkplain String#isEmpty() empty} {@link String} 73 | * 74 | * @see HasMetadata#getMetadata() 75 | * 76 | * @see ObjectMeta#getName() 77 | * 78 | * @see ObjectMeta#getNamespace() 79 | */ 80 | public static final Object getKey(final HasMetadata resource) { 81 | final String cn = HasMetadatas.class.getName(); 82 | final String mn = "getKey"; 83 | final Logger logger = Logger.getLogger(cn); 84 | assert logger != null; 85 | if (logger.isLoggable(Level.FINER)) { 86 | logger.entering(cn, mn, resource); 87 | } 88 | 89 | final Object returnValue; 90 | if (resource == null) { 91 | returnValue = null; 92 | } else { 93 | final ObjectMeta metadata = resource.getMetadata(); 94 | if (metadata == null) { 95 | returnValue = null; 96 | } else { 97 | String name = metadata.getName(); 98 | if (name == null) { 99 | throw new IllegalStateException("metadata.getName() == null"); 100 | } else if (name.isEmpty()) { 101 | throw new IllegalStateException("metadata.getName().isEmpty()"); 102 | } 103 | final String namespace = metadata.getNamespace(); 104 | if (namespace == null || namespace.isEmpty()) { 105 | returnValue = name; 106 | } else { 107 | returnValue = new StringBuilder(namespace).append("/").append(name).toString(); 108 | } 109 | } 110 | } 111 | 112 | if (logger.isLoggable(Level.FINER)) { 113 | logger.exiting(cn, mn, returnValue); 114 | } 115 | return returnValue; 116 | } 117 | 118 | } 119 | -------------------------------------------------------------------------------- /src/main/java/org/microbean/kubernetes/controller/Reflector.java: -------------------------------------------------------------------------------- 1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 2 | * 3 | * Copyright © 2017-2018 microBean. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 | * implied. See the License for the specific language governing 15 | * permissions and limitations under the License. 16 | */ 17 | package org.microbean.kubernetes.controller; 18 | 19 | import java.io.Closeable; 20 | import java.io.IOException; 21 | 22 | import java.lang.reflect.Field; 23 | import java.lang.reflect.Method; 24 | 25 | import java.time.Duration; 26 | 27 | import java.time.temporal.ChronoUnit; 28 | 29 | import java.util.ArrayList; 30 | import java.util.Collection; 31 | import java.util.Collections; 32 | import java.util.Objects; 33 | import java.util.Map; 34 | 35 | import java.util.concurrent.ExecutionException; 36 | import java.util.concurrent.Executors; 37 | import java.util.concurrent.Future; 38 | import java.util.concurrent.FutureTask; 39 | import java.util.concurrent.ScheduledExecutorService; 40 | import java.util.concurrent.ScheduledFuture; 41 | import java.util.concurrent.ScheduledThreadPoolExecutor; 42 | import java.util.concurrent.TimeUnit; 43 | 44 | import java.util.function.Function; 45 | 46 | import java.util.logging.Level; 47 | import java.util.logging.Logger; 48 | 49 | import io.fabric8.kubernetes.client.DefaultKubernetesClient; // for javadoc only 50 | import io.fabric8.kubernetes.client.KubernetesClientException; 51 | import io.fabric8.kubernetes.client.Watch; // for javadoc only 52 | import io.fabric8.kubernetes.client.Watcher; 53 | 54 | import io.fabric8.kubernetes.client.dsl.base.BaseOperation; 55 | import io.fabric8.kubernetes.client.dsl.base.OperationSupport; 56 | 57 | import io.fabric8.kubernetes.client.dsl.Listable; 58 | import io.fabric8.kubernetes.client.dsl.Versionable; 59 | import io.fabric8.kubernetes.client.dsl.VersionWatchable; 60 | import io.fabric8.kubernetes.client.dsl.Watchable; 61 | 62 | import io.fabric8.kubernetes.client.dsl.internal.CustomResourceOperationsImpl; 63 | 64 | import io.fabric8.kubernetes.api.model.HasMetadata; 65 | import io.fabric8.kubernetes.api.model.ObjectMeta; 66 | import io.fabric8.kubernetes.api.model.KubernetesResourceList; 67 | import io.fabric8.kubernetes.api.model.ListMeta; 68 | 69 | import net.jcip.annotations.GuardedBy; 70 | import net.jcip.annotations.ThreadSafe; 71 | 72 | import okhttp3.OkHttpClient; 73 | 74 | import org.microbean.development.annotation.Hack; 75 | import org.microbean.development.annotation.Issue; 76 | import org.microbean.development.annotation.NonBlocking; 77 | 78 | /** 79 | * A pump of sorts that continuously "pulls" logical events out of 80 | * Kubernetes and {@linkplain EventCache#add(Object, AbstractEvent.Type, 81 | * HasMetadata) adds them} to an {@link EventCache} so as to logically 82 | * "reflect" the contents of Kubernetes into the cache. 83 | * 84 | *Instances of this class are safe for concurrent use by multiple 87 | * {@link Thread}s.
88 | * 89 | *This class loosely models the {@code 93 | * Reflector} type in the {@code tools/cache} package of the {@code 94 | * client-go} subproject of Kubernetes.
95 | * 96 | * @paramThis field is never {@code null}.
116 | * 117 | *It is guaranteed that the value of this field may be 118 | * assignable to a reference of type {@link Listable Listable<? 119 | * extends KubernetesResourceList>} or to a reference of type 120 | * {@link VersionWatchable VersionWatchable<? extends Closeable, 121 | * Watcher<T>>}.
122 | * 123 | * @see Listable 124 | * 125 | * @see VersionWatchable 126 | */ 127 | private final Object operation; 128 | 129 | /** 130 | * The resource version that a successful watch operation processed. 131 | * 132 | * @see #setLastSynchronizationResourceVersion(Object) 133 | * 134 | * @see WatchHandler#eventReceived(Watcher.Action, HasMetadata) 135 | */ 136 | private volatile Object lastSynchronizationResourceVersion; 137 | 138 | /** 139 | * The {@link ScheduledExecutorService} in charge of scheduling 140 | * repeated invocations of the {@link #synchronize()} method. 141 | * 142 | *This field may be {@code null}.
143 | * 144 | *This field is not safe for concurrent use by multiple threads 147 | * without explicit synchronization on it.
148 | * 149 | * @see #synchronize() 150 | */ 151 | @GuardedBy("this") 152 | private ScheduledExecutorService synchronizationExecutorService; 153 | 154 | /** 155 | * A {@link Function} that consumes a {@link Throwable} and returns 156 | * {@code true} if the error represented by that {@link Throwable} 157 | * was handled in some way. 158 | * 159 | *This field may be {@code null}.
160 | */ 161 | private final Function synchronizationErrorHandler; 162 | 163 | /** 164 | * A {@link ScheduledFuture} representing the task that is scheduled 165 | * to repeatedly invoke the {@link #synchronize()} method. 166 | * 167 | *This field may be {@code null}.
168 | * 169 | *This field is not safe for concurrent use by multiple threads 172 | * without explicit synchronization on it.
173 | * 174 | * @see #synchronize() 175 | */ 176 | @GuardedBy("this") 177 | private ScheduledFuture synchronizationTask; 178 | 179 | /** 180 | * A flag tracking whether the {@link 181 | * #synchronizationExecutorService} should be shut down when this 182 | * {@link Reflector} is {@linkplain #close() closed}. If the 183 | * creator of this {@link Reflector} supplied an explicit {@link 184 | * ScheduledExecutorService} at construction time, then it will not 185 | * be shut down. 186 | */ 187 | private final boolean shutdownSynchronizationExecutorServiceOnClose; 188 | 189 | /** 190 | * How many seconds to wait in between scheduled invocations of the 191 | * {@link #synchronize()} method. If the value of this field is 192 | * less than or equal to zero then no synchronization will take 193 | * place. 194 | */ 195 | private final long synchronizationIntervalInSeconds; 196 | 197 | /** 198 | * The watch operation currently in effect. 199 | * 200 | *This field may be {@code null} at any point.
201 | * 202 | *This field is not safe for concurrent use by multiple threads 205 | * without explicit synchronization on it.
206 | */ 207 | @GuardedBy("this") 208 | private Closeable watch; 209 | 210 | /** 211 | * An {@link EventCache} (often an {@link EventQueueCollection}) 212 | * whose contents will be added to to reflect the current state of 213 | * Kubernetes. 214 | * 215 | *This field is never {@code null}.
216 | */ 217 | @GuardedBy("itself") 218 | private final EventCacheThis field is never {@code null}.
224 | * 225 | * @see #createLogger() 226 | */ 227 | protected final Logger logger; 228 | 229 | 230 | /* 231 | * Constructors. 232 | */ 233 | 234 | 235 | /** 236 | * Creates a new {@link Reflector}. 237 | * 238 | * @paramThis method never returns {@code null}.
457 | * 458 | *Overrides of this method must not return {@code null}.
459 | * 460 | * @return a non-{@code null} {@link Logger} 461 | */ 462 | protected Logger createLogger() { 463 | return Logger.getLogger(this.getClass().getName()); 464 | } 465 | 466 | /** 467 | * Notionally closes this {@link Reflector} by terminating any 468 | * {@link Thread}s that it has started and invoking the {@link 469 | * #onClose()} method while holding this {@link Reflector}'s 470 | * monitor. 471 | * 472 | * @exception IOException if an error occurs 473 | * 474 | * @see #onClose() 475 | */ 476 | @Override 477 | public synchronized final void close() throws IOException { 478 | final String cn = this.getClass().getName(); 479 | final String mn = "close"; 480 | if (this.logger.isLoggable(Level.FINER)) { 481 | this.logger.entering(cn, mn); 482 | } 483 | 484 | try { 485 | this.closeSynchronizationExecutorService(); 486 | if (this.watch != null) { 487 | this.watch.close(); 488 | } 489 | } finally { 490 | this.onClose(); 491 | } 492 | 493 | if (this.logger.isLoggable(Level.FINER)) { 494 | this.logger.exiting(cn, mn); 495 | } 496 | } 497 | 498 | /** 499 | * {@linkplain Future#cancel(boolean) Cancels} scheduled invocations 500 | * of the {@link #synchronize()} method. 501 | * 502 | *This method is invoked by the {@link 503 | * #closeSynchronizationExecutorService()} method.
504 | * 505 | * @see #setUpSynchronization() 506 | * 507 | * @see #closeSynchronizationExecutorService() 508 | */ 509 | private synchronized final void cancelSynchronization() { 510 | final String cn = this.getClass().getName(); 511 | final String mn = "cancelSynchronization"; 512 | if (this.logger.isLoggable(Level.FINER)) { 513 | this.logger.entering(cn, mn); 514 | } 515 | 516 | if (this.synchronizationTask != null) { 517 | this.synchronizationTask.cancel(true /* interrupt the task */); 518 | this.synchronizationTask = null; // very important; see setUpSynchronization() 519 | } 520 | 521 | if (this.logger.isLoggable(Level.FINER)) { 522 | this.logger.exiting(cn, mn); 523 | } 524 | } 525 | 526 | /** 527 | * {@linkplain #cancelSynchronization Cancels scheduled invocations 528 | * of thesynchronize() method} and, when appropriate,
529 | * shuts down the {@link ScheduledExecutorService} responsible for
530 | * the scheduling.
531 | *
532 | * @see #cancelSynchronization()
533 | *
534 | * @see #setUpSynchronization()
535 | */
536 | private synchronized final void closeSynchronizationExecutorService() {
537 | final String cn = this.getClass().getName();
538 | final String mn = "closeSynchronizationExecutorService";
539 | if (this.logger.isLoggable(Level.FINER)) {
540 | this.logger.entering(cn, mn);
541 | }
542 |
543 | this.cancelSynchronization();
544 |
545 | if (this.synchronizationExecutorService != null && this.shutdownSynchronizationExecutorServiceOnClose) {
546 |
547 | // Stop accepting new tasks. Not that any will be showing up
548 | // anyway, but it's the right thing to do.
549 | this.synchronizationExecutorService.shutdown();
550 |
551 | try {
552 | if (!this.synchronizationExecutorService.awaitTermination(60L, TimeUnit.SECONDS)) {
553 | this.synchronizationExecutorService.shutdownNow();
554 | if (!this.synchronizationExecutorService.awaitTermination(60L, TimeUnit.SECONDS)) {
555 | if (this.logger.isLoggable(Level.WARNING)) {
556 | this.logger.logp(Level.WARNING,
557 | cn, mn,
558 | "synchronizationExecutorService did not terminate cleanly after 60 seconds");
559 | }
560 | }
561 | }
562 | } catch (final InterruptedException interruptedException) {
563 | this.synchronizationExecutorService.shutdownNow();
564 | Thread.currentThread().interrupt();
565 | }
566 |
567 | }
568 |
569 | if (this.logger.isLoggable(Level.FINER)) {
570 | this.logger.exiting(cn, mn);
571 | }
572 | }
573 |
574 | /**
575 | * As the name implies, sets up synchronization, which is
576 | * the act of the downstream event cache telling its associated
577 | * event listeners that there are items remaining to be processed,
578 | * and returns a {@link Future} reprsenting the scheduled, repeating
579 | * task.
580 | *
581 | * This method schedules repeated invocations of the {@link 582 | * #synchronize()} method.
583 | * 584 | *This method may return {@code null}.
585 | * 586 | * @return a {@link Future} representing the scheduled repeating 587 | * synchronization task, or {@code null} if no such task was 588 | * scheduled 589 | * 590 | * @see #synchronize() 591 | * 592 | * @see EventCache#synchronize() 593 | */ 594 | private synchronized final Future setUpSynchronization() { 595 | final String cn = this.getClass().getName(); 596 | final String mn = "setUpSynchronization"; 597 | if (this.logger.isLoggable(Level.FINER)) { 598 | this.logger.entering(cn, mn); 599 | } 600 | 601 | if (this.synchronizationIntervalInSeconds > 0L) { 602 | if (this.synchronizationExecutorService == null || this.synchronizationExecutorService.isTerminated()) { 603 | this.synchronizationExecutorService = Executors.newScheduledThreadPool(1); 604 | if (this.synchronizationExecutorService instanceof ScheduledThreadPoolExecutor) { 605 | ((ScheduledThreadPoolExecutor)this.synchronizationExecutorService).setRemoveOnCancelPolicy(true); 606 | } 607 | } 608 | if (this.synchronizationTask == null) { 609 | if (this.logger.isLoggable(Level.INFO)) { 610 | this.logger.logp(Level.INFO, 611 | cn, mn, 612 | "Scheduling downstream synchronization every {0} seconds", 613 | Long.valueOf(this.synchronizationIntervalInSeconds)); 614 | } 615 | this.synchronizationTask = this.synchronizationExecutorService.scheduleWithFixedDelay(this::synchronize, 0L, this.synchronizationIntervalInSeconds, TimeUnit.SECONDS); 616 | } 617 | assert this.synchronizationExecutorService != null; 618 | assert this.synchronizationTask != null; 619 | } 620 | 621 | if (this.logger.isLoggable(Level.FINER)) { 622 | this.logger.exiting(cn, mn, this.synchronizationTask); 623 | } 624 | return this.synchronizationTask; 625 | } 626 | 627 | /** 628 | * Calls {@link EventCache#synchronize()} on this {@link 629 | * Reflector}'s {@linkplain #eventCache affiliated 630 | *EventCache}.
631 | *
632 | * This method is normally invoked on a schedule by this {@link
633 | * Reflector}'s {@linkplain #synchronizationExecutorService
634 | * affiliated ScheduledExecutorService}.
The default implementation of this method returns {@code true} 689 | * if this {@link Reflector} was constructed with an explicit 690 | * synchronization interval or {@link ScheduledExecutorService} or 691 | * both.
692 | * 693 | *This code follows the Go code in the Kubernetes {@code 696 | * client-go/tools/cache} package. One thing that becomes clear 697 | * when looking at all of this through an object-oriented lens is 698 | * that it is the {@link EventCache} (the {@code delta_fifo}, in the 699 | * Go code) that is ultimately in charge of synchronizing. It is 700 | * not clear why in the Go code this is a function of a reflector. 701 | * In an object-oriented world, perhaps the {@link EventCache} 702 | * itself should be in charge of resynchronization schedules, but we 703 | * choose to follow the Go code's division of responsibilities 704 | * here.
705 | * 706 | * @return {@code true} if this {@link Reflector} should cause its 707 | * {@link EventCache} to {@linkplain EventCache#synchronize() 708 | * synchronize}; {@code false} otherwise 709 | */ 710 | protected boolean shouldSynchronize() { 711 | final String cn = this.getClass().getName(); 712 | final String mn = "shouldSynchronize"; 713 | if (this.logger.isLoggable(Level.FINER)) { 714 | this.logger.entering(cn, mn); 715 | } 716 | final boolean returnValue; 717 | synchronized (this) { 718 | returnValue = this.synchronizationExecutorService != null; 719 | } 720 | if (this.logger.isLoggable(Level.FINER)) { 721 | this.logger.exiting(cn, mn, Boolean.valueOf(returnValue)); 722 | } 723 | return returnValue; 724 | } 725 | 726 | // Not used; not used in the Go code either?! 727 | private final Object getLastSynchronizationResourceVersion() { 728 | return this.lastSynchronizationResourceVersion; 729 | } 730 | 731 | /** 732 | * Records the last resource version processed by a successful watch 733 | * operation. 734 | * 735 | * @param resourceVersion the resource version in question; may be 736 | * {@code null} 737 | * 738 | * @see WatchHandler#eventReceived(Watcher.Action, HasMetadata) 739 | */ 740 | private final void setLastSynchronizationResourceVersion(final Object resourceVersion) { 741 | // lastSynchronizationResourceVersion is volatile; this is an 742 | // atomic assignment 743 | this.lastSynchronizationResourceVersion = resourceVersion; 744 | } 745 | 746 | /** 747 | * Using the {@code operation} supplied at construction time, 748 | * {@linkplain Listable#list() lists} appropriate Kubernetes 749 | * resources, and then, on a separate {@link Thread}, {@linkplain 750 | * VersionWatchable sets up a watch} on them, calling {@link 751 | * EventCache#replace(Collection, Object)} and {@link 752 | * EventCache#add(Object, AbstractEvent.Type, HasMetadata)} methods 753 | * as appropriate. 754 | * 755 | *For convenience only, this method returns a 756 | * {@link Future} representing any scheduled synchronization task 757 | * created as a result of the user's having supplied a {@link 758 | * Duration} at construction time. The return value may be (and 759 | * usually is) safely ignored. Invoking {@link 760 | * Future#cancel(boolean)} on the returned {@link Future} will 761 | * result in the scheduled synchronization task being cancelled 762 | * irrevocably. Notably, invoking {@link 763 | * Future#cancel(boolean)} on the returned {@link Future} will 764 | * not {@linkplain #close() close} this {@link 765 | * Reflector}. 766 | * 767 | *
This method never returns {@code null}.
768 | * 769 | *The calling {@link Thread} is not blocked by invocations of 770 | * this method.
771 | * 772 | *This method loosely models the {@code 776 | * Run} function in {@code reflector.go} together with the {@code 777 | * ListAndWatch} function in the same file.
778 | * 779 | * @return a {@link Future} representing a scheduled synchronization 780 | * operation; never {@code null} 781 | * 782 | * @exception IOException if a watch has previously been established 783 | * and could not be {@linkplain Watch#close() closed} 784 | * 785 | * @exception KubernetesClientException if the initial attempt to 786 | * {@linkplain Listable#list() list} Kubernetes resources fails 787 | * 788 | * @see #close() 789 | */ 790 | @NonBlocking 791 | public final Future start() throws IOException { 792 | final String cn = this.getClass().getName(); 793 | final String mn = "start"; 794 | if (this.logger.isLoggable(Level.FINER)) { 795 | this.logger.entering(cn, mn); 796 | } 797 | 798 | Future returnValue = null; 799 | synchronized (this) { 800 | 801 | try { 802 | 803 | // If somehow we got called while a watch already exists, then 804 | // close the old watch (we'll replace it). Note that, 805 | // critically, the onClose() method of our watch handler sets 806 | // this reference to null, so if the watch is in the process 807 | // of being closed, this little block won't be executed. 808 | if (this.watch != null) { 809 | final Closeable watch = this.watch; 810 | this.watch = null; 811 | if (logger.isLoggable(Level.FINE)) { 812 | logger.logp(Level.FINE, 813 | cn, mn, 814 | "Closing pre-existing watch"); 815 | } 816 | watch.close(); 817 | if (logger.isLoggable(Level.FINE)) { 818 | logger.logp(Level.FINE, 819 | cn, mn, 820 | "Closed pre-existing watch"); 821 | } 822 | } 823 | 824 | // Run a list operation, and get the resourceVersion of that list. 825 | if (logger.isLoggable(Level.FINE)) { 826 | logger.logp(Level.FINE, 827 | cn, mn, 828 | "Listing Kubernetes resources using {0}", this.operation); 829 | } 830 | @Issue(id = "13", uri = "https://github.com/microbean/microbean-kubernetes-controller/issues/13") 831 | @SuppressWarnings("unchecked") 832 | final KubernetesResourceList list = ((Listable>)this.operation).list(); 833 | assert list != null; 834 | 835 | final ListMeta metadata = list.getMetadata(); 836 | assert metadata != null; 837 | 838 | final String resourceVersion = metadata.getResourceVersion(); 839 | assert resourceVersion != null; 840 | 841 | // Using the results of that list operation, do a full replace 842 | // on the EventCache with them. 843 | final Collection replacementItems; 844 | final Collection items = list.getItems(); 845 | if (items == null || items.isEmpty()) { 846 | replacementItems = Collections.emptySet(); 847 | } else { 848 | replacementItems = Collections.unmodifiableCollection(new ArrayList<>(items)); 849 | } 850 | 851 | if (logger.isLoggable(Level.FINE)) { 852 | logger.logp(Level.FINE, cn, mn, "Replacing resources in the event cache"); 853 | } 854 | synchronized (this.eventCache) { 855 | this.eventCache.replace(replacementItems, resourceVersion); 856 | } 857 | if (logger.isLoggable(Level.FINE)) { 858 | logger.logp(Level.FINE, cn, mn, "Done replacing resources in the event cache"); 859 | } 860 | 861 | // Record the resource version we captured during our list 862 | // operation. 863 | this.setLastSynchronizationResourceVersion(resourceVersion); 864 | 865 | // Now that we've vetted that our list operation works (i.e. no 866 | // syntax errors, no connectivity problems) we can schedule 867 | // synchronizations if necessary. 868 | // 869 | // A synchronization is an operation where, if allowed, our 870 | // eventCache goes through its set of known objects and--for 871 | // any that are not enqueued for further processing 872 | // already--fires a *synchronization* event of type 873 | // MODIFICATION. This happens on a schedule, not in reaction 874 | // to an event. This allows its downstream processors a 875 | // chance to try to bring system state in line with desired 876 | // state, even if no events have occurred (kind of like a 877 | // heartbeat). See 878 | // https://engineering.bitnami.com/articles/a-deep-dive-into-kubernetes-controllers.html#resyncperiod. 879 | this.setUpSynchronization(); 880 | returnValue = this.synchronizationTask; 881 | 882 | // If there wasn't a synchronizationTask, then that means the 883 | // user who created this Reflector didn't want any 884 | // synchronization to happen. We return a "dummy" Future that 885 | // is already "completed" (isDone() returns true) to avoid 886 | // having to return null. The returned Future can be 887 | // cancelled with no effect. 888 | if (returnValue == null) { 889 | final FutureTask futureTask = new FutureTaskThe default implementation of this method does nothing.
949 | * 950 | *Overrides of this method must consider that they will be 951 | * invoked with this {@link Reflector}'s monitor held.
952 | * 953 | *Overrides of this method must not call the {@link #close()} 954 | * method.
955 | * 956 | * @see #close() 957 | */ 958 | protected synchronized void onClose() { 959 | 960 | } 961 | 962 | 963 | /* 964 | * Inner and nested classes. 965 | */ 966 | 967 | 968 | /** 969 | * A {@link Watcher} of Kubernetes resources. 970 | * 971 | * @author Laird Nelson 973 | * 974 | * @see Watcher 975 | */ 976 | private final class WatchHandler implements WatcherTypically you would supply an implementation of this class to a 37 | * {@link Controller}.
38 | * 39 | * @paramThis field may be {@code null} in which case no resource 61 | * tracking will take place.
62 | * 63 | *The value of this field is {@linkplain 64 | * #ResourceTrackingEventQueueConsumer(Map) supplied at construction 65 | * time} and is synchronized on and written to, if 66 | * non-{@code null}, by the {@link #accept(EventQueue)} method.
67 | * 68 | *This class synchronizes on this field's 69 | * value, if it is non-{@code null}, when mutating its 70 | * contents.
71 | */ 72 | @GuardedBy("itself") 73 | private final MapThis field is never {@code null}.
80 | * 81 | * @see #createLogger() 82 | */ 83 | protected final Logger logger; 84 | 85 | 86 | /* 87 | * Constructors. 88 | */ 89 | 90 | 91 | /** 92 | * Creates a new {@link ResourceTrackingEventQueueConsumer}. 93 | * 94 | * @param knownObjects a mutable {@link Map} of {@link HasMetadata} 95 | * objects indexed by their keys (often a pairing of namespace and 96 | * name); may be {@code null} if deletion tracking is not needed; 97 | * will have its contents changed by this {@link 98 | * ResourceTrackingEventQueueConsumer}'s {@link #accept(EventQueue)} 99 | * method; will be synchronized on by this {@link 100 | * ResourceTrackingEventQueueConsumer}'s {@link #accept(EventQueue)} 101 | * method 102 | * 103 | * @see #accept(EventQueue) 104 | */ 105 | protected ResourceTrackingEventQueueConsumer(final MapThis method never returns {@code null}.
141 | * 142 | *Overrides of this method must not return {@code null}.
143 | * 144 | * @return a non-{@code null} {@link Logger} 145 | */ 146 | protected Logger createLogger() { 147 | return Logger.getLogger(this.getClass().getName()); 148 | } 149 | 150 | 151 | /** 152 | * {@linkplain EventQueue#iterator() Loops through} all the {@link 153 | * AbstractEvent}s in the supplied {@link EventQueue}, keeping track 154 | * of the {@link HasMetadata} it concerns along the way by 155 | * synchronizing on and writing to the {@link Map} 156 | * {@linkplain #ResourceTrackingEventQueueConsumer(Map) supplied at 157 | * construction time}. 158 | * 159 | *Individual {@link AbstractEvent}s are forwarded on to the 160 | * {@link #accept(AbstractEvent)} method.
161 | * 162 | *This loosely models the {@code 166 | * HandleDeltas} function in {@code 167 | * tools/cache/shared_informer.go}. The final distribution step 168 | * is left unimplemented on purpose.
169 | * 170 | * @param eventQueue the {@link EventQueue} to process; may be 171 | * {@code null} in which case no action will be taken 172 | * 173 | * @see #accept(AbstractEvent) 174 | */ 175 | @Override 176 | public final void accept(final EventQueue eventQueue) { 177 | final String cn = this.getClass().getName(); 178 | final String mn = "accept"; 179 | if (eventQueue == null) { 180 | if (this.logger.isLoggable(Level.FINER)) { 181 | this.logger.entering(cn, mn, null); 182 | } 183 | } else { 184 | synchronized (eventQueue) { 185 | if (this.logger.isLoggable(Level.FINER)) { 186 | this.logger.entering(cn, mn, eventQueue); 187 | } 188 | 189 | final Object key = eventQueue.getKey(); 190 | if (key == null) { 191 | throw new IllegalStateException("eventQueue.getKey() == null; eventQueue: " + eventQueue); 192 | } 193 | 194 | for (final AbstractEvent event : eventQueue) { 195 | if (event != null) { 196 | 197 | assert key.equals(event.getKey()); 198 | 199 | final Event.Type eventType = event.getType(); 200 | assert eventType != null; 201 | 202 | final T newResource = event.getResource(); 203 | 204 | if (event.getPriorResource() != null && this.logger.isLoggable(Level.FINE)) { 205 | this.logger.logp(Level.FINE, cn, mn, "Unexpected state; event has a priorResource: {0}", event.getPriorResource()); 206 | } 207 | 208 | final T priorResource; 209 | final AbstractEvent newEvent; 210 | 211 | if (this.knownObjects == null) { 212 | priorResource = null; 213 | newEvent = event; 214 | } else if (Event.Type.DELETION.equals(eventType)) { 215 | 216 | // "Forget" (untrack) the object in question. 217 | synchronized (this.knownObjects) { 218 | priorResource = this.knownObjects.remove(key); 219 | } 220 | 221 | newEvent = event; 222 | } else { 223 | assert eventType.equals(Event.Type.ADDITION) || eventType.equals(Event.Type.MODIFICATION); 224 | 225 | // "Learn" (track) the resource in question. 226 | synchronized (this.knownObjects) { 227 | priorResource = this.knownObjects.put(key, newResource); 228 | } 229 | 230 | if (event instanceof SynchronizationEvent) { 231 | if (priorResource == null) { 232 | assert Event.Type.ADDITION.equals(eventType) : "!Event.Type.ADDITION.equals(eventType): " + eventType; 233 | newEvent = event; 234 | } else { 235 | assert Event.Type.MODIFICATION.equals(eventType) : "!Event.Type.MODIFICATION.equals(eventType): " + eventType; 236 | newEvent = this.createSynchronizationEvent(Event.Type.MODIFICATION, priorResource, newResource); 237 | } 238 | } else if (priorResource == null) { 239 | if (Event.Type.ADDITION.equals(eventType)) { 240 | newEvent = event; 241 | } else { 242 | newEvent = this.createEvent(Event.Type.ADDITION, null, newResource); 243 | } 244 | } else { 245 | newEvent = this.createEvent(Event.Type.MODIFICATION, priorResource, newResource); 246 | } 247 | } 248 | 249 | assert newEvent != null; 250 | assert newEvent instanceof SynchronizationEvent || newEvent instanceof Event; 251 | 252 | // This is the final consumption/distribution step; it is 253 | // an abstract method in this class. 254 | this.accept(newEvent); 255 | 256 | } 257 | } 258 | 259 | } 260 | } 261 | if (this.logger.isLoggable(Level.FINER)) { 262 | this.logger.exiting(cn, mn); 263 | } 264 | } 265 | 266 | /** 267 | * Creates and returns a new {@link Event}. 268 | * 269 | *This method never returns {@code null}.
270 | * 271 | *Overrides of this method must not return {@code null}.
272 | * 273 | * @param eventType the {@link AbstractEvent.Type} for the new 274 | * {@link Event}; must not be {@code null}; when supplied by the 275 | * {@link #accept(EventQueue)} method's internals, will always be 276 | * either {@link AbstractEvent.Type#ADDITION} or {@link 277 | * AbstractEvent.Type#MODIFICATION} 278 | * 279 | * @param priorResource the prior state of the resource the new 280 | * {@link Event} will represent; may be (and often is) {@code null} 281 | * 282 | * @param resource the latest state of the resource the new {@link 283 | * Event} will represent; must not be {@code null} 284 | * 285 | * @return a new, non-{@code null} {@link Event} with each 286 | * invocation 287 | * 288 | * @exception NullPointerException if {@code eventType} or {@code 289 | * resource} is {@code null} 290 | */ 291 | protected EventThis method never returns {@code null}.
309 | * 310 | *Overrides of this method must not return {@code null}.
311 | * 312 | * @param eventType the {@link AbstractEvent.Type} for the new 313 | * {@link SynchronizationEvent}; must not be {@code null}; when 314 | * supplied by the {@link #accept(EventQueue)} method's internals, 315 | * will always be {@link AbstractEvent.Type#MODIFICATION} 316 | * 317 | * @param priorResource the prior state of the resource the new 318 | * {@link SynchronizationEvent} will represent; may be (and often 319 | * is) {@code null} 320 | * 321 | * @param resource the latest state of the resource the new {@link 322 | * SynchronizationEvent} will represent; must not be {@code null} 323 | * 324 | * @return a new, non-{@code null} {@link SynchronizationEvent} with 325 | * each invocation 326 | * 327 | * @exception NullPointerException if {@code eventType} or {@code 328 | * resource} is {@code null} 329 | */ 330 | protected SynchronizationEventImplementations of this method should be relatively fast as 350 | * this method dictates the speed of {@link EventQueue} 351 | * processing.
352 | * 353 | * @param event the {@link AbstractEvent} encountered in the {@link 354 | * EventQueue}; must not be {@code null} 355 | * 356 | * @exception NullPointerException if {@code event} is {@code null} 357 | * 358 | * @see #accept(EventQueue) 359 | */ 360 | protected abstract void accept(final AbstractEvent event); 361 | 362 | } 363 | -------------------------------------------------------------------------------- /src/main/java/org/microbean/kubernetes/controller/SynchronizationEvent.java: -------------------------------------------------------------------------------- 1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- 2 | * 3 | * Copyright © 2017-2018 microBean. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 | * implied. See the License for the specific language governing 15 | * permissions and limitations under the License. 16 | */ 17 | package org.microbean.kubernetes.controller; 18 | 19 | import java.io.Serializable; // for javadoc only 20 | 21 | import java.util.EventObject; 22 | 23 | import io.fabric8.kubernetes.api.model.HasMetadata; 24 | 25 | /** 26 | * An {@link AbstractEvent} that describes an {@link EventCache} 27 | * synchronization event. 28 | * 29 | * @paramEvent primarily concerns}; may
70 | * be—and often is—null
71 | *
72 | * @param resource a {@link HasMetadata} representing a Kubernetes
73 | * resource; must not be {@code null}
74 | *
75 | * @exception NullPointerException if {@code source}, {@code type}
76 | * or {@code resource} is {@code null}
77 | *
78 | * @exception IllegalArgumentException if {@link Type#DELETION} is
79 | * equal to {@code type}
80 | *
81 | * @see Type
82 | *
83 | * @see EventObject#getSource()
84 | */
85 | public SynchronizationEvent(final Object source, final Type type, final T priorResource, final T resource) {
86 | super(source, type, priorResource, resource);
87 | if (Type.DELETION.equals(type)) {
88 | throw new IllegalArgumentException("DELETION.equals(type): " + type);
89 | }
90 | }
91 |
92 |
93 | /*
94 | * Instance methods.
95 | */
96 |
97 |
98 | /**
99 | * Returns {@code true} if the supplied {@link Object} is also a
100 | * {@link SynchronizationEvent} and is equal in every respect to
101 | * this one.
102 | *
103 | * @param other the {@link Object} to test; may be {@code null} in
104 | * which case {@code false} will be returned
105 | *
106 | * @return {@code true} if the supplied {@link Object} is also a
107 | * {@link SynchronizationEvent} and is equal in every respect to
108 | * this one; {@code false} otherwise
109 | */
110 | @Override
111 | public boolean equals(final Object other) {
112 | if (other == this) {
113 | return true;
114 | } else if (other instanceof SynchronizationEvent) {
115 |
116 | final boolean superEquals = super.equals(other);
117 | if (!superEquals) {
118 | return false;
119 | }
120 |
121 | return true;
122 | } else {
123 | return false;
124 | }
125 | }
126 |
127 | }
128 |
--------------------------------------------------------------------------------
/src/main/java/org/microbean/kubernetes/controller/package-info.java:
--------------------------------------------------------------------------------
1 | /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
2 | *
3 | * Copyright © 2017-2018 microBean.
4 | *
5 | * Licensed under the Apache License, Version 2.0 (the "License");
6 | * you may not use this file except in compliance with the License.
7 | * You may obtain a copy of the License at
8 | *
9 | * http://www.apache.org/licenses/LICENSE-2.0
10 | *
11 | * Unless required by applicable law or agreed to in writing, software
12 | * distributed under the License is distributed on an "AS IS" BASIS,
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
14 | * implied. See the License for the specific language governing
15 | * permissions and limitations under the License.
16 | */
17 |
18 | /**
19 | * Provides classes and interfaces assisting in the writing of
20 | * Kubernetes controllers.
21 | *
22 | * @author Laird Nelson
24 | *
25 | * @see org.microbean.kubernetes.controller.Controller
26 | *
27 | * @see org.microbean.kubernetes.controller.EventCache
28 | *
29 | * @see org.microbean.kubernetes.controller.EventQueueCollection
30 | *
31 | * @see org.microbean.kubernetes.controller.EventQueue
32 | *
33 | * @see org.microbean.kubernetes.controller.Reflector
34 | */
35 | @org.microbean.development.annotation.License(
36 | name = "Apache License 2.0",
37 | uri = "https://www.apache.org/licenses/LICENSE-2.0"
38 | )
39 | package org.microbean.kubernetes.controller;
40 |
--------------------------------------------------------------------------------
/src/main/javadoc/css/stylesheet.css:
--------------------------------------------------------------------------------
1 | /* Javadoc style sheet */
2 | /*
3 | Overall document style
4 | */
5 |
6 | @import url('https://fonts.googleapis.com/css?family=Lobster|Roboto');
7 |
8 | body {
9 | background-color:#ffffff;
10 | color:#353833;
11 | font-family: Arial, Helvetica, sans-serif;
12 | font-size:14px;
13 | margin:0;
14 | }
15 | a:link, a:visited {
16 | text-decoration:none;
17 | color:#4A6782;
18 | }
19 | a:hover, a:focus {
20 | text-decoration:none;
21 | color:#bb7a2a;
22 | }
23 | a:active {
24 | text-decoration:none;
25 | color:#4A6782;
26 | }
27 | a[name] {
28 | color:#353833;
29 | }
30 | a[name]:hover {
31 | text-decoration:none;
32 | color:#353833;
33 | }
34 | pre {
35 | font-family: monospace;
36 | font-size:14px;
37 | }
38 | h1 {
39 | font-size:20px;
40 | }
41 | h2 {
42 | font-size:18px;
43 | }
44 | h3 {
45 | font-size:16px;
46 | font-style:italic;
47 | }
48 | h4 {
49 | font-size:13px;
50 | }
51 | h5 {
52 | font-size:12px;
53 | }
54 | h6 {
55 | font-size:11px;
56 | }
57 | ul {
58 | list-style-type:disc;
59 | }
60 | code, tt {
61 | font-family:monospace;
62 | font-size:14px;
63 | padding-top:4px;
64 | margin-top:8px;
65 | line-height:1.4em;
66 | }
67 | dt code {
68 | font-family:monospace;
69 | font-size:14px;
70 | padding-top:4px;
71 | }
72 | table tr td dt code {
73 | font-family:monospace;
74 | font-size:14px;
75 | vertical-align:top;
76 | padding-top:4px;
77 | }
78 | sup {
79 | font-size:8px;
80 | }
81 | /*
82 | Document title and Copyright styles
83 | */
84 | .clear {
85 | clear:both;
86 | height:0px;
87 | overflow:hidden;
88 | }
89 | .aboutLanguage {
90 | float:right;
91 | padding:0px 21px;
92 | font-size:11px;
93 | z-index:200;
94 | margin-top:-9px;
95 | }
96 | .legalCopy {
97 | margin-left:.5em;
98 | }
99 | .bar a, .bar a:link, .bar a:visited, .bar a:active {
100 | color:#FFFFFF;
101 | text-decoration:none;
102 | }
103 | .bar a:hover, .bar a:focus {
104 | color:#bb7a2a;
105 | }
106 | .tab {
107 | background-color:#0066FF;
108 | color:#ffffff;
109 | padding:8px;
110 | width:5em;
111 | font-weight:bold;
112 | }
113 | /*
114 | Navigation bar styles
115 | */
116 | .bar {
117 | background-color:#4D7A97;
118 | color:#FFFFFF;
119 | padding:.8em .5em .4em .8em;
120 | height:auto;/*height:1.8em;*/
121 | font-size:11px;
122 | margin:0;
123 | }
124 | .topNav {
125 | background-color:#4D7A97;
126 | color:#FFFFFF;
127 | float:left;
128 | padding:0;
129 | width:100%;
130 | clear:right;
131 | height:2.8em;
132 | padding-top:10px;
133 | overflow:hidden;
134 | font-size:12px;
135 | }
136 | .bottomNav {
137 | margin-top:10px;
138 | background-color:#4D7A97;
139 | color:#FFFFFF;
140 | float:left;
141 | padding:0;
142 | width:100%;
143 | clear:right;
144 | height:2.8em;
145 | padding-top:10px;
146 | overflow:hidden;
147 | font-size:12px;
148 | }
149 | .subNav {
150 | background-color:#dee3e9;
151 | float:left;
152 | width:100%;
153 | overflow:hidden;
154 | font-size:12px;
155 | }
156 | .subNav div {
157 | clear:left;
158 | float:left;
159 | padding:0 0 5px 6px;
160 | text-transform:uppercase;
161 | }
162 | ul.navList, ul.subNavList {
163 | float:left;
164 | margin:0 25px 0 0;
165 | padding:0;
166 | }
167 | ul.navList li{
168 | list-style:none;
169 | float:left;
170 | padding: 5px 6px;
171 | text-transform:uppercase;
172 | }
173 | ul.subNavList li{
174 | list-style:none;
175 | float:left;
176 | }
177 | .topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {
178 | color:#FFFFFF;
179 | text-decoration:none;
180 | text-transform:uppercase;
181 | }
182 | .topNav a:hover, .bottomNav a:hover {
183 | text-decoration:none;
184 | color:#bb7a2a;
185 | text-transform:uppercase;
186 | }
187 | .navBarCell1Rev {
188 | background-color:#F8981D;
189 | color:#253441;
190 | margin: auto 5px;
191 | }
192 | .skipNav {
193 | position:absolute;
194 | top:auto;
195 | left:-9999px;
196 | overflow:hidden;
197 | }
198 | /*
199 | Page header and footer styles
200 | */
201 | .header, .footer {
202 | clear:both;
203 | margin:0 20px;
204 | padding:5px 0 0 0;
205 | }
206 | .indexHeader {
207 | margin:10px;
208 | position:relative;
209 | }
210 | .indexHeader span{
211 | margin-right:15px;
212 | }
213 | .indexHeader h1 {
214 | font-size:13px;
215 | }
216 | .title {
217 | color:#2c4557;
218 | margin:10px 0;
219 | }
220 | .subTitle {
221 | margin:5px 0 0 0;
222 | }
223 | .header ul {
224 | margin:0 0 15px 0;
225 | padding:0;
226 | }
227 | .footer ul {
228 | margin:20px 0 5px 0;
229 | }
230 | .header ul li, .footer ul li {
231 | list-style:none;
232 | font-size:13px;
233 | }
234 | /*
235 | Heading styles
236 | */
237 | div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {
238 | background-color:#dee3e9;
239 | border:1px solid #d0d9e0;
240 | margin:0 0 6px -8px;
241 | padding:7px 5px;
242 | }
243 | ul.blockList ul.blockList ul.blockList li.blockList h3 {
244 | background-color:#dee3e9;
245 | border:1px solid #d0d9e0;
246 | margin:0 0 6px -8px;
247 | padding:7px 5px;
248 | }
249 | ul.blockList ul.blockList li.blockList h3 {
250 | padding:0;
251 | margin:15px 0;
252 | }
253 | ul.blockList li.blockList h2 {
254 | padding:0px 0 20px 0;
255 | }
256 | /*
257 | Page layout container styles
258 | */
259 | .contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {
260 | clear:both;
261 | padding:10px 20px;
262 | position:relative;
263 | }
264 | .indexContainer {
265 | margin:10px;
266 | position:relative;
267 | font-size:12px;
268 | }
269 | .indexContainer h2 {
270 | font-size:13px;
271 | padding:0 0 3px 0;
272 | }
273 | .indexContainer ul {
274 | margin:0;
275 | padding:0;
276 | }
277 | .indexContainer ul li {
278 | list-style:none;
279 | padding-top:2px;
280 | }
281 | .contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {
282 | font-size:12px;
283 | font-weight:bold;
284 | margin:10px 0 0 0;
285 | color:#4E4E4E;
286 | }
287 | .contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {
288 | margin:5px 0 10px 0px;
289 | font-size:14px;
290 | font-family:monospace;
291 | }
292 | .serializedFormContainer dl.nameValue dt {
293 | margin-left:1px;
294 | font-size:1.1em;
295 | display:inline;
296 | font-weight:bold;
297 | }
298 | .serializedFormContainer dl.nameValue dd {
299 | margin:0 0 0 1px;
300 | font-size:1.1em;
301 | display:inline;
302 | }
303 | /*
304 | List styles
305 | */
306 | ul.horizontal li {
307 | display:inline;
308 | font-size:0.9em;
309 | }
310 | ul.inheritance {
311 | margin:0;
312 | padding:0;
313 | }
314 | ul.inheritance li {
315 | display:inline;
316 | list-style:none;
317 | }
318 | ul.inheritance li ul.inheritance {
319 | margin-left:15px;
320 | padding-left:15px;
321 | padding-top:1px;
322 | }
323 | ul.blockList, ul.blockListLast {
324 | margin:10px 0 10px 0;
325 | padding:0;
326 | }
327 | ul.blockList li.blockList, ul.blockListLast li.blockList {
328 | list-style:none;
329 | margin-bottom:15px;
330 | line-height:1.4;
331 | }
332 | ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {
333 | padding:0px 20px 5px 10px;
334 | border:1px solid #ededed;
335 | background-color:#f8f8f8;
336 | }
337 | ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {
338 | padding:0 0 5px 8px;
339 | background-color:#ffffff;
340 | border:none;
341 | }
342 | ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {
343 | margin-left:0;
344 | padding-left:0;
345 | padding-bottom:15px;
346 | border:none;
347 | }
348 | ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {
349 | list-style:none;
350 | border-bottom:none;
351 | padding-bottom:0;
352 | }
353 | table tr td dl, table tr td dl dt, table tr td dl dd {
354 | margin-top:0;
355 | margin-bottom:1px;
356 | }
357 | /*
358 | Table styles
359 | */
360 | .overviewSummary, .memberSummary, .typeSummary, .useSummary, .constantsSummary, .deprecatedSummary {
361 | width:100%;
362 | border-left:1px solid #EEE;
363 | border-right:1px solid #EEE;
364 | border-bottom:1px solid #EEE;
365 | }
366 | .overviewSummary, .memberSummary {
367 | padding:0px;
368 | }
369 | .overviewSummary caption, .memberSummary caption, .typeSummary caption,
370 | .useSummary caption, .constantsSummary caption, .deprecatedSummary caption {
371 | position:relative;
372 | text-align:left;
373 | background-repeat:no-repeat;
374 | color:#253441;
375 | font-weight:bold;
376 | clear:none;
377 | overflow:hidden;
378 | padding:0px;
379 | padding-top:10px;
380 | padding-left:1px;
381 | margin:0px;
382 | white-space:pre;
383 | }
384 | .overviewSummary caption a:link, .memberSummary caption a:link, .typeSummary caption a:link,
385 | .useSummary caption a:link, .constantsSummary caption a:link, .deprecatedSummary caption a:link,
386 | .overviewSummary caption a:hover, .memberSummary caption a:hover, .typeSummary caption a:hover,
387 | .useSummary caption a:hover, .constantsSummary caption a:hover, .deprecatedSummary caption a:hover,
388 | .overviewSummary caption a:active, .memberSummary caption a:active, .typeSummary caption a:active,
389 | .useSummary caption a:active, .constantsSummary caption a:active, .deprecatedSummary caption a:active,
390 | .overviewSummary caption a:visited, .memberSummary caption a:visited, .typeSummary caption a:visited,
391 | .useSummary caption a:visited, .constantsSummary caption a:visited, .deprecatedSummary caption a:visited {
392 | color:#FFFFFF;
393 | }
394 | .overviewSummary caption span, .memberSummary caption span, .typeSummary caption span,
395 | .useSummary caption span, .constantsSummary caption span, .deprecatedSummary caption span {
396 | white-space:nowrap;
397 | padding-top:5px;
398 | padding-left:12px;
399 | padding-right:12px;
400 | padding-bottom:7px;
401 | display:inline-block;
402 | float:left;
403 | background-color:#F8981D;
404 | border: none;
405 | height:16px;
406 | }
407 | .memberSummary caption span.activeTableTab span {
408 | white-space:nowrap;
409 | padding-top:5px;
410 | padding-left:12px;
411 | padding-right:12px;
412 | margin-right:3px;
413 | display:inline-block;
414 | float:left;
415 | background-color:#F8981D;
416 | height:16px;
417 | }
418 | .memberSummary caption span.tableTab span {
419 | white-space:nowrap;
420 | padding-top:5px;
421 | padding-left:12px;
422 | padding-right:12px;
423 | margin-right:3px;
424 | display:inline-block;
425 | float:left;
426 | background-color:#4D7A97;
427 | height:16px;
428 | }
429 | .memberSummary caption span.tableTab, .memberSummary caption span.activeTableTab {
430 | padding-top:0px;
431 | padding-left:0px;
432 | padding-right:0px;
433 | background-image:none;
434 | float:none;
435 | display:inline;
436 | }
437 | .overviewSummary .tabEnd, .memberSummary .tabEnd, .typeSummary .tabEnd,
438 | .useSummary .tabEnd, .constantsSummary .tabEnd, .deprecatedSummary .tabEnd {
439 | display:none;
440 | width:5px;
441 | position:relative;
442 | float:left;
443 | background-color:#F8981D;
444 | }
445 | .memberSummary .activeTableTab .tabEnd {
446 | display:none;
447 | width:5px;
448 | margin-right:3px;
449 | position:relative;
450 | float:left;
451 | background-color:#F8981D;
452 | }
453 | .memberSummary .tableTab .tabEnd {
454 | display:none;
455 | width:5px;
456 | margin-right:3px;
457 | position:relative;
458 | background-color:#4D7A97;
459 | float:left;
460 |
461 | }
462 | .overviewSummary td, .memberSummary td, .typeSummary td,
463 | .useSummary td, .constantsSummary td, .deprecatedSummary td {
464 | text-align:left;
465 | padding:0px 0px 12px 10px;
466 | }
467 | th.colOne, th.colFirst, th.colLast, .useSummary th, .constantsSummary th,
468 | td.colOne, td.colFirst, td.colLast, .useSummary td, .constantsSummary td{
469 | vertical-align:top;
470 | padding-right:0px;
471 | padding-top:8px;
472 | padding-bottom:3px;
473 | }
474 | th.colFirst, th.colLast, th.colOne, .constantsSummary th {
475 | background:#dee3e9;
476 | text-align:left;
477 | padding:8px 3px 3px 7px;
478 | }
479 | td.colFirst, th.colFirst {
480 | white-space:nowrap;
481 | font-size:13px;
482 | }
483 | td.colLast, th.colLast {
484 | font-size:13px;
485 | }
486 | td.colOne, th.colOne {
487 | font-size:13px;
488 | }
489 | .overviewSummary td.colFirst, .overviewSummary th.colFirst,
490 | .useSummary td.colFirst, .useSummary th.colFirst,
491 | .overviewSummary td.colOne, .overviewSummary th.colOne,
492 | .memberSummary td.colFirst, .memberSummary th.colFirst,
493 | .memberSummary td.colOne, .memberSummary th.colOne,
494 | .typeSummary td.colFirst{
495 | width:25%;
496 | vertical-align:top;
497 | }
498 | td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {
499 | font-weight:bold;
500 | }
501 | .tableSubHeadingColor {
502 | background-color:#EEEEFF;
503 | }
504 | .altColor {
505 | background-color:#FFFFFF;
506 | }
507 | .rowColor {
508 | background-color:#EEEEEF;
509 | }
510 | /*
511 | Content styles
512 | */
513 | .description pre {
514 | margin-top:0;
515 | }
516 | .deprecatedContent {
517 | margin:0;
518 | padding:10px 0;
519 | }
520 | .docSummary {
521 | padding:0;
522 | }
523 |
524 | ul.blockList ul.blockList ul.blockList li.blockList h3 {
525 | font-style:normal;
526 | }
527 |
528 | div.block {
529 | font-size:14px;
530 | font-family:Georgia, "Times New Roman", Times, serif;
531 | }
532 |
533 | td.colLast div {
534 | padding-top:0px;
535 | }
536 |
537 |
538 | td.colLast a {
539 | padding-bottom:3px;
540 | }
541 | /*
542 | Formatting effect styles
543 | */
544 | .sourceLineNo {
545 | color:green;
546 | padding:0 30px 0 0;
547 | }
548 | h1.hidden {
549 | visibility:hidden;
550 | overflow:hidden;
551 | font-size:10px;
552 | }
553 | .block {
554 | display:block;
555 | margin:3px 10px 2px 0px;
556 | color:#474747;
557 | }
558 | .deprecatedLabel, .descfrmTypeLabel, .memberNameLabel, .memberNameLink,
559 | .overrideSpecifyLabel, .packageHierarchyLabel, .paramLabel, .returnLabel,
560 | .seeLabel, .simpleTagLabel, .throwsLabel, .typeNameLabel, .typeNameLink {
561 | font-weight:bold;
562 | }
563 | .deprecationComment, .emphasizedPhrase, .interfaceName {
564 | font-style:italic;
565 | }
566 |
567 | div.block div.block span.deprecationComment, div.block div.block span.emphasizedPhrase,
568 | div.block div.block span.interfaceName {
569 | font-style:normal;
570 | }
571 |
572 | div.contentContainer ul.blockList li.blockList h2{
573 | padding-bottom:0px;
574 | }
575 |
--------------------------------------------------------------------------------
/src/main/javadoc/overview.html:
--------------------------------------------------------------------------------
1 |
2 |
3 | Provides classes and interfaces for assisting in the writing of 4 | Kubernetes controllers.
5 | 6 | @author Laird Nelson 8 | 9 | @see org.microbean.kubernetes.controller.EventCache 10 | 11 | @see org.microbean.kubernetes.controller.EventQueueCollection 12 | 13 | @see org.microbean.kubernetes.controller.EventQueue 14 | 15 | @see org.microbean.kubernetes.controller.Reflector 16 | 17 | 18 | -------------------------------------------------------------------------------- /src/site/markdown/index.md.vm: -------------------------------------------------------------------------------- 1 | #include("../../../README.md") 2 | -------------------------------------------------------------------------------- /src/site/resources/css/site.css: -------------------------------------------------------------------------------- 1 | @import url('https://fonts.googleapis.com/css?family=Lobster|Roboto'); 2 | -------------------------------------------------------------------------------- /src/site/site.xml: -------------------------------------------------------------------------------- 1 | 2 |