Bug 1280: Added option to automaticly create parents
[controller.git] / opendaylight / md-sal / sal-binding-api / src / main / java / org / opendaylight / controller / md / sal / binding / api / WriteTransaction.java
1 /*
2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
3  *
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
7  */
8 package org.opendaylight.controller.md.sal.binding.api;
9
10 import org.opendaylight.controller.md.sal.common.api.data.AsyncWriteTransaction;
11 import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType;
12 import org.opendaylight.yangtools.yang.binding.DataObject;
13 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
14
15 /**
16  * A transaction that provides mutation capabilities on a data tree.
17  * <p>
18  * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
19  */
20 public interface WriteTransaction extends AsyncWriteTransaction<InstanceIdentifier<?>, DataObject> {
21
22     /**
23      * Stores a piece of data at the specified path. This acts as an add / replace
24      * operation, which is to say that whole subtree will be replaced by the specified data.
25      * * <p>
26      * This method does not automatically create missing parent nodes. It is equivalent to invoking
27      * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
28      * with <code>createMissingParents</code> set to false.
29      * <p>
30      * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
31      * <p>
32      * If you need to make sure that a parent object exists but you do not want modify
33      * its pre-existing state by using put, consider using {@link #merge} instead.
34      *
35      * @param store
36      *            the logical data store which should be modified
37      * @param path
38      *            the data object path
39      * @param data
40      *            the data object to be written to the specified path
41      * @throws IllegalStateException
42      *             if the transaction has already been submitted
43      */
44     <T extends DataObject> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
45
46
47     /**
48      * Stores a piece of data at the specified path. This acts as an add /
49      * replace operation, which is to say that whole subtree will be replaced by
50      * the specified data.
51      * <p>
52      * For more information on usage and examples, please see the documentation
53      * in {@link AsyncWriteTransaction}.
54      * <p>
55      * If you need to make sure that a parent object exists but you do not want
56      * modify its pre-existing state by using put, consider using {@link #merge}
57      * instead.
58      *
59      * Note: Using <code>createMissingParents</code> with value true, may
60      * introduce garbage in data store, or recreate nodes, which were deleted by
61      * previous transaction.
62      *
63      * @param store
64      *            the logical data store which should be modified
65      * @param path
66      *            the data object path
67      * @param data
68      *            the data object to be written to the specified path
69      * @param createMissingParents
70      *            if true, any missing parent nodes will be automatically
71      *            created using a merge operation.
72      * @throws IllegalStateException
73      *             if the transaction has already been submitted
74      */
75     <T extends DataObject> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
76             boolean createMissingParents);
77
78     /**
79      * Merges a piece of data with the existing data at a specified path. Any pre-existing data
80      * which is not explicitly overwritten will be preserved. This means that if you store a container,
81      * its child lists will be merged.
82      * <p>
83      * This method does not automatically create missing parent nodes. It is equivalent to invoking
84      * {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
85      * with <code>createMissingParents</code> set to false.
86      * <p>
87      * For more information on usage and examples, please see the documentation in {@link AsyncWriteTransaction}.
88      *<p>
89      * If you require an explicit replace operation, use {@link #put} instead.
90      * @param store
91      *            the logical data store which should be modified
92      * @param path
93      *            the data object path
94      * @param data
95      *            the data object to be merged to the specified path
96      * @throws IllegalStateException
97      *             if the transaction has already been submitted
98      */
99     <T extends DataObject> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
100
101     /**
102      * Merges a piece of data with the existing data at a specified path. Any
103      * pre-existing data which is not explicitly overwritten will be preserved.
104      * This means that if you store a container, its child lists will be merged.
105      * <p>
106      * For more information on usage and examples, please see the documentation
107      * in {@link AsyncWriteTransaction}.
108      * <p>
109      * If you require an explicit replace operation, use {@link #put} instead.
110      *
111      * @param store
112      *            the logical data store which should be modified
113      * @param path
114      *            the data object path
115      * @param data
116      *            the data object to be merged to the specified path
117      * @param createMissingParents
118      *            if true, any missing parent nodes will be automatically created
119      *            using a merge operation.
120      * @throws IllegalStateException
121      *             if the transaction has already been submitted
122      */
123     <T extends DataObject> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
124             boolean createMissingParents);
125
126     @Override
127     void delete(LogicalDatastoreType store, InstanceIdentifier<?> path);
128 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.