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:
Extends
Members
(static) withTypeOrSelector
- Source:
- 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 :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:
- Source:
dataReceptionTime :Date
The time at which data was received by the DataStream
Type:
- Date
- Source:
query :DataQuery
The query defining the data returned in this stream.
Type:
- Source:
selector :DataQuery
The selector defining the data returned in this stream.
Type:
- Source:
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:
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:
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:
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:
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:
- Source:
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: