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