opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/AbstractSnapshotBackedTransactionChain.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 import com.google.common.annotations.Beta;
  11 import com.google.common.base.Preconditions;
  12 import java.util.AbstractMap.SimpleEntry;
  13 import java.util.Map.Entry;
  14 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
  15 import org.opendaylight.controller.sal.core.spi.data.SnapshotBackedWriteTransaction.TransactionReadyPrototype;
  16 import org.opendaylight.yangtools.yang.data.api.schema.tree.DataTreeModification;
  17 import org.opendaylight.yangtools.yang.data.api.schema.tree.DataTreeSnapshot;
  18 import org.slf4j.Logger;
  19 import org.slf4j.LoggerFactory;
  20
  21 /**
  22  * Abstract implementation of the {@link DOMStoreTransactionChain} interface relying on {@link DataTreeSnapshot} supplier
  23  * and backend commit coordinator.
  24  *
  25  * @param <T> transaction identifier type
  26  */
  27 @Beta
  28 public abstract class AbstractSnapshotBackedTransactionChain<T> extends TransactionReadyPrototype<T> implements DOMStoreTransactionChain {
  29     private static abstract class State {
  30         /**
  31          * Allocate a new snapshot.
  32          *
  33          * @return A new snapshot
  34          */
  35         protected abstract DataTreeSnapshot getSnapshot(Object transactionId);
  36     }
  37
  38     private static final class Idle extends State {
  39         private final AbstractSnapshotBackedTransactionChain<?> chain;
  40
  41         Idle(final AbstractSnapshotBackedTransactionChain<?> chain) {
  42             this.chain = Preconditions.checkNotNull(chain);
  43         }
  44
  45         @Override
  46         protected DataTreeSnapshot getSnapshot(Object transactionId) {
  47             return chain.takeSnapshot();
  48         }
  49     }
  50
  51     /**
  52      * We have a transaction out there.
  53      */
  54     private static final class Allocated extends State {
  55         private static final AtomicReferenceFieldUpdater<Allocated, DataTreeSnapshot> SNAPSHOT_UPDATER =
  56                 AtomicReferenceFieldUpdater.newUpdater(Allocated.class, DataTreeSnapshot.class, "snapshot");
  57         private final DOMStoreWriteTransaction transaction;
  58         private volatile DataTreeSnapshot snapshot;
  59
  60         Allocated(final DOMStoreWriteTransaction transaction) {
  61             this.transaction = Preconditions.checkNotNull(transaction);
  62         }
  63
  64         public DOMStoreWriteTransaction getTransaction() {
  65             return transaction;
  66         }
  67
  68         @Override
  69         protected DataTreeSnapshot getSnapshot(Object transactionId) {
  70             final DataTreeSnapshot ret = snapshot;
  71             Preconditions.checkState(ret != null, "Could not get snapshot for transaction %s - previous transaction %s is not ready yet",
  72                     transactionId, transaction.getIdentifier());
  73             return ret;
  74         }
  75
  76         void setSnapshot(final DataTreeSnapshot snapshot) {
  77             final boolean success = SNAPSHOT_UPDATER.compareAndSet(this, null, snapshot);
  78             Preconditions.checkState(success, "Transaction %s has already been marked as ready", transaction.getIdentifier());
  79         }
  80     }
  81
  82     /**
  83      * Chain is logically shut down, no further allocation allowed.
  84      */
  85     private static final class Shutdown extends State {
  86         private final String message;
  87
  88         Shutdown(final String message) {
  89             this.message = Preconditions.checkNotNull(message);
  90         }
  91
  92         @Override
  93         protected DataTreeSnapshot getSnapshot(Object transactionId) {
  94             throw new IllegalStateException(message);
  95         }
  96     }
  97
  98     @SuppressWarnings("rawtypes")
  99     private static final AtomicReferenceFieldUpdater<AbstractSnapshotBackedTransactionChain, State> STATE_UPDATER =
 100             AtomicReferenceFieldUpdater.newUpdater(AbstractSnapshotBackedTransactionChain.class, State.class, "state");
 101     private static final Logger LOG = LoggerFactory.getLogger(AbstractSnapshotBackedTransactionChain.class);
 102     private static final Shutdown CLOSED = new Shutdown("Transaction chain is closed");
 103     private static final Shutdown FAILED = new Shutdown("Transaction chain has failed");
 104     private final Idle idleState;
 105     private volatile State state;
 106
 107     protected AbstractSnapshotBackedTransactionChain() {
 108         idleState = new Idle(this);
 109         state = idleState;
 110     }
 111
 112     private Entry<State, DataTreeSnapshot> getSnapshot(T transactionId) {
 113         final State localState = state;
 114         return new SimpleEntry<>(localState, localState.getSnapshot(transactionId));
 115     }
 116
 117     private boolean recordTransaction(final State expected, final DOMStoreWriteTransaction transaction) {
 118         final State state = new Allocated(transaction);
 119         return STATE_UPDATER.compareAndSet(this, expected, state);
 120     }
 121
 122     @Override
 123     public final DOMStoreReadTransaction newReadOnlyTransaction() {
 124         return newReadOnlyTransaction(nextTransactionIdentifier());
 125     }
 126
 127     protected DOMStoreReadTransaction newReadOnlyTransaction(T transactionId) {
 128         final Entry<State, DataTreeSnapshot> entry = getSnapshot(transactionId);
 129         return SnapshotBackedTransactions.newReadTransaction(transactionId, getDebugTransactions(), entry.getValue());
 130     }
 131
 132     @Override
 133     public final DOMStoreReadWriteTransaction newReadWriteTransaction() {
 134         return newReadWriteTransaction(nextTransactionIdentifier());
 135     }
 136
 137     protected DOMStoreReadWriteTransaction newReadWriteTransaction(T transactionId) {
 138         Entry<State, DataTreeSnapshot> entry;
 139         DOMStoreReadWriteTransaction ret;
 140
 141         do {
 142             entry = getSnapshot(transactionId);
 143             ret = new SnapshotBackedReadWriteTransaction<T>(transactionId, getDebugTransactions(), entry.getValue(), this);
 144         } while (!recordTransaction(entry.getKey(), ret));
 145
 146         return ret;
 147     }
 148
 149     @Override
 150     public final DOMStoreWriteTransaction newWriteOnlyTransaction() {
 151         return newWriteOnlyTransaction(nextTransactionIdentifier());
 152     }
 153
 154     protected DOMStoreWriteTransaction newWriteOnlyTransaction(T transactionId) {
 155         Entry<State, DataTreeSnapshot> entry;
 156         DOMStoreWriteTransaction ret;
 157
 158         do {
 159             entry = getSnapshot(transactionId);
 160             ret = new SnapshotBackedWriteTransaction<T>(transactionId, getDebugTransactions(), entry.getValue(), this);
 161         } while (!recordTransaction(entry.getKey(), ret));
 162
 163         return ret;
 164     }
 165
 166     @Override
 167     protected final void transactionAborted(final SnapshotBackedWriteTransaction<T> tx) {
 168         final State localState = state;
 169         if (localState instanceof Allocated) {
 170             final Allocated allocated = (Allocated)localState;
 171             if (allocated.getTransaction().equals(tx)) {
 172                 final boolean success = STATE_UPDATER.compareAndSet(this, localState, idleState);
 173                 if (!success) {
 174                     LOG.warn("Transaction {} aborted, but chain {} state already transitioned from {} to {}, very strange",
 175                         tx, this, localState, state);
 176                 }
 177             }
 178         }
 179     }
 180
 181     @Override
 182     protected final DOMStoreThreePhaseCommitCohort transactionReady(final SnapshotBackedWriteTransaction<T> tx, final DataTreeModification tree) {
 183         final State localState = state;
 184
 185         if (localState instanceof Allocated) {
 186             final Allocated allocated = (Allocated)localState;
 187             final DOMStoreWriteTransaction transaction = allocated.getTransaction();
 188             Preconditions.checkState(tx.equals(transaction), "Mis-ordered ready transaction %s last allocated was %s", tx, transaction);
 189             allocated.setSnapshot(tree);
 190         } else {
 191             LOG.debug("Ignoring transaction {} readiness due to state {}", tx, localState);
 192         }
 193
 194         return createCohort(tx, tree);
 195     }
 196
 197     @Override
 198     public final void close() {
 199         final State localState = state;
 200
 201         do {
 202             Preconditions.checkState(!CLOSED.equals(localState), "Transaction chain {} has been closed", this);
 203
 204             if (FAILED.equals(localState)) {
 205                 LOG.debug("Ignoring user close in failed state");
 206                 return;
 207             }
 208         } while (!STATE_UPDATER.compareAndSet(this, localState, CLOSED));
 209     }
 210
 211     /**
 212      * Notify the base logic that a previously-submitted transaction has been committed successfully.
 213      *
 214      * @param transaction Transaction which completed successfully.
 215      */
 216     protected final void onTransactionCommited(final SnapshotBackedWriteTransaction<T> transaction) {
 217         // If the committed transaction was the one we allocated last,
 218         // we clear it and the ready snapshot, so the next transaction
 219         // allocated refers to the data tree directly.
 220         final State localState = state;
 221
 222         if (!(localState instanceof Allocated)) {
 223             // This can legally happen if the chain is shut down before the transaction was committed
 224             // by the backend.
 225             LOG.debug("Ignoring successful transaction {} in state {}", transaction, localState);
 226             return;
 227         }
 228
 229         final Allocated allocated = (Allocated)localState;
 230         final DOMStoreWriteTransaction tx = allocated.getTransaction();
 231         if (!tx.equals(transaction)) {
 232             LOG.debug("Ignoring non-latest successful transaction {} in state {}", transaction, allocated);
 233             return;
 234         }
 235
 236         if (!STATE_UPDATER.compareAndSet(this, localState, idleState)) {
 237             LOG.debug("Transaction chain {} has already transitioned from {} to {}, not making it idle", this, localState, state);
 238         }
 239     }
 240
 241     /**
 242      * Notify the base logic that a previously-submitted transaction has failed.
 243      *
 244      * @param transaction Transaction which failed.
 245      * @param cause Failure cause
 246      */
 247     protected final void onTransactionFailed(final SnapshotBackedWriteTransaction<T> transaction, final Throwable cause) {
 248         LOG.debug("Transaction chain {} failed on transaction {}", this, transaction, cause);
 249         state = FAILED;
 250     }
 251
 252     /**
 253      * Return the next transaction identifier.
 254      *
 255      * @return transaction identifier.
 256      */
 257     protected abstract T nextTransactionIdentifier();
 258
 259     /**
 260      * Inquire as to whether transactions should record their allocation context.
 261      *
 262      * @return True if allocation context should be recorded.
 263      */
 264     protected abstract boolean getDebugTransactions();
 265
 266     /**
 267      * Take a fresh {@link DataTreeSnapshot} from the backend.
 268      *
 269      * @return A new snapshot.
 270      */
 271     protected abstract DataTreeSnapshot takeSnapshot();
 272
 273     /**
 274      * Create a cohort for driving the transaction through the commit process.
 275      *
 276      * @param transaction Transaction handle
 277      * @param modification {@link DataTreeModification} which needs to be applied to the backend
 278      * @return A {@link DOMStoreThreePhaseCommitCohort} cohort.
 279      */
 280     protected abstract DOMStoreThreePhaseCommitCohort createCohort(final SnapshotBackedWriteTransaction<T> transaction, final DataTreeModification modification);
 281 }