com.azure.security.keyvault.certificates

Class Poller<T,R>

java.lang.Object

com.azure.security.keyvault.certificates.Poller<T,R>

Type Parameters:

T - Type of poll response value

public class Poller<T,R>
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.

See Also:

PollResponse

Constructor Summary

Constructors

Constructor and Description
Poller(Duration pollInterval, Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation) Create a Poller instance with poll interval and poll operation.
Poller(Duration pollInterval, Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation, Supplier<Mono<R>> fetchResultOperation, Consumer<Poller<T,R>> 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<R>> fetchResultOperation, Supplier<Mono<T>> activationOperation) 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, Supplier<Mono<R>> fetchResultOperation, Consumer<Poller<T,R>> cancelOperation) Create a Poller instance with poll interval and poll operation.

Method Summary

Modifier and Type	Method and Description
R	block() Blocks execution and wait for polling to complete.
R	block(Duration timeout) Blocks execution and wait for polling to complete.
PollResponse<T>	blockUntil(PollResponse.OperationStatus statusToBlockFor) Blocks indefinitely until given statusToBlockFor is received.
PollResponse<T>	blockUntil(PollResponse.OperationStatus statusToBlockFor, Duration timeout) Blocks until given statusToBlockFor is received or a timeout expires if provided.
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() Enable user to take control of polling and trigger manual poll operation.
Mono<R>	result()
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)

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.

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 status. 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>,Mono<PollResponse<T>>> pollOperation,
              Supplier<Mono<T>> activationOperation,
              Supplier<Mono<R>> fetchResultOperation,
              Consumer<Poller<T,R>> cancelOperation)

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.

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

activationOperation - the operation to be called before polling begins. It can be null which will indicate to the Poller that polling can begin straight away.

fetchResultOperation - the operation to be called to fetch final result after polling has been completed.

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

Poller

public Poller(Duration pollInterval,
              Function<PollResponse<T>,Mono<PollResponse<T>>> pollOperation,
              Supplier<Mono<R>> fetchResultOperation,
              Consumer<Poller<T,R>> 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 status. 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.

fetchResultOperation - the operation to be called to fetch final result after polling has been completed.

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

Poller

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

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

fetchResultOperation - the operation to be called to fetch final result after polling has been completed.

activationOperation - the operation to be called before polling begins. It can be null which will indicate to the Poller that polling can begin straight away.

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 'In Progress' otherwise it does nothing.

Throws:

UnsupportedOperationException - when cancel operation is not provided.

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()

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.

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 R block()

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

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

Returns:

returns final PollResponse when polling is complete.

result

public Mono<R> result()

block

public R block(Duration timeout)

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

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

Parameters:

timeout - the duration for which the excecution is blocked and waits for polling to complete.

Returns:

returns final PollResponse when polling is complete.

blockUntil

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

Blocks indefinitely until given statusToBlockFor is received.

Parameters:

statusToBlockFor - The desired status to block for.

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 statusToBlockFor is received or a timeout expires if provided. A null timeout will cause to block indefinitely for desired status.

Parameters:

statusToBlockFor - The desired status to block for.

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.

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.