Package org.apache.sling.testing.clients.util.poller

# Class Polling

java.lang.Object
org.apache.sling.testing.clients.util.poller.Polling

All Implemented Interfaces:
  `Callable<Boolean>`

public class Polling extends Object implements Callable<Boolean>
Helper for repeating a call until it returns true, with timeout capabilities. Subclasses should override the `call()` method. Can be used with lambda expressions, using the constructor `Polling(Callable c)`.

Since:
  1.1.0

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final Callable<Boolean>`
`c`
Optional object to be used by the default implementation of call()
`protected List<Exception>`
`exceptions`
List of all the exceptions thrown by call(), to be used for logging
`protected Exception`
`lastException`
Holder for the last exception thrown by call(), to be used for logging
`protected long`
`waited`
Counter for total waiting time

## Constructor Summary

Constructors
Constructor
Description
`Polling()`
Default constructor to be used in subclasses that override the `call()` method.
`Polling(Callable<Boolean> c)`
Creates a new instance that uses the `Callable` parameter for polling

## Method Summary

Modifier and Type
Method
Description
`Boolean`
`call()`
Method to be called by `poll(long timeout, long delay)`, potentially multiple times, until it returns true or timeout is reached.
Subclasses can override it to change the check accordingly.
`List<Exception>`
`getExceptions()`
Return the list of all exceptions while polling
`Exception`
`getLastException()`
Return the last exception while polling or {null}
`long`
`getWaited()`
`protected String`
`message()`
Returns the string to be used in the `TimeoutException`, if needed.
`void`
`poll(long timeout, long delay)`
Tries to execute `call()` until it returns true or until `timeout` is reached.

### Methods inherited from class java.lang.Object

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

## Field Details

### c

protected final Callable<Boolean> c
Optional object to be used by the default implementation of call()

### lastException

protected Exception lastException
Holder for the last exception thrown by call(), to be used for logging

### exceptions

protected List<Exception> exceptions
List of all the exceptions thrown by call(), to be used for logging

### waited

protected long waited
Counter for total waiting time

## Constructor Details

### Polling

public Polling()
Default constructor to be used in subclasses that override the `call()` method. Should not be used directly on `Polling` instances, but only on extended classes. If used directly to get a `Polling` instance, executing `poll(long timeout, long delay)` will be equivalent to `Thread.sleep(timeout)`

### Polling

public Polling(Callable<Boolean> c)
Creates a new instance that uses the `Callable` parameter for polling

Parameters:
  `c` - object whose `call()` method will be polled

## Method Details

### call

public Boolean call() throws Exception

Method to be called by `poll(long timeout, long delay)`, potentially multiple times, until it returns true or timeout is reached.
Subclasses can override it to change the check accordingly. The method should return true only when the call was successful.
It can return false or throw any `Exception` to make the poller try again later.

The default implementation delegates the call to the `Callable c` instance.

Specified by:
  `call` in interface `Callable<Boolean>`
Returns:
  `true` to end polling
Throws:
  `Exception` - if unable to compute a result

### poll

public void poll(long timeout, long delay) throws TimeoutException, InterruptedException

Tries to execute `call()` until it returns true or until `timeout` is reached. Between retries, it waits using `Thread.sleep(delay)`. It means the retry is not at a fixed pace, but depends on the execution time of the call itself.

The method guarantees that the call() will be executed at least once. If the timeout is 0 or less, then call() will be executed exactly once.

The timeout is adjusted using `TimeoutsProvider` so the final value can be changed using the system property: "sling.testing.timeout.multiplier"

Parameters:
  `timeout` - max total execution time, in milliseconds
  `delay` - time to wait between calls, in milliseconds
Throws:
  `TimeoutException` - if `timeout` was reached
  `InterruptedException` - if the thread was interrupted while sleeping; caller should throw it further

### getWaited

public long getWaited()

### message

protected String message()
Returns the string to be used in the `TimeoutException`, if needed. The string is passed to `String.format(message(), timeout, delay)`, so it can be a format including `%1$d` and `%2$d`. The field `lastException` is also available for logging

Returns:
  the format string

### getLastException

public Exception getLastException()
Return the last exception while polling or {null}

Returns:
  the last exception (can be null)

### getExceptions

public List<Exception> getExceptions()
Return the list of all exceptions while polling

Returns:
  the non-null list of exceptions