import org.eclipse.jdt.annotation.NonNull;
import org.opendaylight.yangtools.util.concurrent.FluentFutures;
import org.opendaylight.yangtools.yang.binding.DataObject;
+import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
import org.opendaylight.yangtools.yang.binding.InstanceNotification;
/**
* A {@link BindingService} which allows its users to submit YANG-modeled top-level (YANG 1.1)
- * {@link InstanceNotification}s for delivery. There are three methods of submission, following the patters from
- * {@link java.util.concurrent.BlockingQueue}:
- * <ul>
- * <li>{@link #putNotification(InstanceNotification)}, which may block indefinitely if the implementation cannot
- * allocate resources to accept the notification,</li>
- * <li>{@link #offerNotification(InstanceNotification)}, which does not block if face of resource starvation,</li>
- * <li>{@link #offerNotification(InstanceNotification, int, TimeUnit)}, which may block for specified time if
- * resources are thin.</li>
- * </ul>
- *
- * <p>
- * The actual delivery to listeners is asynchronous and implementation-specific. Users of this interface should not make
- * any assumptions as to whether the notification has or has not been seen.
+ * {@link InstanceNotification}s for delivery.
*/
@Beta
public interface InstanceNotificationPublishService extends BindingService {
/**
- * Well-known value indicating that the binding-aware implementation is currently not able to accept a notification.
- */
- @NonNull ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
- new NotificationRejectedException("Rejected due to resource constraints."));
-
- /**
- * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
- * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
- *
- * <b>Note:</b> This call will block when the notification queue is full.
+ * Create a new {@link Publisher} for a {@link InstanceNotificationSpec}. Returned interface may be freely reused
+ * and accessed concurrently from multiple threads.
*
- * @param notification the notification to publish.
- * @throws InterruptedException if interrupted while waiting
- * @throws NullPointerException if any argument is null
+ * @param <N> Generated InstanceNotification interface type
+ * @param <P> Notification parent type
+ * @param notificationSpec Specification of an {@link InstanceNotification}
+ * @return A {@link Publisher} handle
+ * @throws NullPointerException if {@code notificationSpec} is {@code null}
+ * @throws IllegalArgumentException when {@code notificationSpec} cannot be resolved
*/
- <N extends InstanceNotification<N, P>, P extends DataObject> void putNotification(
- @NonNull DataTreeIdentifier<P> path, @NonNull N notification) throws InterruptedException;
+ <N extends InstanceNotification<N, P>, P extends DataObject> @NonNull Publisher<N, P> newPublisher(
+ InstanceNotificationSpec<N, P> notificationSpec);
/**
- * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
- * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
+ * Interface for publishing {@link InstanceNotification} of a particular type bound to an instantiation. There are
+ * three methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
+ * <ul>
+ * <li>{@link #putNotification(InstanceNotification)}, which may block indefinitely if the implementation cannot
+ * allocate resources to accept the notification,</li>
+ * <li>{@link #offerNotification(InstanceNotification)}, which does not block if face of resource starvation,</li>
+ * <li>{@link #offerNotification(InstanceNotification, int, TimeUnit)}, which may block for specified time if
+ * resources are thin.</li>
+ * </ul>
*
* <p>
- * Still guaranteed not to block. Returns Listenable Future which will complete once the delivery is completed.
+ * The actual delivery to listeners is asynchronous and implementation-specific. Users of this interface should not
+ * make any assumptions as to whether the notification has or has not been seen.
*
- * @param notification the notification to publish.
- * @return A listenable future which will report completion when the service has finished propagating the
- * notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
- * @throws NullPointerException if any argument is null
+ * @param <N> Generated InstanceNotification interface type
+ * @param <P> Notification parent type
*/
- <N extends InstanceNotification<N, P>, P extends DataObject>
- @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull DataTreeIdentifier<P> path,
+ @Beta
+ interface Publisher<N extends InstanceNotification<N, P>, P extends DataObject> {
+ /**
+ * Well-known value indicating that the binding-aware implementation is currently not able to accept a
+ * notification.
+ */
+ @NonNull ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
+ new NotificationRejectedException("Rejected due to resource constraints."));
+
+ /**
+ * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
+ * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
+ *
+ * <b>Note:</b> This call will block when the notification queue is full.
+ *
+ * @param path parent path
+ * @param notification the notification to publish.
+ * @throws InterruptedException if interrupted while waiting
+ * @throws NullPointerException if any argument is null
+ */
+ void putNotification(@NonNull InstanceIdentifier<P> path, @NonNull N notification) throws InterruptedException;
+
+ /**
+ * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
+ * delivery to the listeners can happen asynchronously, potentially after a call to this method returns.
+ *
+ * <p>
+ * Still guaranteed not to block. Returns Listenable Future which will complete once the delivery is completed.
+ *
+ * @param path parent path
+ * @param notification the notification to publish.
+ * @return A listenable future which will report completion when the service has finished propagating the
+ * notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
+ * @throws NullPointerException if any argument is null
+ */
+ @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull InstanceIdentifier<P> path,
@NonNull N notification);
- /**
- * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
- * delivery to the listeners can happen asynchronously, potentially after a call to this method returns. This method
- * is guaranteed not to block more than the specified timeout.
- *
- * @param notification the notification to publish.
- * @param timeout how long to wait before giving up, in units of unit
- * @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 {@link #REJECTED} if resource constraints prevent
- * @throws InterruptedException if interrupted while waiting
- * @throws NullPointerException if any argument is null
- * @throws IllegalArgumentException if timeout is negative.
- */
- <N extends InstanceNotification<N, P>, P extends DataObject>
- @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull
DataTreeIdentifier<P> path,
+ /**
+ * Publishes a notification to subscribed listeners. This initiates the process of sending the notification, but
+ * delivery to the listeners can happen asynchronously, potentially after a call to this method returns. This
+ * method is guaranteed not to block more than the specified timeout.
+ *
+ * @param path parent path
+ * @param notification the notification to publish.
+ * @param timeout how long to wait before giving up, in units of unit
+ * @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 {@link #REJECTED} if resource constraints prevent
+ * @throws InterruptedException if interrupted while waiting
+ * @throws NullPointerException if any argument is null
+ * @throws IllegalArgumentException if timeout is negative.
+ */
+ @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull
InstanceIdentifier<P> path,
@NonNull N notification, long timeout, @NonNull TimeUnit unit) throws InterruptedException;
+ }
}
Code Review / mdsal.git / blobdiff