opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.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.common.api.data;
   9
  10 import java.util.concurrent.Future;
  11
  12 import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
  13 import org.opendaylight.yangtools.concepts.Path;
  14 import org.opendaylight.yangtools.yang.common.RpcResult;
  15
  16 public interface AsyncWriteTransaction<P extends Path<P>, D>  extends AsyncTransaction<P, D> {
  17     /**
  18      * Cancels transaction.
  19      *
  20      * Transaction could be only cancelled if it's status
  21      * is {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
  22      *
  23      * Invoking cancel() on {@link TransactionStatus#FAILED} or {@link TransactionStatus#CANCELED}
  24      * will have no effect.
  25      *
  26      * @throws IllegalStateException If transaction status is {@link TransactionStatus#COMMITED}
  27      *
  28      */
  29     public void cancel();
  30
  31     /**
  32      * Store a piece of data at specified path. This acts as a add / replace operation,
  33      * which is to say that whole subtree will be replaced by specified path.
  34      *
  35      * If you need add or merge of current object with specified use {@link #merge(LogicalDatastoreType, Path, Object)}
  36      *
  37      * @param store Logical data store which should be modified
  38      * @param path Data object path
  39      * @param data Data object to be written to specified path
  40      * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
  41      */
  42     public void put(LogicalDatastoreType store, P path, D data);
  43
  44     /**
  45      * Store a piece of data at specified path. This acts as a merge operation,
  46      * which is to say that any pre-existing data which is not explicitly
  47      * overwritten will be preserved. This means that if you store a container,
  48      * its child lists will be merged. Performing the following put operations:
  49      *
  50      * 1) container { list [ a ] }
  51      * 2) container { list [ b ] }
  52      *
  53      * will result in the following data being present:
  54      *
  55      * container { list [ a, b ] }
  56      *
  57      * This also means that storing the container will preserve any augmentations
  58      * which have been attached to it.
  59      *
  60      * If you require an explicit replace operation, use {@link #put(LogicalDatastoreType, Path, Object)} instead.
  61      *
  62      * @param store Logical data store which should be modified
  63      * @param path Data object path
  64      * @param data Data object to be written to specified path
  65      * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
  66      */
  67     public void merge(LogicalDatastoreType store, P path, D data);
  68
  69     /**
  70      * Remove a piece of data from specified path. This operation does not fail
  71      * if the specified path does not exist.
  72      *
  73      * @param store Logical data store which should be modified
  74      * @param path Data object path
  75      * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
  76      */
  77     public void delete(LogicalDatastoreType store, P path);
  78
  79     /**
  80      *
  81      * Closes transaction and resources allocated to the transaction.
  82      *
  83      * This call does not change Transaction status. Client SHOULD
  84      * explicitly {@link #commit()} or {@link #cancel()} transaction.
  85      *
  86      * @throws IllegalStateException if the transaction has not been
  87      *         updated by invoking {@link #commit()} or {@link #cancel()}.
  88      */
  89     @Override
  90     public void close();
  91
  92     /**
  93      * Initiates a commit of modification. This call logically seals the
  94      * transaction, preventing any the client from interacting with the
  95      * data stores. The transaction is marked as {@link TransactionStatus#SUBMITED}
  96      * and enqueued into the data store backed for processing.
  97      *
  98      * <p>
  99      * The successful commit changes the state of the system and may affect
 100      * several components.
 101      *
 102      * <p>
 103      * The effects of successful commit of data are described in the
 104      * specifications and YANG models describing the Provider components of
 105      * controller. It is assumed that Consumer has an understanding of this
 106      * changes.
 107      *
 108      * @see DataCommitHandler for further information how two-phase commit is
 109      *      processed.
 110      * @param store Identifier of the store, where commit should occur.
 111      * @return Result of the Commit, containing success information or list of
 112      *         encountered errors, if commit was not successful. The Future
 113      *         blocks until {@link TransactionStatus#COMMITED} or
 114      *         {@link TransactionStatus#FAILED} is reached.
 115      * @throws IllegalStateException if the transaction is not {@link TransactionStatus#NEW}
 116      */
 117     public Future<RpcResult<TransactionStatus>> commit();
 118
 119 }