opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionChain.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.sal.core.spi.data;
   9
  10 /**
  11  * A chain of transactions. Transactions in a chain need to be committed in
  12  * sequence and each transaction must see the effects of previous transactions
  13  * as if they happened. A chain makes no guarantees of atomicity, in fact
  14  * transactions are committed as soon as possible.
  15  *
  16  *
  17  */
  18 public interface DOMStoreTransactionChain extends DOMStoreTransactionFactory, AutoCloseable {
  19
  20     /**
  21      * Create a new read only transaction which will continue the chain. The
  22      * previous write transaction has to be either READY or CANCELLED.
  23      *
  24      * If previous write transaction was already commited to data store, new
  25      * read-only transaction is same as obtained via {@link DOMStore#newReadOnlyTransaction()}
  26      * and contains merged result of previous one and current state of data store.
  27      *
  28      * Otherwise read-only transaction presents isolated view as if previous read-write
  29      * transaction was successful. State which was introduced by other transactions
  30      * outside this transaction chain after creation of previous transaction is not visible.
  31      *
  32      * @return New transaction in the chain.
  33      * @throws IllegalStateException
  34      *             if the previous transaction was not READY or CANCELLED, or
  35      *             if the chain has been closed.
  36      */
  37     @Override
  38     public DOMStoreReadTransaction newReadOnlyTransaction();
  39
  40     /**
  41      * Create a new read write transaction which will continue the chain. The
  42      * previous read-write transaction has to be either COMMITED or CANCELLED.
  43      *
  44      * If previous write transaction was already commited to data store, new
  45      * read-write transaction is same as obtained via {@link DOMStore#newReadWriteTransaction()}
  46      * and contains merged result of previous one and current state of data store.
  47      *
  48      * Otherwise read-write transaction presents isolated view as if previous read-write
  49      * transaction was successful. State which was introduced by other transactions
  50      * outside this transaction chain after creation of previous transaction is not visible.
  51      *
  52      * @return New transaction in the chain.
  53      * @throws IllegalStateException
  54      *             if the previous transaction was not READY or CANCELLED, or
  55      *             if the chain has been closed.
  56      */
  57     @Override
  58     public DOMStoreReadWriteTransaction newReadWriteTransaction();
  59
  60     /**
  61      * Create a new read write transaction which will continue the chain. The
  62      * previous read-write transaction has to be either READY or CANCELLED.
  63      *
  64      *
  65      * @return New transaction in the chain.
  66      * @throws IllegalStateException
  67      *             if the previous transaction was not READY or CANCELLED, or
  68      *             if the chain has been closed.
  69      */
  70     @Override
  71     public DOMStoreWriteTransaction newWriteOnlyTransaction();
  72
  73
  74     /**
  75      * Closes Transaction Chain.
  76      *
  77      * Close method of transaction chain does not guarantee that
  78      * last alocated transaction is ready or was submitted.
  79      *
  80      * @throws IllegalStateException If any of the outstanding created transactions was not canceled or ready.
  81      */
  82     @Override
  83     public void close();
  84
  85 }