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