com.browsermob.api
Interface HttpClient

public interface HttpClient

The API that makes HTTP requests for BrowserMob scripts. This API is used directly by VU scritps and indirectly by RBU scripts (browser requests are proxied through here). In either case, requests to this API are logged in the transaction results, with timings for time-to-first-byte, DNS lookup, time-to-last-byte, etc captured.

In addition to the basic GET/POST HTTP actions, this API provides many useful utilities to extend/modify the normal script or browser behavior. For example:

• remapHost(java.lang.String, java.lang.String) - Useful for simulating entries in your /etc/hosts file.
• addRequestInterceptor(HttpRequestInterceptor) - Allows your scripts to modify the behavior of all request in a single place.
• autoBasicAuthorization(java.lang.String, java.lang.String, java.lang.String) - If your site is protected by BASIC authentication, use this.
• rewriteUrl(java.lang.String, java.lang.String) - Uses regular expressions to rewrite a URL before the request is made.
• blacklistRequests(java.lang.String, int) and whitelistRequests(java.lang.String[], int) - For when you don't want certain requests to even be made.

Method Summary

void	addRequestInterceptor(HttpRequestInterceptor i) Registers a hook that will be called upon every single HTTP request.
void	addResponseInterceptor(HttpResponseInterceptor i) Registers a hook that will be called upon every single HTTP response.
void	autoBasicAuthorization(java.lang.String domain, java.lang.String username, java.lang.String password) Forces all requests to the specific domain ("example.com") or host ("www.example.com) to have the proper header necessary to automatically pass any BASIC authentication challenge (ie: the Authorization header) with the supplied username and password.
void	blacklistRequests(java.lang.String pattern, int responseCode) Instructs BrowserMob to blacklist any HTTP request that matches the supplied regular expression pattern, automatically registering the supplied response code as the response without actually making the call.
void	clearCookies() Remove all cookies.
void	clearDNSCache() Flushes the DNS cache used by this http client
void	createCookie(java.lang.String name, java.lang.String value, java.lang.String domain) Create a new cookie.
void	createCookie(java.lang.String name, java.lang.String value, java.lang.String domain, java.lang.String path) Create a new cookie.
HttpResponse	get(java.lang.String url) Issues an HTTP GET without any content verification.
HttpResponse	get(java.lang.String url, int expectedStatusCode) Issues an HTTP GET without any content verification but with a status code check.
HttpResponse	get(java.lang.String url, int expectedStatusCode, java.lang.String expectedLocation) Issues an HTTP GET without any content verification but with a status code check and, in case of a redirection, a location redirect check.
HttpResponse	get(java.lang.String url, java.lang.String verificationText) Issues an HTTP GET with content verification.
HttpResponse	get(java.lang.String url, java.lang.String verificationText, int expectedStatusCode) Issues an HTTP GET with content verification and automatic status code checking.
HttpResponse	get(java.lang.String url, java.lang.String verificationText, int expectedStatusCode, java.lang.String expectedLocation) Issues an HTTP GET with content verification and automatic status code checking.
Cookie	getCookie(java.lang.String name) Retrieve a cookie by name.
Cookie	getCookie(java.lang.String name, java.lang.String domain) Retrieve a cookie by name.
Cookie	getCookie(java.lang.String name, java.lang.String domain, java.lang.String path) Retrieve a cookie by name.
HttpGetRequest	newGet(java.lang.String url) Creates a new GET request that can be further modified before finally executed.
HttpPostRequest	newPost(java.lang.String url) Creates a new POST request that can be further modified before finally executed.
HttpResponse	post(java.lang.String url) Issues an HTTP POST without any content verification.
HttpResponse	post(java.lang.String url, int expectedStatusCode) Issues an HTTP POST with content verification and automatic status code checking.
HttpResponse	post(java.lang.String url, int expectedStatusCode, java.lang.String expectedLocation) Issues an HTTP POST with content verification and automatic status code checking.
HttpResponse	post(java.lang.String url, java.lang.String verificationText) Issues an HTTP POST with content verification.
HttpResponse	post(java.lang.String url, java.lang.String verificationText, int expectedStatusCode, NativeObject paramsNO) Issues an HTTP POST with content verification and automatic status code checking.
HttpResponse	post(java.lang.String url, java.lang.String verificationText, int expectedStatusCode, java.lang.String expectedLocation, NativeObject paramsNO) Issues an HTTP POST with content verification and automatic status code checking.
HttpResponse	post(java.lang.String url, java.lang.String verificationText, NativeObject paramsNO) Issues an HTTP POST with content verification.
void	remapHost(java.lang.String source, java.lang.String target) Provides functionality similar to editing your "hosts file" on your local computer.
void	rewriteUrl(java.lang.String match, java.lang.String replace) Tells the browser to rewrite any URL it encounters using the provided regular expression and replacement string.
void	setConnectionTimeout(int connectionTimeout) Sets the timeout for the connection to be established.
void	setDNSCacheTimeout(int timeout) Sets the TTL for objects in the DNS cache in seconds.
void	setFollowRedirects(boolean followRedirects) Tells the HttpClient whether redirects (300 status codes) should automatically be followed.
void	setRequestTimeout(int requestTimeout) Sets the request timeout for all subsequent HTTP requests.
void	setRetryCount(int count) Set the automatic retry count for HTTP requests (for VUs and RBUs alike).
void	setSocketOperationTimeout(int socketOperationTimeout) Sets the timeout for a socket operation, such as reading a byte from the HTTP stream (SO_TIMEOUT).
void	whitelistRequests(java.lang.String[] patterns, int responseCode) Instructs BrowserMob to whitelist any HTTP request that matches the supplied regular expression patterns, automatically registering the supplied response code as the response for any request not in the set of whitelists.

Method Detail

setRetryCount

void setRetryCount(int count)

Set the automatic retry count for HTTP requests (for VUs and RBUs alike). A request will be retried if the connection is dropped or interupted in any way. By default this is 0, following the similar behavior of most modern web browsers.

Parameters:

count - the number of times to retry an HTTP request (0 by default)

remapHost

void remapHost(java.lang.String source,
               java.lang.String target)

Provides functionality similar to editing your "hosts file" on your local computer. This can be used to map a domain to an IP address or alternative domain that isn't yet in the public DNS records. This is great for testing websites that aren't yet public.

Parameters:

source - the source host to re-map from (ie: www.example.com)

target - the target host to re-map to (ie: new.example.com)

addRequestInterceptor

void addRequestInterceptor(HttpRequestInterceptor i)

Registers a hook that will be called upon every single HTTP request. The argument passed in must be in in this form:

 c.addRequestInterceptor(function(req) {
     // do something to the request
 });
 

The req argument in your callback function has it's own set of functions that you can use to add/remove/edit headers and get the requesting URL. Consult the API documentation for the underlying library that BrowserMob uses (Apache HTTP Client) to see all the functions available to you.

Parameters:

i - the javascript function, in the form of function(req) { ... }

addResponseInterceptor

void addResponseInterceptor(HttpResponseInterceptor i)

Registers a hook that will be called upon every single HTTP response. The argument passed in must be in in this form:

 c.addRequestInterceptor(function(res) {
     // do something to the response
 });
 

The res argument in your callback function has it's own set of functions that you can use to read response headers and the status code. Consult the API documentation for the underlying library that BrowserMob uses (Apache HTTP Client) to see all the functions available to you.

Parameters:

i - the javascript function, in the form of function(res) { ... }

autoBasicAuthorization

void autoBasicAuthorization(java.lang.String domain,
                            java.lang.String username,
                            java.lang.String password)

Forces all requests to the specific domain ("example.com") or host ("www.example.com) to have the proper header necessary to automatically pass any BASIC authentication challenge (ie: the Authorization header) with the supplied username and password.

Parameters:

domain - the domain or host to auto authenticate

username - the username to login with

password - the password to login with

createCookie

void createCookie(java.lang.String name,
                  java.lang.String value,
                  java.lang.String domain)

Create a new cookie.

Parameters:

name -

value -

domain -

createCookie

void createCookie(java.lang.String name,
                  java.lang.String value,
                  java.lang.String domain,
                  java.lang.String path)

Create a new cookie.

Parameters:

name -

value -

domain -

path -

clearCookies

void clearCookies()

Remove all cookies.

getCookie

Cookie getCookie(java.lang.String name)

Retrieve a cookie by name. The first cookie matching the name will be returned.

Parameters:

name - the name of the cookie

Returns:

getCookie

Cookie getCookie(java.lang.String name,
                 java.lang.String domain)

Retrieve a cookie by name. The first cookie matching both name and domain will be returned.

Parameters:

name - the name of the cookie

domain - the domain for which the cookie is valid

Returns:

getCookie

Cookie getCookie(java.lang.String name,
                 java.lang.String domain,
                 java.lang.String path)

Retrieve a cookie by name. If domain or path are not null, they must match the cookie values exactly.

Parameters:

name - the name of the cookie

domain - the domain for which the cookie is valid

path - the subset of URLs on the origin server to which this cookie applies

Returns:

rewriteUrl

void rewriteUrl(java.lang.String match,
                java.lang.String replace)

Tells the browser to rewrite any URL it encounters using the provided regular expression and replacement string. For example, if the match parameter is "http://my-ad-vendor\.com/" and the replacement string is "http://example.com/mock_ads/", then when the browser tries to load http://my-ad-vendor.com/foo.js it would actually end up requesting http://example.com/mock_ads/foo.js.

This is very useful for when you can't change the underlying site by want to remap one request to another or possibly even force some requests to never make it to their intended destination (ie: perfect for site analytics packages when you don't want your scripts causing un-realistic traffic patterns).

Parameters:

match - the regular expression string to match against. You can use regex symbols such as ".", "\d", "\W", "[...]", etc.

replace - the plain text string to replace any matching subsection of a URL handled by the browser.

blacklistRequests

void blacklistRequests(java.lang.String pattern,
                       int responseCode)

Instructs BrowserMob to blacklist any HTTP request that matches the supplied regular expression pattern, automatically registering the supplied response code as the response without actually making the call. The response time for these requests will always be 0 ms. These requests will also not be matched against any automatic "expected response code" validation, even if one was supplied before making the request.

For example, to prevent Google Analytics requests from being issued, you could do the following:

 c.blacklistRequests("http://www\\.google-analytics\\.com/.*", 200);
 

Parameters:

pattern - the regular expression string to match against. You can use regex symbols such as ".", "\d", "\W", "[...]", etc.

responseCode - the HTTP response code to immediately "return" instead of making the actual HTTP request.

whitelistRequests

void whitelistRequests(java.lang.String[] patterns,
                       int responseCode)

Instructs BrowserMob to whitelist any HTTP request that matches the supplied regular expression patterns, automatically registering the supplied response code as the response for any request not in the set of whitelists. The response time for those requests will always be 0 ms. Those requests will also not be matched against any automatic "expected response code" validation, even if one was supplied before making the request.

For example, to prevent all 3rd party requests from being made and to only allow requests to www.example.com and images.example.com, you would do:

 c.whitelistRequests(["http://www\\.example\\.com/.*", "http://images\\.example.com\\.com/.*"], 200);
 

Parameters:

patterns - the array regular expression string to match against. You can use regex symbols such as ".", "\d", "\W", "[...]", etc.

responseCode - the HTTP response code to immediately "return" instead of making the actual HTTP request.

get

HttpResponse get(java.lang.String url)

Issues an HTTP GET without any content verification.

Parameters:

url - the URL to make an HTTP GET request to.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

get

HttpResponse get(java.lang.String url,
                 int expectedStatusCode)

Issues an HTTP GET without any content verification but with a status code check. If the status code returned does not match the supplied status code, an expection will be automatically thrown.

Parameters:

url - the URL to make an HTTP GET request to.

expectedStatusCode - the expected status code

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

get

HttpResponse get(java.lang.String url,
                 int expectedStatusCode,
                 java.lang.String expectedLocation)

Issues an HTTP GET without any content verification but with a status code check and, in case of a redirection, a location redirect check. If the status code returned does not match the supplied status code, an exception will be automatically thrown.

Parameters:

url - the URL to make an HTTP GET request to.

expectedStatusCode - the expected status code

expectedLocation - the expected redirect location

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

get

HttpResponse get(java.lang.String url,
                 java.lang.String verificationText)

Issues an HTTP GET with content verification. The text supplied is checked against the content returned by the HTTP request. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

Parameters:

url - the URL to make an HTTP GET request to.

verificationText - the text to check against the returned content.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

get

HttpResponse get(java.lang.String url,
                 java.lang.String verificationText,
                 int expectedStatusCode)

Issues an HTTP GET with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

Parameters:

url - the URL to make an HTTP GET request to.

verificationText - the text to check against the returned content.

expectedStatusCode - the expected status code

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

get

HttpResponse get(java.lang.String url,
                 java.lang.String verificationText,
                 int expectedStatusCode,
                 java.lang.String expectedLocation)

Issues an HTTP GET with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request and, in case of a redirection, a location redirect check. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

Parameters:

url - the URL to make an HTTP GET request to.

verificationText - the text to check against the returned content.

expectedStatusCode - the expected status code

expectedLocation - the expected redirect location

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url)

Issues an HTTP POST without any content verification.

Parameters:

url - the URL to make an HTTP POST request to.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  int expectedStatusCode)

Issues an HTTP POST with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request and, in case of a redirection, a location redirect check.

Parameters:

url - the URL to make an HTTP POST request to.

expectedStatusCode - the expected status code

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  int expectedStatusCode,
                  java.lang.String expectedLocation)

Issues an HTTP POST with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request and, in case of a redirection, a location redirect check.

Parameters:

url - the URL to make an HTTP POST request to.

expectedStatusCode - the expected status code

expectedLocation - the expected redirect location

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  java.lang.String verificationText)

Issues an HTTP POST with content verification. The text supplied is checked against the content returned by the HTTP request. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

Parameters:

url - the URL to make an HTTP POST request to.

verificationText - the text to check against the returned content.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  java.lang.String verificationText,
                  NativeObject paramsNO)

Issues an HTTP POST with content verification. The text supplied is checked against the content returned by the HTTP request. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

A set of HTTP parameters that are supplied in the POST data can be specified with the third argument. While the type is documented "NativeObject", this really just means that the argument can be some sort of JavaScript key/value pair. For example, a call might look like the following:

 c.post("http://example.com", null, {
     param_one: 'some value',
     param_two: ['foo', 'bar']
 });
 

Parameters:

url - the URL to make an HTTP POST request to.

verificationText - the text to check against the returned content.

paramsNO - the JavaScript map of parameters used when issuing an HTTP POST.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  java.lang.String verificationText,
                  int expectedStatusCode,
                  NativeObject paramsNO)

Issues an HTTP POST with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

A set of HTTP parameters that are supplied in the POST data can be specified with the third argument. While the type is documented "NativeObject", this really just means that the argument can be some sort of JavaScript key/value pair. For example, a call might look like the following:

 c.post("http://example.com", null, {
     param_one: 'some value',
     param_two: ['foo', 'bar']
 });
 

Parameters:

url - the URL to make an HTTP POST request to.

verificationText - the text to check against the returned content.

expectedStatusCode - the expected status code

paramsNO - the JavaScript map of parameters used when issuing an HTTP POST.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

post

HttpResponse post(java.lang.String url,
                  java.lang.String verificationText,
                  int expectedStatusCode,
                  java.lang.String expectedLocation,
                  NativeObject paramsNO)

Issues an HTTP POST with content verification and automatic status code checking. The text supplied is checked against the content returned by the HTTP request and, in case of a redirection, a location redirect check. The result of the content verification is supplied in the returned HttpResponse object. If null is passed in to the verification text, then no content verification is done.

A set of HTTP parameters that are supplied in the POST data can be specified with the third argument. While the type is documented "NativeObject", this really just means that the argument can be some sort of JavaScript key/value pair. For example, a call might look like the following:

 c.post("http://example.com", null, {
     param_one: 'some value',
     param_two: ['foo', 'bar']
 });
 

Parameters:

url - the URL to make an HTTP POST request to.

verificationText - the text to check against the returned content.

expectedStatusCode - the expected status code

expectedLocation - the expected redirect location

paramsNO - the JavaScript map of parameters used when issuing an HTTP POST.

Returns:

an object that contains the detailed object results (status code, timings, etc) and whether content verification matched.

setFollowRedirects

void setFollowRedirects(boolean followRedirects)

Tells the HttpClient whether redirects (300 status codes) should automatically be followed. By default this is true and is generally only set to false for VU scripts that have been converted from an existing RBU script.

Parameters:

followRedirects - true for redirects to be followed.

setRequestTimeout

void setRequestTimeout(int requestTimeout)

Sets the request timeout for all subsequent HTTP requests. The request timeout is the overall time it takes to complete an HTTP request. By default, this value is set to -1, which means there is no timeout and HTTP requests can continue forever provided they don't contain a socket operation timeout (SO_TIMEOUT) or connection timeout.

Parameters:

requestTimeout - the timeout value, in milliseconds, to use.

setSocketOperationTimeout

void setSocketOperationTimeout(int socketOperationTimeout)

Sets the timeout for a socket operation, such as reading a byte from the HTTP stream (SO_TIMEOUT). The default value for this setting is 30000, which is 30 seconds.

Parameters:

socketOperationTimeout - the timeout value, in milliseconds, to use.

setConnectionTimeout

void setConnectionTimeout(int connectionTimeout)

Sets the timeout for the connection to be established. The default value for this setting is 30000, which is 30 seconds.

Parameters:

connectionTimeout - the timeout value, in milliseconds, to use.

newGet

HttpGetRequest newGet(java.lang.String url)

Creates a new GET request that can be further modified before finally executed.

Parameters:

url - the URL to make an HTTP GET request to.

Returns:

an object representing the HTTP GET request that will be executed in the future.

newPost

HttpPostRequest newPost(java.lang.String url)

Creates a new POST request that can be further modified before finally executed.

Parameters:

url - the URL to make an HTTP POST request to.

Returns:

an object representing the HTTP POST request that will be executed in the future.

clearDNSCache

void clearDNSCache()

Flushes the DNS cache used by this http client

setDNSCacheTimeout

void setDNSCacheTimeout(int timeout)

Sets the TTL for objects in the DNS cache in seconds. Notice that -1 represents cache forever and 0 will effectively disable it

Parameters:

timeout - timeout in seconds