com.aquafold.openapi.net
Interface AQWebClient

public interface AQWebClient

The AQWebClient interface provides an environment that allows application to send an HTTP request to an HTTP server and process the response accordingly. The request can be either sent to the server directly or routed to the server via a proxy server.

The AQWebClient interface supports automatic management of cookies, including allowing the server to set cookies and automatically return them to the server when required. There are several conflicting standards for handling Cookies: the Netscape Cookie draft, RFC2109, RFC2965 and a large number of vendor specific implementations that are compliant with neither specification. To deal with this, AQWebClient provides policy driven cookie management. The following cookie specifications are supported:

• Browser Compatibility: The compatibility specification is designed to be compatible with as many different servers as possible even if they are not completely standards compliant. This is the default cookie policy used by AQWebClient.
• RFC2109: RFC 2109 is the first official cookie specification released by the W3C. Theoretically, all servers that handle version 1 cookies should use this specification
• RFC2965: RFC 2965 defines cookie version 2 and attempts to address the shortcomings of the RFC2109 regarding cookie version 1. RFC2965 is intended to eventually supersede RFC2109.
• Netscape Draft: The Netscape draft is the original cookie specification which formed the basis for RFC2109.
• Ignore Cookies: This cookie specification ignores all cookies. It should be used to prevent AQWebClient from accepting and sending cookies.

The most common problems encountered with parsing cookies is due to non-compliant servers. In these cases, switching to the compatibility cookie specification usually solves the problem. Application can use the following methods to switch among cookie policies listed above respectively:

• setBrowserCookiePolicy()
• setRFC2109CookiePolicy()
• setRFC2965CookiePolicy()
• setNetscapeCookiePolicy()
• setIgnoreCookiePolicy()

An object implementing this interface is available via aqua.net.newWebClient() alias.

To send a request to an HTTP server, application needs to create an AQWebRequest object first, as shown below:

     var client = aqua.net.newWebClient();
     var url = "http://www.aquafold.com/download/";
     var request = client.newWebRequest(url);
 

Once request object is created and properly configured, it can be submitted to the web server via one the following methods:

submitGetRequest(AQWebRequest request)
submitPostRequest(AQWebRequest request)

Please see AQWebRequest for more information about configuration of a request object.

An response object, AQWebResponse, is returned to the application if request is successfully processed. Application then can use supported APIs to retrieve information from the returned response object. Please see AQWebResponse for more information.

Method Summary

void	clearCookies() Clears all cookies.
void	closeConnection() Closes all of server connections tracked by this client and releases all of allocated system resources.
int	getConnectionTimeout() Returns the timeout, in milliseconds, used to establish a connection between this object and an HTTP server.
int	getMethodRetryCount() Returns the number of times a request will be retried due to network error.
int	getSocketTimeout() Returns the socket timeout in milliseconds which is the timeout for waiting for data.
AQWebRequest	newWebRequest(String url) Creates a new web request.
void	setBrowserCookiePolicy() Uses Browser Compatibility policy for cookie management.
void	setConnectionTimeout(int timeout) Sets the timeout, in milliseconds, used to establish a connection between this object and an HTTP server.
void	setIgnoreCookiePolicy() Indicates to neither accept nor send cookies.
void	setMethodRetryCount(int count) Sets the number of times a request will be retried due to network error.
void	setNetscapeCookiePolicy() Uses Netscape Draft policy for cookie management.
void	setProxySettings(String host, int port, String realm, Object username, Object password, String userAgent) Sets the proxy server via which requests and responses to be sent and received.
void	setRFC2109CookiePolicy() Uses RFC2109 policy for cookie management.
void	setRFC2965CookiePolicy() Uses RFC2965 policy for cookie management.
void	setSocketTimeout(int timeout) Sets the socket timeout in milliseconds which is the timeout for waiting for data.
AQWebResponse	submitGetRequest(AQWebRequest request) Sends an HTTP Get request to a server per the URL defined in the specified request.
AQWebResponse	submitPostRequest(AQWebRequest request) Sends an HTTP Post request to a server per the URL defined in the specified request.

Method Detail

newWebRequest

AQWebRequest newWebRequest(String url)
                           throws Exception

Creates a new web request.

Parameters:

url - the string to parse as a URL

Returns:

a newly created web request

Throws:

Exception - if the string is a malformed URL

submitGetRequest

AQWebResponse submitGetRequest(AQWebRequest request)
                               throws Exception

Sends an HTTP Get request to a server per the URL defined in the specified request.

Parameters:

request - a web request with a valid URL defined

Returns:

a response returned from the HTTP server

Throws:

Exception - if request contains invalid data or failed to communicate with HTTP server due to network error

submitPostRequest

AQWebResponse submitPostRequest(AQWebRequest request)
                                throws Exception

Sends an HTTP Post request to a server per the URL defined in the specified request.

Parameters:

request - a web request with a valid URL defined

Returns:

a response returned from the HTTP server

Throws:

Exception - if request contains invalid data or failed to communicate with HTTP server due to network error

setProxySettings

void setProxySettings(String host,
                      int port,
                      String realm,
                      Object username,
                      Object password,
                      String userAgent)

Sets the proxy server via which requests and responses to be sent and received.

Parameters:

host - the name of the host where the proxy server is running.

port - the port number from which the proxy server accepts requests.

realm - the realm to which the proxy server to apply the authentication; may be set to null if authentication is applicable to any realm.

username - the name of the account used for authentication purpose; may be set to null if authentication is not required.

password - the password of the account used for authentication purpose; may be set to null if authentication is not required.

userAgent - the string to be stored in the User-Agent header; may be set to null.

clearCookies

void clearCookies()

Clears all cookies.

closeConnection

void closeConnection()

Closes all of server connections tracked by this client and releases all of allocated system resources.

getConnectionTimeout

int getConnectionTimeout()

Returns the timeout, in milliseconds, used to establish a connection between this object and an HTTP server. A value of zero means the timeout is not used. The default value is zero.

Returns:

the timeout, in milliseconds, used to establish a connection between this object and an HTTP server.

setConnectionTimeout

void setConnectionTimeout(int timeout)

Sets the timeout, in milliseconds, used to establish a connection between this object and an HTTP server. A value of zero means the timeout is not used. The default value is zero.

Parameters:

timeout - timeout in milliseconds

getSocketTimeout

int getSocketTimeout()

Returns the socket timeout in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout. The default value is zero.

Returns:

the socket timeout in milliseconds which is the timeout for waiting for data.

setSocketTimeout

void setSocketTimeout(int timeout)

Sets the socket timeout in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout. The default value is zero.

Parameters:

timeout - timeout in milliseconds

setBrowserCookiePolicy

void setBrowserCookiePolicy()

Uses Browser Compatibility policy for cookie management.

setRFC2109CookiePolicy

void setRFC2109CookiePolicy()

Uses RFC2109 policy for cookie management.

setRFC2965CookiePolicy

void setRFC2965CookiePolicy()

Uses RFC2965 policy for cookie management.

setNetscapeCookiePolicy

void setNetscapeCookiePolicy()

Uses Netscape Draft policy for cookie management.

setIgnoreCookiePolicy

void setIgnoreCookiePolicy()

Indicates to neither accept nor send cookies.

getMethodRetryCount

int getMethodRetryCount()

Returns the number of times a request will be retried due to network error.

Returns:

the number of times a request will be retried

setMethodRetryCount

void setMethodRetryCount(int count)

Sets the number of times a request will be retried due to network error.

Parameters:

count - the number of times a request will be retried