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 Azure service. The Poller consist of poll operation, cancel operation if supported by Azure service and 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. It means that the Poller starts polling as soon as its 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. The Poller.getStatus() represents the status returned by the 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-poling by calling setAutoPollingEnabled#false and perform manual poll by invoking Poller.poll() function. It will call poll operation once and update the Poller with the latest status.

When auto-polling is disabled, the Poller will not update its status or 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 it is disabled. The polling is considered complete based on status defined in PollResponse.OperationStatus.

Code Samples

Instantiating and Subscribing to Poll Response

Duration pollInterval = Duration.ofMillis(100);
// Assumption : Poll Operation will return a String type in our example.
Function<PollResponse<String>, Mono<PollResponse<String>>> pollOperation =
    new Function<PollResponse<String>, Mono<PollResponse<String>>>() {
        // Will return success after this time.
        LocalDateTime timeToReturnFinalResponse
            = LocalDateTime.now().plus(Duration.ofMillis(800));

        @Override
        public Mono<PollResponse<String>> apply(PollResponse<String> prePollResponse) {
            if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) {
                System.out.println("returning intermediate response " + inProgressResp.getValue());
                return Mono.just(inProgressResp);
            } else {
                System.out.println("returning final response " + finalPollResponse.getValue());
                return Mono.just(finalPollResponse);
            }
        }
    };

//Create poller instance
Poller<String> myPoller = new Poller<>(pollInterval, pollOperation);

// Listen to poll responses
myPoller.getObserver().subscribe(pr -> {
    //process poll response
    System.out.println("Got Response status,value " + pr.getStatus().toString() + " " + pr.getValue());
});
// Do something else

Wait/Block for Polling to complete

PollResponse<String> myFinalResponse = myPoller.block();
System.out.println("Polling complete final status , value=  "
    + myFinalResponse.getStatus().toString() + "," + myFinalResponse.getValue());

Disable auto polling and polling manually

myPoller.setAutoPollingEnabled(false);
PollResponse<String> pollResponse = null;
// We assume that we get SUCCESSFULLY_COMPLETED status from pollOperation when polling is complete.
while (pollResponse != null
    && pollResponse.getStatus() != PollResponse.OperationStatus.SUCCESSFULLY_COMPLETED) {
    pollResponse = myPoller.poll().block();
    try {
        // Ensure that you have sufficient wait in each poll() which is suitable for your application.
        Thread.sleep(500);
    } catch (InterruptedException e) {
    }
}
System.out.println("Polling complete with status  " + myPoller.getStatus().toString());

See Also:

PollResponse, PollResponse.OperationStatus

Constructor Summary

Constructors

Constructor and Description
Poller(Duration pollInterval, Function<PollResponse<T>,reactor.core.publisher.Mono<PollResponse<T>>> pollOperation) Create a Poller instance with poll interval and poll operation.
Poller(Duration pollInterval, Function<PollResponse<T>,reactor.core.publisher.Mono<PollResponse<T>>> pollOperation, Consumer<Poller> cancelOperation) Create a Poller instance with poll interval, poll operation and cancel operation.

Method Summary

Modifier and Type	Method and Description
PollResponse<T>	block() 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 PollResponse.OperationStatus is received or a timeout expires if provided.
void	cancelOperation() Attempts to cancel the long-running operation that this Poller represents.
reactor.core.publisher.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.
reactor.core.publisher.Mono<PollResponse<T>>	poll() Enable 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>,reactor.core.publisher.Mono<PollResponse<T>>> pollOperation)

Create 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.

Code Sample - Create poller object

// Define your custom poll operation
Function<PollResponse<String>, Mono<PollResponse<String>>> pollOperation =
    new Function<PollResponse<String>, Mono<PollResponse<String>>>() {
        // Will return success after this time.
        LocalDateTime timeToReturnFinalResponse
            = LocalDateTime.now().plus(Duration.ofMillis(800));
        @Override
        public Mono<PollResponse<String>> apply(PollResponse<String> prePollResponse) {
            if (LocalDateTime.now().isBefore(timeToReturnFinalResponse)) {
                System.out.println("returning intermediate response " + inProgressResp.getValue());
                return Mono.just(inProgressResp);
            } else {
                System.out.println("returning final response " + finalPollResponse.getValue());
                return Mono.just(finalPollResponse);
            }
        }
    };

//Create poller instance
Poller<String> myPoller = new Poller<>(Duration.ofMillis(100), pollOperation);

// Default polling will start transparently.

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.

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>,reactor.core.publisher.Mono<PollResponse<T>>> pollOperation,
              Consumer<Poller> 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 handle it 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 cancel operation is not provided.

getObserver

public reactor.core.publisher.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 reactor.core.publisher.Mono<PollResponse<T>> poll()

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

Code Samples

Manual Polling

// Turn off auto polling and this code will take control of polling
myPoller.setAutoPollingEnabled(false);

PollResponse<String> pollResponse = null;
while (pollResponse == null
    || pollResponse.getStatus() == PollResponse.OperationStatus.IN_PROGRESS
    || pollResponse.getStatus() == PollResponse.OperationStatus.NOT_STARTED) {
    // get one poll Response at a time..
    pollResponse = myPoller.poll().block();
    System.out.println("Poll response status  " + pollResponse.getStatus().toString());
    // Ensure that you have sufficient wait in each poll() which is suitable for your application.
    try {
        // wait before next poll.
        Thread.sleep(500);
    } catch (InterruptedException e) {
    }
}
System.out.println("Polling complete with status  " + myPoller.getStatus().toString());

Returns:

a Mono of PollResponse This will call poll operation once. The Mono returned here could be subscribed for receiving PollResponse in async manner.

block

public PollResponse<T> block()

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.

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 and it can be any valid PollResponse.OperationStatus value.

Returns:

PollResponse for matching desired status.

Throws:

IllegalArgumentException - If statusToBlockFor is null.

blockUntil

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

Blocks until given PollResponse.OperationStatus is received or a timeout expires if provided. A null timeout will cause to block indefinitely for desired status.

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:

A boolean value representing if auto-polling is enabled or not..

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.