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 /**
  12  * <p>
  13  * The EntityOwnershipService provides the means for a component/application to request ownership for a given
  14  * Entity on the current cluster member. Entity ownership is always tied to a process and two components on the same
  15  * process cannot register a candidate for a given Entity.
  16  * </p>
  17  * <p>
  18  * A component/application may also register interest in the ownership status of an Entity. The listener would be
  19  * notified whenever the ownership status changes.
  20  * </p>
  21  */
  22 public interface EntityOwnershipService {
  23
  24     /**
  25      * Registers as a Candidate that wants to own the given Entity. Only one such request can be made per process.
  26      * If multiple requests for registering a Candidate for a given Entity are received in the current process a
  27      * CandidateAlreadyRegisteredException will be thrown
  28      *
  29      * @param entity the entity which the Candidate wants to own
  30      * @param candidate the Candidate that wants to own the entity
  31      * @return a registration object that can be used to unregister the Candidate
  32      * @throws org.opendaylight.controller.md.sal.common.api.clustering.CandidateAlreadyRegisteredException
  33      */
  34     EntityOwnershipCandidateRegistration registerCandidate(Entity entity, EntityOwnershipCandidate candidate)
  35             throws CandidateAlreadyRegisteredException;
  36
  37     /**
  38      * Registers a Listener that is interested in the ownership status of the given Entity. On registration the Listener
  39      * will be notified of the ownership status of the given Entity at the time of registration.
  40      *
  41      * @param entity the Entity whose ownership status the Listener is interested in
  42      * @param listener the Listener that is interested in the entity
  43      * @return a registration object that can be used to unregister the Listener
  44      */
  45     EntityOwnershipListenerRegistration registerListener(Entity entity, EntityOwnershipListener listener);
  46
  47 }