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 com.google.common.annotations.Beta;
11 import org.eclipse.jdt.annotation.NonNull;
12 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
13 import org.opendaylight.yangtools.yang.binding.DataObject;
14 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
17 * Write-like operations supported by {@link WriteTransaction} and {@link ReadWriteTransaction}. This interface defines
18 * the operations without a tie-in with lifecycle management.
20 public interface WriteOperations {
22 * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that
23 * whole subtree will be replaced by the specified data.
26 * If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using
27 * put, consider using {@link #merge} instead.
29 * @param store the logical data store which should be modified
30 * @param path the data object path
31 * @param data the data object to be written to the specified path
32 * @throws IllegalStateException if the transaction has already been submitted
33 * @throws NullPointerException if any of the arguments is null
35 <T extends DataObject> void put(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
39 * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that whole
40 * subtree will be replaced by the specified data.
43 * If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using
44 * put, consider using {@link #merge} instead.
46 * <b>WARNING:</b> Using this method may introduce garbage in data store, or recreate nodes, which were deleted by
47 * a previous transaction. It is not necessary in most scenarios and has a significantly higher cost
48 * than {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject)} and should only be used
49 * when absolutely necessary.
51 * @param store the logical data store which should be modified
52 * @param path the data object path
53 * @param data the data object to be written to the specified path
54 * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
55 * created using a merge operation. <b>WARNING:</b> using this option is not needed
56 * in most scenarios and has a significant performance cost and should be avoided
58 * @throws IllegalStateException if the transaction has already been submitted
59 * @throws NullPointerException if any of the arguments is null
60 * @deprecated Use {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject)} or
61 * {@link #mergeParentStructurePut(LogicalDatastoreType, InstanceIdentifier, DataObject)}
64 @Deprecated(forRemoval = true)
65 default <T extends DataObject> void put(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
66 @NonNull T data, boolean createMissingParents) {
67 if (createMissingParents) {
68 mergeParentStructurePut(store, path, data);
70 put(store, path, data);
75 * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that whole
76 * subtree will be replaced by the specified data. Unlike
77 * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject)}, this method will attempt to create
78 * semantically-significant parent nodes, like list entries and presence containers, as indicated by {@code path}.
81 * If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using
82 * put, consider using {@link #merge} instead.
85 * <b>WARNING:</b> Using this method may introduce garbage in data store, or recreate nodes, which were deleted by
86 * a previous transaction. It also has a significantly higher cost than
87 * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject)} and should only be used when
88 * absolutely necessary.
90 * @param store the logical data store which should be modified
91 * @param path the data object path
92 * @param data the data object to be written to the specified path
93 * @throws IllegalStateException if the transaction has already been submitted
94 * @throws NullPointerException if any of the arguments is null
96 // TODO: can we come up with a better name?
98 <T extends DataObject> void mergeParentStructurePut(@NonNull LogicalDatastoreType store,
99 @NonNull InstanceIdentifier<T> path, @NonNull T data);
102 * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
103 * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
106 * If you require an explicit replace operation, use {@link #put} instead.
108 * @param store the logical data store which should be modified
109 * @param path the data object path
110 * @param data the data object to be merged to the specified path
111 * @throws IllegalStateException if the transaction has already been submitted
112 * @throws NullPointerException if any of the arguments is null
114 <T extends DataObject> void merge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
118 * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
119 * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
122 * If you require an explicit replace operation, use {@link #put} instead.
124 * @param store the logical data store which should be modified
125 * @param path the data object path
126 * @param data the data object to be merged to the specified path
127 * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
128 * created using a merge operation. <b>WARNING:</b> using this option is not needed
129 * in most scenarios and has a significant performance cost and should be avoided
131 * @throws IllegalStateException if the transaction has already been submitted
132 * @throws NullPointerException if any of the arguments is null
133 * @deprecated Use {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject)} or
134 * {@link #mergeParentStructureMerge(LogicalDatastoreType, InstanceIdentifier, DataObject)}
137 @Deprecated(forRemoval = true)
138 default <T extends DataObject> void merge(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<T> path,
139 @NonNull T data, boolean createMissingParents) {
140 if (createMissingParents) {
141 mergeParentStructureMerge(store, path, data);
143 merge(store, path, data);
148 * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
149 * overwritten will be preserved. This means that if you store a container, its child lists will be merged. Unlike
150 * {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject)}, this method will attempt to create
151 * semantically-significant parent nodes, like list entries and presence containers, as indicated by {@code path}.
154 * If you require an explicit replace operation, use {@link #put} instead.
157 * <b>WARNING:</b> Using this method may introduce garbage in data store, or recreate nodes, which were deleted by
158 * a previous transaction. It is not necessary in most scenarios and has a significantly higher cost
159 * than {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject)}. It should only be used
160 * when absolutely necessary.
162 * @param store the logical data store which should be modified
163 * @param path the data object path
164 * @param data the data object to be merged to the specified path
165 * @throws IllegalStateException if the transaction has already been submitted
166 * @throws NullPointerException if any of the arguments is null
168 // TODO: can we come up with a better name?
170 <T extends DataObject> void mergeParentStructureMerge(@NonNull LogicalDatastoreType store,
171 @NonNull InstanceIdentifier<T> path, @NonNull T data);
174 * Removes a piece of data from specified path. This operation does not fail if the specified path does not exist.
176 * @param store Logical data store which should be modified
177 * @param path Data object path
178 * @throws IllegalStateException if the transaction was committed or canceled.
180 void delete(@NonNull LogicalDatastoreType store, @NonNull InstanceIdentifier<?> path);
183 * Flag value indicating that missing parents should be created.
186 * <b>WARNING:</b> Using this flag may introduce garbage in data store, or recreate nodes, which were deleted by
187 * a previous transaction. It is not necessary in most scenarios and also has a significantly higher
188 * cost than {@link #FAIL_ON_MISSING_PARENTS} and should only be used when absolutely necessary.
190 * @deprecated To be removed with {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
191 * and {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}.
193 @Deprecated(forRemoval = true)
194 boolean CREATE_MISSING_PARENTS = true;
197 * Flag value indicating that missing parents should cause an error.
199 * @deprecated To be removed with {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
200 * and {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}.
202 @Deprecated(forRemoval = true)
203 boolean FAIL_ON_MISSING_PARENTS = false;