From: Robert Varga Date: Tue, 27 Dec 2016 16:57:18 +0000 (+0100) Subject: BUG-7407: Introduce API to request shard leader movement X-Git-Tag: release/carbon~276 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=212081e3f3f8b88b15e2cf1c0d6fd96cb260fe22 BUG-7407: Introduce API to request shard leader movement There are some applications which would really want to control shard leader location, so their producers talk to the local leader and do not cross boundaries if not necessary. Change-Id: I6c789d91b78d42f325890e36725d03892ae4a23f Signed-off-by: Robert Varga --- diff --git a/features/mdsal/features-mdsal/src/main/features/features.xml b/features/mdsal/features-mdsal/src/main/features/features.xml index 1ba88d395b..6aa7798d80 100644 --- a/features/mdsal/features-mdsal/src/main/features/features.xml +++ b/features/mdsal/features-mdsal/src/main/features/features.xml @@ -87,6 +87,7 @@ odl-mdsal-clustering-commons mvn:org.opendaylight.controller/cds-access-api/{{VERSION}} mvn:org.opendaylight.controller/cds-access-client/{{VERSION}} + mvn:org.opendaylight.controller/cds-dom-api/{{VERSION}} mvn:org.opendaylight.controller/sal-distributed-datastore/{{VERSION}} mvn:org.opendaylight.controller/sal-cluster-admin-api/{{VERSION}} mvn:org.opendaylight.controller/sal-cluster-admin-impl/{{VERSION}} diff --git a/features/mdsal/odl-mdsal-distributed-datastore/pom.xml b/features/mdsal/odl-mdsal-distributed-datastore/pom.xml index 9ff7adf043..a78a755c24 100644 --- a/features/mdsal/odl-mdsal-distributed-datastore/pom.xml +++ b/features/mdsal/odl-mdsal-distributed-datastore/pom.xml @@ -56,6 +56,10 @@ ${project.groupId} cds-access-client + + ${project.groupId} + cds-dom-api + ${project.groupId} sal-distributed-datastore @@ -69,4 +73,4 @@ sal-cluster-admin-impl - \ No newline at end of file + diff --git a/opendaylight/md-sal/cds-dom-api/pom.xml b/opendaylight/md-sal/cds-dom-api/pom.xml new file mode 100644 index 0000000000..bcd28a509a --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/pom.xml @@ -0,0 +1,81 @@ + + + 4.0.0 + + + org.opendaylight.odlparent + bundle-parent + 1.8.0-SNAPSHOT + + + + org.opendaylight.controller + cds-dom-api + 1.1.0-SNAPSHOT + bundle + + + + + org.opendaylight.yangtools + yangtools-artifacts + 1.1.0-SNAPSHOT + pom + import + + + org.opendaylight.mdsal + mdsal-artifacts + 2.2.0-SNAPSHOT + pom + import + + + + + + + com.google.guava + guava + + + com.typesafe.akka + akka-actor_${scala.version} + + + + org.opendaylight.yangtools + concepts + + + org.opendaylight.mdsal + mdsal-dom-api + + + + + + + org.apache.maven.plugins + maven-checkstyle-plugin + + checkstyle.violationSeverity=error + + + + org.codehaus.mojo + findbugs-maven-plugin + + true + + + + + + + scm:git:http://git.opendaylight.org/gerrit/controller.git + scm:git:ssh://git.opendaylight.org:29418/controller.git + HEAD + https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Architecture:Clustering + + diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSDataTreeProducer.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSDataTreeProducer.java new file mode 100644 index 0000000000..0d54235aa3 --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSDataTreeProducer.java @@ -0,0 +1,40 @@ +/* + * Copyright (c) 2016 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.dom.api; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; +import org.opendaylight.mdsal.dom.api.DOMDataTreeIdentifier; +import org.opendaylight.mdsal.dom.api.DOMDataTreeProducer; + +/** + * An extension to {@link DOMDataTreeProducer}, which allows users access + * to information about the backing shard. + * + * @author Robert Varga + */ +@Beta +public interface CDSDataTreeProducer extends DOMDataTreeProducer { + /** + * Return a {@link CDSShardAccess} handle. This handle will remain valid + * as long as this producer is operational. Returned handle can be accessed + * independently from this producer and is not subject to the usual access + * restrictions imposed on DOMDataTreeProducer state. + * + * @param subtree One of the subtrees to which are currently under control of this producer + * @return A shard access handle. + * @throws NullPointerException when subtree is null + * @throws IllegalArgumentException if the specified subtree is not controlled by this producer + * @throws IllegalStateException if this producer is no longer operational + * @throws IllegalThreadStateException if the access rules to this producer + * are violated, for example if this producer is bound and this thread + * is currently not executing from a listener context. + */ + @Nonnull CDSShardAccess getShardAccess(@Nonnull DOMDataTreeIdentifier subtree); +} + diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSShardAccess.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSShardAccess.java new file mode 100644 index 0000000000..d08b99a50f --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/CDSShardAccess.java @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2016 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.dom.api; + +import com.google.common.annotations.Beta; +import java.util.concurrent.CompletionStage; +import javax.annotation.Nonnull; +import org.opendaylight.mdsal.dom.api.DOMDataTreeIdentifier; + +/** + * Unprivileged access interface to shard information. Provides read-only access to operational details about a CDS + * shard. + * + * @author Robert Varga + */ +@Beta +public interface CDSShardAccess { + /** + * Return the shard identifier. + * + * @return Shard identifier. + * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated + * {@link CDSDataTreeProducer} is no longer valid. + */ + @Nonnull DOMDataTreeIdentifier getShardIdentifier(); + + /** + * Return the shard leader location relative to the local node. + * + * @return Shard leader location. + * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated + * {@link CDSDataTreeProducer} is no longer valid. + */ + @Nonnull LeaderLocation getLeaderLocation(); + + /** + * Request the shard leader to be moved to the local node. The request will be evaluated against shard state and + * satisfied if leader movement is possible. If current shard policy or state prevents the movement from happening, + * the returned {@link CompletionStage} will report an exception. + * + *

+ * This is a one-time operation, which does not prevent further movement happening in future. Even if this request + * succeeds, there is no guarantee that the leader will remain local in face of failures, shutdown or any future + * movement requests from other nodes. + * + *

+ * Note that due to asynchronous nature of CDS, the leader may no longer be local by the time the returned + * {@link CompletionStage} reports success. + * + * @return A {@link CompletionStage} representing the request. + * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated + * {@link CDSDataTreeProducer} is no longer valid. + */ + @Nonnull CompletionStage makeLeaderLocal(); + + /** + * Register a listener to shard location changes. Each listener object can be registered at most once. + * + * @param listener Listener object + * @return A {@link LeaderLocationListenerRegistration} for the listener. + * @throws IllegalArgumentException if the specified listener is already registered. + * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated + * {@link CDSDataTreeProducer} is no longer valid. + * @throws NullPointerException if listener is null. + */ + @Nonnull LeaderLocationListenerRegistration registerLeaderLocationListener( + @Nonnull L listener); +} diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocation.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocation.java new file mode 100644 index 0000000000..696fec2753 --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocation.java @@ -0,0 +1,33 @@ +/* + * Copyright (c) 2016 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.dom.api; + +import com.google.common.annotations.Beta; + +/** + * Enumeration of possible shard leader locations relative to the local node. + * + * @author Robert Varga + */ +@Beta +public enum LeaderLocation { + /** + * The leader is co-located on this node. + */ + LOCAL, + /** + * The leader is resident on a different node. + */ + REMOTE, + /** + * The leader is residence is currently unknown. This is a transition state during a leader failure, which can be + * caused by a network partition. This state is not observed during a leadership transfer vote initiated by + * the leader shutting down. + */ + UNKNOWN, +} diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListener.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListener.java new file mode 100644 index 0000000000..489539a688 --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListener.java @@ -0,0 +1,27 @@ +/* + * Copyright (c) 2016 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.dom.api; + +import com.google.common.annotations.Beta; +import java.util.EventListener; +import javax.annotation.Nonnull; + +/** + * Listener for shard leader location changes. + * + * @author Robert Varga + */ +@Beta +public interface LeaderLocationListener extends EventListener { + /** + * Invoked when shard leader location changes. + * + * @param location Current leader location as known by the local node. + */ + void onLeaderLocationChanged(@Nonnull LeaderLocation location); +} diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListenerRegistration.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListenerRegistration.java new file mode 100644 index 0000000000..61f6426af5 --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/LeaderLocationListenerRegistration.java @@ -0,0 +1,23 @@ +/* + * Copyright (c) 2016 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.dom.api; + +import com.google.common.annotations.Beta; +import org.opendaylight.yangtools.concepts.ListenerRegistration; + +/** + * Registration of a {@link LeaderLocationListener}. + * + * @author Robert Varga + * + * @param Listener type + */ +@Beta +public interface LeaderLocationListenerRegistration extends ListenerRegistration { + +} diff --git a/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/package-info.java b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/package-info.java new file mode 100644 index 0000000000..5c65801573 --- /dev/null +++ b/opendaylight/md-sal/cds-dom-api/src/main/java/org/opendaylight/controller/cluster/dom/api/package-info.java @@ -0,0 +1,12 @@ +/* + * Copyright (c) 2016 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 + */ +/** + * This package defines extensions to org.opendaylight.mdsal.dom.api specific + * to Clustered Datastore implementation. + */ +package org.opendaylight.controller.cluster.dom.api; diff --git a/opendaylight/md-sal/mdsal-artifacts/pom.xml b/opendaylight/md-sal/mdsal-artifacts/pom.xml index a2b6a9c89f..b7ce936dd3 100644 --- a/opendaylight/md-sal/mdsal-artifacts/pom.xml +++ b/opendaylight/md-sal/mdsal-artifacts/pom.xml @@ -215,6 +215,11 @@ sal-cluster-admin-impl ${project.version} + + org.opendaylight.controller + cds-dom-api + 1.1.0-SNAPSHOT + diff --git a/opendaylight/md-sal/pom.xml b/opendaylight/md-sal/pom.xml index dc504ad720..865675258f 100644 --- a/opendaylight/md-sal/pom.xml +++ b/opendaylight/md-sal/pom.xml @@ -80,6 +80,7 @@ sal-clustering-commons cds-access-api cds-access-client + cds-dom-api sal-clustering-config diff --git a/opendaylight/md-sal/sal-distributed-datastore/pom.xml b/opendaylight/md-sal/sal-distributed-datastore/pom.xml index e8c927f3fd..b0e92c87f1 100644 --- a/opendaylight/md-sal/sal-distributed-datastore/pom.xml +++ b/opendaylight/md-sal/sal-distributed-datastore/pom.xml @@ -110,6 +110,10 @@ org.opendaylight.controller cds-access-client + + org.opendaylight.controller + cds-dom-api + org.opendaylight.controller sal-akka-raft-example