DP_RequestPool

This component requires a JavaScript (ECMAScript) 1.3 (or better) development environment. All downloads and code are covered by our Source Code Policy.

DP_RequestPool.zip, 4.49kb Zip-Format Archive

The library consists of a single JavaScript file with a .JS extension.

Importing the Library

The library must be imported before it is used. To import the library use the <script> tag. For example:
<script type=”text/javascript” src=”DP_RequestPool.js”></script>.

Your path may vary depending on the location of the script on your server.

Creating and Accessing the Object

Once the library has been imported you may create DP_RequestPool objects as you would any other JavaScript object. For example:

var MyPool = new DP_RequestPool(...);

See the Constructor section for more information.

Once you have created an instance of the object you can use the methods and properties provided. See the Examples section for some sample code.

Some Terminology

There are some conceptual terms that will make understanding and using this object easier.

• Request: A representation of a request (request method, URL, parameters, etc).
• Requester: Requesters are the individual HTTP object that actually do most of the work. The specific objects used depend upon the environment. In FireFox, IE 7 and others these will be instances of the native XMLHttpRequest object while in older versions of IE these will be instances of the Microsoft.XMLHTTP ActiveX object.
• Pool: This refers to the collection of request objects (as in a “pool of resources”). The pool both contains the objects and controls access to them.
• Request: Requests are the actual HTTP calls being defined (call a specific URL and pass the results to a specific function).
• Queue: Requests are added to the queue (a first-in, first-out stack) to wait for available requester objects. The queue is periodically examined and the oldest request is passed to the first available requester.

General Recommendations

The point of the DP_RequestPool object is to simplify the reuse and control the proliferation of HTTP request objects with an application. Considering this some general guidelines can be inferred:

• The object should be instantiated and persisted within an application. The point of the object is reuse: it shouldn’t be destroyed and recreated often.
• The number of pooled request objects to create will vary according to the application needs. However in general a lower number (3-6) will suit most applications well. Many operating systems limit the total number of simultaneous requests allowed so this should also be taken into consideration. More requests means more resources dedicated to managing them. In short adding more objects may not speed your application but could in fact slow it. Experiment with the number in your application to find the best balance.
• Although seemingly counter-intuitive using only one request object is sometimes beneficial. It will ensure that all of your requests are made in serial (that only one request is active at any time and requests are made in the order in which they were added to the queue). This can be very useful for applications where the target server is slow, overloaded or would otherwise benefit from such throttling. Note that requests may still return in any order (a long request made early will return after quick requests made later).

Integration with DP_Debug

DP_RequestPool features optional integration with DP_DeBug. If the DP_Debug library is loaded and enabled (using the DP_Debug.enabled() method, see the documentation for more information) debugging information will be displayed in the debugging console.

DP_RequestPool()

DP_Request()

DP_Request

There are several properties available in an DP_Request. All of these properties correlate to the DP_Request constructor method arguments. See the constructor documentation for more information.

DP_Request properties available:

• Method: The HTTP method to use for the request.
• URL: The URL to call.
• Parameters: An object whose properties represent parameters to be passed with the request.
• Handler: A reference to the function which should be called upon completion of the request.
• HandlerArgs: The contents of the array will be passed as additional arguments to the handler function.
• Timeout: Defaults to the value set in the DP_RequestPool.
• MaxAttempts: Defaults to the value set in the DP_RequestPool.

DP_Request methods available:

• None.

DP_RequestPool

There are several properties available in an DP_RequestPool. However it is recommended that all access to these properties only via their related method calls.

DP_RequestPool properties available:

• DefaultTimeout: The request default timeout (as set in the constructor).
• DefaultMaxAttempts: The default number of request retry attempts (as set in the contructor).
• Name: The name of the pool (as set in the contructor).
• Requesters: An array of all instantiated requester objects.
• RequestQueue: An array containing all pending requests.

DP_RequestPool methods available:

• addRequest()
• clearQueue()
• doRequest()
• isBusy()
• isQueueEmpty()
• manageTimeouts()
• queueCount()
• startInterval()
• stopInterval()

Note that in method/function signatures a pipe (“|”) indicates “OR” while arguments in square brackets are optional.

addRequest()

clearQueue()

doRequest()

isBusy()

isQueueEmpty()

manageTimeouts()

queueCount()

startInterval()

stopInterval()

Instantiating the Pool

You instantiate a pool for use as you would any other JavaScript Object. The following line will instantiate a Request Pool with four request objects:

myRequestPool = new DP_RequestPool(4);

At this point the pool is created and ready to accept new requests. Importantly however it is not yet checking its queue for new requests. To automatically check for queue entries at an interval use the startInterval() method. The following line will instruct the pool to check its queue every 100 milliseconds:

myRequestPool.startInterval(100);
	

You can stop the interval later (to “pause” requests for example) using the stopInterval() method.

Creating Requests

Requests are created using the DP_Request() constructor and represent all information needed to make the request and react to the the response. The arguments which define the call itself are method (“GET” or “POST”), URL (the URL to call) and an object representing any parameters to pass to the URL. The arguments which define how the results are handled upon completion are the function to call (the “handler”) and an array of values to pass to the handler as arguments.

An an example Let’s assume that:

• The URL http://www.mysite.com/Add.htm accepts two numeric parameters (“FirstNum” and “SecondNum”) adds them up and returns the results.
• The client-side function AddUp() accepts three numeric arguments and adds them up.

We want our request to first call the URL with the values “5” and “10” then pass the results along with the values “7” and “13” to the AddUp() function. The following code creates this request:

	// Set the URL to call
myURL = "http://www.mysite.com/Add.htm";
	// Create the Parameters to pass to the URL (an object where each property will be passed as a parameter)
myParams = new Object();
myParams.FirstNum = 5;
myParams.SecondNum = 10;
	// Create an array to hold the "extra" arguments needed by the handler
	// (Note that the first argument passed to the handler is always the results of the request.)
myArgs = new Array();
myArgs[0] = 7;
myArgs[1] = 13;
	// Create the Request
myRequest = new DP_Request("GET", myURL, myParams, AddUp, myArgs);
	

While this code does work it’s quite verbose. The same request could be created with less code using literal notations as follows:

	// Create the Request
myRequest = new DP_Request(
	"GET",
	"http://www.mysite.com/Add.htm",
	{"FirstNum" : 5, "SecondNum" : 10},
	AddUp,
	[7,13]);
	

The handler function, AddUp(), might look like this:

	// The handler function
function AddUp(Num1, Num2, Num3) {
	alert(Num1 + Num2 + Num3);
};
	

Adding Requests to the Pool

Once created Requests are added to the Request Pool’s queue using the addRequest() method of the pool object. Here’s an example which assumes that the myRequestPool and myRequest from the prior examples have already been created:

	// Add the request to the queue
myRequestPool.addRequest(myRequest);
	

Of course the request object could also be built inline (anonymously) like so:

	// Add the request to the queue
myRequestPool.addRequest( new DP_Request( ...request arguments... ) );
	

The Full Example

For clarification here is the the full example:

	// The handler function
function AddUp(Num1, Num2, Num3) {
	alert(Num1 + Num2 + Num3);
};

	// Instantiate the Pool
myRequestPool = new DP_RequestPool(4);

	// Start the Interval
myRequestPool.startInterval(100);

	// Create the Request
myRequest = new DP_Request(
	"GET",
	"http://www.mysite.com/Add.htm",
	{"FirstNum" : 5, "SecondNum" : 10},
	AddUp,
	[7,13]);

	// Add the request to the queue
myRequestPool.addRequest(myRequest);
	

Breaking down the example we see that:

• We’re calling http://www.mysite.com/Add.htm using the GET method.
• We’ve generated an object (myParams in the first example) which contains property=value pairs. These will be converted to corrosponding name=value parameters and passed to the URL. (if the POST method were used they would be passed as form-field values.)
• The function AddUp() is our handler. A reference to it (without the parenthesis as we’re passing the function itself, not the result of the function) is used as an argument DP_Request(). When the request is completed this function will be called. The first argument of this call will be the text results of the HTTP call in the form of: AddUp(HTTPResponseContent).
• Arguments intended for the handler are added to an array (myArgs in the first example) and will be passed (unaltered and in the array-specified order) as additional arguments to the handler. In this case the values “7” and “13” will be passed as second and third arguments to the handler in the form of: AddUp(HTTPResponseContent, 7, 13).
• The handler function adds up the three numbers and raises an alert with the total (in this case, if our math if correct, 35).

In this simple example the AddUp() function simply creates an alert with the total of the arguments. In reality the handler would most likely perform some action to either store or display the results within the current web page.

Remember that the call to addRequest() does not actually run the request. Instead it simply adds the request to the queue. Only after the request is run and completed will the handler be called. Don’t be confused and assume that the result of addRequest() will be the response from the HTTP request or the result returned from the handler. Code after addRequest() will run immediately; it will not wait for the response to complete.

November 14, 2006

This is a major update and may require changes to support applications which use older versions.

• Eliminated the getRequest() method in favor of a more OO-style DP_Request constructor. Requests can now be generated directly and passed to the addRequest() method. Requests can also be stored (in case they need to be reissued for example).
• Improved and extended the IE ActiveX object detection.
• Added the ability to timeout requests after a user-configurable duration has passed. Added arguments to the DP_Request and DP_RequestPool constructors to support this.

October 25, 2006

• Added support for DP_DeBug. When the DP_Debug library is loaded and enabled (using the DP_Debug.enabled() method) debugging information will be displayed in the console.
• Added the “PoolName” parameter to the object constructor. This optional parameter can be used to identify debugging output when multiple request pools are in use.
• Requests can now be retried automatically when they fail (when the HTTP response is not 200 or zero). Added the “MaxRequestAttempts” parameter to the object constructor to support this change (the default number of reattempts is 3).
• Added the getRequest() method which returns a request object but does not add it to the queue. Using this an application can store requests until the results can be examined, if the initial request fails the stored request can be reissued easily.
• addRequest() can now accept a request object (as from getRequest()) in addition to individual parameters.
• Added the isBusy() method which returns a boolean. If true at least one of the request object is in a “busy” state (readystatechange of 1, 2 or 3). This method can assist with the construction of “Network Activity” indicators.
• Improved request object detection for IE (including IE 7) and streamlined request queue object discovery and onReadyStateChange handler functionality.

September 07, 2006

• Fixed a bug in which requests would sometimes be abandoned under load.
• Made the “Handler” argument of the addRequest() method optional (useful for requests which don’t require confirmation).

June 22, 2006

• Initial Release.