Package net.corda.v5.application.messaging

Interface FlowSession

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

    A FlowSession is a handle on a communication sequence between two paired flows, possibly running on separate nodes.

    It is used to send and receive messages between the flows as well as to query information about the counter-flow. Sessions have their own local flow context which can be accessed via getContextProperties. Note that the parent context is snapshotted at the point getContextProperties is first accessed, after which no other changes to the parent context will be reflected in them. See getContextProperties for more information.

    There are two ways of obtaining such a session:

    • Calling initiateFlow. This will create a FlowSession object on which the first send/receive operation will attempt to kick off a corresponding ResponderFlow flow on the counterpart's node.
    • As constructor parameter to ResponderFlow flows. This session is the one corresponding to the initiating flow and may be used for replies.

    • 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

      • getCounterpartyFlowInfo

        @Suspendable()@NotNull() abstract FlowInfo getCounterpartyFlowInfo()

        Returns a [FlowInfo] object describing the flow which the [counterparty] is running. With [FlowInfo.protocolVersion] it provides the necessary information needed for the evolution of flows and enabling backwards compatibility. This method can be called before any send or receive has been done with [counterparty]. In such a case this will force them to start their flow.

      • getContextProperties

        @NotNull() abstract FlowContextProperties getContextProperties()

        Session local FlowContextProperties.

        If this session is part of an initiating flow, i.e. was obtained from FlowMessaging then this is a read only set of context properties which will be used to determine context on the initiated side. Modifying this set is only possible when session are initiated, see FlowMessaging.

        If this session was passed to an initiated flow by Corda, the context properties are associated with the initiating flow at the other end of the connection. They differ from the FlowContextProperties available to all flows via the FlowEngine in that they are not a description of the context of the currently executing flow, but instead the flow which initiated it.

        Any calls to modify these contextProperties will throw a CordaRuntimeException, they should be considered immutable.

      • sendAndReceive

        @Suspendable()@NotNull() abstract <R> R sendAndReceive(@NotNull() Class<R> receiveType, @NotNull() Object payload)

        Serializes and queues the given payload object for sending to getCounterparty. Suspends until a response is received, which must be of the given receiveType.

        Note that this function is not just a simple send and receive pair. It is more efficient and more correct to use sendAndReceive when you expect to do a message swap rather than use send and then receive.

        Both the payload object and 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 - The data type received from the counterparty.
        payload - The data sent to the counterparty, which should be either a primitive type or a type annotated with @CordaSerializable.

      • receive

        @Suspendable()@NotNull() abstract <R> R receive(@NotNull() Class<R> receiveType)

        Suspends until a message of type is received from .

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

        Parameters:
        receiveType - The data type received from the counterparty, which should be either a primitive type or a type annotated with @CordaSerializable.

      • send

        @Suspendable() abstract void send(@NotNull() Object payload)

        Queues the given payload for sending to getCounterparty and continues without suspending.

        Note that the other party may receive the message at some arbitrary later point or not at all: if getCounterparty is offline then message delivery will be retried until it comes back or until the message is older than the network's event horizon time.

        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 data sent to the counterparty, which should be either a primitive type or a type annotated with @CordaSerializable.

      • close

        @Suspendable() abstract void close()

        Closes this session and performs cleanup of any resources tied to this session.

        Note that sessions are closed automatically when the corresponding top-level flow terminates.

        So, it's beneficial to eagerly close them in long-lived flows that might have many open sessions that are not needed anymore and consume resources (e.g. memory, disk etc.).

        A closed session cannot be used anymore, e.g. to send or receive messages. So, you have to ensure you are calling this method only when the session is not going to be used anymore. As a result, any operations on a closed session will fail with an CordaRuntimeException.

        When a session is closed, the other side is informed and the session is closed there too eventually.