com.azure.core.util.polling

Class Poller<T>

java.lang.Object

com.azure.core.util.polling.Poller<T>

Type Parameters:

T - Type of poll response value

public class Poller<T>
extends Object

This class offers API that simplifies the task of executing long-running operations against an Azure service. The Poller consists of a poll operation, a cancel operation, if it is supported by the Azure service, and a polling interval.

It provides the following functionality:

• Querying the current state of long-running operations.
• Requesting an asynchronous notification for long-running operation's state.
• Cancelling the long-running operation if cancellation is supported by the service.
• Triggering a poll operation manually.
• Enable/Disable auto-polling.

Auto polling

Auto-polling is enabled by default. The Poller starts polling as soon as the instance is created. The Poller will transparently call the poll operation every polling cycle and track the state of the long-running operation. Azure services can return PollResponse.getRetryAfter() to override the Poller.pollInterval defined in the Poller. Poller.getStatus() represents the status returned by a successful long-running operation at the time the last auto-polling or last manual polling, whichever happened most recently.

Disable auto polling

For those scenarios which require manual control of the polling cycle, disable auto-polling by calling setAutoPollingEnabled(false). Then perform manual polling by invoking Poller.poll() function. It will call poll operation once and update Poller.getStatus() with the latest status.

When auto-polling is disabled, the Poller will not update its status or any other information, unless manual polling is triggered by calling Poller.poll() function.

The Poller will stop polling when the long-running operation is complete or disabled. Polling is considered complete based on status defined in PollResponse.OperationStatus.

Code samples

Instantiating and subscribing to PollResponse

LocalDateTime timeToReturnFinalResponse = LocalDateTime.now().plus(Duration.ofMillis(800));

// Create poller instance
Duration pollInterval = Duration.ofMillis(100);
Poller<String> poller = new Poller<>(pollInterval,
    // Define your custom poll operation
    prePollResponse -> {
        if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) {
            System.out.println("Returning intermediate response.");
            return Mono.just(new PollResponse<>(PollResponse.OperationStatus.IN_PROGRESS, "Operation in progress."));
        } else {
            System.out.println("Returning final response.");
            return Mono.just(new PollResponse<>(PollResponse.OperationStatus.SUCCESSFULLY_COMPLETED, "Operation Completed."));
        }
    });

// Listen to poll responses
poller.getObserver().subscribe(response -> {
    // Process poll response
    System.out.printf("Got response. Status: %s, Value: %s%n", response.getStatus(), response.getValue());
});
// Do something else

Wait for polling to complete

PollResponse<String> response = myPoller.block();
System.out.printf("Polling complete. Status: %s, Value: %s%n", response.getStatus(), response.getValue());

Disable auto polling and poll manually

// Turns off auto polling.
myPoller.setAutoPollingEnabled(false);

// Continue to poll every 500ms until the response emitted from poll() is SUCCESSFULLY_COMPLETED.
myPoller.poll()
    .repeatWhen(attemptsCompleted -> attemptsCompleted.flatMap(attempt -> Mono.delay(Duration.ofMillis(500))))
    .takeUntil(response -> response.getStatus() == PollResponse.OperationStatus.SUCCESSFULLY_COMPLETED)
    .subscribe(
        response -> System.out.printf("Status: %s. Value: %s%n", response.getStatus(), response.getValue()),
        error -> System.err.printf("Exception occurred while polling: %s%n", error),
        () -> System.out.printf("Polling complete with status: %s%n", myPoller.getStatus()));

See Also:

PollResponse, PollResponse.OperationStatus

Constructor Summary

Constructors

Constructor and Description
Poller(Duration pollInterval, Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation) Creates a Poller instance with poll interval and poll operation.
Poller(Duration pollInterval, Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation, Consumer<Poller<T>> cancelOperation) Create a Poller instance with poll interval, poll operation and cancel operation.
Poller(Duration pollInterval, Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation, Supplier<Mono<T>> activationOperation, Consumer<Poller<T>> cancelOperation) Creates a Poller instance with poll interval, poll operation, and optional cancel operation.

Method Summary

Modifier and Type	Method and Description
PollResponse<T>	block() Blocks execution and wait for polling to complete.
PollResponse<T>	block(Duration timeout) Blocks execution and wait for polling to complete.
PollResponse<T>	blockUntil(PollResponse.OperationStatus statusToBlockFor) Blocks indefinitely until given PollResponse.OperationStatus is received.
PollResponse<T>	blockUntil(PollResponse.OperationStatus statusToBlockFor, Duration timeout) Blocks until given statusToBlockFor is received or the timeout elapses.
void	cancelOperation() Attempts to cancel the long-running operation that this Poller represents.
Flux<PollResponse<T>>	getObserver() This method returns a Flux that can be subscribed to, enabling a subscriber to receive notification of every PollResponse, as it is received.
PollResponse.OperationStatus	getStatus() Current known status as a result of last poll event or last response from a manual polling.
boolean	isAutoPollingEnabled() Indicates if auto polling is enabled.
Mono<PollResponse<T>>	poll() Enables user to take control of polling and trigger manual poll operation.
void	setAutoPollingEnabled(boolean autoPollingEnabled) Controls whether auto-polling is enabled or disabled.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Poller

public Poller(Duration pollInterval,
              Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation)

Creates a Poller instance with poll interval and poll operation. The polling starts immediately by invoking pollOperation. The next poll cycle will be defined by retryAfter value in PollResponse. In absence of retryAfter, the Poller will use pollInterval.

Create poller object

LocalDateTime timeToReturnFinalResponse = LocalDateTime.now().plus(Duration.ofMillis(800));

// Create poller instance
Poller<String> poller = new Poller<>(Duration.ofMillis(100),
    // Define your custom poll operation
    perPollResponse -> {
        if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) {
            System.out.println("Returning intermediate response.");
            return Mono.just(new PollResponse<>(PollResponse.OperationStatus.IN_PROGRESS, "Operation in progress."));
        } else {
            System.out.println("Returning final response.");
            return Mono.just(new PollResponse<>(PollResponse.OperationStatus.SUCCESSFULLY_COMPLETED, "Operation completed."));
        }
    });

// Default polling will start transparently.

Parameters:

pollInterval - Non null and greater than zero poll interval.

pollOperation - The polling operation to be called by the Poller instance. This must never return null and always have a non-null PollResponse.OperationStatus. Mono returned from poll operation should never return Mono.error(Throwable). If an unexpected scenario happens during the poll operation, it should be handled by the client library and return a valid PollResponse. However if the poll operation returns Mono.error(Throwable), the Poller will disregard it and continue to poll.

Throws:

IllegalArgumentException - if pollInterval is less than or equal to zero and if pollInterval or pollOperation are null

Poller

public Poller(Duration pollInterval,
              Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation,
              Supplier<Mono<T>> activationOperation,
              Consumer<Poller<T>> cancelOperation)

Creates a Poller instance with poll interval, poll operation, and optional cancel operation. Polling starts immediately by invoking pollOperation. The next poll cycle will be defined by retryAfter value in PollResponse. In absence of PollResponse.getRetryAfter(), the Poller will use pollInterval.

Parameters:

pollInterval - Not-null and greater than zero poll interval.

pollOperation - The polling operation to be called by the Poller instance. This must never return null and always have a non-null PollResponse.OperationStatus. Mono returned from poll operation should never return Mono.error(Throwable). If an unexpected scenario happens during the poll operation, it should be handled by the client library and return a valid PollResponse. However if the poll operation returns Mono.error(Throwable), the Poller will disregard it and continue to poll.

activationOperation - The activation operation to be called by the Poller instance before calling pollOperation. It can be null which will indicate to the Poller that pollOperation can be called straight away.

cancelOperation - Cancel operation if cancellation is supported by the service. If it is null, then the cancel operation is not supported.

Throws:

IllegalArgumentException - if pollInterval is less than or equal to zero and if pollInterval or pollOperation are null

Poller

public Poller(Duration pollInterval,
              Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation,
              Consumer<Poller<T>> cancelOperation)

Create a Poller instance with poll interval, poll operation and cancel operation. The polling starts immediately by invoking pollOperation. The next poll cycle will be defined by retryAfter value in PollResponse. In absence of PollResponse.getRetryAfter(), the Poller will use pollInterval.

Parameters:

pollInterval - Not-null and greater than zero poll interval.

pollOperation - The polling operation to be called by the Poller instance. This is a callback into the client library, which must never return null, and which must always have a non-null PollResponse.OperationStatus. Mono returned from poll operation should never return Mono.error(Throwable).If any unexpected scenario happens in poll operation, it should be handled by client library and return a valid PollResponse. However if poll operation returns Mono.error(Throwable), the Poller will disregard that and continue to poll.

cancelOperation - cancel operation if cancellation is supported by the service. It can be null which will indicate to the Poller that cancel operation is not supported by Azure service.

Throws:

IllegalArgumentException - if pollInterval is less than or equal to zero and if pollInterval or pollOperation are null

Method Detail

cancelOperation

public void cancelOperation()
                     throws UnsupportedOperationException

Attempts to cancel the long-running operation that this Poller represents. This is possible only if the service supports it, otherwise an UnsupportedOperationException will be thrown.

It will call cancelOperation if status is PollResponse.OperationStatus.IN_PROGRESS otherwise it does nothing.

Throws:

UnsupportedOperationException - when the cancel operation is not supported by the Azure service.

getObserver

public Flux<PollResponse<T>> getObserver()

This method returns a Flux that can be subscribed to, enabling a subscriber to receive notification of every PollResponse, as it is received.

Returns:

A Flux that can be subscribed to receive poll responses as the long-running operation executes.

poll

public Mono<PollResponse<T>> poll()

Enables user to take control of polling and trigger manual poll operation. It will call poll operation once. This will not turn off auto polling.

Manual polling

final Predicate<PollResponse<String>> isComplete = response -> {
    return response.getStatus() != PollResponse.OperationStatus.IN_PROGRESS
        && response.getStatus() != PollResponse.OperationStatus.NOT_STARTED;
};

// Turns off auto polling
myPoller.setAutoPollingEnabled(false);

myPoller.poll()
    .repeatWhen(attemptsCompleted -> {
        // Retry each poll operation after 500ms.
        return attemptsCompleted.flatMap(attempt -> Mono.delay(Duration.ofMillis(500)));
    })
    .takeUntil(isComplete)
    .filter(isComplete)
    .subscribe(completed -> {
        System.out.println("Completed poll response: " + completed.getStatus());
        System.out.println("Polling complete with status: " + myPoller.getStatus().toString());
    });

Returns:

A Mono that returns PollResponse. This will call poll operation once.

block

public PollResponse<T> block()

Blocks execution and wait for polling to complete. The polling is considered complete based on the status defined in PollResponse.OperationStatus.

It will enable auto-polling if it was disabled by the user.

Returns:

A PollResponse when polling is complete.

block

public PollResponse<T> block(Duration timeout)

Blocks execution and wait for polling to complete. The polling is considered complete based on status defined in PollResponse.OperationStatus.

It will enable auto-polling if it was disable by user.

Parameters:

timeout - The duration for which execution is blocked and waits for polling to complete.

Returns:

returns final PollResponse when polling is complete as defined in PollResponse.OperationStatus.

blockUntil

public PollResponse<T> blockUntil(PollResponse.OperationStatus statusToBlockFor)

Blocks indefinitely until given PollResponse.OperationStatus is received.

Parameters:

statusToBlockFor - The desired PollResponse.OperationStatus to block for.

Returns:

PollResponse whose PollResponse.getStatus() matches statusToBlockFor.

Throws:

IllegalArgumentException - If statusToBlockFor is null.

blockUntil

public PollResponse<T> blockUntil(PollResponse.OperationStatus statusToBlockFor,
                                  Duration timeout)

Blocks until given statusToBlockFor is received or the timeout elapses. If a null timeout is given, it will block indefinitely.

Parameters:

statusToBlockFor - The desired PollResponse.OperationStatus to block for and it can be any valid PollResponse.OperationStatus value.

timeout - The time after which it will stop blocking. A null value will cause to block indefinitely. Zero or negative are not valid values.

Returns:

PollResponse for matching desired status to block for.

Throws:

IllegalArgumentException - if timeout is zero or negative and if statusToBlockFor is null.

setAutoPollingEnabled

public final void setAutoPollingEnabled(boolean autoPollingEnabled)

Controls whether auto-polling is enabled or disabled. Refer to the Poller class-level JavaDoc for more details on auto-polling.

Disable auto polling

myPoller.setAutoPollingEnabled(false);
System.out.println("Polling Enabled? " + myPoller.isAutoPollingEnabled());

Enable auto polling

myPoller.setAutoPollingEnabled(true);
System.out.println("Polling Enabled? " + myPoller.isAutoPollingEnabled());

Parameters:

autoPollingEnabled - If true, auto-polling will occur transparently in the background, otherwise it requires manual polling by the user to get the latest state.

isAutoPollingEnabled

public boolean isAutoPollingEnabled()

Indicates if auto polling is enabled. Refer to the Poller class-level JavaDoc for more details on auto-polling.

Returns:

true if auto-polling is enabled and false otherwise.

getStatus

public PollResponse.OperationStatus getStatus()

Current known status as a result of last poll event or last response from a manual polling.

Returns:

Current status or null if no status is available.