Package net.corda.v5.application.messaging

Interface FlowMessaging

  • All Implemented Interfaces:
    @DoNotImplement() 
public interface FlowMessaging

    FlowMessaging allows a flow to initiate and communicate with one or more 3rd party flows.

    The platform will provide an instance of FlowMessaging to flows via property injection.

    A Flow can initiate one or more flows other counterparties within the network, when a new flow is initiated a FlowSession is created. The FlowSession represents the connection to an initiated flow and can be used to send and receive data between the two flows.

    Example usage:

    • Kotlin:
      
class MyFlow : ClientStartableFlow {
   
   lateinit var flowMessaging: FlowMessaging

   override fun call(requestBody: RestRequestBody): String {
       val counterparty = parse("CN=Alice, O=Alice Corp, L=LDN, C=GB")

       val session = flowMessaging.initiateFlow(counterparty)

       val result = session.sendAndReceive<String>("hello")

       session.close()

       return result
   }
 }
    • Java:
      
class MyFlow implements ClientStartableFlow {

   
   public FlowMessaging flowMessaging;

   
   public String call(RestRequestBody requestBody) {
       MemberX500Name counterparty = MemberX500Name.parse("CN=Alice, O=Alice Corp, L=LDN, C=GB");
       FlowSession session = flowMessaging.initiateFlow(counterparty);

       String result = session.sendAndReceive(String.class, "hello");

       session.close();

       return result;
   }
}

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Constructor Detail

    • Method Detail

      • initiateFlow

        @Suspendable()@NotNull() abstract FlowSession initiateFlow(@NotNull() MemberX500Name x500Name)

        Creates a communication session with a counterparty's ResponderFlow. Subsequently, you may send/receive using this session object. Note that this function does not communicate in itself. The counter-flow will be kicked off by the first send/receive.

        Initiated flows are initiated with context based on the context of the initiating flow at the point in time this method is called. The context of the initiating flow is snapshotted by the returned session. Altering the flow context has no effect on the context of the session after this point, and therefore it has no effect on the context of the initiated flow either.

        Parameters:
        x500Name - The X500 name of the member to communicate with.

      • initiateFlow

        @Suspendable()@NotNull() abstract FlowSession initiateFlow(@NotNull() MemberX500Name x500Name, boolean requireClose)

        Creates a communication session with a counterparty's ResponderFlow. Subsequently, you may send/receive using this session object. Note that this function does not communicate in itself. The counter-flow will be kicked off by the first send/receive.

        Initiated flows are initiated with context based on the context of the initiating flow at the point in time this method is called. The context of the initiating flow is snapshotted by the returned session. Altering the flow context has no effect on the context of the session after this point, and therefore it has no effect on the context of the initiated flow either.

        Parameters:
        x500Name - The X500 name of the member to communicate with.
        requireClose - When set to true, the initiated party will send a close message after calling FlowSession.close() and the initiating party will suspend and wait to receive the message when they call FlowSession.close().

      • initiateFlow

        @Suspendable()@NotNull() abstract FlowSession initiateFlow(@NotNull() MemberX500Name x500Name, @NotNull() FlowContextPropertiesBuilder flowContextPropertiesBuilder)

        Creates a communication session with another member. Subsequently, you may send/receive using this session object. Note that this function does not communicate in itself. The counter-flow will be kicked off by the first send/receive.

        This overload takes a builder of context properties. Any properties set or modified against the context passed to this builder will be propagated to initiated flows and all that flow's initiated flows and sub flows down the stack. The properties passed to the builder are pre-populated with the current flow context properties, see FlowContextProperties. Altering the current flow context has no effect on the context of the session after the builder is applied and the session returned by this method, and therefore it has no effect on the context of the initiated flow either.

        Example of use in Kotlin. ```Kotlin val flowSession = flowMessaging.initiateFlow(virtualNodeName) { flowContextProperties -> flowContextProperties["key"] = "value" } ``` Example of use in Java. ```Java FlowSession flowSession = flowMessaging.initiateFlow(virtualNodeName, (flowContextProperties) -> { flowContextProperties.put("key", "value"); }); ```

        Parameters:
        x500Name - The X500 name of the member to communicate with.
        flowContextPropertiesBuilder - A builder of context properties.

      • initiateFlow

        @Suspendable()@NotNull() abstract FlowSession initiateFlow(@NotNull() MemberX500Name x500Name, boolean requireClose, @NotNull() FlowContextPropertiesBuilder flowContextPropertiesBuilder)

        Creates a communication session with another member. Subsequently, you may send/receive using this session object. Note that this function does not communicate in itself. The counter-flow will be kicked off by the first send/receive.

        This overload takes a builder of context properties. Any properties set or modified against the context passed to this builder will be propagated to initiated flows and all that flow's initiated flows and sub flows down the stack. The properties passed to the builder are pre-populated with the current flow context properties, see FlowContextProperties. Altering the current flow context has no effect on the context of the session after the builder is applied and the session returned by this method, and therefore it has no effect on the context of the initiated flow either.

        Example of use in Kotlin. ```Kotlin val flowSession = flowMessaging.initiateFlow(virtualNodeName) { flowContextProperties -> flowContextProperties["key"] = "value" } ``` Example of use in Java. ```Java FlowSession flowSession = flowMessaging.initiateFlow(virtualNodeName, (flowContextProperties) -> { flowContextProperties.put("key", "value"); }); ```

        Parameters:
        x500Name - The X500 name of the member to communicate with.
        requireClose - When set to true, the initiated party will send a close message after calling FlowSession.close() and the initiating party will suspend and wait to receive the message when they call FlowSession.close().
        flowContextPropertiesBuilder - A builder of context properties.

      • receiveAll

        @Suspendable()@NotNull() abstract <R> List<R> receiveAll(@NotNull() Class<out R> receiveType, @NotNull() Set<FlowSession> sessions)

        Suspends until a message has been received for each session in the specified sessions.

        Consider receiveAllMap when sessions are expected to receive different types.

        The receiveType should be of a type that is annotated with @CordaSerializable or a primitive type. This function cannot handle types that do not meet these criteria.

        Parameters:
        receiveType - Type of object to be received for all sessions, which should be either a primitive type or a type annotated with @CordaSerializable.
        sessions - Set of sessions to receive from.

      • receiveAllMap

        @Suspendable()@NotNull() abstract Map<FlowSession, out Object> receiveAllMap(@NotNull() Map<FlowSession, Class<out Object>> sessions)

        Suspends until a message has been received for each session in the specified sessions.

        Consider receiveAll when the same type is expected from all sessions.

        The types of objects expected to be received should be annotated with @CordaSerializable or be a primitive type. This function cannot handle types that do not meet these criteria.

        Parameters:
        sessions - Map of session to the type of object that is expected to be received

      • sendAll

        @Suspendable() abstract void sendAll(@NotNull() Object payload, @NotNull() Set<FlowSession> sessions)

        Queues the given payload for sending to the provided sessions and continues without waiting for a response.

        Note that the other parties may receive the message at some arbitrary later point or not at all: if one of the provided [sessions] is offline then message delivery will be retried until the session expires. Sessions are deemed to be expired when this session stops receiving heartbeat messages from the counterparty within the configurable timeout.

        The payload object should be of a type that is annotated with @CordaSerializable or a primitive type. This function cannot handle types that do not meet these criteria.

        Parameters:
        payload - the payload to send, which should be either a primitive type or a type annotated with @CordaSerializable.
        sessions - the sessions to send the provided payload to.

      • sendAllMap

        @Suspendable() abstract void sendAllMap(@NotNull() Map<FlowSession, Object> payloadsPerSession)

        Queues the given payloads for sending to the provided sessions and continues without waiting for a response.

        Note that the other parties may receive the message at some arbitrary later point or not at all: if one of the provided [sessions] is offline then message delivery will be retried until the session expires. Sessions are deemed to be expired when this session stops receiving heartbeat messages from the counterparty within the configurable timeout.

        The objects in payloadsPerSession should be of types that are annotated with @CordaSerializable or be primitive types. This function cannot handle types that do not meet these criteria.

        Parameters:
        payloadsPerSession - a mapping that contains the payload to be sent to each session.