From b011979b6e3b0b9e7f6d0bd5574fda9bc4668059 Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Thu, 8 Dec 2022 23:09:13 +0100 Subject: [PATCH] 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 --- .../mdsal/binding/api/WriteOperations.java | 39 ++++++++++++++++--- .../BindingDOMWriteTransactionAdapter.java | 2 + .../spi/ForwardingReadWriteTransaction.java | 2 + .../spi/ForwardingWriteTransaction.java | 2 + 4 files changed, 40 insertions(+), 5 deletions(-) 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 72855e2cf0..bd695d3659 100644 --- 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: + * + * 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") void mergeParentStructurePut(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier 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: + *
    + *
  • {@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
    • + *
  • {@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.
    • + *
+ * 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") void mergeParentStructureMerge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier 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 92cb94b956..0c6bef8814 100644 --- 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 e getDelegate().put(store, normalized.getKey(), normalized.getValue()); } + @Deprecated @Override public final void mergeParentStructurePut(final LogicalDatastoreType store, final InstanceIdentifier path, final U data) { @@ -50,6 +51,7 @@ class BindingDOMWriteTransactionAdapter e getDelegate().merge(store, normalized.getKey(), normalized.getValue()); } + @Deprecated @Override public final void mergeParentStructureMerge(final LogicalDatastoreType store, final InstanceIdentifier 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 d421a8cefc..8f4b12616d 100644 --- 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 void mergeParentStructurePut(final LogicalDatastoreType store, final InstanceIdentifier path, final T data) { @@ -67,6 +68,7 @@ public class ForwardingReadWriteTransaction extends ForwardingTransaction implem delegate.merge(store, path, data); } + @Deprecated @Override public void mergeParentStructureMerge(final LogicalDatastoreType store, final InstanceIdentifier 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 7fbc69c9ec..5404ffe600 100644 --- 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 void mergeParentStructurePut(final LogicalDatastoreType store, final InstanceIdentifier path, final T data) { delegate.mergeParentStructurePut(store, path, data); } + @Deprecated @Override public void merge(final LogicalDatastoreType store, final InstanceIdentifier path, final T data) { -- 2.36.6