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