com.gargoylesoftware.htmlunit
Class WebClient

java.lang.Object
  extended by com.gargoylesoftware.htmlunit.WebClient
All Implemented Interfaces:
Serializable

public class WebClient
extends Object
implements Serializable

An object that represents a web browser.

Version:
$Revision: 2161 $
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
See Also:
Serialized Form

Field Summary
static String HTMLUNIT_COOKIE_POLICY
          HtmlUnit's cookie policy is to be browser-compatible.
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)
          Create an instance that will use the specified BrowserVersion and proxy server
 
Method Summary
 void addHostsToProxyBypass(String pattern)
          Any hosts matched by the specified regular expression pattern will bypass the configured proxy.
 void addRequestHeader(String name, String value)
          Set a header which will be sent up on EVERY request from this client.
 void addWebWindowListener(WebWindowListener listener)
          Add a listener for WebWindowEvent's.
 void assertionFailed(String message)
          Deprecated.  
 void deregisterWebWindow(WebWindow webWindow)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Remove a web window from the list of available windows.
protected  URL encodeUrl(URL url)
          Encodes illegal parameter in path or query string (if any) as done by browsers.
static URL expandUrl(URL baseUrl, String relativeUrl)
          Expands a relative url relative to the specified base.
 Map getActiveXObjectMap()
          Return the active X object map for this webclient.
 AjaxController getAjaxController()
          Gets the current Ajax controller
 AlertHandler getAlertHandler()
          Return the alert handler for this webclient.
 BrowserVersion getBrowserVersion()
          Return the current browser version
 Cache getCache()
          Gets the cache currently used
 ConfirmHandler getConfirmHandler()
          Return the confirm handler.
 CredentialsProvider getCredentialsProvider()
          Returns the credentials provider for this client instance.
 WebWindow getCurrentWindow()
          Return 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.
static boolean getIgnoreOutsideContent()
          Get the state of the flag to ignore content outside the BODY and HTML tags
 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.
protected  Log getLog()
          Return the log object for this web client
 OnbeforeunloadHandler getOnbeforeunloadHandler()
          Return the onbeforeunload handler for this webclient.
 Page getPage(String url)
          Convenient method to build an URL and load it into the current WebWindow
 Page getPage(URL url)
          Convenient method to load a URL into the current WebWindow
 Page getPage(WebRequestSettings request)
          Convenient method to load a web request into the current WebWindow
 Page getPage(WebWindow opener, String target, WebRequestSettings params)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
 Page getPage(WebWindow webWindow, WebRequestSettings parameters)
          Send a request to a server and return a Page that represents the response from the server.
 PageCreator getPageCreator()
          Return the current page creator.
 boolean getPrintContentOnFailingStatusCode()
          Return true if the content of the resulting document will be printed to the console in the event of a failing response code.
 PromptHandler getPromptHandler()
          Return the prompt handler.
 RefreshHandler getRefreshHandler()
          Return the current refresh handler or null if one has not been set.
 ScriptPreProcessor getScriptPreProcessor()
          Return the script pre processor for this webclient.
 StatusHandler getStatusHandler()
          Return the status handler for this webclient.
 int getTimeout()
          Gets the timeout value for the WebConnection
 WebConnection getWebConnection()
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
 WebWindow getWebWindowByName(String name)
          Return the first WebWindow that matches the specified name.
 List getWebWindows()
          Return an immutable list of open web windows (top 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.
Initialize a new page for JavaScript.
 void initialize(WebWindow webWindow)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initialize a new web window for JavaScript.
 void initializeEmptyWindow(WebWindow webWindow)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initialize a new empty web window for JavaScript.
 boolean isCookiesEnabled()
          Returns true if cookies are 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()
          Return whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
 boolean isThrowExceptionOnFailingStatusCode()
          Return 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.
 WebResponse loadWebResponse(WebRequestSettings webRequestSettings)
          Loads a WebResponse from the server
 Page loadWebResponseInto(WebResponse webResponse, WebWindow webWindow)
          Use the specified WebResponse to create a Page object which will then get inserted into the WebWindow.
 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.
 WebWindow popFirstWindow()
          Return the "first" window for this client.
 void printContentIfNecessary(WebResponse webResponse)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
 void pushClearFirstWindow()
          Clear the first window for this client.
 void registerWebWindow(WebWindow webWindow)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Add a new web window to the list of available windows.
 void removeHostsFromProxyBypass(String pattern)
          Any hosts matched by the specified regular expression pattern will no longer bypass the configured proxy.
 void removeRequestHeader(String name)
          Remove a header
 void removeWebWindowListener(WebWindowListener listener)
          Remove a listener for WebWindowEvent's.
 void setActiveXObjectMap(Map activeXObjectMap)
          Set the active X object map for this webclient.
 void setAjaxController(AjaxController newValue)
          Sets the current Ajax controller EXPERIMENTAL - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
 void setAlertHandler(AlertHandler alertHandler)
          Set the alert handler for this webclient.
 void setCache(Cache cache)
          Sets the cache to use
 void setConfirmHandler(ConfirmHandler handler)
          Set the handler that will be executed when the javascript method Window.confirm() is called.
 void setCookiesEnabled(boolean enabled)
          Enable/disable cookie support.
 void setCredentialsProvider(CredentialsProvider credentialsProvider)
          Sets the credentials provider that will provide authentication information when trying to access protected information on a web server.
 void setCurrentWindow(WebWindow window)
          Set the current window for this client.
 void setHomePage(String homePage)
          Sets the client's homepage.
 void setHTMLParserListener(HTMLParserListener listener)
          Defines a listener for messages generated by the html parser.
Note: If getIgnoreOutsideContent() returns false, the parser will ignore closing <body> and <html> tags to be able to handle html content incorrectly located after the end of the html file.
static void setIgnoreOutsideContent(boolean ignoreOutsideContent)
          Set the flag on the HtmlParse to ignore the content that is outside of the BODY and HTML tags.
 void setIncorrectnessListener(IncorrectnessListener listener)
          Returns the current HTML incorrectness listener.
 void setJavaScriptEnabled(boolean enabled)
          Enable/disable JavaScript support.
 void setJavaScriptEngine(com.gargoylesoftware.htmlunit.javascript.JavaScriptEngine engine)
          This method is intended for testing only - use at your own risk.
 void setOnbeforeunloadHandler(OnbeforeunloadHandler onbeforeunloadHandler)
          Set the onbeforeunload handler for this webclient.
 void setPageCreator(PageCreator pageCreator)
          Set 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)
          Set the handler that will be executed when the javascript method Window.prompt() is called.
 void setRedirectEnabled(boolean enabled)
          Set whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
 void setRefreshHandler(RefreshHandler handler)
          Set the handler to be used whenever a refresh is triggered.
 void setScriptPreProcessor(ScriptPreProcessor scriptPreProcessor)
          Set the script pre processor for this webclient.
 void setStatusHandler(StatusHandler statusHandler)
          Set 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)
          Set the object that will resolve all url requests

This method is intended for unit testing HtmlUnit itself.

 void throwFailingHttpStatusCodeExceptionIfNecessary(WebResponse webResponse)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HTMLUNIT_COOKIE_POLICY

public static final String HTMLUNIT_COOKIE_POLICY
HtmlUnit's cookie policy is to be browser-compatible. Code which requires access to HtmlUnit's cookie policy should use this constant, rather than making assumptions and using one of the HttpClient CookiePolicy constants directly.

See Also:
Constant Field Values

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)
Create 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)
Set the object that will resolve all url requests

This method is intended for unit testing HtmlUnit itself. It is not expected to change but you shouldn't need to call it during normal use of HtmlUnit.

Parameters:
webConnection - The new web connection

getPage

public Page getPage(WebWindow webWindow,
                    WebRequestSettings 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 this frame.

The type of Page will depend on the content type of the http response.

Content type Type of page
"text/html" HtmlPage
"text/xhtml" HtmlPage
"application/xhtml+xml" HtmlPage for now, in the future it will be XML validated as well
"text/*" TextPage
Anything else UnexpectedPage

Parameters:
webWindow - The WebWindow to load this request into
parameters - Parameter object for the web request
Returns:
See above
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:
WebRequestSettings

getPage

public Page getPage(WebWindow opener,
                    String target,
                    WebRequestSettings 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,WebRequestSettings)

Parameters:
opener - The web window that initiated the request.
target - The name of the window to be opened. This is the name that would 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 Page getPage(String url)
             throws IOException,
                    FailingHttpStatusCodeException,
                    MalformedURLException
Convenient method to build an URL and load it into the current WebWindow

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 Page getPage(URL url)
             throws IOException,
                    FailingHttpStatusCodeException
Convenient method to load a URL into the current WebWindow

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 Page getPage(WebRequestSettings request)
             throws IOException,
                    FailingHttpStatusCodeException
Convenient method to load a web request into the current WebWindow

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,WebRequestSettings)

loadWebResponseInto

public Page loadWebResponseInto(WebResponse webResponse,
                                WebWindow webWindow)
                         throws IOException,
                                FailingHttpStatusCodeException
Use the specified WebResponse to create a Page object which will then get inserted into the WebWindow. All initialization and event notification will be handled here.

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

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()
Return true if the content of the resulting document will be printed to the console in the event of a failing response code.

Returns:
See above
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()
Return true if an exception will be thrown in the event of a failing response code.

Returns:
See above
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)
Set a header which will be sent up on EVERY request from this client.

Parameters:
name - The name of the header
value - The value of the header

removeRequestHeader

public void removeRequestHeader(String name)
Remove a header

Parameters:
name - Name of the header
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.

assertionFailed

public void assertionFailed(String message)
Deprecated. 

Throw an exception with the specified message. If junit is found in the classpath then a junit.framework.AssertionFailedError will be thrown (the same behavior as calling fail() in junit). If junit is not found then an IllegalStateException will be thrown instead of the AssertionFailedError.

Override this to provide custom behavior.

Parameters:
message - The failure message
See Also:
WebAssert

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)
Enable/disable 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

setCookiesEnabled

public void setCookiesEnabled(boolean enabled)
Enable/disable cookie support. By default, this property is enabled.

Parameters:
enabled - true to enable cookie support

isCookiesEnabled

public boolean isCookiesEnabled()
Returns true if cookies are enabled.

Returns:
true if cookies are 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

addHostsToProxyBypass

public void addHostsToProxyBypass(String pattern)
Any hosts matched by the specified regular expression pattern will bypass the configured proxy.

Parameters:
pattern - A regular expression pattern that matches the hostnames of the hosts which should bypass the configured proxy.
See Also:
Pattern

removeHostsFromProxyBypass

public void removeHostsFromProxyBypass(String pattern)
Any hosts matched by the specified regular expression pattern will no longer bypass the configured proxy.

Parameters:
pattern - The previously added regular expression pattern.
See Also:
Pattern

setAlertHandler

public void setAlertHandler(AlertHandler alertHandler)
Set the alert handler for this webclient.

Parameters:
alertHandler - The new alerthandler or null if none is specified.

getAlertHandler

public AlertHandler getAlertHandler()
Return the alert handler for this webclient.

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

setConfirmHandler

public void setConfirmHandler(ConfirmHandler handler)
Set 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()
Return the confirm handler.

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

setPromptHandler

public void setPromptHandler(PromptHandler handler)
Set 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()
Return the prompt handler.

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

setStatusHandler

public void setStatusHandler(StatusHandler statusHandler)
Set the status handler for this webclient.

Parameters:
statusHandler - The new alerthandler or null if none is specified.

getStatusHandler

public StatusHandler getStatusHandler()
Return the status handler for this webclient.

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

getBrowserVersion

public BrowserVersion getBrowserVersion()
Return the current browser version

Returns:
the current browser version.

getCurrentWindow

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

Returns:
The current window.

setCurrentWindow

public void setCurrentWindow(WebWindow window)
Set 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 window.

popFirstWindow

public WebWindow popFirstWindow()
Return the "first" window for this client. This is the first window opened since pushClearFirstWindow() was last called.

Returns:
The first window.

pushClearFirstWindow

public void pushClearFirstWindow()
Clear the first window for this client.


addWebWindowListener

public void addWebWindowListener(WebWindowListener listener)
Add a listener for WebWindowEvent's. 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)
Remove a listener for WebWindowEvent's.

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.

setRedirectEnabled

public void setRedirectEnabled(boolean enabled)
Set 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()
Return 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)
Set 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()
Return the current page creator.

Returns:
the page creator

getWebWindowByName

public WebWindow getWebWindowByName(String name)
                             throws WebWindowNotFoundException
Return 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.

initialize

public void initialize(WebWindow webWindow)
INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Initialize 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.
Initialize 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.
Initialize a new empty web 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.
Add a new web 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.
Remove a web window from the list of available windows.

Parameters:
webWindow - The WebWindow to remove

getLog

protected final Log getLog()
Return the log object for this web client

Returns:
The log object

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:
See above
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(WebRequestSettings webRequestSettings)
                            throws IOException
Loads a WebResponse from the server

Parameters:
webRequestSettings - settings to use when making the request
Returns:
The WebResponse
Throws:
IOException - if an IO problem occurs

encodeUrl

protected URL encodeUrl(URL url)
                 throws MalformedURLException,
                        URIException
Encodes illegal parameter in path or query string (if any) as done by browsers. Example: changes "http://first?a=b c" to "http://first?a=b%20c"

Parameters:
url - the url to encode
Returns:
the provided url if no change needed, the fixed url else
Throws:
MalformedURLException - if the new URL could note be instantiated
URIException - if the default protocol charset is not supported

getWebWindows

public List getWebWindows()
Return an immutable list of open web windows (top windows or not).

Returns:
The web windows

setRefreshHandler

public void setRefreshHandler(RefreshHandler handler)
Set 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()
Return the current refresh handler or null if one has not been set.

Returns:
The current RefreshHandler or null

setScriptPreProcessor

public void setScriptPreProcessor(ScriptPreProcessor scriptPreProcessor)
Set the script pre processor for this webclient.

Parameters:
scriptPreProcessor - The new preprocessor or null if none is specified

getScriptPreProcessor

public ScriptPreProcessor getScriptPreProcessor()
Return the script pre processor for this webclient.

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

setActiveXObjectMap

public void setActiveXObjectMap(Map activeXObjectMap)
Set 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 getActiveXObjectMap()
Return the active X object map for this webclient.

Returns:
the active X object map.

setHTMLParserListener

public void setHTMLParserListener(HTMLParserListener listener)
Defines a listener for messages generated by the html parser.
Note: If getIgnoreOutsideContent() returns false, the parser will ignore closing <body> and <html> tags to be able to handle html content incorrectly located after the end of the html file. As a consequence it will finally notify as errors that <body> and <html> are not closed properly even if they were correctly present.

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).

setIgnoreOutsideContent

public static void setIgnoreOutsideContent(boolean ignoreOutsideContent)
Set the flag on the HtmlParse to ignore the content that is outside of the BODY and HTML tags.

Parameters:
ignoreOutsideContent - The boolean flag to enable or disable the support of content outside of the HTML and BODY tags

getIgnoreOutsideContent

public static boolean getIgnoreOutsideContent()
Get the state of the flag to ignore content outside the BODY and HTML tags

Returns:
- The current state

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 EXPERIMENTAL - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.

Parameters:
newValue - the controller

setOnbeforeunloadHandler

public void setOnbeforeunloadHandler(OnbeforeunloadHandler onbeforeunloadHandler)
Set the onbeforeunload handler for this webclient.

Parameters:
onbeforeunloadHandler - The new onbeforeunloadHandler or null if none is specified.

getOnbeforeunloadHandler

public OnbeforeunloadHandler getOnbeforeunloadHandler()
Return 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 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)


Copyright © 2002-2010 Gargoyle Software Inc.. All Rights Reserved.