Class: Batch

baja.comm. Batch


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 be params.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 to Batch.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
*