com.gargoylesoftware.htmlunit.javascript

Class JavaScriptEngine

java.lang.Object

com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine

All Implemented Interfaces:

AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

public class JavaScriptEngine
extends Object
implements AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

A wrapper for the Rhino JavaScript engine that provides browser specific features.

Like all classes in this package, this class is not intended for direct use and may change without notice.

Author:

Mike Bowler, Chen Jun, David K. Taylor, Chris Erskine, Ben Curren, David D. Kilzer, Marc Guillemot, Daniel Gredler, Ahmed Ashour, Amit Manjhi, Ronald Brill, Frank Danek

See Also:

Rhino and Java Browser

Field Summary

Fields

Modifier and Type	Field and Description
static String	KEY_STARTING_PAGE Key used to place the HtmlPage for which the JavaScript code is executed as thread local attribute in current context.
static String	KEY_STARTING_SCOPE Key used to place the scope in which the execution of some JavaScript code started as thread local attribute in current context.

Constructor Summary

Constructors

Constructor and Description
JavaScriptEngine(WebClient webClient) Creates an instance for the specified WebClient.

Method Summary

Modifier and Type	Method and Description
void	addPostponedAction(PostponedAction action) Adds an action that should be executed first when the script currently being executed has finished.
Object	callFunction(HtmlPage page, net.sourceforge.htmlunit.corejs.javascript.Function javaScriptFunction, net.sourceforge.htmlunit.corejs.javascript.Scriptable thisObject, Object[] args, DomNode node) Calls a JavaScript function and return the result.
Object	callFunction(HtmlPage page, net.sourceforge.htmlunit.corejs.javascript.Function function, net.sourceforge.htmlunit.corejs.javascript.Scriptable scope, net.sourceforge.htmlunit.corejs.javascript.Scriptable thisObject, Object[] args) Calls the given function taking care of synchronization issues.
net.sourceforge.htmlunit.corejs.javascript.Script	compile(HtmlPage owningPage, net.sourceforge.htmlunit.corejs.javascript.Scriptable scope, String sourceCode, String sourceName, int startLine) Compiles the specified JavaScript code in the context of a given scope.
net.sourceforge.htmlunit.corejs.javascript.Script	compile(HtmlPage page, String sourceCode, String sourceName, int startLine) Compiles the specified JavaScript code in the context of a given HTML page.
static HtmlUnitScriptable	configureClass(ClassConfiguration config, net.sourceforge.htmlunit.corejs.javascript.Scriptable window, BrowserVersion browserVersion) Configures the specified class for access via JavaScript.
Object	execute(HtmlPage page, net.sourceforge.htmlunit.corejs.javascript.Script script) Executes the specified JavaScript code in the context of a given page.
Object	execute(HtmlPage page, net.sourceforge.htmlunit.corejs.javascript.Scriptable scope, net.sourceforge.htmlunit.corejs.javascript.Script script) Executes the specified JavaScript code in the given scope.
Object	execute(HtmlPage page, String sourceCode, String sourceName, int startLine) Executes the specified JavaScript code in the context of a given page.
HtmlUnitContextFactory	getContextFactory() Returns this JavaScript engine's Rhino ContextFactory.
Class<? extends HtmlUnitScriptable>	getJavaScriptClass(Class<?> c) Gets the class of the JavaScript object for the node class.
JavaScriptConfiguration	getJavaScriptConfiguration() Gets the associated configuration.
JavaScriptExecutor	getJavaScriptExecutor() Returns the JavaScriptExecutor.
long	getJavaScriptTimeout() Returns the javascript timeout.
WebClient	getWebClient() Returns the web client that this engine is associated with.
protected void	handleJavaScriptException(ScriptException scriptException, boolean triggerOnError) Handles an exception that occurred during execution of JavaScript code.
void	holdPosponedActions() INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Indicates that no postponed action should be executed.
void	initialize(WebWindow webWindow) Performs initialization for the given webWindow.
boolean	isScriptRunning() Indicates if JavaScript is running in current thread.
void	processPostponedActions() INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Process postponed actions, if any.
int	pumpEventLoop(long timeoutMillis) Executes the jobs in the eventLoop till timeoutMillis expires or the eventLoop becomes empty.
void	registerWindowAndMaybeStartEventLoop(WebWindow webWindow) Register WebWindow with the JavaScriptExecutor.
void	setJavaScriptTimeout(long timeout) Sets the javascript timeout.
void	shutdown() Shutdown the JavaScriptEngine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

KEY_STARTING_SCOPE

public static final String KEY_STARTING_SCOPE

Key used to place the scope in which the execution of some JavaScript code started as thread local attribute in current context.

This is needed to resolve some relative locations relatively to the page in which the script is executed and not to the page which location is changed.

See Also:

Constant Field Values

KEY_STARTING_PAGE

public static final String KEY_STARTING_PAGE

Key used to place the HtmlPage for which the JavaScript code is executed as thread local attribute in current context.

See Also:

Constant Field Values

Constructor Detail

JavaScriptEngine

public JavaScriptEngine(WebClient webClient)

Creates an instance for the specified WebClient.

Parameters:

webClient - the client that will own this engine

Method Detail

getWebClient

public final WebClient getWebClient()

Returns the web client that this engine is associated with.

Returns:

the web client

getContextFactory

public HtmlUnitContextFactory getContextFactory()

Returns this JavaScript engine's Rhino ContextFactory.

Returns:

this JavaScript engine's Rhino ContextFactory

initialize

public void initialize(WebWindow webWindow)

Performs initialization for the given webWindow.

Specified by:

initialize in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

webWindow - the web window to initialize for

getJavaScriptExecutor

public JavaScriptExecutor getJavaScriptExecutor()

Returns the JavaScriptExecutor.

Returns:

the JavaScriptExecutor.

configureClass

public static HtmlUnitScriptable configureClass(ClassConfiguration config,
                                                net.sourceforge.htmlunit.corejs.javascript.Scriptable window,
                                                BrowserVersion browserVersion)
                                         throws InstantiationException,
                                                IllegalAccessException

Configures the specified class for access via JavaScript.

Parameters:

config - the configuration settings for the class to be configured

window - the scope within which to configure the class

browserVersion - the browser version

Returns:

the created prototype

Throws:

InstantiationException - if the new class cannot be instantiated

IllegalAccessException - if we don't have access to create the new instance

registerWindowAndMaybeStartEventLoop

public void registerWindowAndMaybeStartEventLoop(WebWindow webWindow)

Register WebWindow with the JavaScriptExecutor.

Specified by:

registerWindowAndMaybeStartEventLoop in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

webWindow - the WebWindow to be registered.

pumpEventLoop

public int pumpEventLoop(long timeoutMillis)

Executes the jobs in the eventLoop till timeoutMillis expires or the eventLoop becomes empty. No use in non-GAE mode (see GAEUtils.isGaeMode().

Parameters:

timeoutMillis - the timeout in milliseconds

Returns:

the number of jobs executed

shutdown

public void shutdown()

Shutdown the JavaScriptEngine.

Specified by:

shutdown in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

compile

public net.sourceforge.htmlunit.corejs.javascript.Script compile(HtmlPage page,
                                                                 String sourceCode,
                                                                 String sourceName,
                                                                 int startLine)

Compiles the specified JavaScript code in the context of a given HTML page.

Specified by:

compile in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

page - the page that the code will execute within

sourceCode - the JavaScript code to execute

sourceName - the name that will be displayed on error conditions

startLine - the line at which the script source starts

Returns:

the result of executing the specified code

compile

public net.sourceforge.htmlunit.corejs.javascript.Script compile(HtmlPage owningPage,
                                                                 net.sourceforge.htmlunit.corejs.javascript.Scriptable scope,
                                                                 String sourceCode,
                                                                 String sourceName,
                                                                 int startLine)

Compiles the specified JavaScript code in the context of a given scope.

Parameters:

owningPage - the page from which the code started

scope - the scope in which to execute the javascript code

sourceCode - the JavaScript code to execute

sourceName - the name that will be displayed on error conditions

startLine - the line at which the script source starts

Returns:

the result of executing the specified code

execute

public Object execute(HtmlPage page,
                      String sourceCode,
                      String sourceName,
                      int startLine)

Executes the specified JavaScript code in the context of a given page.

Specified by:

execute in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

page - the page that the code will execute within

sourceCode - the JavaScript code to execute

sourceName - the name that will be displayed on error conditions

startLine - the line at which the script source starts

Returns:

the result of executing the specified code

execute

public Object execute(HtmlPage page,
                      net.sourceforge.htmlunit.corejs.javascript.Script script)

Executes the specified JavaScript code in the context of a given page.

Specified by:

execute in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

page - the page that the code will execute within

script - the script to execute

Returns:

the result of executing the specified code

execute

public Object execute(HtmlPage page,
                      net.sourceforge.htmlunit.corejs.javascript.Scriptable scope,
                      net.sourceforge.htmlunit.corejs.javascript.Script script)

Executes the specified JavaScript code in the given scope.

Parameters:

page - the page that started the execution

scope - the scope in which to execute

script - the script to execute

Returns:

the result of executing the specified code

callFunction

public Object callFunction(HtmlPage page,
                           net.sourceforge.htmlunit.corejs.javascript.Function javaScriptFunction,
                           net.sourceforge.htmlunit.corejs.javascript.Scriptable thisObject,
                           Object[] args,
                           DomNode node)

Calls a JavaScript function and return the result.

Parameters:

page - the page

javaScriptFunction - the function to call

thisObject - the this object for class method calls

args - the list of arguments to pass to the function

node - the HTML element that will act as the context

Returns:

the result of the function call

callFunction

public Object callFunction(HtmlPage page,
                           net.sourceforge.htmlunit.corejs.javascript.Function function,
                           net.sourceforge.htmlunit.corejs.javascript.Scriptable scope,
                           net.sourceforge.htmlunit.corejs.javascript.Scriptable thisObject,
                           Object[] args)

Calls the given function taking care of synchronization issues.

Parameters:

page - the interactive page that caused this script to executed

function - the JavaScript function to execute

scope - the execution scope

thisObject - the 'this' object

args - the function's arguments

Returns:

the function result

isScriptRunning

public boolean isScriptRunning()

Indicates if JavaScript is running in current thread.

This allows code to know if there own evaluation is has been triggered by some JS code.

Specified by:

isScriptRunning in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Returns:

true if JavaScript is running

addPostponedAction

public void addPostponedAction(PostponedAction action)

Adds an action that should be executed first when the script currently being executed has finished.

Specified by:

addPostponedAction in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

action - the action

handleJavaScriptException

protected void handleJavaScriptException(ScriptException scriptException,
                                         boolean triggerOnError)

Handles an exception that occurred during execution of JavaScript code.

Parameters:

scriptException - the exception

triggerOnError - if true, this triggers the onerror handler

holdPosponedActions

public void holdPosponedActions()

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Indicates that no postponed action should be executed.

Specified by:

holdPosponedActions in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

processPostponedActions

public void processPostponedActions()

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Process postponed actions, if any.

Specified by:

processPostponedActions in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

getJavaScriptClass

public Class<? extends HtmlUnitScriptable> getJavaScriptClass(Class<?> c)

Gets the class of the JavaScript object for the node class.

Parameters:

c - the node class DomNode or some subclass.

Returns:

null if none found

getJavaScriptConfiguration

public JavaScriptConfiguration getJavaScriptConfiguration()

Gets the associated configuration.

Specified by:

getJavaScriptConfiguration in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Returns:

the configuration

getJavaScriptTimeout

public long getJavaScriptTimeout()

Returns the javascript timeout.

Specified by:

getJavaScriptTimeout in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Returns:

the javascript timeout

setJavaScriptTimeout

public void setJavaScriptTimeout(long timeout)

Sets the javascript timeout.

Specified by:

setJavaScriptTimeout in interface AbstractJavaScriptEngine<net.sourceforge.htmlunit.corejs.javascript.Script>

Parameters:

timeout - the timeout