singleton-service/mdsal-singleton-dom-impl/src/main/java/org/opendaylight/mdsal/singleton/dom/impl/ClusterSingletonServiceGroup.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
   9 package org.opendaylight.mdsal.singleton.dom.impl;
  10
  11 import com.google.common.util.concurrent.ListenableFuture;
  12 import java.util.List;
  13 import org.opendaylight.mdsal.eos.common.api.GenericEntity;
  14 import org.opendaylight.mdsal.eos.common.api.GenericEntityOwnershipChange;
  15 import org.opendaylight.mdsal.singleton.common.api.ClusterSingletonService;
  16 import org.opendaylight.mdsal.singleton.common.api.ClusterSingletonServiceRegistration;
  17 import org.opendaylight.yangtools.concepts.Path;
  18
  19 /**
  20  * {@link ClusterSingletonServiceGroup} maintains a group of {@link ClusterSingletonService}
  21  * instancies. All EntityOwnershipChange notifications have to applied to all registered
  22  * services at the same time in the same manner.
  23  * So this interface represents a single cluster service group instance." - remove this
  24  * sentence. All registered services have only one instantiated service instance in a cluster
  25  * at one time on same Cluster Node. This is realized via a double candidate approach where
  26  * a service group instance maintains a candidate registration for ownership of the service
  27  * entity in the cluster and also a registration that acts as a guard to ensure a service
  28  * group instance has fully closed prior to relinquishing service ownership. To achieve
  29  * ownership of the service group, a service group candidate must hold ownership
  30  * of both these entities.
  31  *
  32  * @param <P> the instance identifier path type
  33  * @param <E> the GenericEntity type
  34  * @param <C> the GenericEntityOwnershipChange type
  35  */
  36 interface ClusterSingletonServiceGroup<P extends Path<P>, E extends GenericEntity<P>,
  37                                        C extends GenericEntityOwnershipChange<P, E>> {
  38
  39     /**
  40      * This method must be called once on startup to initialize this group and
  41      * register the relevant group entity candidate. It means create relevant
  42      * Group Entity Candidate Registration.
  43      */
  44     void initializationClusterSingletonGroup();
  45
  46     /**
  47      * This method registers a service instance for this service group. If the local node has
  48      * ownership of the service group, the {@link ClusterSingletonService#instantiateServiceInstance()}
  49      * method is called. Otherwise, the method is called once the local node gains ownership.
  50      *
  51      * @param service instance
  52      * @return closable {@link ClusterSingletonServiceRegistration}
  53      */
  54     ClusterSingletonServiceRegistration registerService(ClusterSingletonService service);
  55
  56     /**
  57      * Method provides possibility to restart some service from group without change
  58      * leadership for whole group. {@link ClusterSingletonServiceRegistration#close()}
  59      * implementation has to call this service.
  60      * Candidates are signed for group, so unregistration for group with one service
  61      * has to trigger new election only otherwise we can see same behavior as on server
  62      * without clustering.
  63      *
  64      * @param service instance
  65      */
  66     void unregisterService(ClusterSingletonService service);
  67
  68     /**
  69      * Method implementation has to apply ownershipChange for all registred services.
  70      *
  71      * @param ownershipChange change role for ClusterSingletonServiceGroup
  72      */
  73     void ownershipChanged(final C ownershipChange);
  74
  75     /**
  76      * Closes this service group. All registered service providers are also closed.
  77      *
  78      * @return {@link ListenableFuture} in list for all Future from closing {@link ClusterSingletonService}
  79      */
  80     ListenableFuture<List<Void>> closeClusterSingletonGroup();
  81
  82 }
  83