Class i$.promise.Promise
Class representing a Promise
Constructor Attributes | Constructor Name and Description |
---|---|
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 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.