1 package com.atlassian.pageobjects.elements.query;
2
3
4 import java.util.concurrent.TimeUnit;
5 import javax.annotation.concurrent.NotThreadSafe;
6
7 /**
8 * <p>
9 * Represents a repeatable query over the state of the test that results in an object instance of a particular type
10 * <tt>T</tt>. The query may be evaluated immediately ({@link #now()}, or within some timeout
11 * ({@link #byDefaultTimeout()}, {@link #by(long)}, {@link #by(long, java.util.concurrent.TimeUnit)}).
12 * Usually there is a specific value of <tt>T</tt> expected by the query and it will not return until the
13 * underlying query evaluates to this expected value, or the timeout expires.
14 *
15 * <p>
16 * The specific semantics of how the polling is performed are up to implementations of this interface and should be
17 * documented appropriately. E.g. a particular implementation may be waiting for a specific value <i>t</i> of <tt>T</tt>,
18 * and returning the real value <i>s</i>, if the query does not return <i>t</i> within the given timeout. Other
19 * implementations may throw exceptions, or return <code>null</code>, if an expected query result value is not returned
20 * within timeout, etc.
21 *
22 *
23 * @param <T> type of the query result
24 */
25 @NotThreadSafe
26 public interface TimedQuery<T> extends PollingQuery
27 {
28
29 /**
30 * Evaluate this query by a timeout deemed default by this query.
31 *
32 * @return expected value of <tt>T</tt>, or any suitable value, if the expected value was not returned before
33 * the default timeout expired
34 * @see #defaultTimeout()
35 */
36 T byDefaultTimeout();
37
38 /**
39 * Evaluate this query by given timeout. That is, return the expected <tt>T</tt> as soon as the query evaluates
40 * to the expected value, otherwise perform any appropriate operation when the <tt>timeout</tt> expires (e.g.
41 * return real value, <code>null</code>, or throw exception
42 *
43 * @param timeoutInMillis timeout in milliseconds (must be greater than 0)
44 * @return expected value of <tt>T</tt>, or any suitable value, if the expected value was not returned before
45 * <tt>timeout</tt> expired
46 */
47 T by(long timeoutInMillis);
48
49 /**
50 * Evaluate this query by given timeout. That is, return the expected <tt>T</tt> as soon as the query evaluates
51 * to the expected value, otherwise perform any appropriate operation when the <tt>timeout</tt> expires (e.g.
52 * return real value, <code>null</code>, or throw exception
53 *
54 * @param timeout timeout (must be greater than 0)
55 * @param unit the unit that the timeout is in
56 * @return expected value of <tt>T</tt>, or any suitable value, if the expected value was not returned before
57 * <tt>timeout</tt> expired
58 */
59 T by(long timeout, TimeUnit unit);
60
61 /**
62 * Evaluate this query immediately.
63 *
64 * @return current evaluation of the underlying query.
65 */
66 T now();
67 }