entityownership/mdsal-eos-common-api/src/main/java/org/opendaylight/mdsal/eos/common/api/GenericEntityOwnershipService.java

   1 /*
   2  * Copyright (c) 2015 Brocade Communications 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.eos.common.api;
   9
  10 import java.util.Optional;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.opendaylight.yangtools.concepts.HierarchicalIdentifier;
  13 import org.opendaylight.yangtools.concepts.Registration;
  14
  15 /**
  16  * <p>
  17  * An interface that provides the means for a component/application to request ownership for a given
  18  * Entity on the current cluster member. Entity ownership is always tied to a process and two components on the same
  19  * process cannot register a candidate for a given Entity.
  20  * </p>
  21  * <p>
  22  * A component/application may also register interest in the ownership status of an Entity. The listener would be
  23  * notified whenever the ownership status changes.
  24  * </p>
  25  *
  26  * @author Thomas Pantelis
  27  *
  28  * @param <P> the instance identifier path type
  29  * @param <E> the GenericEntity type
  30  */
  31 public interface GenericEntityOwnershipService<P extends HierarchicalIdentifier<P>, E extends GenericEntity<P>,
  32         L extends GenericEntityOwnershipListener<P, ? extends GenericEntityOwnershipChange<P, E>>> {
  33     /**
  34      * Registers a candidate for ownership of the given entity. Only one such request can be made per entity
  35      * per process. If multiple requests for registering a candidate for a given entity are received in the
  36      * current process a CandidateAlreadyRegisteredException will be thrown.
  37      *
  38      * <p>
  39      * The registration is performed asynchronously and any registered entity ownership listener is
  40      * notified of ownership status changes for the entity.
  41      *
  42      * @param entity the entity which the Candidate wants to own
  43      * @return a registration object that can be used to unregister the Candidate
  44      * @throws CandidateAlreadyRegisteredException if the candidate was already registered
  45      */
  46     @NonNull Registration registerCandidate(@NonNull E entity) throws CandidateAlreadyRegisteredException;
  47
  48     /**
  49      * Registers a listener that is interested in ownership changes for entities of the given entity type. The
  50      * listener is notified whenever its process instance is granted ownership of the entity and also whenever
  51      * it loses ownership. On registration the listener will be notified of all entities its process instance
  52      * currently owns at the time of registration.
  53      *
  54      * @param entityType the type of entities whose ownership status the Listener is interested in
  55      * @param listener the listener that is interested in the entities
  56      * @return a registration object that can be used to unregister the Listener
  57      */
  58     GenericEntityOwnershipListenerRegistration<P, L> registerListener(@NonNull String entityType, @NonNull L listener);
  59
  60     /**
  61      * Gets the current ownership state information for an entity.
  62      *
  63      * @param forEntity the entity to query.
  64      * @return an Optional EntityOwnershipState whose instance is present if the entity is found
  65      */
  66     Optional<EntityOwnershipState> getOwnershipState(@NonNull E forEntity);
  67
  68     /**
  69      * Checks if a local candidate is registered for the given entity.
  70      *
  71      * @param forEntity the entity to query.
  72      * @return true if a candidate is registered locally, false otherwise
  73      */
  74     boolean isCandidateRegistered(@NonNull E forEntity);
  75 }