Chapter 10. $fh.sync

The cloud sync framework requires handler functions to be defined which provide access to the back end data & manage data collisions. These are specified in the handleXXX() functions. Each unique dataset being managed is identified by a dataset_id which must be specified as the first parameter when calling any function of the sync framework.

Note

Default implementations of the handler functions are already provided as part of the MBaaS service. They use hosted db service to save data (via $fh.db). If this is enough for your app, you don’t need to implement the handler functions anymore, you just need to call the init function and provide sync options.

However, if the default implementations do not meet your app’s requirement (e.g you need to save data to somewhere else), you need to provide your own implementations of the handler functions listed below. You can provide implementations for all the CRUDL operations, or you can change the default behaviour of a particular operation by only providing an override for the corresponding handler function (e.g provide an override $fh.sync.handleRead function will allow you to implement your own read data logic, but keep the rest operations to still use the default MBaaS implementations).

The following table outlines the changes to the APIs relating to the introduction of fh-mbaas-api version 7 in this release. You can continue to use the pre 7.0.0 version, and the old documentation is still available.

API7.0.0 or laterpre 7.0.0

$fh.sync.setConfig

New

N/A

$fh.sync.connect

New

N/A

$fh.sync.init

Unchanged

Old documentation

$fh.sync.invoke

Unchanged

Old documentation

$fh.sync.stop

Unchanged

Old documentation

$fh.sync.stopAll

Unchanged

Old documentation

$fh.sync.handleList

Changed

Old documentation

$fh.sync.globalHandleList

Changed

Old documentation

$fh.sync.handleCreate

Changed

Old documentation

$fh.sync.globalHandleCreate

Changed

Old documentation

$fh.sync.handleRead

Changed

Old documentation

$fh.sync.globalHandleRead

Changed

Old documentation

$fh.sync.handleUpdate

Changed

Old documentation

$fh.sync.globalHandleUpdate

Changed

Old documentation

$fh.sync.handleDelete

Changed

Old documentation

$fh.sync.globalHandleDelete

Changed

Old documentation

$fh.sync.handleCollision

Unchanged

Old documentation

$fh.sync.globalHandleCollision

Unchanged

Old documentation

$fh.sync.listCollisions

Changed

Old documentation

$fh.sync.globalListCollisions

Changed

Old documentation

$fh.sync.removeCollision

Changed

Old documentation

$fh.sync.globalRemoveCollision

Changed

Old documentation

$fh.sync.setGlobalHashFn

New

N/A

$fh.sync.setRecordHashFn

New

N/A

$fh.sync.interceptRequest

Changed

Old documentation

$fh.sync.globalInterceptRequest

Changed

Old documentation

$fh.sync.getEventEmitter

New

N/A

10.1. $fh.sync.setConfig

Configure the sync server.

Call this API when the sync server is ready, but before initialising any of the datasets. Initialisation of a Dataset typically happens when the first Sync client connects, unless you have explicit calls to sync.init. Either way, a reasonable location to call setConfig is when the sync:ready event triggers.

10.1.1. Usage

$fh.sync.setConfig(options)

10.1.2. Parameters

10.1.2.1. options

  • Description: Configuration options for the sync server
  • Type: Object
  • Supported Keys

    • pendingWorkerInterval

      • Description: Set the interval value for the pending workers, in milliseconds. For more details about the worker interval, see the Data Sync Configuration Guide.
      • Type: Number
      • Default: 1
    • pendingWorkerBackoff

      • Description: Specify the backoff strategy for the pending workers. For more details about the worker backoff, see the Data Sync Configuration Guide.
      • Type: Object
      • Default: {strategy: 'exp', max: 60000}

        • strategy

          Define the backoff strategy. Valid values are exp (exponential) and fib (fibonacci). Setting the value to anything else disables worker backoff.

        • max

          The max delay time for the backoff strategy, in milliseconds.

    • pendingWorkerConcurrency

      • Description: Set the number of concurrent pending workers. Set it to 0 will disable the pending workers.
      • Type: Number
      • Default: 1
    • ackWorkerInterval

      • Description: Set the interval value for the ack workers, in milliseconds. For more details about the worker interval, see the Data Sync Configuration Guide.
      • Type: Number
      • Default: 1
    • ackWorkerBackoff

      • Description: Specify the backoff strategy for the ack workers. For more details about the worker backoff, see the Data Sync Configuration Guide.
      • Type: Object
      • Default: {strategy: 'exp', max: 60000}

        • strategy

          Define the backoff strategy. Valid values are exp (exponential) and fib (fibonacci). Setting it to anything else disables the backoff strategy for the ack workers.

        • max

          The max delay time for the backoff strategy, in milliseconds.

    • ackWorkerConcurrency

      • Description: Set the number of concurrent ack workers. Setting it to 0 disables the ack workers.
      • Type: Number
      • Default: 1
    • syncWorkerInterval

      • Description: Set the interval value for the sync workers, in milliseconds. For more details about the worker interval, see the Data Sync Configuration Guide.
      • Type: Number
      • Default: 100
    • syncWorkerBackoff

      • Description: Specify the backoff strategy for the sync workers. For more details about the worker backoff, see the Data Sync Configuration Guide.
      • Type: Object
      • Default: {strategy: 'none'}

        • strategy

          Define the backoff strategy. Valid values are exp (exponential) and fib (fibonacci). Setting it to anything else disables the backoff strategy.

        • max

          The max delay time for the backoff strategy, in milliseconds.

    • syncWorkerConcurrency

      • Description: Set the number of concurrent sync workers. Setting it to 0 disables the sync workers.
      • Type: Number
      • Default: 1
    • collectStats

      • Description: Determine if the sync server collects performance stats data.

        By default, the sync server collects some performance data, for example, db operation timing, API timing, queue size.

        The stats data is stored in Redis and has minimum performance overhead.

      • Type: Boolean
      • Default: true
    • statsRecordsToKeep

      • Description: Determine how many stats data points to save for each metric series in Redis.
      • Type: Number
      • Default: 1000
    • collectStatsInterval

      • Description: Determine how often the stats should be collected, in milliseconds.
      • Type: Number
      • Default: 5000
    • metricsInfluxdbHost

      • Description: Specify the InfluxDB host to which the sync server sends performance data.
      • Type: String
      • Default: null
    • metricsInfluxdbPort

      • Description: Specify the InfluxDB port. It must be a UDP port.
      • Type: Number
      • Default: null
    • queueMessagesTTL

      • Description: The time to live value for the queue messages that are marked for deletion. The messages are removed from the database once TTL value is reached. In seconds.
      • Type: Number
      • Default: 86400 (1 day)
    • datasetClientCleanerRetentionPeriod

      • Description: Specify how long an inactive datasetClient is kept in the database before it is deleted.

        To avoid unnessary deletion of datasetClients, consider overriding this configuration with a value that is appropriate for the app. For example, if there is no user using the app during the weekend, you could set this value to '96h'.

      • Type: String
      • Default: '24h'

        • Other supported units including: s (second), m (minute), h (hour), d (day), w (week), y (year)
    • datasetClientCleanerCheckFrequency

      • Description: Specify how often the datasetClient cleaner job runs.
      • Type: String
      • Default: '1h'
    • useCache

      • Description: Specify if Redis is used to cache the records of a Dataset Client.

        When enabled, it should reduce the number of requests on the database, and reduce the time of the syncRecords API call.

        It is an experimental feature and may cause delay for changes to be visible to all clients.

      • Type: Boolean
      • Default: false
    • schedulerInterval

      • Description: set the interval for the sync scheduler, in milliseconds.

        Typically, you do not need to change the value.

      • Type: Number
      • Default: 500
    • schedulerLockName

      • Description: A lock is used to make sure that only 1 sync scheduler can run at any given time. This field determines the name of that lock.

        Typically, you do not need to change the value.

      • Type: String
      • Default: locks:sync:SyncScheduler
    • schedulerLockMaxTime

      • Description: A lock is used to make sure that only 1 sync scheduler can run at any given time. This field determines the maximum time the sync scheduler can hold the lock for. This is to prevent the sync scheduler from holding the lock forever (for example, if the process crashes).

        Typically, you do not need to change the value.

      • Type: Number
      • Default: 20000
    • datasetClientUpdateConcurrency

      • Description: When there are a lot concurrent sync requests to the sync server, a lot of update operations to the Dataset Clients are generated. To avoid overloading the database, those operations are queued and then performed with the concurrency of this option.

        Typically, you do not need to change the value.

      • Type: Number
      • Default: 10

10.1.3. Example

$fh.events.on('sync:ready', function(){
  var pendingWorkerInterval = process.env.PENDING_WORKER_INTERVAL || 500;
  var syncWorkerInterval = process.env.SYNC_WORKER_INTERVAL || 500;
  var ackWorkerInterval = process.env.ACK_WORKER_INTERVAL || 500;
  var useCache = process.env.USE_CACHE === 'true';
  var syncConfig = {
    pendingWorkerInterval: parseInt(pendingWorkerInterval),
    ackWorkerInterval: parseInt(ackWorkerInterval),
    syncWorkerInterval: parseInt(syncWorkerInterval),
    collectStatsInterval: 4000,
    metricsInfluxdbHost: process.env.METRICS_HOST,
    metricsInfluxdbPort: parseInt(process.env.METRICS_PORT),
    useCache: useCache
  };
  $fh.sync.setConfig(syncConfig);
});

10.2. $fh.sync.connect

Make sure the sync server is connected to the required resources, that is, MongoDB and Redis.

Note

When using the sync server from fh-mbaas-api, sync.connect is called automatically, and uses the Cloud App’s database. There is no need to call sync.connect in this scenario.

10.2.1. Usage

$fh.sync.connect(mongodbConnectionString, mongodbConf, redisConnectionString, callback)

10.2.2. Parameters

10.2.2.1. mongodbConnectionString

  • Description: The connection url of MongoDB. The url is passed straight to the mongodb module.
  • Type: String

10.2.2.2. mongodbConf

  • Description: The MongoDB connection options. For more details of this option, see MongoClient.connect API doc.

    Typically, you do not need to call this API. However, you can control some of the MongoDB connection options using environment variables:

    • SYNC_MONGODB_POOLSIZE

      • Description: Specify the MongoDB connection pool size
      • Type: Number
      • Default: 50
  • Type: Object

10.2.2.3. redisConnectionString

  • Description: The connection URL of Redis, which can include authentication information if required. The URL is passed directly to the redis module.
  • Type: String

10.2.2.4. callback

  • Description: the callback function
  • Type: function

10.2.3. Example

var mongodbUrl = "mongodb://mongouser:mongopass@127.0.0.1";
var redisUrl = "redis://redisuser:redispass@127.0.0.1";

$fh.sync.connect(mongodbUrl, {}, redisUrl, function(err){
  if (err) {
    console.error('Connection error for sync', err);
  } else {
    console.log('sync connected');
  }
});

10.3. $fh.sync.init

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Set the sync options for the Dataset and start the sync process. This API can also be used to start the sync process on a Dataset.

This API call is optional, but can be used to override options for a specific Dataset.

10.3.1. Usage

$fh.sync.init(dataset_id, options, callback)

10.3.2. Parameters

10.3.2.1. dataset_id

  • Description: The id of the dataset that needs to be synchronized.
  • Type: String

10.3.2.2. options

  • Description: The sync options for the Dataset.
  • Type: Object
  • Supported Keys:

    • syncFrequency

    • clientSyncTimeout

      • Description: Specify the period of time before the Dataset client is marked as "inactive" due to inactivity, in seconds.

        If a Dataset client is marked as "inactive", the sync server stops syncing the data of the Dataset client with the backend.

        If a user accesses an "inactive" Dataset client later, the user might need to wait until the next sync operation is complete. To avoid this scenario, set this timeout to a relatively long value.

      • Type: Number
      • Default: 3600 (1 hour)
    • backendListTimeout

      • Description: Specify the timeout value the sync server waits for the sync operation with the Backend Database to complete, in seconds.
      • Type: Number
      • Default: 300

10.3.2.3. callback

  • Description: The callback function invoked when fh.init is complete.
  • Type: Function

10.3.3. Example

var datasetId = "todolist";
var syncOptions = {
  syncFrequency: 10,
  clientSyncTimeout: 24*60*60
};
$fh.sync.init(datasetId, syncOptions, function(err){
  if (err) {
    console.error('sync init failed due to error', err);
  } else {
    console.log('sync init finished successfully');
  }
});

10.3.4. $fh.sync.init for fh-mbaas-api Version Less than 7.0.0

$fh.sync.init(dataset_id, options, callback)

Initialise cloud data sync service for specified dataset.

10.3.4.1. Example

// Unique Id for the dataset to initialise.
var dataset_id = 'tasks';
// Configuration options
var options = {
  "syncFrequency": 10, // How often to synchronise data with the back end data store in seconds. Default: 10s
  "logLevel":"info" // The level of logging. Can be usful for debugging. Valid options including: 'silly', 'verbose', 'info', 'warn', 'debug', 'error'
};
$fh.sync.init(dataset_id, options, function(err) {
  // Check for any error thrown during initialisation
  if (err) {
    console.error(err);
  } else {
    //you can now provide data handler function overrides (again, not required at all). For example,
    $fh.sync.handleList(dataset_id, function(dataset_id, params, cb, meta_data){
      //implement the data listing logic
    });
  }
});

10.4. $fh.sync.invoke

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Invoke internal sync functions of the sync server. Typical development does not require you to invoke these functions. Note that the params object is the same as the request body from Sync clients, because this API is called by Sync clients.

10.4.1. Usage

$fh.sync.invoke(dataset_id, params, callback)

10.4.2. Parameters

10.4.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.4.2.2. params

  • Description: Specify the target function name, also passed to the target function.
  • Type: Object
  • Supported Keys:

    • fn

      • Description: specify the name of the target function to invoke. Supported functions including:

        • sync
        • syncRecords
        • listCollisions
        • removeCollision
      • Type: String
    • Other fields vary depending on the target function. Please check the source code for the required fields.

10.4.3. Example

var datasetId = "todo";
var syncRecordsParams = {
  fn: 'syncRecords',
  dataset_id: datasetId,
  query_params: {},
  clientRecs: {},
  __fh: {
    cuid: 'testdeviceid'
  }
};

$fh.sync.invoke(datasetId, syncRecordsParams, function(err, syncData) {
  if (err) {
    console.error('Failed to call syncRecords due to error', err);
  } else {
    console.log('Got sync data', syncData);
  }
});

10.4.4. $fh.sync.invoke for fh-mbaas-api Version Less than 7.0.0

$fh.sync.invoke(dataset_id, params, callback)

Invoke the Sync Server.

10.4.4.1. Example

// This should be called from a cloud “act” function.
// The params passed to the “act” function:
var params = {
  "limit": 50
};
$fh.sync.invoke(dataset_id, params, function() {
  // "act" function callback
});

10.5. $fh.sync.stop

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Stop the synchronization of a specific Dataset with the Dataset Backend.

10.5.1. Usage

$fh.sync.stop(dataset_id, callback)

10.5.2. Parameters

10.5.2.1. dataset_id

  • Description: The id of the dataset.
  • Type: String

10.5.2.2. callback

  • Description: The callback function.
  • Type: Function

10.5.3. Example

var datasetId = "todolist";
$fh.sync.stop(datasetId, function(err){
  if (err) {
    console.error('sync stop failed due to error', err);
  } else {
    console.log('sync stop finished successfully');
  }
});

10.5.4. $fh.sync.stop for fh-mbaas-api Version Less than 7.0.0

$fh.sync.stop(dataset_id, callback)

Stop cloud data sync for the specified dataset_id.

10.5.4.1. Example

// This will remove any reference to the dataset from the sync service.
// Any subsequent cloud calls to sync.invoke will fail with an unknown_dataset error.
// The dataset can be put back under control of the sync service by calling the
// sync.init() function again.
// Calling stop on a non-existent dataset has no effect.
// Calling stop multiple times on the same dataset has no effect.
$fh.sync.stop(dataset_id, function() {
  // Callback to invoke once the dataset has been removed from the management
  // of the service.
  // There are no parameters passed to this callback.
});

10.6. $fh.sync.stopAll

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Stop the synchronization of all Datasets with the Dataset Backend.

10.6.1. Usage

$fh.sync.stopAll(callback)

10.6.2. Parameters

10.6.2.1. callback

  • Description: The callback function.
  • Type: Function

10.6.3. Example

$fh.sync.stopAll(function(err){
  if (err) {
    console.error('sync stopAll failed due to error', err);
  } else {
    console.log('sync stopAll finished successfully');
  }
});

10.6.4. $fh.sync.stopAll for fh-mbaas-api Version Less than 7.0.0

$fh.sync.stopAll(callback)

Stop cloud data sync service for ALL datasets.

10.6.4.1. Example

// This will remove all reference to all datasets from the sync service.
// Any subsequent cloud calls to sync.invoke() will fail with an unknown_dataset error.
// Any of the datasets can be put back under control of the sync service by calling
// the sync.init() function again and passing the required dataset_id.
// Calling stop multiple times has no effect -
// except that the return data to the callback (an array of dataset_ids which are no longer being synced) will be different.
$fh.sync.stopAll(function(err, res) {
  if (err) console.error(err); // Any error thrown during the removal of the datasets

  // A JSON Array of Strings - representing the dataset_Ids which have been
  // removed from the sync service.
  console.log(res);
});

10.7. $fh.sync.handleList

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function listing data from the Dataset Backend for a specific Dataset.

Note

Make sure the returned data is valid JSON objects. For example, a Date object is not valid in a JSON Object.

Note

Make sure there is no _id field in the returned data (or any of the nested objects). MongoDB does not save data that contains the _id field.

10.7.1. Usage

$fh.sync.handleList(dataset_id, function listHandler(dataset_id, query_params, meta_data, cb){});

10.7.2. Parameters

10.7.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.7.2.2. listHandler

  • Description: The function that is invoked when listing records
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • query_params

      • Description: the query parameter to use as part of the list, can be null.
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.7.3. Example

$fh.sync.handleList("todo", function(dataset_id, params, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // JSON object representing query parameters passed from the client.
  // These can be used to restrict the data set returned.
  console.log(params);

  // The callback into the sync service to store the dataset
  // cb(err, data)
  cb(null, { // A JSON Object - representing the data
    uid_1 : {/* data */},
    uid_2 : {/* data */},
    uid_3 : {/* data */}
  });
});

// It is recommended that the handleList function converts data from the back end
// format into a full JSON Object.
// This is a sensible approach when reading data from relational and nonrelational
// databases, and works well for SOAP and XML data.
// However, it may not always be feasible - for example, when reading non structured data.
// In these cases, the recomened approach is to create a JSON object with a single
// key called “data” and set the value for this key to be the actual data.
// for example, xml data
/*
<dataset>
  <row>
    <userid>123456</userid>
    <firstname>Joe</firstname>
    <surname>Bloggs</surname>
    <dob>1970-01-01</dob>
    <gender>male</gender>
  </row>
</dataset>
*/
/* json data
{
  "123456" : {
    "userid" : "123456",
    "firstname" : "Joe",
    "surname" : "Bloggs",
    "dob" : "1970-01-01",
    "gender" : "male"
  }
}
*/

// And for non structured data:
/*
123456|Joe|Bloggs|1970-01-01|male

{
  "123456" : {
    "data" : "123456|Joe|Bloggs|1970-01-01|male"
  }
}
*/

10.7.4. $fh.sync.handleList for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleList(dataset_id, callback)

Defines a handler function for listing data from the back end data source for a dataset. Call this API after the dataset is initialized.

10.7.4.1. Example

$fh.sync.handleList(dataset_id, function(dataset_id, params, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // JSON object representing query parameters passed from the client.
  // These can be used to restrict the data set returned.
  console.log(params);

  // The callback into the sync service to store the dataset
  // cb(err, data)
  cb(null, { // A JSON Object - representing the data
    uid_1 : {/* data */},
    uid_2 : {/* data */},
    uid_3 : {/* data */}
  });
});
// It is recommended that the handleList function converts data from the back end
// format into a full JSON Object.
// This is a sensible approach when reading data from relational and nonrelational
// databases, and works well for SOAP and XML data.
// However, it may not always be feasible - for example, when reading non structured data.
// In these cases, the recomened approach is to create a JSON object with a single
// key called “data” and set the value for this key to be the actual data.
// for example, xml data
/*
<dataset>
  <row>
    <userid>123456</userid>
    <firstname>Joe</firstname>
    <surname>Bloggs</surname>
    <dob>1970-01-01</dob>
    <gender>male</gender>
  </row>
</dataset>
*/
/* json data
{
  "123456" : {
    "userid" : "123456",
    "firstname" : "Joe",
    "surname" : "Bloggs",
    "dob" : "1970-01-01",
    "gender" : "male"
  }
}
*/

// And for non structured data:
/*
123456|Joe|Bloggs|1970-01-01|male

{
  "123456" : {
    "data" : "123456|Joe|Bloggs|1970-01-01|male"
  }
}
*/

10.8. $fh.sync.globalHandleList

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function for listing data from the Dataset Backend.

It can be used by multiple datasets, but typically, is only used if there is no handler assigned to the dataset using the handleList API.

Note

Make sure the returned data is valid JSON objects. For example, a Date object is not valid in a JSON Object.

Note

Make sure there is no _id field in the returned data (or any of the nested objects). MongoDB does not save data that contains the _id field.

10.8.1. Usage

$fh.sync.globalHandleList(function listHandler(dataset_id, query_params, meta_data, cb){});

10.8.2. Parameters

10.8.2.1. listHandler

  • Description: The function that is invoked when listing records
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • query_params

      • Description: the query parameter to use as part of the list, can be null.
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.8.3. Example

$fh.sync.globalHandleList(function(dataset_id, params, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // JSON object representing query parameters passed from the client.
  // These can be used to restrict the data set returned.
  console.log(params);

  // The callback into the sync service to store the dataset
  // cb(err, data)
  cb(null, { // A JSON Object - representing the data
    uid_1 : {/* data */},
    uid_2 : {/* data */},
    uid_3 : {/* data */}
  });
});

// It is recommended that the handleList function converts data from the back end
// format into a full JSON Object.
// This is a sensible approach when reading data from relational and nonrelational
// databases, and works well for SOAP and XML data.
// However, it may not always be feasible - for example, when reading non structured data.
// In these cases, the recomened approach is to create a JSON object with a single
// key called “data” and set the value for this key to be the actual data.
// for example, xml data
/*
<dataset>
  <row>
    <userid>123456</userid>
    <firstname>Joe</firstname>
    <surname>Bloggs</surname>
    <dob>1970-01-01</dob>
    <gender>male</gender>
  </row>
</dataset>
*/
/* json data
{
  "123456" : {
    "userid" : "123456",
    "firstname" : "Joe",
    "surname" : "Bloggs",
    "dob" : "1970-01-01",
    "gender" : "male"
  }
}
*/

// And for non structured data:
/*
123456|Joe|Bloggs|1970-01-01|male

{
  "123456" : {
    "data" : "123456|Joe|Bloggs|1970-01-01|male"
  }
}
*/

10.8.4. $fh.sync.globalHandleList for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleList(callback)

Similar to $fh.sync.handleList, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleList.

10.8.4.1. Example

$fh.sync.globalHandleList(function(dataset_id, params, cb, meta_data){
  //list data for the specified dataset_id
});

10.9. $fh.sync.handleCreate

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to create a single row of data in the Dataset Backend for a specific Dataset.

10.9.1. Usage

$fh.sync.handleCreate(dataset_id, function createHandler(dataset_id, data, meta_data, cb){});

10.9.2. Parameters

10.9.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.9.2.2. createHandler

  • Description: The function that is invoked when creating a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • data

      • Description: the data to create
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.9.3. Example

$fh.sync.handleCreate("todo", function(dataset_id, data, meta_data, cb){
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Row of data to create
  console.log(data);

  // Sample back-end storage call
  var savedData = saveData(data);
  var res = {
    "uid": savedData.uid, // Unique Identifier for row
    "data": savedData.data // The created data record - including any system or UID fields added during the create process
  };

  // Callback function for when the data has been created, or if theres an error
  return cb(null, res);
});

10.9.4. $fh.sync.handleCreate for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleCreate(dataset_id, callback)

Defines a handler function for creating a single row of data in the back end. Should be called after the dataset is inited.

10.9.4.1. Example

// data source for a dataset.
$fh.sync.handleCreate(dataset_id, function(dataset_id, data, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Row of data to create
  console.log(data);

  // Sample back-end storage call
  var savedData = saveData(data);
  var res = {
    "uid": savedData.uid, // Unique Identifier for row
    "data": savedData.data // The created data record - including any system or UID fields added during the create process
  };

  // Callback function for when the data has been created, or if theres an error
  return cb(null, res);
});

10.10. $fh.sync.globalHandleCreate

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function for creating a single row of data in the back end.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the handleCreate API.

10.10.1. Usage

$fh.sync.globalHandleCreate(function createHandler(dataset_id, data, meta_data, cb){});

10.10.2. Parameters

10.10.2.1. createHandler

  • Description: The function that is invoked when creating a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • data

      • Description: the data to create
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.10.3. Example

$fh.sync.globalHandleCreate(function(dataset_id, data, meta_data, cb){
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Row of data to create
  console.log(data);

  // Sample back-end storage call
  var savedData = saveData(data);
  var res = {
    "uid": savedData.uid, // Unique Identifier for row
    "data": savedData.data // The created data record - including any system or UID fields added during the create process
  };

  // Callback function for when the data has been created, or if theres an error
  return cb(null, res);
});

10.10.4. $fh.sync.globalHandleCreate for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleCreate(callback)

Similar to $fh.sync.handleCreate, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleCreate.

10.10.4.1. Example

$fh.sync.globalHandleCreate(function(dataset_id, data, cb, meta_data){
  //create data for the specified dataset_id
});

10.11. $fh.sync.handleRead

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to read a single row of data from the Dataset Backend for a specific Dataset.

10.11.1. Usage

$fh.sync.handleRead(dataset_id, function readHandler(dataset_id, uid, meta_data, cb){});

10.11.2. Parameters

10.11.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.11.2.2. readHandler

  • Description: The function that is invoked when reading a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to read
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.11.3. Example

$fh.sync.handleRead("todo", function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to read
  console.log(uid);

  // Sample back-end storage call
  var data = readData(uid);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the row of data
  return cb(null, data);
});

10.11.4. $fh.sync.handleRead for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleRead(dataset_id, callback)

Defines a handler function for reading a single row of data from the back end. Should be called after the dataset is initialised.

10.11.4.1. Example

// data source for a dataset
$fh.sync.handleRead(dataset_id, function(dataset_id, uid, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to read
  console.log(uid);

  // Sample back-end storage call
  var data = readData(uid);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the row of data
  return cb(null, data);
});

10.12. $fh.sync.globalHandleRead

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to read a single row of data from the Dataset Backend.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the handleRead API.

10.12.1. Usage

$fh.sync.globalHandleRead(function readHandler(dataset_id, uid, meta_data, cb){});

10.12.2. Parameters

10.12.2.1. readHandler

  • Description: The function that is invoked when reading a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to read
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.12.3. Example

$fh.sync.globalHandleRead(function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to read
  console.log(uid);

  // Sample back-end storage call
  var data = readData(uid);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the row of data
  return cb(null, data);
});

10.12.4. $fh.sync.globalHandleRead for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleRead(callback)

Similar to $fh.sync.handleRead, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleRead.

10.12.4.1. Example

$fh.sync.globalHandleRead(function(dataset_id, uid, cb, meta_data){
  //read data for the specified dataset_id and uid
});

10.13. $fh.sync.handleUpdate

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to update a single row of data on the Dataset Backend for a specific Dataset.

The sync server makes sure the data can be updated by checking the current value matches the value in the back end. If the values do not match, the update operation is not be performed and a collision is generated.

10.13.1. Usage

$fh.sync.handleUpdate(dataset_id, function updateHandler(dataset_id, uid, data, meta_data, cb){});

10.13.2. Parameters

10.13.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.13.2.2. updateHandler

  • Description: The function that is invoked when updating a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to update
      • Type: String
    • data

      • Description: the new date fields
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.13.3. Example

$fh.sync.handleUpdate("todo", function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Row of data to update
  console.log(data);

  // Sample back-end storage call
  var updatedData = updateData(uid, data);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the updated row of data
  return cb(null, updatedData);
});

10.13.4. $fh.sync.handleUpdate for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleUpdate(dataset_id, callback)

Defines a handler function for updating a single row of data from the back end. Should be called after the dataset is initialised.

10.13.4.1. Example

// data source for a dataset.
// The sync service will verify that the update can proceed
// (that is, collision detection) before it invokes the update function.
$fh.sync.handleUpdate(dataset_id, function(dataset_id, uid, data, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Row of data to update
  console.log(data);

  // Sample back-end storage call
  var updatedData = updateData(uid, data);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the updated row of data
  return cb(null, updatedData);
});

10.14. $fh.sync.globalHandleUpdate

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to update a single row of data on the Dataset Backend.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the handleUpdate API.

The sync server makes sure the data can be updated by checking the current value matches the value in the Dataset Backend. If the values do not match, the update operation is not be performed and a collision is generated.

10.14.1. Usage

$fh.sync.globalHandleUpdate(function updateHandler(dataset_id, uid, data, meta_data, cb){});

10.14.2. Parameters

10.14.2.1. updateHandler

  • Description: The function that is invoked when updating a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to update
      • Type: String
    • data

      • Description: the new date fields
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.14.3. Example

$fh.sync.globalHandleUpdate(function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Row of data to update
  console.log(data);

  // Sample back-end storage call
  var updatedData = updateData(uid, data);
  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the updated row of data
  return cb(null, updatedData);
});

10.14.4. $fh.sync.globalHandleUpdate for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleUpdate(callback)

Similar to $fh.sync.handleUpdate, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleUpdate.

10.14.4.1. Example

$fh.sync.globalHandleUpdate(function(dataset_id, uid, data, cb, meta_data){
  //update data for the specified dataset_id and uid
});

10.15. $fh.sync.handleDelete

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to delete a single row of data from the Dataset Backend for a specific Dataset. The sync server makes sure the data can be deleted, that is, the row is up to date and will not cause collisions.

10.15.1. Usage

$fh.sync.handleDelete(dataset_id, function deleteHandler(dataset_id, uid, meta_data, cb){});

10.15.2. Parameters

10.15.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.15.2.2. deleteHandler

  • Description: The function that is invoked when deleting a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to delete
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.15.3. Example

$fh.sync.handleDelete("todo", function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Sample back-end storage call
  var deletedData = deleteData(uid);

  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the deleted row of data
  return cb(null, deletedData);
});

10.15.4. $fh.sync.handleDelete for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleDelete(dataset_id, callback)

Defines a handler function for deleting a single row of data from the back end. Should be called after the dataset is initialised.

10.15.4.1. Example

// data source for a dataset.
// The sync service will verify that the delete can proceed
// (that is, collision detection) before it invokes the delete function.
$fh.sync.handleDelete(dataset_id, function(dataset_id, uid, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Sample back-end storage call
  var deletedData = deleteData(uid);

  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the deleted row of data
  return cb(null, deletedData);
});

10.16. $fh.sync.globalHandleDelete

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to delete a single row of data from the Dataset Backend.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the handleDelete API.

The sync server makes sure the data can be deleted, that is, the row is up to date and will not cause collisions.

10.16.1. Usage

$fh.sync.globalHandleDelete(function deleteHandler(dataset_id, uid, meta_data, cb){});

10.16.2. Parameters

10.16.2.1. deleteHandler

  • Description: The function that is invoked when deleting a record.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • uid

      • Description: the unique id of the record to delete
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.16.3. Example

$fh.sync.globalHandleDelete(function(dataset_id, uid, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique Identifier for row to update
  console.log(uid);

  // Sample back-end storage call
  var deletedData = deleteData(uid);

  /* sample response
    {
      "userid": "1234",
      "name": "Jane Bloggs",
      "age": 27
    }
  */

  // The callback into the sync service to return the deleted row of data
  return cb(null, deletedData);
});

10.16.4. $fh.sync.globalHandleDelete for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleDelete(callback)

Similar to $fh.sync.handleDelete, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleDelete.

10.16.4.1. Example

$fh.sync.globalHandleDelete(function(dataset_id, uid, cb, meta_data){
  //delete data for the specified dataset_id and uid
});

10.17. $fh.sync.handleCollision

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to deal with data collisions for a specific Dataset.

You can resolve the collision in this function, or just persist the collision somewhere for later review.

10.17.1. Usage

$fh.sync.handleCollision(dataset_id, function collisionHandler(dataset_id, hash, timestamp, uid, pre, post, meta_data){});

10.17.2. Parameters

10.17.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.17.2.2. collisionHandler

  • Description: The function that is invoked when a collision is generated.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • hash

      • Description: the unique hash value of the collision
      • Type: String
    • timestamp

      • Description: the timestamp when the change is generated on the client. In milliseconds.
      • Type: Number
    • uid

      • Description: the unique id of the pending record
      • Type: String
    • pre

      • Description: the data before the change
      • Type: Object
    • post

      • Description: the changed data
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object

10.17.3. Example

// Typically a collision handler will write the data record to a collisions table
// which is reviewed by a user who can manually reconcile the collisions.
$fh.sync.handleCollision("todo", function(dataset_id, hash, timestamp, uid, pre, post, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique hash value identifying the collision
  console.log(hash);

  // Date / time that update was created on client device
  console.log(timestamp);

  // Unique Identifier for row
  console.log(uid);

  // The data row the client started with
  console.log(pre);

  //The data row the client tried to write
  console.log(post);

  // sample back-end storage call
  saveCollisionData(dataset_id, hash, timestamp, uid, pre, post);
});

10.17.4. $fh.sync.handleCollision for fh-mbaas-api Version Less than 7.0.0

$fh.sync.handleCollision(dataset_id, callback)

Defines a handler function for dealing with data collisions (that is, stale updates). Should be called after the dataset is initialised.

10.17.4.1. Example

// Typically a collision handler will write the data record to a collisions table
// which is reviewed by a user who can manually reconcile the collisions.
$fh.sync.handleCollision(dataset_id, function(dataset_id, hash, timestamp, uid, pre, post, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique hash value identifying the collision
  console.log(hash);

  // Date / time that update was created on client device
  console.log(timestamp);

  // Unique Identifier for row
  console.log(uid);

  // The data row the client started with
  console.log(pre);

  //The data row the client tried to write
  console.log(post);

  // sample back-end storage call
  saveCollisionData(dataset_id, hash, timestamp, uid, pre, post);
});

10.18. $fh.sync.globalHandleCollision

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to deal with data collisions.

You can resolve the collision in this function, or just persist the collision somewhere for later review.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the handleCollision API.

10.18.1. Usage

$fh.sync.globalHandleCollision(function collisionHandler(dataset_id, hash, timestamp, uid, pre, post, meta_data){});

10.18.2. Parameters

10.18.2.1. collisionHandler

  • Description: The function that is invoked when a collision is generated.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • hash

      • Description: the unique hash value of the collision
      • Type: String
    • timestamp

      • Description: the timestamp when the change is generated on the client. In milliseconds.
      • Type: Number
    • uid

      • Description: the unique id of the pending record
      • Type: String
    • pre

      • Description: the data before the change
      • Type: Object
    • post

      • Description: the changed data
      • Type: Object
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object

10.18.3. Example

// Typically a collision handler will write the data record to a collisions table
// which is reviewed by a user who can manually reconcile the collisions.
$fh.sync.globalHandleCollision(function(dataset_id, hash, timestamp, uid, pre, post, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // Unique hash value identifying the collision
  console.log(hash);

  // Date / time that update was created on client device
  console.log(timestamp);

  // Unique Identifier for row
  console.log(uid);

  // The data row the client started with
  console.log(pre);

  //The data row the client tried to write
  console.log(post);

  // sample back-end storage call
  saveCollisionData(dataset_id, hash, timestamp, uid, pre, post);
});

10.18.4. $fh.sync.globalHandleCollision for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalHandleCollision(callback)

Similar to $fh.sync.handleCollision, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.handleCollision.

10.18.4.1. Example

$fh.sync.globalHandleCollision(function(dataset_id, hash, timestamp, uid, pre, post, meta_data){

});

10.19. $fh.sync.listCollisions

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to return the current list of collisions for a Dataset.

10.19.1. Usage

$fh.sync.listCollisions(dataset_id, function listCollisionsHandler(dataset_id, meta_data, cb){});

10.19.2. Parameters

10.19.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.19.2.2. listCollisionsHandler

  • Description: The function that is invoked when listing collisions.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.19.3. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.listCollisions("todo", function(dataset_id, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  var collisions = getCollisions(dataset_id);
  /* sample response:
  {
    "collision_hash_1" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    }
  }
  */

  // The callback into the sync service to return the list of known collisions
  return cb(null, collisions);
});

10.19.4. $fh.sync.listCollisions for fh-mbaas-api Version Less than 7.0.0

$fh.sync.listCollisions(dataset_id, callback)

Defines a handler function for returning the current list of collisions. Should be called after the dataset is initialised.

10.19.4.1. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.listCollisions(dataset_id, function(dataset_id, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  var collisions = getCollisions(dataset_id);
  /* sample response:
  {
    "collision_hash_1" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    }
  }
  */

  // The callback into the sync service to return the list of known collisions
  return cb(null, collisions);
});
Note

"collision_hash" is the hash value which uniquely identifies a collision. This value will have been passed as the "hash" parameter when the collision was originally created in the "handleCollision" function.

10.20. $fh.sync.globalListCollisions

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to return the current list of collisions.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the listCollisions API.

10.20.1. Usage

$fh.sync.globalListCollisions(function listCollisionsHandler(dataset_id, meta_data, cb){});

10.20.2. Parameters

10.20.2.1. listCollisionsHandler

  • Description: The function that is invoked when listing collisions.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.20.3. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.globalListCollisions(function(dataset_id, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  var collisions = getCollisions(dataset_id);
  /* sample response:
  {
    "collision_hash_1" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    },
    "collision_hash_2" : {
      "uid": "<uid_of_data_row>",
      "timestamp": "<timestamp_value_passed_to_handleCollision_fn>",
      "pre": "<pre_data_record_passed_to_handleCollision_fn>",
      "post": "<post_data_record_passed_to_handleCollision_fn>"
    }
  }
  */

  // The callback into the sync service to return the list of known collisions
  return cb(null, collisions);
});

10.20.4. $fh.sync.globalListCollisions for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalListCollisions(callback)

Similar to $fh.sync.listCollisions, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.listCollisions.

10.20.4.1. Example

$fh.sync.globalListCollisions(function(dataset_id, cb, meta_data){

});

10.21. $fh.sync.removeCollision

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a handler function to delete a collision for a Dataset.

10.21.1. Usage

$fh.sync.removeCollision(dataset_id, function removeCollisionHandler(dataset_id, collision_hash, meta_data, cb){});

10.21.2. Parameters

10.21.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.21.2.2. removeCollisionHandler

  • Description: The function that is invoked when deleting a collisions.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • collision_hash

      • Description: the unique hash of the collision
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.21.3. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.removeCollision("todo", function(dataset_id, collision_hash, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  removeCollision(collision_hash);

  // The callback into the sync service to return the delete row of data
  return cb(null);
});

10.21.4. $fh.sync.removeCollision for fh-mbaas-api Version Less than 7.0.0

$fh.sync.removeCollision(dataset_id, callback)

Defines a handler function for deleting a collision from the collisions list. Should be called after the dataset is initialised.

10.21.4.1. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.removeCollision(dataset_id, function(dataset_id, collision_hash, cb, meta_data) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  removeCollision(collision_hash);

  // The callback into the sync service to return the delete row of data
  return cb(null);
});

10.22. $fh.sync.globalRemoveCollision

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Defines a global handler function to delete a collision.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the removeCollision API.

10.22.1. Usage

$fh.sync.globalRemoveCollision(function removeCollisionHandler(dataset_id, collision_hash, meta_data, cb){});

10.22.2. Parameters

10.22.2.1. removeCollisionHandler

  • Description: The function that is invoked when deleting a collision.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • collision_hash

      • Description: the unique hash of the collision
      • Type: String
    • meta_data

      • Description: the meta data associated with the data, can be null.
      • Type: Object
    • cb

      • Description: the callback function
      • Type: Function

10.22.3. Example

// This would usually be used by an administration console where a user is
// manually reviewing & resolving collisions.
$fh.sync.globalRemoveCollision(function(dataset_id, collision_hash, meta_data, cb) {
  // The dataset identifier that this function was defined for
  console.log(dataset_id);

  // sample back-end storage call
  removeCollision(collision_hash);

  // The callback into the sync service to return the delete row of data
  return cb(null);
});

10.22.4. $fh.sync.globalRemoveCollision for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalRemoveCollision(callback)

Similar to $fh.sync.removeCollision, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.removeCollision.

10.22.4.1. Example

$fh.sync.globalRemoveCollision(function(dataset_id, collision_hash, cb, meta_data){

});

10.23. $fh.sync.interceptRequest

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Intercept the sync requests for a specific Dataset before it is processed. Use this API to check client identities and validating authentication.

10.23.1. Usage

$fh.sync.interceptRequest(dataset_id, function requestInterceptor(dataset_id, interceptorParams, cb){});

10.23.2. Parameters

10.23.2.1. dataset_id

  • Description: the id of the Dataset
  • Type: String

10.23.2.2. requestInterceptor

  • Description: The function that is invoked when a sync request is received from clients.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the Dataset
      • Type: String
    • interceptorParams

      • Description: the parameters associated with the request
      • Type: Object
      • Supported Keys

        • query_params

          • Description: the query parameters associated with the request
          • Type: Object
        • meta_data

          • Description: the meta data associated with the request
          • Type: Object
    • cb

      • Description: the callback function.

        If it is invoked with a non-null response, the sync request is rejected.

      • Type: Function

10.23.3. Example

$fh.sync.interceptRequest("todo", function(dataset_id, interceptorParams, cb){

  var query_params = interceptorParams.query_params; //the query_params specified in the client $fh.sync.manage
  var meta_data = interceptorParams.meta_data;  //the meta_data specified in the client $fh.sync.manage

  var validUser = function(qp, meta){
    //implement user authentication and return true or false
  };

  if(validUser(query_params, meta_data)){
    return cb(null);
  } else {
     // Return a non null response to cause the sync request to fail.
    return cb({error: 'invalid user'});
  }
});

10.23.4. $fh.sync.interceptRequest for fh-mbaas-api Version Less than 7.0.0

$fh.sync.interceptRequest(dataset_id, callback);

Intercept the sync requests for the specified dataset. Can be useful for checking client identities and validating authentication.

10.23.4.1. Example

$fh.sync.interceptRequest(dataset_id, function(dataset_id, interceptorParams, cb){

  var query_params = interceptorParams.query_params; //the query_params specified in the client $fh.sync.manage
  var meta_data = interceptorParams.meta_data;  //the meta_data specified in the client $fh.sync.manage

  var validUser = function(qp, meta){
    //implement user authentication and return true or false
  };

  if(validUser(query_params, meta_data)){
    return cb(null);
  } else {
     // Return a non null response to cause the sync request to fail.
    return cb({error: 'invalid user'});
  }
});

10.24. $fh.sync.setRecordHashFn

Define a function that will generate the hash value of a single record. A record hash is used when comparing a cached record with the latest from the Dataset Backend.

If the hash matches, the records are assumed to be the same (so no need to update the cache or clients). The default implementation takes a conservative approach by doing a sorted stringification of the record, and calculates a sha-1 of it.

However, you may want to override this to save on CPU time.

IMPORTANT Avoid using fields that are updated server-side in your hash calculation. For example, if a Dataset has a lastModified field that is updated at save time on the Dataset Backend, this should be omitted from the hash calculation. Otherwise, a collision is likely to happen with any subsequent update as clients will be unaware of the new value for that field until the data has synced back with the clients.

This function will allow you to override the default implementation.

10.24.1. Usage

$fh.sync.setRecordHashFn(dataset_id, function generateHash(dataset_id, record){});

10.24.2. Parameters

10.24.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.24.2.2. generateHash

  • Description: The function that will be used to generate the hash of a dataset.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • record

      • Description: the record
      • Type: Object

10.24.3. Returns

The hash value of the record.

10.24.4. Example

$fh.sync.setRecordHashFn("todo", function(dataset_id, record){
  return record.lastModified;
});

10.25. $fh.sync.setGlobalHashFn

Define a function that will calculate the global hash of a dataset. The global hash will be used to determine if a dataset has changed or not.

IMPORTANT Avoid using fields that are updated server-side in your hash calculation. For example, if a Dataset has a lastModified field that is updated at save time on the Dataset Backend, this should be omitted from the hash calculation. Otherwise, a collision is likely to happen with any subsequent update as clients will be unaware of the new value for that field until the data has synced back with the clients.

10.25.1. Usage

$fh.sync.setGlobalHashFn(dataset_id, function generateHash(dataRecordHashes){});

10.25.2. Parameters

10.25.2.1. dataset_id

  • Description: the id of the dataset
  • Type: String

10.25.2.2. generateHash

  • Description: The function that will be used to generate the hash of a dataset.
  • Type: Function
  • Invoked Parameters:

    • dataRecordHashes

      • Description: an array of all the hashes of all the records in the dataset.
      • Type: Array

10.25.3. Returns

The global hash value of the dataset.

10.25.4. Example

$fh.sync.setGlobalHashFn("todo", function(dataRecordHashes){
  return dataRecordHashes.join('');
});

10.26. $fh.sync.globalInterceptRequest

NOTE: RHMAP 3.19 includes fh-mbaas-api version 7. If the version of fh-mbaas-api in your package.json file is less than 7.0.0, see the section for the old version

Intercept all sync requests before they are processed. Use this API to check client identities and validating authentication.

It can be used by multiple datasets, but is only used if there is no handler assigned to the dataset using the interceptRequest API.

10.26.1. Usage

$fh.sync.globalInterceptRequest(function requestInterceptor(dataset_id, interceptorParams, cb){});

10.26.2. Parameters

10.26.2.1. requestInterceptor

  • Description: The function that is invoked when a sync request is received from clients.
  • Type: Function
  • Invoked Parameters:

    • dataset_id

      • Description: the id of the dataset
      • Type: String
    • interceptorParams

      • Description: the parameters associated with the request
      • Type: Object
      • Supported Keys

        • query_params

          • Description: the query parameters associated with the request
          • Type: Object
        • meta_data

          • Description: the meta data associated with the request
          • Type: Object
    • cb

      • Description: the callback function.

        If it is invoked with a non-null response, the sync request is rejected.

      • Type: Function

10.26.3. Example

$fh.sync.globalInterceptRequest(function(dataset_id, interceptorParams, cb){

  var query_params = interceptorParams.query_params; //the query_params specified in the client $fh.sync.manage
  var meta_data = interceptorParams.meta_data;  //the meta_data specified in the client $fh.sync.manage

  var validUser = function(qp, meta){
    //implement user authentication and return true or false
  };

  if(validUser(query_params, meta_data)){
    return cb(null);
  } else {
     // Return a non null response to cause the sync request to fail.
    return cb({error: 'invalid user'});
  }
});

10.26.4. $fh.sync.globalInterceptRequest for fh-mbaas-api Version Less than 7.0.0

$fh.sync.globalInterceptRequest(callback)

Similar to $fh.sync.interceptRequest, but set the handler globally which means the same handler function can be used by multiple datasets. The global handler will only be used if there is no handler assigned to the dataset via $fh.sync.interceptRequest.

10.26.4.1. Example

$fh.sync.globalInterceptRequest(function(dataset_id, interceptorParams, cb){

});

10.27. $fh.sync.getEventEmitter

Get the event emitter of the sync server.

If using sync from fh-mbaas-api, it will return the same emitter instance as $fh.events.

10.27.1. Usage

var emitter = $fh.sync.getEventEmitter();

10.27.2. Parameters

None.

10.27.3. Example

var emitter = $fh.sync.getEventEmitter();
emitter.once('sync:ready', function(){
  //do something here
});