Batch

new Batch()

Description:

• A Batch is used to "package up" a number of operations (such as setting a
  Slot value or invoking an Action) into a single network call. Use a Batch
  when you want to be absolutely certain that a group of operations will all
  arrive at the server at the same time, be processed on their own (not
  alongside any other operations that are not part of this Batch), and be
  executed on the server synchronously.

  When interacting with a JACE, it is important to keep the number of
  individual network calls low. This is because the JACE has to do some work
  to receive an HTTP request, whether that request is one byte or 10,000
  bytes. Therefore, by packaging requests into fewer network calls, we reduce
  the CPU load on the JACE and improve response times in the browser.

  Previous to Niagara 4.10, it was required to use a Batch to get
  individual operations to package up into a single network call. However,
  Batches can be easy to forget and add additional complexity to your code.
  Therefore, starting in Niagara 4.10, BajaScript will automatically
  package operations together. Using a technique called "implicit batching",
  operations that occur chronologically close together in the browser will
  get packaged up into a single network call. As of Niagara 4.10, you can
  consider the use of Batches purely for network efficiency as deprecated -
  BajaScript will make network calls efficient by default.

  When operations are batched together, it does not imply any sort of error
  handling. A Batch is not a replacement for Promise.all. Its only job is
  to cut down on network traffic. 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.

  Most operations in BajaScript can be batched together. To use a Batch,
  you'll typically pass it in as an argument to a function that supports it.
  Please see the examples.

Source:

• baja/comm/Batch.js, line 142

Examples

Invoking two actions, using a Batch to make it explicit that the actions should execute on the server at the same time.

var batch = new baja.comm.Batch();

var promise = Promise.all([
  myComp.invoke({ slot: 'thisActionWillSucceed', batch: batch })
    .then(function () { console.log('this message will show'); }),
  myComp2.invoke({ slot: 'thisActionWillFailOnTheStation', 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();
return promise;

batch.commit() returns its argument. Use this to improve the brevity and readability of your code.

var batch = new baja.comm.Batch();

return batch.commit(Promise.all([
  comp.invoke({ slot: 'action1', batch: batch }),
  comp.invoke({ slot: 'action2', batch: batch })
]));

Here, our only concern is network efficiency. We can call set() as many times as we want. Because we queue everything up at the same time, the set() operations will automatically batch together into a single network call. If other operations also execute at the same time as these set() calls, it's possible they could all also be packaged into the same batch. Prior to Niagara 4.10, each un-batched set() would cause its own network call.

return Promise.all([
  comp.set({ slot: 'slot1', value: 'value1' }),
  comp.set({ slot: 'slot2', value: 'value2' }),
  comp.set({ slot: 'slot3', value: 'value3' })
]);

Here, these two set() calls may not implicitly batch together because they don't happen close to each other chronologically. They will probably go up to the station in two separate network calls.

return Promise.all([
  comp.set({ slot: 'slot1', value: 'value1' }),
  waitSeconds(2)
    .then(function () {
      return comp.set({ slot: 'slot2', value: 'value2' });
    });
]);

The size of a WebSocket message is limited. If there are too many batched operations to fit into a single WebSocket message, BajaScript will automatically split the batch into multiple network calls. They will be reassembled on the other end, and the batch will be processed as normal. Prior to Niagara 4.10, exceeding the WebSocket message size would result in an error.

function addTenThousandSlots(comp) {
  var promises = [];
  for (var i = 0; i < 10000; ++i) {
    promises.push(comp.add({ slot: 'number?', value: i }));
  }
  return Promise.all(promises);
}

//instead of this...
var promise = doABunchOfNetworkCalls(batch);
batch.commit();
return promise;

//do this:
return batch.commit(doABunchOfNetworkCalls(batch));

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();