org.htmlunit.javascript

Class JavaScriptEngine

java.lang.Object

org.htmlunit.javascript.JavaScriptEngine

All Implemented Interfaces:

AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

public class JavaScriptEngine
extends Object
implements AbstractJavaScriptEngine<org.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, Lai Quang Duong, Sven Strickroth

See Also:

Rhino and Java Browser

Field Summary

Fields

Modifier and Type	Field and Description
static Object[]	EMPTY_ARGS ScriptRuntime.emptyArgs.
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 Object	UNDEFINED org.htmlunit.corejs.javascript.Undefined.instance.

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.
static void	applyPolyfills(WebClient webClient, BrowserVersion browserVersion, org.htmlunit.corejs.javascript.Context context, HtmlUnitScriptable scriptable) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.RhinoException	asJavaScriptException(HtmlUnitScriptable scope, String message, int type) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Object	callFunction(HtmlPage page, org.htmlunit.corejs.javascript.Function javaScriptFunction, org.htmlunit.corejs.javascript.Scriptable thisObject, Object[] args, DomNode node) Calls a JavaScript function and return the result.
Object	callFunction(HtmlPage page, org.htmlunit.corejs.javascript.Function function, org.htmlunit.corejs.javascript.Scriptable scope, org.htmlunit.corejs.javascript.Scriptable thisObject, Object[] args) Calls the given function taking care of synchronization issues.
<T> T	callSecured(org.htmlunit.corejs.javascript.ContextAction<T> action, HtmlPage page) Forwards this to the HtmlUnitContextFactory but with checking shutdown handling.
org.htmlunit.corejs.javascript.Script	compile(HtmlPage owningPage, org.htmlunit.corejs.javascript.Scriptable scope, String sourceCode, String sourceName, int startLine) Compiles the specified JavaScript code in the context of a given scope.
static HtmlUnitScriptable	configureClass(ClassConfiguration config, org.htmlunit.corejs.javascript.Scriptable window) Configures the specified class for access via JavaScript.
static void	configureRhino(WebClient webClient, BrowserVersion browserVersion, HtmlUnitScriptable scope) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static void	configureScope(HtmlUnitScriptable jsScope, ClassConfiguration scopeConfig, org.htmlunit.corejs.javascript.FunctionObject scopeContructorFunctionObject, AbstractJavaScriptConfiguration jsConfig, BrowserVersion browserVersion, Map<Class<? extends org.htmlunit.corejs.javascript.Scriptable>,org.htmlunit.corejs.javascript.Scriptable> prototypes, Map<String,org.htmlunit.corejs.javascript.Scriptable> prototypesPerJSName) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.EcmaError	constructError(String error, String message)
static String	evaluateProxyAutoConfig(BrowserVersion browserVersion, String content, URL url) Evaluates the FindProxyForURL method of the specified content.
Object	execute(HtmlPage page, org.htmlunit.corejs.javascript.Scriptable scope, org.htmlunit.corejs.javascript.Script script) Executes the specified JavaScript code in the context of a given page.
Object	execute(HtmlPage page, org.htmlunit.corejs.javascript.Scriptable scope, String sourceCode, String sourceName, int startLine) Executes the specified JavaScript code in the context of a given page.
HtmlUnitContextFactory	getContextFactory()
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.
static org.htmlunit.corejs.javascript.Scriptable	getTopCallScope()
protected void	handleJavaScriptException(ScriptException scriptException, boolean triggerOnError) Handles an exception that occurred during execution of JavaScript code.
protected void	handleJavaScriptTimeoutError(HtmlPage page, TimeoutError e) 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.
void	initialize(WebWindow webWindow, Page page) Performs initialization for the given webWindow.
static boolean	isArray(Object obj)
static boolean	isNaN(Object obj)
boolean	isScriptRunning() Indicates if JavaScript is running in current thread.
static boolean	isUndefined(Object obj)
static org.htmlunit.corejs.javascript.Scriptable	newArray(org.htmlunit.corejs.javascript.Scriptable scope, int length) Create an array with a specified initial length.
static org.htmlunit.corejs.javascript.Scriptable	newArray(org.htmlunit.corejs.javascript.Scriptable scope, Object[] elements) Create an array with a specified initial length.
static org.htmlunit.corejs.javascript.Scriptable	newArrayIteratorTypeEntries(org.htmlunit.corejs.javascript.Scriptable scope, org.htmlunit.corejs.javascript.Scriptable arrayLike) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.Scriptable	newArrayIteratorTypeKeys(org.htmlunit.corejs.javascript.Scriptable scope, org.htmlunit.corejs.javascript.Scriptable arrayLike) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.Scriptable	newArrayIteratorTypeValues(org.htmlunit.corejs.javascript.Scriptable scope, org.htmlunit.corejs.javascript.Scriptable arrayLike) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.Scriptable	newObject(org.htmlunit.corejs.javascript.Scriptable scope) Create a new JavaScript object.
static org.htmlunit.corejs.javascript.Scriptable	newObject(org.htmlunit.corejs.javascript.Scriptable scope, String constructorName, Object[] args) Create a new javascript object by calling the ctor with the provided args.
void	prepareShutdown() Disable starting of new js threads.
void	processPostponedActions() INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
static org.htmlunit.corejs.javascript.EcmaError	rangeError(String message) Report a runtime error using the error reporter for the current thread.
void	registerWindowAndMaybeStartEventLoop(WebWindow webWindow) Register WebWindow with the JavaScriptExecutor.
static RuntimeException	reportRuntimeError(String message) Report a runtime error using the error reporter for the current thread.
void	setJavaScriptTimeout(long timeout) Sets the javascript timeout.
void	shutdown() Shutdown the JavaScriptEngine.
static org.htmlunit.corejs.javascript.EcmaError	syntaxError(String message) Report a runtime error using the error reporter for the current thread.
static RuntimeException	throwAsScriptRuntimeEx(Throwable e) Rethrow the exception wrapping it as the script runtime exception.
static boolean	toBoolean(Object value) Convert the value to a JavaScript boolean value.
static int	toInt32(Object o)
static double	toInteger(Object o)
static double	toInteger(Object[] args, int index)
static double	toNumber(Object value) Convert the value to a JavaScript Number value.
static String	toString(Object value) Convert the value to a JavaScript String value.
static org.htmlunit.corejs.javascript.EcmaError	typeError(String message) Report a runtime error using the error reporter for the current thread.
static org.htmlunit.corejs.javascript.EcmaError	typeErrorIllegalConstructor() Report a TypeError with the message "Illegal constructor.".
static String	uncompressJavaScript(String scriptSource, String scriptName) Tries to uncompress the JavaScript code in the provided response.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ARGS

public static final Object[] EMPTY_ARGS

ScriptRuntime.emptyArgs.

UNDEFINED

public static final Object UNDEFINED

org.htmlunit.corejs.javascript.Undefined.instance.

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

getContextFactory

public HtmlUnitContextFactory getContextFactory()

Specified by:

getContextFactory in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Returns:

this JavaScript engine's HtmlUnitContextFactory

initialize

public void initialize(WebWindow webWindow,
                       Page page)

Performs initialization for the given webWindow.

Specified by:

initialize in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Parameters:

webWindow - the web window to initialize for

page - the page that will become the enclosing page

getJavaScriptExecutor

public JavaScriptExecutor getJavaScriptExecutor()

Returns the JavaScriptExecutor.

Returns:

the JavaScriptExecutor or null if javascript is disabled or no executor was required so far.

configureScope

public static void configureScope(HtmlUnitScriptable jsScope,
                                  ClassConfiguration scopeConfig,
                                  org.htmlunit.corejs.javascript.FunctionObject scopeContructorFunctionObject,
                                  AbstractJavaScriptConfiguration jsConfig,
                                  BrowserVersion browserVersion,
                                  Map<Class<? extends org.htmlunit.corejs.javascript.Scriptable>,org.htmlunit.corejs.javascript.Scriptable> prototypes,
                                  Map<String,org.htmlunit.corejs.javascript.Scriptable> prototypesPerJSName)
                           throws Exception

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.

Parameters:

jsScope - the js scope to set up

scopeConfig - the ClassConfiguration that is used for the scope

scopeContructorFunctionObject - the (already registered) ctor

jsConfig - the complete jsConfig

browserVersion - the BrowserVersion

prototypes - map of prototypes

prototypesPerJSName - map of prototypes with the class name as key

Throws:

Exception - in case of error

configureRhino

public static void configureRhino(WebClient webClient,
                                  BrowserVersion browserVersion,
                                  HtmlUnitScriptable scope)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.

Parameters:

webClient - the WebClient

browserVersion - the BrowserVersion

scope - the window or the DedicatedWorkerGlobalScope

applyPolyfills

public static void applyPolyfills(WebClient webClient,
                                  BrowserVersion browserVersion,
                                  org.htmlunit.corejs.javascript.Context context,
                                  HtmlUnitScriptable scriptable)
                           throws IOException

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.

Parameters:

webClient - the WebClient

browserVersion - the BrowserVersion

context - the current context

scriptable - the window or the DedicatedWorkerGlobalScope

Throws:

IOException - in case of problems

configureClass

public static HtmlUnitScriptable configureClass(ClassConfiguration config,
                                                org.htmlunit.corejs.javascript.Scriptable window)
                                         throws Exception

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

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

Exception - in case of errors

registerWindowAndMaybeStartEventLoop

public void registerWindowAndMaybeStartEventLoop(WebWindow webWindow)

Register WebWindow with the JavaScriptExecutor.

Specified by:

registerWindowAndMaybeStartEventLoop in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Parameters:

webWindow - the WebWindow to be registered.

prepareShutdown

public void prepareShutdown()

Disable starting of new js threads.

Specified by:

prepareShutdown in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

shutdown

public void shutdown()

Shutdown the JavaScriptEngine.

Specified by:

shutdown in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

compile

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

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

Specified by:

compile in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

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

callSecured

public final <T> T callSecured(org.htmlunit.corejs.javascript.ContextAction<T> action,
                               HtmlPage page)

Forwards this to the HtmlUnitContextFactory but with checking shutdown handling.

Type Parameters:

T - return type of the action

Parameters:

action - the contextAction

page - the page

Returns:

the result of the call

execute

public Object execute(HtmlPage page,
                      org.htmlunit.corejs.javascript.Scriptable scope,
                      String sourceCode,
                      String sourceName,
                      int startLine)

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

Specified by:

execute in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Parameters:

page - the page that the code will execute within

scope - the scope in which to execute

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,
                      org.htmlunit.corejs.javascript.Scriptable scope,
                      org.htmlunit.corejs.javascript.Script script)

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

Specified by:

execute in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Parameters:

page - the page that the code will execute within

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,
                           org.htmlunit.corejs.javascript.Function javaScriptFunction,
                           org.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,
                           org.htmlunit.corejs.javascript.Function function,
                           org.htmlunit.corejs.javascript.Scriptable scope,
                           org.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 their own evaluation has been triggered by some JS code.

Specified by:

isScriptRunning in interface AbstractJavaScriptEngine<org.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<org.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

handleJavaScriptTimeoutError

protected void handleJavaScriptTimeoutError(HtmlPage page,
                                            TimeoutError e)

Handles an exception that occurred during execution of JavaScript code.

Parameters:

page - the page in which the script causing this exception was executed

e - the timeout error that was thrown from the script engine

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<org.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<org.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<org.htmlunit.corejs.javascript.Script>

Returns:

the configuration

getJavaScriptTimeout

public long getJavaScriptTimeout()

Returns the javascript timeout.

Specified by:

getJavaScriptTimeout in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Returns:

the javascript timeout

setJavaScriptTimeout

public void setJavaScriptTimeout(long timeout)

Sets the javascript timeout.

Specified by:

setJavaScriptTimeout in interface AbstractJavaScriptEngine<org.htmlunit.corejs.javascript.Script>

Parameters:

timeout - the timeout

toNumber

public static double toNumber(Object value)

Convert the value to a JavaScript Number value.

Parameters:

value - a JavaScript value

Returns:

the corresponding double value converted using the ECMA rules

toString

public static String toString(Object value)

Convert the value to a JavaScript String value.

Parameters:

value - a JavaScript value

Returns:

the corresponding String value converted using the ECMA rules

toBoolean

public static boolean toBoolean(Object value)

Convert the value to a JavaScript boolean value.

Parameters:

value - a JavaScript value

Returns:

the corresponding boolean value converted using the ECMA rules

throwAsScriptRuntimeEx

public static RuntimeException throwAsScriptRuntimeEx(Throwable e)

Rethrow the exception wrapping it as the script runtime exception.

Parameters:

e - the exception to rethrow