net.grinder.plugin.http

Interface HTTPPluginConnection

public interface HTTPPluginConnection

Interface that script can use to control HTTP connections.

Most of the documentation for this class has been copied verbatim from the HTTPClient documentation.

Author:

Philip Aston, Richard Perks, Bertrand Ave

See Also:

HTTPPluginControl

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Explicitly closes physical connection to the server.
void	setBandwidthLimit(int targetBPS) Artificially limit the bandwidth used by this connection.
void	setDefaultHeaders(NVPair[] defaultHeaders) Sets the default HTTP headers to be sent with each request.
void	setFollowRedirects(boolean followRedirects) Set whether redirects should be automatically followed.
void	setLocalAddress(String localAddress) Set the client IP address to use for outbound connections.
void	setProxyServer(String host, int port) Set the proxy server to use.
void	setTimeout(int timeout) Sets the timeout to be used for creating connections and reading responses.
void	setUseAuthorizationModule(boolean useAuthorizationModule) Set whether the HTTPClient Authorization Module is enabled.
void	setUseContentEncoding(boolean useContentEncoding) Set whether content encoding will be used.
void	setUseCookies(boolean useCookies) Set whether cookies will be used.
void	setUseTransferEncoding(boolean useTransferEncoding) Set whether transfer encoding will be used.
void	setVerifyServerDistinguishedName(boolean b) Set whether an exception should be thrown if the subject distinguished name of the server's certificate doesn't match the host name when establishing an HTTPS connection.

Method Detail

setFollowRedirects

void setFollowRedirects(boolean followRedirects)

Set whether redirects should be automatically followed.

This enables the HTTPClient Redirection module.

Default: false

Parameters:

followRedirects - true => follow redirects.

setUseCookies

void setUseCookies(boolean useCookies)

Set whether cookies will be used.

This enables the HTTPClient Cookie module.

Default: true

Parameters:

useCookies - true => use cookies.

setUseContentEncoding

void setUseContentEncoding(boolean useContentEncoding)

Set whether content encoding will be used.

This enables the HTTPClient Content Encoding module.

Default: false

Parameters:

useContentEncoding - true => use content encoding.

setUseTransferEncoding

void setUseTransferEncoding(boolean useTransferEncoding)

Set whether transfer encoding will be used.

This enables the HTTPClient Transfer Encoding module.

Default: false

Parameters:

useTransferEncoding - true => use transfer encoding.

setUseAuthorizationModule

void setUseAuthorizationModule(boolean useAuthorizationModule)

Set whether the HTTPClient Authorization Module is enabled.

Default: false

Parameters:

useAuthorizationModule - true => use the HTTPClient Authorization module.

setDefaultHeaders

void setDefaultHeaders(NVPair[] defaultHeaders)

Sets the default HTTP headers to be sent with each request.

The actual headers sent are determined as follows: for each header specified in multiple places a value given as part of the request takes priority over any default values set by this method, which in turn takes priority over any built-in default values. A different way of looking at it is that we start off with a list of all headers specified with the request, then add any default headers set by this method which aren't already in our list, and finally add any built-in headers which aren't yet in the list. There is one exception to this rule: Content-Length header is always ignored; and when posting form-data any Content-Type is ignored in favor of the built-in application/x-www-form-urlencoded (however it will be overridden by any content-type header specified as part of the request).

Typical headers you might want to set here are Accept and its Accept-* relatives, Connection, From, User-Agent, etc.

Parameters:

defaultHeaders - an array of header-name/value pairs (do not give the separating ':').

setTimeout

void setTimeout(int timeout)

Sets the timeout to be used for creating connections and reading responses.

Setting the timeout to anything other than 0 will cause additional threads to be spawned for each HTTP request made.

When a timeout expires the operation will throw a TimeoutException.

When creating new sockets the timeout will limit the time spent doing the host name translation and establishing the connection with the server.

The timeout also influences the reading of the response headers. However, it does not specify a how long, for example, HTTPResponse.getStatusCode() may take, as might be assumed. Instead it specifies how long a read on the socket may take. If the response dribbles in slowly with packets arriving quicker than the timeout then the method will complete normally. I.e. the exception is only thrown if nothing arrives on the socket for the specified time. Furthermore, the timeout only influences the reading of the headers, not the reading of the body.

Read timeouts are associated with responses, so that you may change this value before each request and it won't affect the reading of responses to previous requests.

Parameters:

timeout - the time in milliseconds. A time of 0 means wait indefinitely.

setVerifyServerDistinguishedName

void setVerifyServerDistinguishedName(boolean b)

Set whether an exception should be thrown if the subject distinguished name of the server's certificate doesn't match the host name when establishing an HTTPS connection.

Parameters:

b - a boolean value

setProxyServer

void setProxyServer(String host,
                  int port)

Set the proxy server to use. A null or empty string host parameter disables the proxy.

Note that if you set a proxy for the connection using this method, and a request made over this connection is redirected to a different server, then the connection used for new server will not pick this proxy setting, but instead will use the default proxy settings. The default proxy setting can be set using HTTPPluginControl.getConnectionDefaults().setProxyServer().

Parameters:

host - The host on which the proxy server resides.

port - The port the proxy server is listening on.

setLocalAddress

void setLocalAddress(String localAddress)
                     throws URLException

Set the client IP address to use for outbound connections.

The default client IP address, and hence the network interface, used for outbound HTTP requests is the first returned to the Java VM by the operating system. This method allows a different network interface to be specified that will be used for connections that are subsequently created. It does not affect existing socket connections that may have already been created for this HTTPPluginConnection.

localAddress should correspond to a local network interface.If it doesn't a java.net.BindException will be thrown when the connection is first used.

Parameters:

localAddress - The local host name or IP address to bind to. Pass null to set the default local interface.

Throws:

URLException - If localAddress could not be resolved.

setBandwidthLimit

void setBandwidthLimit(int targetBPS)

Artificially limit the bandwidth used by this connection.

Only bytes in the HTTP message bodies are taken into account when interpreting targetBPS. No account is taken of the network efficiency (e.g. it might take 10 bits on the wire to transmit one byte of application data), or of the HTTP headers.

The limiting is also applied to the bodies of POST requests uploaded to the server.

When bandwidth limiting is applied, the time taken by each HTTP request will be correspondingly longer.

.

Parameters:

targetBPS - Target bandwidth in bits per second. Set to 0 to disable bandwidth limiting.

close

void close()

Explicitly closes physical connection to the server. A new connection will be created if this HTTPPluginConnection is used again. You shouldn't normally need to call this.