The HttpClient class provides a thin wrapper around the browser XmlHttp object to allow making HTTP calls against a server and receive the results back. This class is a low level helper that is used by a number of other XHR related features of this library.

This class works by using the .send() message to send an HTTP request with optional parameters and then firing error or success callback handlers or a promise as a result of the send operation. The class manages error trapping of the HTTP requests and captures the result of HTTP contents attempting to parse the result data for error messages. Captures HTTP errors as well as application errors as long as invalid results return a JSON structure with a .message property.

The properties of this class effectively set behavior of the HTTP request. You can send the URL, timeout, HTTP verb, content-type and so on.

Usage

This class is not typically used directly by application code. Instead you'll use ajaxJson(), ajaxCallMethod() or $.postJson() which use this class under the covers.

If you want to use this class directly you can use the following logic. The first example demonstrates using Callbacks:

function HttpSample()
{
	var Http = new HttpClient();     
	
	// set behavior properties
	Http.appendHeader("custom-header","custom value")
	
	// send the request with callbacks
	Http.send("http://localhost/",null,
               function(result) { 
                alert("It worked: " + result);  // shows HTML result
               },
               function(error)
               {
                alert("Error: " + error.message);
               });
                      
}

Alternately Http.send() function also returns a Promise object which you can use in lieu of the callback parameters:

function HttpSampleWithPromise()
{
	var Http = new HttpClient();     
	var promise = Http.send("http://localhost/",null);

    promise
        .success(function(result) { 
	                 alert("It worked: " + result);  // shows HTML result
	             })
        .error(function(error) {
                  alert("Error: " + error.message);
               });	                       
                  
}

Promises make it easy to pass the error handling logic up the application stack, allowing you to handle the success and error closer to the code that needs to process the result. Promises also allow you to attach multiple handlers to the same HTTP operation which can be useful for components that track errors but pass final processing to the application.

Http calls are asynchronous so results are fired into the result functions out of band. To make multiple simultaneous callbacks create multiple instances of this class.