2 * Copyright (c) 2018 Pantheon Technologies, s.r.o. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.mdsal.binding.api;
10 import org.eclipse.jdt.annotation.NonNull;
11 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
12 import org.opendaylight.yangtools.yang.binding.DataObject;
13 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
16 * Write-like operations supported by {@link WriteTransaction} and {@link ReadWriteTransaction}. This interface defines
17 * the operations without a tie-in with lifecycle management.
19 public interface WriteOperations {
21 * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that
22 * whole subtree will be replaced by the specified data.
25 * This method does not automatically create missing parent nodes. It is equivalent to invoking
26 * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
27 * with <code>createMissingParents</code> set to false.
30 * If you need to make sure that a parent object exists but you do not want modify
31 * its pre-existing state by using put, consider using {@link #merge} instead.
33 * @param store the logical data store which should be modified
34 * @param path the data object path
35 * @param data the data object to be written to the specified path
36 * @throws IllegalStateException if the transaction has already been submitted
37 * @throws NullPointerException if any of the arguments is null
39 <T extends DataObject> void put(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
43 * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that whole
44 * subtree will be replaced by the specified data.
47 * If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using
48 * put, consider using {@link #merge} instead.
51 * Note: Using <code>createMissingParents</code> with value true, may introduce garbage in data store, or recreate
52 * nodes, which were deleted by previous transaction.
54 * @param store the logical data store which should be modified
55 * @param path the data object path
56 * @param data the data object to be written to the specified path
57 * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
58 * created using a merge operation.
59 * @throws IllegalStateException if the transaction has already been submitted
60 * @throws NullPointerException if any of the arguments is null
62 <T extends DataObject> void put(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
63 @NonNull T data, boolean createMissingParents);
66 * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
67 * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
70 * This method does not automatically create missing parent nodes. It is equivalent to invoking
71 * {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
72 * with <code>createMissingParents</code> set to false.
75 * If you require an explicit replace operation, use {@link #put} instead.
76 * @param store the logical data store which should be modified
77 * @param path the data object path
78 * @param data the data object to be merged to the specified path
79 * @throws IllegalStateException if the transaction has already been submitted
80 * @throws NullPointerException if any of the arguments is null
82 <T extends DataObject> void merge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
86 * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
87 * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
90 * If you require an explicit replace operation, use {@link #put} instead.
92 * @param store the logical data store which should be modified
93 * @param path the data object path
94 * @param data the data object to be merged to the specified path
95 * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
96 * created using a merge operation.
97 * @throws IllegalStateException if the transaction has already been submitted
98 * @throws NullPointerException if any of the arguments is null
100 <T extends DataObject> void merge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
101 @NonNull T data, boolean createMissingParents);
104 * Removes a piece of data from specified path. This operation does not fail if the specified path does not exist.
106 * @param store Logical data store which should be modified
107 * @param path Data object path
108 * @throws IllegalStateException if the transaction was committed or canceled.
110 void delete(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<?> path);
113 * Flag value indicating that missing parents should be created.
115 boolean CREATE_MISSING_PARENTS = true;
118 * Flag value indicating that missing parents should cause an error.
120 boolean FAIL_ON_MISSING_PARENTS = false;