Table Of Contents

Previous topic

21.38. The Renderable Interface

Next topic

21.40. The ResourceLoader Object

This Page

21.39. The RequestHandler Object

The RequestHandler object handles HTTP requests and captures events such as a lost connection as well as repeating failed requests. This makes requests easier to make as you no longer have to support the connection loss or service busy response codes.

The RequestHandler catches the following HTTP response codes:

  • 0 - The connection has been lost, the request timed out or a cross domain request has been made.
  • 408 Request time-out - The client did not produce a request within the time that the server was prepared to wait.
  • 429 Too Many Requests - The service is overloaded or unable to respond correctly.
  • 480 Temporarily unavailable - The service is overloaded or unable to respond correctly.

It also catches any XMLHttpRequest responses with a Retry-After header. When a request fails like this the RequestHandler does the following:

  • Queues up any other failed requests.
  • Repeats the failed request with an exponential timeout (or the specified Retry-After value).
  • If the failed request now succeeds then the queued up requests are repeated and all the onload callbacks are called.
  • If the failed request continues to fail after a set period the RequestHandler calls its onRequestTimeout callback. The failed request is still being repeated with an exponential timeout.
  • If sometime after this the failed request succeeds then the RequestHandler calls its onReconnected callback. Then the queued up requests are made and all the onload callbacks are called.

The RequestHandler provides means for event handlers to be added for different event types. Event handlers are added and removed using addEventListener and removeEventListener. Multiple event listeners may be added for each event type.

Required scripts

The RequestHandler object requires:

/*{{ javascript("jslib/observer.js") }}*/
/*{{ javascript("jslib/requesthandler.js") }}*/

21.39.1. Examples

TurbulenzEngine.request

// TurbulenzEngine.request(src, onload) becomes:

requestHandler.request({
    src: src,
    onload: onload
});

GraphicsDevice.createTexture

// graphicsDevice.createTexture({
//     src     : src,
//     mipmaps : true,
//     onload  : onload
// });
// becomes:

var textureRequest = function textureRequestFn(src, onload, callContext)
{
    var texture = graphicsDevice.createTexture({
        src     : src,
        mipmaps : callContext.userData.mipmaps,
        onload  : onload
    });
    if (!texture)
    {
        errorCallback("Texture '" + callContext.src + "' not created.");
    }
};

requestHandler.request({
    src: src,
    userData:
    {
        mipmaps : mipmaps
    },
    requestFn: textureRequest,
    onload: onload
});

Alternatively, you can use the TextureManager. The SoundManager and FontManager also use a RequestHandler object to make requests.

21.39.2. Constructor

21.39.2.1. create

Summary

Creates a RequestHandler object.

Syntax

var requestHandler = RequestHandler.create({
    initialRetryTime: 500,
    notifyTime: 4000,
    maxRetryTime: 8000,
    onReconnected: function onReconnectedFn(reason, requestCallContext)
    {
        console.log('Reconnected');
    },
    onRequestTimeout: function onRequestTimeoutFn(reason, requestCallContext)
    {
        console.log('Connection lost');
    }
});

See the properties section for information on these parameters.

21.39.3. Methods

21.39.3.1. request

Summary

Makes a HTTP request. For more information on this function see the RequestHandler introduction section.

Syntax

var callContext = {
    src: 'textures/duck.png',
    requestOwner: ownerObject,
    requestFn: function requestFn(src, onResponse, callContext) {},
    onload: function onloadFn(response, status, callContext) {},
    userData: {}
};

requestHandler.request(callContext);

// for example:

var loadedTextures = {};
var techniqueParameters;

var callContext = {
    src: 'textures/duck.png',
    requestFn: function requestFn(src, onResponse, callContext) {
        var userData = callContext.userData;
        if (!graphicsDevice.createTexture({
            src: src,
            onload: onResponse,
            mipmaps: userData.mipmaps
        }))
        {
            errorCallback('Unable to create texture for URL: ' + src);
        }
    },
    onload: function onloadFn(texture, status, callContext) {
        if (status === 200 && texture)
        {
            loadedTextures[callContext.src] = texture;
        }
    },
    userData: {
        mipmaps: true
    }
};

requestHandler.request(callContext);
src
A JavaScript string. The request URL.
requestOwner (Optional)
A JavaScript function or object with a request function property. If requestFn is undefined then requestOwner.request is used as the request function.
requestFn (Optional)
A JavaScript function. This function makes the request. The RequestHandler calls this function to repeat requests. It must call onResponse with the response and the status code of the request. If requestFn and requestOwner are undefined then TurbulenzEngine.request is used.
onload
A JavaScript function. Called once the request has been successfully made.
userData
The developer can put anything they want on to this property. The requestFn and onload callbacks are called with the callContext parameter.

21.39.3.2. addEventListener

Summary

Adds an event listener for the specified event. Multiple event listeners may be added for each event type. Adding the same event listener twice has no effect - the event listener will still only be called once per event.

Syntax

var eventType = 'eventOnLoad';
var eventListener = function eventOnLoad(event)
{
    ...
    ...
}

requestHandler.addEventListener(eventType, eventListener);
eventType
A valid event type string.
eventListener
Callback associated with events of eventType.

21.39.3.3. removeEventListener

Summary

Removes an event listener for the specified event. If the event listener supplied was never added using addEventListener, this has no effect.

Syntax

requestHandler.removeEventListener(eventType, eventListener);
eventType
A valid event type string.
eventListener
Callback associated with events of eventType.

21.39.3.4. destroy

Summary

Destroys the object. Callbacks for any outstanding requests are not called. This will usually be called from the application’s destroy function callback, set using TurbulenzEngine.onunload, to prevent the callbacks accessing invalid state.

Syntax

requestHandler.destroy();

21.39.4. Properties

21.39.4.1. initialRetryTime

Summary

A JavaScript number. Initial time in milliseconds to wait before retrying a request. Defaults to 500.

Syntax

var initialRetryTime = requestHandler.initialRetryTime;

21.39.4.2. notifyTime

Summary

A JavaScript number. Time in milliseconds to wait before calling onRequestTimeout with the callContext of the asset that failed. Defaults to 4000.

Syntax

var notifyTime = requestHandler.notifyTime;

21.39.4.3. maxRetryTime

Summary

A JavaScript number. Maximum time in milliseconds to wait before retrying a request. Defaults to 8000.

Syntax

var maxRetryTime = requestHandler.maxRetryTime;

21.39.4.4. onReconnected

Summary

A JavaScript function. Called if onRequestTimeout has been called and the connection has been regained or the service is back online allowing the request to succeed.

Syntax

requestHandler.onReconnected = function onReconnectedFn(reason, requestCallContext)
{
    failedAsset = null;
    if (reason === this.reasonConnectionLost)
    {
        // switch off a connection lost message
        ...
    }
    else if (reason === this.reasonServiceBusy)
    {
        // switch off a service busy message
        ...
    }
};
reason
A JavaScript number. The reason code for the original failure.
requestCallContext
The callContext of the requestHandler.request call that caused the timeout. The callContext now contains the following additional properties:
  • status - The returned status response of the last request.
  • retries - The number of times the RequestHandler has retried the request.

21.39.4.5. onRequestTimeout

Summary

A JavaScript function. Called when a request fails because of a lost internet connection or a disconnected or overloaded server.

Syntax

requestHandler.onRequestTimeout = function onRequestTimeoutFn(reason, requestCallContext)
{
    failedAsset = requestCallContext;
    if (reason === this.reasonConnectionLost)
    {
        // switch on a connection lost message
        log('After ' + requestCallContext.retries + ' retries the ' + requestCallContext.src + ' asset failed with code ' + requestCallContext.status);
        ...
    }
    else if (reason === this.reasonServiceBusy)
    {
        // switch on a service busy message
        ...
    }
};
reason
A JavaScript number. The reason code for the failure.
requestCallContext
The callContext of the requestHandler.request call that caused the timeout. The callContext now contains the following additional properties:
  • status - The returned status response of the last request.
  • retries - The number of times the RequestHandler has retried the request.

Note

The first set of assets to load should be the assets required to display a connection lost message. This means that if a connection is lost at any time the message can be displayed.

21.39.4.6. reasonConnectionLost

Summary

A JavaScript number. A reason code given as an argument for the onReconnected and onRequestTimeout functions.

Syntax

var reasonConnectionLost = requestHandler.reasonConnectionLost;

21.39.4.7. reasonServiceBusy

Summary

A JavaScript number. A reason code given as an argument for the onReconnected and onRequestTimeout functions.

Syntax

var reasonServiceBusy = requestHandler.reasonServiceBusy;

21.39.5. Event Types

Event listeners can be added for the following event types:

21.39.5.1. eventOnLoad

Summary

Occurs when an asset is loaded.

Syntax

var eventType = 'eventOnLoad';

var eventListener = function eventOnLoad(event)
{
        ...
        ...
}

requestHandler.addEventListener(eventType, eventListener);

Event Listener Arguments

event
An object with the following fields
name
The name of the asset just loaded.
eventType
The event that triggered this callback.