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

Class 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 Detail

      • 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 Detail

      • 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 Detail

      • 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