new Batch()
Batch Network Call Capturing.
A Batch object can be used to batch up a number of network calls into
one network call. It's used for network efficient remote programming in
BajaScript.
When specified, a batch object is typically an optional argument in a method
that could make a network call.
Please be aware: a Batch is not a replacement for Promise.all
. Its only
job is to cut down on network traffic. If you batch several operations
together, then as long as the one network call successfully goes out over
the wire and receives a response, each operation will still succeed
or fail individually. See the example.
Example
var batch = new baja.comm.Batch(); myComp.invoke({ slot: 'thisActionWillSucceed', batch: batch }) .then(function () { console.log('this message will show'); }); myComp2.invoke({ slot: 'thisActionWillThrowAnExceptionOnTheStation', batch: batch }) .catch(function (err) { console.log('this error will show: ' + err); }); // Make a single network call that will invoke both Actions in one go. // Just because the second action fails on the station and sends back an // error message, the first action didn't fail along with it just // because they shared a Batch. batch.commit();
Extends
Methods
-
<static> reserve( [params])
-
Reserve a new batch. If an input batch is given (either directly or as a
batch
property of an object), it will create a new reserve batch off
of that batch. If no input batch is given, this will simply return a new
batch.Use this when your function might have an input batch parameter that you
want to make use of while still leaving the question of when to commit the
batch up to the caller.Parameters:
Name Type Argument Description params
baja.comm.Batch | object <optional>
If a batch is given, will reserve
a new batch off of the input batch. Can also beparams.batch
. Otherwise,
will create a new batch.Properties
Name Type Argument Description batch
baja.comm.Batch <optional>
Returns:
either a reserved, or a new batch. It is your
responsibility as the caller toBatch.reserve
to commit this batch.- Type
- baja.comm.Batch
-
commit( [arg])
-
Sends all BOX requests queued up in this batch across the wire in one
network call.Once called, this batch can no longer have messages or callbacks added, or
be committed a second time.Parameters:
Name Type Argument Description arg
* <optional>
an input argument to be returned directly - see example
Throws:
-
if already committed
- Type
- Error
Returns:
input arg
- Type
- *
Example
Returning the input arg enables a bit of API cleanliness when returning promises.
//instead of this... var promise = doABunchOfNetworkCalls(batch); batch.commit(); return promise; //do this: return batch.commit(doABunchOfNetworkCalls(batch));
-
-
equals(obj)
-
Indicates whether some other object is equal to this one.
Parameters:
Name Type Description obj
Object the reference object with which to compare.
- Inherited From:
Returns:
true if this object is the same as the obj argument; false otherwise.
- Type
- Boolean
-
reserve()
-
Creates a new batch that will prevent the current batch from sending any
network calls until the reserve batch itself has been committed. All
requests on all reserve batches, as well as the current batch, will be
condensed into a single network call and sent as soon as all reserve
batches are committed.Use this function when you need to add requests to a batch after completing
some other asynchronous operation. It signals to the original batch, "wait
for me!"The reserved batch's
commit()
function will not actually send any data.
It simply signals that your code has finished adding requests to it and
the original batch is clear to send its data.Returns:
- Type
- baja.comm.Batch
Example
Given a set of relation knobs, I need to resolve each knob's relation ORD and retrieve all relations from the source component. I happen to know that the relation ORDs have already been resolved, so resolving the ORD will not incur a network call, but retrieving relations always does. Therefore, I want to reserve the batch to use on the relations() call.
function retrieveSourceComponentRelations(relationKnob, inpBatch) { var reserved = inpBatch.reserve(); return relationKnob.getRelationOrd().get() .then(function (relationSourceComponent) { //if I had not reserved a batch, inpBatch would have already been committed //by the caller, and this would throw an error. var relationsPromise = relationSourceComponent.relations({ batch: reserved }); //calling commit() on the reserved batch notifies inpBatch that I'm done //adding operations, and inpBatch is clear to go ahead and send out the //network call. reserved.commit(); return relationsPromise; }); } //now all relations() calls will batch together into a single network call. var batch = new baja.comm.Batch(), promise = Promise.all(allRelationKnobs.map(function (relationKnob) { return retrieveSourceComponentRelations(relationKnob, batch); })) .then(function (relationsResults) { relationsResults.forEach(function (relations) { handle(relations); }); }); batch.commit();
-
valueOf()
-
Return the inner value of the object.
By default the object's instance is returned.
- Inherited From:
Returns:
the inner value of the object or just the object's instance.
- Type
- *