Package com.azure.core.util.polling

Interface SyncPoller<T,U>

Type Parameters:
T - The type of poll response value.
U - The type of the final result of long-running operation.
public interface SyncPoller<T,U>
A type that offers API that simplifies the task of executing long-running operations against an Azure service.

It provides the following functionality:

  • Querying the current state of the long-running operation.
  • Requesting cancellation of long-running operation, if supported by the service.
  • Fetching final result of long-running operation, if supported by the service.
  • Wait for long-running operation to complete, with optional timeout.
  • Wait for long-running operation to reach a specific state.

  • Method Details

    • poll

      PollResponse<T> poll()
      Poll once and return the poll response received.
      Returns:
      the poll response

    • waitForCompletion

      PollResponse<T> waitForCompletion()
      Wait for polling to complete. The polling is considered complete based on status defined in LongRunningOperationStatus.

      This operation will wait indefinitely until a completed LongRunningOperationStatus is received.

      Returns:
      the final poll response

    • waitForCompletion

      PollResponse<T> waitForCompletion(Duration timeout)
      Wait for polling to complete with a timeout. The polling is considered complete based on status defined in LongRunningOperationStatus or if the timeout expires.

      Polling will continue until a completed LongRunningOperationStatus is received or the timeout expires.

      The timeout is applied in two ways, first it's used during each poll operation to time it out if the polling operation takes too long. Second, it's used to determine when the wait for should stop. If polling doesn't reach a completion state before the timeout elapses a RuntimeException wrapping a TimeoutException will be thrown.

      Parameters:
      timeout - the duration to wait for polling completion.
      Returns:
      the final poll response.
      Throws:
      NullPointerException - If timeout is null.
      IllegalArgumentException - If timeout is zero or negative.
      RuntimeException - If polling doesn't complete before the timeout elapses. (Throwable.getCause() should be a TimeoutException).

    • waitUntil

      PollResponse<T> waitUntil(LongRunningOperationStatus statusToWaitFor)
      Wait for the given LongRunningOperationStatus to receive.

      This operation will wait indefinitely until the statusToWaitFor is received or a LongRunningOperationStatus.isComplete() state is reached.

      Parameters:
      statusToWaitFor - the desired LongRunningOperationStatus to block for.
      Returns:
      PollResponse whose PollResponse.getStatus() matches statusToWaitFor or is LongRunningOperationStatus.isComplete().
      Throws:
      NullPointerException - if statusToWaitFor is null.

    • waitUntil

      PollResponse<T> waitUntil(Duration timeout, LongRunningOperationStatus statusToWaitFor)
      Wait for the given LongRunningOperationStatus with a timeout.

      Polling will continue until a response is returned with a LongRunningOperationStatus matching statusToWaitFor, a LongRunningOperationStatus.isComplete() state is reached, or the timeout expires.

      Unlike waitForCompletion(Duration) or getFinalResult(Duration), when the timeout elapses a RuntimeException wrapping a TimeoutException will not be thrown. Instead, the last poll response will be returned. This is because unlike a completion state, a wait for state may be skipped if the state is reached and completed before a poll operation is executed. For example, if a long-running operation has the flow A -> B -> C -> D and the statusToWaitFor is B and the first poll request returns state A but in the time between polls state B completes, then the next poll request will return state C and the statusToWaitFor will never be returned.

      This may return null if no poll operation completes within the timeout.

      Parameters:
      timeout - the duration to wait for the polling.
      statusToWaitFor - the desired LongRunningOperationStatus to block for.
      Returns:
      PollResponse whose PollResponse.getStatus() matches statusToWaitFor, or null if no response was returned within the timeout.
      Throws:
      NullPointerException - if statusToWaitFor or timeout is null.
      IllegalArgumentException - if timeout is zero or negative.

    • getFinalResult

      U getFinalResult()
      Retrieve the final result of the long-running operation.

      If polling hasn't completed this will wait indefinitely until polling completes.

      Returns:
      the final result of the long-running operation if there is one.

    • getFinalResult

      default U getFinalResult(Duration timeout)
      Retrieve the final result of the long-running operation.

      If polling hasn't completed this will wait for the timeout for polling to complete. In this case this API is effectively equivalent to waitForCompletion(Duration) + getFinalResult().

      Polling will continue until a completed LongRunningOperationStatus is received or the timeout expires.

      The timeout is applied in two ways, first it's used during each poll operation to time it out if the polling operation takes too long. Second, it's used to determine when the wait for should stop. If polling doesn't reach a completion state before the timeout elapses a RuntimeException wrapping a TimeoutException will be thrown.

      If this method isn't overridden by the implementation then this method is effectively equivalent to calling waitForCompletion(Duration) then getFinalResult().

      Parameters:
      timeout - the duration to wait for polling completion.
      Returns:
      the final result of the long-running operation if there is one.
      Throws:
      NullPointerException - If timeout is null.
      IllegalArgumentException - If timeout is zero or negative.
      RuntimeException - If polling doesn't complete before the timeout elapses. (Throwable.getCause() should be a TimeoutException).

    • cancelOperation

      void cancelOperation()
      Cancels the remote long-running operation if cancellation is supported by the service.

      If cancellation isn't supported by the service this will throw an exception.

      Throws:
      RuntimeException - if the operation does not support cancellation.

    • setPollInterval

      default SyncPoller<T,U> setPollInterval(Duration pollInterval)
      Sets the poll interval for this poller. The new interval will be used for all subsequent polling operations including the polling operations that are already in progress.
      Parameters:
      pollInterval - The new poll interval for this poller.
      Returns:
      The updated instance of SyncPoller.
      Throws:
      NullPointerException - if the pollInterval is null.
      IllegalArgumentException - if the pollInterval is zero or negative.

    • createPoller

      static <T, U> SyncPoller<T,U> createPoller(Duration pollInterval, Function<PollingContext<T>,PollResponse<T>> syncActivationOperation, Function<PollingContext<T>,PollResponse<T>> pollOperation, BiFunction<PollingContext<T>,PollResponse<T>,T> cancelOperation, Function<PollingContext<T>,U> fetchResultOperation)
      Creates default SyncPoller.
      Type Parameters:
      T - The type of poll response value.
      U - The type of the final result of long-running operation.
      Parameters:
      pollInterval - the polling interval.
      syncActivationOperation - the operation to synchronously activate (start) the long-running operation, this operation will be called with a new PollingContext.
      pollOperation - the operation to poll the current state of long-running operation, this parameter is required and the operation will be called with current PollingContext.
      cancelOperation - a Function that represents the operation to cancel the long-running operation if service supports cancellation, this parameter is required and if service does not support cancellation then the implementer should throw an exception with an error message indicating absence of cancellation support, the operation will be called with current PollingContext.
      fetchResultOperation - a Function that represents the operation to retrieve final result of the long-running operation if service support it, this parameter is required and operation will be called current PollingContext, if service does not have an api to fetch final result and if final result is same as final poll response value then implementer can choose to simply return value from provided final poll response.
      Returns:
      new SyncPoller instance.
      Throws:
      NullPointerException - if pollInterval, syncActivationOperation, pollOperation, cancelOperation or fetchResultOperation is null.
      IllegalArgumentException - if pollInterval is zero or negative.

    • createPoller

      static <T, U> SyncPoller<T,U> createPoller(Duration pollInterval, Supplier<Response<?>> initialOperation, SyncPollingStrategy<T,U> strategy, TypeReference<T> pollResponseType, TypeReference<U> resultType)
      Creates PollerFlux.

      This method uses a SyncPollingStrategy to poll the status of a long-running operation after the activation operation is invoked. See SyncPollingStrategy for more details of known polling strategies and how to create a custom strategy.

      Type Parameters:
      T - The type of poll response value.
      U - The type of the final result of long-running operation.
      Parameters:
      pollInterval - the polling interval
      initialOperation - the activation operation to activate (start) the long-running operation. This operation will be invoked at most once across all subscriptions. This parameter is required. If there is no specific activation work to be done then invocation should return null, this operation will be called with a new PollingContext.
      strategy - a known synchronous strategy for polling a long-running operation in Azure
      pollResponseType - the TypeReference of the response type from a polling call, or BinaryData if raw response body should be kept. This should match the generic parameter SyncPoller.
      resultType - the TypeReference of the final result object to deserialize into, or BinaryData if raw response body should be kept. This should match the generic parameter SyncPoller.
      Returns:
      new SyncPoller instance.
      Throws:
      NullPointerException - if pollInterval, initialOperation, strategy, pollResponseType or resultType is null.
      IllegalArgumentException - if pollInterval is zero or negative.