Update WriteOperations/TypedTransaction API design

[mdsal.git] / binding / mdsal-binding-util / src / main / java / org / opendaylight / mdsal / binding / util / TypedWriteTransaction.java

diff --git a/binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/TypedWriteTransaction.java b/binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/TypedWriteTransaction.java
index f8be2a4ed3ae9b88e5a68a2e2a566fbe2aac7013..e2790eb6b59773e6effed3ca3d35bec928eaa4b7 100644 (file)
--- a/binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/TypedWriteTransaction.java
+++ b/binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/TypedWriteTransaction.java
@@ -7,8 +7,9 @@
  */
 package org.opendaylight.mdsal.binding.util;
 
+import com.google.common.annotations.Beta;
 import org.opendaylight.mdsal.binding.api.Transaction;
-import org.opendaylight.mdsal.binding.api.WriteTransaction;
+import org.opendaylight.mdsal.binding.api.WriteOperations;
 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
 import org.opendaylight.yangtools.yang.binding.DataObject;
 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
@@ -18,13 +19,13 @@ import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  * with {@link ManagedNewTransactionRunner} (it doesn’t support explicit cancel or commit operations).
  *
  * @param <D> The logical datastore handled by the transaction.
- * @see WriteTransaction
+ * @see WriteOperations
  */
 public interface TypedWriteTransaction<D extends Datastore> extends Transaction {
     /**
      * Writes an object to the given path.
      *
-     * @see WriteTransaction#put(LogicalDatastoreType, InstanceIdentifier, DataObject)
+     * @see WriteOperations#put(LogicalDatastoreType, InstanceIdentifier, DataObject)
      *
      * @param path The path to write to.
      * @param data The object to write.
@@ -35,20 +36,40 @@ public interface TypedWriteTransaction<D extends Datastore> extends Transaction
     /**
      * Writes an object to the given path, creating missing parents if requested.
      *
-     * @see WriteTransaction#put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)
+     * @see WriteOperations#put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)
      *
      * @param path The path to write to.
      * @param data The object to write.
-     * @param createMissingParents {@link WriteTransaction#CREATE_MISSING_PARENTS} to create missing parents,
-     * {@link WriteTransaction#FAIL_ON_MISSING_PARENTS} to fail if parents are missing.
+     * @param createMissingParents {@link WriteOperations#CREATE_MISSING_PARENTS} to create missing parents,
+     *                             {@link WriteOperations#FAIL_ON_MISSING_PARENTS} to fail if parents are missing.
      * @param <T> The type of the provided object.
+     * @deprecated Use {@link #put(InstanceIdentifier, DataObject)} or
+     *             {@link #mergeParentStructurePut(InstanceIdentifier, DataObject)} instead.
      */
+    @Deprecated
     <T extends DataObject> void put(InstanceIdentifier<T> path, T data, boolean createMissingParents);
 
+    /**
+     * Writes an object to the given path, creating significant parents, like presence containers and list entries,
+     * if needed.
+     *
+     * @see WriteOperations#mergeParentStructurePut(LogicalDatastoreType, InstanceIdentifier, DataObject)
+     *
+     * @param path The path to write to.
+     * @param data The object to write.
+     * @param <T> The type of the provided object.
+     */
+    // TODO: can we come up with a better name?
+    @Beta
+    @SuppressWarnings("deprecation")
+    default <T extends DataObject> void mergeParentStructurePut(final InstanceIdentifier<T> path, final T data) {
+        put(path, data, WriteOperations.CREATE_MISSING_PARENTS);
+    }
+
     /**
      * Merges an object with the data already present at the given path.
      *
-     * @see WriteTransaction#merge(LogicalDatastoreType, InstanceIdentifier, DataObject)
+     * @see WriteOperations#merge(LogicalDatastoreType, InstanceIdentifier, DataObject)
      *
      * @param path The path to write to.
      * @param data The object to merge.
@@ -57,22 +78,44 @@ public interface TypedWriteTransaction<D extends Datastore> extends Transaction
     <T extends DataObject> void merge(InstanceIdentifier<T> path, T data);
 
     /**
-     * Merges an object with the data already present at the given path, creating missing parents if requested.
+     * Merges an object with the data already present at the given path, creating significant parents, like presence
+     * containers and list entries, if needed.
      *
-     * @see WriteTransaction#merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)
+     * @see WriteOperations#merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)
      *
      * @param path The path to write to.
      * @param data The object to merge.
-     * @param createMissingParents {@link WriteTransaction#CREATE_MISSING_PARENTS} to create missing parents,
-     * {@link WriteTransaction#FAIL_ON_MISSING_PARENTS} to fail if parents are missing.
+     * @param createMissingParents {@link WriteOperations#CREATE_MISSING_PARENTS} to create missing parents,
+     *                             {@link WriteOperations#FAIL_ON_MISSING_PARENTS} to fail if parents are missing.
      * @param <T> The type of the provided object.
+     * @deprecated Use {@link #merge(InstanceIdentifier, DataObject)} or
+     *             {@link #mergeParentStructureMerge(InstanceIdentifier, DataObject)} instead.
      */
+    @Deprecated
     <T extends DataObject> void merge(InstanceIdentifier<T> path, T data, boolean createMissingParents);
 
+    /**
+     * Merges an object with the data already present at the given path, creating missing parents if requested.
+     *
+     * @see WriteOperations#merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)
+     *
+     * @param path The path to write to.
+     * @param data The object to merge.
+     * @param <T> The type of the provided object.
+     */
+    // FIXME: 4.0.0: make this method non-default
+    // TODO: can we come up with a better name?
+    @Beta
+    @SuppressWarnings("deprecation")
+    default <T extends DataObject> void mergeParentStructureMerge(final InstanceIdentifier<T> path,
+            final T data) {
+        merge(path, data, WriteOperations.CREATE_MISSING_PARENTS);
+    }
+
     /**
      * Deletes the object present at the given path.
      *
-     * @see WriteTransaction#delete(LogicalDatastoreType, InstanceIdentifier)
+     * @see WriteOperations#delete(LogicalDatastoreType, InstanceIdentifier)
      *
      * @param path The path to delete.
      */