SyncPoller<T,U> Interface

  • Reference
Package:
com.azure.core.util.polling
Maven Artifact:
com.azure:azure-core:1.54.0

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 Summary

Modifier and Type Method and Description
static SyncPoller<T,U> <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.
static SyncPoller<T,U> <T,U>createPoller(Duration pollInterval, Supplier<Response<?>> initialOperation, SyncPollingStrategy<T,U> strategy, TypeReference<T> pollResponseType, TypeReference<U> resultType)

Creates PollerFlux.
abstract void cancelOperation()

Cancels the remote long-running operation if cancellation is supported by the service.
abstract U getFinalResult()

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

Retrieve the final result of the long-running operation.
abstract PollResponse<T> poll()

Poll once and return the poll response received.
default SyncPoller<T,U> setPollInterval(Duration pollInterval)

Sets the poll interval for this poller.
abstract PollResponse<T> waitForCompletion()

Wait for polling to complete.
abstract PollResponse<T> waitForCompletion(Duration timeout)

Wait for polling to complete with a timeout.
abstract PollResponse<T> waitUntil(LongRunningOperationStatus statusToWaitFor)

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

Wait for the given LongRunningOperationStatus with a timeout.

Method Details

<T,U>createPoller

public static SyncPoller createPoller(Duration pollInterval, Function,PollResponse> syncActivationOperation, Function,PollResponse> pollOperation, BiFunction,PollResponse,T> cancelOperation, Function,U> fetchResultOperation)

Creates default SyncPoller.

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<T>.
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<T>.
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<T>.
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<T>, 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<T,U> instance.

<T,U>createPoller

public static SyncPoller createPoller(Duration pollInterval, Supplier> initialOperation, SyncPollingStrategy strategy, TypeReference pollResponseType, TypeReference resultType)

Creates PollerFlux.

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

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<T>.
strategy - a known synchronous strategy for polling a long-running operation in Azure
pollResponseType - the TypeReference<T> of the response type from a polling call, or BinaryData if raw response body should be kept. This should match the generic parameter U.
resultType - the TypeReference<T> of the final result object to deserialize into, or BinaryData if raw response body should be kept. This should match the generic parameter U.

Returns:

new SyncPoller<T,U> instance.

cancelOperation

public abstract 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.

getFinalResult

public abstract 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

public 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 timeout) + 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 timeout) then getFinalResult().

Parameters:

timeout - the duration to wait for polling completion.

Returns:

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

poll

public abstract PollResponse poll()

Poll once and return the poll response received.

Returns:

the poll response

setPollInterval

public default SyncPoller 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<T,U>.

waitForCompletion

public abstract PollResponse 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

public abstract PollResponse 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.

waitUntil

public abstract PollResponse waitUntil(LongRunningOperationStatus statusToWaitFor)

Wait for the given LongRunningOperationStatus to receive.

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

Parameters:

statusToWaitFor - the desired LongRunningOperationStatus to block for.

Returns:

PollResponse<T> whose getStatus() matches statusToWaitFor or is isComplete().

waitUntil

public abstract PollResponse 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 isComplete() state is reached, or the timeout expires.

Unlike waitForCompletion(Duration timeout) or getFinalResult(Duration timeout), 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<T> whose getStatus() matches statusToWaitFor, or null if no response was returned within the timeout.

Applies to