Package com.google.api.gax.retrying

Interface RetryingFuture<ResponseT>

  • Type Parameters:
    ResponseT - response type
    All Superinterfaces:
    com.google.api.core.ApiFuture<ResponseT>, java.util.concurrent.Future<ResponseT>
    public interface RetryingFuture<ResponseT>
extends com.google.api.core.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.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      com.google.api.core.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.
      TimedAttemptSettings getAttemptSettings()
      Returns current (active) attempt settings.
      java.util.concurrent.Callable<ResponseT> getCallable()
      Returns callable tracked by this future.
      com.google.api.core.ApiFuture<ResponseT> peekAttemptResult()
      Returns latest completed attempt result or null if the first attempt hasn't completed yet.
      void setAttemptFuture​(com.google.api.core.ApiFuture<ResponseT> attemptFuture)
      Sets the attempt in a form of a future.

      • Methods inherited from interface com.google.api.core.ApiFuture

        addListener

      • Methods inherited from interface java.util.concurrent.Future

        cancel, get, get, isCancelled, isDone

    • Method Detail

      • setAttemptFuture

        void setAttemptFuture​(com.google.api.core.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 ScheduledExecutorService, or an already completed future if the attempts are executed synchronously.
        Parameters:
        attemptFuture - the attempt future

      • getCallable

        java.util.concurrent.Callable<ResponseT> getCallable()
        Returns callable tracked by this future.

      • getAttemptSettings

        TimedAttemptSettings getAttemptSettings()
        Returns current (active) attempt settings.

      • peekAttemptResult

        com.google.api.core.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 Future.isDone() will always be true and Future.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.

      • getAttemptResult

        com.google.api.core.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 Future.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 Future.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.