1 package com.atlassian.pageobjects.elements;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.pageobjects.elements.timeout.TimeoutType;
5 import org.openqa.selenium.By;
6
7 import java.util.List;
8 import javax.annotation.Nonnull;
9
10 /**
11 * <p/>
12 * Encapsulates functionality for finding instances and collections of {@link com.atlassian.pageobjects.elements.PageElement}
13 * on the tested pages, or parts of pages.
14 *
15 * <p/>
16 * A finder is associated with some search scope - it will find elements within this scope (e.g. globally, or within
17 * a parent page element).
18 *
19 * @since 2.0
20 */
21 @PublicApi
22 public interface PageElementFinder {
23
24 /**
25 * Creates {@link com.atlassian.pageobjects.elements.PageElement} implementation
26 * using the specified <tt>locator</tt> and default timeout.
27 *
28 * @param by Locator mechanism to use
29 * @return Element that waits until its present in the DOM before executing actions.
30 */
31 @Nonnull
32 PageElement find(@Nonnull By by);
33
34 /**
35 * Creates {@link com.atlassian.pageobjects.elements.PageElement} implementation
36 * using the specified <tt>locator</tt> and given <tt>timeoutType</tt>.
37 *
38 * @param by Locator mechanism to use
39 * @param timeoutType timeout for the element's timed operations
40 * @return Element that waits until its present in the DOM before executing actions.
41 */
42 @Nonnull
43 PageElement find(@Nonnull By by, @Nonnull TimeoutType timeoutType);
44
45 /**
46 * Creates a {@link com.atlassian.pageobjects.elements.PageElement} for each element that matches the given <tt>locator</tt>
47 * using default timeout.
48 *
49 * @param by Locator mechanism to use
50 * @return List of PageElements that match the given locator
51 */
52 @Nonnull
53 List<PageElement> findAll(@Nonnull By by);
54
55 /**
56 * Creates a {@link com.atlassian.pageobjects.elements.PageElement} for each element that matches the given <tt>locator</tt>
57 * using <tt>timeoutType</tt>.
58 *
59 * @param by Locator mechanism to use
60 * @param timeoutType timeout for the element's timed operations
61 * @return List of PageElements that match the given locator
62 */
63 @Nonnull
64 List<PageElement> findAll(@Nonnull By by, @Nonnull TimeoutType timeoutType);
65
66 /**
67 * Creates {@link com.atlassian.pageobjects.elements.PageElement} extension of type <tt>T</tt> using the specified
68 * <tt>locator</tt> and default timeout.
69 *
70 * @param by Locator mechanism to use
71 * @param elementClass The class of the element to create
72 * @return An instance that implements specified PageElement interface
73 */
74 @Nonnull
75 <T extends PageElement> T find(@Nonnull By by, @Nonnull Class<T> elementClass);
76
77 /**
78 * Creates {@link com.atlassian.pageobjects.elements.PageElement} extension of type <tt>T</tt> using the specified
79 * <tt>locator</tt> and given <tt>timeoutType</tt>
80 *
81 * @param by Locator mechanism to use
82 * @param elementClass The class of the element to create
83 * @param timeoutType timeout for the element's timed operations
84 * @return An instance that implements specified PageElement interface
85 */
86 @Nonnull
87 <T extends PageElement> T find(@Nonnull By by, @Nonnull Class<T> elementClass, @Nonnull TimeoutType timeoutType);
88
89 /**
90 * Creates (@Link PageElement) extension of type <tt>T</tt> for each element that matches the given
91 * <tt>locator</tt> with default timeout
92 * @param by Locator mechanism to use
93 * @param elementClass The class of the element to create
94 * @return A list of objects that implement specified PageElement interface
95 */
96 @Nonnull
97 <T extends PageElement> List<T> findAll(@Nonnull By by, @Nonnull Class<T> elementClass);
98
99 /**
100 * Creates (@Link PageElement) extension of type <tt>T</tt> for each element that matches the given
101 * <tt>locator</tt> with <tt>timeoutType</tt>
102 * @param by Locator mechanism to use
103 * @param elementClass The class of the element to create
104 * @param timeoutType timeout for the element's timed operations
105 * @return A list of objects that implement specified PageElement interface
106 */
107 @Nonnull
108 <T extends PageElement> List<T> findAll(@Nonnull By by, @Nonnull Class<T> elementClass,
109 @Nonnull TimeoutType timeoutType);
110 }