From 4c84760ea597cf452a0cd904be7c4a5de5f63ec9 Mon Sep 17 00:00:00 2001 From: tpantelis Date: Sat, 12 Jul 2014 06:53:46 -0400 Subject: [PATCH 1/1] Change put/merge methods to be type-safe in WriteTransaction Removed declaration of put/merge methods from the common AsyncWriteTransaction interface. Defined put/merge methods in the derived Binding and DOM interfaces. The Binding methods were made type-safe. Javadoc usage/examples for the methods was put into the AsyncWriteTransaction class docs and is linked to by the derived interfaces. This change is source-code compatible - no client code needs to change (unless a client actually is incompatible path and data). Change-Id: I779f6477f1c98e299c5d559043da612be97bfbe6 Signed-off-by: tpantelis --- .../md/sal/binding/api/WriteTransaction.java | 42 +++++- .../impl/BindingDataWriteTransactionImpl.java | 6 +- .../api/data/AsyncWriteTransaction.java | 129 +++++++----------- .../sal/dom/api/DOMDataWriteTransaction.java | 45 ++++++ 4 files changed, 141 insertions(+), 81 deletions(-) diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/WriteTransaction.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/WriteTransaction.java index 0cef81d359..044a700d84 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/WriteTransaction.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/md/sal/binding/api/WriteTransaction.java @@ -18,8 +18,46 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier; * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}. */ public interface WriteTransaction extends AsyncWriteTransaction, DataObject> { - @Override - void put(LogicalDatastoreType store, InstanceIdentifier path, DataObject data); + + /** + * Stores a piece of data at the specified path. This acts as an add / replace + * operation, which is to say that whole subtree will be replaced by the specified data. + *

+ * 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. + * + * @param store + * the logical data store which should be modified + * @param path + * the data object path + * @param data + * the data object to be written to the specified path + * @throws IllegalStateException + * if the transaction has already been submitted + */ + void put(LogicalDatastoreType store, InstanceIdentifier path, T data); + + /** + * 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. + *

+ * 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 + * the logical data store which should be modified + * @param path + * the data object path + * @param data + * the data object to be merged to the specified path + * @throws IllegalStateException + * if the transaction has already been submitted + */ + void merge(LogicalDatastoreType store, InstanceIdentifier path, T data); @Override void delete(LogicalDatastoreType store, InstanceIdentifier path); diff --git a/opendaylight/md-sal/sal-binding-broker/src/main/java/org/opendaylight/controller/md/sal/binding/impl/BindingDataWriteTransactionImpl.java b/opendaylight/md-sal/sal-binding-broker/src/main/java/org/opendaylight/controller/md/sal/binding/impl/BindingDataWriteTransactionImpl.java index 7e622baac3..29790fb60a 100644 --- a/opendaylight/md-sal/sal-binding-broker/src/main/java/org/opendaylight/controller/md/sal/binding/impl/BindingDataWriteTransactionImpl.java +++ b/opendaylight/md-sal/sal-binding-broker/src/main/java/org/opendaylight/controller/md/sal/binding/impl/BindingDataWriteTransactionImpl.java @@ -27,12 +27,14 @@ class BindingDataWriteTransactionImpl extends } @Override - public void put(final LogicalDatastoreType store, final InstanceIdentifier path, final DataObject data) { + public void put(final LogicalDatastoreType store, final InstanceIdentifier path, + final T data) { doPut(store, path, data); } @Override - public void merge(final LogicalDatastoreType store, final InstanceIdentifier path, final DataObject data) { + public void merge(final LogicalDatastoreType store, final InstanceIdentifier path, + final T data) { doMerge(store, path, data); } 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 9aaa77ca61..e47b54a0a1 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 @@ -27,15 +27,57 @@ import com.google.common.util.concurrent.ListenableFuture; * change for the data tree and it is not visible to any other concurrently running * transaction. *

- * Applications publish the changes proposed in the transaction by calling {@link #commit} - * on the transaction. This seals the transaction + * Applications make changes to the local data tree in the transaction by via the + * put, merge, and delete operations. + * + *

Put operation

+ * 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: + * + * 

+ * 1) container { list [ a ] }
+ * 2) container { list [ b ] }
+ *
+ * + * will result in the following data being present: + * + * 
+ * container { list [ b ] }
+ *
+ *

Merge operation

+ * 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: + * + * 

+ * 1) container { list [ a ] }
+ * 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 #commit()} for more concrete commit failure examples. - * - * + * 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. @@ -57,7 +99,7 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa * {@link TransactionStatus#CANCELED} will have no effect, and transaction * is considered cancelled. * - * Invoking cancel() on finished transaction (future returned by {@link #commit()} + * Invoking cancel() on finished transaction (future returned by {@link #submit()} * already completed with {@link TransactionStatus#COMMITED}) will always * fail (return false). * @@ -69,74 +111,7 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa boolean cancel(); /** - * Store a piece of data at specified path. This acts as an add / replace - * operation, which is to say that whole subtree will be replaced by - * specified path. Performing the following put operations: - * - * 

-     * 1) container { list [ a ] }
-     * 2) container { list [ b ] }
-     *
- * - * will result in the following data being present: - * - * 
-     * container { list [ b ] }
-     *
- * - * - * If you need to make sure that a parent object exists, but you do not want modify - * its preexisting state by using put, consider using - * {@link #merge(LogicalDatastoreType, Path, Object)} - * - * @param store - * Logical data store which should be modified - * @param path - * Data object path - * @param data - * Data object to be written to specified path - * @throws IllegalStateException - * if the transaction is no longer {@link TransactionStatus#NEW} - */ - void put(LogicalDatastoreType store, P path, D data); - - /** - * Store a piece of data at the specified path. This acts as a merge operation, - * which is to say that 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: - * - * 
-     * 1) container { list [ a ] }
-     * 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. - *

- * If you require an explicit replace operation, use - * {@link #put(LogicalDatastoreType, Path, Object)} instead. - * - * @param store - * Logical data store which should be modified - * @param path - * Data object path - * @param data - * Data object to be written to specified path - * @throws IllegalStateException - * if the transaction is no longer {@link TransactionStatus#NEW} - */ - void merge(LogicalDatastoreType store, P path, D data); - - /** - * Remove a piece of data from specified path. This operation does not fail + * Removes a piece of data from specified path. This operation does not fail * if the specified path does not exist. * * @param store @@ -184,7 +159,7 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa * InstanceIdentifier path = ...; * writeTx.put( LogicalDatastoreType.OPERATIONAL, path, data ); * - * Futures.addCallback( writeTx.commit(), new FutureCallback() { + * Futures.addCallback( writeTx.submit(), new FutureCallback() { * public void onSuccess( Void result ) { * // succeeded * } @@ -312,8 +287,8 @@ public interface AsyncWriteTransaction

, D> extends AsyncTransa * txA.put(CONFIGURATION, PATH, A); // writes to PATH value A * txB.put(CONFIGURATION, PATH, B) // writes to PATH value B * - * ListenableFuture futureA = txA.commit(); // transaction A is sealed and committed - * ListenebleFuture futureB = txB.commit(); // transaction B is sealed and committed + * ListenableFuture futureA = txA.submit(); // transaction A is sealed and submitted + * ListenebleFuture futureB = txB.submit(); // transaction B is sealed and submitted * * * Commit of transaction A will be processed asynchronously and data tree diff --git a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMDataWriteTransaction.java b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMDataWriteTransaction.java index 9415973de5..6a8977154c 100644 --- a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMDataWriteTransaction.java +++ b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMDataWriteTransaction.java @@ -8,9 +8,54 @@ package org.opendaylight.controller.md.sal.dom.api; import org.opendaylight.controller.md.sal.common.api.data.AsyncWriteTransaction; +import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType; import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier; import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; +/** + * A transaction that provides mutation capabilities on a data tree. + *

+ * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}. + */ public interface DOMDataWriteTransaction extends AsyncWriteTransaction> { + /** + * Stores a piece of data at the specified path. This acts as an add / replace + * operation, which is to say that whole subtree will be replaced by the specified data. + *

+ * 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. + * + * @param store + * the logical data store which should be modified + * @param path + * the data object path + * @param data + * the data object to be written to the specified path + * @throws IllegalStateException + * if the transaction has already been submitted + */ + void put(LogicalDatastoreType store, InstanceIdentifier path, NormalizedNode data); + + /** + * 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. + *

+ * 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 + * the logical data store which should be modified + * @param path + * the data object path + * @param data + * the data object to be merged to the specified path + * @throws IllegalStateException + * if the transaction has already been submitted + */ + void merge(LogicalDatastoreType store, InstanceIdentifier path, NormalizedNode data); } -- 2.36.6