From: Tom Pantelis Date: Tue, 6 Mar 2018 03:11:05 +0000 (-0500) Subject: Fix checkstyle violations in sal-binding-api X-Git-Tag: release/fluorine~161 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=f1a918f69b787dd422a09e4e8fd83a1d52a72f83 Fix checkstyle violations in sal-binding-api Change-Id: Ic39062434dccf9616675b3616e142600f250c814 Signed-off-by: Tom Pantelis --- diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingService.java index ccce73c7d7..f8a7bff07b 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingService.java @@ -10,14 +10,15 @@ package org.opendaylight.controller.md.sal.binding.api; import org.opendaylight.controller.sal.binding.api.BindingAwareService; /** - * * Marker interface for MD-SAL services which are available for users of MD-SAL. * + *

* BindingService is marker interface for infrastructure services provided by * the SAL. These services may be session-specific, and wrapped by custom * delegator patterns in order to introduce additional semantics / checks * to the system. * + *

* This interface extends {@link BindingAwareService}, order to be make * new services available via * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext} diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingTransactionChain.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingTransactionChain.java index c71aa049c0..b28fbe459c 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingTransactionChain.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/BindingTransactionChain.java @@ -13,6 +13,7 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; /** * A chain of transactions. + * *

* For more information about transaction chaining and transaction chains * see {@link TransactionChain}. @@ -20,22 +21,14 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; * @see TransactionChain * */ -public interface BindingTransactionChain extends TransactionFactory, TransactionChain, DataObject> { - /** - * {@inheritDoc} - */ +public interface BindingTransactionChain extends TransactionFactory, + TransactionChain, DataObject> { @Override ReadOnlyTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override ReadWriteTransaction newReadWriteTransaction(); - /** - * {@inheritDoc} - */ @Override WriteTransaction newWriteOnlyTransaction(); } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ClusteredDataTreeChangeListener.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ClusteredDataTreeChangeListener.java index 557541424e..aa4d8d34c6 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ClusteredDataTreeChangeListener.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ClusteredDataTreeChangeListener.java @@ -12,6 +12,7 @@ import org.opendaylight.yangtools.yang.binding.DataObject; /** * ClusteredDataTreeChangeListener is a marker interface to enable data tree change notifications on all * instances in a cluster where this listener is registered. + * *

* Applications should implement ClusteredDataTreeChangeListener instead of {@link DataTreeChangeListener}, * if they want to listen for data tree change notifications on any node of a clustered data store. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataBroker.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataBroker.java index 8b085bae2d..d5c794336d 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataBroker.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataBroker.java @@ -18,6 +18,7 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; /** * Provides access to a conceptual data tree store and also provides the ability to * subscribe for changes to data under a given branch of the tree. + * *

* For more information on usage, please see the documentation in {@link AsyncDataBroker}. * @@ -25,35 +26,21 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; * @see TransactionChainFactory */ public interface DataBroker extends AsyncDataBroker, DataObject, DataChangeListener>, - TransactionChainFactory, DataObject>, TransactionFactory, BindingService, DataTreeChangeService { - /** - * {@inheritDoc} - */ + TransactionChainFactory, DataObject>, TransactionFactory, BindingService, + DataTreeChangeService { @Override ReadOnlyTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override ReadWriteTransaction newReadWriteTransaction(); - /** - * {@inheritDoc} - */ @Override WriteTransaction newWriteOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override ListenerRegistration registerDataChangeListener(LogicalDatastoreType store, InstanceIdentifier path, DataChangeListener listener, DataChangeScope triggeringScope); - /** - * {@inheritDoc} - */ @Override BindingTransactionChain createTransactionChain(TransactionChainListener listener); } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataObjectModification.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataObjectModification.java index f8dd3b0cce..2df4f8bde0 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataObjectModification.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataObjectModification.java @@ -19,28 +19,25 @@ import org.opendaylight.yangtools.yang.binding.Identifier; import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument; /** - * Modified Data Object. - * - * Represents modification of Data Object. - * + * Represents a modification of DataObject. */ -public interface DataObjectModification extends org.opendaylight.yangtools.concepts.Identifiable { +public interface DataObjectModification + extends org.opendaylight.yangtools.concepts.Identifiable { enum ModificationType { /** - * * Child node (direct or indirect) was modified. * */ SUBTREE_MODIFIED, + /** - * * Node was explicitly created / overwritten. * */ + WRITE, /** - * * Node was deleted. * */ @@ -58,8 +55,7 @@ public interface DataObjectModification extends org.openda @Nonnull Class getDataType(); /** - * - * Returns type of modification + * Returns type of modification. * * @return type Type of performed modification. */ @@ -89,9 +85,9 @@ public interface DataObjectModification extends org.openda @Nonnull Collection> getModifiedChildren(); /** - * Returns container child modification if {@code child} was modified by this - * modification. + * Returns container child modification if {@code child} was modified by this modification. * + *

* For accessing all modified list items consider iterating over {@link #getModifiedChildren()}. * * @param child Type of child - must be only container @@ -99,12 +95,13 @@ public interface DataObjectModification extends org.openda * @throws IllegalArgumentException If supplied {@code child} class is not valid child according * to generated model. */ - @Nullable > DataObjectModification getModifiedChildContainer(@Nonnull Class child); + @Nullable > DataObjectModification getModifiedChildContainer( + @Nonnull Class child); /** - * Returns augmentation child modification if {@code augmentation} was modified by this - * modification. + * Returns augmentation child modification if {@code augmentation} was modified by this modification. * + *

* For accessing all modified list items consider iterating over {@link #getModifiedChildren()}. * * @param augmentation Type of augmentation - must be only container @@ -112,7 +109,8 @@ public interface DataObjectModification extends org.openda * @throws IllegalArgumentException If supplied {@code augmentation} class is not valid augmentation * according to generated model. */ - @Nullable & DataObject> DataObjectModification getModifiedAugmentation(@Nonnull Class augmentation); + @Nullable & DataObject> DataObjectModification getModifiedAugmentation( + @Nonnull Class augmentation); /** @@ -124,8 +122,8 @@ public interface DataObjectModification extends org.openda * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according * to generated model. */ - & ChildOf, K extends Identifier> DataObjectModification getModifiedChildListItem( - @Nonnull Class listItem,@Nonnull K listKey); + & ChildOf, K extends Identifier> DataObjectModification + getModifiedChildListItem(@Nonnull Class listItem,@Nonnull K listKey); /** * Returns a child modification if a node identified by {@code childArgument} was modified by @@ -139,5 +137,4 @@ public interface DataObjectModification extends org.openda * */ @Nullable DataObjectModification getModifiedChild(PathArgument childArgument); - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeListener.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeListener.java index d52835b7ed..6d6ea17a35 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeListener.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeListener.java @@ -17,6 +17,7 @@ import org.opendaylight.yangtools.yang.binding.DataObject; * data tree changes. This interface differs from {@link DataChangeListener} * in that it provides a cursor-based view of the change, which has potentially * lower overhead and allow more flexible consumption of change event. + * *

* Note: this interface enables notifications only at the leader of the data store, if clustered. If you want * notifications on all instances in a cluster, use the {@link ClusteredDataTreeChangeListener}. @@ -37,6 +38,7 @@ public interface DataTreeChangeListener extends EventListe * to recover from such events. Event producers are expected to exert reasonable * effort to suppress such events. * + *

* In other words, it is completely acceptable to observe * a {@link DataObjectModification}, while the state observed before and * after- data items compare as equal. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeService.java index f899eb13e4..11697bfc85 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeChangeService.java @@ -20,14 +20,16 @@ public interface DataTreeChangeService extends BindingService { * Registers a {@link DataTreeChangeListener} to receive * notifications when data changes under a given path in the conceptual data * tree. + * *

* You are able to register for notifications for any node or subtree * which can be represented using {@link DataTreeIdentifier}. - *

* + *

* You are able to register for data change notifications for a subtree or leaf * even if it does not exist. You will receive notification once that node is * created. + * *

* If there is any pre-existing data in the data tree for the path for which you are * registering, you will receive an initial data change event, which will @@ -37,6 +39,7 @@ public interface DataTreeChangeService extends BindingService { * This method returns a {@link ListenerRegistration} object. To * "unregister" your listener for changes call the {@link ListenerRegistration#close()} * method on the returned object. + * *

* You MUST explicitly unregister your listener when you no longer want to receive * notifications. This is especially true in OSGi environments, where failure to @@ -51,5 +54,6 @@ public interface DataTreeChangeService extends BindingService { * your listener using {@link ListenerRegistration#close()} to stop * delivery of change events. */ - @Nonnull > ListenerRegistration registerDataTreeChangeListener(@Nonnull DataTreeIdentifier treeId, @Nonnull L listener); + @Nonnull > ListenerRegistration + registerDataTreeChangeListener(@Nonnull DataTreeIdentifier treeId, @Nonnull L listener); } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeIdentifier.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeIdentifier.java index 13d0a92600..79b2a6d526 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeIdentifier.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/DataTreeIdentifier.java @@ -20,7 +20,8 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; * A unique identifier for a particular subtree. It is composed of the logical * data store type and the instance identifier of the root node. */ -public final class DataTreeIdentifier implements Immutable, Path>, Serializable { +public final class DataTreeIdentifier implements Immutable, + Path>, Serializable { private static final long serialVersionUID = 1L; private final InstanceIdentifier rootIdentifier; private final LogicalDatastoreType datastoreType; @@ -79,7 +80,7 @@ public final class DataTreeIdentifier implements Immutable @Override public String toString() { - return getClass().getSimpleName() + "{datastoreType = " + datastoreType + ", rootIdentifier = " + - rootIdentifier + "}"; + return getClass().getSimpleName() + "{datastoreType = " + datastoreType + ", rootIdentifier = " + + rootIdentifier + "}"; } } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ForwardingWriteTransaction.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ForwardingWriteTransaction.java index e6027430ce..13151eef8a 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ForwardingWriteTransaction.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ForwardingWriteTransaction.java @@ -10,7 +10,6 @@ package org.opendaylight.controller.md.sal.binding.api; import com.google.common.collect.ForwardingObject; import com.google.common.util.concurrent.CheckedFuture; import com.google.common.util.concurrent.ListenableFuture; -import org.opendaylight.controller.md.sal.binding.api.WriteTransaction; import org.opendaylight.controller.md.sal.common.api.TransactionStatus; import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType; import org.opendaylight.controller.md.sal.common.api.data.TransactionCommitFailedException; @@ -82,5 +81,4 @@ public class ForwardingWriteTransaction extends ForwardingObject implements Writ public Object getIdentifier() { return delegate.getIdentifier(); } - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/MountPoint.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/MountPoint.java index e8bd753bba..0c676e0653 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/MountPoint.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/MountPoint.java @@ -11,8 +11,6 @@ import com.google.common.base.Optional; import org.opendaylight.yangtools.concepts.Identifiable; import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; -public interface MountPoint extends Identifiable>{ - +public interface MountPoint extends Identifiable> { Optional getService(Class service); - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationPublishService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationPublishService.java index 393839ce58..db36d3001f 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationPublishService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationPublishService.java @@ -23,6 +23,7 @@ import org.opendaylight.yangtools.yang.binding.Notification; * - {@link #offerNotification(Notification, int, TimeUnit)}, which may block * for specified time if resources are thin. * + *

* 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. @@ -33,7 +34,8 @@ public interface NotificationPublishService extends BindingService { * Well-known value indicating that the binding-aware implementation is currently not * able to accept a notification. */ - ListenableFuture REJECTED = Futures.immediateFailedFuture(new NotificationRejectedException("Rejected due to resource constraints.")); + ListenableFuture REJECTED = Futures.immediateFailedFuture(new NotificationRejectedException( + "Rejected due to resource constraints.")); /** * Publishes a notification to subscribed listeners. This initiates @@ -56,13 +58,14 @@ public interface NotificationPublishService extends BindingService { * listeners can happen asynchronously, potentially after a call to * this method returns. * + *

* Still guaranteed not to block. Returns Listenable Future which will complete once. * * @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 + * propagating the notification to its immediate registrants, or {@link #REJECTED} if resource + * constraints prevent * @throws NullPointerException if the notification is null */ ListenableFuture offerNotification(Notification notification); @@ -80,8 +83,8 @@ public interface NotificationPublishService extends BindingService { * @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 + * propagating the notification to its immediate registrants, or {@link #REJECTED} if resource + * constraints prevent * @throws InterruptedException if interrupted while waiting * @throws NullPointerException if the notification or unit is null * @throws IllegalArgumentException if timeout is negative. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationService.java index c0e8ea5fee..3744eeef99 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/NotificationService.java @@ -13,15 +13,17 @@ import org.opendaylight.yangtools.yang.binding.NotificationListener; /** * Notification broker which allows clients to subscribe for and publish YANG-modeled notifications. * + *

* Each YANG module which defines notifications results in a generated interface {ModuleName}Listener * which handles all the notifications defined in the YANG model. Each notification type translates to * a specific method of the form on{NotificationType} on the generated interface. * The generated interface also extends the * {@link org.opendaylight.yangtools.yang.binding.NotificationListener} interface and implementations - * are registered using {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)} - * method. + * are registered using + * {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)} method. * *

Dispatch Listener Example

+ * *

* Lets assume we have following YANG model: * @@ -39,6 +41,7 @@ import org.opendaylight.yangtools.yang.binding.NotificationListener; * } * * + *

* The generated interface will be: * {@code * public interface ExampleListener extends NotificationListener { diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadOnlyTransaction.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadOnlyTransaction.java index f3b42b96f0..5e76e2183b 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadOnlyTransaction.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadOnlyTransaction.java @@ -13,10 +13,11 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; /** * A transaction that provides a stateful read-only view of the data tree. + * *

* For more information on usage and examples, please see the documentation in * {@link org.opendaylight.controller.md.sal.common.api.data.AsyncReadTransaction}. */ -public interface ReadOnlyTransaction extends ReadTransaction, AsyncReadOnlyTransaction, DataObject> { - +public interface ReadOnlyTransaction extends ReadTransaction, AsyncReadOnlyTransaction, + DataObject> { } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadTransaction.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadTransaction.java index b0c93734e0..21bcf23cd4 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadTransaction.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadTransaction.java @@ -7,17 +7,17 @@ */ package org.opendaylight.controller.md.sal.binding.api; +import com.google.common.base.Optional; +import com.google.common.util.concurrent.CheckedFuture; import org.opendaylight.controller.md.sal.common.api.data.AsyncReadTransaction; import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType; import org.opendaylight.controller.md.sal.common.api.data.ReadFailedException; import org.opendaylight.yangtools.yang.binding.DataObject; import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; -import com.google.common.base.Optional; -import com.google.common.util.concurrent.CheckedFuture; - /** * A transaction that provides read access to a logical data store. + * *

* For more information on usage and examples, please see the documentation in {@link AsyncReadTransaction}. */ diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadWriteTransaction.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadWriteTransaction.java index 9fbbbe5a73..99da3b6826 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadWriteTransaction.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/ReadWriteTransaction.java @@ -13,9 +13,10 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; /** * A transaction that enables combined read/write capabilities. + * *

* For more information on usage and examples, please see the documentation in {@link AsyncReadWriteTransaction}. */ -public interface ReadWriteTransaction extends ReadTransaction, WriteTransaction, AsyncReadWriteTransaction, DataObject> { - +public interface ReadWriteTransaction extends ReadTransaction, WriteTransaction, + AsyncReadWriteTransaction, DataObject> { } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/TransactionFactory.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/TransactionFactory.java index 1f0a6fcf01..fee1b7c8d0 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/TransactionFactory.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/TransactionFactory.java @@ -12,8 +12,7 @@ import org.opendaylight.controller.md.sal.common.api.data.AsyncDataTransactionFa import org.opendaylight.yangtools.yang.binding.DataObject; import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; -public interface TransactionFactory extends AsyncDataTransactionFactory, DataObject>{ - +public interface TransactionFactory extends AsyncDataTransactionFactory, DataObject> { @Override ReadOnlyTransaction newReadOnlyTransaction(); @@ -22,5 +21,4 @@ public interface TransactionFactory extends AsyncDataTransactionFactory * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}. */ diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareConsumer.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareConsumer.java index fc9d9fa2ba..031c157026 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareConsumer.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareConsumer.java @@ -10,11 +10,10 @@ package org.opendaylight.controller.sal.binding.api; import org.osgi.framework.BundleContext; @Deprecated -public abstract class AbstractBindingAwareConsumer extends AbstractBrokerAwareActivator implements BindingAwareConsumer { - +public abstract class AbstractBindingAwareConsumer extends AbstractBrokerAwareActivator + implements BindingAwareConsumer { @Override protected final void onBrokerAvailable(BindingAwareBroker broker, BundleContext context) { broker.registerConsumer(this, context); } - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareProvider.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareProvider.java index 0b9c604c2b..967bbbf2c4 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareProvider.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBindingAwareProvider.java @@ -7,14 +7,13 @@ */ package org.opendaylight.controller.sal.binding.api; -import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext; import org.osgi.framework.BundleContext; @Deprecated -public abstract class AbstractBindingAwareProvider extends AbstractBrokerAwareActivator implements BindingAwareProvider { - +public abstract class AbstractBindingAwareProvider extends AbstractBrokerAwareActivator + implements BindingAwareProvider { @Override protected final void onBrokerAvailable(BindingAwareBroker broker, BundleContext context) { - ProviderContext ctx = broker.registerProvider(this, context); + broker.registerProvider(this, context); } } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBrokerAwareActivator.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBrokerAwareActivator.java index a489e63410..83af462af3 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBrokerAwareActivator.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/AbstractBrokerAwareActivator.java @@ -9,7 +9,7 @@ package org.opendaylight.controller.sal.binding.api; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; - +import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext; import org.osgi.framework.BundleActivator; import org.osgi.framework.BundleContext; import org.osgi.framework.ServiceReference; @@ -18,16 +18,17 @@ import org.osgi.util.tracker.ServiceTrackerCustomizer; public abstract class AbstractBrokerAwareActivator implements BundleActivator { - private static final ExecutorService mdActivationPool = Executors.newCachedThreadPool(); + private static final ExecutorService MD_ACTIVATION_POOL = Executors.newCachedThreadPool(); private BundleContext context; private ServiceTracker tracker; private BindingAwareBroker broker; - private ServiceTrackerCustomizer customizer = new ServiceTrackerCustomizer() { + private final ServiceTrackerCustomizer customizer = + new ServiceTrackerCustomizer() { @Override public BindingAwareBroker addingService(ServiceReference reference) { broker = context.getService(reference); - mdActivationPool.execute(() -> onBrokerAvailable(broker, context)); + MD_ACTIVATION_POOL.execute(() -> onBrokerAvailable(broker, context)); return broker; } @@ -40,17 +41,17 @@ public abstract class AbstractBrokerAwareActivator implements BundleActivator { @Override public void removedService(ServiceReference reference, BindingAwareBroker service) { broker = context.getService(reference); - mdActivationPool.execute(() -> onBrokerRemoved(broker, context)); + MD_ACTIVATION_POOL.execute(() -> onBrokerRemoved(broker, context)); } }; @Override - public final void start(BundleContext context) throws Exception { - this.context = context; - startImpl(context); - tracker = new ServiceTracker<>(context, BindingAwareBroker.class, customizer); + public final void start(BundleContext bundleContext) throws Exception { + this.context = bundleContext; + startImpl(bundleContext); + tracker = new ServiceTracker<>(bundleContext, BindingAwareBroker.class, customizer); tracker.open(); } @@ -58,12 +59,11 @@ public abstract class AbstractBrokerAwareActivator implements BundleActivator { @Override - public final void stop(BundleContext context) throws Exception { + public final void stop(BundleContext bundleContext) throws Exception { tracker.close(); - stopImpl(context); + stopImpl(bundleContext); } - /** * Called when this bundle is started (before * {@link BindingAwareProvider#onSessionInitiated(ProviderContext)} so the Framework can perform @@ -74,7 +74,7 @@ public abstract class AbstractBrokerAwareActivator implements BundleActivator { *

* This method must complete and return to its caller in a timely manner. * - * @param context + * @param bundleContext * The execution context of the bundle being started. * @throws RuntimeException * If this method throws an exception, this bundle is marked as @@ -82,7 +82,7 @@ public abstract class AbstractBrokerAwareActivator implements BundleActivator { * listeners, unregister all services registered by this bundle, * and release all services used by this bundle. */ - protected void startImpl(BundleContext context) { + protected void startImpl(BundleContext bundleContext) { // NOOP } @@ -97,20 +97,19 @@ public abstract class AbstractBrokerAwareActivator implements BundleActivator { *

* This method must complete and return to its caller in a timely manner. * - * @param context The execution context of the bundle being stopped. + * @param bundleContext The execution context of the bundle being stopped. * @throws RuntimeException If this method throws an exception, the bundle is still * marked as stopped, and the Framework will remove the bundle's * listeners, unregister all services registered by the bundle, and * release all services used by the bundle. */ - protected void stopImpl(BundleContext context) { + protected void stopImpl(BundleContext bundleContext) { // NOOP } + protected abstract void onBrokerAvailable(BindingAwareBroker bindingBroker, BundleContext bundleContext); - protected abstract void onBrokerAvailable(BindingAwareBroker broker, BundleContext context); - - protected void onBrokerRemoved(BindingAwareBroker broker, BundleContext context) { - stopImpl(context); + protected void onBrokerRemoved(BindingAwareBroker bindingBroker, BundleContext bundleContext) { + stopImpl(bundleContext); } } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.java index 2841bb77b0..81f8124c46 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.java @@ -17,17 +17,18 @@ import org.osgi.framework.BundleContext; /** * Binding-aware core of the SAL layer responsible for wiring the SAL consumers. * + *

* The responsibility of the broker is to maintain registration of SAL * functionality Consumers and Providers, store provider and * consumer specific context and functionality registration via * {@link ConsumerContext} and provide access to infrastructure services, which * removes direct dependencies between providers and consumers. * + *

* The Binding-aware broker is also responsible for translation from Java * classes modeling the functionality and data to binding-independent form which * is used in SAL Core. * - * *

Infrastructure services

Some examples of infrastructure services: * *
    @@ -37,13 +38,16 @@ import org.osgi.framework.BundleContext; * {@link NotificationProviderService} *
* + *

* The services are exposed via session. * *

Session-based access

* + *

* The providers and consumers needs to register in order to use the * binding-independent SAL layer and to expose functionality via SAL layer. * + *

* For more information about session-based access see {@link ConsumerContext} * and {@link ProviderContext} */ @@ -129,8 +133,7 @@ public interface BindingAwareBroker { interface ConsumerContext extends RpcConsumerRegistry { /** - * Returns a session specific instance (implementation) of requested - * binding-aware infrastructural service + * Returns a session specific instance (implementation) of requested binding-aware infrastructure service. * * @param service * Broker service @@ -186,25 +189,17 @@ public interface BindingAwareBroker { RoutedRegistration, InstanceIdentifier, T> { /** - * Register particular instance identifier to be processed by this - * RpcService - * - * Deprecated in favor of RoutedRegistration#registerPath(Object, Object). + * Register particular instance identifier to be processed by this RpcService. * - * @param context - * @param instance + * @deprecated in favor of RoutedRegistration#registerPath(Object, Object). */ @Deprecated void registerInstance(Class context, InstanceIdentifier instance); /** - * Unregister particular instance identifier to be processed by this - * RpcService - * - * Deprecated in favor of RoutedRegistration#unregisterPath(Class, InstanceIdentifier). + * Unregister particular instance identifier to be processed by this RpcService. * - * @param context - * @param instance + * @deprecated in favor of RoutedRegistration#unregisterPath(Class, InstanceIdentifier). */ @Deprecated void unregisterInstance(Class context, InstanceIdentifier instance); diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java index b3b3e07b5e..d194591a88 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java @@ -10,75 +10,83 @@ package org.opendaylight.controller.sal.binding.api; import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext; /** -* -* A developer implemented component that gets registered with the Broker. -* -* Semantically, a consumer may: -* -*

    -*
  1. Subscribe for Notifications
    2. -*
  2. Invoke RPCs
    3. -*
  3. Read from either the operational or config data tree
    4. -*
  4. Write to the config data tree
    5. -*
-* If you need to: -*
    -*
  1. Emit Notifications
    2. -*
  2. Provide the implementation of RPCs
    3. -*
  3. Write to the operational data tree
    4. -*
-* -* Consider using a BindingAwareProvider -* -* Examples: -* -* To get a NotificationService: -* -* {code -* public void onSessionInitiated(ProviderContext session) { -* NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class); -* notificationService.publish(notification) -* } -* where notification is an instance of a modeled Notification. -* For more information on sending notifications via the NotificationProviderService -* @see org.opendaylight.controller.sal.binding.api.NotificationProviderService -* -* -* A consumer can *invoke* and RPC ( ie, call foo(fooArgs)) but it cannot register an RPC -* implementation with the MD-SAL that others can invoke(call). -* To get an invokable RPC: -* -* {code -* public void onSessionInitiated(ProviderContext session) { -* MyService rpcFlowSalService = session.getRpcService(MyService.class); -* } -* -* Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it. The returned -* rpcFlowSalService can be used like any other object by invoking its methods. Note, nothing special needs to be done -* for RoutedRPCs. They just work. -* -* To get a DataBroker to allow access to the data tree: -* -* {code -* public void onSessionInitiated(final ProviderContext session) { -* DataBroker databroker = session.getSALService(BindingDataBroker.class); -* } -* } + * A developer implemented component that gets registered with the Broker. + * + *

+ * Semantically, a consumer may: + * + *

    + *
  1. Subscribe for Notifications
    2. + *
  2. Invoke RPCs
    3. + *
  3. Read from either the operational or config data tree
    4. + *
  4. Write to the config data tree
    5. + *
+ * If you need to: + *
    + *
  1. Emit Notifications
    2. + *
  2. Provide the implementation of RPCs
    3. + *
  3. Write to the operational data tree
    4. + *
+ * + *

+ * Consider using a BindingAwareProvider + * + *

+ * Examples: + * + *

+ * To get a NotificationService: + * + *

+ * {code + * public void onSessionInitiated(ProviderContext session) { + * NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class); + * notificationService.publish(notification) + * } + * where notification is an instance of a modeled Notification. + * For more information on sending notifications via the NotificationProviderService + * see org.opendaylight.controller.sal.binding.api.NotificationProviderService + * + *

+ * A consumer can *invoke* and RPC ( ie, call foo(fooArgs)) but it cannot register an RPC + * implementation with the MD-SAL that others can invoke(call). + * To get an invokable RPC: + * + *

+ * {code + * public void onSessionInitiated(ProviderContext session) { + * MyService rpcFlowSalService = session.getRpcService(MyService.class); + * } + * + *

+ * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it. The returned + * rpcFlowSalService can be used like any other object by invoking its methods. Note, nothing special needs to be done + * for RoutedRPCs. They just work. + * + *

+ * To get a DataBroker to allow access to the data tree: + * + *

+ * {code + * public void onSessionInitiated(final ProviderContext session) { + * DataBroker databroker = session.getSALService(BindingDataBroker.class); + * } + * } */ public interface BindingAwareConsumer { /** * Callback signaling initialization of the consumer session to the SAL. * + *

* The consumer MUST use the session for all communication with SAL or * retrieving SAL infrastructure services. * - * This method is invoked by - * {@link BindingAwareBroker#registerConsumer(BindingAwareConsumer)} + *

+ * This method is invoked by {@link BindingAwareBroker#registerConsumer(BindingAwareConsumer)} * * @param session * Unique session between consumer and SAL. */ void onSessionInitialized(ConsumerContext session); - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java index 808863262d..699fd9171e 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java @@ -10,9 +10,9 @@ package org.opendaylight.controller.sal.binding.api; import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext; /** - * * A developer implemented component that gets registered with the Broker. * + *

* Semantically, a provider may: * *

    @@ -21,14 +21,13 @@ import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderCo *
  1. Write to the operational data tree
    2. *
* + *

* If a class is not doing at least one of those three, consider using * a BindingAwareConsumer instead: - * @see org.opendaylight.controller.sal.binding.api.BindingAwareConsumer + * see {@link org.opendaylight.controller.sal.binding.api.BindingAwareConsumer} * *

- * - *In addition, a BindingAwareProvider can in pursuit of its goals: - * + * In addition, a BindingAwareProvider can in pursuit of its goals: *

    *
  1. Subscribe for Notifications
    2. *
  2. Invoke RPCs
    3. @@ -37,12 +36,10 @@ import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderCo *
* (All of the above are things a Consumer can also do). * - *

- * + *

* Examples: * *

- * * To get a NotificationService: * * {@code @@ -51,8 +48,9 @@ import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderCo * } * } * For more information on sending notifications via the NotificationProviderService - * @see org.opendaylight.controller.sal.binding.api.NotificationProviderService + * see {@link org.opendaylight.controller.sal.binding.api.NotificationProviderService} * + *

* To register an RPC implementation: * * {@code @@ -62,35 +60,41 @@ import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderCo * } * *

- * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it and myImplementationInstance - * is an instance of a class that implements MyService. + * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it and + * myImplementationInstance is an instance of a class that implements MyService. * + *

* To register a Routed RPC Implementation: * {@code * public void onSessionInitiated(ProviderContext session) { - * RoutedRpcRegistration flowRegistration = session.addRoutedRpcImplementation(SalFlowService.class, salFlowServiceImplementationInstance); + * RoutedRpcRegistration flowRegistration = session.addRoutedRpcImplementation(SalFlowService.class, + * salFlowServiceImplementationInstance); flowRegistration.registerPath(NodeContext.class, nodeInstanceId); * } * } * - * Where SalFlowService.class is a Service interface generated from a yang model with RPCs modeled in it and salFlowServiceImplementationInstance is an instance - * of a class that implements SalFlowService. + *

+ * Where SalFlowService.class is a Service interface generated from a yang model with RPCs modeled in it and + * salFlowServiceImplementationInstance is an instance of a class that implements SalFlowService. + * *

* The line: * {@code * flowRegistration.registerPath(NodeContext.class, nodeInstanceId); * } - * Is indicating that the RPC implementation is registered to handle RPC invocations that have their NodeContext pointing to the node with instance id nodeInstanceId. - * This bears a bit of further explanation. RoutedRPCs can be 'routed' to an implementation based upon 'context'. 'context' is a pointer (instanceId) to some place - * in the data tree. In this example, the 'context' is a pointer to a Node. In this way, a provider can register its ability to provide a service for a particular - * Node, but not *all* Nodes. The Broker routes the RPC by 'context' to the correct implementation, without the caller having to do extra work. Because of this when - * a RoutedRPC is registered, it needs to also be able to indicate for which 'contexts' it is providing an implementation. + * Is indicating that the RPC implementation is registered to handle RPC invocations that have their NodeContext + * pointing to the node with instance id nodeInstanceId. This bears a bit of further explanation. RoutedRPCs can be + * 'routed' to an implementation based upon 'context'. 'context' is a pointer (instanceId) to some place in the data + * tree. In this example, the 'context' is a pointer to a Node. In this way, a provider can register its ability to + * provide a service for a particular Node, but not *all* Nodes. The Broker routes the RPC by 'context' to the correct + * implementation, without the caller having to do extra work. Because of this when a RoutedRPC is registered, it + * needs to also be able to indicate for which 'contexts' it is providing an implementation. * - * An example of a Routed RPC would be an updateFlow(node, flow) that would be routed based on node to the provider which had registered to provide - * it *for that node*. + *

+ * An example of a Routed RPC would be an updateFlow(node, flow) that would be routed based on node to the provider + * which had registered to provide it *for that node*. * *

- * * To get a DataBroker to allow access to the data tree: * * {@code @@ -104,9 +108,11 @@ public interface BindingAwareProvider { /** * Callback signaling initialization of the consumer session to the SAL. * + *

* The consumer MUST use the session for all communication with SAL or * retrieving SAL infrastructure services. * + *

* This method is invoked by * {@link BindingAwareBroker#registerProvider(BindingAwareProvider)} * diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareService.java index adaa27f3e6..61714b1b9b 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareService.java @@ -17,13 +17,13 @@ package org.opendaylight.controller.sal.binding.api; * instance of the service with it's own context. * *

- * The consumer's (or provider's) instance of specific service could be obtained - * by invoking {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext#getSALService(Class)} method on session - * assigned to the consumer. + * The consumer's (or provider's) instance of specific service could be obtained by invoking + * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext#getSALService(Class)} + * method on session assigned to the consumer. * *

- * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext} and {@link BindingAwareProvider} may seem - * similar, but provider provides YANG model-based functionality and + * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext} + * and {@link BindingAwareProvider} may seem similar, but provider provides YANG model-based functionality and * {@link BindingAwareProvider} exposes the necessary supporting functionality * to implement specific functionality of YANG and to reuse it in the * development of {@link BindingAwareConsumer}s and {@link BindingAwareProvider}s. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationListener.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationListener.java index e5a0a2bd6d..dbe6937b0d 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationListener.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationListener.java @@ -22,6 +22,7 @@ import org.opendaylight.yangtools.yang.binding.Notification; public interface NotificationListener extends EventListener { /** * Invoked to deliver a notification. + * *

* Note that this method may be invoked from a shared thread pool, so implementations SHOULD NOT * perform CPU-intensive operations and MUST NOT invoke any potentially blocking operations. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java index 073f98a91f..0f183a0e8c 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java @@ -23,15 +23,9 @@ import org.opendaylight.yangtools.yang.binding.Notification; @Deprecated public interface NotificationProviderService extends NotificationService, NotificationPublishService { - /** - * {@inheritDoc} - */ @Override void publish(Notification notification); - /** - * {@inheritDoc} - */ @Override void publish(Notification notification, ExecutorService executor); @@ -39,6 +33,7 @@ public interface NotificationProviderService extends NotificationService, Notifi * Registers a listener to be notified about notification subscriptions. This * enables a component to know when there is a notification listener subscribed * for a particular notification type. + * *

* On registration of this listener, the * {@link NotificationInterestListener#onNotificationSubscribtion(Class)} method @@ -59,12 +54,13 @@ public interface NotificationProviderService extends NotificationService, Notifi interface NotificationInterestListener extends EventListener { /** - * Callback that is invoked when a notification listener subscribes for a - * particular notification type. + * Callback that is invoked when a notification listener subscribes for a particular notification type. + * *

* This method is only called for the first subscription that occurs for a * particular notification type. Subsequent subscriptions for the same * notification type do not trigger invocation of this method. + * *

* Note:This callback is delivered from thread not owned by this listener, * all processing should be as fast as possible and implementations should diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationService.java index 015988e3d9..8f3e1470e4 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationService.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationService.java @@ -23,13 +23,16 @@ import org.opendaylight.yangtools.yang.binding.Notification; * * *

Generic Listener

+ * *

* A generic listener implements the {@link NotificationListener} interface which has one callback method * onNotification that is invoked for any notification type the listener is subscribed to. + * *

* A generic listener is subscribed using the {@link #registerNotificationListener(Class, NotificationListener)} * method by which you specify the type of notification to receive. A generic listener may be registered for * multiple notification types via multiple subscriptions. + * *

* Generic listeners allow for a more flexible approach, allowing you to subscribe for just * one type of notification from a YANG model. You could also have a general subscription @@ -39,16 +42,18 @@ import org.opendaylight.yangtools.yang.binding.Notification; * * *

Dispatch Listener

+ * *

* A dispatch listener implements a YANG-generated module interface {ModuleName}Listener * which handles all the notifications defined in the YANG model. Each notification type translates to * a specific method of the form on{NotificationType} on the generated interface. * The generated interface also extends the * {@link org.opendaylight.yangtools.yang.binding.NotificationListener} interface and implementations - * are registered using {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)} - * method. + * are registered using + * {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)} method. * *

Dispatch Listener Example

+ * *

* Lets assume we have following YANG model: * @@ -66,6 +71,7 @@ import org.opendaylight.yangtools.yang.binding.Notification; * } * } * + *

* The generated interface will be: * {@code * public interface ExampleListener extends NotificationListener { diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcConsumerRegistry.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcConsumerRegistry.java index d31a2fe327..3967ff1c44 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcConsumerRegistry.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcConsumerRegistry.java @@ -13,6 +13,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; /** * Provides access to registered Remote Procedure Call (RPC) service implementations. The RPCs are * defined in YANG models. + * *

* RPC implementations are registered using the {@link RpcProviderRegistry}. * @@ -45,24 +46,24 @@ public interface RpcConsumerRegistry extends BindingAwareService, BindingService * RPC methods may be implemented asynchronously, callers should avoid blocking on the * {@link java.util.concurrent.Future Future} result. Instead, it is recommended to use * {@link com.google.common.util.concurrent.JdkFutureAdapters#listenInPoolThread(java.util.concurrent.Future)} - * or {@link com.google.common.util.concurrent.JdkFutureAdapters#listenInPoolThread(java.util.concurrent.Future, java.util.concurrent.Executor)} + * or {@link com.google.common.util.concurrent.JdkFutureAdapters#listenInPoolThread(java.util.concurrent.Future, + * java.util.concurrent.Executor)} * to listen for Rpc Result. This will asynchronously listen for future result in executor and * will not block current thread. * * {@code * final Future> future = someRpcService.someRpc( ... ); - * Futures.addCallback(JdkFutureAdapters.listenInThreadPool(future), new FutureCallback>() { - * - * public void onSuccess(RpcResult result) { - * // process result ... - * } + * Futures.addCallback(JdkFutureAdapters.listenInThreadPool(future), + * new FutureCallback>() { + * public void onSuccess(RpcResult result) { + * // process result ... + * } * - * public void onFailure(Throwable t) { - * // RPC failed - * } - * ); - * } - * } + * public void onFailure(Throwable t) { + * // RPC failed + * } + * }); + * } * * @param serviceInterface the interface of the RPC Service. Typically this is an interface generated * from a YANG model. diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java index 759dbe01a7..268906f450 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java @@ -17,6 +17,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; /** * Provides a registry for Remote Procedure Call (RPC) service implementations. The RPCs are * defined in YANG models. + * *

* There are 2 types of RPCs: *

    @@ -25,18 +26,22 @@ import org.opendaylight.yangtools.yang.binding.RpcService; *
* *

Global RPC

+ * *

* An RPC is global if there is intended to be only 1 registered implementation. A global RPC is not * explicitly declared as such, essentially any RPC that is not defined to be routed is considered global. + * *

* Global RPCs are registered using the * {@link #addRpcImplementation(Class, RpcService)} method. * *

Routed RPC

+ * *

* MD-SAL supports routing of RPC between multiple implementations where the appropriate * implementation is selected at run time based on the content of the RPC message as described in * YANG model. + * *

* RPC routing is based on: *

    @@ -49,6 +54,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; *
* *

Context type

+ * *

* A context type is modeled in YANG using a combination of a YANG identity * and Opendaylight specific extensions from yang-ext module. These extensions are: @@ -65,10 +71,9 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * instance-identifier or a type derived from instance-identifier. * * - * - *

Routed RPC example

- *

+ *


*

1. Defining a Context Type

+ * *

* The following snippet declares a simple YANG identity named example-context: * @@ -81,11 +86,13 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * ... * } * } + * *

* We then use the declared identity to define a context type by using it in combination * with the context-instance YANG extension. We'll associate the context type * with a list element in the data tree. This defines the set of nodes whose instance * identifiers are valid for the example-context context type. + * *

* The following YANG snippet imports the yang-ext module and defines the list * element named item inside a container named foo: @@ -105,6 +112,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * ... * } * } + * *

* The statement ext:context-instance "example-context"; inside the list element * declares that any instance identifier referencing item in the data @@ -118,15 +126,19 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * InstanceIdentifier.create(Example.class) * * is not valid. + * *

* So using an identity in combination with context-instance we * have effectively defined a context type that can be referenced in a YANG RPC input. * + *

*

2. Defining an RPC to use the Context Type
+ * *

* To define an RPC to be routed based on the context type we need to add an input leaf element * that references the context type which will hold an instance identifier value to be * used to route the RPC. + * *

* The following snippet defines an RPC named show-item with 2 leaf elements * as input: item of type instance-identifier and description: @@ -149,11 +161,13 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * } * } * + * *

* We mark the item leaf with a context-reference statement that * references the example-context context type. RPC calls will then be routed * based on the instance identifier value contained in item. Only instance * identifiers that point to a foo/item node are valid as input. + * *

* The generated RPC Service interface for the module is: * @@ -162,15 +176,18 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * Future<RpcResult<Void>> showItem(ShowItemInput input); * } * + * *

* For constructing the RPC input, there are generated classes ShowItemInput and ShowItemInputBuilder. * *

3. Registering a routed RPC implementation
+ * *

* To register a routed implementation for the show-item RPC, we must use the * {@link #addRoutedRpcImplementation(Class, RpcService)} method. This * will return a {@link RoutedRpcRegistration} instance which can then be used to register / * unregister routed paths associated with the registered implementation. + * *

* The following snippet registers myImpl as the RPC implementation for an * item with key "foo": @@ -185,6 +202,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * // YANG-generated class for the example-context identity. * reg.registerPath(ExampleContext.class, path); * + * *

* It is also possible to register the same implementation for multiple paths: * @@ -203,13 +221,18 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * arguments in ShowItemInput, extract the InstanceIdentifier value of the item leaf and select * the implementation whose registered path matches the InstanceIdentifier value of the item leaf. * + *


*

Notes for RPC Implementations

* + *

*

RpcResult

+ * *

* The generated interfaces require implementors to return - * {@link java.util.concurrent.Future Future}<{@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult}<{RpcName}Output>> instances. + * {@link java.util.concurrent.Future Future}<{@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult} + * <{RpcName}Output>> instances. * + *

* Implementations should do processing of RPC calls asynchronously and update the * returned {@link java.util.concurrent.Future Future} instance when processing is complete. * However using {@link com.google.common.util.concurrent.Futures#immediateFuture(Object) Futures.immediateFuture} @@ -223,6 +246,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * or completely fail. This is intended to provide additional human readable information * for users of the API and to transfer warning / error information across the system * so it may be visible via other external APIs such as Restconf. + * *

* It is recommended to use the {@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult} * for conveying appropriate error information diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcContextIdentifier.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcContextIdentifier.java index b4bd6eb6a7..3bdb432eb8 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcContextIdentifier.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcContextIdentifier.java @@ -11,7 +11,7 @@ import org.opendaylight.yangtools.concepts.Immutable; import org.opendaylight.yangtools.yang.binding.BaseIdentity; import org.opendaylight.yangtools.yang.binding.RpcService; -public final class RpcContextIdentifier implements Immutable{ +public final class RpcContextIdentifier implements Immutable { public final Class rpcService; public final Class routingContext; @@ -29,11 +29,12 @@ public final class RpcContextIdentifier implements Immutable{ return routingContext; } - public static final RpcContextIdentifier contextForGlobalRpc(Class serviceType) { + public static RpcContextIdentifier contextForGlobalRpc(Class serviceType) { return new RpcContextIdentifier(serviceType, null); } - public static final RpcContextIdentifier contextFor(Class serviceType,Class routingContext) { + public static RpcContextIdentifier contextFor(Class serviceType, + Class routingContext) { return new RpcContextIdentifier(serviceType, routingContext); } @@ -41,31 +42,37 @@ public final class RpcContextIdentifier implements Immutable{ public int hashCode() { final int prime = 31; int result = 1; - result = prime * result + ((routingContext == null) ? 0 : routingContext.hashCode()); - result = prime * result + ((rpcService == null) ? 0 : rpcService.hashCode()); + result = prime * result + (routingContext == null ? 0 : routingContext.hashCode()); + result = prime * result + (rpcService == null ? 0 : rpcService.hashCode()); return result; } @Override public boolean equals(Object obj) { - if (this == obj) + if (this == obj) { return true; - if (obj == null) + } + if (obj == null) { return false; - if (getClass() != obj.getClass()) + } + if (getClass() != obj.getClass()) { return false; + } RpcContextIdentifier other = (RpcContextIdentifier) obj; if (routingContext == null) { - if (other.routingContext != null) + if (other.routingContext != null) { return false; - } else if (!routingContext.equals(other.routingContext)) + } + } else if (!routingContext.equals(other.routingContext)) { return false; + } if (rpcService == null) { - if (other.rpcService != null) + if (other.rpcService != null) { return false; - } else if (!rpcService.equals(other.rpcService)) + } + } else if (!rpcService.equals(other.rpcService)) { return false; + } return true; } - } diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcRoutingContext.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcRoutingContext.java index a886692e8c..4d42ff2bfc 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcRoutingContext.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/rpc/RpcRoutingContext.java @@ -13,5 +13,6 @@ import org.opendaylight.yangtools.yang.binding.RpcService; public interface RpcRoutingContext { Class getContextType(); + Class getServiceType(); }