Add flow state machine extension tutorial

docs/source/example-code/src/integration-test/kotlin/net/corda/docs/TutorialFlowAsyncOperationTest.kt

@@ -0,0 +1,29 @@
+package net.corda.docs
+
+import net.corda.client.rpc.CordaRPCClient
+import net.corda.core.messaging.startFlow
+import net.corda.core.utilities.getOrThrow
+import net.corda.docs.tutorial.flowstatemachines.ExampleSummingFlow
+import net.corda.node.services.Permissions
+import net.corda.testing.core.ALICE_NAME
+import net.corda.testing.driver.DriverParameters
+import net.corda.testing.driver.driver
+import net.corda.testing.node.User
+import org.junit.Test
+import kotlin.test.assertEquals
+
+class TutorialFlowAsyncOperationTest {
+    // DOCSTART summingWorks
+    @Test
+    fun summingWorks() {
+        driver(DriverParameters(startNodesInProcess = true)) {
+            val aliceUser = User("aliceUser", "testPassword1", permissions = setOf(Permissions.all()))
+            val alice = startNode(providedName = ALICE_NAME, rpcUsers = listOf(aliceUser)).getOrThrow()
+            val aliceClient = CordaRPCClient(alice.rpcAddress)
+            val aliceProxy = aliceClient.start("aliceUser", "testPassword1").proxy
+            val answer = aliceProxy.startFlow(::ExampleSummingFlow).returnValue.getOrThrow()
+            assertEquals(3, answer)
+        }
+    }
+    // DOCEND summingWorks
+}

docs/source/example-code/src/main/kotlin/net/corda/docs/tutorial/flowstatemachines/TutorialFlowAsyncOperation.kt

@@ -0,0 +1,38 @@
+package net.corda.docs.tutorial.flowstatemachines
+
+import co.paralleluniverse.fibers.Suspendable
+import net.corda.core.concurrent.CordaFuture
+import net.corda.core.flows.FlowLogic
+import net.corda.core.flows.StartableByRPC
+import net.corda.core.internal.FlowAsyncOperation
+import net.corda.core.internal.concurrent.doneFuture
+import net.corda.core.internal.concurrent.openFuture
+import net.corda.core.internal.executeAsync
+
+// DOCSTART SummingOperation
+class SummingOperation(val a: Int, val b: Int) : FlowAsyncOperation<Int> {
+    override fun execute(): CordaFuture<Int> {
+        return doneFuture(a + b)
+    }
+}
+// DOCEND SummingOperation
+
+// DOCSTART SummingOperationThrowing
+class SummingOperationThrowing(val a: Int, val b: Int) : FlowAsyncOperation<Int> {
+    override fun execute(): CordaFuture<Int> {
+        throw IllegalStateException("You shouldn't be calling me")
+    }
+}
+// DOCEND SummingOperationThrowing
+
+// DOCSTART ExampleSummingFlow
+@StartableByRPC
+class ExampleSummingFlow : FlowLogic<Int>() {
+    @Suspendable
+    override fun call(): Int {
+        val answer = executeAsync(SummingOperationThrowing(1, 2))
+        return answer // hopefully 3
+    }
+}
+// DOCEND ExampleSummingFlow
+