Deprecate WriteTransaction.mergeParentStructure*()

These methods hark to our dark past. Most of their uses should be
superfluous with current semantics and they paper over important
lifecycle management questions. Furthermore there are corner cases for
which they cannot be made to work simply because of the semantics
involved.

Deprecate these method so their users are pointed out and can be
gradually migrated.

Change-Id: Ib85d42a9514b33fcdb1efb1ddb273b4c6ee0e554
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteOperations.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteOperations.java
index 72855e2cf0cc326ddbcba7fc0fa0b30674226398..bd695d365961d06954186b51be07944bc519c3ee 100644 (file)
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteOperations.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteOperations.java
@@ -7,7 +7,6 @@
  */
 package org.opendaylight.mdsal.binding.api;
 
-import com.google.common.annotations.Beta;
 import org.eclipse.jdt.annotation.NonNull;
 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
 import org.opendaylight.mdsal.common.api.TransactionDatastoreMismatchException;
@@ -59,9 +58,24 @@ public interface WriteOperations {
      * @throws IllegalStateException if the transaction has already been submitted
      * @throws NullPointerException if any of the arguments is {@code null}
      * @throws TransactionDatastoreMismatchException if this transaction is already bound to a different data store
+     * @deprecated Use of this method is a manifestation of bad lifecycle management: it attempts to create data tree
+     *             parent nodes which may have semantic meaning without assigning responsibility. The datastore handles
+     *             all the cases which do not attach semantics, such as {@code container}s without {@code presence},
+     *             {@code augmentation} and {@code list} encapsulation.
+     *             This method does not work in the general case, where there are:
+     *             <ul>
+     *               <li>{@code container} parents with {@code presence}, as these form a {@code mandatory} enforcement
+     *                   boundary. We cannot infer the mandatory nodes from {@code path} and hence we may end up wanting
+     *                   to create an invalid structure</li>
+     *               <li>{@code list} parents with {@code unique} encompassing other leaves than {@code key}. While we
+     *                   can re-create the key {@code leaf} items, we have no way of constructing of {@code unique}
+     *                   requirements.</li>
+     *             </ul>
+     *             Based on this analysis, all users of this method need to be migrated to have a proper lifecycle
+     *             relationship with entities responsible for managing such semantic items which are created by this
+     *             method.
      */
-    // TODO: can we come up with a better name?
-    @Beta
+    @Deprecated(since = "11.0.3")
     <T extends DataObject> void mergeParentStructurePut(@NonNull LogicalDatastoreType store,
             @NonNull InstanceIdentifier<T> path, @NonNull T data);
 
@@ -103,9 +117,24 @@ public interface WriteOperations {
      * @throws IllegalStateException if the transaction has already been submitted
      * @throws NullPointerException if any of the arguments is {@code null}
      * @throws TransactionDatastoreMismatchException if this transaction is already bound to a different data store
+     * @deprecated Use of this method is a manifestation of bad lifecycle management: it attempts to create data tree
+     *             parent nodes which may have semantic meaning without assigning responsibility. The datastore handles
+     *             all the cases which do not attach semantics, such as {@code container}s without {@code presence},
+     *             {@code augmentation} and {@code list} encapsulation.
+     *             This method does not work in the general case, where there are:
+     *             <ul>
+     *               <li>{@code container} parents with {@code presence}, as these form a {@code mandatory} enforcement
+     *                   boundary. We cannot infer the mandatory nodes from {@code path} and hence we may end up wanting
+     *                   to create an invalid structure</li>
+     *               <li>{@code list} parents with {@code unique} encompassing other leaves than {@code key}. While we
+     *                   can re-create the key {@code leaf} items, we have no way of constructing of {@code unique}
+     *                   requirements.</li>
+     *             </ul>
+     *             Based on this analysis, all users of this method need to be migrated to have a proper lifecycle
+     *             relationship with entities responsible for managing such semantic items which are created by this
+     *             method.
      */
-    // TODO: can we come up with a better name?
-    @Beta
+    @Deprecated(since = "11.0.3")
     <T extends DataObject> void mergeParentStructureMerge(@NonNull LogicalDatastoreType store,
             @NonNull InstanceIdentifier<T> path, @NonNull T data);
 

diff --git a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMWriteTransactionAdapter.java b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMWriteTransactionAdapter.java
index 92cb94b956b34d40553dda72538400f5b325c91a..0c6bef88148d62b96c9271122bd5bdb0af1e5b72 100644 (file)
--- a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMWriteTransactionAdapter.java
+++ b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/BindingDOMWriteTransactionAdapter.java
@@ -34,6 +34,7 @@ class BindingDOMWriteTransactionAdapter<T extends DOMDataTreeWriteTransaction> e
         getDelegate().put(store, normalized.getKey(), normalized.getValue());
     }
 
+    @Deprecated
     @Override
     public final <U extends DataObject> void mergeParentStructurePut(final LogicalDatastoreType store,
             final InstanceIdentifier<U> path, final U data) {
@@ -50,6 +51,7 @@ class BindingDOMWriteTransactionAdapter<T extends DOMDataTreeWriteTransaction> e
         getDelegate().merge(store, normalized.getKey(), normalized.getValue());
     }
 
+    @Deprecated
     @Override
     public final <U extends DataObject> void mergeParentStructureMerge(final LogicalDatastoreType store,
             final InstanceIdentifier<U> path, final U data) {

diff --git a/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingReadWriteTransaction.java b/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingReadWriteTransaction.java
index d421a8cefc8a34a64421cdc730c43ae743a1107c..8f4b12616dc83e83285baaad181d18668314fad8 100644 (file)
--- a/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingReadWriteTransaction.java
+++ b/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingReadWriteTransaction.java
@@ -39,6 +39,7 @@ public class ForwardingReadWriteTransaction extends ForwardingTransaction implem
         delegate.put(store, path, data);
     }
 
+    @Deprecated
     @Override
     public <T extends DataObject> void mergeParentStructurePut(final LogicalDatastoreType store,
             final InstanceIdentifier<T> path, final T data) {
@@ -67,6 +68,7 @@ public class ForwardingReadWriteTransaction extends ForwardingTransaction implem
         delegate.merge(store, path, data);
     }
 
+    @Deprecated
     @Override
     public <T extends DataObject> void mergeParentStructureMerge(final LogicalDatastoreType store,
             final InstanceIdentifier<T> path, final T data) {

diff --git a/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingWriteTransaction.java b/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingWriteTransaction.java
index 7fbc69c9ec478bda0f0aca083c049f6efdf8de4e..5404ffe60026a2a7b88da0b509330793fbdad8df 100644 (file)
--- a/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingWriteTransaction.java
+++ b/binding/mdsal-binding-spi/src/main/java/org/opendaylight/mdsal/binding/spi/ForwardingWriteTransaction.java
@@ -38,12 +38,14 @@ public class ForwardingWriteTransaction extends ForwardingTransaction implements
         delegate.put(store, path, data);
     }
 
+    @Deprecated
     @Override
     public <T extends DataObject> void mergeParentStructurePut(final LogicalDatastoreType store,
             final InstanceIdentifier<T> path, final T data) {
         delegate.mergeParentStructurePut(store, path, data);
     }
 
+    @Deprecated
     @Override
     public <T extends DataObject> void merge(final LogicalDatastoreType store, final InstanceIdentifier<T> path,
             final T data) {