com.sun.slamd.http
Class HTTPClient

java.lang.Object
  com.sun.slamd.http.HTTPClient

public class HTTPClient

extends java.lang.Object

This class defines a client that may be used for communicating with Web servers using HTTP or HTTPS. It offers a number of features for behaving like actual Web browsers, including the ability to parse the contents of an HTML document, the ability to include images when retrieving a page, and the ability to operate through a proxy server.

Field Summary

static java.lang.String	AUTH_HEADER_PREFIX The prefix that will be used for the HTTP header that sends authentication information to the remote Web server.
static int	BUFFER_SIZE The size of the buffer that we will use for reading data.
static java.lang.String	PROXY_AUTH_HEADER_PREFIX The prefix that will be used for the HTTP header that sends authentication information to the proxy server.
static java.lang.String	STAT_TRACKER_REDIRECTS_FOLLOWED The display name for the stat tracker used to keep track of the number of redirects followed.
static java.lang.String	STAT_TRACKER_REQUESTS_PROCESSED The display name for the stat tracker used to keep track of the total number of requests processed.
static java.lang.String	STAT_TRACKER_RESPONSE_BODY_TIME The display name for the stat tracker used to keep track of the length of time required to retrieve the body of the response.
static java.lang.String	STAT_TRACKER_RESPONSE_CODES The display name for the stat tracker used to keep track of the response codes from all the requests.
static java.lang.String	STAT_TRACKER_RESPONSE_HEADER_TIME The display name for the stat tracker used to keep track of the length of time required to retrieve send the request and retrieve the header.
static java.lang.String	STAT_TRACKER_RESPONSE_SIZE The display name for the stat tracker used to keep track of the size in bytes of the response.
static java.lang.String	STAT_TRACKER_TOTAL_REQUEST_TIME The display name for the stat tracker used to keep track of the total length of time required to handle a request.

Constructor Summary

HTTPClient()
Creates a new instance of this HTTP client.

Method Summary

void	addCookie(HTTPCookie cookie) Adds the specified cookie to the set of cookies associated with this client.
boolean	authenticationEnabled() Indicates whether the client will attempt to provide authentication information to the remote HTTP server.
void	clearCommonHeaders() Removes all common headers that have been defined for this client.
void	clearCookies() Clears all cookie information associated with this client.
void	closeAll() Closes all open connections that are associated with this HTTP client.
boolean	cookiesEnabled() Indicates whether support for cookies is enabled in this client.
void	disableAuthentication() Indicates that no authentication should be performed for the remote Web server.
void	disableDebugMode() Indicates that this HTTP client should not operate in debug mode.
void	disableProxy() Indicates that the client should not use a proxy server but rather try to communicate directly with the remote Web server.
void	disableStatisticsCollection() Indicates that the client should not automatically maintain any statistics.
void	enableAuthentication(java.lang.String authID, java.lang.String authPW) Indicates that authentication should be performed for the remote Web server using the provided information.
void	enableDebugMode() Indicates that this HTTP client should operate in debug mode.
void	enableDebugMode(java.io.PrintStream debugStream) Indicates that this HTTP client should operate in debug mode.
void	enableProxy(java.lang.String proxyHost, int proxyPort) Indicates that the client should communicate with the specified proxy server rather than attempting to communicate directly with the remote Web server.
void	enableProxy(java.lang.String proxyHost, int proxyPort, java.lang.String proxyAuthID, java.lang.String proxyAuthPW) Indicates that the client should communicate with the specified proxy server rather than attempting to communicate directly with the remote Web server.
void	enableStatisticsCollection(java.lang.String clientID, java.lang.String threadID, int collectionInterval) Indicates that the client should automatically maintain a set of stat trackers that keep track of various statistics around HTTP processing.
boolean	followRedirects() Indicates whether this client will attempt to automatically follow redirects returned by the server.
java.lang.String	getAuthID() Retrieves the username that will be provided to the remote HTTP server if authentication will be performed.
java.lang.String	getAuthPassword() Retrieves the password that will be provided to the remote HTTP server if authentication will be performed.
java.lang.String	getCommonHeader(java.lang.String name) Retrieves the value of the common header with the provided name.
java.lang.String[]	getCommonHeaderNames() Retrieves the names of the common headers that have been defined for this client.
java.lang.String[][]	getCommonHeaders() Retrieves a two-dimensional array containing the names and values of all headers that will always be included in requests sent using this client.
java.lang.String[]	getCommonHeaderValues() Retreives the values of the common headers that have been defined for this client.
HTTPCookie[]	getCookies(java.net.URL requestURL) Retrieves an array of cookies that apply to the given URL.
java.lang.String	getProxyAuthID() Retrieves the username that will be provided to the HTTP proxy server if authentication will be performed.
java.lang.String	getProxyAuthPassword() Retrieves the password that will be provided to the HTTP proxy server if authentication will be performed.
java.lang.String	getProxyHost() Retrieves the address of the proxy server that has been configured.
int	getProxyPort() Retrieves the port number of the proxy server that has been configured.
javax.net.ssl.SSLSocketFactory	getSSLSocketFactory() Retrieves the socket factory that will be used to create SSL-based connections.
StatTracker[]	getStatTrackers() Retrieves the set of stat trackers that have been maintained by this client.
void	invalidateSSLSessions() Invalidates all SSL sessions associated with any connections held by this HTTP client.
static boolean	isRedirect(int statusCode) Indicates whether the provided status code defines a redirect that may be followed to get the actual content.
boolean	proxyAuthenticationEnabled() Indicates whether the client will attempt to authenticate to an HTTP proxy server.
boolean	proxyEnabled() Indicates whether the client will attempt to forward requests through an HTTP proxy server.
void	removeCommonHeader(java.lang.String name) Removes the common header with the specified name.
boolean	retrieveAssociatedFiles() Indicates whether this client should automatically retrieve any additional files associated with the HTML documents that are retrieved.
HTTPResponse	sendRequest(HTTPRequest request) Sends the provided request to the specified server and returns the response.
void	setCommonHeader(java.lang.String name, java.lang.String value) Adds a common header with the specified name and value.
void	setCookiesEnabled(boolean cookiesEnabled) Specifies whether cookie support should be enabled for this client.
void	setFollowRedirects(boolean followRedirects) Specifies whether this client should attempt to automatically follow redirects returned by the server.
void	setRetrieveAssociatedFiles(boolean retrieveAssociatedFiles) Specifies whether this client should automatically retrieve any additional files (images, external style sheets, frame elements, etc.) associated with any HTML documents that it retrieves.
void	setSSLSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory) Specifies the socket factory that should be used to create SSL-based connections.
void	setUseKeepAlive(boolean useKeepAlive) Indicates whether to use HTTP 1.1 keepalive to possibly re-use the same connection for multiple requests.
boolean	useKeepAlive() Indicates whether this connection will attempt to use HTTP 1.1 keepalive to possibly re-use the same connection for multiple requests.

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE

The size of the buffer that we will use for reading data.

See Also:

Constant Field Values

AUTH_HEADER_PREFIX

public static final java.lang.String AUTH_HEADER_PREFIX

The prefix that will be used for the HTTP header that sends authentication information to the remote Web server.

See Also:

Constant Field Values

PROXY_AUTH_HEADER_PREFIX

public static final java.lang.String PROXY_AUTH_HEADER_PREFIX

The prefix that will be used for the HTTP header that sends authentication information to the proxy server.

See Also:

Constant Field Values

STAT_TRACKER_REDIRECTS_FOLLOWED

public static final java.lang.String STAT_TRACKER_REDIRECTS_FOLLOWED

The display name for the stat tracker used to keep track of the number of redirects followed.

See Also:

Constant Field Values

STAT_TRACKER_REQUESTS_PROCESSED

public static final java.lang.String STAT_TRACKER_REQUESTS_PROCESSED

The display name for the stat tracker used to keep track of the total number of requests processed.

See Also:

Constant Field Values

STAT_TRACKER_RESPONSE_BODY_TIME

public static final java.lang.String STAT_TRACKER_RESPONSE_BODY_TIME

The display name for the stat tracker used to keep track of the length of time required to retrieve the body of the response.

See Also:

Constant Field Values

STAT_TRACKER_RESPONSE_CODES

public static final java.lang.String STAT_TRACKER_RESPONSE_CODES

The display name for the stat tracker used to keep track of the response codes from all the requests.

See Also:

Constant Field Values

STAT_TRACKER_RESPONSE_HEADER_TIME

public static final java.lang.String STAT_TRACKER_RESPONSE_HEADER_TIME

The display name for the stat tracker used to keep track of the length of time required to retrieve send the request and retrieve the header.

See Also:

Constant Field Values

STAT_TRACKER_RESPONSE_SIZE

public static final java.lang.String STAT_TRACKER_RESPONSE_SIZE

The display name for the stat tracker used to keep track of the size in bytes of the response.

See Also:

Constant Field Values

STAT_TRACKER_TOTAL_REQUEST_TIME

public static final java.lang.String STAT_TRACKER_TOTAL_REQUEST_TIME

The display name for the stat tracker used to keep track of the total length of time required to handle a request.

See Also:

Constant Field Values

Constructor Detail

HTTPClient

public HTTPClient()

Creates a new instance of this HTTP client. It will not use a proxy server, it will not perform authentication, and it will not automatically retrieve images when retrieving an HTML ocument.

Method Detail

enableDebugMode

public void enableDebugMode()

Indicates that this HTTP client should operate in debug mode. Debug messages will be sent to standard error.

enableDebugMode

public void enableDebugMode(java.io.PrintStream debugStream)

Indicates that this HTTP client should operate in debug mode. Debug messages will be sent to the provided print stream.

Parameters:

debugStream - The print stream to which debug messages should be sent.

disableDebugMode

public void disableDebugMode()

Indicates that this HTTP client should not operate in debug mode.

setSSLSocketFactory

public void setSSLSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory)

Specifies the socket factory that should be used to create SSL-based connections.

Parameters:

sslSocketFactory - The socket factory that should be used to create SSL-based connections.

getSSLSocketFactory

public javax.net.ssl.SSLSocketFactory getSSLSocketFactory()

Retrieves the socket factory that will be used to create SSL-based connections.

Returns:

The socket factory that will be used to create SSL-based connections.

enableProxy

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

Indicates that the client should communicate with the specified proxy server rather than attempting to communicate directly with the remote Web server. No authentication will be used when communicating with the proxy server.

Parameters:

proxyHost - The address of the proxy server.

proxyPort - The port of the proxy server.

enableProxy

public void enableProxy(java.lang.String proxyHost,
                        int proxyPort,
                        java.lang.String proxyAuthID,
                        java.lang.String proxyAuthPW)

Indicates that the client should communicate with the specified proxy server rather than attempting to communicate directly with the remote Web server. Basic authentication will be performed using the provided user ID and password.

Parameters:

proxyHost - The address of the proxy server.

proxyPort - The port of the proxy server.

proxyAuthID - The user ID to use to authenticate to the proxy server.

proxyAuthPW - The password to use to authenticate to the proxy server.

disableProxy

public void disableProxy()

Indicates that the client should not use a proxy server but rather try to communicate directly with the remote Web server.

proxyEnabled

public boolean proxyEnabled()

Indicates whether the client will attempt to forward requests through an HTTP proxy server.

Returns:

true if an HTTP proxy server will be used, or false if not.

proxyAuthenticationEnabled

public boolean proxyAuthenticationEnabled()

Indicates whether the client will attempt to authenticate to an HTTP proxy server.

Returns:

true if an HTTP proxy server will be used and authentication information will be provided to it, or false if not.

getProxyHost

public java.lang.String getProxyHost()

Retrieves the address of the proxy server that has been configured.

Returns:

The address of the proxy server that has been configured, or null if none has been specified.

getProxyPort

public int getProxyPort()

Retrieves the port number of the proxy server that has been configured.

Returns:

The port number of the proxy server that has been configured, or -1 if none has been specified.

getProxyAuthID

public java.lang.String getProxyAuthID()

Retrieves the username that will be provided to the HTTP proxy server if authentication will be performed.

Returns:

The username that will be provided to the HTTP proxy server if authentication will be performed, or null if no authentication will be performed.

getProxyAuthPassword

public java.lang.String getProxyAuthPassword()

Retrieves the password that will be provided to the HTTP proxy server if authentication will be performed.

Returns:

The password that will be provided to the HTTP proxy server if authentication will be performed, or null if no authentication will be performed.

enableAuthentication

public void enableAuthentication(java.lang.String authID,
                                 java.lang.String authPW)

Indicates that authentication should be performed for the remote Web server using the provided information.

Parameters:

authID - The user ID to use to authenticate to the remote Web server.

authPW - The password to use to authenticate to the remote Web server.

disableAuthentication

public void disableAuthentication()

Indicates that no authentication should be performed for the remote Web server.

authenticationEnabled

public boolean authenticationEnabled()

Indicates whether the client will attempt to provide authentication information to the remote HTTP server.

Returns:

true if HTTP authentication will be performed, or false if not.

getAuthID

public java.lang.String getAuthID()

Retrieves the username that will be provided to the remote HTTP server if authentication will be performed.

Returns:

The username that will be provided to the remote HTTP server if authentication will be performed, or null if no authentication will be performed.

getAuthPassword

public java.lang.String getAuthPassword()

Retrieves the password that will be provided to the remote HTTP server if authentication will be performed.

Returns:

The password that will be provided to the remote HTTP server if authentication will be performed, or null if no authentication will be performed.

followRedirects

public boolean followRedirects()

Indicates whether this client will attempt to automatically follow redirects returned by the server.

Returns:

true if this client will attempt to follow redirects, or false if not.

setFollowRedirects

public void setFollowRedirects(boolean followRedirects)

Specifies whether this client should attempt to automatically follow redirects returned by the server.

Parameters:

followRedirects - Indicates whether to try to automatically follow redirects returned by the server.

useKeepAlive

public boolean useKeepAlive()

Indicates whether this connection will attempt to use HTTP 1.1 keepalive to possibly re-use the same connection for multiple requests.

Returns:

true if the connection should attempt to use keepalive, or false if not.

setUseKeepAlive

public void setUseKeepAlive(boolean useKeepAlive)

Indicates whether to use HTTP 1.1 keepalive to possibly re-use the same connection for multiple requests.

Parameters:

useKeepAlive - Indicates whether to use HTTP 1.1 keepalive to possibly re-use the same connection for multiple requests.

retrieveAssociatedFiles

public boolean retrieveAssociatedFiles()

Indicates whether this client should automatically retrieve any additional files associated with the HTML documents that are retrieved. Note that the contents of those files will not be available to the client calling sendRequest() -- only the contents of the primary document requested.

Returns:

true if this client should automatically retrieve any additional files associated with the HTML documents that are retrieved, or falses if not.

setRetrieveAssociatedFiles

public void setRetrieveAssociatedFiles(boolean retrieveAssociatedFiles)

Specifies whether this client should automatically retrieve any additional files (images, external style sheets, frame elements, etc.) associated with any HTML documents that it retrieves.

Parameters:

retrieveAssociatedFiles - Indicates whether this client should automatically retrieve any additional files associated with the HTML documents that are retrieved.

getCommonHeaders

public java.lang.String[][] getCommonHeaders()

Retrieves a two-dimensional array containing the names and values of all headers that will always be included in requests sent using this client.

Returns:

A two-dimensional array containing the names and values of all headers that will always be included in requests sent using this client.

getCommonHeader

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

Retrieves the value of the common header with the provided name.

Parameters:

name - The name of the common header whose value should be retrieved.

Returns:

The value of the specified common header, or null if no such header has been defined.

getCommonHeaderNames

public java.lang.String[] getCommonHeaderNames()

Retrieves the names of the common headers that have been defined for this client.

Returns:

The names of the common headers that have been defined for this client.

getCommonHeaderValues

public java.lang.String[] getCommonHeaderValues()

Retreives the values of the common headers that have been defined for this client. The order of the header values will be the same as the order of the names returned by the getCommonHeaderNames() method.

Returns:

The values of the common headers that have been defined for this client.

setCommonHeader

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

Adds a common header with the specified name and value. If a header already exists with the specified name, then the given value will replace the existing value. If the given value is null, then any existing header with that name will be removed.

Parameters:

name - The name to use for the common header.

value - The value to use for the common header.

removeCommonHeader

public void removeCommonHeader(java.lang.String name)

Removes the common header with the specified name. If no such header is defined for this client, then no action will be performed.

Parameters:

name - The name of the common header to be removed.

clearCommonHeaders

public void clearCommonHeaders()

Removes all common headers that have been defined for this client.

cookiesEnabled

public boolean cookiesEnabled()

Indicates whether support for cookies is enabled in this client.

Returns:

true if support for cookies is enabled, or false if not.

setCookiesEnabled

public void setCookiesEnabled(boolean cookiesEnabled)

Specifies whether cookie support should be enabled for this client.

Parameters:

cookiesEnabled - Indicates whether cookie support should be enabled for this client.

getCookies

public HTTPCookie[] getCookies(java.net.URL requestURL)

Retrieves an array of cookies that apply to the given URL. If there are no applicable cookies, then an empty array will be returned.

Parameters:

requestURL - The URL for which to retrieve the applicable cookies.

Returns:

An array of cookies that apply to the given URL.

addCookie

public void addCookie(HTTPCookie cookie)

Adds the specified cookie to the set of cookies associated with this client. If the cookie information provided matches that of another cookie that already exists, then that cookie will be updated. If the provided cookie has an expiration date in the past, then the specified cookie will be removed.

Parameters:

cookie - The cookie to be added to this client.

clearCookies

public void clearCookies()

Clears all cookie information associated with this client.

enableStatisticsCollection

public void enableStatisticsCollection(java.lang.String clientID,
                                       java.lang.String threadID,
                                       int collectionInterval)

Indicates that the client should automatically maintain a set of stat trackers that keep track of various statistics around HTTP processing.

Parameters:

clientID - The client ID to use for the stat trackers.

threadID - The thread ID to use for the stat trackers.

collectionInterval - The statistics collection interval to use for the stat trackers.

disableStatisticsCollection

public void disableStatisticsCollection()

Indicates that the client should not automatically maintain any statistics.

getStatTrackers

public StatTracker[] getStatTrackers()

Retrieves the set of stat trackers that have been maintained by this client.

Returns:

The set of stat trackers that have been maintained by this client, or an empty array if statistics collection has not been enabled.

sendRequest

public HTTPResponse sendRequest(HTTPRequest request)
                         throws HTTPException

Sends the provided request to the specified server and returns the response. If so configured, any associated files will also be retrieved.

Parameters:

request - The request to send to the server.

Returns:

The response returned by the server.

Throws:

HTTPException - If a problem occurs while sending the request or reading the response.

isRedirect

public static boolean isRedirect(int statusCode)

Indicates whether the provided status code defines a redirect that may be followed to get the actual content.

Parameters:

statusCode - The HTTP status code for which to make the determination.

Returns:

true if the provided status code will be used for a redirect, or false if not.

closeAll

public void closeAll()

Closes all open connections that are associated with this HTTP client. The client will still be available for use.

invalidateSSLSessions

public void invalidateSSLSessions()

Invalidates all SSL sessions associated with any connections held by this HTTP client. The existing SSL-based connections will still be valid, but any new connections created will be required to complete the full SSL negotiation process.