From 2e87ec417c4c268fc1ad5f66dd0a5c2b9224e6fc Mon Sep 17 00:00:00 2001 From: Tony Tkacik Date: Mon, 26 May 2014 12:03:23 +0200 Subject: [PATCH] Bug 1073: Introduced Transaction Chain to DOMStore APIs. Introduced concept of TransactionChain to DOMStore APIs. Decomposed DOMStore to DOMStoreTransactionFactory to allow factory methods reuse between DOMStoreTransactionChain and DOMStore itself. Change-Id: I186242e40e8ada098deb431b09db67707371af58 Signed-off-by: Tony Tkacik --- .../dom/store/impl/InMemoryDOMDataStore.java | 6 ++ .../sal/core/spi/data/DOMStore.java | 68 ++++++++------- .../spi/data/DOMStoreTransactionChain.java | 85 +++++++++++++++++++ .../spi/data/DOMStoreTransactionFactory.java | 69 +++++++++++++++ 4 files changed, 199 insertions(+), 29 deletions(-) create mode 100644 opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionChain.java create mode 100644 opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionFactory.java diff --git a/opendaylight/md-sal/sal-dom-broker/src/main/java/org/opendaylight/controller/md/sal/dom/store/impl/InMemoryDOMDataStore.java b/opendaylight/md-sal/sal-dom-broker/src/main/java/org/opendaylight/controller/md/sal/dom/store/impl/InMemoryDOMDataStore.java index 00df6580ef..d04be6b244 100644 --- a/opendaylight/md-sal/sal-dom-broker/src/main/java/org/opendaylight/controller/md/sal/dom/store/impl/InMemoryDOMDataStore.java +++ b/opendaylight/md-sal/sal-dom-broker/src/main/java/org/opendaylight/controller/md/sal/dom/store/impl/InMemoryDOMDataStore.java @@ -28,6 +28,7 @@ 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.DOMStoreThreePhaseCommitCohort; import org.opendaylight.controller.sal.core.spi.data.DOMStoreTransaction; +import org.opendaylight.controller.sal.core.spi.data.DOMStoreTransactionChain; import org.opendaylight.controller.sal.core.spi.data.DOMStoreWriteTransaction; import org.opendaylight.yangtools.concepts.AbstractListenerRegistration; import org.opendaylight.yangtools.concepts.Identifiable; @@ -80,6 +81,11 @@ public class InMemoryDOMDataStore implements DOMStore, Identifiable, Sch return new SnapshotBackedWriteTransaction(nextIdentifier(), dataTree.takeSnapshot(), this); } + @Override + public DOMStoreTransactionChain createTransactionChain() { + throw new UnsupportedOperationException("Not implemented yet."); + } + @Override public synchronized void onGlobalContextUpdated(final SchemaContext ctx) { dataTree.setSchemaContext(ctx); diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStore.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStore.java index c82a2b855f..138b726edb 100644 --- a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStore.java +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStore.java @@ -10,51 +10,61 @@ package org.opendaylight.controller.sal.core.spi.data; import org.opendaylight.controller.md.sal.common.api.data.AsyncDataBroker.DataChangeScope; import org.opendaylight.controller.md.sal.common.api.data.AsyncDataChangeListener; import org.opendaylight.controller.md.sal.common.api.data.DataChangeListener; +import org.opendaylight.controller.md.sal.common.api.data.TransactionChain; import org.opendaylight.yangtools.concepts.ListenerRegistration; import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier; import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; -public interface DOMStore { +/** + * DOM Data Store + * + *

+ * DOM Data Store provides transactional tree-like storage for YANG-modeled + * entities described by YANG schema and represented by {@link NormalizedNode}. + * + * Read and write access to stored data is provided only via transactions + * created using {@link #newReadOnlyTransaction()}, + * {@link #newWriteOnlyTransaction()} and {@link #newReadWriteTransaction()}, or + * by creating {@link TransactionChain}. + * + */ +public interface DOMStore extends DOMStoreTransactionFactory { /** + * Registers {@link DataChangeListener} for Data Change callbacks which will + * be triggered on the change of provided subpath. What constitutes a change + * depends on the @scope parameter. * - * Creates a read only transaction + * Listener upon registration receives an initial callback + * {@link AsyncDataChangeListener#onDataChanged(org.opendaylight.controller.md.sal.common.api.data.AsyncDataChangeEvent)} + * which contains stable view of data tree at the time of registration. * - * @return - */ - DOMStoreReadTransaction newReadOnlyTransaction(); - - /** - * Creates write only transaction + *  @param path Path (subtree identifier) on which client listener will be + * invoked. * - * @return - */ - DOMStoreWriteTransaction newWriteOnlyTransaction(); - - /** - * Creates Read-Write transaction + * @param listener + * Instance of listener which should be invoked on + * @param scope + * Scope of change which triggers callback. + * @return Listener Registration object, which client may use to close + * registration / interest on receiving data changes. * - * @return */ - DOMStoreReadWriteTransaction newReadWriteTransaction(); + >> ListenerRegistration registerChangeListener( + InstanceIdentifier path, L listener, DataChangeScope scope); /** - * Registers {@link DataChangeListener} for Data Change callbacks - * which will be triggered on the change of provided subpath. What - * constitutes a change depends on the @scope parameter. * - * Listener upon registration receives an initial callback - * {@link AsyncDataChangeListener#onDataChanged(org.opendaylight.controller.md.sal.common.api.data.AsyncDataChangeEvent)} - * which contains stable view of data tree at the time of registration. + * Creates new transaction chain. + * + * Transactions in a chain need to be committed in sequence and each + * transaction should see the effects of previous transactions as if they + * happened. * - * @param path Path (subtree identifier) on which client listener will be invoked. - * @param listener Instance of listener which should be invoked on - * @param scope Scope of change which triggers callback. - * @return Listener Registration object, which client may use to close registration - * / interest on receiving data changes. + * See {@link DOMStoreTransactionChain} for more information. * + * @return Newly created transaction chain. */ - >> ListenerRegistration registerChangeListener( - InstanceIdentifier path, L listener, DataChangeScope scope); + DOMStoreTransactionChain createTransactionChain(); } diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionChain.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionChain.java new file mode 100644 index 0000000000..5876c50d51 --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionChain.java @@ -0,0 +1,85 @@ +/* + * 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.sal.core.spi.data; + +/** + * A chain of transactions. Transactions in a chain need to be committed in + * sequence and each transaction must 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. + * + * + */ +public interface DOMStoreTransactionChain extends DOMStoreTransactionFactory, AutoCloseable { + + /** + * Create a new read only transaction which will continue the chain. The + * previous write transaction has to be either READY or CANCELLED. + * + * If previous write transaction was already commited to data store, new + * read-only transaction is same as obtained via {@link DOMStore#newReadOnlyTransaction()} + * and contains merged result of previous one and current state of data store. + * + * Otherwise read-only transaction presents isolated view as if previous read-write + * transaction was successful. State which was introduced by other transactions + * outside this transaction chain after creation of previous transaction is not visible. + * + * @return New transaction in the chain. + * @throws IllegalStateException + * if the previous transaction was not READY or CANCELLED, or + * if the chain has been closed. + */ + @Override + public DOMStoreReadTransaction newReadOnlyTransaction(); + + /** + * Create a new read write transaction which will continue the chain. The + * previous read-write transaction has to be either COMMITED or CANCELLED. + * + * If previous write transaction was already commited to data store, new + * read-write transaction is same as obtained via {@link DOMStore#newReadWriteTransaction()} + * and contains merged result of previous one and current state of data store. + * + * Otherwise read-write transaction presents isolated view as if previous read-write + * transaction was successful. State which was introduced by other transactions + * outside this transaction chain after creation of previous transaction is not visible. + * + * @return New transaction in the chain. + * @throws IllegalStateException + * if the previous transaction was not READY or CANCELLED, or + * if the chain has been closed. + */ + @Override + public DOMStoreReadWriteTransaction newReadWriteTransaction(); + + /** + * Create a new read write transaction which will continue the chain. The + * previous read-write transaction has to be either READY or CANCELLED. + * + * + * @return New transaction in the chain. + * @throws IllegalStateException + * if the previous transaction was not READY or CANCELLED, or + * if the chain has been closed. + */ + @Override + public DOMStoreWriteTransaction newWriteOnlyTransaction(); + + + /** + * Closes Transaction Chain. + * + * Close method of transaction chain does not guarantee that + * last alocated transaction is ready or was submitted. + * + * @throws IllegalStateException If any of the outstanding created transactions was not canceled or ready. + */ + @Override + public void close(); + +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionFactory.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionFactory.java new file mode 100644 index 0000000000..433d575cd1 --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransactionFactory.java @@ -0,0 +1,69 @@ +/* + * 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.sal.core.spi.data; + +/** + * Factory for DOM Store Transactions + * + *

+ * Factory provides method to construct read-only, read-write and write-only + * transactions, which may be used to retrieve and modify stored information in + * Underlying {@link DOMStore} or {@link DOMStoreTransactionChain}. + * + *

+ * See {@link DOMStore} or {@link DOMStoreTransactionChain} for concrete + * variations of this factory. + * + *

+ * Note: This interface is used only to define common functionality + * between {@link DOMStore} and {@link DOMStoreTransactionChain}, which + * further specify behaviour of returned transactions. + * + */ +public interface DOMStoreTransactionFactory { + + /** + * + * Creates a read only transaction + * + *

+ * Creates a new read-only transaction, which provides read access to + * snapshot of current state. + * + * See {@link DOMStoreReadTransaction} for more information. + * + * @return new {@link DOMStoreReadTransaction} + * @throws IllegalStateException + * If state of factory prevents allocating new transaction. + * + */ + DOMStoreReadTransaction newReadOnlyTransaction(); + + /** + * Creates write only transaction + * + *

+ * See {@link DOMStoreWriteTransaction} for more information. + * + * @return new {@link DOMStoreWriteTransaction} + * @throws IllegalStateException If state of factory prevents allocating new transaction. + */ + DOMStoreWriteTransaction newWriteOnlyTransaction(); + + /** + * Creates Read-Write transaction + * + *

+ * See {@link DOMStoreReadWriteTransaction} for more information. + * + * @return new {@link DOMStoreWriteTransaction} + * @throws IllegalStateException If state of factory prevents allocating new transaction. + */ + DOMStoreReadWriteTransaction newReadWriteTransaction(); + +} -- 2.36.6