LeadershipService: Support for a leaderBoard.

Change-Id: I0dd8267e104466ec65a2c67d23d1c4d923cad266

Change-Id: I6bc548510400eacabb12482f8fba1b7f2abb0604
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/Leadership.java b/core/api/src/main/java/org/onlab/onos/cluster/Leadership.java
index c370ab5..dbf36a5 100644
--- a/core/api/src/main/java/org/onlab/onos/cluster/Leadership.java
+++ b/core/api/src/main/java/org/onlab/onos/cluster/Leadership.java
@@ -11,12 +11,12 @@
 
     private final String topic;
     private final ControllerNode leader;
-    private final long term;
+    private final long epoch;
 
-    public Leadership(String topic, ControllerNode leader, long term) {
+    public Leadership(String topic, ControllerNode leader, long epoch) {
         this.topic = topic;
         this.leader = leader;
-        this.term = term;
+        this.epoch = epoch;
     }
 
     /**
@@ -36,16 +36,16 @@
     }
 
     /**
-     * The term number associated with this leadership.
-     * @return leadership term
+     * The epoch when the leadership was assumed.
+     * @return leadership epoch
      */
-    public long term() {
-        return term;
+    public long epoch() {
+        return epoch;
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(topic, leader, term);
+        return Objects.hash(topic, leader, epoch);
     }
 
     @Override
@@ -53,7 +53,7 @@
         return MoreObjects.toStringHelper(this.getClass())
             .add("topic", topic)
             .add("leader", leader)
-            .add("term", term)
+            .add("epoch", epoch)
             .toString();
     }
 }
\ No newline at end of file
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/LeadershipService.java b/core/api/src/main/java/org/onlab/onos/cluster/LeadershipService.java
index c9e336b..e70cc1f 100644
--- a/core/api/src/main/java/org/onlab/onos/cluster/LeadershipService.java
+++ b/core/api/src/main/java/org/onlab/onos/cluster/LeadershipService.java
@@ -17,14 +17,21 @@
 
 /**
  * Service for leader election.
- * Leadership contents are organized around topics. ONOS instance can join the
- * leadership race for a topic or withdraw from a race it has previously joined
- * Once in the race, the instance can get asynchronously notified
- * of leadership election results.
+ * Leadership contests are organized around topics. A instance can join the
+ * leadership race for a topic or withdraw from a race it has previously joined.
+ * Listeners can be added to receive notifications asynchronously for various
+ * leadership contests.
  */
 public interface LeadershipService {
 
     /**
+     * Gets the most recent leader for the topic.
+     * @param path topic
+     * @return node who is the leader, null if so such topic exists.
+     */
+    ControllerNode getLeader(String path);
+
+    /**
      * Joins the leadership contest.
      * @param path topic for which this controller node wishes to be a leader.
      */
diff --git a/core/api/src/main/java/org/onlab/onos/store/service/Lock.java b/core/api/src/main/java/org/onlab/onos/store/service/Lock.java
index cef7752..01682d1 100644
--- a/core/api/src/main/java/org/onlab/onos/store/service/Lock.java
+++ b/core/api/src/main/java/org/onlab/onos/store/service/Lock.java
@@ -76,6 +76,15 @@
     boolean isLocked();
 
     /**
+     * Returns the epoch for this lock.
+     * If this lock is currently locked i.e. isLocked() returns true, epoch signifies the logical time
+     * when the lock was acquired. The concept of epoch lets one come up with a global ordering for all
+     * lock acquisition events
+     * @return epoch
+     */
+     long epoch();
+
+    /**
      * Releases the lock.
      */
     void unlock();