opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipService.java

   1 /*
   2  * Copyright (c) 2015 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.controller.md.sal.common.api.clustering;
  10
  11 import javax.annotation.Nonnull;
  12
  13 /**
  14  * <p>
  15  * The EntityOwnershipService provides the means for a component/application to request ownership for a given
  16  * Entity on the current cluster member. Entity ownership is always tied to a process and two components on the same
  17  * process cannot register a candidate for a given Entity.
  18  * </p>
  19  * <p>
  20  * A component/application may also register interest in the ownership status of an Entity. The listener would be
  21  * notified whenever the ownership status changes.
  22  * </p>
  23  */
  24 public interface EntityOwnershipService {
  25
  26     /**
  27      * Registers a candidate for ownership of the given entity. Only one such request can be made per entity
  28      * per process. If multiple requests for registering a candidate for a given entity are received in the
  29      * current process a CandidateAlreadyRegisteredException will be thrown.
  30      * <p>
  31      * The registration is performed asynchronously and the {@link EntityOwnershipCandidate} instance is
  32      * notified whenever its process instance is granted ownership of the entity and also whenever it loses
  33      * ownership. Note that the {@link EntityOwnershipCandidate} is not notified when another process instance
  34      * is granted ownership.
  35      *
  36      * @param entity the entity which the Candidate wants to own
  37      * @param candidate the Candidate that wants to own the entity
  38      * @return a registration object that can be used to unregister the Candidate
  39      * @throws org.opendaylight.controller.md.sal.common.api.clustering.CandidateAlreadyRegisteredException
  40      */
  41     EntityOwnershipCandidateRegistration registerCandidate(@Nonnull Entity entity, @Nonnull EntityOwnershipCandidate candidate)
  42             throws CandidateAlreadyRegisteredException;
  43
  44     /**
  45      * Registers a listener that is interested in ownership changes for entities of the given entity type. The
  46      * listener is notified whenever its process instance is granted ownership of the entity and also whenever
  47      * it loses ownership. On registration the listener will be notified of all entities its process instance
  48      * currently owns at the time of registration.
  49      *
  50      * @param entityType the type of entities whose ownership status the Listener is interested in
  51      * @param listener the listener that is interested in the entities
  52      * @return a registration object that can be used to unregister the Listener
  53      */
  54     EntityOwnershipListenerRegistration registerListener(@Nonnull String entityType, @Nonnull EntityOwnershipListener listener);
  55
  56 }