Class RapidContext.Procedure

The procedure wrapper function. Used to provide a simplified way of calling a procedure and connecting results through signals (instead of using deferred callbacks).

The actual calls are performed with normal function calls, but the results are asynchronous. When called, the procedure function returns a MochiKit.Async.Deferred object (as the normal API call), but the results will also be signalled through the onsuccess signal.

Differing from normal functions, a procedure function will also ensure that only a single call is in progress at any time, automatically cancelling any previous call if needed.

Source code: RapidContext_Procedure.js

Class Summary
	RapidContext.Procedure(procedure) Creates a new procedure caller function.

Field Summary
	args The arguments used in the last call.
	procedure The procedure name.

Method Summary
	cancel() Cancels any current execution of this procedure.
<static>	RapidContext.Procedure.mapAll(obj) Creates a new procedure caller for each key-value-pair in the specified object.
	multicall(args, transform) Calls the procedure multiple times (in sequence) with different arguments (supplied as an array of argument arrays).
	recall() Calls the procedure with the same arguments as used in the last call.
	reset() Cancels any current execution and removes the reference to the arguments of this procedure.

Event Summary
	oncall() Emitted when the procedure is called.
	oncancel() Emitted when a procedure call was cancelled.
	onerror() Emitted when a procedure call failed.
	onresponse() Emitted when the procedure response has been received.
	onsuccess() Emitted when a procedure call returned a result.
	onupdate() Emitted if a partial procedure result is available.

Class Detail

RapidContext.Procedure(procedure)

Creates a new procedure caller function. This function can be called either as a constructor or as a plain function. In both cases it returns a new JavaScript function with additional methods.

Parameters:
{String} procedure: the procedure name

Field Detail

{String} procedure

The procedure name.

{Array} args

The arguments used in the last call.

Method Detail

<static> {Object} RapidContext.Procedure.mapAll(obj)

Creates a new procedure caller for each key-value-pair in the specified object.

Parameters:
{Object} obj: an object mapping keys to procedure names

Returns:: {Object} an object mapping keys to procedure instances

{Deferred} recall()

Calls the procedure with the same arguments as used in the last call. The call is asynchronous, so results will not be returned by this method. Instead the results will be available through the onsuccess signal, for example.

Note that any previously running call will automatically be cancelled, since only a single call can be processed at any time.

Returns:: {Deferred} a MochiKit.Async.Deferred object that will callback with the response data or error

{Deferred} multicall(args, transform)

Calls the procedure multiple times (in sequence) with different arguments (supplied as an array of argument arrays). The calls are asynchronous, so results will not be returned by this method. Instead an array with the results will be available through the onupdate and onsuccess signals, for example.

Note that any previously running call will automatically be cancelled, since only a single call can be processed at any time. A result transform function can be supplied to transform each individual result. If the transform function throws an error, that result will be omitted.

Parameters:
{Array} args: the array of argument arrays
{Function} transform Optional: the optional result transform function

Returns:: {Deferred} a MochiKit.Async.Deferred object that will callback with the response data or error

cancel()

Cancels any current execution of this procedure. This method does nothing if no procedure call was currently executing.

reset()

Cancels any current execution and removes the reference to the arguments of this procedure.

Event Detail

oncall()

Emitted when the procedure is called. Each call corresponds to exactly one oncall and one onresponse event (even if the call was cancelled). No event data will be sent.

onupdate()

Emitted if a partial procedure result is available. This event will only be emitted when performing a multi-call, along with the oncall and onresponse events (for each call). The partial procedure result will be sent as the event data.

onresponse()

Emitted when the procedure response has been received. Each call corresponds to exactly one oncall and one onresponse event (even if the call was cancelled). The call response or error object will be sent as the event data.

onsuccess()

Emitted when a procedure call returned a result. This event is emitted after the onresponse event, but only if the procedure call actually succeeded. Use the onerror or oncancel signals for other result statuses. The call response object will be sent as the event data.

onerror()

Emitted when a procedure call failed. This event is emitted after the onresponse event, but only if the procedure call returned an error. Use the onsuccess or oncancel for other result statuses. The call error object will be sent as the event data.

oncancel()

Emitted when a procedure call was cancelled. This event is emitted after the onresponse event, but only if the procedure call was cancelled. Use the onsuccess or onerror for other result statuses. No event data will be sent.