diff --git a/README.md b/README.md index d544407..9bb9513 100755 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![CircleCI](https://circleci.com/gh/Streampunk/ledger.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/Streampunk/ledger) # Ledger -Ledger is a [Node.js](http://nodejs.org/) Javascript implementation of the [Advanced Media Workflow Association's](http://www.amwa.tv/) [Networked Media Open Specifications](http://www.nmos.tv/) [discovery and registration APIs](https://github.com/AMWA-TV/nmos-discovery-registration) version 1.0. +Ledger is a [Node.js](http://nodejs.org/) Javascript implementation of the [Advanced Media Workflow Association's](http://www.amwa.tv/) [Networked Media Open Specifications](http://www.nmos.tv/) [discovery and registration APIs](https://github.com/AMWA-TV/nmos-discovery-registration) version 1.0. Currently, this is a fairly complete implementation of the node, registration and query APIs. (Work on the support of the v1.1 changes and the peer-to-peer API is still in progress.) @@ -9,6 +9,8 @@ Currently, this is a fairly complete implementation of the node, registration an Install [Node.js](http://nodejs.org/) for your platform. This software has been developed against the long term stable (LTS) release. +Make sure `git` is installed for your system. This is because the current version of ledger depends on a fork of the [mdns-js](https://github.com/mdns-js/node-mdns-js) library, created by the authors of ledger to fix a bug, rather than the version published to NPM. A pull request is in progress. + Ledger can be run as a standalone registration application and query API or `require`d to use from your own application, such as to create an instance of a Node API to represent local devices. ### Standalone registration @@ -66,47 +68,47 @@ nodeAPI.stop(); ### Node API lifecycle -During the lifetime of the node represented by the Node API, devices, sources, senders, receivers and flows - known as the _resources_ - will need to be added and removed from the node. Do not try to interact with the underlying store directly. The Node API provides methods for non-blocking, safe, serialized access for updating of the store via the `getResource`, `getResources`, `putResource` and `deleteResource` methods. For example: - - +During the lifetime of the node represented by the Node API, devices, sources, senders, receivers and flows - known as the _resources_ - will need to be added and removed from the node. Do not try to interact with the underlying store directly. The Node API provides methods for non-blocking, safe, serialized access for updating of the store via the `getResource`, `getResources`, `putResource` and `deleteResource` methods. For example: + + ```javascript var device = new Device(null, null, "My Device", null, node.id); -nodeAPI.putResource(device).catch(console.error); -nodeAPI.getResource(device.id, 'device', function (err, result) { - if (err) return console.error(err); - assert.deepEqual(result, device); - // ... -}); +nodeAPI.putResource(device).catch(console.error); +nodeAPI.getResource(device.id, 'device', function (err, result) { + if (err) return console.error(err); + assert.deepEqual(result, device); + // ... +}); +``` + +These four resource-related methods work in one of two ways: + +1. If provided with a callback function as the last argument, then the methods follow the standard pattern of the callback functions first argument being an error and the second argument being the successful result. +2. With no callback function, the methods return a [promise](https://www.promisejs.org/) and the result returned can be processed with `.then`, `.done`, `.catch` and `.finally`. + +The order of adding resources is important as referential integrity checks are carried out. For example, the `device_id` property of a source must reference a device that is already stored. + +Updates and reads via the resource methods are sequential in the order in which requests are made to the Node API. For reasons of efficiency, reads via the HTTP REST API rather than the Javascript API do not block and wait for the update. A put request for a resource followed in time with a get request for the same resource should safely retrieve that resource. Other requests to change the store may be interleaved. Here are some further examples: + +```javascript +nodeAPI.putResource(device).catch(console.error); +nodeAPI.putResource(videSource).then(console.log, console.error); +nodeAPI.putResource(videoFlow).catch(console.error); +nodeAPI.getResources('source').then(function (srcs) { + console.log('Current sources are:'); + srcs.map(function (s) { return s.label; }).forEach(console.log); +}); +nodeAPI.deleteResource(videoSource.id, 'source'); +nodeAPI.getResource(videoSource.id, 'source').then(function (onResolved) { + console.error('Video source was not removed as expected.'); +}, function (onRejection) { + console.log('Video source deleted as expected.'); +}); ``` - -These four resource-related methods work in one of two ways: - -1. If provided with a callback function as the last argument, then the methods follow the standard pattern of the callback functions first argument being an error and the second argument being the successful result. -2. With no callback function, the methods return a [promise](https://www.promisejs.org/) and the result returned can be processed with `.then`, `.done`, `.catch` and `.finally`. - -The order of adding resources is important as referential integrity checks are carried out. For example, the `device_id` property of a source must reference a device that is already stored. - -Updates and reads via the resource methods are sequential in the order in which requests are made to the Node API. For reasons of efficiency, reads via the HTTP REST API rather than the Javascript API do not block and wait for the update. A put request for a resource followed in time with a get request for the same resource should safely retrieve that resource. Other requests to change the store may be interleaved. Here are some further examples: - -```javascript -nodeAPI.putResource(device).catch(console.error); -nodeAPI.putResource(videSource).then(console.log, console.error); -nodeAPI.putResource(videoFlow).catch(console.error); -nodeAPI.getResources('source').then(function (srcs) { - console.log('Current sources are:'); - srcs.map(function (s) { return s.label; }).forEach(console.log); -}); -nodeAPI.deleteResource(videoSource.id, 'source'); -nodeAPI.getResource(videoSource.id, 'source').then(function (onResolved) { - console.error('Video source was not removed as expected.'); -}, function (onRejection) { - console.log('Video source deleted as expected.'); -}); -``` - -Reading and updating the _self_ node is achieved using the `getSelf` and `putSelf` methods respectively. - -The previously recommended methods of `getStore` and `setStore` have been deprecated. + +Reading and updating the _self_ node is achieved using the `getSelf` and `putSelf` methods respectively. + +The previously recommended methods of `getStore` and `setStore` have been deprecated. ### Modify events @@ -143,7 +145,7 @@ The API has some features that are not specified in the NMOS documentation. Thes ## Documentation -JsDoc API documentation can be found in the `docs` folder. Details of the APIs are available via the [AMWA NMOS discovery and registration github repository](https://github.com/AMWA-TV/nmos-discovery-registration). +JsDoc API documentation can be found in the `docs` folder. Details of the APIs are available via the [AMWA NMOS discovery and registration github repository](https://github.com/AMWA-TV/nmos-discovery-registration). ## Status, support and further development