An array, containing all pending requests that have been queued up and are waiting to be performed.

NOTES

see also the flush, queueRequest, and useQueue instance methods

The Perform Request instance event fires each time before a request is performed - for both single requests as well as batch requests. The event object contains a "request" property, which is a reference to the request object for the request about to be performed.

The Request Queue Updated event is fired each time the requestQueue instance property is updated.

A method that lets you flush the request queue.

SYNTAX

myInstance.flush ();

NOTES

	this method takes no parameters
	after flushing the request queue, the Request Queue Updated instance event will be fired
	see also the queueRequest and useQueue instance methods
	see also the requestQueue instance property

Lets you flush the cached response for a specific request, or lets you flush the entire response cache for the instance.

SYNTAX

myInstance.flushCache (requestOBJ);

VARIATION 1

myInstance.flushCache (requestUrlSTR);

As an alternative to specifying a request by request object, a request can be specified by its URL (ie. the value of the url property of the request object).

VARIATION 2

myInstance.flushCache ();

When no parameter is specified, then the flushCache method will flush the entire response cache for the instance.

NOTES

don't confuse this method with the flush instance method that flushes the request queue

A method that should be overrided in subclasses that implement support for specific communication protocols.

SYNTAX

myInstance.performRequest (requestOBJ,callbackFUNC)

This method is not intended to be called by application code. It is only public so that it can be overrided in subclasses. When implementing this method in a subclass, your method should expect to receive the two parameters requestOBJ and callbackFUNC. The requestOBJ parameter will contain all the information necessary for performing the request.

Once the request has been sucessfully completed, your implementation should place request results into requestOBJ and then call the callback function specified in the callbackFUNC parameter. It is not necessary to pass any parameters when calling the callbackFUNC function, since the request results are placed into requestOBJ.

A method that lets you initiate a request.

SYNTAX

myInstance.request (requestOBJ);

All the information that governs the request is contained inside the requestOBJ parameter. The properties of this object will vary, depending on the communication protocol and are determined by the particular subclass Uize.Comm you are using.

SYNTAX (EXPLODED)

myInstance.request ({
  // ...properties specific to comm protocol...
  // ...properties specific to comm protocol...
  // ...properties specific to comm protocol...
  returnType:returnTypeSTR,
  cache:cacheBOOLorSTR,
  callback:callbackFUNC
});

4.4.1. requestOBJ Properties

A method that facilitates asynchronous iteration through and processing of the elements of an array.

SYNTAX

Uize.Comm.processArrayAsync (elementsARRAY,processElementAsyncFUNC,completionFUNC);

While asynchronous, the array specified by the elementsARRAY parameter is guaranteed to be iterated through sequentially. This method is useful for iterating through the elements of an array and using an asynchronous communication protocol, such as Ajax, in the processing of the elements.

The function you specify in the processElementAsyncFUNC parameter should be of the form...

myAsyncElementProcessor (elementToProcessANYTYPE,processNextElementFUNC,elementNoINT);

The value of the elementToProcessANYTYPE parameter will be the value of each successive element in the array that is being iterated through. In order to inform the Uize.Comm.processArrayAsync method that the asynchronous processing of the current element has been completed so that it can continue on with the iteration, the function specified by the processNextElementFUNC parameter should be called. This function does not need to be called with any parameters. However, if you call it with the value false, then the iteration will be terminated and any function that you specified for the completionFUNC parameter will be called.

Your processor function can optionally declare an elementNoINT parameter, to receive the array index of the current element being processed. This might be useful if you need to index into other corresponding support data structures, or use the number as part of the construction of some string or such. Naturally, your own element processor function can name these three parameters whatever it likes.

If you specified a value for the optional completionFUNC parameter, then your completion function will be called once the iteration is completed, with one parameter, being the length of the array that was processed.

TYPICAL USAGE SKELETON

Uize.Comm.processArrayAsync (
  _elementsToIterateThrough,
  function (_currentElement,_continueIterating) {
    _doSomethingAsynchronous (
      function () { // the callback for _doSomethingAsynchronous
        // further processing of element
        _continueIterating ();
      }
    );
  },
  function () {
    // done iterating, wrap it all up
  }
);

EXAMPLE

var imagesInfoHtml = '';
Uize.Comm.processArrayAsync (
  myPhotoStream.getImageIds (),
  function (_imageId,_addInfoHtmlForNextImage) {
    myAjaxCommObject.request ({
      url:'/svc/getimageinfo?id=' + _imageId,
      returnType:'json',
      requestMethod:'GET',
      callback:function (resonseJson) {
        imagesInfoHtml +=
          'title: ' + resonseJson.title + '<br/>' +
          'description: ' + resonseJson.description + '<br/>' +
          'dimensions: ' + resonseJson.width + 'x' + resonseJson.height + '<br/>' +
          '<hr/>'
        ;
        _addInfoHtmlForNextImage ();
      }
    });
  },
  function () {
    Uize.Node.setInnerHtml ('imagesInfo',imagesInfoHtml);
  }
);

In this fictitious example, Uize.Comm.processArrayAsync is being used to iterate through an array of image IDs for a photo stream.

On each iteration, the processor function performs an asynchronous request, using an instance of Uize.Comm.Ajax, to the service "/svc/getimageinfo" in order to get info for each image. When the Ajax request returns with the image info, the callback registered for the request uses the image info to build image info HTML for the entire photo stream. After adding to the HTML string, the continuation function is called in order to continue the iteration. Once all the image IDs have been processed, the completion function is called, which spits out the constructed info HTML into the page.

One thing that this example demonstrates is that the parameters that your element processor function receives can be named to be semantically suitable to your application.

VARIATION 1

Uize.Comm.processArrayAsync (
  elementsARRAY,processElementAsyncFUNC,completionFUNC,directionINT
);

The optional directionINT parameter lets you specify the increment (and, therefore, direction) of the asynchronous loop. By default, this method loops forward through the array - from the first element to the last element. Specifying a value of -1 for the directionINT parameter will cause the iteration to start from the last element of the array and loop towards the first element - one element at a time. Specifying a value of -2 will also result in a reverse loop, but will iterate backwards two elements at a time.

VARIATION 2

Uize.Comm.processArrayAsync (elementsARRAY,processElementAsyncFUNC);

When the optional completionFUNC parameter is not specified, then the caller of this method will not be notified when the process has been completed.