Interface RetryingFuture<ResponseT> (2.31.1)

public interface RetryingFuture<ResponseT> extends ApiFuture<ResponseT>

Represents a retrying future. This is a facade hiding all the complications of an asynchronous/synchronous execution of a retriable task.

This interface is for advanced/internal use only.

Implements

ApiFuture<ResponseT>

Type Parameter

NameDescription
ResponseT

Methods

getAttemptResult()

public abstract ApiFuture<ResponseT> getAttemptResult()

Returns the current (active on the moment of the execution of this method) attempt result future, allowing to track progress of the retrying future execution.

Adding direct executor (same thread) callbacks to the future returned by this method is strongly not recommended, since the future is resolved under retrying future's internal lock and may affect the whole retrying process. Adding separate thread callbacks is ok.

This method is for internal/advanced use only.

The returned future completes right after the corresponding attempt which it tracks, so calling ApiFuture#get() is potentially a blocking operation. This method returns exactly same future object until it completes (meaning that the corresponding attempt has completed). If there is another attempt made after completion of the current attempt, the subsequent call to this method will return a new future which will track the new attempt.

In case if the whole retrying future is completed, this method returns the same result as the retrying future itself.

The returned future is non-cancellable, so calling ApiFuture#cancel(boolean) will have no effect and will always return false.

The number of attempt results may be (and usually is) lower than the number of actual attempts, since only a completed attempt has a result and not all attempts complete (some of the service attempts, needed for proper execution of the actual attempts).

For each execution the following invariants hold:

  • The future returned by this method completes soon after the attempt it tracks.
  • If it was the last attempt, the futures complete in the following order: 1) the attempt future; 2) the whole retrying future; 3) the attempt result future returned by this method.
  • After completion of the whole retrying future this method always returns exactly same future object.
Returns
TypeDescription
ApiFuture<ResponseT>

getAttemptSettings()

public abstract TimedAttemptSettings getAttemptSettings()

Returns current (active) attempt settings.

Returns
TypeDescription
TimedAttemptSettings

getCallable()

public abstract Callable<ResponseT> getCallable()

Returns callable tracked by this future.

Returns
TypeDescription
Callable<ResponseT>

peekAttemptResult()

public abstract ApiFuture<ResponseT> peekAttemptResult()

Returns latest completed attempt result or null if the first attempt hasn't completed yet.

This method is for internal/advanced use only.

If not null, the returned value is guaranteed to be an already completed future, so ApiFuture#isDone() will always be true and ApiFuture#get() will always be non-blocking.

In case if the whole retrying future is completed, this method returns the same result as the retrying future itself.

The number of attempt results may be (and usually is) lower than the number of actual attempts, since only a completed attempt has a result and not all attempts complete (some of the service attempts, needed for proper execution of the actual attempts).

For each execution the following invariants hold:

  • If the first attempt hasn't completed yet, this method returns null.
  • Right after completion of each attempt this method starts returning a new already completed future, which represents the result of the latest completed attempt.
  • If it was the last attempt, the events happen in the following order: 1) the attempt future completes; 2) the whole retrying future completes; 3) this method starts returning a new already completed future, which represents the result of the last completed attempt.
  • After completion of the whole retrying future this method always returns exactly same future object.
Returns
TypeDescription
ApiFuture<ResponseT>

setAttemptFuture(ApiFuture<ResponseT> attemptFuture)

public abstract void setAttemptFuture(ApiFuture<ResponseT> attemptFuture)

Sets the attempt in a form of a future. This future represents a concrete retry attempt, potentially scheduled for execution in a some form of java.util.concurrent.ScheduledExecutorService, or an already completed future if the attempts are executed synchronously.

Parameter
NameDescription
attemptFutureApiFuture<ResponseT>

the attempt future