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

©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.