From: janab Date: Wed, 7 Sep 2016 17:39:51 +0000 (-0700) Subject: checkStyleViolationSeverity=error implemented for mdsal-binding-api module X-Git-Tag: release/carbon~175 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=104afbbc04792df68ee001c14fb02171d640f889;hp=703b1cac5f0bdd429dcb64809b7cd599e973877f;p=mdsal.git checkStyleViolationSeverity=error implemented for mdsal-binding-api module Code review comments are implemented. Change-Id: I925d71befa5806db4e7522c8009f5b125564adfe Signed-off-by: Brinda Jana --- diff --git a/binding/mdsal-binding-api/pom.xml b/binding/mdsal-binding-api/pom.xml index a108bbef48..f05f1e9a7d 100644 --- a/binding/mdsal-binding-api/pom.xml +++ b/binding/mdsal-binding-api/pom.xml @@ -60,6 +60,18 @@ test + + + + org.apache.maven.plugins + maven-checkstyle-plugin + + checkstyle.violationSeverity=error + + + + + scm:git:http://git.opendaylight.org/gerrit/controller.git scm:git:ssh://git.opendaylight.org:29418/controller.git diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingService.java index 3e83600e77..ed69c1dc4f 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingService.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingService.java @@ -9,9 +9,9 @@ package org.opendaylight.mdsal.binding.api; /** - * * 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 diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingTransactionChain.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingTransactionChain.java index 25809b40a3..bf1219cdd4 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingTransactionChain.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/BindingTransactionChain.java @@ -14,6 +14,7 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; /** * A chain of transactions. + * *

* For more information about transaction chaining and transaction chains * see {@link TransactionChain}. @@ -21,16 +22,12 @@ 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 ReadTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override WriteTransaction newWriteOnlyTransaction(); } diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/CursorAwareWriteTransaction.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/CursorAwareWriteTransaction.java index 839c19cd95..b47e3d46c7 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/CursorAwareWriteTransaction.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/CursorAwareWriteTransaction.java @@ -23,6 +23,7 @@ public interface CursorAwareWriteTransaction extends DataTreeCursorProvider { * Create a {@link DataTreeWriteCursor} anchored at the specified path. * There can only be one cursor open at a time. * + *

* @param path Path at which the cursor is to be anchored * @return write cursor at the desired location. * @throws IllegalStateException when there's an open cursor, or this transaction is closed already. @@ -34,11 +35,14 @@ public interface CursorAwareWriteTransaction extends DataTreeCursorProvider { /** * Cancels the transaction. * + *

* Transactions can only be cancelled if it was not yet submited. * + *

* Invoking cancel() on failed or already canceled will have no effect, and transaction is * considered cancelled. * + *

* Invoking cancel() on finished transaction (future returned by {@link #submit()} already * successfully completed) will always fail (return false). * @@ -51,15 +55,18 @@ public interface CursorAwareWriteTransaction extends DataTreeCursorProvider { /** * Submits this transaction to be asynchronously applied to update the logical data tree. The * returned CheckedFuture conveys the result of applying the data changes. + * *

* Note: It is strongly recommended to process the CheckedFuture result in an * asynchronous manner rather than using the blocking get() method. * + *

* This call logically seals the transaction, which prevents the client from further changing * data tree using this transaction's cursor. Any subsequent calls to * createCursorCursor(DOMDataTreeIdentifier * or any of the cursor's methods will fail with {@link IllegalStateException}. * + *

* The transaction is marked as submitted and enqueued into the shard back-end for * processing. */ diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataBroker.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataBroker.java index 2394ed6b86..c43889c0c8 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataBroker.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataBroker.java @@ -8,17 +8,15 @@ package org.opendaylight.mdsal.binding.api; import org.opendaylight.mdsal.common.api.AsyncDataBroker; -import org.opendaylight.mdsal.common.api.LogicalDatastoreType; import org.opendaylight.mdsal.common.api.TransactionChainFactory; import org.opendaylight.mdsal.common.api.TransactionChainListener; - -import org.opendaylight.yangtools.concepts.ListenerRegistration; import org.opendaylight.yangtools.yang.binding.DataObject; 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}. * @@ -26,22 +24,15 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; * @see TransactionChainFactory */ public interface DataBroker extends AsyncDataBroker, DataObject>, - TransactionChainFactory, DataObject>, TransactionFactory, BindingService, DataTreeChangeService { - /** - * {@inheritDoc} - */ + TransactionChainFactory, DataObject>, TransactionFactory, BindingService, + DataTreeChangeService { + @Override ReadTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override WriteTransaction newWriteOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override BindingTransactionChain createTransactionChain(TransactionChainListener listener); } diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataObjectModification.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataObjectModification.java index 26e9f40c1c..fbd90eac20 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataObjectModification.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataObjectModification.java @@ -21,12 +21,15 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument; /** * Modified Data Object. * + *

* Represents modification of Data Object - * . + * + *

* @param Type of modified object * */ -public interface DataObjectModification extends org.opendaylight.yangtools.concepts.Identifiable { +public interface DataObjectModification extends + org.opendaylight.yangtools.concepts.Identifiable { /** * Represents type of modification which has occured. @@ -34,19 +37,16 @@ public interface DataObjectModification extends org.openda */ enum ModificationType { /** - * * Child node (direct or indirect) was modified. * */ SUBTREE_MODIFIED, /** - * * Node was explicitly created / overwritten. * */ WRITE, /** - * * Node was deleted. * */ @@ -64,8 +64,7 @@ public interface DataObjectModification extends org.openda @Nonnull Class getDataType(); /** - * - * Returns type of modification + * Returns type of modification. * * @return type Type of performed modification. */ @@ -75,7 +74,6 @@ public interface DataObjectModification extends org.openda * Returns before-state of top level container. Implementations are encouraged, but not required * to provide this state. * - * * @return State of object before modification. Null if subtree was not present, or the * implementation cannot provide the state. */ @@ -103,12 +101,14 @@ public interface DataObjectModification extends org.openda * @throws IllegalArgumentException If supplied {@code childType} class is not valid child according * to generated model. */ - > Collection> getModifiedChildren(@Nonnull Class childType); + > Collection> getModifiedChildren( + @Nonnull Class childType); /** * 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 @@ -116,12 +116,14 @@ 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. * + *

* For accessing all modified list items consider iterating over {@link #getModifiedChildren()}. * * @param augmentation Type of augmentation - must be only container @@ -129,7 +131,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); /** @@ -141,8 +144,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 diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeListener.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeListener.java index 1c28e8705f..2dc28988a1 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeListener.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeListener.java @@ -33,6 +33,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/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java index 50d20c993f..aae09b4886 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java @@ -19,14 +19,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 @@ -36,6 +38,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 @@ -50,5 +53,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); } \ No newline at end of file diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohort.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohort.java index 44db3af9cd..5384edaf7a 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohort.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohort.java @@ -15,8 +15,6 @@ import org.opendaylight.mdsal.common.api.PostCanCommitStep; import org.opendaylight.yangtools.yang.binding.DataObject; /** - * ** - * * Commit cohort participating in commit of data modification, which can validate data tree * modifications, with option to reject supplied modification, and with callbacks describing state * of commit. @@ -26,20 +24,22 @@ import org.opendaylight.yangtools.yang.binding.DataObject; * {@link DataTreeCommitCohort}s are hooked up into commit of data tree changes and MAY * negatively affect performance of data broker / store. * + *

* Implementations of this interface are discouraged, unless you really need ability to veto data * tree changes, or to provide external state change in sync with visibility of commited data. * - * *

Implementation requirements

* *

Correctness assumptions

Implementation SHOULD use only provided * {@link DataTreeModification} for validation purposes. * + *

* Use of any other external mutable state is discouraged, implementation MUST NOT use any * transaction related APIs on same data broker / data store instance during invocation of * callbacks, except ones provided as argument. Note that this MAY BE enforced by some * implementations of {@link DataBroker} or Commit coordinator * + *

* Note that this may be enforced by some implementations of {@link DataTreeCommitCohortRegistry} * and such calls may fail. * @@ -48,18 +48,20 @@ import org.opendaylight.yangtools.yang.binding.DataObject; * {@link PostCanCommitStep#preCommit()} and * {@link org.opendaylight.mdsal.common.api.PostPreCommitStep#commit()} callback was invoked. * - * *

Usage patterns

* *

Data Tree Validator

* + *

* Validator is implementation, which only validates {@link DataTreeModification} and does not * retain any state derived from edited data - does not care if {@link DataTreeModification} was * rejected afterwards or transaction was cancelled. * + *

* Implementation may opt-out from receiving {@code preCommit()}, {@code commit()}, {@code abort()} * callbacks by returning {@link PostCanCommitStep#NOOP}. * + *

* TODO: Provide example and describe more usage patterns * * @author Tony Tkacik <ttkacik@cisco.com> diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohortRegistry.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohortRegistry.java index da73700553..ec30a938e7 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohortRegistry.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeCommitCohortRegistry.java @@ -12,9 +12,9 @@ import org.opendaylight.yangtools.concepts.ObjectRegistration; import org.opendaylight.yangtools.yang.binding.DataObject; /** - * * Commit Cohort registry. * + *

* See {@link DataTreeCommitCohort} for more details. * * @author Tony Tkacik <ttkacik@cisco.com> diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifier.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifier.java index 0ae385641f..52e2317cb3 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifier.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/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; diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeProducer.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeProducer.java index 0520b40e21..09ab7693b7 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeProducer.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeProducer.java @@ -16,19 +16,23 @@ import javax.annotation.Nonnull; * either submitted or cancelled before another one can be open. Once a transaction is submitted, it * will proceed to be committed asynchronously. * + *

* Each instance has an upper bound on the number of transactions which can be in-flight, once that * capacity is exceeded, an attempt to create a new transaction will block until some transactions * complete. * + *

* Each {@link DataTreeProducer} can be in two logical states, bound and unbound, which define the * lifecycle rules for when is it legal to create and submit transactions in relationship with * {@link DataTreeListener} callbacks. * + *

* When a producer is first created, it is unbound. In this state the producer can be accessed by * any application thread to allocate or submit transactions, as long as the 'single open * transaction' rule is maintained. The producer and any transaction object MUST NOT be accessed, * directly or indirectly, from a {@link DataTreeListener} callback. * + *

* When a producer is referenced in a call to * {@link DataTreeService#registerListener(DataTreeListener, java.util.Collection, boolean, java.util.Collection)} * , an attempt will be made to bind the producer to the specified {@link DataTreeListener}. Such an @@ -59,17 +63,20 @@ public interface DataTreeProducer extends DataTreeProducerFactory, AutoCloseable CursorAwareWriteTransaction createTransaction(boolean isolated); /** - * {@inheritDoc} + * {@inheritDoc}. * + *

* When invoked on a {@link DataTreeProducer}, this method has additional restrictions. There * may not be an open transaction from this producer. The method needs to be invoked in * appropriate context, e.g. bound or unbound. * + *

* Specified subtrees must be accessible by this producer. Accessible means they are a subset of * the subtrees specified when the producer is instantiated. The set is further reduced as child * producers are instantiated -- if you create a producer for /a and then a child for /a/b, /a/b * is not accessible from the first producer. * + *

* Once this method returns successfully, this (parent) producer loses the ability to access the * specified paths until the resulting (child) producer is shut down. * @@ -86,7 +93,7 @@ public interface DataTreeProducer extends DataTreeProducerFactory, AutoCloseable DataTreeProducer createProducer(@Nonnull Collection> subtrees); /** - * {@inheritDoc} + * {@inheritDoc}. * * @throws DataTreeProducerBusyException when there is an open transaction. */ diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeService.java index de578a1439..c2db154647 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeService.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeService.java @@ -16,10 +16,12 @@ import org.opendaylight.yangtools.concepts.ListenerRegistration; * tree are split into data producers and consumers (listeners). Each of them operate on a set of * subtrees, which need to be declared at instantiation time. * + *

* Returned instances are not thread-safe and expected to be used by a single thread at a time. * Furthermore, producers may not be accessed from consumer callbacks unless they were specified * when the listener is registered. * + *

* The service maintains a loop-free topology of producers and consumers. What this means is that a * consumer is not allowed to access a producer, which affects any of the subtrees it is subscribed * to. This restriction is in place to ensure the system does not go into a feedback loop, where it @@ -34,12 +36,14 @@ public interface DataTreeService extends DataTreeProducerFactory, BindingService * a smaller number of them will be reported, possibly hiding some data transitions (like * flaps). * + *

* If the listener wants to write into any producer, that producer has to be mentioned in the * call to this method. Those producers will be bound exclusively to the registration, so that * accessing them outside of this listener's callback will trigger an error. Any producers * mentioned must be idle, e.g. they may not have an open transaction at the time this method is * invoked. * + *

* Each listener instance can be registered at most once. Implementations of this interface have * to guarantee that the listener's methods will not be invoked concurrently from multiple * threads. diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeWriteCursor.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeWriteCursor.java index 653c6a4e73..a2e7b5b4d4 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeWriteCursor.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeWriteCursor.java @@ -13,8 +13,9 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument; import org.opendaylight.yangtools.yang.data.api.schema.tree.BackendFailedException; /** - * {@inheritDoc} + * {@inheritDoc}. * + *

* In addition this cursor also provides write operations(delete, merge, write). */ public interface DataTreeWriteCursor extends DataTreeCursor { diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/MountPoint.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/MountPoint.java index d05b13f2f1..8e461ad620 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/MountPoint.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/MountPoint.java @@ -11,7 +11,7 @@ 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/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationPublishService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationPublishService.java index e6c527d03c..1541008f3c 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationPublishService.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/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 @@ -55,6 +57,7 @@ public interface NotificationPublishService extends BindingService { * notification, but delivery to the 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. diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationRejectedException.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationRejectedException.java index b409ca67ea..2517e87f8a 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationRejectedException.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationRejectedException.java @@ -8,13 +8,11 @@ package org.opendaylight.mdsal.binding.api; /** - *

* This exception indicates that given notification can not be processed by corresponding mechanism. * More info can be provided in message. - *

+ * *

* Expected use: {@link NotificationPublishService} - *

*/ public class NotificationRejectedException extends Exception { private static final long serialVersionUID = 1L; diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationService.java index 34f88a1b87..42729f6512 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationService.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationService.java @@ -13,6 +13,7 @@ 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 @@ -23,54 +24,59 @@ import org.opendaylight.yangtools.yang.binding.NotificationListener; * method. * * Dispatch Listener Example + * *

* Lets assume we have following YANG model: * * 

  * module example {
  *      ...
- * 
+ *
  *      notification start {
  *          ...
  *      }
- * 
+ *
  *      notification stop {
  *           ...
  *      }
  * }
  *
* + *

* The generated interface will be: - * + * * 

  * public interface ExampleListener extends NotificationListener {
  *     void onStart(Start notification);
- * 
+ *
  *     void onStop(Stop notification);
  * }
  *
- * + * + *

* The following defines an implementation of the generated interface: - * + * * 

  * public class MyExampleListener implements ExampleListener {
  *     public void onStart(Start notification) {
  *         // do something
  *     }
- * 
+ *
  *     public void onStop(Stop notification) {
  *         // do something
  *     }
  * }
  *
- * + * + *

* The implementation is registered as follows: - * + * * 

  * MyExampleListener listener = new MyExampleListener();
  * ListenerRegistration<NotificationListener> reg = service.registerNotificationListener(listener);
  *
- * + * + *

* The onStart method will be invoked when someone publishes a Start * notification and the onStop method will be invoked when someone publishes a * Stop notification. @@ -81,6 +87,7 @@ public interface NotificationService extends BindingService { * {@link NotificationListener}. The listener is registered for all notifications present in * the implemented interface. * + *

* @param listener the listener implementation that will receive notifications. * @return a {@link ListenerRegistration} instance that should be used to unregister the listener * by invoking the {@link ListenerRegistration#close()} method when no longer needed. diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java index ee40cdd760..9a4c682b31 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java @@ -7,17 +7,18 @@ */ package org.opendaylight.mdsal.binding.api; +import com.google.common.base.Optional; +import com.google.common.util.concurrent.CheckedFuture; import org.opendaylight.mdsal.common.api.AsyncReadTransaction; import org.opendaylight.mdsal.common.api.LogicalDatastoreType; import org.opendaylight.mdsal.common.api.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 a stateful read-only view of the data tree. + * *

* For more information on usage and examples, please see the documentation in * {@link org.opendaylight.mdsal.common.api.AsyncReadTransaction}. @@ -26,6 +27,7 @@ public interface ReadTransaction extends AsyncReadTransaction * If the target is a subtree, then the whole subtree is read (and will be * accessible from the returned data object). diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/RpcConsumerRegistry.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/RpcConsumerRegistry.java index 755b88c976..d2e0e985fe 100644 --- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/RpcConsumerRegistry.java +++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/RpcConsumerRegistry.java @@ -14,6 +14,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 RpcProviderService}. * @@ -25,8 +26,8 @@ public interface RpcConsumerRegistry extends BindingService { *

* The returned instance is not an actual implementation of the RPC service interface, but a * proxy implementation of the interface that forwards to an actual implementation, if any. - *

* + *

* The following describes the behavior of the proxy when invoking RPC methods: *

    *
  • If an actual implementation is registered with the MD-SAL, all invocations are forwarded @@ -38,6 +39,7 @@ public interface RpcConsumerRegistry extends BindingService { *
* * The returned proxy is automatically updated with the most recent registered implementation. + * *

* The generated RPC method APIs require implementors to return a * {@link java.util.concurrent.Future Future} instance that wraps the @@ -46,13 +48,14 @@ public interface RpcConsumerRegistry extends BindingService { * {@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)} - * to listen for Rpc Result. This will asynchronously listen for future result in executor and - * will not block current thread. + * {@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. * * 

      *   final Future<RpcResult<SomeRpcOutput>> future = someRpcService.someRpc( ... );
-     *   Futures.addCallback(JdkFutureAdapters.listenInThreadPool(future), new FutureCallback<RpcResult<SomeRpcOutput>>() {
+     *   Futures.addCallback(JdkFutureAdapters.listenInThreadPool(future), new FutureCallback<RpcResult<
+     *   SomeRpcOutput>>() {
      *
      *       public void onSuccess(RpcResult<SomeRpcOutput> result) {
      *          // process result ...
diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/TransactionFactory.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/TransactionFactory.java
index 32ad78d990..4d6adcde4d 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/TransactionFactory.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/TransactionFactory.java
@@ -13,7 +13,7 @@ import org.opendaylight.mdsal.common.api.AsyncDataTransactionFactory;
 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
     ReadTransaction newReadOnlyTransaction();
diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
index 195610a8ad..d9d029a097 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteTransaction.java
@@ -15,6 +15,7 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
 
 /**
  * A transaction that provides mutation capabilities on a data tree.
+ *
  * 

  * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
  */
@@ -23,10 +24,12 @@ public interface WriteTransaction extends AsyncWriteTransaction
+     *
+     * 

      * This method does not automatically create missing parent nodes. It is equivalent to invoking
      * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
      * with createMissingParents set to false.
+     *
      * 

      * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
      * 

@@ -49,14 +52,17 @@ public interface WriteTransaction extends AsyncWriteTransaction
      * For more information on usage and examples, please see the documentation
      * in {@link AsyncWriteTransaction}.
+     *
      * 

      * If you need to make sure that a parent object exists but you do not want
      * modify its pre-existing state by using put, consider using {@link #merge}
      * instead.
      *
+     * 

      * Note: Using createMissingParents with value true, may
      * introduce garbage in data store, or recreate nodes, which were deleted by
      * previous transaction.
@@ -80,12 +86,16 @@ public interface WriteTransaction extends AsyncWriteTransaction
      * This method does not automatically create missing parent nodes. It is equivalent to invoking
      * {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
      * with createMissingParents set to false.
+     *
      * 

-     * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
+     * For more information on usage and examples, please see the documentation in
+     * {@link AsyncWriteTransaction}.
+     *
      *

      * If you require an explicit replace operation, use {@link #put} instead.
      * @param store
@@ -103,9 +113,11 @@ public interface WriteTransaction extends AsyncWriteTransaction
      * For more information on usage and examples, please see the documentation
      * in {@link AsyncWriteTransaction}.
+     *
      * 

      * If you require an explicit replace operation, use {@link #put} instead.
      *
diff --git a/binding/mdsal-binding-api/src/test/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifierTest.java b/binding/mdsal-binding-api/src/test/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifierTest.java
index 7df98fabcb..6e22e98029 100644
--- a/binding/mdsal-binding-api/src/test/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifierTest.java
+++ b/binding/mdsal-binding-api/src/test/java/org/opendaylight/mdsal/binding/api/DataTreeIdentifierTest.java
@@ -40,8 +40,8 @@ public class DataTreeIdentifierTest {
 
     @Test
     public void hashCodeTest() {
-        assertEquals("hashCode", TEST_IDENTIFIER1.hashCode(), DataTreeIdentifier.create(LogicalDatastoreType.OPERATIONAL,
-                InstanceIdentifier.create(TestDataObject1.class)).hashCode());
+        assertEquals("hashCode", TEST_IDENTIFIER1.hashCode(), DataTreeIdentifier.create(
+                LogicalDatastoreType.OPERATIONAL, InstanceIdentifier.create(TestDataObject1.class)).hashCode());
         assertNotEquals("hashCode", TEST_IDENTIFIER1.hashCode(), TEST_IDENTIFIER2.hashCode());
     }