binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/InstanceNotificationPublishService.java

   1 /*
   2  * Copyright (c) 2022 PANTHEON.tech, s.r.o. 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.mdsal.binding.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.util.concurrent.ListenableFuture;
  12 import java.util.concurrent.TimeUnit;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.opendaylight.yangtools.util.concurrent.FluentFutures;
  15 import org.opendaylight.yangtools.yang.binding.DataObject;
  16 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  17 import org.opendaylight.yangtools.yang.binding.InstanceNotification;
  18
  19 /**
  20  * A {@link BindingService} which allows its users to submit YANG-modeled top-level (YANG 1.1)
  21  * {@link InstanceNotification}s for delivery.
  22  */
  23 @Beta
  24 public interface InstanceNotificationPublishService extends BindingService {
  25     /**
  26      * Create a new {@link Publisher} for a {@link InstanceNotificationSpec}. Returned interface may be freely reused
  27      * and accessed concurrently from multiple threads.
  28      *
  29      * @param <N> Generated InstanceNotification interface type
  30      * @param <P> Notification parent type
  31      * @param notificationSpec Specification of an {@link InstanceNotification}
  32      * @return A {@link Publisher} handle
  33      * @throws NullPointerException if {@code notificationSpec} is {@code null}
  34      * @throws IllegalArgumentException when {@code notificationSpec} cannot be resolved
  35      */
  36     <N extends InstanceNotification<N, P>, P extends DataObject> @NonNull Publisher<N, P> newPublisher(
  37         InstanceNotificationSpec<N, P> notificationSpec);
  38
  39     /**
  40      * Interface for publishing {@link InstanceNotification} of a particular type bound to an instantiation. There are
  41      * three methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
  42      * <ul>
  43      *   <li>{@link #putNotification(InstanceIdentifier, InstanceNotification)}, which may block indefinitely if the
  44      *       implementation cannot allocate resources to accept the notification,</li>
  45      *   <li>{@link #offerNotification(InstanceIdentifier, InstanceNotification)}, which does not block if face of
  46      *       resource starvation,</li>
  47      *   <li>{@link #offerNotification(InstanceIdentifier, InstanceNotification, int, TimeUnit)}, which may block for
  48      *       specified time if resources are thin.</li>
  49      * </ul>
  50      *
  51      * <p>
  52      * The actual delivery to listeners is asynchronous and implementation-specific. Users of this interface should not
  53      * make any assumptions as to whether the notification has or has not been seen.
  54      *
  55      * @param <N> Generated InstanceNotification interface type
  56      * @param <P> Notification parent type
  57      */
  58     @Beta
  59     interface Publisher<N extends InstanceNotification<N, P>, P extends DataObject> {
  60         /**
  61          * Well-known value indicating that the binding-aware implementation is currently not able to accept a
  62          * notification.
  63          */
  64         @NonNull ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
  65                 new NotificationRejectedException("Rejected due to resource constraints."));
  66
  67         /**
  68          * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  69          * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
  70          *
  71          * <b>Note:</b> This call will block when the notification queue is full.
  72          *
  73          * @param path parent path
  74          * @param notification the notification to publish.
  75          * @throws InterruptedException if interrupted while waiting
  76          * @throws NullPointerException if any argument is null
  77          */
  78         void putNotification(@NonNull InstanceIdentifier<P> path, @NonNull N notification) throws InterruptedException;
  79
  80         /**
  81          * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  82          * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
  83          *
  84          * <p>
  85          * Still guaranteed not to block. Returns Listenable Future which will complete once the delivery is completed.
  86          *
  87          * @param path parent path
  88          * @param notification the notification to publish.
  89          * @return A listenable future which will report completion when the service has finished propagating the
  90          *         notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
  91          * @throws NullPointerException if any argument is null
  92          */
  93         @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull InstanceIdentifier<P> path,
  94             @NonNull N notification);
  95
  96         /**
  97          * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  98          * delivery to the listeners can happen asynchronously, potentially after a call to this method returns. This
  99          * method is guaranteed not to block more than the specified timeout.
 100          *
 101          * @param path parent path
 102          * @param notification the notification to publish.
 103          * @param timeout how long to wait before giving up, in units of unit
 104          * @param unit a TimeUnit determining how to interpret the timeout parameter
 105          * @return A listenable future which will report completion when the service has finished propagating the
 106          *         notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
 107          * @throws InterruptedException if interrupted while waiting
 108          * @throws NullPointerException if any argument is null
 109          * @throws IllegalArgumentException if timeout is negative.
 110          */
 111         @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull InstanceIdentifier<P> path,
 112             @NonNull N notification, long timeout, @NonNull TimeUnit unit) throws InterruptedException;
 113     }
 114 }