1 package com.atlassian.pageobjects.elements.search;
2
3
4 import com.atlassian.annotations.PublicApi;
5 import com.atlassian.pageobjects.PageBinder;
6 import com.atlassian.pageobjects.elements.PageElements;
7 import com.atlassian.pageobjects.elements.query.TimedCondition;
8 import com.atlassian.pageobjects.elements.query.TimedQuery;
9 import com.google.common.base.Function;
10 import com.google.common.base.Predicate;
11 import com.google.common.base.Supplier;
12
13 import javax.annotation.Nonnull;
14 import javax.annotation.Nullable;
15
16 /**
17 * Represents a generic query for any type of object. The query provides API to:
18 * <ul>
19 * <li>map and filter the results ({@link #filter(Predicate)}, {@link #map(Function)}, {@link #flatMap(Function)},
20 * {@link #bindTo(Class, Object...)})</li>
21 * <li>obtain query results (e.g. {@link #get()}, {@link #now()}, {@link #first()}, {@link #hasResult()},
22 * {@link #timed()})</li>
23 * </ul>
24 *
25 * @see PageElementSearch
26 * @see AnyQuery
27 * @see PageElementQuery
28 * @see PageElements
29 *
30 * @since 2.3
31 */
32 @PublicApi
33 public interface SearchQuery<E, Q extends SearchQuery<E, Q>> extends Supplier<Iterable<E>>
34 {
35 /**
36 * Filter the underlying results using {@code predicate}.
37 *
38 * @param predicate predicate to filter the results
39 * @return new query with the applied filter
40 */
41 @Nonnull
42 Q filter(@Nonnull Predicate<? super E> predicate);
43
44 /**
45 * Map the query results using {@code mapper}.
46 *
47 * @param mapper a function to map the results
48 * @param <F> the new result type
49 * @return new query with mapped results
50 */
51 @Nonnull
52 <F> AnyQuery<F> map(@Nonnull Function<? super E, F> mapper);
53
54 /**
55 * Flat map the results using {@code mapper}.
56 *
57 * @param mapper the function to use to flat map
58 * @param <F> the new result type
59 * @return new query with mapped results.
60 */
61 @Nonnull
62 <F> AnyQuery<F> flatMap(@Nonnull Function<? super E, Iterable<F>> mapper);
63
64 /**
65 * Map the results by binding into a page object. The resulting page objects needs to provide a compatible
66 * constructor.
67 *
68 * @param pageObjectClass page object class
69 * @param extraArgs extra arguments to the bind method
70 * @param <F> the new result type
71 * @return new query with mapped results
72 * @see com.atlassian.pageobjects.PageObjects#bind(PageBinder, Iterable, Class, Object...)
73 */
74 @Nonnull
75 <F> AnyQuery<F> bindTo(@Nonnull Class<F> pageObjectClass, @Nonnull Object... extraArgs);
76
77
78 /**
79 * @return first result , or {@code null} if there is no results
80 */
81 @Nullable
82 E first();
83
84 /**
85 * Equivalent to {@link #get()}.
86 *
87 * @return all results, as they are now
88 */
89 @Nonnull
90 Iterable<E> now();
91
92 /**
93 * @return timed condition to check whether this query has any result
94 */
95 @Nonnull
96 TimedCondition hasResult();
97
98 /**
99 * @return timed query for all results
100 */
101 @Nonnull
102 TimedQuery<Iterable<E>> timed();
103 }