DP_RequestPool

This component has been deprecated and is no longer being supported.
Please consider using the more capable DP_AJAX instead.

The DP_RequestPool library provides a simple way to manage multiple HTTP requests in AJAX-style applications.

  • The library has a very small footprint (only two global objects are created).
  • Multiple pools can be instantiated in the same application if required (for example a “fast” pool might be created for user interface interaction while a “slow” pool might be created for automated logging).
  • Highly configurable. The number of request objects in the pool, the interval at which the request queue is checked, the number of retry attempts and the timeout for requests are user-configurable on a per-instance basis.

The extension has been tested successfully on Internet Explorer 6+, Firefox 1+ and Opera 9+.

Download

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

Usage

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.

Constructor

DP_RequestPool()

Used to create DP_RequestPool instances.

Method Signature

new DP_RequestPool([RequesterCount], [DefaultTimeout], [DefaultMaxAttempts], [Name])

Arguments

  • RequesterCount: Number, Optional. Defaults to “4”. The number of requester objects to be instantiated. In effect the total number of simutaneous requests that can be made using the component.
  • DefaultTimeout: Number, Optional. Defaults to 0 (no timeout). The duration, in seconds, that represents the maximum time to attempt a request. Timeouts can be checked manually with the manageTimeouts() method. This can be automated using the startInterval() method.
  • DefaultMaxAttempts: Number, Optional. Defaults to “1” (do not retry). The number of times that a request should be reattempted in case of a failure response. (In this case “failure” is considered an HTTP result code of something other than 200 or 0).
  • Name: String, Optional. Defaults to “DP_RequestPool”. A short identifier for the pool, used for debugging purposes only.

Return

A reference to the new DP_RequestPool.

DP_Request()

Used to create DP_Request instances.

Method Signature

new DP_Request(Method, URL, [Parameters], [Handler], [HandlerArgs], [Timeout], [MaxAttempts])

Arguments

  • Method: String, required. Valid values are “GET” or “POST”. Sets the HTTP method to use for the request.
  • URL: String, required. The URL to call.
  • Parameters: Object, optional. An object whose properties represent parameters to be passed with the request. Each property of the object will be passed as a name=value pair in the HTTP request.
  • Handler: Function reference, optional. A reference to the function which should be called upon completion of the request. When calling the handler the text results of the HTTP call will be passed as the first argument to the function.
  • HandlerArgs: Array, optional. The contents of the array will be passed as additional arguments to the handler function.
  • Timeout: Number, Optional. Defaults to the value set in the DP_RequestPool. The duration, in seconds, that represents the maximum time to attempt the request. Timeouts can be checked manually with the manageTimeouts() method. This can be automated using the startInterval() method.
  • MaxAttempts: Number, Optional. Defaults to the value set in the DP_RequestPool. The number of times that a request should be reattempted in case of a failure response. (In this case “failure” is considered an HTTP result code of something other than 200 or 0).

Return

A reference to the new Request.

Properties and Methods

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:

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

addRequest()

Adds a new request to the queue.

Method Signature

addRequest(Request)

Arguments

This method has one argument:

  • Request: A Request Object (created with the DP_Request constructor), required.

Return

Boolean. Always returns “true”.

clearQueue()

Clears the request queue and, optionally, cancels any currently running requests.

Method Signature

clearQueue(AbortRunningRequests)

Arguments

This method has one argument:

  • AbortRunningRequests: Boolean, optional. Defaults to “false”. If True an attempt will be made to abort all currently running requests. If False only queued (not yet running) requests will be eliminated.

Return

True.

doRequest()

Launches the next request in the queue.

Method Signature

doRequest()

Arguments

This method has no arguments.

Return

True if a request was made, false if no request was made (if the queue is empty).

isBusy()

Returns true if any objects in the pool are currently “busy” (loading data), false if not. Can be used to inform “Network Activity” interface indicators.

Method Signature

isBusy()

Arguments

This method has no arguments.

Return

True if any object in the pool is busy (specifically if the onreadystate for any object is 1, 2 or 3), false if not (if the onreadystate for all objects is 0 or 4).

isQueueEmpty()

Determines if there are any requests waiting to be serviced.

Method Signature

isQueueEmpty()

Arguments

This method has no arguments.

Return

Boolean. True if there are requests currently waiting in the queue, false if the queue is empty.

manageTimeouts()

Checks the timeout status of all running requests.

Method Signature

manageTimeouts()

Arguments

This method has no arguments.

Return

Boolean. Always returns “true”.

queueCount()

Returns the number of requests currently queued.

Method Signature

queueCount()

Arguments

This method has no arguments.

Return

Numeric. The number of requests in the queue.

startInterval()

A convienence method which automatically calls the doRequest() and manageTimeouts() methods each time the specified number of milliseconds has elapsed.

Method Signature

startInterval(Interval)

Arguments

This method has one argument:

  • Interval: Number, Optional. Defaults to “500”. The time interval, in milliseconds, between calls to doRequest().

Return

None.

stopInterval()

Cancels the current interval. doRequest() will not be called automatically any longer.

Method Signature

stopInterval()

Arguments

This method has no arguments.

Return

None.

Examples

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.

Revision History

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.