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<>(transactionId, getDebugTransactions(), entry.getValue(),
 144                     this);
 145         } while (!recordTransaction(entry.getKey(), ret));
 146
 147         return ret;
 148     }
 149
 150     @Override
 151     public final DOMStoreWriteTransaction newWriteOnlyTransaction() {
 152         return newWriteOnlyTransaction(nextTransactionIdentifier());
 153     }
 154
 155     protected DOMStoreWriteTransaction newWriteOnlyTransaction(T transactionId) {
 156         Entry<State, DataTreeSnapshot> entry;
 157         DOMStoreWriteTransaction ret;
 158
 159         do {
 160             entry = getSnapshot(transactionId);
 161             ret = new SnapshotBackedWriteTransaction<>(transactionId, getDebugTransactions(), entry.getValue(), this);
 162         } while (!recordTransaction(entry.getKey(), ret));
 163
 164         return ret;
 165     }
 166
 167     @Override
 168     protected final void transactionAborted(final SnapshotBackedWriteTransaction<T> tx) {
 169         final State localState = state;
 170         if (localState instanceof Allocated) {
 171             final Allocated allocated = (Allocated)localState;
 172             if (allocated.getTransaction().equals(tx)) {
 173                 final boolean success = STATE_UPDATER.compareAndSet(this, localState, idleState);
 174                 if (!success) {
 175                     LOG.warn("Transaction {} aborted, but chain {} state already transitioned from {} to {}, very strange",
 176                         tx, this, localState, state);
 177                 }
 178             }
 179         }
 180     }
 181
 182     @Override
 183     protected final DOMStoreThreePhaseCommitCohort transactionReady(final SnapshotBackedWriteTransaction<T> tx, final DataTreeModification tree) {
 184         final State localState = state;
 185
 186         if (localState instanceof Allocated) {
 187             final Allocated allocated = (Allocated)localState;
 188             final DOMStoreWriteTransaction transaction = allocated.getTransaction();
 189             Preconditions.checkState(tx.equals(transaction), "Mis-ordered ready transaction %s last allocated was %s", tx, transaction);
 190             allocated.setSnapshot(tree);
 191         } else {
 192             LOG.debug("Ignoring transaction {} readiness due to state {}", tx, localState);
 193         }
 194
 195         return createCohort(tx, tree);
 196     }
 197
 198     @Override
 199     public final void close() {
 200         final State localState = state;
 201
 202         do {
 203             Preconditions.checkState(!CLOSED.equals(localState), "Transaction chain %s has been closed", this);
 204
 205             if (FAILED.equals(localState)) {
 206                 LOG.debug("Ignoring user close in failed state");
 207                 return;
 208             }
 209         } while (!STATE_UPDATER.compareAndSet(this, localState, CLOSED));
 210     }
 211
 212     /**
 213      * Notify the base logic that a previously-submitted transaction has been committed successfully.
 214      *
 215      * @param transaction Transaction which completed successfully.
 216      */
 217     protected final void onTransactionCommited(final SnapshotBackedWriteTransaction<T> transaction) {
 218         // If the committed transaction was the one we allocated last,
 219         // we clear it and the ready snapshot, so the next transaction
 220         // allocated refers to the data tree directly.
 221         final State localState = state;
 222
 223         if (!(localState instanceof Allocated)) {
 224             // This can legally happen if the chain is shut down before the transaction was committed
 225             // by the backend.
 226             LOG.debug("Ignoring successful transaction {} in state {}", transaction, localState);
 227             return;
 228         }
 229
 230         final Allocated allocated = (Allocated)localState;
 231         final DOMStoreWriteTransaction tx = allocated.getTransaction();
 232         if (!tx.equals(transaction)) {
 233             LOG.debug("Ignoring non-latest successful transaction {} in state {}", transaction, allocated);
 234             return;
 235         }
 236
 237         if (!STATE_UPDATER.compareAndSet(this, localState, idleState)) {
 238             LOG.debug("Transaction chain {} has already transitioned from {} to {}, not making it idle", this, localState, state);
 239         }
 240     }
 241
 242     /**
 243      * Notify the base logic that a previously-submitted transaction has failed.
 244      *
 245      * @param transaction Transaction which failed.
 246      * @param cause Failure cause
 247      */
 248     protected final void onTransactionFailed(final SnapshotBackedWriteTransaction<T> transaction, final Throwable cause) {
 249         LOG.debug("Transaction chain {} failed on transaction {}", this, transaction, cause);
 250         state = FAILED;
 251     }
 252
 253     /**
 254      * Return the next transaction identifier.
 255      *
 256      * @return transaction identifier.
 257      */
 258     protected abstract T nextTransactionIdentifier();
 259
 260     /**
 261      * Inquire as to whether transactions should record their allocation context.
 262      *
 263      * @return True if allocation context should be recorded.
 264      */
 265     protected abstract boolean getDebugTransactions();
 266
 267     /**
 268      * Take a fresh {@link DataTreeSnapshot} from the backend.
 269      *
 270      * @return A new snapshot.
 271      */
 272     protected abstract DataTreeSnapshot takeSnapshot();
 273
 274     /**
 275      * Create a cohort for driving the transaction through the commit process.
 276      *
 277      * @param transaction Transaction handle
 278      * @param modification {@link DataTreeModification} which needs to be applied to the backend
 279      * @return A {@link DOMStoreThreePhaseCommitCohort} cohort.
 280      */
 281     protected abstract DOMStoreThreePhaseCommitCohort createCohort(final SnapshotBackedWriteTransaction<T> transaction, final DataTreeModification modification);
 282 }