Permalink
Browse files

removed updateInterval, upgraded to v2 auth, removed update method, c…

…leaned up docs and example
  • Loading branch information...
1 parent 2e5d79f commit 3e40ca7d8bb22903da4db613aeab9dd56f072f12 @markmahoney markmahoney committed Dec 28, 2011
Showing with 376 additions and 226 deletions.
  1. +53 −52 README.md
  2. +264 −106 bndry/data-source.js
  3. +57 −66 example-volume-graph.js
  4. +2 −2 index.html
View
105 README.md
@@ -1,14 +1,14 @@
# Boundary JavaScript API
-### October Preview
+### December Preview
---
-Note: This documentation represents the current status of the Boundary JavaScript API as of October 28, 2012. While we will make a best effort to maintain compatibility and provide advance notice of API changes, all APIs and output formats described below are subject to change.
+Note: This documentation represents the current status of the Boundary JavaScript API as of December 28, 2011. While we will make a best effort to maintain compatibility and provide advance notice of API changes, all APIs and output formats described below are subject to change.
## Overview
-The Boundary JavaScript API encapsulates the functionality required to authenticate and manage CometD subscriptions to the Boundary Streaming API service. The JavaScript API allows you to retrieve streaming JSON data from various Boundary endpoints, or "data sources," and associate that incoming data with any JavaScript object that implements an "update" method. One common use of this functionality would be to create browser-based visualizations of the traffic data being reported for your organization. It is the basis of Boundary's own visualization front end.
+The Boundary JavaScript API manages authentication and streaming data subscriptions for the Boundary Streaming API service. The API allows you to retrieve streaming updates relating to various aspects of your Boundary-monitored network in JSON format using a set of [predefined queries](https://app.boundary.com/docs#streaming_api). One common use of this functionality would be to create browser-based visualizations of the traffic data being reported for your organization. It is the basis of Boundary's own visualization front end.
## External Requirements
@@ -24,9 +24,9 @@ The following files, supplied in the repository, are required to run the JavaScr
The Boundary JavaScript API itself is comprised of two files:
* **/bndry/auth.js** - stores credentials for subscribing to the Boundary Streaming service
-* **/bndry/data-source.js** - defines the bndry.dataSource object, which is used to create query-specific data sources, which can be subscribed to by other objects
+* **/bndry/data-source.js** - defines the bndry.dataSource object, which is used to create query-specific data sources, which can then be subscribed to
-**NOTE: You will need to edit the auth.js file with your Boundary account information in order to use the JavaScript API.** You can find this information at [https://boundary.com/account](https://boundary.com/account).
+**NOTE: You will need to edit the included auth.js file with your Boundary account information in order to use the JavaScript API.** You can find this information at [https://app.boundary.com/account](https://app.boundary.com/account).
## The Bndry Namespace
@@ -42,68 +42,50 @@ In order for the Boundary JavaScript API to function, the bndry.auth object must
bndry = bndry || {};
bndry.auth = {
cometd: "https://api.boundary.com/streaming",
- user: [user email],
org_id: [org_id string],
- apikey: [api key]
+ apikey: [api key]
};
-In the repo, this is defined in **/bndry/auth.js**. You will need to replace the information in that file with your own account credentials, which may be retrieved from [https://boundary.com/account](https://boundary.com/account).
+In the repo, this is defined in **/bndry/auth.js**. You will need to replace the information in that file with your own account credentials, which may be retrieved from [https://app.boundary.com/account](https://app.boundary.com/account).
## dataSources
-A dataSource object manages the connection to a single query in the Boundary Streaming API, and allows subscriber objects to recieve updates from the dataSource as they arrive from the API. It is defined in the **/bndry/data-source.js** file, which will create the **bndry.dataSource** object. Calling this method will return a new dataSource instance, which other objects may subscribe to:
+A dataSource object manages the connection to a single query in the Boundary Streaming API, and allows subscribers to receive updates from the dataSource as they arrive from the API. It is defined in the **/bndry/data-source.js** file, which will create the **bndry.dataSource** object. Calling the **create** method of this object will return a new dataSource instance, which you may subscribe to:
bndry.dataSource.create(query, [options]) -> dataSource
-The second, optional argument passed to the dataSource **create** method is an object specifying additional configuration parameters:
+The second, optional argument passed to the dataSource **create** method defines additional configuration parameters:
-* **updateInterval** - may be passed to the dataSource method to force the dataSource to return updates at regular intervals, instead of waiting for updates from the server. This is most useful at the 1 second time resolution, to smooth out updates
* **forceConnect** - normally, a dataSource will not poll the streaming API for updates unless it has at least one subscriber. This option forces dataSource to poll the API regardless.
* **subscription** - currently only required to subscribe to annotations, in which case it should be set to 'opaque'.
-To force subscription updates every second, regardless of new data from the API:
-
- var source = bndry.dataSource.create('volume_1s', { updateInterval: 1000 });
-
-To subscribe to annotation updates:
+An annotation query example:
var source = bndry.dataSource.create('annotations', { subscription: 'opaque' });
-For a list of all available queries in the Streaming API, see the Data Sources section of [the Streaming API Documentation](https://boundary.com/docs#streaming_api).
-
-## dataSource subscribers
-
-A dataSource subscriber is any object that has defined an **update** method. Once an object has subscribed to recieve updates from a dataSource, it will begin recieving data objects from the Streaming API via this method.
-
-An example of a subscriber that simply log's Streaming API data:
-
- var logger = {
- update: function (data) {
- console.log(data);
- }
- };
-
-## dataSource updates
-
-The required **update** method recieves updates from the dataSource. If a transformation function has not been paired with this subscriber (discussed in the [addSubscriber](#add-subscriber) section in [dataSource Methods](#data-source-methods)), then the update object will have the following fields:
-
-* **state** - list of all currently tracked samples for the dataSource's query, keyed by a unique field named **\_\_key\_\_**, which is a composite of the sample's other fields concatenated with the ':' character
-* **added** - list of samples added to the state since the last update
-* **removed** - list of samples removed from the state since the last update
+For a list of all available queries in the Streaming API, see the Data Sources section of [the Streaming API Documentation](https://app.boundary.com/docs#streaming_api).
<a id="data-source-methods"></a>
## dataSource Methods
-Once a dataSource instance has been created, any number of subscription objects may subscribe to it for updates, unsubscribe from updates, request the most recent data recieved from the Streaming API, or update their optional transformation functions.
+Once a dataSource instance has been created, any number of subscriber callback functions may be added to receive streaming updates. You may also unsubscribe callback functions from receiving updates, request the most recent update received from the Streaming API, or update the optional transformation function for a particular subscriber.
<a id="add-subscriber"></a>
### addSubscriber
-Registers a subscriber object to start recieving data from the Streaming service. Calling this method returns a subscription identifier, which may be used to update or remove the subscription later.
+Registers a callback function to receive data from the Streaming API service. Calling this method returns a subscription identifier, which may be used to update or remove the subscribed callback later.
+
+ datasource.addSubscriber(subscriber_callback, [transformation]) -> subscription_id
- datasource.addSubscriber(subscriber_object, [transformation]) -> subscription_id
+**subscriber_callback** is a function that receives a single argument, an object containing updates to the current recordset for your query, as well as the overall state of the query itself. See [dataSource Updates](#data-source-updates) for more information.
-An optional **transformation** function may be provided to process the data before it is handed off to the subscriber's **update** method. The transformation function is any function that takes a data object and a callback as input, and passes it's processed data to the supplied callback method when it is finished. This allows for potentially asynchronous data processing, such as using web workers.
+ var datasource = bndry.dataSource.create('volume_1s');
+
+ datasource.addSubscriber(function (data) {
+ console.log(data);
+ });
+
+An optional **transformation** function may be provided to process the data before it is handed off to the subscriber callback. The transformation function is any function that takes the Streaming API update argument and a callback as input, and hands off it's processed update argument to the supplied callback method when it is finished. This callback method allows asynchronous processing of large amounts of Streaming API data, for instance with web workers.
var transformation = function (data, callback) {
var transformed_data = {};
@@ -113,36 +95,55 @@ An optional **transformation** function may be provided to process the data befo
callback(transformed_data);
}
-The **addSubscriber** method returns a subscription identifier, which may be used to unsubscribe the object from it's dataSource at any time.
+The **addSubscriber** method returns a subscription identifier, which may be used to unsubscribe the **subscriber_callback** function from it's dataSource at any time.
-Example: subscribing to a total volume per second stream, with an optional forced update interval of one second:
+Example: subscribing to updates from a total volume per second stream:
- var source = bndry.dataSource.create('volume_1s', { updateInterval: 1000 });
- var logger = {
- update: function (data) {
- console.log(data);
- }
+ var source = bndry.dataSource.create('volume_1s');
+
+ function logger(data) {
+ console.log(data);
};
+
var subscription = source.addSubscriber(logger);
### updateTransformation
-Updates the transformation function associated with a particular subscriber.
+Updates the optional transformation function associated with a particular subscription.
datasource.updateTransformation(subscription_id, transform_function)
Calling this method will immediately update the subscriber associated with this subscription_id, using the new transformation function.
### removeSubscriber
-Decouples a subscription object from a dataSource.
+Decouples a subscriber from a dataSource.
datasource.removeSubscriber(subscription_id)
-Onced called, the subscription object associated with that subscription_id will no long recieve updates from the dataSource instance.
+Once called, the subscriber associated with that subscription_id will no long receive updates from the dataSource instance.
### lastUpdate
Returns the last data object sent to all subscribers.
- datasource.lastUpdate() -> unprocessed data object
+ datasource.lastUpdate() -> unprocessed data object
+
+<a id="data-source-updates"></a>
+## dataSource updates
+
+If a transformation function has not been paired with your subscription (discussed in the [addSubscriber](#add-subscriber) section in [dataSource Methods](#data-source-methods)), then the update objects received by the subscriber_callback function will contain the following fields:
+
+* **state** - list of all currently tracked samples for the dataSource's query, keyed by a unique field named **\_\_key\_\_**, which is a composite of the sample's other fields concatenated with the ':' character
+* **added** - list of records added to the state since the last update
+* **removed** - list of records removed from the state since the last update
+
+---
+
+### Recent updates to the Boundary Javascript API:
+December 28, 2011:
+
+* Removed optional update interval smoothing from dataSource creation
+* Updated bndry.auth object to V2 authentication (if you've previously been using the Boundary Javascript API files, you may want to check [https://app.boundary.com/account](https://app.boundary.com/account) to see if your api key has changed)
+* dataSource subscribers are no longer objects with update methods, but are now simply callback functions
+* the included example js file has been simplified to better illustrate baseline usage
Oops, something went wrong.

0 comments on commit 3e40ca7

Please sign in to comment.