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 package org.opendaylight.mdsal.singleton.dom.impl;
   9
  10 import com.google.common.util.concurrent.ListenableFuture;
  11 import org.eclipse.jdt.annotation.Nullable;
  12 import org.opendaylight.mdsal.eos.common.api.CandidateAlreadyRegisteredException;
  13 import org.opendaylight.mdsal.eos.common.api.EntityOwnershipStateChange;
  14 import org.opendaylight.mdsal.eos.common.api.GenericEntity;
  15 import org.opendaylight.mdsal.singleton.common.api.ClusterSingletonService;
  16 import org.opendaylight.mdsal.singleton.common.api.ClusterSingletonServiceRegistration;
  17 import org.opendaylight.yangtools.concepts.HierarchicalIdentifier;
  18 import org.opendaylight.yangtools.concepts.Identifiable;
  19
  20 /**
  21  * {@link ClusterSingletonServiceGroup} maintains a group of {@link ClusterSingletonService} instances.
  22  * All EntityOwnershipChange notifications have to applied to all registered services at the same time in the same
  23  * manner. All registered services have only one instantiated service instance in a cluster at one time on same
  24  * Cluster Node. This is realized via a double candidate approach where a service group instance maintains a candidate
  25  * registration for ownership of the service entity in the cluster and also a registration that acts as a guard to
  26  * ensure a service group instance has fully closed prior to relinquishing service ownership. To achieve ownership
  27  * of the service group, a service group candidate must hold ownership of both these entities.
  28  *
  29  * @param <P> the instance identifier path type
  30  * @param <E> the GenericEntity type
  31  */
  32 abstract class ClusterSingletonServiceGroup<P extends HierarchicalIdentifier<P>, E extends GenericEntity<P>>
  33         implements Identifiable<String> {
  34     /**
  35      * This method must be called once on startup to initialize this group and
  36      * register the relevant group entity candidate. It means create relevant
  37      * Group Entity Candidate Registration.
  38      */
  39     abstract void initialize() throws CandidateAlreadyRegisteredException;
  40
  41     /**
  42      * This method registers a service instance for this service group. If the local node has
  43      * ownership of the service group, the {@link ClusterSingletonService#instantiateServiceInstance()}
  44      * method is called. Otherwise, the method is called once the local node gains ownership.
  45      *
  46      * @param service instance
  47      */
  48     abstract void registerService(ClusterSingletonServiceRegistration reg);
  49
  50     /**
  51      * Method provides possibility to restart some service from group without change
  52      * leadership for whole group. {@link ClusterSingletonServiceRegistration#close()}
  53      * implementation has to call this service.
  54      * Candidates are signed for group, so unregistration for group with one service
  55      * has to trigger new election only otherwise we can see same behavior as on server
  56      * without clustering.
  57      *
  58      * @param service instance
  59      * @return Future which completes when this instance is shutdown if this was the last registration, null otherwise
  60      */
  61     abstract @Nullable ListenableFuture<?> unregisterService(ClusterSingletonServiceRegistration reg);
  62
  63     /**
  64      * Method implementation has to apply ownershipChange for all registered services.
  65      *
  66      * @param entity the entity whose ownership status changed
  67      * @param change the change the entity underwent
  68      * @param inJeopardy {@code true} if ownership is in jeopardy and the reported change may be inaccurate
  69      */
  70     abstract void ownershipChanged(E entity, EntityOwnershipStateChange change, boolean inJeopardy);
  71
  72     /**
  73      * Closes this service group. All registered service providers are also closed. Please be careful
  74      * and use this method without active EOS listener only.
  75      *
  76      * @return {@link ListenableFuture} in list for all Future from closing {@link ClusterSingletonService}
  77      */
  78     abstract ListenableFuture<?> closeClusterSingletonGroup();
  79 }
  80