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