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