*/
package org.opendaylight.mdsal.binding.api;
-import com.google.common.annotations.Beta;
+import com.google.common.util.concurrent.FluentFuture;
import org.eclipse.jdt.annotation.NonNull;
import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
+import org.opendaylight.mdsal.common.api.TransactionDatastoreMismatchException;
import org.opendaylight.yangtools.yang.binding.DataObject;
import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
* @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
- * @throws NullPointerException if any of the arguments is null
+ * @throws NullPointerException if any of the arguments is {@code null}
+ * @throws TransactionDatastoreMismatchException if this transaction is already bound to a different data store
*/
<T extends DataObject> void put(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
@NonNull T data);
* @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
- * @throws NullPointerException if any of the arguments is null
+ * @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);
* @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
- * @throws NullPointerException if any of the arguments is null
+ * @throws NullPointerException if any of the arguments is {@code null}
+ * @throws TransactionDatastoreMismatchException if this transaction is already bound to a different data store
*/
<T extends DataObject> void merge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
@NonNull T data);
* @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
- * @throws NullPointerException if any of the arguments is null
+ * @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);
* @param store Logical data store which should be modified
* @param path Data object path
* @throws IllegalStateException if the transaction was committed or canceled.
+ * @throws NullPointerException if any of the arguments is {@code null}
+ * @throws TransactionDatastoreMismatchException if this transaction is already bound to a different data store
*/
void delete(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<?> path);
+
+ /**
+ * Return a {@link FluentFuture} which completes.
+ *
+ * @return A future which completes when the requested operations complete.
+ */
+ @NonNull FluentFuture<?> completionFuture();
}
Code Review / mdsal.git / blobdiff