1 package com.atlassian.pageobjects.elements.search;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.pageobjects.elements.PageElement;
5 import com.atlassian.pageobjects.elements.timeout.TimeoutType;
6 import com.google.common.base.Predicate;
7 import org.openqa.selenium.By;
8
9 import javax.annotation.Nonnull;
10
11 /**
12 * {@link SearchQuery}, whose element type is an instance of {@link PageElement}. Allows for nesting the search
13 * ({@link #by(By)}) and mapping the underlying page elements into elements of specialized type ({@link #as(Class)}, or
14 * with a customized timeout ({@link #withTimeout(TimeoutType)}.
15 *
16 * @since 2.3
17 */
18 @PublicApi
19 public interface PageElementQuery<E extends PageElement> extends SearchQuery<E, PageElementQuery<E>>
20 {
21 /**
22 * Search withing all results for child elements matching {@code by}. This is technically a flat map that will
23 * expand each current result element into a set of child elements matching {@code by}.
24 *
25 * @param by locator to search by
26 * @return new query with results matching {@code by}
27 */
28 @Nonnull
29 PageElementQuery<E> by(@Nonnull By by);
30
31 /**
32 * Search child elements using {@code by} and applying the {@code filter} at the same time. This is equivalent to
33 * calling {@link #by(By)} and {@link #filter(Predicate)} in succession.
34 *
35 * @param by locator to search by
36 * @param filter filter for the results of the search
37 * @return new query with results matching {@code by} and filtered using {@code filter}
38 */
39 @Nonnull
40 PageElementQuery<E> by(@Nonnull By by, @Nonnull Predicate<? super PageElement> filter);
41
42 /**
43 * Apply a custom {@code timeoutType} to all resulting elements.
44 *
45 * @param timeoutType new timeout type
46 * @return a query equivalent to this query, but with a custom timeout
47 */
48 @Nonnull
49 PageElementQuery<E> withTimeout(@Nonnull TimeoutType timeoutType);
50
51 /**
52 * Map current results to a more specialized {@code pageElementClass} (e.g. {@code CheckboxElement}).
53 *
54 * @param pageElementClass the page element class to apply
55 * @param <PE> the new element type parameter
56 * @return new query equivalent to this query, but with different element type, corresponding to
57 * {@code pageElementClass}
58 */
59 @Nonnull
60 <PE extends E> PageElementQuery<PE> as(@Nonnull Class<PE> pageElementClass);
61 }