Deprecate old MD-SAL APIs for removal

[controller.git] / opendaylight / md-sal / sal-dom-api / src / main / java / org / opendaylight / controller / md / sal / dom / api / DOMNotificationPublishService.java

diff --git a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMNotificationPublishService.java b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMNotificationPublishService.java
index 8a845e87299fd87c89c553243fa31974b9382454..90aa87849e606013cdfe8660421e7c9efca77487 100644 (file)
--- a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMNotificationPublishService.java
+++ b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMNotificationPublishService.java
@@ -10,8 +10,7 @@ package org.opendaylight.controller.md.sal.dom.api;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.ListenableFuture;
 import java.util.concurrent.TimeUnit;
-import javax.annotation.Nonnegative;
-import javax.annotation.Nonnull;
+import org.eclipse.jdt.annotation.NonNull;
 
 /**
  * A {@link DOMService} which allows its user to send {@link DOMNotification}s. It
@@ -22,13 +21,17 @@ import javax.annotation.Nonnull;
  * - an offer-style method, which attempts to enqueue the notification, but allows
  *   the caller to specify that it should never wait, or put an upper bound on how
  *   long it is going to wait.
+ *
+ * @deprecated Use {@link org.opendaylight.mdsal.dom.api.DOMNotificationPublishService} instead
  */
+@Deprecated(forRemoval = true)
 public interface DOMNotificationPublishService extends DOMService {
     /**
      * Well-known value indicating that the implementation is currently not
      * able to accept a notification.
      */
-    ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(new Throwable("Unacceptable blocking conditions encountered"));
+    ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(
+            new DOMNotificationRejectedException("Unacceptable blocking conditions encountered"));
 
     /**
      * Publish a notification. The result of this method is a {@link ListenableFuture}
@@ -37,15 +40,20 @@ public interface DOMNotificationPublishService extends DOMService {
      * and implementations may use it to convey additional information related to the
      * publishing process.
      *
+     * <p>
      * Abstract subclasses can refine the return type as returning a promise of a
      * more specific type, e.g.:
      *
+     * {@code
      *     public interface DeliveryStatus { int getListenerCount(); }
      *     ListenableFuture<? extends DeliveryStatus> putNotification(DOMNotification notification);
+     * }
      *
+     * <p>
      * Once the Future succeeds, the resulting object can be queried for traits using
      * instanceof, e.g:
      *
+     * {@code
      *     // Can block when (for example) the implemention's ThreadPool queue is full
      *     Object o = service.putNotification(notif).get();
      *     if (o instanceof DeliveryStatus) {
@@ -54,10 +62,12 @@ public interface DOMNotificationPublishService extends DOMService {
      *     }
      * }
      *
+     * <p>
      * In case an implementation is running out of resources, it can block the calling
      * thread until enough resources become available to accept the notification for
      * processing, or it is interrupted.
      *
+     * <p>
      * Caution: completion here means that the implementation has completed processing
      *          of the notification. This does not mean that all existing registrants
      *          have seen the notification. Most importantly, the delivery process at
@@ -69,7 +79,7 @@ public interface DOMNotificationPublishService extends DOMService {
      * @throws InterruptedException if interrupted while waiting
      * @throws NullPointerException if notification is null.
      */
-    @Nonnull ListenableFuture<? extends Object> putNotification(@Nonnull DOMNotification notification) throws InterruptedException;
+    @NonNull ListenableFuture<?> putNotification(@NonNull DOMNotification notification) throws InterruptedException;
 
     /**
      * Attempt to publish a notification. The result of this method is a {@link ListenableFuture}
@@ -82,11 +92,11 @@ public interface DOMNotificationPublishService extends DOMService {
      * @param notification Notification to be published.
      * @return A listenable future which will report completion when the service
      *         has finished propagating the notification to its immediate registrants,
-     *         or {@value #REJECTED} if resource constraints prevent
+     *         or {@link #REJECTED} if resource constraints prevent
      *         the implementation from accepting the notification for delivery.
      * @throws NullPointerException if notification is null.
      */
-    @Nonnull ListenableFuture<? extends Object> offerNotification(@Nonnull DOMNotification notification);
+    @NonNull ListenableFuture<?> offerNotification(@NonNull DOMNotification notification);
 
     /**
      * Attempt to publish a notification. The result of this method is a {@link ListenableFuture}
@@ -97,16 +107,16 @@ public interface DOMNotificationPublishService extends DOMService {
      * is guaranteed to block more than the specified timeout.
      *
      * @param notification Notification to be published.
-     * @param timeout how long to wait before giving up, in units of unit
+     * @param timeout how long to wait before giving up, in units of unit, must not be negative
      * @param unit a TimeUnit determining how to interpret the timeout parameter
      * @return A listenable future which will report completion when the service
      *         has finished propagating the notification to its immediate registrants,
-     *         or {@value #REJECTED} if resource constraints prevent
+     *         or {@link #REJECTED} if resource constraints prevent
      *         the implementation from accepting the notification for delivery.
      * @throws InterruptedException if interrupted while waiting
      * @throws NullPointerException if notification or unit is null.
      * @throws IllegalArgumentException if timeout is negative.
      */
-    @Nonnull ListenableFuture<? extends Object> offerNotification(@Nonnull DOMNotification notification,
-        @Nonnegative long timeout, @Nonnull TimeUnit unit) throws InterruptedException;
+    @NonNull ListenableFuture<?> offerNotification(@NonNull DOMNotification notification,
+        long timeout, @NonNull TimeUnit unit) throws InterruptedException;
 }