# Class: DataStream

## DataStream

#### new DataStream()

A DataProvider whose data is received sequentially. A DataStream is also a `promise` which is fulfilled when all the data it expects has been received. Objects receiving data from a stream will use its data property to access that data. Alternatively they can use its then() method to get that data or to handle errors, or its catch() method to handle errors. Objects feeding data to a stream will use its addData() method to add that data and its dataDone() method to indicate that all available data has been added or its dataError() method to indicate an error occurred. Objects can either receive data from a stream or add data to it, but not both. Additionally, only one object can ever add data to a particular stream. Typically that object will be a Service. Each stream is also a `promise` that becomes fulfilled when all the data expected for it is first received and dataDone() is called, or rejected when an error is first encountered and dataError() is called. Each such promise is fulfilled or rejected only once and will not be fulfilled or rejected again if the stream's data changes or if an error is encountered subsequently for any reason.

Source:
  - data/service/data-stream.js, line 44

### Extends

- DataProvider

### Members

#### (static) withTypeOrSelector

Source:
  - data/service/data-stream.js, line 352
To Do:
  - Document.

#### _dataMaxAge :Number

The maximum amount of time a DataStream's data will be considered fresh. This should take precedence over an ObjectDescriptor's maxAge which should take precedence over a DataService's dataMaxAge global default value.

##### Type:

- Number

Source:
  - data/service/data-stream.js, line 330

#### data :Array

The objects that have been added to the stream, as defined in this class' DataProvider superclass. This array is created lazilly the first time it is needed and then not allowed to change, though its contents can and typically will change.

##### Type:

- Array

Overrides:
  - DataProvider#data
Source:
  - data/service/data-stream.js, line 84

#### dataReceptionTime :Date

The time at which data was received by the DataStream

##### Type:

- Date

Source:
  - data/service/data-stream.js, line 319

#### query :DataQuery

The query defining the data returned in this stream.

##### Type:

- DataQuery

Source:
  - data/service/data-stream.js, line 55

#### selector :DataQuery

The selector defining the data returned in this stream.

##### Type:

- DataQuery

Source:
  - data/service/data-stream.js, line 64

### Methods

#### addData(objects)

Add some object to the stream's data array.

##### Parameters:

Name | Type | Description
--- | --- | ---
`objects` | Array | An array of objects to add to the stream's data. If this array is empty, `null`, or `undefined`, no objects are added.

Source:
  - data/service/data-stream.js, line 236

#### catch(onRejected)

Method of the `Promise` class used to kick off additional processing when an error has been encountered.

##### Parameters:

Name | Type | Description
--- | --- | ---
`onRejected` | OnRejected | Called when the stream's dataError() method is called, usually after an error is encountered while fetching data for the stream. The value passed in to this callback will be the `reason` received by the stream's dataError() method.

Source:
  - data/service/data-stream.js, line 218

#### dataDone()

To be called when all the data expected by this stream has been added to its data array. After this is called all subsequent calls to dataDone() or dataError() will be ignored.

Source:
  - data/service/data-stream.js, line 260

#### dataError(reasonopt)

To be called when a problem is encountered while trying to fetch data for this stream. After this is called all subsequent calls to dataError() or dataDone() will be ignored.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`reason` | Object | <optional> | An object, usually an Error, indicating what caused the problem. This will be passed in to any external:onRejected callback specified in then() or catch() calls to the stream.

Source:
  - data/service/data-stream.js, line 284

#### requestData(start, length)

Request specific data, as defined in this class' DataProvider superclass. Calling this method has no effect as data will come in the order in which it is added to the stream and this order cannot be changed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`start` | int | See superclass.
`length` | int | See superclass.

Overrides:
  - DataProvider#requestData
Source:
  - data/service/data-stream.js, line 103

#### then(onFulfilled, onRejectedopt)

Method of the `Promise` class used to kick off additional processing when all the data expected by this stream has been received or when an error has been encountered.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---

`onFulfilled`

OnFulfilled

Called when the stream's dataDone() method is called, usually after all the data expected for the stream has been sent to it. Because a stream's selector can change after that, or changes in the service data can occur for other reasons, it is possible for a stream's data array contents to change after this callback is called. If that happens this callback will not be called again. This callback therefore only provides an indication of when the first set of data expected by a stream is received. The value passed in to this callback is the stream's DataStream#data.

`onRejected`

OnRejected

<optional>

Called when the stream's dataError() method is called, usually after an error is encountered while fetching data for the stream. The value passed in to this callback will be the `reason` received by the stream's dataError() method. Because catch() also handles the case where exceptions are encountered in the `onFulfilled` callback, this argument is usually not provided and catch() is usually used instead to specify the `onRejected` callback.

Source:
  - data/service/data-stream.js, line 196