1 package com.atlassian.pageobjects.elements;
2
3 import com.atlassian.pageobjects.elements.query.TimedQuery;
4
5 /**
6 * <p>
7 * Encapsulates Javascript functionality of the {@link com.atlassian.pageobjects.elements.PageElement}.
8 * </p>
9 *
10 * <p>
11 * {@link PageElement#isPresent()} of the corresponding page element must return <code>true</code>
12 * before any of the methods of this interface are invoked, otherwise {@link org.openqa.selenium.NoSuchElementException}
13 * will be raised.
14 * </p>
15 *
16 * @since 2.1
17 */
18 public interface PageElementJavascript
19 {
20
21 /**
22 * Access to mouse events for the associated page element.
23 *
24 * @return mouse events for the element
25 */
26 PageElementMouseJavascript mouse();
27
28
29 /**
30 * Access to form events for the associated page element.
31 *
32 * @return form events for the element
33 */
34 PageElementFormJavascript form();
35
36 /**
37 * <p>
38 * Executes custom script on this element.
39 * </p>
40 *
41 * <p>
42 * The corresponding HTML element will be available in the executing script under <tt>arguments[0]</tt> entry.
43 * The provided <tt>arguments</tt> will be available under subsequents entries in the 'arguments' magic variable, as
44 * stated in {@link org.openqa.selenium.JavascriptExecutor#executeScript(String, Object...)}.
45 * </p>
46 *
47 * <p>
48 * The arguments and return type are as in
49 * {@link org.openqa.selenium.JavascriptExecutor#executeScript(String, Object...)} with addition of
50 * {@link com.atlassian.pageobjects.elements.PageElement}s as valid argument type.
51 * </p>
52 *
53 * <p>
54 * When a DOM element is returned from the script, a corresponding
55 * {@link com.atlassian.pageobjects.elements.PageElement}
56 * instance will be returned from this method
57 * </p>
58 *
59 * @param script javascript to execute
60 * @param arguments custom arguments to the script. a number, a boolean, a String,
61 * a {@link com.atlassian.pageobjects.elements.PageElement}, a {@link org.openqa.selenium.WebElement} or a List of
62 * any combination of the above
63 * @return One of Boolean, Long, String, List or {@link com.atlassian.pageobjects.elements.PageElement},
64 * or <code>null</code>.
65 * @throws NullPointerException if <tt>script</tt> is <code>null</code>
66 *
67 * @see org.openqa.selenium.JavascriptExecutor#executeScript(String, Object...)
68 */
69 Object execute(String script, Object... arguments);
70
71 /**
72 * <p>
73 * Provides the same functionality as {@link #execute(String, Object...)}, but lets the client specify the
74 * expected result type. The expected result type must not be <code>null</code> and must match the actual
75 * result from the executed script.
76 * </p>
77 *
78 * @param resultType expected type of the result. One of Boolean, Long, String, List or
79 * {@link com.atlassian.pageobjects.elements.PageElement} . Must not be <code>null</code>
80 * @param script javascript to execute
81 * @param arguments custom arguments to the script. a number, a boolean, a String,
82 * a {@link com.atlassian.pageobjects.elements.PageElement}, a {@link org.openqa.selenium.WebElement} or a List of
83 * any combination of the above
84 * @return result of the script converted to the <tt>resultType</tt>
85 * @throws NullPointerException if <tt>script</tt> or <tt>resultType</tt> is <code>null</code>
86 * @throws IllegalArgumentException if <tt>resultType</tt> is not one of the expected types
87 * @throws ClassCastException if the actual result type does not match <tt>resultType</tt>
88 *
89 * @see #execute(String, Object...)
90 */
91 <T> T execute(Class<T> resultType, String script, Object... arguments);
92
93
94 /**
95 * <p>
96 * Executes custom script on this element in a periodic manner, allowing the client to wait for a particular
97 * expected result to occur (via the returned {@link TimedQuery}).
98 * </p>
99 *
100 * <p>
101 * All rules (in particular with regards to the result type) of {@link #execute(String, Object...)} apply to this
102 * method.
103 * </p>
104 *
105 * <p>
106 * The caller must provide the expected return type as <tt>resultType</tt>. It must be one of the valid result types
107 * or an exception will be raised.
108 * </p>
109 *
110 * @param resultType expected type of the result. One of Boolean, Long, String or List. Must not be <code>null</code>
111 * @param script javascript to execute
112 * @param arguments custom arguments to the script. a number, a boolean, a String,
113 * a {@link com.atlassian.pageobjects.elements.PageElement}, a {@link org.openqa.selenium.WebElement} or a List of
114 * any combination of the above
115 * @return {@link com.atlassian.pageobjects.elements.query.TimedQuery} to query for the expected result
116 * @throws NullPointerException if <tt>script</tt> or <tt>resultType</tt> is <code>null</code>
117 * @throws IllegalArgumentException if <tt>resultType</tt> is not one of the expected types
118 * @throws ClassCastException if the actual result type does not match <tt>resultType</tt>
119 *
120 * @see org.openqa.selenium.JavascriptExecutor#executeScript(String, Object...)
121 * @see #execute(String, Object...)
122 *
123 */
124 <T> TimedQuery<T> executeTimed(Class<T> resultType, String script, Object... arguments);
125
126
127 /**
128 * <p>
129 * Executes custom script on this element asynchronously.
130 * </p>
131 *
132 * <p>
133 * All rules and conditions of {@link #execute(String, Object...)} apply, except the last argument in the
134 * 'arguments' magic variable in the script is a callback that has to be invoked and given result of the script
135 * so that this method returns. See {@link org.openqa.selenium.JavascriptExecutor#executeAsyncScript(String, Object...)}
136 * for details.
137 * </p>
138 *
139 * <p>
140 * Consider using {@link #executeTimed(Class, String, Object...)} instead.
141 * </p>
142 *
143 * @param script javascript to execute
144 * @param arguments custom arguments to the script. a number, a boolean, a String,
145 * a {@link com.atlassian.pageobjects.elements.PageElement}, a {@link org.openqa.selenium.WebElement} or a List of
146 * any combination of the above
147 * @return One of Boolean, Long, String, List or {@link com.atlassian.pageobjects.elements.PageElement}. Or null.
148 * @throws NullPointerException if <tt>script</tt> is <code>null</code>
149 *
150 * @see org.openqa.selenium.JavascriptExecutor#executeAsyncScript(String, Object...) (String, Object...)
151 * @see #execute(String, Object...)
152 */
153 Object executeAsync(String script, Object... arguments);
154
155 /**
156 * <p>
157 * Provides the same functionality as {@link #executeAsync(Class, String, Object...)}, but lets the client specify
158 * the expected result type. The expected result type must not be <code>null</code> and must match the actual
159 * result from the executed script.
160 * </p>
161 *
162 * <p>
163 * Consider using {@link #executeTimed(Class, String, Object...)} instead.
164 * </p>
165 *
166 * @param resultType expected type of the result. One of Boolean, Long, String, List or
167 * {@link com.atlassian.pageobjects.elements.PageElement} . Must not be <code>null</code>
168 * @param script javascript to execute
169 * @param arguments custom arguments to the script. a number, a boolean, a String,
170 * a {@link com.atlassian.pageobjects.elements.PageElement}, a {@link org.openqa.selenium.WebElement} or a List of
171 * any combination of the above
172 * @return result of the script converted to the <tt>resultType</tt>
173 * @throws NullPointerException if <tt>script</tt> or <tt>resultType</tt> is <code>null</code>
174 * @throws IllegalArgumentException if <tt>resultType</tt> is not one of the expected types
175 * @throws ClassCastException if the actual result type does not match <tt>resultType</tt>
176 *
177 * @see #executeAsync(String, Object...) (String, Object...)
178 */
179 <T> T executeAsync(Class<T> resultType, String script, Object... arguments);
180 }