dom/mdsal-dom-broker/src/main/java/org/opendaylight/mdsal/dom/broker/AbstractDOMForwardedTransactionFactory.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.mdsal.dom.broker;
   9
  10 import static com.google.common.base.Preconditions.checkState;
  11 import static java.util.Objects.requireNonNull;
  12
  13 import com.google.common.util.concurrent.FluentFuture;
  14 import java.lang.invoke.MethodHandles;
  15 import java.lang.invoke.VarHandle;
  16 import java.util.EnumMap;
  17 import java.util.Map;
  18 import org.eclipse.jdt.annotation.NonNull;
  19 import org.opendaylight.mdsal.common.api.CommitInfo;
  20 import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
  21 import org.opendaylight.mdsal.common.api.TransactionCommitFailedException;
  22 import org.opendaylight.mdsal.dom.api.DOMDataTreeReadTransaction;
  23 import org.opendaylight.mdsal.dom.api.DOMDataTreeReadWriteTransaction;
  24 import org.opendaylight.mdsal.dom.api.DOMDataTreeWriteTransaction;
  25 import org.opendaylight.mdsal.dom.spi.store.DOMStoreThreePhaseCommitCohort;
  26 import org.opendaylight.mdsal.dom.spi.store.DOMStoreTransactionFactory;
  27 import org.opendaylight.mdsal.dom.spi.store.DOMStoreWriteTransaction;
  28 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  29 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  30 import org.slf4j.Logger;
  31 import org.slf4j.LoggerFactory;
  32
  33 /**
  34  * Abstract composite transaction factory.
  35  *
  36  * <p>
  37  * Provides a convenience common implementation for composite DOM Transactions, where subtransaction is identified by
  38  * {@link LogicalDatastoreType} type and implementation of subtransaction is provided by
  39  * {@link DOMStoreTransactionFactory}.
  40  *
  41  * <b>Note:</b>This class does not have thread-safe implementation of  {@link #close()}, implementation may allow
  42  * accessing and allocating new transactions during closing this instance.
  43  *
  44  * @param <T> Type of {@link DOMStoreTransactionFactory} factory.
  45  */
  46 abstract class AbstractDOMForwardedTransactionFactory<T extends DOMStoreTransactionFactory> implements AutoCloseable {
  47     private static final Logger LOG = LoggerFactory.getLogger(AbstractDOMForwardedTransactionFactory.class);
  48     private static final VarHandle CLOSED;
  49
  50     static {
  51         try {
  52             CLOSED = MethodHandles.lookup()
  53                 .findVarHandle(AbstractDOMForwardedTransactionFactory.class, "closed", boolean.class);
  54         } catch (NoSuchFieldException | IllegalAccessException e) {
  55             throw new ExceptionInInitializerError(e);
  56         }
  57     }
  58
  59     private final Map<LogicalDatastoreType, T> storeTxFactories;
  60
  61     private volatile boolean closed;
  62
  63     protected AbstractDOMForwardedTransactionFactory(final Map<LogicalDatastoreType, ? extends T> txFactories) {
  64         checkState(!txFactories.isEmpty(), "txFactories should not be empty.");
  65         this.storeTxFactories = new EnumMap<>(txFactories);
  66     }
  67
  68     /**
  69      * Implementations must return unique identifier for each and every call of this method.
  70      *
  71      * @return new Unique transaction identifier.
  72      */
  73     protected abstract Object newTransactionIdentifier();
  74
  75     /**
  76      * User-supplied implementation of {@link DOMDataTreeWriteTransaction#commit()} for transaction.
  77      *
  78      * <p>
  79      * Callback invoked when {@link DOMDataTreeWriteTransaction#commit()} is invoked on transaction created by this
  80      * factory.
  81      *
  82      * @param transaction Transaction on which {@link DOMDataTreeWriteTransaction#commit()} was invoked.
  83      * @param cohort      Subtransactions associated with the transaction being committed.
  84      * @return a FluentFuture. if commit coordination on cohorts finished successfully, a CommitInfo is returned from
  85      *     the Future, On failure, the Future fails with a {@link TransactionCommitFailedException}.
  86      */
  87     protected abstract FluentFuture<? extends CommitInfo> commit(DOMDataTreeWriteTransaction transaction,
  88             DOMStoreThreePhaseCommitCohort cohort);
  89
  90     /**
  91      * Creates a new forwarded read-only transaction.
  92      *
  93      * <p>
  94      * Creates a new read-only transaction backed by single read-only sub-transaction.
  95      * Target datastore is determined dynamically on first usage.
  96      *
  97      * <p>
  98      * Sub-transaction for reading is selected by supplied {@link LogicalDatastoreType} as parameter for
  99      * {@link DOMDataTreeReadTransaction#read(LogicalDatastoreType, YangInstanceIdentifier)}
 100      *
 101      * <p>
 102      * Identifier of returned transaction is retrieved via {@link #newTransactionIdentifier()}.
 103      *
 104      * @return New composite read-only transaction.
 105      */
 106     public final DOMDataTreeReadTransaction newReadOnlyTransaction() {
 107         checkNotClosed();
 108         return new DOMForwardedReadOnlyTransaction(newTransactionIdentifier(),
 109             storeType -> requireTxFactory(storeType).newReadOnlyTransaction());
 110     }
 111
 112     /**
 113      * Creates a new forwarded write-only transaction
 114      *
 115      * <p>
 116      * Creates a new write-only transaction backed by single write-only sub-transaction.
 117      * Target datastore is determined dynamically on first usage.
 118      *
 119      * <p>
 120      * Implementation of composite Write-only transaction is following:
 121      *
 122      * <ul>
 123      * <li>{@link DOMDataTreeWriteTransaction#put(LogicalDatastoreType, YangInstanceIdentifier, NormalizedNode)}
 124      *     - backing subtransaction is selected by {@link LogicalDatastoreType},
 125      *       {@link DOMStoreWriteTransaction#write(YangInstanceIdentifier, NormalizedNode)} is invoked on selected
 126      *       subtransaction.</li>
 127      * <li> {@link DOMDataTreeWriteTransaction#merge(LogicalDatastoreType, YangInstanceIdentifier, NormalizedNode)}
 128      *      - backing subtransaction is selected by {@link LogicalDatastoreType},
 129      *        {@link DOMStoreWriteTransaction#merge(YangInstanceIdentifier, NormalizedNode)} is invoked on selected
 130      *        subtransaction.</li>
 131      * <li>{@link DOMDataTreeWriteTransaction#delete(LogicalDatastoreType, YangInstanceIdentifier)}
 132      *     - backing subtransaction is selected by {@link LogicalDatastoreType},
 133      *       {@link DOMStoreWriteTransaction#delete(YangInstanceIdentifier)} is invoked on selected subtransaction.
 134      * <li>{@link DOMDataTreeWriteTransaction#commit()} - results in invoking {@link DOMStoreWriteTransaction#ready()},
 135      *     gathering resulting cohort and then invoking finalized implementation callback
 136      *     {@link #commit(DOMDataTreeWriteTransaction, DOMStoreThreePhaseCommitCohort)} with transaction which
 137      *     was committed and gathered results.</li>
 138      * </ul>
 139      *
 140      * <p>
 141      * Identifier of returned transaction is generated via {@link #newTransactionIdentifier()}.
 142      *
 143      * @return New composite write-only transaction associated with this factory.
 144      */
 145     public final DOMDataTreeWriteTransaction newWriteOnlyTransaction() {
 146         checkNotClosed();
 147         return new DOMForwardedWriteTransaction<>(newTransactionIdentifier(),
 148             storeType -> requireTxFactory(storeType).newWriteOnlyTransaction(), this);
 149     }
 150
 151     /**
 152      * Creates a new forwarded read-write transaction.
 153      *
 154      * @return New forwarded read-write transaction associated with this factory.
 155      */
 156     public final DOMDataTreeReadWriteTransaction newReadWriteTransaction() {
 157         checkNotClosed();
 158         return new DOMForwardedReadWriteTransaction(newTransactionIdentifier(),
 159             storeType -> requireTxFactory(storeType).newReadWriteTransaction(), this);
 160     }
 161
 162     /**
 163      * Convenience accessor of backing factories intended to be used only by finalization of this class.
 164      *
 165      * <b>Note:</b> Finalization of this class may want to access other functionality of supplied Transaction factories.
 166      *
 167      * @return Map of backing transaction factories.
 168      */
 169     protected final Map<LogicalDatastoreType, T> getTxFactories() {
 170         return storeTxFactories;
 171     }
 172
 173     private @NonNull T requireTxFactory(final LogicalDatastoreType type) {
 174         final var factory = storeTxFactories.get(requireNonNull(type));
 175         if (factory == null) {
 176             throw new IllegalArgumentException("Unsupported datastore type " + type);
 177         }
 178         return factory;
 179     }
 180
 181     /**
 182      * Checks if instance is not closed.
 183      *
 184      * @throws IllegalStateException If instance of this class was closed.
 185      */
 186     protected final void checkNotClosed() {
 187         checkState(!closed, "Transaction factory was closed. No further operations allowed.");
 188     }
 189
 190     @Override
 191     public void close() {
 192         if (!CLOSED.compareAndSet(this, false, true)) {
 193             LOG.warn("Transaction factory was already closed", new Throwable());
 194         }
 195     }
 196 }