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