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