binding2/mdsal-binding2-api/src/main/java/org/opendaylight/mdsal/binding/javav2/api/NotificationPublishService.java

   1 /*
   2  * Copyright (c) 2017 Pantheon Technologies 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
   9 package org.opendaylight.mdsal.binding.javav2.api;
  10
  11 import com.google.common.annotations.Beta;
  12 import com.google.common.util.concurrent.Futures;
  13 import com.google.common.util.concurrent.ListenableFuture;
  14 import java.util.concurrent.TimeUnit;
  15 import org.opendaylight.mdsal.binding.javav2.spec.base.InstanceIdentifier;
  16 import org.opendaylight.mdsal.binding.javav2.spec.base.KeyedInstanceIdentifier;
  17 import org.opendaylight.mdsal.binding.javav2.spec.base.Notification;
  18 import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
  19
  20 /**
  21  * A {@link NotificationService} which also allows its users to submit YANG-modeled notifications for delivery.
  22  *
  23  * <p>
  24  * There are three methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
  25  *
  26  * <p>
  27  * - {@link #putNotification(org.opendaylight.mdsal.binding.javav2.spec.base.Notification)}, which may block
  28  * indefinitely if the implementation cannot allocate resources to accept the notification,
  29  * - {@link #offerNotification(org.opendaylight.mdsal.binding.javav2.spec.base.Notification)}, which does not block if
  30  * face of resource starvation,
  31  * - {@link #offerNotification(org.opendaylight.mdsal.binding.javav2.spec.base.Notification, int, TimeUnit)}, which may
  32  * block for specified time if resources are thin.
  33  *
  34  * <p>
  35  * Every method has two alternatives for YANG 1.1 notifications tied to container or list node.
  36  *
  37  *<p>
  38  * The actual delivery to listeners is asynchronous and implementation-specific.
  39  * Users of this interface should not make any assumptions as to whether the
  40  * notification has or has not been seen.
  41  */
  42
  43 @Beta
  44 public interface NotificationPublishService {
  45
  46     ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(
  47         new NotificationRejectedException("Rejected due to resource constraints."));
  48
  49     void putNotification(Notification notification) throws InterruptedException;
  50
  51     ListenableFuture<?> offerNotification(Notification notification);
  52
  53     ListenableFuture<?> offerNotification(Notification notification, int timeout, TimeUnit unit)
  54         throws InterruptedException;
  55
  56
  57     <T extends TreeNode> void putContainerNotification(Notification notification, InstanceIdentifier<T> ii)
  58         throws InterruptedException;
  59
  60     <T extends TreeNode> ListenableFuture<?> offerContainerNotification(Notification notification,
  61         InstanceIdentifier<T> ii);
  62
  63     <T extends TreeNode> ListenableFuture<?> offerContainerNotification(Notification notification, int timeout,
  64         TimeUnit unit, InstanceIdentifier<T> ii) throws InterruptedException;
  65
  66
  67     <T extends TreeNode, K> void putListNotification(Notification notification, KeyedInstanceIdentifier<T, K> kii)
  68         throws InterruptedException;
  69
  70     <T extends TreeNode, K> ListenableFuture<?> offerListNotification(Notification notification,
  71         KeyedInstanceIdentifier<T, K> kii);
  72
  73     <T extends TreeNode, K> ListenableFuture<?> offerListNotification(Notification notification, int timeout,
  74         TimeUnit unit, KeyedInstanceIdentifier<T, K> kii) throws InterruptedException;
  75 }