From: Robert Varga Date: Tue, 11 Mar 2014 18:20:00 +0000 (+0100) Subject: Bug 500: DOMStore SPI X-Git-Tag: autorelease-tag-v20140601202136_82eb3f9~307^2 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=745c204dc183898a6909c09bfcfbcadd5017133d Bug 500: DOMStore SPI This is the API which needs to be implemented by a single logical tree store, such that it can be plugged into the in-memory datastore prototype. The prototype keeps one logical data store for each of operational and configuration subtrees. A front-end (client-visible) transaction results in two back-end (data store) transactions. State transitions between the three are coordinated using three-phase-commit protocol (3PC), with the frontend transaction acting as the coordinator and the backend transactions acting as cohorts. Change-Id: Idfce04553e7c36ae6a1bb8c8b2699ca78c458bb4 Signed-off-by: Tony Tkacik Signed-off-by: Robert Varga --- 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 new file mode 100644 index 0000000000..c82a2b855f --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStore.java @@ -0,0 +1,60 @@ +/* + * 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; + +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.yangtools.concepts.ListenerRegistration; +import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +public interface DOMStore { + + /** + * + * Creates a read only transaction + * + * @return + */ + DOMStoreReadTransaction newReadOnlyTransaction(); + + /** + * Creates write only transaction + * + * @return + */ + DOMStoreWriteTransaction newWriteOnlyTransaction(); + + /** + * Creates Read-Write transaction + * + * @return + */ + DOMStoreReadWriteTransaction newReadWriteTransaction(); + + /** + * 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. + * + * @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. + * + */ + >> ListenerRegistration registerChangeListener( + InstanceIdentifier path, L listener, DataChangeScope scope); + +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadTransaction.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadTransaction.java new file mode 100644 index 0000000000..733c10926c --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadTransaction.java @@ -0,0 +1,37 @@ +/* + * 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; + +import java.util.concurrent.Future; + +import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +import com.google.common.base.Optional; +import com.google.common.util.concurrent.ListenableFuture; + +public interface DOMStoreReadTransaction extends DOMStoreTransaction { + + /** + * + * Reads data from provided logical data store located at provided path + * + * + * @param path + * Path which uniquely identifies subtree which client want to + * read + * @return Listenable Future which contains read result + *
    + *
  • If data at supplied path exists the {@link Future#get()} + * returns Optional object containing data + *
  • If data at supplied path does not exists the + * {@link Future#get()} returns {@link Optional#absent()}. + *
+ */ + ListenableFuture>> read(InstanceIdentifier path); +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadWriteTransaction.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadWriteTransaction.java new file mode 100644 index 0000000000..72774062f4 --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreReadWriteTransaction.java @@ -0,0 +1,15 @@ +/* + * 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; + +/** + * Combination of a {@link DOMStoreReadTransaction} and {@link DOMStoreWriteTransaction}. + */ +public interface DOMStoreReadWriteTransaction extends DOMStoreReadTransaction, DOMStoreWriteTransaction { + +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreThreePhaseCommitCohort.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreThreePhaseCommitCohort.java new file mode 100644 index 0000000000..986a153efb --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreThreePhaseCommitCohort.java @@ -0,0 +1,62 @@ +/* + * 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; + +import com.google.common.util.concurrent.ListenableFuture; + +/** + * Interface implemented by the {@link DOMStore} and exposed for each {@link DOMStoreWriteTransaction} + * upon its transition to Ready state. The frontend (DOMStore user) uses this interface to drive the + * commit procedure across potentially multiple DOMStores using the Three-Phase-Commit (3PC) Protocol, + * as described in {@link https://en.wikipedia.org/wiki/Three-phase_commit}. + */ +public interface DOMStoreThreePhaseCommitCohort { + + /** + * Sends transaction associated with this three phase commit instance to the + * participant, participant votes on the transaction, if the transaction + * should be committed or aborted. + * + * @return ListenableFuture with vote of the participant. Vote + * {@link ListenableFuture#get()} is following: + *
    + *
  • + * true if transaction is approved by data store. + *
  • false if the transaction is not approved by data store and + * should be aborted. + */ + ListenableFuture canCommit(); + + /** + * Initiates a pre-commit phase of associated transaction on datastore. + * + * This message is valid only and only if and only if the participant responded + * on {@link #canCommit()} call with positive response. + * + * @return ListenableFuture representing acknowledgment for participant + * that pre-commit message was received and processed. + */ + ListenableFuture preCommit(); + + /** + * Initiates a abort phase of associated transaction on data store. + * + * @return ListenableFuture representing acknowledgment for participant + * that abort message was received. + */ + ListenableFuture abort(); + + /** + * Initiates a commit phase on of associated transaction on data store. + * + * @return ListenableFuture representing acknowledgment for participant + * that commit message was received and commit of transaction was + * processed. + */ + ListenableFuture commit(); +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransaction.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransaction.java new file mode 100644 index 0000000000..76ea78b299 --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreTransaction.java @@ -0,0 +1,28 @@ +/* + * 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; + +import org.opendaylight.yangtools.concepts.Identifiable; + +/** + * DOM Data Store transaction + * + * See {@link DOMStoreReadTransaction}, {@link DOMStoreWriteTransaction} and {@link DOMStoreReadWriteTransaction} + * for specific transaction types. + * + */ +public interface DOMStoreTransaction extends AutoCloseable, Identifiable { + /** + * Unique identifier of the transaction + */ + @Override + public Object getIdentifier(); + + @Override + void close(); +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreWriteTransaction.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreWriteTransaction.java new file mode 100644 index 0000000000..6761bc1968 --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/DOMStoreWriteTransaction.java @@ -0,0 +1,57 @@ +/* + * 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; + +import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType; +import org.opendaylight.yangtools.concepts.Path; +import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +public interface DOMStoreWriteTransaction extends DOMStoreTransaction { + + /** + * Store a provided data at specified path. This acts as a add / replace + * operation, which is to say that whole subtree will be replaced by + * specified path. + * + * If you need add or merge of current object with specified use + * {@link #merge(LogicalDatastoreType, Path, Object)} + * + * + * @param path + * @param data + * Data object to be written + * + * @throws IllegalStateException + * if the client code already sealed transaction and invoked + * {@link #ready()} + */ + void write(InstanceIdentifier path, NormalizedNode data); + + /** + * + * Deletes data and whole subtree located at provided path. + * + * @param path + * Path to delete + * @throws IllegalStateException + * if the client code already sealed transaction and invoked + * {@link #ready()} + */ + void delete(InstanceIdentifier path); + + /** + * + * Seals transaction, and returns three-phase commit cohort associated + * with this transaction and DOM Store to be coordinated by coordinator. + * + * @return Three Phase Commit Cohort instance for this transaction. + */ + DOMStoreThreePhaseCommitCohort ready(); + +} diff --git a/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/package-info.java b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/package-info.java new file mode 100644 index 0000000000..ec3b69813e --- /dev/null +++ b/opendaylight/md-sal/sal-dom-spi/src/main/java/org/opendaylight/controller/sal/core/spi/data/package-info.java @@ -0,0 +1,8 @@ +/* + * 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; \ No newline at end of file