1 /*
2 * Copyright (c) 2002-2025 Gargoyle Software Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 * https://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 package org.htmlunit.javascript;
16
17 import org.htmlunit.Page;
18 import org.htmlunit.WebWindow;
19 import org.htmlunit.corejs.javascript.Scriptable;
20 import org.htmlunit.html.HtmlPage;
21 import org.htmlunit.javascript.configuration.JavaScriptConfiguration;
22
23 /**
24 * An interface for {@code JavaScriptEngine}.
25 *
26 * @param <SCRIPT> the script type
27 *
28 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
29 * @author <a href="mailto:chen_jun@users.sourceforge.net">Chen Jun</a>
30 * @author David K. Taylor
31 * @author Chris Erskine
32 * @author <a href="mailto:bcurren@esomnie.com">Ben Curren</a>
33 * @author David D. Kilzer
34 * @author Marc Guillemot
35 * @author Daniel Gredler
36 * @author Ahmed Ashour
37 * @author Amit Manjhi
38 * @author Ronald Brill
39 * @author Frank Danek
40 */
41 public interface AbstractJavaScriptEngine<SCRIPT> {
42
43 /**
44 * Gets the associated configuration.
45 * @return the configuration
46 */
47 JavaScriptConfiguration getJavaScriptConfiguration();
48
49 /**
50 * Adds an action that should be executed first when the script currently being executed has finished.
51 * @param action the action
52 */
53 void addPostponedAction(PostponedAction action);
54
55 /**
56 * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
57 * Process postponed actions, if any.
58 */
59 void processPostponedActions();
60
61 /**
62 * Register WebWindow with the JavaScriptExecutor.
63 * @param webWindow the WebWindow to be registered.
64 */
65 void registerWindowAndMaybeStartEventLoop(WebWindow webWindow);
66
67 /**
68 * Performs initialization for the given webWindow and page.
69 * @param webWindow the web window to initialize for
70 * @param page the page that will become the enclosing page
71 */
72 void initialize(WebWindow webWindow, Page page);
73
74 /**
75 * Sets the number of milliseconds that a script is allowed to execute before being terminated.
76 * A value of 0 or less means no timeout.
77 *
78 * @param timeout the timeout value, in milliseconds
79 */
80 void setJavaScriptTimeout(long timeout);
81
82 /**
83 * Returns the number of milliseconds that a script is allowed to execute before being terminated.
84 * A value of 0 or less means no timeout.
85 *
86 * @return the timeout value, in milliseconds
87 */
88 long getJavaScriptTimeout();
89
90 /**
91 * Disable starting of new js threads.
92 */
93 void prepareShutdown();
94
95 /**
96 * Shutdown the JavaScriptEngine.
97 */
98 void shutdown();
99
100 /**
101 * Indicates if JavaScript is running in current thread.
102 * This allows code to know if their own evaluation is has been triggered by some JS code.
103 * @return {@code true} if JavaScript is running
104 */
105 boolean isScriptRunning();
106
107 /**
108 * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
109 * Indicates that no postponed action should be executed.
110 */
111 void holdPosponedActions();
112
113 /**
114 * Compiles the specified JavaScript code in the context of a given scope.
115 *
116 * @param owningPage the page from which the code started
117 * @param scope the scope in which to execute the javascript code
118 * @param sourceCode the JavaScript code to execute
119 * @param sourceName the name that will be displayed on error conditions
120 * @param startLine the line at which the script source starts
121 * @return the result of executing the specified code
122 */
123 SCRIPT compile(HtmlPage owningPage, Scriptable scope, String sourceCode, String sourceName, int startLine);
124
125 /**
126 * Executes the specified JavaScript code in the context of a given page.
127 *
128 * @param page the page that the code will execute within
129 * @param scope the scope in which to execute
130 * @param script the script to execute
131 * @return the result of executing the specified code
132 */
133 Object execute(HtmlPage page, Scriptable scope, SCRIPT script);
134
135 /**
136 * Executes the specified JavaScript code in the context of a given page.
137 *
138 * @param page the page that the code will execute within
139 * @param scope the scope in which to execute
140 * @param sourceCode the JavaScript code to execute
141 * @param sourceName the name that will be displayed on error conditions
142 * @param startLine the line at which the script source starts
143 * @return the result of executing the specified code
144 */
145 Object execute(HtmlPage page,
146 Scriptable scope,
147 String sourceCode,
148 String sourceName,
149 int startLine);
150
151 /**
152 * @return this JavaScript engine's {@link HtmlUnitContextFactory}
153 */
154 HtmlUnitContextFactory getContextFactory();
155
156 }