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 }