binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/WriteOperations.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, s.r.o. 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.mdsal.binding.api;
   9
  10 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
  11 import org.opendaylight.yangtools.yang.binding.DataObject;
  12 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  13
  14 /**
  15  * Write-like operations supported by {@link WriteTransaction} and {@link ReadWriteTransaction}. This interface defines
  16  * the operations without a tie-in with lifecycle management.
  17  */
  18 public interface WriteOperations {
  19     /**
  20      * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that
  21      * whole subtree will be replaced by the specified data.
  22      *
  23      * <p>
  24      * This method does not automatically create missing parent nodes. It is equivalent to invoking
  25      * {@link #put(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
  26      * with <code>createMissingParents</code> set to false.
  27      *
  28      * <p>
  29      * If you need to make sure that a parent object exists but you do not want modify
  30      * its pre-existing state by using put, consider using {@link #merge} instead.
  31      *
  32      * @param store the logical data store which should be modified
  33      * @param path the data object path
  34      * @param data the data object to be written to the specified path
  35      * @throws IllegalStateException if the transaction has already been submitted
  36      * @throws NullPointerException if any of the arguments is null
  37      */
  38     <T extends DataObject> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
  39
  40     /**
  41      * Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that whole
  42      * subtree will be replaced by the specified data.
  43      *
  44      * <p>
  45      * If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using
  46      * put, consider using {@link #merge} instead.
  47      *
  48      * <p>
  49      * Note: Using <code>createMissingParents</code> with value true, may introduce garbage in data store, or recreate
  50      * nodes, which were deleted by previous transaction.
  51      *
  52      * @param store the logical data store which should be modified
  53      * @param path the data object path
  54      * @param data the data object to be written to the specified path
  55      * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
  56      *                             created using a merge operation.
  57      * @throws IllegalStateException if the transaction has already been submitted
  58      * @throws NullPointerException if any of the arguments is null
  59      */
  60     <T extends DataObject> void put(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
  61             boolean createMissingParents);
  62
  63     /**
  64      * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
  65      * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
  66      *
  67      * <p>
  68      * This method does not automatically create missing parent nodes. It is equivalent to invoking
  69      * {@link #merge(LogicalDatastoreType, InstanceIdentifier, DataObject, boolean)}
  70      * with <code>createMissingParents</code> set to false.
  71      *
  72      * <p>
  73      * If you require an explicit replace operation, use {@link #put} instead.
  74      * @param store the logical data store which should be modified
  75      * @param path the data object path
  76      * @param data the data object to be merged to the specified path
  77      * @throws IllegalStateException if the transaction has already been submitted
  78      * @throws NullPointerException if any of the arguments is null
  79      */
  80     <T extends DataObject> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data);
  81
  82     /**
  83      * Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly
  84      * overwritten will be preserved. This means that if you store a container, its child lists will be merged.
  85      *
  86      * <p>
  87      * If you require an explicit replace operation, use {@link #put} instead.
  88      *
  89      * @param store the logical data store which should be modified
  90      * @param path the data object path
  91      * @param data the data object to be merged to the specified path
  92      * @param createMissingParents if {@link #CREATE_MISSING_PARENTS}, any missing parent nodes will be automatically
  93      *                             created using a merge operation.
  94      * @throws IllegalStateException if the transaction has already been submitted
  95      * @throws NullPointerException if any of the arguments is null
  96      */
  97     <T extends DataObject> void merge(LogicalDatastoreType store, InstanceIdentifier<T> path, T data,
  98             boolean createMissingParents);
  99
 100     /**
 101      * Removes a piece of data from specified path. This operation does not fail if the specified path does not exist.
 102      *
 103      * @param store Logical data store which should be modified
 104      * @param path Data object path
 105      * @throws IllegalStateException if the transaction was committed or canceled.
 106      */
 107     void delete(LogicalDatastoreType store, InstanceIdentifier<?> path);
 108
 109     /**
 110      * Flag value indicating that missing parents should be created.
 111      */
 112     boolean CREATE_MISSING_PARENTS = true;
 113
 114     /**
 115      * Flag value indicating that missing parents should cause an error.
 116      */
 117     boolean FAIL_ON_MISSING_PARENTS = false;
 118 }