Mass-migrate to java.util.Optional
[mdsal.git] / 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 javax.annotation.Nonnull;
12 import org.opendaylight.yangtools.concepts.Path;
13
14 /**
15  * <p>
16  * An interface that provides the means for a component/application to request ownership for a given
17  * Entity on the current cluster member. Entity ownership is always tied to a process and two components on the same
18  * process cannot register a candidate for a given Entity.
19  * </p>
20  * <p>
21  * A component/application may also register interest in the ownership status of an Entity. The listener would be
22  * notified whenever the ownership status changes.
23  * </p>
24  *
25  * @author Thomas Pantelis
26  *
27  * @param <P> the instance identifier path type
28  * @param <E> the GenericEntity type
29  */
30 public interface GenericEntityOwnershipService<P extends Path<P>, E extends GenericEntity<P>,
31         L extends GenericEntityOwnershipListener<P, ? extends GenericEntityOwnershipChange<P, E>>> {
32
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     GenericEntityOwnershipCandidateRegistration<P, E> registerCandidate(@Nonnull E entity)
47             throws CandidateAlreadyRegisteredException;
48
49     /**
50      * Registers a listener that is interested in ownership changes for entities of the given entity type. The
51      * listener is notified whenever its process instance is granted ownership of the entity and also whenever
52      * it loses ownership. On registration the listener will be notified of all entities its process instance
53      * currently owns at the time of registration.
54      *
55      * @param entityType the type of entities whose ownership status the Listener is interested in
56      * @param listener the listener that is interested in the entities
57      * @return a registration object that can be used to unregister the Listener
58      */
59     GenericEntityOwnershipListenerRegistration<P, L> registerListener(@Nonnull String entityType, @Nonnull L listener);
60
61     /**
62      * Gets the current ownership state information for an entity.
63      *
64      * @param forEntity the entity to query.
65      * @return an Optional EntityOwnershipState whose instance is present if the entity is found
66      */
67     Optional<EntityOwnershipState> getOwnershipState(@Nonnull E forEntity);
68
69     /**
70      * Checks if a local candidate is registered for the given entity.
71      *
72      * @param forEntity the entity to query.
73      * @return true if a candidate is registered locally, false otherwise
74      */
75     boolean isCandidateRegistered(@Nonnull E forEntity);
76 }