From: Tom Pantelis Date: Mon, 5 Mar 2018 23:14:18 +0000 (-0500) Subject: Fix checkstyle violations in sal-common-api X-Git-Tag: release/fluorine~166 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=2e4ffc89f2d46950dbfdd8259f817ae4c336e3ef Fix checkstyle violations in sal-common-api Change-Id: I66ec5ec7c5066a5a95b7d40ca7e902d9f415f4ed Signed-off-by: Tom Pantelis --- diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/Entity.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/Entity.java index 2c79ff6803..c97fe51d36 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/Entity.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/Entity.java @@ -42,8 +42,8 @@ import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier; public final class Entity implements Serializable { private static final long serialVersionUID = 1L; - private static final QName ENTITY_QNAME = - org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.controller.md.sal.core.general.entity.rev150820.Entity.QNAME; + private static final QName ENTITY_QNAME = org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang + .controller.md.sal.core.general.entity.rev150820.Entity.QNAME; private static final QName ENTITY_NAME = QName.create(ENTITY_QNAME, "name"); private final String type; @@ -74,34 +74,32 @@ public final class Entity implements Serializable { } /** - * - * @return id of entity + * Returns the id of entity. */ @Nonnull - public YangInstanceIdentifier getId(){ + public YangInstanceIdentifier getId() { return id; } /** - * - * @return type of entity + * Returns the type of entity. */ @Nonnull - public String getType(){ + public String getType() { return type; } @Override - public boolean equals(Object o) { - if (this == o) { + public boolean equals(Object obj) { + if (this == obj) { return true; } - if (o == null || getClass() != o.getClass()) { + if (obj == null || getClass() != obj.getClass()) { return false; } - Entity entity = (Entity) o; + Entity entity = (Entity) obj; if (!id.equals(entity.id)) { return false; diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipService.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipService.java index 07c93e780c..8e34d80f47 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipService.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipService.java @@ -32,13 +32,14 @@ public interface EntityOwnershipService { * Registers a candidate for ownership of the given entity. Only one such request can be made per entity * per process. If multiple requests for registering a candidate for a given entity are received in the * current process a CandidateAlreadyRegisteredException will be thrown. + * *

* The registration is performed asynchronously and any registered {@link EntityOwnershipListener} is * notified of ownership status changes for the entity. * * @param entity the entity which the Candidate wants to own * @return a registration object that can be used to unregister the Candidate - * @throws org.opendaylight.controller.md.sal.common.api.clustering.CandidateAlreadyRegisteredException + * @throws CandidateAlreadyRegisteredException if the candidate is already registered */ EntityOwnershipCandidateRegistration registerCandidate(@Nonnull Entity entity) throws CandidateAlreadyRegisteredException; @@ -53,7 +54,8 @@ public interface EntityOwnershipService { * @param listener the listener that is interested in the entities * @return a registration object that can be used to unregister the Listener */ - EntityOwnershipListenerRegistration registerListener(@Nonnull String entityType, @Nonnull EntityOwnershipListener listener); + EntityOwnershipListenerRegistration registerListener(@Nonnull String entityType, + @Nonnull EntityOwnershipListener listener); /** * Gets the current ownership state information for an entity. @@ -64,9 +66,9 @@ public interface EntityOwnershipService { Optional getOwnershipState(@Nonnull Entity forEntity); /** - * Check if a local candidate is registered for the given entity + * Check if a local candidate is registered for the given entity. * - * @param entity + * @param entity the entity * @return true if a candidate was registered locally, false otherwise */ boolean isCandidateRegistered(@Nonnull Entity entity); diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCohort.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCohort.java index 9fb350b7c0..6f81e941c7 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCohort.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCohort.java @@ -7,14 +7,11 @@ */ package org.opendaylight.controller.md.sal.common.api.data; -import org.opendaylight.yangtools.concepts.Path; - import com.google.common.util.concurrent.ListenableFuture; +import org.opendaylight.yangtools.concepts.Path; /** - * - * Three phase Commit Cohort for subtree, which is - * uniquely associated with user submitted transcation. + * Three phase Commit Cohort for subtree, which is uniquely associated with user submitted transaction. * * @param

* Type of path (subtree identifier), which represents location in @@ -27,6 +24,7 @@ public interface AsyncConfigurationCommitCohort

, D> { /** * Initiates a pre-commit of associated request * + *

* Implementation MUST NOT do any blocking calls during this callback, all * pre-commit preparation SHOULD happen asynchronously and MUST result in * completing returned future object. @@ -40,9 +38,9 @@ public interface AsyncConfigurationCommitCohort

, D> { ListenableFuture preCommit(AsyncReadTransaction rebasedTransaction); /** - * * Initiates a commit phase of associated request * + *

* Implementation MUST NOT do any blocking calls during this callback, all * commit finalization SHOULD happen asynchronously and MUST result in * completing returned future object. @@ -53,9 +51,9 @@ public interface AsyncConfigurationCommitCohort

, D> { ListenableFuture commit(); /** - * * Initiates abort phase of associated request * + *

* Implementation MUST NOT do any blocking calls during this callback, all * commit finalization SHOULD happen asynchronously and MUST result in * completing returned future object. diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCoordinator.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCoordinator.java index 6d669ab9df..4cc608c56e 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCoordinator.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitCoordinator.java @@ -12,7 +12,7 @@ import org.opendaylight.yangtools.concepts.Path; /** * Three Phase Commit Coordinator with support of user-supplied commit cohorts - * which participates in three-phase commit protocols + * which participates in three-phase commit protocols. * * @param

* Type of path (subtree identifier), which represents location in @@ -23,7 +23,7 @@ import org.opendaylight.yangtools.concepts.Path; public interface AsyncConfigurationCommitCoordinator

, D> { /** - * Register configuration commit handler for particular subtree + * Register configuration commit handler for particular subtree. * * Configuration commit handler is invoked for all write transactions * which modifies subtree diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitHandler.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitHandler.java index b966589afd..4ad4680122 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitHandler.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncConfigurationCommitHandler.java @@ -7,13 +7,13 @@ */ package org.opendaylight.controller.md.sal.common.api.data; -import org.opendaylight.yangtools.concepts.Path; - import com.google.common.util.concurrent.CheckedFuture; +import org.opendaylight.yangtools.concepts.Path; /** - * User-supplied participant in three-phase commit of transaction for configuration data tree + * User-supplied participant in three-phase commit of transaction for configuration data tree. * + *

* Client-supplied implementation of commit handler for subtree, which * is responsible for processing CAN-COMMIT phase of three-phase commit protocol * and return CommitCohort, which provides access to additional transitions @@ -28,9 +28,9 @@ import com.google.common.util.concurrent.CheckedFuture; public interface AsyncConfigurationCommitHandler

, D> { /** - * * Requests a can commit phase * + *

* Implementations SHOULD NOT do any blocking operation during * processing this callback. * @@ -44,7 +44,8 @@ public interface AsyncConfigurationCommitHandler

, D> { *

@@ -63,9 +64,9 @@ public interface AsyncConfigurationCommitHandler

, D> { ConfigurationCommitRequest request); /** - * * Commit Request as was submitted by client code * + *

* Commit Request contains list view of created / updated / removed * path and read-only view of proposed client transaction, * which may be used to retrieve modified or referenced data. @@ -80,30 +81,29 @@ public interface AsyncConfigurationCommitHandler

, D> { interface ConfigurationCommitRequest

, D> { /** - * * Read-only transaction which provides access only to configuration * data tree as if submitted transaction successfully happened and * no other concurrent modifications happened between allocation * of client transactions and write of client transactions. * + *

* Implementations of Commit Handlers are REQUIRED to use this * read-only view to access any data from configuration data tree, * in order to capture them as preconditions for this transaction. * * @return Read-only transaction which provides access only to configuration - * data tree as if submitted transaction successfully happened + * data tree as if submitted transaction successfully happened */ AsyncReadTransaction getReadOnlyView(); /** - * * Returns iteration of paths, to data which was introduced by this transaction. * * @return Iteration of paths, which was introduced by this transaction. */ Iterable

getCreatedPaths(); + /** - * * Returns iteration of paths, to data which was updated by this transaction. * * @return Iteration of paths, which was updated by this transaction. @@ -111,7 +111,6 @@ public interface AsyncConfigurationCommitHandler

, D> { Iterable

getUpdatedPaths(); /** - * * Returns iteration of paths, to data which was removed by this transaction. * * @return Iteration of paths, which was removed by this transaction. diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java index 5283241517..6da0af4986 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java @@ -11,7 +11,6 @@ import org.opendaylight.yangtools.concepts.ListenerRegistration; import org.opendaylight.yangtools.concepts.Path; /** - * * Base interface that 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. * @@ -57,16 +56,15 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange AsyncDataTransactionFactory { /** - * * Scope of Data Change * *

* Represents scope of data change (addition, replacement, deletion). - * * The terminology for scope types is reused from LDAP. * *

Examples

* + *

* Following is an example model with comments describing what notifications * you would receive based on the scope you specify, when you are * registering for changes on container a. @@ -83,6 +81,7 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * id "b" // scope SUBTREE * * + *

* Following is an example model with comments describing what notifications * you would receive based on the scope you specify, when you are * registering for changes on list list (without specifying concrete item in @@ -112,12 +111,14 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange /** * Represent a change (addition,replacement,deletion) of the node or one of its direct * children. + * *

* Note that this is done in the binding independent data tree and so the behavior * might be counterintuitive when used with binding aware interfaces particularly * when it comes to lists. The list itself is a node in the binding independent tree, * which means that if you want to listen on new elements you must listen on the list itself * with the scope of {@link #ONE}. + * *

* As an example, in the below YANG snippet, listening on node with scope * {@link #ONE} would tell you if the node-connector list was created or deleted, @@ -140,6 +141,7 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * } * * + *

* This scope is superset of {@link #BASE}. * */ @@ -148,27 +150,19 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * Represents a change of the node or any of or any of its child nodes, * direct and nested. * + *

* This scope is superset of {@link #ONE} and {@link #BASE}. * */ SUBTREE } - /** - * {@inheritDoc} - */ @Override AsyncReadOnlyTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override AsyncReadWriteTransaction newReadWriteTransaction(); - /** - * {@inheritDoc} - */ @Override AsyncWriteTransaction newWriteOnlyTransaction(); @@ -176,16 +170,19 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * Registers a {@link AsyncDataChangeListener} 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 reached via the supplied path. + * *

* If path type P allows it, you may specify paths up to the leaf nodes * then it is possible to listen on leaf nodes. + * *

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

* If there is any preexisting data in data tree on path for which you are * registering, you will receive initial data change event, which will @@ -194,6 +191,7 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange *

* You are also able to specify the scope of the changes you want to be * notified. + * *

* Supported scopes are: *

* See {@link DataChangeScope} for examples. + * *

* This method returns a {@link ListenerRegistration} object. To * "unregister" your listener for changes call the "close" method on this * returned object. + * *

* You MUST call close when you no longer need to receive notifications * (such as during shutdown or for example if your bundle is shutting down). diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java index ac4a0ffc33..8d5e347b17 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java @@ -9,26 +9,26 @@ package org.opendaylight.controller.md.sal.common.api.data; import java.util.Map; import java.util.Set; - import org.opendaylight.yangtools.concepts.Immutable; import org.opendaylight.yangtools.concepts.Path; /** - * - * An event which contains a capture of changes in a data subtree + * An event which contains a capture of changes in a data subtree. * *

* Represents a notification indicating that some data at or under a particular * path has changed. The notification contains a capture of the changes in the data * subtree. This event is triggered by successful application of modifications * from a transaction on the global data tree. Use the - * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)} + * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, + * AsyncDataBroker.DataChangeScope)} * method to register a listener for data change events. * *

* A listener will only receive notifications for changes to data under the path * they register for. See - * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)} + * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, + * AsyncDataBroker.DataChangeScope)} * to learn more about registration scopes. * *

@@ -50,7 +50,8 @@ public interface AsyncDataChangeEvent

, D> extends Immutable { * Returns a map of paths and newly created objects, which were introduced by * this change into conceptual data tree, if no new objects were introduced * this map will be empty. - *

+ * + *

* This map contains all data tree nodes (and paths to them) which were created * and are in the scope of listener registration. The data tree nodes * contain their whole subtree with their current state. @@ -63,14 +64,17 @@ public interface AsyncDataChangeEvent

, D> extends Immutable { * Returns a map of paths and objects which were updated by this change in the * conceptual data tree if no existing objects were updated * this map will be empty. - *

+ * + *

* This map contains all data tree nodes (and paths to them) which were updated * and are in the scope of listener registration. The data tree nodes * contain their whole subtree with their current state. - *

+ * + *

* A Node is considered updated if it contents were replaced or one of its * children was created, removed or updated. - *

+ * + *

* Original state of the updated data tree nodes is in * {@link #getOriginalData()} stored with same path. * @@ -80,10 +84,12 @@ public interface AsyncDataChangeEvent

, D> extends Immutable { /** * Returns an immutable set of removed paths. - *

+ * + *

* This set contains the paths to the data tree nodes which are in the scope * of the listener registration that have been removed. - *

+ * + *

* Original state of the removed data tree nodes is in * {@link #getOriginalData()} stored with same path. * @@ -110,7 +116,8 @@ public interface AsyncDataChangeEvent

, D> extends Immutable { *

* The view is rooted at the point where the listener, to which the event is * being delivered, was registered. - *

+ * + *

* If listener used a wildcarded path (if supported by path type) during * registration for change listeners this method returns null, and original * state can be accessed only via {@link #getOriginalData()} @@ -124,10 +131,12 @@ public interface AsyncDataChangeEvent

, D> extends Immutable { /** * Returns an immutable stable view of data, which captures the state of data * store after the reported change. - *

+ * + *

* The view is rooted at the point where the listener, to which the event is * being delivered, was registered. - *

+ * + *

* If listener used a wildcarded path (if supported by path type) during * registration for change listeners this method returns null, and state * can be accessed only via {@link #getCreatedData()}, diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeListener.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeListener.java index a7a9fef07f..3b956d7f93 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeListener.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeListener.java @@ -8,7 +8,6 @@ package org.opendaylight.controller.md.sal.common.api.data; import java.util.EventListener; - import org.opendaylight.yangtools.concepts.Path; /** @@ -16,7 +15,8 @@ import org.opendaylight.yangtools.concepts.Path; * *

* User-supplied implementations of this listener interface MUST register via - * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)} + * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, + * AsyncDataBroker.DataChangeScope)} * in order to start receiving data change events, which capture state changes * in a subtree. * @@ -33,9 +33,9 @@ import org.opendaylight.yangtools.concepts.Path; @Deprecated public interface AsyncDataChangeListener

, D> extends EventListener { /** - * * Invoked when there is data change for the particular path, which was used to * register this listener. + * *

* This method may be also invoked during registration of the listener if * there is any preexisting data in the conceptual data tree for supplied path. diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java index a558b96b2d..22fa5ff9e4 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java @@ -48,7 +48,8 @@ import org.opendaylight.yangtools.concepts.Path; * implementations may optimize the transaction for reading if they know ahead * of time that you only need to read data - such as not keeping additional meta-data, * which may be required for write transactions. - *

+ * + *

* Implementation Note: This interface is not intended to be implemented * by users of MD-SAL, but only to be consumed by them. * @@ -64,9 +65,9 @@ import org.opendaylight.yangtools.concepts.Path; public interface AsyncDataTransactionFactory

, D> { /** - * Allocates a new read-only transaction which provides an immutable snapshot of - * the data tree. - *

+ * Allocates a new read-only transaction which provides an immutable snapshot of the data tree. + * + *

* The view of data tree is an immutable snapshot of current data tree state when * transaction was allocated. * @@ -107,6 +108,7 @@ public interface AsyncDataTransactionFactory

, D> { * used only by callers which are exclusive writers (exporters of data) * to the subtree they modify. This prevents optimistic * lock failures as described in {@link AsyncWriteTransaction#commit()}. + * *

* Exclusivity of writers to particular subtree SHOULD BE enforced by * external locking mechanism. diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadTransaction.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadTransaction.java index 053d6346a4..ae34213893 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadTransaction.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadTransaction.java @@ -10,7 +10,6 @@ package org.opendaylight.controller.md.sal.common.api.data; import org.opendaylight.yangtools.concepts.Path; /** - * * Marker interface for stateful read view of the data tree. * *

@@ -46,7 +45,8 @@ import org.opendaylight.yangtools.concepts.Path; * that action happened after other asynchronous action. Use of blocking call * {@link com.google.common.util.concurrent.ListenableFuture#get()} is discouraged for most * uses and you should use - * {@link com.google.common.util.concurrent.Futures#addCallback(com.google.common.util.concurrent.ListenableFuture, com.google.common.util.concurrent.FutureCallback)} + * {@link com.google.common.util.concurrent.Futures#addCallback(com.google.common.util.concurrent.ListenableFuture, + * com.google.common.util.concurrent.FutureCallback)} * or other functions from {@link com.google.common.util.concurrent.Futures} to * register more specific listeners. * diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadWriteTransaction.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadWriteTransaction.java index 16b4ed4fe2..1ebb5309e8 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadWriteTransaction.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncReadWriteTransaction.java @@ -40,6 +40,7 @@ import org.opendaylight.yangtools.concepts.Path; * *

Transaction local state

* + *

* Let assume initial state of data tree for PATH is A * . * @@ -56,6 +57,7 @@ import org.opendaylight.yangtools.concepts.Path; * tx1afterCommit.read(OPERATIONAL,PATH).get(); // returns Optional containing B * * + *

* As you could see read-write transaction provides capabilities as * {@link AsyncWriteTransaction} but also allows for reading proposed changes as * if they already happened. @@ -119,8 +121,8 @@ import org.opendaylight.yangtools.concepts.Path; * Note: examples contains blocking calls on future only to illustrate * that action happened after other asynchronous action. Use of blocking call * {@link com.google.common.util.concurrent.ListenableFuture#get()} is discouraged for most uses and you should - * use - * {@link com.google.common.util.concurrent.Futures#addCallback(com.google.common.util.concurrent.ListenableFuture, com.google.common.util.concurrent.FutureCallback)} + * use {@link com.google.common.util.concurrent.Futures#addCallback(com.google.common.util.concurrent.ListenableFuture, + * com.google.common.util.concurrent.FutureCallback)} * or other functions from {@link com.google.common.util.concurrent.Futures} to * register more specific listeners. * diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncTransaction.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncTransaction.java index 9855b2245c..2fe3760c9d 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncTransaction.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncTransaction.java @@ -12,14 +12,15 @@ import org.opendaylight.yangtools.concepts.Path; /** - * * A common parent for all transactions which operate on a conceptual data tree. * + *

* See derived transaction types for more concrete behavior: *

* * Implementation Note: This interface is not intended to be implemented @@ -33,6 +34,4 @@ public interface AsyncTransaction

,D> extends // @Override Object getIdentifier(); - - } diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java index effeabefae..f12cb88a18 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java @@ -7,13 +7,12 @@ */ package org.opendaylight.controller.md.sal.common.api.data; +import com.google.common.util.concurrent.CheckedFuture; +import com.google.common.util.concurrent.ListenableFuture; import org.opendaylight.controller.md.sal.common.api.TransactionStatus; import org.opendaylight.yangtools.concepts.Path; import org.opendaylight.yangtools.yang.common.RpcResult; -import com.google.common.util.concurrent.CheckedFuture; -import com.google.common.util.concurrent.ListenableFuture; - /** * Write transaction provides mutation capabilities for a data tree. * @@ -21,11 +20,13 @@ import com.google.common.util.concurrent.ListenableFuture; * Initial state of write transaction is a stable snapshot of the current data tree. * The state is captured when the transaction is created and its state and underlying * data tree are not affected by other concurrently running transactions. + * *

* Write transactions are isolated from other concurrent write transactions. All * writes are local to the transaction and represent only a proposal of state * change for the data tree and it is not visible to any other concurrently running * transaction. + * *

* Applications make changes to the local data tree in the transaction by via the * put, merge, and delete operations. @@ -34,6 +35,7 @@ import com.google.common.util.concurrent.ListenableFuture; * Stores a piece of data at a specified path. This acts as an add / replace * operation, which is to say that whole subtree will be replaced by the * specified data. + * *

* Performing the following put operations: * @@ -42,6 +44,7 @@ import com.google.common.util.concurrent.ListenableFuture; * 2) container { list [ b ] } * * + *

* will result in the following data being present: * * 

@@ -51,6 +54,7 @@ import com.google.common.util.concurrent.ListenableFuture;
  * Merges a piece of data with the existing data at a specified path. Any pre-existing data
  * which is not explicitly overwritten will be preserved. This means that if you store a container,
  * its child lists will be merged.
+ *
  * 

  * Performing the following merge operations:
  *
@@ -59,25 +63,30 @@ import com.google.common.util.concurrent.ListenableFuture;
  * 2) container { list [ b ] }
  *
* + *

* will result in the following data being present: * * 

  * container { list [ a, b ] }
  *
* + *

* This also means that storing the container will preserve any * augmentations which have been attached to it. * *

Delete operation

* Removes a piece of data from a specified path. + * *

* After applying changes to the local data tree, applications publish the changes proposed in the * transaction by calling {@link #submit} on the transaction. This seals the transaction * (preventing any further writes using this transaction) and submits it to be * processed and applied to global conceptual data tree. + * *

* The transaction commit may fail due to a concurrent transaction modifying and committing data in * an incompatible way. See {@link #submit} for more concrete commit failure examples. + * *

* Implementation Note: This interface is not intended to be implemented * by users of MD-SAL, but only to be consumed by them. @@ -92,19 +101,21 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa /** * Cancels the transaction. * + *

* Transactions can only be cancelled if it's status is * {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED} * + *

* Invoking cancel() on {@link TransactionStatus#FAILED} or * {@link TransactionStatus#CANCELED} will have no effect, and transaction * is considered cancelled. * + *

* Invoking cancel() on finished transaction (future returned by {@link #submit()} * already completed with {@link TransactionStatus#COMMITED}) will always * fail (return false). * - * @return false if the task could not be cancelled, - * typically because it has already completed normally; + * @return false if the task could not be cancelled, typically because it has already completed normally * true otherwise * */ @@ -126,23 +137,26 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa /** * 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. See example usage below. + * *

* This call logically seals the transaction, which prevents the client from * further changing data tree using this transaction. Any subsequent calls to * {@link #delete(LogicalDatastoreType, Path)} will fail with * {@link IllegalStateException}. * + *

* The transaction is marked as {@link TransactionStatus#SUBMITED} and * enqueued into the data store back-end for processing. * *

* Whether or not the commit is successful is determined by versioning * of the data tree and validation of registered commit participants - * ({@link AsyncConfigurationCommitHandler}) - * if the transaction changes the data tree. + * ({@link AsyncConfigurationCommitHandler}) if the transaction changes the data tree. + * *

* The effects of a successful commit of data depends on data change listeners * ({@link AsyncDataChangeListener}) and commit participants @@ -179,6 +193,7 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa * doWrite( 2 ); * *

Failure scenarios

+ * *

* Transaction may fail because of multiple reasons, such as *