com.meterware.httpunit

Class WebClient

public abstract class WebClient extends 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 classWebClient.HeaderDictionary
Constructor Summary
protected WebClient()
Method Summary
voidaddClientListener(WebClientListener listener)
Adds a listener to watch for requests and responses.
voidaddCookie(String name, String value)
Defines a cookie to be sent to the server on every request.
voidaddWindowListener(WebWindowListener listener)
Adds a listener to watch for window openings and closings.
voidclearContents()
Resets the state of this client, removing all cookies, frames, and per-client headers.
voidclearProxyServer()
Clears the proxy server settings.
ClientPropertiesgetClientProperties()
Returns the properties associated with this client.
String[]getCookieNames()
Returns the name of all the active cookies which will be sent to the server.
StringgetCookieValue(String name)
Returns the value of the specified cookie.
WebResponsegetCurrentPage()
Returns the response representing the current top page in the main window.
booleangetExceptionsThrownOnErrorStatus()
Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
WebResponsegetFrameContents(String frameName)
Returns the response associated with the specified frame name in the main window.
WebResponsegetFrameContents(FrameSelector targetFrame)
Returns the response associated with the specified frame name in the main window.
String[]getFrameNames()
Returns the name of the currently active frames in the main window.
StringgetHeaderField(String fieldName)
Returns the value for the header field with the specified name.
protected DictionarygetHeaderFields(URL targetURL)
Returns the value of all current header fields.
WebWindowgetMainWindow()
StringgetNextAlert()
Returns the next javascript alert without removing it from the queue.
WebWindowgetOpenWindow(String name)
WebWindow[]getOpenWindows()
StringgetProxyHost()
Returns the name of the active proxy server.
intgetProxyPort()
Returns the number of the active proxy port, or 0 is none is specified.
WebResponsegetResource(WebRequest request)
Returns the resource specified by the request.
WebResponsegetResponse(String urlString)
Submits a GET method request and returns a response.
WebResponsegetResponse(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.
StringgetUserAgent()
Returns the current user agent setting.
protected abstract WebResponsenewResponse(WebRequest request, FrameSelector targetFrame)
Creates a web response object which represents the response to the specified web request.
StringpopNextAlert()
Returns the next javascript alert and removes it from the queue.
voidputCookie(String name, String value)
Defines a cookie to be sent to the server on every request.
voidremoveClientListener(WebClientListener listener)
Removes a listener to watch for requests and responses.
voidremoveWindowListener(WebWindowListener listener)
Removes a listener to watch for window openings and closings.
WebResponsesendRequest(WebRequest request)
Submits a web request and returns a response.
voidsetAuthorization(String userName, String password)
Sets a username and password for a basic authentication scheme.
voidsetDialogResponder(DialogResponder responder)
Specifies the object which will respond to all dialogs.
voidsetExceptionsThrownOnErrorStatus(boolean throwExceptions)
Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
voidsetHeaderField(String fieldName, String fieldValue)
Sets the value for a header field to be sent with all requests.
voidsetMainWindow(WebWindow mainWindow)
voidsetProxyServer(String proxyHost, int proxyPort)
Specifies a proxy server to use for requests from this client.
voidsetProxyServer(String proxyHost, int proxyPort, String userName, String password)
Specifies a proxy server to use, along with a user and password for authentication.
voidsetUserAgent(String userAgent)
Specifies the user agent identification.
protected voidupdateMainWindow(FrameSelector frame, WebResponse response)
Updates this web client based on a received response.
protected voidwriteMessageBody(WebRequest request, OutputStream stream)
Writes the message body for the request.

Constructor Detail

WebClient

protected WebClient()

Method Detail

addClientListener

public void addClientListener(WebClientListener listener)
Adds a listener to watch for requests and responses.

addCookie

public void addCookie(String name, String value)

Deprecated: as of 1.6, use #putCookie instead.

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

addWindowListener

public void addWindowListener(WebWindowListener listener)
Adds a listener to watch for window openings and closings.

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.

clearProxyServer

public void clearProxyServer()
Clears the proxy server settings.

getClientProperties

public ClientProperties getClientProperties()
Returns the properties associated with this client.

getCookieNames

public String[] getCookieNames()
Returns the name of all the active cookies which will be sent to the server.

getCookieValue

public String getCookieValue(String name)
Returns the value of the specified cookie.

getCurrentPage

public WebResponse getCurrentPage()
Returns the response representing the current top page in the main window.

getExceptionsThrownOnErrorStatus

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

getFrameContents

public WebResponse getFrameContents(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

getFrameNames

public String[] getFrameNames()
Returns the name of the currently active frames in the main window.

getHeaderField

public String getHeaderField(String fieldName)
Returns the value for the header field with the specified name. This method will ignore the case of the field name.

getHeaderFields

protected Dictionary getHeaderFields(URL targetURL)
Returns the value of all current header fields.

getMainWindow

public WebWindow getMainWindow()

getNextAlert

public String getNextAlert()
Returns the next javascript alert without removing it from the queue.

getOpenWindow

public WebWindow getOpenWindow(String name)

getOpenWindows

public WebWindow[] getOpenWindows()

getProxyHost

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

getResource

public WebResponse getResource(WebRequest request)
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.

getResponse

public WebResponse getResponse(String urlString)
Submits a GET method request and returns a response.

Throws: SAXException thrown if there is an error parsing the retrieved page

getResponse

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

Throws: SAXException thrown if there is an error parsing the retrieved page

getUserAgent

public String getUserAgent()

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

Returns the current user agent setting.

newResponse

protected abstract WebResponse newResponse(WebRequest request, FrameSelector targetFrame)
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

popNextAlert

public String popNextAlert()
Returns the next javascript alert and removes it from the queue. If the queue is empty, will return an empty string.

putCookie

public void putCookie(String name, String value)
Defines a cookie to be sent to the server on every request. This overrides any previous setting for this cookie name.

removeClientListener

public void removeClientListener(WebClientListener listener)
Removes a listener to watch for requests and responses.

removeWindowListener

public void removeWindowListener(WebWindowListener listener)
Removes a listener to watch for window openings and closings.

sendRequest

public WebResponse sendRequest(WebRequest request)
Submits a web request and returns a response. This is an alternate name for the getResponse method.

setAuthorization

public void setAuthorization(String userName, String password)
Sets a username and password for a basic authentication scheme.

setDialogResponder

public void setDialogResponder(DialogResponder responder)
Specifies the object which will respond to all dialogs.

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.

setHeaderField

public void setHeaderField(String fieldName, 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.

setMainWindow

public void setMainWindow(WebWindow mainWindow)

setProxyServer

public void setProxyServer(String proxyHost, int proxyPort)
Specifies a proxy server to use for requests from this client.

setProxyServer

public void setProxyServer(String proxyHost, int proxyPort, String userName, String password)
Specifies a proxy server to use, along with a user and password for authentication.

Since: 1.6

setUserAgent

public void setUserAgent(String userAgent)

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

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

updateMainWindow

protected final void updateMainWindow(FrameSelector frame, WebResponse response)
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.

writeMessageBody

protected final void writeMessageBody(WebRequest request, OutputStream stream)
Writes the message body for the request.