com.gargoylesoftware.htmlunit
Class WebClient

java.lang.Object
  com.gargoylesoftware.htmlunit.WebClient

All Implemented Interfaces:

Serializable

public class WebClient
extends Object
implements Serializable

The main starting point in HtmlUnit: this class simulates a web browser.

A standard usage of HtmlUnit will start with using the getPage(String) method (or getPage(URL)) to load a first Page and will continue with further processing on this page depending on its type.

Example:

final WebClient webClient = new WebClient();
final HtmlPage startPage = webClient.getPage("http://htmlunit.sf.net");
assertEquals("HtmlUnit - Welcome to HtmlUnit", startPage.getTitleText());

Note: a WebClient instance is not thread safe. It is intended to be used from a single thread.

Version:

$Revision: 5864 $

Author:

Mike Bowler, Mike J. Bresnahan, Dominique Broeglin, Noboru Sinohara, Chen Jun, David K. Taylor, Christian Sell, Ben Curren, Marc Guillemot, Chris Erskine, Daniel Gredler, Sergey Gorelkin, Hans Donner, Paul King, Ahmed Ashour, Bruce Chapman, Sudhan Moghe, Martin Tamme, Amit Manjhi, Nicolas Belisle

See Also:

Serialized Form

Field Summary

static URL

URL_ABOUT_BLANK URL for "about:blank".

Constructor Summary

WebClient()
Creates a web client instance using the browser version returned by BrowserVersion.getDefault().

WebClient(BrowserVersion browserVersion)
Creates a web client instance using the specified BrowserVersion.

WebClient(BrowserVersion browserVersion, String proxyHost, int proxyPort)
Creates an instance that will use the specified BrowserVersion and proxy server.

Method Summary

void	addRequestHeader(String name, String value) Adds a header which will be sent with EVERY request from this client.
void	addWebWindowListener(WebWindowListener listener) Adds a listener for WebWindowEvents.
void	closeAllWindows() Closes all opened windows, stopping all background JavaScript processing.
void	deregisterWebWindow(WebWindow webWindow) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Removes a window from the list of available windows.
void	download(WebWindow requestingWindow, String target, WebRequest request, String description) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Perform the downloads and stores it for loading later into a window.
static URL	expandUrl(URL baseUrl, String relativeUrl) Expands a relative URL relative to the specified base.
Map<String,String>	getActiveXObjectMap() Returns the active X object map for this webclient.
AjaxController	getAjaxController() Gets the current AJAX controller.
AlertHandler	getAlertHandler() Returns the alert handler for this webclient.
AttachmentHandler	getAttachmentHandler() Returns the current attachment handler.
BrowserVersion	getBrowserVersion() Returns the current browser version.
Cache	getCache() Gets the cache currently being used.
ConfirmHandler	getConfirmHandler() Returns the confirm handler.
CookieManager	getCookieManager() Returns the cookie manager used by this web client.
CredentialsProvider	getCredentialsProvider() Returns the credentials provider for this client instance.
org.w3c.css.sac.ErrorHandler	getCssErrorHandler() Returns the CSS error handler used by this web client when CSS problems are encountered.
WebWindow	getCurrentWindow() Returns the "current" window for this client.
String	getHomePage() Returns the client's current homepage.
HTMLParserListener	getHTMLParserListener() Gets the configured listener for messages generated by the HTML parser.
IncorrectnessListener	getIncorrectnessListener() Gets the current listener for encountered incorrectness (except HTML parsing messages that are handled by the HTML parser listener).
com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine	getJavaScriptEngine() This method is intended for testing only - use at your own risk.
long	getJavaScriptTimeout() Returns the number of milliseconds that a script is allowed to execute before being terminated.
OnbeforeunloadHandler	getOnbeforeunloadHandler() Returns the onbeforeunload handler for this webclient.
<P extends Page> P	getPage(String url) Convenient method to build an URL and load it into the current WebWindow as it would be done by getPage(WebWindow, WebRequest).
<P extends Page> P	getPage(URL url) Convenient method to load a URL into the current top WebWindow as it would be done by getPage(WebWindow, WebRequest).
<P extends Page> P	getPage(WebRequest request) Convenient method to load a web request into the current top WebWindow.
<P extends Page> P	getPage(WebWindow opener, String target, WebRequest params) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
<P extends Page> P	getPage(WebWindow webWindow, WebRequest parameters) Send a request to a server and return a Page that represents the response from the server.
PageCreator	getPageCreator() Returns the current page creator.
boolean	getPrintContentOnFailingStatusCode() Returns true if the content of the resulting document will be printed to the console in the event of a failing response code.
PromptHandler	getPromptHandler() Returns the prompt handler.
ProxyConfig	getProxyConfig() Returns the proxy configuration for this client.
RefreshHandler	getRefreshHandler() Returns the current refresh handler or null if one has not been set.
ScriptPreProcessor	getScriptPreProcessor() Returns the script pre processor for this webclient.
StatusHandler	getStatusHandler() Returns the status handler for this webclient.
int	getTimeout() Gets the timeout value for the WebConnection.
List<TopLevelWindow>	getTopLevelWindows() Returns an immutable list of open top level windows.
WebConnection	getWebConnection() INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
WebWindow	getWebWindowByName(String name) Returns the first WebWindow that matches the specified name.
List<WebWindow>	getWebWindows() Returns an immutable list of open web windows (whether they are top level windows or not).
String	guessContentType(File file) Tries to guess the content type of the file. This utility could be located in an helper class but we can compare this functionality for instance with the "Helper Applications" settings of Mozilla and therefore see it as a property of the "browser".
void	initialize(Page newPage) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Initializes a new page for JavaScript.
void	initialize(WebWindow webWindow) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Initializes a new web window for JavaScript.
void	initializeEmptyWindow(WebWindow webWindow) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Initializes a new empty window for JavaScript.
boolean	isActiveXNative() Returns whether native ActiveX components are allowed or no.
boolean	isAppletEnabled() Returns true if Applet are enabled.
boolean	isCssEnabled() Returns true if CSS is enabled.
boolean	isJavaScriptEnabled() Returns true if JavaScript is enabled and the script engine was loaded successfully.
boolean	isPopupBlockerEnabled() Returns true if the popup window blocker is enabled.
boolean	isRedirectEnabled() Returns whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
boolean	isThrowExceptionOnFailingStatusCode() Returns true if an exception will be thrown in the event of a failing response code.
boolean	isThrowExceptionOnScriptError() Indicates if an exception should be thrown when a script execution fails (the default) or if it should be caught and just logged to allow page execution to continue.
void	loadDownloadedResponses() INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Loads downloaded responses into the corresponding windows.
WebResponse	loadWebResponse(WebRequest webRequest) Loads a WebResponse from the server.
Page	loadWebResponseInto(WebResponse webResponse, WebWindow webWindow) Creates a page based on the specified response and inserts it into the specified window.
DialogWindow	openDialogWindow(URL url, WebWindow opener, Object dialogArguments) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
WebWindow	openWindow(URL url, String windowName) Open a new window with the specified name.
WebWindow	openWindow(URL url, String windowName, WebWindow opener) Open a new window with the specified name.
void	printContentIfNecessary(WebResponse webResponse) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
void	registerWebWindow(WebWindow webWindow) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Adds a new window to the list of available windows.
void	removeRequestHeader(String name) Removes a header from being sent with EVERY request from this client.
void	removeWebWindowListener(WebWindowListener listener) Removes a listener for WebWindowEvents.
void	setActiveXNative(boolean allow) Sets whether to allow native ActiveX or no.
void	setActiveXObjectMap(Map<String,String> activeXObjectMap) Sets the active X object map for this webclient.
void	setAjaxController(AjaxController newValue) Sets the current AJAX controller.
void	setAlertHandler(AlertHandler alertHandler) Sets the alert handler for this webclient.
void	setAppletEnabled(boolean enabled) Enables/disables Applet support.
void	setAttachmentHandler(AttachmentHandler handler) Sets the attachment handler.
void	setCache(Cache cache) Sets the cache to use.
void	setConfirmHandler(ConfirmHandler handler) Sets the handler that will be executed when the JavaScript method Window.confirm() is called.
void	setCookieManager(CookieManager cookieManager) Sets the cookie manager used by this web client.
void	setCredentialsProvider(CredentialsProvider credentialsProvider) Sets the credentials provider that will provide authentication information when trying to access protected information on a web server.
void	setCssEnabled(boolean enabled) Enables/disables CSS support.
void	setCssErrorHandler(org.w3c.css.sac.ErrorHandler cssErrorHandler) Sets the CSS error handler used by this web client when CSS problems are encountered.
void	setCurrentWindow(WebWindow window) Sets the "current" window for this client.
void	setHomePage(String homePage) Sets the client's homepage.
void	setHTMLParserListener(HTMLParserListener listener) Sets the listener for messages generated by the HTML parser.
void	setIncorrectnessListener(IncorrectnessListener listener) Returns the current HTML incorrectness listener.
void	setJavaScriptEnabled(boolean enabled) Enables/disables JavaScript support.
void	setJavaScriptEngine(com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine engine) This method is intended for testing only - use at your own risk.
void	setJavaScriptTimeout(long timeout) Sets the number of milliseconds that a script is allowed to execute before being terminated.
void	setOnbeforeunloadHandler(OnbeforeunloadHandler onbeforeunloadHandler) Sets the onbeforeunload handler for this webclient.
void	setPageCreator(PageCreator pageCreator) Sets the object that will be used to create pages.
void	setPopupBlockerEnabled(boolean enabled) Enable/disable the popup window blocker.
void	setPrintContentOnFailingStatusCode(boolean enabled) Specify whether or not the content of the resulting document will be printed to the console in the event of a failing response code.
void	setPromptHandler(PromptHandler handler) Sets the handler that will be executed when the JavaScript method Window.prompt() is called.
void	setProxyConfig(ProxyConfig proxyConfig) Sets the proxy configuration for this client.
void	setRedirectEnabled(boolean enabled) Sets whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
void	setRefreshHandler(RefreshHandler handler) Sets the handler to be used whenever a refresh is triggered.
void	setScriptPreProcessor(ScriptPreProcessor scriptPreProcessor) Sets the script pre processor for this webclient.
void	setStatusHandler(StatusHandler statusHandler) Sets the status handler for this webclient.
void	setThrowExceptionOnFailingStatusCode(boolean enabled) Specify whether or not an exception will be thrown in the event of a failing status code.
void	setThrowExceptionOnScriptError(boolean newValue) Changes the behavior of this webclient when a script error occurs.
void	setTimeout(int timeout) Sets the timeout of the WebConnection.
void	setUseInsecureSSL(boolean useInsecureSSL) If set to true, the client will accept connections to any host, regardless of whether they have valid certificates or not.
void	setWebConnection(WebConnection webConnection) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK. Sets the object that will resolve all URL requests.
void	throwFailingHttpStatusCodeExceptionIfNecessary(WebResponse webResponse) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
int	waitForBackgroundJavaScript(long timeoutMillis) Experimental API: May be changed in next release and may not yet work perfectly!
int	waitForBackgroundJavaScriptStartingBefore(long delayMillis) Experimental API: May be changed in next release and may not yet work perfectly!

Methods inherited from class java.lang.Object

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

Field Detail

URL_ABOUT_BLANK

public static final URL URL_ABOUT_BLANK

URL for "about:blank".

Constructor Detail

WebClient

public WebClient()

Creates a web client instance using the browser version returned by BrowserVersion.getDefault().

WebClient

public WebClient(BrowserVersion browserVersion)

Creates a web client instance using the specified BrowserVersion.

Parameters:

browserVersion - the browser version to simulate

WebClient

public WebClient(BrowserVersion browserVersion,
                 String proxyHost,
                 int proxyPort)

Creates an instance that will use the specified BrowserVersion and proxy server.

Parameters:

browserVersion - the browser version to simulate

proxyHost - the server that will act as proxy

proxyPort - the port to use on the proxy server

Method Detail

getWebConnection

public WebConnection getWebConnection()

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

Return the object that will resolve all URL requests

Returns:

the connection that will be used

setWebConnection

public void setWebConnection(WebConnection webConnection)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Sets the object that will resolve all URL requests.

Parameters:

webConnection - the new web connection

getPage

public <P extends Page> P getPage(WebWindow webWindow,
                                  WebRequest parameters)
                       throws IOException,
                              FailingHttpStatusCodeException

Send a request to a server and return a Page that represents the response from the server. This page will be used to populate the provided window.

The returned Page will be created by the PageCreator configured by setPageCreator(PageCreator), if any.

The DefaultPageCreator will create a Page depending on the content type of the HTTP response, basically HtmlPage for HTML content, XmlPage for XML content, TextPage for other text content and UnexpectedPage for anything else.

Type Parameters:

P - the page type

Parameters:

webWindow - the WebWindow to load the result of the request into

parameters - Parameter object for the web request

Returns:

the page returned by the server when the specified request was made in the specified window

Throws:

IOException - if an IO error occurs

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true

See Also:

WebRequest

getPage

public <P extends Page> P getPage(WebWindow opener,
                                  String target,
                                  WebRequest params)
                       throws FailingHttpStatusCodeException,
                              IOException

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

Open a new web window and populate it with a page loaded by getPage(WebWindow,WebRequest)

Type Parameters:

P - the page type

Parameters:

opener - the web window that initiated the request

target - the name of the window to be opened (the name that will be passed into the JavaScript open() method)

params - any parameters

Returns:

the new page

Throws:

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true.

IOException - if an IO problem occurs

getPage

public <P extends Page> P getPage(String url)
                       throws IOException,
                              FailingHttpStatusCodeException,
                              MalformedURLException

Convenient method to build an URL and load it into the current WebWindow as it would be done by getPage(WebWindow, WebRequest).

Type Parameters:

P - the page type

Parameters:

url - the URL of the new content

Returns:

the new page

Throws:

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true.

IOException - if an IO problem occurs

MalformedURLException - if no URL can be created from the provided string

getPage

public <P extends Page> P getPage(URL url)
                       throws IOException,
                              FailingHttpStatusCodeException

Convenient method to load a URL into the current top WebWindow as it would be done by getPage(WebWindow, WebRequest).

Type Parameters:

P - the page type

Parameters:

url - the URL of the new content

Returns:

the new page

Throws:

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true.

IOException - if an IO problem occurs

getPage

public <P extends Page> P getPage(WebRequest request)
                       throws IOException,
                              FailingHttpStatusCodeException

Convenient method to load a web request into the current top WebWindow.

Type Parameters:

P - the page type

Parameters:

request - the request parameters

Returns:

the new page

Throws:

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true.

IOException - if an IO problem occurs

See Also:

getPage(WebWindow,WebRequest)

loadWebResponseInto

public Page loadWebResponseInto(WebResponse webResponse,
                                WebWindow webWindow)
                         throws IOException,
                                FailingHttpStatusCodeException

Creates a page based on the specified response and inserts it into the specified window. All page initialization and event notification is handled here.

Note that if the page created is an attachment page, and an AttachmentHandler has been registered with this client, the page is not loaded into the specified window; in this case, the page is loaded into a new window, and attachment handling is delegated to the registered AttachmentHandler.

Parameters:

webResponse - the response that will be used to create the new page

webWindow - the window that the new page will be placed within

Returns:

the newly created page

Throws:

IOException - if an IO error occurs

FailingHttpStatusCodeException - if the server returns a failing status code AND the property setThrowExceptionOnFailingStatusCode(boolean) is set to true

See Also:

setAttachmentHandler(AttachmentHandler)

setPrintContentOnFailingStatusCode

public void setPrintContentOnFailingStatusCode(boolean enabled)

Specify whether or not the content of the resulting document will be printed to the console in the event of a failing response code. Successful response codes are in the range 200-299. The default is true.

Parameters:

enabled - True to enable this feature

getPrintContentOnFailingStatusCode

public boolean getPrintContentOnFailingStatusCode()

Returns true if the content of the resulting document will be printed to the console in the event of a failing response code.

Returns:

true if the content of the resulting document will be printed to the console in the event of a failing response code

See Also:

setPrintContentOnFailingStatusCode(boolean)

printContentIfNecessary

public void printContentIfNecessary(WebResponse webResponse)

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

Logs the response's content if its status code indicates a request failure and getPrintContentOnFailingStatusCode() returns true.

Parameters:

webResponse - the response whose content may be logged

setThrowExceptionOnFailingStatusCode

public void setThrowExceptionOnFailingStatusCode(boolean enabled)

Specify whether or not an exception will be thrown in the event of a failing status code. Successful status codes are in the range 200-299. The default is true.

Parameters:

enabled - true to enable this feature

isThrowExceptionOnFailingStatusCode

public boolean isThrowExceptionOnFailingStatusCode()

Returns true if an exception will be thrown in the event of a failing response code.

Returns:

true if an exception will be thrown in the event of a failing response code

See Also:

setThrowExceptionOnFailingStatusCode(boolean)

throwFailingHttpStatusCodeExceptionIfNecessary

public void throwFailingHttpStatusCodeExceptionIfNecessary(WebResponse webResponse)

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

Throws a FailingHttpStatusCodeException if the request's status code indicates a request failure and isThrowExceptionOnFailingStatusCode() returns true.

Parameters:

webResponse - the response which may trigger a FailingHttpStatusCodeException

addRequestHeader

public void addRequestHeader(String name,
                             String value)

Adds a header which will be sent with EVERY request from this client.

Parameters:

name - the name of the header to add

value - the value of the header to add

See Also:

removeRequestHeader(String)

removeRequestHeader

public void removeRequestHeader(String name)

Removes a header from being sent with EVERY request from this client.

Parameters:

name - the name of the header to remove

See Also:

addRequestHeader(java.lang.String, java.lang.String)

setCredentialsProvider

public void setCredentialsProvider(CredentialsProvider credentialsProvider)

Sets the credentials provider that will provide authentication information when trying to access protected information on a web server. This information is required when the server is using Basic HTTP authentication, NTLM authentication, or Digest authentication.

Parameters:

credentialsProvider - the new credentials provider to use to authenticate

getCredentialsProvider

public CredentialsProvider getCredentialsProvider()

Returns the credentials provider for this client instance. By default, this method returns an instance of DefaultCredentialsProvider.

Returns:

the credentials provider for this client instance

getJavaScriptEngine

public com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine getJavaScriptEngine()

This method is intended for testing only - use at your own risk.

Returns:

the current JavaScript engine (never null)

setJavaScriptEngine

public void setJavaScriptEngine(com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine engine)

This method is intended for testing only - use at your own risk.

Parameters:

engine - the new script engine to use

setJavaScriptEnabled

public void setJavaScriptEnabled(boolean enabled)

Enables/disables JavaScript support. By default, this property is enabled.

Parameters:

enabled - true to enable JavaScript support

isJavaScriptEnabled

public boolean isJavaScriptEnabled()

Returns true if JavaScript is enabled and the script engine was loaded successfully.

Returns:

true if JavaScript is enabled

setCssEnabled

public void setCssEnabled(boolean enabled)

Enables/disables CSS support. By default, this property is enabled.

Parameters:

enabled - true to enable CSS support

isCssEnabled

public boolean isCssEnabled()

Returns true if CSS is enabled.

Returns:

true if CSS is enabled

setAppletEnabled

public void setAppletEnabled(boolean enabled)

Enables/disables Applet support. By default, this property is disabled.

Note: as of HtmlUnit-2.4, Applet support is experimental and minimal

Parameters:

enabled - true to enable Applet support

Since:

HtmlUnit-2.4

isAppletEnabled

public boolean isAppletEnabled()

Returns true if Applet are enabled.

Returns:

true if Applet is enabled

setPopupBlockerEnabled

public void setPopupBlockerEnabled(boolean enabled)

Enable/disable the popup window blocker. By default, the popup blocker is disabled, and popup windows are allowed. When set to true, window.open() has no effect and returns null.

Parameters:

enabled - true to enable the popup window blocker

isPopupBlockerEnabled

public boolean isPopupBlockerEnabled()

Returns true if the popup window blocker is enabled.

Returns:

true if the popup window blocker is enabled

getHomePage

public String getHomePage()

Returns the client's current homepage.

Returns:

the client's current homepage

setHomePage

public void setHomePage(String homePage)

Sets the client's homepage.

Parameters:

homePage - the new homepage URL

getProxyConfig

public ProxyConfig getProxyConfig()

Returns the proxy configuration for this client.

Returns:

the proxy configuration for this client

setProxyConfig

public void setProxyConfig(ProxyConfig proxyConfig)

Sets the proxy configuration for this client.

Parameters:

proxyConfig - the proxy configuration for this client

getCookieManager

public CookieManager getCookieManager()

Returns the cookie manager used by this web client.

Returns:

the cookie manager used by this web client

setCookieManager

public void setCookieManager(CookieManager cookieManager)

Sets the cookie manager used by this web client.

Parameters:

cookieManager - the cookie manager used by this web client

setAlertHandler

public void setAlertHandler(AlertHandler alertHandler)

Sets the alert handler for this webclient.

Parameters:

alertHandler - the new alerthandler or null if none is specified

getAlertHandler

public AlertHandler getAlertHandler()

Returns the alert handler for this webclient.

Returns:

the alert handler or null if one hasn't been set

setConfirmHandler

public void setConfirmHandler(ConfirmHandler handler)

Sets the handler that will be executed when the JavaScript method Window.confirm() is called.

Parameters:

handler - the new handler or null if no handler is to be used

getConfirmHandler

public ConfirmHandler getConfirmHandler()

Returns the confirm handler.

Returns:

the confirm handler or null if one hasn't been set

setPromptHandler

public void setPromptHandler(PromptHandler handler)

Sets the handler that will be executed when the JavaScript method Window.prompt() is called.

Parameters:

handler - the new handler or null if no handler is to be used

getPromptHandler

public PromptHandler getPromptHandler()

Returns the prompt handler.

Returns:

the prompt handler or null if one hasn't been set

setStatusHandler

public void setStatusHandler(StatusHandler statusHandler)

Sets the status handler for this webclient.

Parameters:

statusHandler - the new status handler or null if none is specified

getStatusHandler

public StatusHandler getStatusHandler()

Returns the status handler for this webclient.

Returns:

the status handler or null if one hasn't been set

getBrowserVersion

public BrowserVersion getBrowserVersion()

Returns the current browser version.

Returns:

the current browser version

getCurrentWindow

public WebWindow getCurrentWindow()

Returns the "current" window for this client. This window (or its top window) will be used when getPage(...) is called without specifying a window.

Returns:

the "current" window for this client

setCurrentWindow

public void setCurrentWindow(WebWindow window)

Sets the "current" window for this client. This is the window that will be used when getPage(...) is called without specifying a window.

Parameters:

window - the new "current" window for this client

addWebWindowListener

public void addWebWindowListener(WebWindowListener listener)

Adds a listener for WebWindowEvents. All events from all windows associated with this client will be sent to the specified listener.

Parameters:

listener - a listener

removeWebWindowListener

public void removeWebWindowListener(WebWindowListener listener)

Removes a listener for WebWindowEvents.

Parameters:

listener - a listener

openWindow

public WebWindow openWindow(URL url,
                            String windowName)

Open a new window with the specified name. If the URL is non-null then attempt to load a page from that location and put it in the new window.

Parameters:

url - the URL to load content from or null if no content is to be loaded

windowName - the name of the new window

Returns:

the new window

openWindow

public WebWindow openWindow(URL url,
                            String windowName,
                            WebWindow opener)

Open a new window with the specified name. If the URL is non-null then attempt to load a page from that location and put it in the new window.

Parameters:

url - the URL to load content from or null if no content is to be loaded

windowName - the name of the new window

opener - the web window that is calling openWindow

Returns:

the new window

openDialogWindow

public DialogWindow openDialogWindow(URL url,
                                     WebWindow opener,
                                     Object dialogArguments)
                              throws IOException

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

Opens a new dialog window.

Parameters:

url - the URL of the document to load and display

opener - the web window that is opening the dialog

dialogArguments - the object to make available inside the dialog via window.dialogArguments

Returns:

the new dialog window

Throws:

IOException - if there is an IO error

setRedirectEnabled

public void setRedirectEnabled(boolean enabled)

Sets whether or not redirections will be followed automatically on receipt of a redirect status code from the server.

Parameters:

enabled - true to enable automatic redirection

isRedirectEnabled

public boolean isRedirectEnabled()

Returns whether or not redirections will be followed automatically on receipt of a redirect status code from the server.

Returns:

true if automatic redirection is enabled

setUseInsecureSSL

public void setUseInsecureSSL(boolean useInsecureSSL)
                       throws GeneralSecurityException

If set to true, the client will accept connections to any host, regardless of whether they have valid certificates or not. This is especially useful when you are trying to connect to a server with expired or corrupt certificates.

Parameters:

useInsecureSSL - whether or not to use insecure SSL

Throws:

GeneralSecurityException - if a security error occurs

setPageCreator

public void setPageCreator(PageCreator pageCreator)

Sets the object that will be used to create pages. Set this if you want to customize the type of page that is returned for a given content type.

Parameters:

pageCreator - the new page creator

getPageCreator

public PageCreator getPageCreator()

Returns the current page creator.

Returns:

the page creator

getWebWindowByName

public WebWindow getWebWindowByName(String name)
                             throws WebWindowNotFoundException

Returns the first WebWindow that matches the specified name.

Parameters:

name - the name to search for

Returns:

the WebWindow with the specified name

Throws:

WebWindowNotFoundException - if the WebWindow can't be found

See Also:

getWebWindows(), getTopLevelWindows()

initialize

public void initialize(WebWindow webWindow)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initializes a new web window for JavaScript.

Parameters:

webWindow - the new WebWindow

initialize

public void initialize(Page newPage)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initializes a new page for JavaScript.

Parameters:

newPage - the new page

initializeEmptyWindow

public void initializeEmptyWindow(WebWindow webWindow)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initializes a new empty window for JavaScript.

Parameters:

webWindow - the new WebWindow

registerWebWindow

public void registerWebWindow(WebWindow webWindow)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Adds a new window to the list of available windows.

Parameters:

webWindow - the new WebWindow

deregisterWebWindow

public void deregisterWebWindow(WebWindow webWindow)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Removes a window from the list of available windows.

Parameters:

webWindow - the window to remove

expandUrl

public static URL expandUrl(URL baseUrl,
                            String relativeUrl)
                     throws MalformedURLException

Expands a relative URL relative to the specified base. In most situations this is the same as new URL(baseUrl, relativeUrl) but there are some cases that URL doesn't handle correctly. See RFC1808 regarding Relative Uniform Resource Locators for more information.

Parameters:

baseUrl - the base URL

relativeUrl - the relative URL

Returns:

the expansion of the specified base and relative URLs

Throws:

MalformedURLException - if an error occurred when creating a URL object

guessContentType

public String guessContentType(File file)

Tries to guess the content type of the file.
This utility could be located in an helper class but we can compare this functionality for instance with the "Helper Applications" settings of Mozilla and therefore see it as a property of the "browser".

Parameters:

file - the file

Returns:

"application/octet-stream" if nothing could be guessed

loadWebResponse

public WebResponse loadWebResponse(WebRequest webRequest)
                            throws IOException

Loads a WebResponse from the server.

Parameters:

webRequest - the request

Returns:

the WebResponse

Throws:

IOException - if an IO problem occurs

getWebWindows

public List<WebWindow> getWebWindows()

Returns an immutable list of open web windows (whether they are top level windows or not).

Returns:

an immutable list of open web windows (whether they are top level windows or not)

See Also:

getWebWindowByName(String), getTopLevelWindows()

getTopLevelWindows

public List<TopLevelWindow> getTopLevelWindows()

Returns an immutable list of open top level windows.

Returns:

an immutable list of open top level windows

See Also:

getWebWindowByName(String), getWebWindows()

setRefreshHandler

public void setRefreshHandler(RefreshHandler handler)

Sets the handler to be used whenever a refresh is triggered. Refer to the documentation for RefreshHandler for more details.

Parameters:

handler - the new handler

getRefreshHandler

public RefreshHandler getRefreshHandler()

Returns the current refresh handler or null if one has not been set.

Returns:

the current RefreshHandler or null

setScriptPreProcessor

public void setScriptPreProcessor(ScriptPreProcessor scriptPreProcessor)

Sets the script pre processor for this webclient.

Parameters:

scriptPreProcessor - the new preprocessor or null if none is specified

getScriptPreProcessor

public ScriptPreProcessor getScriptPreProcessor()

Returns the script pre processor for this webclient.

Returns:

the pre processor or null of one hasn't been set

setActiveXObjectMap

public void setActiveXObjectMap(Map<String,String> activeXObjectMap)

Sets the active X object map for this webclient. The Map is used to map the string passed into the ActiveXObject constructor to a java class name. Therefore you can emulate ActiveXObjects in a web page's JavaScript by mapping the object name to a java class to emulate the active X object.

Parameters:

activeXObjectMap - the new preprocessor or null if none is specified

getActiveXObjectMap

public Map<String,String> getActiveXObjectMap()

Returns the active X object map for this webclient.

Returns:

the active X object map

setActiveXNative

public void setActiveXNative(boolean allow)

Sets whether to allow native ActiveX or no. Default value is false. Beware that you should never allow running native ActiveX components unless you fully trust the JavaScript code, as it is not controlled by the Java Virtual Machine.

Parameters:

allow - whether to allow or no

isActiveXNative

public boolean isActiveXNative()

Returns whether native ActiveX components are allowed or no.

Returns:

whether native ActiveX components are allowed or no

setHTMLParserListener

public void setHTMLParserListener(HTMLParserListener listener)

Sets the listener for messages generated by the HTML parser.

Parameters:

listener - the new listener, null if messages should be totally ignored

getHTMLParserListener

public HTMLParserListener getHTMLParserListener()

Gets the configured listener for messages generated by the HTML parser.

Returns:

null if no listener is defined (default value)

getCssErrorHandler

public org.w3c.css.sac.ErrorHandler getCssErrorHandler()

Returns the CSS error handler used by this web client when CSS problems are encountered.

Returns:

the CSS error handler used by this web client when CSS problems are encountered

See Also:

DefaultCssErrorHandler, SilentCssErrorHandler

setCssErrorHandler

public void setCssErrorHandler(org.w3c.css.sac.ErrorHandler cssErrorHandler)

Sets the CSS error handler used by this web client when CSS problems are encountered.

Parameters:

cssErrorHandler - the CSS error handler used by this web client when CSS problems are encountered

See Also:

DefaultCssErrorHandler, SilentCssErrorHandler

setJavaScriptTimeout

public void setJavaScriptTimeout(long timeout)

Sets the number of milliseconds that a script is allowed to execute before being terminated. A value of 0 or less means no timeout.

Parameters:

timeout - the timeout value, in milliseconds

getJavaScriptTimeout

public long getJavaScriptTimeout()

Returns the number of milliseconds that a script is allowed to execute before being terminated. A value of 0 or less means no timeout.

Returns:

the timeout value, in milliseconds

getTimeout

public int getTimeout()

Gets the timeout value for the WebConnection.

Returns:

the timeout value in milliseconds

See Also:

setTimeout(int)

setTimeout

public void setTimeout(int timeout)

Sets the timeout of the WebConnection. Set to zero (the default) for an infinite wait.

Note: The timeout is used twice. The first is for making the socket connection, the second is for data retrieval. If the time is critical you must allow for twice the time specified here.

Parameters:

timeout - the value of the timeout in milliseconds

isThrowExceptionOnScriptError

public boolean isThrowExceptionOnScriptError()

Indicates if an exception should be thrown when a script execution fails (the default) or if it should be caught and just logged to allow page execution to continue.

Returns:

true if an exception is thrown on script error (the default)

setThrowExceptionOnScriptError

public void setThrowExceptionOnScriptError(boolean newValue)

Changes the behavior of this webclient when a script error occurs.

Parameters:

newValue - indicates if exception should be thrown or not

getIncorrectnessListener

public IncorrectnessListener getIncorrectnessListener()

Gets the current listener for encountered incorrectness (except HTML parsing messages that are handled by the HTML parser listener). Default value is an instance of IncorrectnessListenerImpl.

Returns:

the current listener (not null)

setIncorrectnessListener

public void setIncorrectnessListener(IncorrectnessListener listener)

Returns the current HTML incorrectness listener.

Parameters:

listener - the new value (not null)

getAjaxController

public AjaxController getAjaxController()

Gets the current AJAX controller.

Returns:

the controller

setAjaxController

public void setAjaxController(AjaxController newValue)

Sets the current AJAX controller.

Parameters:

newValue - the controller

setAttachmentHandler

public void setAttachmentHandler(AttachmentHandler handler)

Sets the attachment handler.

Parameters:

handler - the new attachment handler

getAttachmentHandler

public AttachmentHandler getAttachmentHandler()

Returns the current attachment handler.

Returns:

the current attachment handler

setOnbeforeunloadHandler

public void setOnbeforeunloadHandler(OnbeforeunloadHandler onbeforeunloadHandler)

Sets the onbeforeunload handler for this webclient.

Parameters:

onbeforeunloadHandler - the new onbeforeunloadHandler or null if none is specified

getOnbeforeunloadHandler

public OnbeforeunloadHandler getOnbeforeunloadHandler()

Returns the onbeforeunload handler for this webclient.

Returns:

the onbeforeunload handler or null if one hasn't been set

getCache

public Cache getCache()

Gets the cache currently being used.

Returns:

the cache (may not be null)

setCache

public void setCache(Cache cache)

Sets the cache to use.

Parameters:

cache - the new cache (must not be null)

closeAllWindows

public void closeAllWindows()

Closes all opened windows, stopping all background JavaScript processing.

waitForBackgroundJavaScript

public int waitForBackgroundJavaScript(long timeoutMillis)

Experimental API: May be changed in next release and may not yet work perfectly!

This method blocks until all background JavaScript tasks have finished executing. Background JavaScript tasks are JavaScript tasks scheduled for execution via window.setTimeout, window.setInterval or asynchronous XMLHttpRequest.

If a job is scheduled to begin executing after (now + timeoutMillis), this method will wait for timeoutMillis milliseconds and then return a value greater than 0. This method will never block longer than timeoutMillis milliseconds.

Use this method instead of waitForBackgroundJavaScriptStartingBefore(long) if you don't know when your background JavaScript is supposed to start executing, but you're fairly sure that you know how long it should take to finish executing.

Parameters:

timeoutMillis - the maximum amount of time to wait (in milliseconds)

Returns:

the number of background JavaScript jobs still executing or waiting to be executed when this method returns; will be 0 if there are no jobs left to execute

waitForBackgroundJavaScriptStartingBefore

public int waitForBackgroundJavaScriptStartingBefore(long delayMillis)

Experimental API: May be changed in next release and may not yet work perfectly!

This method blocks until all background JavaScript tasks scheduled to start executing before (now + delayMillis) have finished executing. Background JavaScript tasks are JavaScript tasks scheduled for execution via window.setTimeout, window.setInterval or asynchronous XMLHttpRequest.

If there is no background JavaScript task currently executing, and there is no background JavaScript task scheduled to start executing within the specified time, this method returns immediately -- even if there are tasks scheduled to be executed after (now + delayMillis).

Note that the total time spent executing a background JavaScript task is never known ahead of time, so this method makes no guarantees as to how long it will block.

Use this method instead of waitForBackgroundJavaScript(long) if you know roughly when your background JavaScript is supposed to start executing, but you're not necessarily sure how long it will take to execute.

Parameters:

delayMillis - the delay which determines the background tasks to wait for (in milliseconds)

Returns:

the number of background JavaScript jobs still executing or waiting to be executed when this method returns; will be 0 if there are no jobs left to execute

download

public void download(WebWindow requestingWindow,
                     String target,
                     WebRequest request,
                     String description)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Perform the downloads and stores it for loading later into a window. In the future downloads should be performed in parallel in separated threads. TODO: refactor it before next release.

Parameters:

requestingWindow - the window from which the request comes

target - the name of the target window

request - the request to perform

description - information about the origin of the request. Useful for debugging.

loadDownloadedResponses

public void loadDownloadedResponses()
                             throws FailingHttpStatusCodeException,
                                    IOException

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Loads downloaded responses into the corresponding windows. TODO: refactor it before next release.

Throws:

IOException - in case of exception

FailingHttpStatusCodeException - in case of exception