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

Class Polling

  • All Implemented Interfaces:
    java.util.concurrent.Callable<java.lang.Boolean>
    public class Polling
extends java.lang.Object
implements java.util.concurrent.Callable<java.lang.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 java.util.concurrent.Callable<java.lang.Boolean> c
      Optional object to be used by the default implementation of call()
      protected java.util.List<java.lang.Exception> exceptions
      List of all the exceptions thrown by call(), to be used for logging
      protected java.lang.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​(java.util.concurrent.Callable<java.lang.Boolean> c)
      Creates a new instance that uses the Callable parameter for polling

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.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.
      java.util.List<java.lang.Exception> getExceptions()
      Return the list of all exceptions while polling
      java.lang.Exception getLastException()
      Return the last exception while polling or {null}
      long getWaited()  
      protected java.lang.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 Detail

      • c

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

      • lastException

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

      • exceptions

        protected java.util.List<java.lang.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​(java.util.concurrent.Callable<java.lang.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 java.lang.Boolean call()
                       throws java.lang.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 java.util.concurrent.Callable<java.lang.Boolean>
        Returns:
        true to end polling
        Throws:
        java.lang.Exception - if unable to compute a result

      • poll

        public void poll​(long timeout,
                 long delay)
          throws java.util.concurrent.TimeoutException,
                 java.lang.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:
        java.util.concurrent.TimeoutException - if timeout was reached
        java.lang.InterruptedException - if the thread was interrupted while sleeping; caller should throw it further

      • getWaited

        public long getWaited()

      • message

        protected java.lang.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 java.lang.Exception getLastException()
        Return the last exception while polling or {null}
        Returns:

      • getExceptions

        public java.util.List<java.lang.Exception> getExceptions()
        Return the list of all exceptions while polling
        Returns: