2 * Copyright (c) 2017 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
9 package org.opendaylight.mdsal.binding.javav2.api;
11 import com.google.common.annotations.Beta;
12 import org.opendaylight.mdsal.binding.javav2.spec.base.InstanceIdentifier;
13 import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
14 import org.opendaylight.mdsal.common.api.AsyncWriteTransaction;
15 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
18 * A transaction that provides mutation capabilities on a data tree.
21 * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
24 public interface WriteTransaction extends AsyncWriteTransaction<InstanceIdentifier<?>, TreeNode> {
27 * Stores a piece of data at the specified path. This acts as an add / replace
28 * operation, which is to say that whole subtree will be replaced by the specified data.
31 * This method does not automatically create missing parent nodes. It is equivalent to invoking
32 * {@link #put(LogicalDatastoreType, InstanceIdentifier, TreeNode, boolean)}
33 * with <code>createMissingParents</code> set to false.
36 * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
38 * If you need to make sure that a parent object exists but you do not want modify
39 * its pre-existing state by using put, consider using {@link #merge} instead.
42 * the logical data store which should be modified
44 * the data object path
46 * the data object to be written to the specified path
47 * @param <T> data tree type
48 * @throws IllegalStateException
49 * if the transaction has already been submitted
51 <T extends TreeNode> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
54 * Stores a piece of data at the specified path. This acts as an add /
55 * replace operation, which is to say that whole subtree will be replaced by
59 * For more information on usage and examples, please see the documentation
60 * in {@link AsyncWriteTransaction}.
63 * If you need to make sure that a parent object exists but you do not want
64 * modify its pre-existing state by using put, consider using {@link #merge}
68 * Note: Using <code>createMissingParents</code> with value true, may
69 * introduce garbage in data store, or recreate nodes, which were deleted by
70 * previous transaction.
73 * the logical data store which should be modified
75 * the data object path
77 * the data object to be written to the specified path
78 * @param createMissingParents
79 * if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
80 * created using a merge operation.
81 * @param <T> data tree type
82 * @throws IllegalStateException
83 * if the transaction has already been submitted
85 <T extends TreeNode> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
86 boolean createMissingParents);
89 * Merges a piece of data with the existing data at a specified path. Any pre-existing data
90 * which is not explicitly overwritten will be preserved. This means that if you store a container,
91 * its child lists will be merged.
94 * This method does not automatically create missing parent nodes. It is equivalent to invoking
95 * {@link #merge(LogicalDatastoreType, InstanceIdentifier, TreeNode, boolean)}
96 * with <code>createMissingParents</code> set to false.
99 * For more information on usage and examples, please see the documentation in
100 * {@link AsyncWriteTransaction}.
103 * If you require an explicit replace operation, use {@link #put} instead.
105 * the logical data store which should be modified
107 * the data object path
109 * the data object to be merged to the specified path
110 * @param <T> data tree type
111 * @throws IllegalStateException
112 * if the transaction has already been submitted
114 <T extends TreeNode> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
117 * Merges a piece of data with the existing data at a specified path. Any
118 * pre-existing data which is not explicitly overwritten will be preserved.
119 * This means that if you store a container, its child lists will be merged.
122 * For more information on usage and examples, please see the documentation
123 * in {@link AsyncWriteTransaction}.
126 * If you require an explicit replace operation, use {@link #put} instead.
129 * the logical data store which should be modified
131 * the data object path
133 * the data object to be merged to the specified path
134 * @param createMissingParents
135 * if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically created
136 * using a merge operation.
137 * @param <T> data tree type
138 * @throws IllegalStateException
139 * if the transaction has already been submitted
141 <T extends TreeNode> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
142 boolean createMissingParents);
145 * Flag value indicating that missing parents should be created.
147 boolean CREATE_MISSING_PARENTS = true;
150 * Flag value indicating that missing parents should cause an error.
152 boolean FAIL_ON_MISSING_PARENTS = false;