Class i$.promise.Promise

Class representing a Promise

Class Summary
Constructor Attributes	Constructor Name and Description
	i$.promise.Promise() A Promise allows immediate handling of values that are resolved at a later point in time by attaching callback handlers that will be notified when the value is available.

Method Summary
Method Attributes	Method Name and Description
	call(name, args) Calls a function on the eventual resolved value of this Promise with optional arguments.
	get(name) Accesses a property on the resulting value of this Promise, returning a new Promise that resolves to that property's value.
	progress(p) Can be called by Promise producers to notify registered progress handlers of progress events.
	reject(e) Fails this Promise with e and error status permanently.
	resolve(v) Resolves this Promise with value v and success status permanently.
	then(suc, err, prog) Attaches handlers to this Promise that will be invoked by the proper event occuring on this Promise.

Class Detail

i$.promise.Promise()

A Promise allows immediate handling of values that are resolved at a later point in time by attaching callback handlers that will be notified when the value is available. This can be returned by functions to guarantee access to a value at some point in time that may not be available immediately. Consumers of Promise instances can attach callbacks that are fired when the value is eventually available, or if an error occurs during resolution. Progress handlers are entirely optional, are not guaranteed to be fired by the producer of the Promise, and are therefore only a convenience for interfaces that provide such functionality (ex. file uploads with progress notification).

Please note: For faster access this object has been made available directly on i$ as i$.Promise.

Method Detail

{i$.promise.Promise} call(name, args)

Calls a function on the eventual resolved value of this Promise with optional arguments. This immediately returns a new Promise that resolves to the return value of that eventual function call or rejects with any error that is thrown during the function's invocation. If no function exists at the property name specified on the resulting value, the returned Promise rejects with an appropriate error. If the producing Promise (this Promise) rejects, then the returned Promise rejects with the same error that this Promise rejected with.

var obj = {
    add: function(p1, p2){
        return p1 + p2;
    }
}
i$.promise.resolved(obj).call("add", [3, 5]).then(function(data){
    // data is the result of calling obj.add(3, 5)
    alert(data); // alerts 8
});

Parameters:
{String} name: The name of the function on the resolved value of this Promise to call. Must not be null, or will fail with a null pointer exception.
{Array} args: An array of arguments to call the function with. May be null or undefined.

Returns:: {i$.promise.Promise} A Promise that resolves to the return value of the eventual function call. Never null.

{i$.promise.Promise} get(name)

Accesses a property on the resulting value of this Promise, returning a new Promise that resolves to that property's value. If the producing Promise (this Promise) rejects, the returned Promise rejects with the same error this rejected with.

var obj = {
    a: {
        prop: "Value"
    }
}
i$.promise.resolved(obj).get("a").then(function(data){
    // data is a
    alert(data.prop); // alerts "Value"
});

Parameters:
{String} name: The name of the property on the resolved value of this Promise to call. Must not be null, or will fail with a null pointer exception.

Returns:: {i$.promise.Promise} A Promise that resolves to the value of the property on this Promise's resolved value. Never null.

{i$.promise.Promise} progress(p)

Can be called by Promise producers to notify registered progress handlers of progress events.

Parameters:
{Object} p: The value to pass to registered progress handlers. May be null.

Returns:: {i$.promise.Promise} This promise object. Never null.

{i$.promise.Promise} reject(e)

Fails this Promise with e and error status permanently.

Parameters:
{Object} e: The value to reject this Promise with. Does not have to be an error. May be null.

Returns:: {i$.promise.Promise} This promise object. Never null.

{i$.promise.Promise} resolve(v)

Resolves this Promise with value v and success status permanently.

Parameters:
{Object} v: The value to resolve this Promise with. May be null.

Returns:: {i$.promise.Promise} This promise object. Never null.

{i$.promise.Promise} then(suc, err, prog)

Attaches handlers to this Promise that will be invoked by the proper event occuring on this Promise. Success handlers are each called once when this Promise is resolved successfully and receive the resolved value as their first argument. Error handlers are each called once when this Promise is rejected with the error as their first argument. Progress handlers are called whenever this Promise's progress function is called with its first argument passed on to them.

This returns a new Promise whose final resolution is determined by the result of executing the registered callbacks added during this invocation. If the success callback is invoked, the returned Promise is resolved with its return value or rejected if it throws an error during execution. If the error callback is invoked, the returned Promise is rejected with that same error so that it is propagated forward.

var obj = {
    a: 5,
    b: 10
}
i$.promise.resolved(obj).then(function(data){
    // data is obj
    alert(data.b); // alerts 10
});

Parameters:
{Function(v)} suc: The function to attach as a success handler. May be null or undefined.
{Function(e)} err: The function to attach as an error handler. May be null or undefined.
{Function(p)} prog: The function to attach as a progress handler. May be null or undefined.

Returns:: {i$.promise.Promise} A new Promise whose resolution depends on the callbacks registered during this invocation. Never null.

Classes

Class i$.promise.Promise