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:
It also catches any XMLHttpRequest responses with a Retry-After header. When a request fails like this the RequestHandler does the following:
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") }}*/
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.
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.
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);
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);
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);
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();
Summary
A JavaScript number. Initial time in milliseconds to wait before retrying a request. Defaults to 500.
Syntax
var initialRetryTime = requestHandler.initialRetryTime;
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;
Summary
A JavaScript number. Maximum time in milliseconds to wait before retrying a request. Defaults to 8000.
Syntax
var maxRetryTime = requestHandler.maxRetryTime;
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
...
}
};
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
...
}
};
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.
Summary
A JavaScript number. A reason code given as an argument for the onReconnected and onRequestTimeout functions.
Syntax
var reasonConnectionLost = requestHandler.reasonConnectionLost;
Summary
A JavaScript number. A reason code given as an argument for the onReconnected and onRequestTimeout functions.
Syntax
var reasonServiceBusy = requestHandler.reasonServiceBusy;
Event listeners can be added for the following event types:
Summary
Occurs when an asset is loaded.
Syntax
var eventType = 'eventOnLoad';
var eventListener = function eventOnLoad(event)
{
...
...
}
requestHandler.addEventListener(eventType, eventListener);
Event Listener Arguments