com.meterware.httpunit
Class WebClient

java.lang.Object
  com.meterware.httpunit.WebClient

Direct Known Subclasses:

ServletUnitClient, WebConversation

public abstract class WebClient

extends java.lang.Object

The context for a series of web requests. This class manages cookies used to maintain session context, computes relative URLs, and generally emulates the browser behavior needed to build an automated test of a web site.

Author:

Russell Gold, Jan Ohrstrom, Seth Ladd, Oliver Imbusch

Nested Class Summary

static class

WebClient.HeaderDictionary

Constructor Summary

protected

WebClient()

Method Summary

void	addClientListener(WebClientListener listener) Adds a listener to watch for requests and responses.
void	addCookie(java.lang.String name, java.lang.String value) Deprecated. as of 1.6, use #putCookie instead.
void	addWindowListener(WebWindowListener listener) Adds a listener to watch for window openings and closings.
void	clearContents() Resets the state of this client, removing all cookies, frames, and per-client headers.
void	clearProxyServer() Clears the proxy server settings.
ClientProperties	getClientProperties() Returns the properties associated with this client.
Cookie	getCookieDetails(java.lang.String name) Returns an object containing the details of the named cookie
CookieJar	getCookieJar() Deprecated. - use with care - was not public in the past
java.lang.String[]	getCookieNames() Returns the name of all the active cookies which will be sent to the server.
java.lang.String	getCookieValue(java.lang.String name) Returns the value of the specified cookie.
WebResponse	getCurrentPage() Returns the response representing the current top page in the main window.
boolean	getExceptionsThrownOnErrorStatus() Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
WebResponse	getFrameContents(FrameSelector targetFrame) Returns the response associated with the specified frame name in the main window.
WebResponse	getFrameContents(java.lang.String frameName) Returns the response associated with the specified frame name in the main window.
java.lang.String[]	getFrameNames() Returns the name of the currently active frames in the main window.
java.lang.String	getHeaderField(java.lang.String fieldName) Returns the value for the header field with the specified name.
protected java.util.Dictionary	getHeaderFields(java.net.URL targetURL) Returns the value of all current header fields.
WebWindow	getMainWindow()
java.lang.String	getNextAlert() Returns the next javascript alert without removing it from the queue.
WebWindow	getOpenWindow(java.lang.String name)
WebWindow[]	getOpenWindows()
java.lang.String	getProxyHost() Returns the name of the active proxy server.
int	getProxyPort() Returns the number of the active proxy port, or 0 is none is specified.
WebResponse	getResource(WebRequest request) Returns the resource specified by the request.
WebResponse	getResponse(java.lang.String urlString) Submits a GET method request and returns a response.
WebResponse	getResponse(WebRequest request) Submits a web request and returns a response, using all state developed so far as stored in cookies as requested by the server.
java.lang.String	getUserAgent() Deprecated. as of 1.4.6. Use ClientProperties#getUserAgent instead.
protected abstract WebResponse	newResponse(WebRequest request, FrameSelector targetFrame) Creates a web response object which represents the response to the specified web request.
java.lang.String	popNextAlert() Returns the next javascript alert and removes it from the queue.
void	putCookie(java.lang.String name, java.lang.String value) Defines a cookie to be sent to the server on every request.
void	removeClientListener(WebClientListener listener) Removes a listener to watch for requests and responses.
void	removeWindowListener(WebWindowListener listener) Removes a listener to watch for window openings and closings.
WebResponse	sendRequest(WebRequest request) Submits a web request and returns a response.
void	setAuthentication(java.lang.String realm, java.lang.String username, java.lang.String password) Specifies a username and password for on-demand authentication.
void	setAuthorization(java.lang.String userName, java.lang.String password) Deprecated. as of 1.7. Use #setAuthentication for more accurate emulation of browser behavior.
void	setDialogResponder(DialogResponder responder) Specifies the object which will respond to all dialogs.
void	setExceptionsThrownOnErrorStatus(boolean throwExceptions) Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
void	setHeaderField(java.lang.String fieldName, java.lang.String fieldValue) Sets the value for a header field to be sent with all requests.
void	setMainWindow(WebWindow mainWindow)
abstract void	setProxyServer(java.lang.String proxyHost, int proxyPort) Specifies a proxy server to use for requests from this client.
void	setProxyServer(java.lang.String proxyHost, int proxyPort, java.lang.String userName, java.lang.String password) Specifies a proxy server to use, along with a user and password for authentication.
void	setUserAgent(java.lang.String userAgent) Deprecated. as of 1.4.6. Use ClientProperties#setUserAgent instead.
protected void	updateMainWindow(FrameSelector frame, WebResponse response) Updates this web client based on a received response.
protected void	writeMessageBody(WebRequest request, java.io.OutputStream stream) Writes the message body for the request.

Methods inherited from class java.lang.Object

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

Constructor Detail

WebClient

protected WebClient()

Method Detail

getMainWindow

public WebWindow getMainWindow()

setMainWindow

public void setMainWindow(WebWindow mainWindow)

getOpenWindows

public WebWindow[] getOpenWindows()

getOpenWindow

public WebWindow getOpenWindow(java.lang.String name)

getResponse

public WebResponse getResponse(java.lang.String urlString)
                        throws java.io.IOException,
                               org.xml.sax.SAXException

Submits a GET method request and returns a response.

Throws:

org.xml.sax.SAXException - thrown if there is an error parsing the retrieved page

java.io.IOException

sendRequest

public WebResponse sendRequest(WebRequest request)
                        throws java.io.IOException,
                               org.xml.sax.SAXException

Submits a web request and returns a response. This is an alternate name for the getResponse method.

Throws:

java.io.IOException

org.xml.sax.SAXException

getCurrentPage

public WebResponse getCurrentPage()

Returns the response representing the current top page in the main window.

getResponse

public WebResponse getResponse(WebRequest request)
                        throws java.io.IOException,
                               org.xml.sax.SAXException

Submits a web request and returns a response, using all state developed so far as stored in cookies as requested by the server.

Throws:

org.xml.sax.SAXException - thrown if there is an error parsing the retrieved page

java.io.IOException

getFrameNames

public java.lang.String[] getFrameNames()

Returns the name of the currently active frames in the main window.

getFrameContents

public WebResponse getFrameContents(java.lang.String frameName)

Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.

getFrameContents

public WebResponse getFrameContents(FrameSelector targetFrame)

Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.

Since:

1.6

getResource

public WebResponse getResource(WebRequest request)
                        throws java.io.IOException

Returns the resource specified by the request. Does not update the client or load included framesets or scripts. May return null if the resource is a JavaScript URL which would normally leave the client unchanged.

Throws:

java.io.IOException

clearContents

public void clearContents()

Resets the state of this client, removing all cookies, frames, and per-client headers. This does not affect any listeners or preferences which may have been set.

addCookie

public void addCookie(java.lang.String name,
                      java.lang.String value)

Deprecated. as of 1.6, use #putCookie instead.

Defines a cookie to be sent to the server on every request.

putCookie

public void putCookie(java.lang.String name,
                      java.lang.String value)

Defines a cookie to be sent to the server on every request. This overrides any previous setting for this cookie name.

getCookieNames

public java.lang.String[] getCookieNames()

Returns the name of all the active cookies which will be sent to the server.

getCookieDetails

public Cookie getCookieDetails(java.lang.String name)

Returns an object containing the details of the named cookie

Since:

[ 1488617 ] alternate patch for cookie bug #1371204

getCookieValue

public java.lang.String getCookieValue(java.lang.String name)

Returns the value of the specified cookie.

getClientProperties

public ClientProperties getClientProperties()

Returns the properties associated with this client.

setUserAgent

public void setUserAgent(java.lang.String userAgent)

Deprecated. as of 1.4.6. Use ClientProperties#setUserAgent instead.

Specifies the user agent identification. Used to trigger browser-specific server behavior.

getUserAgent

public java.lang.String getUserAgent()

Deprecated. as of 1.4.6. Use ClientProperties#getUserAgent instead.

Returns the current user agent setting.

setAuthorization

public void setAuthorization(java.lang.String userName,
                             java.lang.String password)

Deprecated. as of 1.7. Use #setAuthentication for more accurate emulation of browser behavior.

Sets a username and password for a basic authentication scheme.

setAuthentication

public void setAuthentication(java.lang.String realm,
                              java.lang.String username,
                              java.lang.String password)

Specifies a username and password for on-demand authentication. Will only send the authorization header when challenged for the specified realm.

Parameters:

realm - the realm for which the credentials apply.

username - the user to authenticate

password - the credentials for the user

setProxyServer

public abstract void setProxyServer(java.lang.String proxyHost,
                                    int proxyPort)

Specifies a proxy server to use for requests from this client.

setProxyServer

public void setProxyServer(java.lang.String proxyHost,
                           int proxyPort,
                           java.lang.String userName,
                           java.lang.String password)

Specifies a proxy server to use, along with a user and password for authentication.

Since:

1.6

clearProxyServer

public void clearProxyServer()

Clears the proxy server settings.

getProxyHost

public java.lang.String getProxyHost()

Returns the name of the active proxy server.

getProxyPort

public int getProxyPort()

Returns the number of the active proxy port, or 0 is none is specified.

setHeaderField

public void setHeaderField(java.lang.String fieldName,
                           java.lang.String fieldValue)

Sets the value for a header field to be sent with all requests. If the value set is null, removes the header from those to be sent.

getHeaderField

public java.lang.String getHeaderField(java.lang.String fieldName)

Returns the value for the header field with the specified name. This method will ignore the case of the field name.

setExceptionsThrownOnErrorStatus

public void setExceptionsThrownOnErrorStatus(boolean throwExceptions)

Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response. Defaults to the value returned by HttpUnitOptions.getExceptionsThrownOnErrorStatus.

getExceptionsThrownOnErrorStatus

public boolean getExceptionsThrownOnErrorStatus()

Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.

addClientListener

public void addClientListener(WebClientListener listener)

Adds a listener to watch for requests and responses.

removeClientListener

public void removeClientListener(WebClientListener listener)

Removes a listener to watch for requests and responses.

addWindowListener

public void addWindowListener(WebWindowListener listener)

Adds a listener to watch for window openings and closings.

removeWindowListener

public void removeWindowListener(WebWindowListener listener)

Removes a listener to watch for window openings and closings.

getNextAlert

public java.lang.String getNextAlert()

Returns the next javascript alert without removing it from the queue.

popNextAlert

public java.lang.String popNextAlert()

Returns the next javascript alert and removes it from the queue. If the queue is empty, will return an empty string.

setDialogResponder

public void setDialogResponder(DialogResponder responder)

Specifies the object which will respond to all dialogs.

newResponse

protected abstract WebResponse newResponse(WebRequest request,
                                           FrameSelector targetFrame)
                                    throws java.io.IOException

Creates a web response object which represents the response to the specified web request.

Parameters:

request - the request to which the response should be generated

targetFrame - the frame in which the response should be stored

Throws:

java.io.IOException

writeMessageBody

protected final void writeMessageBody(WebRequest request,
                                      java.io.OutputStream stream)
                               throws java.io.IOException

Writes the message body for the request.

Throws:

java.io.IOException

getHeaderFields

protected java.util.Dictionary getHeaderFields(java.net.URL targetURL)

Returns the value of all current header fields.

updateMainWindow

protected final void updateMainWindow(FrameSelector frame,
                                      WebResponse response)
                               throws java.io.IOException,
                                      org.xml.sax.SAXException

Updates this web client based on a received response. This includes updating cookies and frames. This method is required by ServletUnit, which cannot call the updateWindow method directly.

Throws:

java.io.IOException

org.xml.sax.SAXException

getCookieJar

public CookieJar getCookieJar()

Deprecated. - use with care - was not public in the past

Support Request [ 1288796 ] getCookieJar() in WebClient

Returns:

the cookie jar