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.InstanceNotification;
  17
  18 /**
  19  * A {@link BindingService} which allows its users to submit YANG-modeled top-level (YANG 1.1)
  20  * {@link InstanceNotification}s for delivery. There are three methods of submission, following the patters from
  21  * {@link java.util.concurrent.BlockingQueue}:
  22  * <ul>
  23  *   <li>{@link #putNotification(InstanceNotification)}, which may block indefinitely if the implementation cannot
  24  *       allocate resources to accept the notification,</li>
  25  *   <li>{@link #offerNotification(InstanceNotification)}, which does not block if face of resource starvation,</li>
  26  *   <li>{@link #offerNotification(InstanceNotification, int, TimeUnit)}, which may block for specified time if
  27  *       resources are thin.</li>
  28  * </ul>
  29  *
  30  * <p>
  31  * The actual delivery to listeners is asynchronous and implementation-specific. Users of this interface should not make
  32  * any assumptions as to whether the notification has or has not been seen.
  33  */
  34 @Beta
  35 public interface InstanceNotificationPublishService extends BindingService {
  36     /**
  37      * Well-known value indicating that the binding-aware implementation is currently not able to accept a notification.
  38      */
  39     @NonNull ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
  40             new NotificationRejectedException("Rejected due to resource constraints."));
  41
  42     /**
  43      * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  44      * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
  45      *
  46      * <b>Note:</b> This call will block when the notification queue is full.
  47      *
  48      * @param notification the notification to publish.
  49      * @throws InterruptedException if interrupted while waiting
  50      * @throws NullPointerException if any argument is null
  51      */
  52     <N extends InstanceNotification<N, P>, P extends DataObject> void putNotification(
  53         @NonNull DataTreeIdentifier<P> path, @NonNull N notification) throws InterruptedException;
  54
  55     /**
  56      * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  57      * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
  58      *
  59      * <p>
  60      * Still guaranteed not to block. Returns Listenable Future which will complete once the delivery is completed.
  61      *
  62      * @param notification the notification to publish.
  63      * @return A listenable future which will report completion when the service has finished propagating the
  64      *         notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
  65      * @throws NullPointerException if any argument is null
  66      */
  67     <N extends InstanceNotification<N, P>, P extends DataObject>
  68         @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull DataTreeIdentifier<P> path,
  69             @NonNull N notification);
  70
  71     /**
  72      * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
  73      * delivery to the listeners can happen asynchronously, potentially after a call to this method returns. This method
  74      * is guaranteed not to block more than the specified timeout.
  75      *
  76      * @param notification the notification to publish.
  77      * @param timeout how long to wait before giving up, in units of unit
  78      * @param unit a TimeUnit determining how to interpret the timeout parameter
  79      * @return A listenable future which will report completion when the service has finished propagating the
  80      *         notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
  81      * @throws InterruptedException if interrupted while waiting
  82      * @throws NullPointerException if any argument is null
  83      * @throws IllegalArgumentException if timeout is negative.
  84      */
  85     <N extends InstanceNotification<N, P>, P extends DataObject>
  86         @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull DataTreeIdentifier<P> path,
  87             @NonNull N notification, long timeout, @NonNull TimeUnit unit) throws InterruptedException;
  88 }