Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.5)
  3. Develop Mule Applications
  4. Core Components

  5. Until Successful Scope

Until Successful Scope

The Until Successful scope executes processors within it, in order, until they all succeed or the scope exhausts the maximum number of retries. Until Successful runs synchronously. If any processor within the scope fails to connect or to produce a successful result, Until Successful retries all the processors within it, including the one that failed, until all configured retries are exhausted. If a retry succeeds, the scope proceeds to the next component. If the final retry does not succeed, Until Successful produces an error.

Routing is successful if no exception is raised or if the response matches an expression.

Common processes that use Until Successful include:

  • Dispatching to outbound endpoints, for example, when calling a remote web service that might have availability issues.

  • Executing a component method, for example, when executing on a Spring bean that may depend on unreliable resources.

  • Using a sub-flow to re-execute several actions until they all succeed.

Until Successful Scope Configuration

To configure an Until Successful scope, add the <until-successful> XML element inside an application flow.

You can configure the following attributes in the Until Successful scope:

Field XML Description

Max Retries

maxRetries

Specifies the maximum number of retries that are allowed. This attribute can be either a number or an expression that resolves to a number. An error message looks like this: Message: 'until-successful' retries exhausted. The Mule error type is MULE:RETRY_EXHAUSTED.

Milliseconds Between Retries

millisBetweenRetries

Specifies, in milliseconds, the minimum interval between two retries. The actual interval depends on the previous execution, but it should not exceed twice this number. The default value is 60000 milliseconds (one minute). This attribute can be either a number or an expression that resolves to a number.

Example Configuration of the Until Successful Scope

The following XML example configures a flow triggered by a Scheduler component and an Until Successful scope that executes an FTP Write operation:

<!-- FTP Connector config-->
<ftp:config name="FTP_Config" doc:name="FTP Config" >
  <ftp:connection workingDir="${ftp.dir}" host="${ftp.host}" />
</ftp:config>

<flow name="untilSuccessfulFlow" >
  <!-- Scheduler component to trigger the flow-->
  <scheduler doc:name="Scheduler" >
    <scheduling-strategy >
      <fixed-frequency frequency="15" timeUnit="SECONDS"/>
    </scheduling-strategy>
  </scheduler>
  <!-- Until Successful scope-->
  <until-successful maxRetries="5" doc:name="Until Successful" millisBetweenRetries="3000">
    <!-- FTP Write operation that executes as part of the Until Successful Scope -->
    <ftp:write doc:name="Write" config-ref="FTP_Config" path="/"/>
  </until-successful>
  <logger level="INFO" doc:name="File upload success" message="File upload success"/>
  <!-- Error Handler at flow level-->
  <error-handler>
    <on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" type="RETRY_EXHAUSTED">
      <logger level="INFO" doc:name="File upload failed" message="File upload failed"/>
    </on-error-continue>
  </error-handler>
</flow>

Behavior of the example application:

  • If the FTP Write operation fails

    The Until Successful scope retries the operation every 3000 milliseconds until the operation succeeds, with a limit of 5 retries. If the last execution fails, the scope throws a MULE:RETRY_EXHAUSTED error. Then, the <on-error-continue> handles the error and executes the Logger with the message: File upload failed.

    Before throwing MULE:RETRY_EXHAUSTED, Mule also logs each unsuccessful attempt to retry execution of the processors on the Mule event, for example:

    ERROR 2022-12-09 17:41:44,910 ... event: cdad31c0-782b-11ed-af21-147ddaaf4f97]
...UntilSuccessfulRouter: Retrying execution of event, attempt 1 of 5.
...
ERROR 2022-12-09 17:41:55,079 ... event: cdad31c0-782b-11ed-af21-147ddaaf4f97]
...UntilSuccessfulRouter: Retrying execution of event, attempt 5 of 5.

  • If the FTP Write operation executes successfully in any of the attempts

    The next processor after the Until Successful scope executes, in this case, the Logger showing the message: File upload success.

Variable Propagation

Every execution of the Until Successful scope starts with the same variables and values present before the execution of the block. New variables or modifications to already-existing variables while processing one element are not visible in the next execution (in case there is an error). If the execution finishes correctly, the variables (and payload) are propagated to the rest of the flow.

See also