Merge pull request #1803 from corda/mnesbit-CordaServices-startFlows

Start Flows from services

core/src/main/kotlin/net/corda/core/cordapp/Cordapp.kt

@@ -17,6 +17,7 @@ import java.net.URL
  * @property contractClassNames List of contracts
  * @property initiatedFlows List of initiatable flow classes
  * @property rpcFlows List of RPC initiable flows classes
+ * @property serviceFlows List of [CordaService] initiable flows classes
  * @property schedulableFlows List of flows startable by the scheduler
  * @property servies List of RPC services
  * @property serializationWhitelists List of Corda plugin registries
@@ -28,6 +29,7 @@ interface Cordapp {
     val contractClassNames: List<String>
     val initiatedFlows: List<Class<out FlowLogic<*>>>
     val rpcFlows: List<Class<out FlowLogic<*>>>
+    val serviceFlows:  List<Class<out FlowLogic<*>>>
     val schedulableFlows: List<Class<out FlowLogic<*>>>
     val services: List<Class<out SerializeAsToken>>
     val serializationWhitelists: List<SerializationWhitelist>

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

@@ -20,6 +20,10 @@ sealed class FlowInitiator : Principal {
     data class Peer(val party: Party) : FlowInitiator() {
         override fun getName(): String = party.name.toString()
     }
+    /** Started by a CordaService. */
+    data class Service(val serviceClassName: String) : FlowInitiator() {
+        override fun getName(): String = serviceClassName
+    }
     /** Started as scheduled activity. */
     data class Scheduled(val scheduledState: ScheduledStateRef) : FlowInitiator() {
         override fun getName(): String = "Scheduler"

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

@@ -0,0 +1,12 @@
+package net.corda.core.flows
+
+import kotlin.annotation.AnnotationTarget.CLASS
+
+/**
+ * Any [FlowLogic] which is to be started by the [AppServiceHub] interface from
+ * within a [CordaService] must have this annotation. If it's missing the
+ * flow will not be allowed to start and an exception will be thrown.
+ */
+@Target(CLASS)
+@MustBeDocumented
+annotation class StartableByService

core/src/main/kotlin/net/corda/core/internal/cordapp/CordappImpl.kt

@@ -12,6 +12,7 @@ data class CordappImpl(
         override val contractClassNames: List<String>,
         override val initiatedFlows: List<Class<out FlowLogic<*>>>,
         override val rpcFlows: List<Class<out FlowLogic<*>>>,
+        override val serviceFlows:  List<Class<out FlowLogic<*>>>,
         override val schedulableFlows: List<Class<out FlowLogic<*>>>,
         override val services: List<Class<out SerializeAsToken>>,
         override val serializationWhitelists: List<SerializationWhitelist>,

core/src/main/kotlin/net/corda/core/node/AppServiceHub.kt

@@ -0,0 +1,30 @@
+package net.corda.core.node
+
+import net.corda.core.flows.FlowLogic
+import net.corda.core.messaging.FlowHandle
+import net.corda.core.messaging.FlowProgressHandle
+import rx.Observable
+
+/**
+ * A [CordaService] annotated class requires a constructor taking a
+ * single parameter of type [AppServiceHub].
+ * With the [AppServiceHub] parameter a [CordaService] is able to access to privileged operations.
+ * In particular such a [CordaService] can initiate and track flows marked with [net.corda.core.flows.StartableByService].
+ */
+interface AppServiceHub : ServiceHub {
+
+    /**
+     * Start the given flow with the given arguments. [flow] must be annotated
+     * with [net.corda.core.flows.StartableByService].
+     * TODO it is assumed here that the flow object has an appropriate classloader.
+     */
+    fun <T> startFlow(flow: FlowLogic<T>): FlowHandle<T>
+
+    /**
+     * Start the given flow with the given arguments, returning an [Observable] with a single observation of the
+     * result of running the flow. [flow] must be annotated with [net.corda.core.flows.StartableByService].
+     * TODO it is assumed here that the flow object has an appropriate classloader.
+     */
+    fun <T> startTrackedFlow(flow: FlowLogic<T>): FlowProgressHandle<T>
+
+}

core/src/main/kotlin/net/corda/core/node/services/CordaService.kt

@@ -7,7 +7,7 @@ import kotlin.annotation.AnnotationTarget.CLASS
 
 /**
  * Annotate any class that needs to be a long-lived service within the node, such as an oracle, with this annotation.
- * Such a class needs to have a constructor with a single parameter of type [ServiceHub]. This constructor will be invoked
+ * Such a class needs to have a constructor with a single parameter of type [AppServiceHub]. This constructor will be invoked
  * during node start to initialise the service. The service hub provided can be used to get information about the node
  * that may be necessary for the service. Corda services are created as singletons within the node and are available
  * to flows via [ServiceHub.cordaService].