handoff

Source processor that receives messages handed over from other flows.

A flow with a handoff source has no external endpoint and cannot be invoked directly by a client. It can receive messages only from a distribute or split processor in an upstream flow.

A handoff flow provides its own independent delivery guarantee. Each incoming message is persisted at the handoff source before processing begins in the target pipeline. This persistence enables redelivery and dead letter handling that are independent of the upstream flow. It also enables fast/slow flow isolation. By handing off processing to a separate flow, a slow target no longer limits the throughput of the upstream flow or other targets.

In most cases, a handoff flow should use exchangePattern = OneWay. Because the upstream flow hands off the message and continues independently, there is typically no need to wait for the target flow to complete processing.

Using RequestResponse with a handoff flow is uncommon and introduces significant additional complexity. For more information, see the details below:

The handoff flow will get two tiers of resilience: redelivery and dead letter handling.
Errors will be propagated from the handoff flow to the upstream flow.
Dead letter flows will be executed from both flows.
The total processing time of the upstream flow is affected by the processing time of the handoff. This means that the processing time of the handoff flow must be taken into consideration when configuring the redelivery timeout of the upstream flow.
Redelivery semantics become more complex in the following ways:
- If the propagateErrorTransience processor property is true, the handoff flow will report a transient failure back to the upstream flow after running out of redeliveries. This will then trigger redeliveries from the upstream flow, making the possible number of redeliveries to the handoff flow "upstream-redeliveries * handoff-redeliveries".
- If the propagateErrorTransience processor property is false (the default), the handoff flow will report a non-transient failure back to the upstream flow after running out of redeliveries. This will cause the upstream flow to stop redeliveries and fail with the non-transient error.

Properties

Name Summary

Name	Summary
`propagateErrorTransience`	Determines whether to mark errors as transient when they are propagated back to the upstream flow. This only applies to the rare case where a handoff flow uses the `RequestResponse` exchange pattern. Note that only transient errors will trigger message redeliveries.
`name`	Optional, descriptive name for the processor.
`id`	Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern `[a-zA-Z][a-zA-Z0-9_-]{2,29}`.
`exchangeProperties`	Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

propagateErrorTransience

Determines whether to mark errors as transient when they are propagated back to the upstream flow. This only applies to the rare case where a handoff flow uses the RequestResponse exchange pattern. Note that only transient errors will trigger message redeliveries.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

Sub-builders

Name	Summary
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.

Name

Summary

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

Details

Usage

Both the distribute and split processors support handing off messages to flows. Configure the handoff flow as follows:

flowConfig {
    id = "handoff-flow"
    description = "Message Handoff Flow"
    ownerId = "my-company"
    exchangePattern = FlowExchangePattern.OneWay

    handoff {
        id = "handoff-source"
    }

    restRequest {
        id = "send-http-request"
        defaultMethod = POST
        address = URL("https://my/url")
    }
}

In the main flow, reference the handoff flow as follows:

distribute {
    id = "distribute-message"
    flowId("handoff-flow")
}

For more information about using handoff flows with distribution and splitting patterns, see the Distribution and Splitting Collections sections of the flow design guide.

Was this page helpful?