Bump versions to 4.0.0-SNAPSHOT
[controller.git] / opendaylight / md-sal / cds-dom-api / src / main / java / org / opendaylight / controller / cluster / dom / api / CDSShardAccess.java
1 /*
2  * Copyright (c) 2016 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.controller.cluster.dom.api;
9
10 import com.google.common.annotations.Beta;
11 import java.util.concurrent.CompletionStage;
12 import org.eclipse.jdt.annotation.NonNull;
13 import org.opendaylight.mdsal.dom.api.DOMDataTreeIdentifier;
14
15 /**
16  * Unprivileged access interface to shard information. Provides read-only access to operational details about a CDS
17  * shard.
18  *
19  * @author Robert Varga
20  */
21 @Beta
22 @Deprecated(forRemoval = true)
23 public interface CDSShardAccess {
24     /**
25      * Return the shard identifier.
26      *
27      * @return Shard identifier.
28      * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated
29      *         {@link CDSDataTreeProducer} is no longer valid.
30      */
31     @NonNull DOMDataTreeIdentifier getShardIdentifier();
32
33     /**
34      * Return the shard leader location relative to the local node.
35      *
36      * @return Shard leader location.
37      * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated
38      *         {@link CDSDataTreeProducer} is no longer valid.
39      */
40     @NonNull LeaderLocation getLeaderLocation();
41
42     /**
43      * Request the shard leader to be moved to the local node. The request will be evaluated against shard state and
44      * satisfied if leader movement is possible. If current shard policy or state prevents the movement from happening,
45      * the returned {@link CompletionStage} will report an exception.
46      *
47      * <p>
48      * This is a one-time operation, which does not prevent further movement happening in future. Even if this request
49      * succeeds, there is no guarantee that the leader will remain local in face of failures, shutdown or any future
50      * movement requests from other nodes.
51      *
52      * <p>
53      * Note that due to asynchronous nature of CDS, the leader may no longer be local by the time the returned
54      * {@link CompletionStage} reports success.
55      *
56      * @return A {@link CompletionStage} representing the request.
57      * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated
58      *         {@link CDSDataTreeProducer} is no longer valid.
59      */
60     @NonNull CompletionStage<Void> makeLeaderLocal();
61
62     /**
63      * Register a listener to shard location changes. Each listener object can be registered at most once.
64      *
65      * @param listener Listener object
66      * @return A {@link LeaderLocationListenerRegistration} for the listener.
67      * @throws IllegalArgumentException if the specified listener is already registered.
68      * @throws IllegalStateException if the {@link CDSDataTreeProducer} from which the associated
69      *         {@link CDSDataTreeProducer} is no longer valid.
70      * @throws NullPointerException if listener is null.
71      */
72     @NonNull <L extends LeaderLocationListener> LeaderLocationListenerRegistration<L> registerLeaderLocationListener(
73             @NonNull L listener);
74 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.