String performance and maintenability

[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / clustering / EntityOwnershipListener.java

diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipListener.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipListener.java
index 96b9ec2e5f3ab7f6153db6d8dfaf0454362ec25c..2aa20b2352280300d993c98bb5df3064f5969254 100644 (file)
--- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipListener.java
+++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/clustering/EntityOwnershipListener.java
@@ -9,17 +9,32 @@
 package org.opendaylight.controller.md.sal.common.api.clustering;
 
 /**
- * An EntityOwnershipListener is a component that represents a listener for entity ownership changes
+ * An EntityOwnershipListener is a component that represents a listener for entity ownership changes.
+ *
+ * @deprecated Use org.opendaylight.mdsal.binding.api.clustering.EntityOwnershipListener or
+ *             org.opendaylight.mdsal.dom.api.clustering.DOMEntityOwnershipListener instead
  */
+@Deprecated
 public interface EntityOwnershipListener {
 
     /**
-     * A notification that is generated when the ownership status for a given entity changes in the current process.
+     * A notification that is generated when the ownership status of an entity changes.
      *
-     * @param entity the entity whose ownership status has changed
-     * @param wasOwner true if this process was the owner of the given entity right before this notification
-     *                 was generated
-     * @param isOwner true if this process now owns the given entity
+     * <p>
+     * The following outlines valid combinations of the ownership status flags in the EntityOwnershipChange
+     * parameter and their meanings:
+     * <ul>
+     * <li><b>wasOwner = false, isOwner = true, hasOwner = true</b> - this process has been granted ownership</li>
+     * <li><b>wasOwner = true, isOwner = false, hasOwner = true</b> - this process was the owner but ownership
+     *     transitioned to another process</li>
+     * <li><b>wasOwner = false, isOwner = false, hasOwner = true</b> - ownership transitioned to another process
+     *     and this process was not the previous owner</li>
+     * <li><b>wasOwner = false, isOwner = false, hasOwner = false</b> - the entity no longer has any candidates and
+     *     thus no owner and this process was not the previous owner</li>
+     * <li><b>wasOwner = true, isOwner = false, hasOwner = false</b> - the entity no longer has any candidates and
+     *     thus no owner and this process was the previous owner</li>
+     * </ul>
+     * @param ownershipChange contains the entity and its ownership status flags
      */
-    void ownershipChanged(Entity entity, boolean wasOwner, boolean isOwner);
+    void ownershipChanged(EntityOwnershipChange ownershipChange);
 }