opendaylight/md-sal/sal-distributed-datastore/src/main/java/org/opendaylight/controller/cluster/databroker/actors/dds/ClientTransaction.java

   1 /*
   2  * Copyright (c) 2016 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.cluster.databroker.actors.dds;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.base.Optional;
  12 import com.google.common.base.Preconditions;
  13 import com.google.common.collect.Iterables;
  14 import com.google.common.util.concurrent.CheckedFuture;
  15 import java.util.Collection;
  16 import javax.annotation.Nonnull;
  17 import org.opendaylight.controller.cluster.access.concepts.TransactionIdentifier;
  18 import org.opendaylight.mdsal.common.api.ReadFailedException;
  19 import org.opendaylight.mdsal.dom.api.DOMDataTreeCursor;
  20 import org.opendaylight.mdsal.dom.api.DOMDataTreeWriteCursor;
  21 import org.opendaylight.mdsal.dom.spi.store.DOMStoreThreePhaseCommitCohort;
  22 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  23 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  24
  25 /**
  26  * Client-side view of a transaction.
  27  *
  28  * <p>
  29  * This interface is used by the world outside of the actor system and in the actor system it is manifested via
  30  * its client actor. That requires some state transfer with {@link DistributedDataStoreClientBehavior}. In order to
  31  * reduce request latency, all messages are carbon-copied (and enqueued first) to the client actor.
  32  *
  33  * <p>
  34  * It is internally composed of multiple {@link RemoteProxyTransaction}s, each responsible for a component shard.
  35  *
  36  * <p>
  37  * Implementation is quite a bit complex, and involves cooperation with {@link AbstractClientHistory} for tracking
  38  * gaps in transaction identifiers seen by backends.
  39  *
  40  * <p>
  41  * These gaps need to be accounted for in the transaction setup message sent to a particular backend, so it can verify
  42  * that the requested transaction is in-sequence. This is critical in ensuring that transactions (which are independent
  43  * entities from message queueing perspective) do not get reodered -- thus allowing multiple in-flight transactions.
  44  *
  45  * <p>
  46  * Alternative would be to force visibility by sending an abort request to all potential backends, but that would mean
  47  * that even empty transactions increase load on all shards -- which would be a scalability issue.
  48  *
  49  * <p>
  50  * Yet another alternative would be to introduce inter-transaction dependencies to the queueing layer in client actor,
  51  * but that would require additional indirection and complexity.
  52  *
  53  * @author Robert Varga
  54  */
  55 @Beta
  56 public class ClientTransaction extends AbstractClientHandle<AbstractProxyTransaction> {
  57
  58     private ClientTransactionCursor cursor;
  59
  60     ClientTransaction(final AbstractClientHistory parent, final TransactionIdentifier transactionId) {
  61         super(parent, transactionId);
  62     }
  63
  64     private AbstractProxyTransaction createProxy(final Long shard) {
  65         return parent().createTransactionProxy(getIdentifier(), shard);
  66     }
  67
  68     private AbstractProxyTransaction ensureTransactionProxy(final YangInstanceIdentifier path) {
  69         return ensureProxy(path, this::createProxy);
  70     }
  71
  72     public DOMDataTreeWriteCursor openCursor() {
  73         Preconditions.checkState(cursor == null, "Transaction %s has open cursor", getIdentifier());
  74         cursor = new ClientTransactionCursor(this);
  75         return cursor;
  76     }
  77
  78     public CheckedFuture<Boolean, ReadFailedException> exists(final YangInstanceIdentifier path) {
  79         return ensureTransactionProxy(path).exists(path);
  80     }
  81
  82     public CheckedFuture<Optional<NormalizedNode<?, ?>>, ReadFailedException> read(
  83             final YangInstanceIdentifier path) {
  84         return ensureTransactionProxy(path).read(path);
  85     }
  86
  87     public void delete(final YangInstanceIdentifier path) {
  88         ensureTransactionProxy(path).delete(path);
  89     }
  90
  91     public void merge(final YangInstanceIdentifier path, final NormalizedNode<?, ?> data) {
  92         ensureTransactionProxy(path).merge(path, data);
  93     }
  94
  95     public void write(final YangInstanceIdentifier path, final NormalizedNode<?, ?> data) {
  96         ensureTransactionProxy(path).write(path, data);
  97     }
  98
  99     public DOMStoreThreePhaseCommitCohort ready() {
 100         final Collection<AbstractProxyTransaction> toReady = ensureClosed();
 101         Preconditions.checkState(toReady != null, "Attempted to submit a closed transaction %s", this);
 102
 103         toReady.forEach(AbstractProxyTransaction::seal);
 104         final AbstractTransactionCommitCohort cohort;
 105         switch (toReady.size()) {
 106             case 0:
 107                 cohort = new EmptyTransactionCommitCohort(parent(), getIdentifier());
 108                 break;
 109             case 1:
 110                 cohort = new DirectTransactionCommitCohort(parent(), getIdentifier(),
 111                     Iterables.getOnlyElement(toReady));
 112                 break;
 113             default:
 114                 cohort = new ClientTransactionCommitCohort(parent(), getIdentifier(), toReady);
 115                 break;
 116         }
 117
 118         return parent().onTransactionReady(this, cohort);
 119     }
 120
 121     void closeCursor(@Nonnull final DOMDataTreeCursor cursorToClose) {
 122         if (cursorToClose.equals(this.cursor)) {
 123             this.cursor = null;
 124         }
 125     }
 126 }