mdsalutil/mdsalutil-api/src/main/java/org/opendaylight/genius/datastoreutils/listeners/DataTreeEventCallbackRegistrar.java

   1 /*
   2  * Copyright (c) 2017 Red Hat, Inc. and others. All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.genius.datastoreutils.listeners;
   9
  10 import static org.opendaylight.genius.datastoreutils.listeners.DataTreeEventCallbackRegistrar.NextAction.UNREGISTER;
  11
  12 import com.google.common.annotations.Beta;
  13 import java.time.Duration;
  14 import java.util.function.BiConsumer;
  15 import java.util.function.BiFunction;
  16 import java.util.function.Consumer;
  17 import java.util.function.Function;
  18 import org.eclipse.jdt.annotation.NonNullByDefault;
  19 import org.eclipse.jdt.annotation.Nullable;
  20 import org.opendaylight.mdsal.binding.api.DataTreeIdentifier;
  21 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
  22 import org.opendaylight.yangtools.yang.binding.DataObject;
  23 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  24
  25 /**
  26  * Service to register callbacks for data tree changes for a fixed instance.
  27  *
  28  * <p>The current implementation assumes that the expected instance will eventually be added, updated or deleted; if
  29  * that never happens in the first place, then an internal data structure could fill up and theoretically lead to OOM
  30  * problems if you do not specify a timeout.  Likewise, if {@link NextAction#CALL_AGAIN} is used but no next event
  31  * matching path ever occurs.  In the "Full Sync Upgrade" scenario, for which this utility was originally created, this
  32  * is not a problem, as we are sure the subsequent changes are about to happen (just out of originally expected order).
  33  *
  34  * @author Josh original idea and design feedback
  35  * @author Michael Vorburger.ch API design and first implementation
  36  * @author Tom Pantelis review and feedback on concurrency issue in implementation
  37  */
  38 @Beta // we may still change this API
  39 @NonNullByDefault
  40 public interface DataTreeEventCallbackRegistrar {
  41
  42     enum NextAction {
  43         /**
  44          * When the callback function returns this, then it is unregistered and will
  45          * never be invoked anymore.
  46          */
  47         UNREGISTER,
  48
  49         /**
  50          * When the callback function returns this, then it will be called again for
  51          * add, update OR remove on the given store &amp; path.
  52          */
  53         CALL_AGAIN
  54     }
  55
  56     <T extends DataObject> void onAdd(LogicalDatastoreType store, InstanceIdentifier<T> path,
  57             Function<T, NextAction> callback,
  58             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback);
  59
  60     <T extends DataObject> void onAdd(LogicalDatastoreType store, InstanceIdentifier<T> path,
  61             Function<T, NextAction> callback);
  62
  63     default <T extends DataObject> void onAdd(LogicalDatastoreType store, InstanceIdentifier<T> path,
  64             Consumer<T> callback) {
  65         onAdd(store, path, t -> {
  66             callback.accept(t);
  67             return UNREGISTER;
  68         });
  69     }
  70
  71     default <T extends DataObject> void onAdd(LogicalDatastoreType store, InstanceIdentifier<T> path,
  72             Consumer<T> callback, Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback) {
  73         onAdd(store, path, t -> {
  74             callback.accept(t);
  75             return UNREGISTER;
  76         }, timeoutDuration, timedOutCallback);
  77     }
  78
  79
  80     <T extends DataObject> void onUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
  81             BiFunction<T, T, NextAction> callback,
  82             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback);
  83
  84     <T extends DataObject> void onUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
  85             BiFunction<T, T, NextAction> callback);
  86
  87     default <T extends DataObject> void onUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
  88             BiConsumer<T, T> callback) {
  89         onUpdate(store, path, (t1, t2) -> {
  90             callback.accept(t1, t2);
  91             return UNREGISTER;
  92         });
  93     }
  94
  95     default <T extends DataObject> void onUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
  96             BiConsumer<T, T> callback,
  97             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback) {
  98         onUpdate(store, path, (t1, t2) -> {
  99             callback.accept(t1, t2);
 100             return UNREGISTER;
 101         }, timeoutDuration, timedOutCallback);
 102     }
 103
 104
 105     <T extends DataObject> void onAddOrUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
 106             BiFunction<@Nullable T, T, NextAction> callback,
 107             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback);
 108
 109
 110     /**
 111      * Call back when expected instance was added or updated, with NextAction support.
 112      * @param store the expected data store
 113      * @param path the path to watch for changes on
 114      * @param callback the callback as {@link BiFunction}, where the first argument is the data before the update
 115      *             or null in case of an add, the second argument is the data after the update (or add; never null),
 116      *             and the returned value determines whether to keep listening for changes or not anymore.
 117      * @param <T> DataObject subclass
 118      */
 119     <T extends DataObject> void onAddOrUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
 120                                               BiFunction<@Nullable T, T, NextAction> callback);
 121
 122     /**
 123      * Call back when expected instance was added or updated, with NextAction support.
 124      * @param store the expected data store
 125      * @param path the path to watch for changes on
 126      * @param callback the callback as {@link BiFunction}, where the first argument is the data before the update
 127      *             or null in case of an add, the second argument is the data after the update (or add; never null),
 128      *             and the returned value determines whether to keep listening for changes or not anymore.
 129      * @param <T> DataObject subclass
 130      */
 131     default <T extends DataObject> void onAddOrUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
 132                                                  BiConsumer<@Nullable T, T> callback) {
 133         onAddOrUpdate(store, path, (t1, t2) -> {
 134             callback.accept(t1, t2);
 135             return UNREGISTER;
 136         });
 137     }
 138
 139     default <T extends DataObject> void onAddOrUpdate(LogicalDatastoreType store, InstanceIdentifier<T> path,
 140             BiConsumer<@Nullable T, T> callback,
 141             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback) {
 142         onAddOrUpdate(store, path, (t1, t2) -> {
 143             callback.accept(t1, t2);
 144             return UNREGISTER;
 145         }, timeoutDuration, timedOutCallback);
 146     }
 147
 148
 149     <T extends DataObject> void onRemove(LogicalDatastoreType store, InstanceIdentifier<T> path,
 150             Function<T, NextAction> callback,
 151             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback);
 152
 153     <T extends DataObject> void onRemove(LogicalDatastoreType store, InstanceIdentifier<T> path,
 154             Function<T, NextAction> callback);
 155
 156     default <T extends DataObject> void onRemove(LogicalDatastoreType store, InstanceIdentifier<T> path,
 157             Consumer<T> callback) {
 158         onRemove(store, path, t -> {
 159             callback.accept(t);
 160             return UNREGISTER;
 161         });
 162     }
 163
 164     default <T extends DataObject> void onRemove(LogicalDatastoreType store, InstanceIdentifier<T> path,
 165             Consumer<T> callback,
 166             Duration timeoutDuration, Consumer<DataTreeIdentifier<T>> timedOutCallback) {
 167         onRemove(store, path, t -> {
 168             callback.accept(t);
 169             return UNREGISTER;
 170         }, timeoutDuration, timedOutCallback);
 171     }
 172
 173 }