HttpClient Host Object

1.0 Introduction

When a mashup is being created, we might need to get some content from an external URL. Although you can achieve this using WSRequest hostobject, HttpClient hostobject will make things easier and configurable. The functionality of HttpClient hostobject is somewhat similar to the Apache HttpClient. Its usage involves specifying a method and url minimumly and do an HTTP GET, POST, PUT or DELETE to that url. Further more, using extra configurable options, you can set

  • Content to be sent
  • Url parameters
  • Content type and Charset
  • HTTP headers
  • Cookies
  • Basic, NTLM and Digest authentication for Server and Proxy
  • Connection Timeout
  • Cookie Policy
  • Redirect Handling

1.1 Example

function searchGoogle(query) {
	var client = new HttpClient();
	var content = [ 
		{ name : "q", value : "query" }, 
		{ name : "btnG", value : "Google Search" }, 
		{ name : "hl", value : "en" }, 
		{ name : "source", value : "hp" } 
	];
	var params = {	
		followRedirect : true
	};

	var code = client.executeMethod("GET", "http://google.com/search", content, params);
	if(code == 200) {
		return "<success>" + client.response + "</success>";
	} else {
		return "<failure><code>" + code + "</code><statusText>" + client.statusText + "</statusText></failure>";
	}
}
            

2.0 HttpClient Object

2.1 HttpClient Interface

{
	property array authSchemePriority;
	property object credentials;
	property object proxyCredentials;
	property object host;
	property array cookies;
	readonly array responseHeaders;
	readonly property String response;
	readonly property String statusText;
	function int executeMethod( String method, String url, String content | object content, object params, object headers );
	function void releaseConnection();
}
            

2.2 API Documentation

Member Description
function int executeMethod( String method, String url [, String content | object content [, object params [, object headers]]]); This method executes the specified method on the given url using other configurations set by the mashup. It returns the status code returned by the server and accepts the following parameters:

  • method (String): This is the string representation of HTTP method to be executed. This supports "GET", "POST", "PUT" and "DELETE" for the value of this parameter.
  • url (String): This is the url string which is used to sent the request by HttpClient. It can be an absolute url or a relative url. If it is a relative url, then the host, port and protocol should specified using client.host property.
  • [optional]content (String | object): This is the content to which needs to be sent to the server. It can be just a string or name-value pair object as below.
    content = {
    	param1 : "value1",
    	param2 : "value2",
    	...... 
    }
    									
  • [optional]params (object): This is an object with parameters to be set with HttpClient. You can set following parameters there for further customization.
    params = {	
    	cookiePolicy : String, // one of "compatibility" | "netscape" | 
    						   //"rfc2109" | "rfc2965" | "ignoreCookies" | "default"
    	timeout : int, // Socket timeout in milliseconds E.g. 30000
    	doAuthentication : boolean,  // true | false,
    	followRedirect : boolean, // true | false,
    	contentChunked : boolean, // true | false,
    	primeetiveAuth : boolean, // true | false,
    	contentType : String, // E.g. "application/x-www-form-urlencoded",
    	charset : String // E.g. "iso-8859-5"
    };
    									
  • [optional]headers (array): These are the headers which need to be sent along with the request. This is an array of name-value pair objects as below.
    headers = [
    	{ name : "Accept-Language", value : "en" },
    	{ name : "	Cache-Control", value : "no-cache" },
    	...... 
    ];
    									
function void releaseConnection(); This function releases any resouces associated with the HttpClient object and should be called when you finished accessing of the Host Object.

  • client.releaseConnection();
readonly property array responseHeaders This property contains an array of headers in the response as below.

[
	{ name : "Accept-Language", value : "en" },
	{ name : "	Cache-Control", value : "no-cache" },
	...... 
]
							
readonly property String statusText This property contains the status text (or "reason phrase") associated with response
property array authSchemePriority This property should be set with an array which contains the authentication schemes to be used with the HttpClient in the order of their priority. HttpClient hostobject supports "BASIC", "NTLM" and "DIGEST" schemes only. If this property has not been set, the BASIC authentication scheme will be used by default.

client.authSchemePriority = ["NTLM", "BASIC"];
							
property array cookies This property can be used to set/get an array of cookies which needs to be set with HttpClient hostobject or currently contain in the hostobject. A cookies array is in the following format.

client.cookies = [
	{ domain : ".wso2.com", name : "myCookie", value : "ADCFE113450593", path : "/", age : 20000, secure : true},
	......
	......
];
							
property object credentials This property can be used to set the credentials which needs to authenticate the server. This credentials object should be in the following format.

client.credentials = {
	scope : { host : "www.wso2.com", port : 80, realm : "web", scheme : "basic"},
	credentials : { username : "ruchira", password : "ruchira"}
};
							
property object proxyCredentials This property can be used to set the credentials which needs to authenticate the proxy server if there any. This proxyCredentials object should be in the following format.

client.proxyCredentials = {
	scope : { host : "www.wso2.com", port : 80, realm : "web", scheme : "basic"},
	credentials : { username : "ruchira", password : "ruchira"}
};
							
property object host This property can be used to set host configuration for the HttpClient hostobject which will be then used when you are executing a method using a relative url. This host propery should be in the following format.

client.host = { host : "www.wso2.com", port : 80, protocol : "https"};