Class: DataService

DataService

new DataService()

Provides data objects and manages changes to them. Data service subclasses that implement their own constructor should call this class' constructor at the beginning of their constructor implementation with code like the following: DataService.call(this); Currently only one service tree with one root services is supported, and every instance of DataService or a DataService subclasses must either be that root service or be set as a descendent of that root service.
Source:

Extends

  • external:Montage

Members

(static) mainService :DataService

A reference to the application's main service. Applications typically have one and only one root service to which all data requests are sent, and this is called the application's main service. That service can in turn delegate handling of different types of data to child services specialized by type. This property will be set automatically if the DataService constructor is called and if the first service created is either the main service or a descendent of the main service.
Type:
Source:

addMappingForType

Adds a mapping to the service for the specified type.
Source:

authorization :Object

holds authorization object after a successfull authorization
Type:
  • Object
Source:

authorizationPanel :string

Module ID of the panel component used to gather necessary authorization information
Type:
  • string
Source:

authorizationPolicy :AuthorizationPolicyType

Returns the AuthorizationPolicyType used by this DataService.
Type:
  • AuthorizationPolicyType
Source:

authorizationServices :Array.<string>

Returns the list of moduleIds of DataServices a service accepts to provide authorization on its behalf. If an array has multiple authorizationServices, the final choice will be up to the App user regarding which one to use. This array is expected to return moduleIds, not objects, allowing the AuthorizationManager to manage unicity
Type:
  • Array.<string>
Source:

changedDataObjects :Set.<Object>

A set of the data objects managed by this service or any other descendent of this service's root service that have been changed since that root service's data was last saved, or since the root service was created if that service's data hasn't been saved yet Since root services are responsible for tracking data objects, subclasses whose instances will not be root services should override this property to return their root service's value for it.
Type:
  • Set.<Object>
Source:

childServices :Set.<DataService>

The child services of this service. This value is modified by calls to addChildService() and removeChildService() and must not be modified directly.
Type:
Source:

createdDataObjects :Set.<Object>

A set of the data objects created by this service or any other descendent of this service's root service since that root service's data was last saved, or since the root service was created if that service's data hasn't been saved yet. Since root services are responsible for tracking data objects, subclasses whose instances will not be root services should override this property to return their root service's value for it.
Type:
  • Set.<Object>
Source:

dataMaxAge :Number

The maximum amount of time a DataService's data will be considered fresh. ObjectDescriptor's maxAge should take precedence over this and a DataStream's dataMaxAge should take precedence over a DataService's dataMaxAge global default value.
Type:
  • Number
Source:

emptyArrayPromise

Source:
To Do:
  • Document.

eventLoopPromise :external:Promise

A possibly shared promise resolved in the next cycle of the event loop or soon thereafter, at which point the current event handling will be complete. This is useful for services that need to buffer up actions so they're committed only once in a given event loop.
Type:
  • external:Promise
Source:

isOffline :boolean

Returns a value derived from and continuously updated with the value of navigator.onLine. Root services are responsible for tracking offline status, and subclasses not designed to be root services should override this property to get its value from their root service.
Type:
  • boolean
Source:

isRootService :Boolean

Convenience method to assess if a dataService is the rootService
Type:
  • Boolean
Source:

mappings :Array.<DataMapping>

The data mappings used by this service to convert objects to raw data and vice-versa.
Type:
Source:

mappingWithType

Return the mapping to use for the specified type.
Source:

model

The model that this service supports. If the model is defined the service supports all the object descriptors contained within the model.
Source:

nullFunction :function

A function that does nothing but returns null, useful for terminating a promise chain that needs to return null, as in the following code: var self = this; return this.fetchSomethingAsynchronously().then(function (data) { return self.doSomethingAsynchronously(data.part); }).then(this.nullFunction);
Type:
  • function
Source:

nullPromise :external:Promise

A shared promise resolved with a value of `null`, useful for returning from methods like fetchObjectProperty() when the requested data is already there.
Type:
  • external:Promise
Source:

objectDescriptorForObject

Returns an object descriptor for the provided object. If this service does not have an object descriptor for this object it will ask its parent for one.
Source:

(nullable) parentService :DataService

A read-only reference to the parent of this service. This value is modified by calls to addChildService() and removeChildService() and cannot be modified directly. Data services that have no parents are called root services.
Type:
Source:

providesAuthorization :boolean

Indicates whether a service can provide user-level authorization to its data. Defaults to false. Concrete services need to override this as needed.
Type:
  • boolean
Source:

rootService :DataService

Convenience read-only reference to the root of the service tree containing this service. Most applications have only one root service, the application's main service.
Type:
Source:

types :Array.<DataObjectDescriptor>

The types of data handled by this service. If this `undefined`, `null`, or an empty array this service is assumed to handled all types of data. The default implementation of this property returns the union of all types handled by child services of this service. Subclasses without child services should override this to directly return an array of the specific types they handle. Applications typically have one raw data service service for each set of related data types and one main service which is the parent of all those other services and delegates work to them based on the type of data to which the work applies. It is possible for child data services to have children of their own and delegate some or all of their work to them. A service's types must not be changed after it is added as a child of another service.
Type:
Source:

Methods

addChildService(service, typesopt)

Adds a raw data service as a child of this data service and set it to handle data of the types defined by its types property. Child services must have their types property value or their model set before they are passed in to this method, and that value cannot change after that. The model property takes priority of the types property. If the model is defined the service will handle all the object descriptors associated to the model.
Parameters:
Name Type Attributes Description
service RawDataService
types Array <optional>
Types to use instead of the child's types.
Source:

authorize()

Source:
Returns:
Promise

cancelDataStream(dataStreamopt, reasonopt)

To be called to indicates that the consumer has lost interest in the passed DataStream. This will allow the RawDataService feeding the stream to take appropriate measures.
Parameters:
Name Type Attributes Description
dataStream DataStream <optional>
The DataStream to cancel
reason Object <optional>
An object indicating the reason to cancel.
Source:

createDataObject(type) → {Object}

Create a new data object of the specified type. Since root services are responsible for tracking and creating data objects, subclasses whose instances will not be root services should override this method to call their root service's implementation of it.
Parameters:
Name Type Description
type DataObjectDescriptor The type of object to create.
Source:
Returns:
- The created object.
Type
Object

dataIdentifierForObject(object) → {DataIdentifier}

Returns a unique object for a DataIdentifier fetchObjectProperty() instead of this method. That method will be called by this method when needed.
Parameters:
Name Type Description
object object The object whose property values are being requested.
Source:
Returns:
- An object's DataIdentifier
Type
DataIdentifier

decacheObjectProperties()

Since root services are responsible for triggering data objects fetches, subclasses whose instances will not be root services should override this method to call their root service's implementation of it.
Source:
To Do:
  • Rename and document API and implementation.

deleteDataObject(object) → {external:Promise}

Delete a data object.
Parameters:
Name Type Description
object Object The object whose data should be deleted.
Source:
Returns:
- A promise fulfilled when the object has been deleted.
Type
external:Promise

deleteOfflineOperations(operations) → {Promise}

Delete operations recorded while offline. Services overriding the (plural) performOfflineOperations() method must invoke this method after each operation they perform is successfully performed. This method will be called automatically for services that perform operations by implementing a performOfflineOperation() or `performFooOfflineOperation()` methods (where `foo` is an operation data type). Subclasses that provide offline operations support must override this method to delete the specified offline operations from their records.
Parameters:
Name Type Description
operations Array.<Object>
Source:
Returns:
- A promise fulfilled with a null value when the operations have been deleted.
Type
Promise

fetchData(queryOrType, optionalCriterianullable, optionalStreamnullable) → (nullable) {DataStream}

Fetch data from the service using its child services. This method accept types as alternatives to queries, and its [stream]{DataStream} argument is optional, but when it calls its child services it will provide them with a query, it provide them with a [stream]{DataStream}, creating one if necessary, and the stream will include a reference to the query. Also, if a child service's implementation of this method return `undefined` or `null`, this method will return the stream passed in to the call to that child. The requested data may be fetched asynchronously, in which case the data stream will be returned immediately but the stream's data will be added to the stream at a later time.
Parameters:
Name Type Attributes Description
queryOrType DataQuery | DataObjectDescriptor | ObjectDescriptor | function | String If this argument's value is a query it will define what type of data should be returned and what criteria that data should satisfy. If the value is a type it will only define what type of data should be returned, and the criteria that data should satisfy can be defined using the `criteria` argument. A type is defined as either a DataObjectDesc- riptor, an Object Descriptor, a Construct- or the string module id. The method will convert the passed in type to a Data- ObjectDescriptor (deprecated) or an ObjectDescriptor. This is true whether passing in a DataQuery or a type.
optionalCriteria Object <nullable>
If the first argument's value is a type this argument can optionally be provided to defines the criteria which the returned data should satisfy. If the first argument's value is a query this argument should be omitted and will be ignored if it is provided.
optionalStream DataStream <nullable>
The stream to which the provided data should be added. If no stream is provided a stream will be created and returned by this method.
Source:
Returns:
- The stream to which the fetched data objects were or will be added, whether this stream was provided to or created by this method.
Type
DataStream

fetchObjectProperty(object, name) → {external:Promise}

Fetch the value of a data object's property, possibly asynchronously. The default implementation of this method delegates the fetching to a child services, or does nothing but return a fulfilled promise for `null` if no child service can be found to handle the specified object. Raw data service subclasses should override this method to perform any fetch or other operation required to get the requested data. The subclass implementations of this method should use only fetchData() calls to fetch data. This method should never be called directly: getObjectProperties() or updateObjectProperties() should be called instead as those methods handles some required caching, fetch aggregation, and data trigger. Those methods will call this method if and when that is necessary. Like the promise returned by getObjectProperties(), the promise returned by this method should not pass the requested value to its callback: That value must instead be set on the object passed in to this method.
Parameters:
Name Type Description
object object The object whose property value is being requested.
name string The name of the single property whose value is being requested.
Source:
Returns:
- A promise fulfilled when the requested value has been received and set on the specified property of the passed in object.
Type
external:Promise

getDataObject(type, data, context) → {Object}

Find an existing data object corresponding to the specified raw data, or if no such object exists, create one. Since root services are responsible for tracking and creating data objects, subclasses whose instances will not be root services should override this method to call their root service's implementation of it.
Parameters:
Name Type Description
type DataObjectDescriptor The type of object to find or create.
data Object An object whose property values hold the object's raw data. That data will be used to determine the object's unique identifier.
context ? A value, usually passed in to a raw data service's addRawData() method, that can help in getting or creating the object.
Source:
Returns:
- The existing object with the unique identifier specified in the raw data, or if no such object exists a newly created object of the specified type.
Type
Object

getObjectProperties(object, propertyNames) → {external:Promise}

Request possibly asynchronous values of a data object's properties. These values will only be fetched if necessary and only the first time they are requested. To force an update of a value that was previously obtained or set, use updateObjectProperties() instead of this method. Since root services are responsible for determining when to fetch or update data objects values, subclasses whose instances will not be root services should override this method to call their root service's implementation of it. Subclasses should define how property values are obtained by overriding fetchObjectProperty() instead of this method. That method will be called by this method when needed. Although this method returns a promise, the requested data will not be passed in to the promise's callback. Instead that callback will received a `null` value and the requested values will be set on the specified properties of the object passed in. Those values can be accessed there when the returned promise is fulfilled, as in the following code: myService.getObjectProperties(myObject, "x", "y").then(function () { someFunction(myObject.x, myObject.y); }
Parameters:
Name Type Description
object object The object whose property values are being requested.
propertyNames Array.<string> The names of each of the properties whose values are being requested. These can be provided as an array of strings or as a list of string arguments following the object argument.
Source:
Returns:
- A promise fulfilled when all of the requested data has been received and set on the specified properties of the passed in object.
Type
external:Promise

logOut()

Source:
Returns:
Promise

objectForDataIdentifier(object) → {DataIdentifier}

Returns a unique object for a DataIdentifier fetchObjectProperty() instead of this method. That method will be called by this method when needed.
Parameters:
Name Type Description
object object object
Source:
Returns:
- object's DataIdentifier
Type
DataIdentifier

performOfflineOperation(operation) → {Promise}

Called from performOfflineOperations() to perform a particular operation when no more specific `performFooOfflineOperation()` method is available for that operation, where `Foo` is the operation's data type. The default implementation does nothing. Subclass overriding this method do not need to delete the passed in operation after it has successfully been performed: The method calling this method will take care of that.
Parameters:
Name Type Description
operation DataOperation
Source:
Returns:
- A promise fulfilled with a null value when the operation has been performed, or rejected if a problem occured that should prevent following operations from being performed.
Type
Promise

performOfflineOperations() → {Promise}

Perform operations recorded while offline. This will be invoked when the service comes online after being offline. The default implementation delegates performance of each operation to the child service responsible for that operation, as determined by readOfflineOperations(). It will batch operations if several consecutive operations belong to the same child service. For each operation not handled by a child service, the default implementation calls a method named `performFooOfflineOperation()`, if such a method exists in this service where `foo` is the operation's data type. If no such method exists, readOfflineOperation() is called instead. Subclasses that provide offline support should implement these `performFooOfflineOperation()` methods or override the `readOfflineOperation()` method to perform each operation, or they can override this `performOfflineOperations()` method instead. Subclass overriding this method are responsible for deleting operations after they have been performed. Subclasses implementing `performFooOfflineOperation()` methods or overriding the `readOfflineOperation()` method are not.
Parameters:
Type Description
Array.<DataOperation> operations
Source:
Returns:
- A promise fulfilled with a null value when the operations have been performed, or rejected if a problem occured that should prevent following operations from being performed.
Type
Promise

readOfflineOperations()

Reads all the offline operations recorded on behalf of this service. The default implementation aggregates this service children's offline operations, keeping track of which child service is responsible for each operation. Subclasses that provide offline support should override this method to return the operations that have been performed while offline.
Source:

recordDataIdentifierForObject(object, dataIdentifier)

Records an object's DataIdentifier
Parameters:
Name Type Description
object object an Object.
dataIdentifier DataIdentifier The object whose property values are
Source:

recordObjectForDataIdentifier(dataIdentifier, object)

Records an object's DataIdentifier
Parameters:
Name Type Description
dataIdentifier DataIdentifier DataIdentifier
object object object represented by dataIdentifier
Source:

registerChildService(child) → {Promise}

Alternative to addChildService(). While addChildService is synchronous, registerChildService is asynchronous and may take a child whose types property is a promise instead of an array. This is useful for example if the child service does not know its types immediately, e.g. if it must fetch them from a .mjson descriptors file. If the child's types is an array, it is guaranteed to behave exactly like addChildService.
Parameters:
Name Type Description
child DataService service to add to this service.
Promise | ObjectDescriptor | Array.<ObjectDescriptor>
Source:
Returns:
Type
Promise

removeChildService(service, typesopt)

Remove a raw data service as a child of this service and clear its parent if that service is a child of this service. The performance of this method is O(m) + O(n), where m is the number of children of this service handling the same type as the child service to remove and n is the number of types handled by all children of this service.
Parameters:
Name Type Attributes Description
service RawDataService
types Array <optional>
Types to use instead of the child's types.
Source:

removeDataIdentifierForObject(object)

Remove an object's DataIdentifier
Parameters:
Name Type Description
object object an object
Source:

removeObjectForDataIdentifier(object)

Remove an object's DataIdentifier
Parameters:
Name Type Description
object object an object
Source:

saveDataObject(object) → {external:Promise}

Save changes made to a data object.
Parameters:
Name Type Description
object Object The object whose data should be saved.
Source:
Returns:
- A promise fulfilled when all of the data in the changed object has been saved.
Type
external:Promise

spliceWithArray(array, insert, index, length)

Splice an array into another array.
Parameters:
Name Type Description
array Array The array to modify.
insert Array The items to splice into that array.
index number The index at which to splice those items, by default `0`.
length number The number of items of the original array to replace with items from the spliced array, by default `array.length`.
Source:

unregisterChildService() → {Promise}

Alternative to removeChildService(). While removeChildService is synchronous, unregisterChildService is asynchronous and may take a child whose types property is a promise instead of an array. This is useful for example if the child service does not know its types immediately, e.g. if it must fetch them from a .mjson descriptors file. If the child's types is an array, it is guaranteed to behave exactly like removeChildService.
Source:
Returns:
Type
Promise

updateObjectProperties(object, propertyNames) → {external:Promise}

Request possibly asynchronous values of a data object's properties, forcing asynchronous values to be re-fetched and updated even if they had previously been fetched or set. Except for the forced update, this method behaves exactly like getObjectProperties(). Since root services are responsible for determining when to fetch or update data objects values, subclasses whose instances will not be root services should override this method to call their root service's implementation of it. Subclasses should define how property values are obtained by overriding fetchObjectProperty() instead of this method. That method will be called by this method when needed.
Parameters:
Name Type Description
object object The object whose property values are being requested.
propertyNames Array.<string> The names of each of the properties whose values are being requested. These can be provided as an array of strings or as a list of string arguments following the object argument.
Source:
Returns:
- A promise fulfilled when all of the requested data has been received and set on the specified properties of the passed in object.
Type
external:Promise