import org.opendaylight.yangtools.concepts.Path;
/**
- * A chain of transactions. Transactions in a chain need to be committed in sequence and each
- * transaction should see the effects of previous transactions as if they happened. A chain
- * makes no guarantees of atomicity, in fact transactions are committed as soon as possible.
+ * A chain of transactions. Transactions in a chain need to be committed in
+ * sequence and each transaction should see the effects of previous committed transactions
+ * as they occurred. A chain makes no guarantees of atomicity across the chained transactions -
+ * the transactions are committed as soon as possible in the order that they were submitted.
*
+ * This behaviour is different from the default AsyncDataBroker, where a
+ * transaction is always created from the current global state, not taking into
+ * account any transactions previously committed by the calling thread. Due to
+ * the asynchronous nature of transaction submission this can lead to surprising
+ * results. If a thread executes the following sequence sufficiently quickly:
+ *
+ * AsyncWriteTransaction t1 = broker.newWriteOnlyTransaction();
+ * t1.put(id, data);
+ * t1.submit();
+ *
+ * AsyncReadTransaction t2 = broker.newReadOnlyTransaction();
+ * Optional<?> maybeData = t2.read(id).get();
+ *
+ * it may happen, that it sees maybeData.isPresent() == false, simply because
+ * t1 has not completed the processes of being applied and t2 is actually
+ * allocated from the previous state. This is obviously bad for users who create
+ * incremental state in the datastore and actually read what they write in
+ * subsequent transactions.
+ *
+ * Using a TransactionChain instead of a broker solves this particular problem,
+ * and leads to expected behavior: t2 will always see the data written in t1
+ * present.
*/
-public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable, AsyncDataTransactionFactory<P, D> {
+public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable,
+ AsyncDataTransactionFactory<P, D> {
/**
* Create a new read only transaction which will continue the chain.
- * The previous read-write transaction has to be either COMMITED or CANCELLED.
+ *
+ * <p>
+ * The previous write transaction has to be either SUBMITTED
+ * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
+ * ({@link #close close} was invoked).
+ * <p>
+ * The returned read-only transaction presents an isolated view of the data if the previous
+ * write transaction was successful - in other words, this read-only transaction will see the
+ * state changes made by the previous write transaction in the chain. However, state which
+ * was introduced by other transactions outside this transaction chain after creation of
+ * the previous transaction is not visible.
*
* @return New transaction in the chain.
- * @throws IllegalStateException if the previous transaction was not COMMITED
- * or CANCELLED.
- * @throws TransactionChainClosedException if the chain has been closed.
+ * @throws IllegalStateException
+ * if the previous transaction was not SUBMITTED or CANCELLED.
+ * @throws TransactionChainClosedException
+ * if the chain has been closed.
*/
@Override
public AsyncReadOnlyTransaction<P, D> newReadOnlyTransaction();
-
/**
- * Create a new read write transaction which will continue the chain.
- * The previous read-write transaction has to be either COMMITED or CANCELLED.
+ * Create a new read-write transaction which will continue the chain.
+ *
+ * <p>
+ * The previous write transaction has to be either SUBMITTED
+ * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
+ * ({@link #close close} was invoked).
+ * <p>
+ * The returned read-write transaction presents an isolated view of the data if the previous
+ * write transaction was successful - in other words, this read-write transaction will see the
+ * state changes made by the previous write transaction in the chain. However, state which
+ * was introduced by other transactions outside this transaction chain after creation of
+ * the previous transaction is not visible.
+ * <p>
+ * Committing this read-write transaction using {@link AsyncWriteTransaction#submit submit}
+ * will submit the state changes in this transaction to be visible to any subsequent
+ * transaction in this chain and also to any transaction outside this chain.
*
* @return New transaction in the chain.
- * @throws IllegalStateException if the previous transaction was not COMMITTED
- * or CANCELLED.
- * @throws TransactionChainClosedException if the chain has been closed.
+ * @throws IllegalStateException
+ * if the previous transaction was not SUBMITTED or CANCELLED.
+ * @throws TransactionChainClosedException
+ * if the chain has been closed.
*/
@Override
public AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
+ /**
+ * Create a new write-only transaction which will continue the chain.
+ *
+ * <p>
+ * The previous write transaction has to be either SUBMITTED
+ * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
+ * ({@link #close close} was invoked).
+ * <p>
+ * The returned write-only transaction presents an isolated view of the data if the previous
+ * write transaction was successful - in other words, this write-only transaction will see the
+ * state changes made by the previous write transaction in the chain. However, state which
+ * was introduced by other transactions outside this transaction chain after creation of
+ * the previous transaction is not visible.
+ * <p>
+ * Committing this write-only transaction using {@link AsyncWriteTransaction#submit submit}
+ * will submit the state changes in this transaction to be visible to any subsequent
+ * transaction in this chain and also to any transaction outside this chain.
+ *
+ * @return New transaction in the chain.
+ * @throws IllegalStateException
+ * if the previous transaction was not SUBMITTED or CANCELLED.
+ * @throws TransactionChainClosedException
+ * if the chain has been closed.
+ */
+ @Override
+ public AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
+
@Override
void close();
}
-
--- /dev/null
+/*
+ *
+ * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ *
+ */
+
+package org.opendaylight.controller.cluster.datastore;
+
+import org.junit.Assert;
+import org.junit.Test;
+import org.mockito.Mockito;
+import org.opendaylight.controller.cluster.datastore.utils.ActorContext;
+import org.opendaylight.controller.sal.core.spi.data.DOMStoreReadTransaction;
+import org.opendaylight.controller.sal.core.spi.data.DOMStoreReadWriteTransaction;
+import org.opendaylight.controller.sal.core.spi.data.DOMStoreTransaction;
+import org.opendaylight.controller.sal.core.spi.data.DOMStoreWriteTransaction;
+import org.opendaylight.yangtools.yang.model.api.SchemaContext;
+
+public class TransactionChainProxyTest {
+ ActorContext actorContext = Mockito.mock(ActorContext.class);
+ SchemaContext schemaContext = Mockito.mock(SchemaContext.class);
+ @Test
+ public void testNewReadOnlyTransaction() throws Exception {
+
+ DOMStoreTransaction dst = new TransactionChainProxy(actorContext, schemaContext).newReadOnlyTransaction();
+ Assert.assertTrue(dst instanceof DOMStoreReadTransaction);
+
+ }
+
+ @Test
+ public void testNewReadWriteTransaction() throws Exception {
+ DOMStoreTransaction dst = new TransactionChainProxy(actorContext, schemaContext).newReadWriteTransaction();
+ Assert.assertTrue(dst instanceof DOMStoreReadWriteTransaction);
+
+ }
+
+ @Test
+ public void testNewWriteOnlyTransaction() throws Exception {
+ DOMStoreTransaction dst = new TransactionChainProxy(actorContext, schemaContext).newWriteOnlyTransaction();
+ Assert.assertTrue(dst instanceof DOMStoreWriteTransaction);
+
+ }
+
+ @Test(expected=UnsupportedOperationException.class)
+ public void testClose() throws Exception {
+ new TransactionChainProxy(actorContext, schemaContext).close();
+ }
+}