CORDA-311-post PR merged fixes (#2106)

* SSH server integration

core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt

@@ -348,6 +348,12 @@ abstract class FlowLogic<out T> {
         }
     }
 
+    /**
+     * Returns a pair of the current progress step index (as integer) in steps tree of current [progressTracker], and an observable
+     * of its upcoming changes.
+     *
+     * @return Returns null if this flow has no progress tracker.
+     */
     fun trackStepsTreeIndex(): DataFeed<Int, Int>? {
         // TODO this is not threadsafe, needs an atomic get-step-and-subscribe
         return progressTracker?.let {
@@ -355,6 +361,12 @@ abstract class FlowLogic<out T> {
         }
     }
 
+    /**
+     * Returns a pair of the current steps tree of current [progressTracker] as pairs of zero-based depth and stringified step
+     * label and observable of upcoming changes to the structure.
+     *
+     * @return Returns null if this flow has no progress tracker.
+     */
     fun trackStepsTree(): DataFeed<List<Pair<Int,String>>, List<Pair<Int,String>>>? {
         // TODO this is not threadsafe, needs an atomic get-step-and-subscribe
         return progressTracker?.let {

core/src/main/kotlin/net/corda/core/messaging/FlowHandle.kt

@@ -8,13 +8,17 @@ import rx.Observable
 
 /**
  * [FlowHandle] is a serialisable handle for the started flow, parameterised by the type of the flow's return value.
- *
- * @property id The started state machine's ID.
- * @property returnValue A [CordaFuture] of the flow's return value.
  */
 @DoNotImplement
 interface FlowHandle<A> : AutoCloseable {
+    /**
+     * The started state machine's ID.
+     */
     val id: StateMachineRunId
+
+    /**
+     * A [CordaFuture] of the flow's return value.
+     */
     val returnValue: CordaFuture<A>
 
     /**
@@ -25,15 +29,23 @@ interface FlowHandle<A> : AutoCloseable {
 
 /**
  * [FlowProgressHandle] is a serialisable handle for the started flow, parameterised by the type of the flow's return value.
- *
- * @property progress The stream of progress tracker events.
  */
 interface FlowProgressHandle<A> : FlowHandle<A> {
+    /**
+     * The stream of progress tracker events.
+     */
     val progress: Observable<String>
 
+    /**
+     * [DataFeed] of current step in the steps tree, see [ProgressTracker]
+     */
     val stepsTreeIndexFeed: DataFeed<Int, Int>?
 
+    /**
+     * [DataFeed] of current steps tree, see [ProgressTracker]
+     */
     val stepsTreeFeed: DataFeed<List<Pair<Int, String>>, List<Pair<Int, String>>>?
+
     /**
      * Use this function for flows whose returnValue and progress are not going to be used or tracked, so as to free up
      * server resources.

core/src/main/kotlin/net/corda/core/utilities/ProgressTracker.kt

@@ -99,6 +99,7 @@ class ProgressTracker(vararg steps: Step) {
             field = value
         }
 
+    /** The zero-bases index of the current step in a [allStepsLabels] list */
     var stepsTreeIndex: Int = -1
         private set(value) {
             field = value
@@ -226,6 +227,10 @@ class ProgressTracker(vararg steps: Step) {
      */
     val allSteps: List<Pair<Int, Step>> get() = _allStepsCache
 
+    /**
+     * A list of all steps label in this ProgressTracker and the children, with the indent level provided starting at zero.
+     * Note that UNSTARTED is never counted, and DONE is only counted at the calling level.
+     */
     val allStepsLabels: List<Pair<Int, String>> get() = _allStepsLabels()
 
     private var curChangeSubscription: Subscription? = null
@@ -245,8 +250,14 @@ class ProgressTracker(vararg steps: Step) {
      */
     val changes: Observable<Change> get() = _changes
 
+    /**
+     * An observable stream of changes to the [allStepsLabels]
+     */
     val stepsTreeChanges: Observable<List<Pair<Int,String>>> get() = _stepsTreeChanges
 
+    /**
+     * An observable stream of changes to the [stepsTreeIndex]
+     */
     val stepsTreeIndexChanges: Observable<Int> get() = _stepsTreeIndexChanges
 
     /** Returns true if the progress tracker has ended, either by reaching the [DONE] step or prematurely with an error */

core/src/test/kotlin/net/corda/core/utilities/ProgressTrackerTest.kt

@@ -98,7 +98,7 @@ class ProgressTrackerTest {
 
         val allSteps = pt.allSteps
 
-        //capture notifications
+        // Capture notifications.
         val stepsIndexNotifications = LinkedList<Int>()
         pt.stepsTreeIndexChanges.subscribe {
             stepsIndexNotifications += it
@@ -113,7 +113,7 @@ class ProgressTrackerTest {
             assertEquals(step, allSteps[pt.stepsTreeIndex].second)
         }
 
-        //travel tree
+        // Travel tree.
         pt.currentStep = SimpleSteps.ONE
         assertCurrentStepsTree(0, SimpleSteps.ONE)
 
@@ -126,7 +126,7 @@ class ProgressTrackerTest {
         pt.currentStep = SimpleSteps.THREE
         assertCurrentStepsTree(5, SimpleSteps.THREE)
 
-        //assert no structure changes and proper steps propagation
+        // Assert no structure changes and proper steps propagation.
         assertThat(stepsIndexNotifications).containsExactlyElementsOf(listOf(0, 1, 3, 5))
         assertThat(stepsTreeNotification).isEmpty()
     }
@@ -135,13 +135,13 @@ class ProgressTrackerTest {
     fun `structure changes are pushed down when progress trackers are added`() {
         pt.setChildProgressTracker(SimpleSteps.TWO, pt2)
 
-        //capture notifications
+        // Capture notifications.
         val stepsIndexNotifications = LinkedList<Int>()
         pt.stepsTreeIndexChanges.subscribe {
             stepsIndexNotifications += it
         }
 
-        //put current state as a first change for simplicity when asserting
+        // Put current state as a first change for simplicity when asserting.
         val stepsTreeNotification = mutableListOf(pt.allStepsLabels)
         println(pt.allStepsLabels)
         pt.stepsTreeChanges.subscribe {
@@ -164,7 +164,7 @@ class ProgressTrackerTest {
 
         assertCurrentStepsTree(9, SimpleSteps.FOUR)
 
-        //assert no structure changes and proper steps propagation
+        // Assert no structure changes and proper steps propagation.
         assertThat(stepsIndexNotifications).containsExactlyElementsOf(listOf(1, 6, 9))
         assertThat(stepsTreeNotification).hasSize(2) // 1 change + 1 our initial state
     }
@@ -173,13 +173,13 @@ class ProgressTrackerTest {
     fun `structure changes are pushed down when progress trackers are removed`() {
         pt.setChildProgressTracker(SimpleSteps.TWO, pt2)
 
-        //capture notifications
+        // Capture notifications.
         val stepsIndexNotifications = LinkedList<Int>()
         pt.stepsTreeIndexChanges.subscribe {
             stepsIndexNotifications += it
         }
 
-        //put current state as a first change for simplicity when asserting
+        // Put current state as a first change for simplicity when asserting.
         val stepsTreeNotification = mutableListOf(pt.allStepsLabels)
         pt.stepsTreeChanges.subscribe {
             stepsTreeNotification += it
@@ -199,9 +199,9 @@ class ProgressTrackerTest {
 
         assertCurrentStepsTree(2, BabySteps.UNOS)
 
-        //assert no structure changes and proper steps propagation
+        // Assert no structure changes and proper steps propagation.
         assertThat(stepsIndexNotifications).containsExactlyElementsOf(listOf(1, 4, 2))
-        assertThat(stepsTreeNotification).hasSize(2) // 1 change + 1 our initial state
+        assertThat(stepsTreeNotification).hasSize(2) // 1 change + 1 our initial state.
     }
 
     @Test