# Class: PersistentDataService

## PersistentDataService

#### new PersistentDataService()

TODO: Document !!!!!THIS IS A WORK IN PROGRESS generalizing OfflineService, so code started from that and is evolving from there.

Source:
  - data/service/persistent-data-service.js, line 23

### Extends

- RawDataService

### Members

#### _persistingObjectDescriptorNames

returns the set of all ObjectDescriptors names that should persist.

Source:
  - data/service/persistent-data-service.js, line 286

#### _storage

returns a Promise that resolves to the object used by the service to store data. This is meant to be an abstraction of the "Database"

Source:
  - data/service/persistent-data-service.js, line 66

#### addMappingForType

Adds a mapping to the service for the specified type.

Inherited From:
  - DataService#addMappingForType
Source:
  - data/service/data-service.js, line 687

#### authorization :Object

holds authorization object after a successfull authorization

##### Type:

- Object

Inherited From:
  - DataService#authorization
Source:
  - data/service/data-service.js, line 799

#### authorizationPanel :string

Module ID of the panel component used to gather necessary authorization information

##### Type:

- string

Inherited From:
  - DataService#authorizationPanel
Source:
  - data/service/data-service.js, line 824

#### authorizationPolicy :AuthorizationPolicyType

Returns the AuthorizationPolicyType used by this DataService.

##### Type:

- AuthorizationPolicyType

Inherited From:
  - DataService#authorizationPolicy
Source:
  - data/service/data-service.js, line 789

#### 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>

Inherited From:
  - DataService#authorizationServices
Source:
  - data/service/data-service.js, line 816

#### 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>

Inherited From:
  - DataService#changedDataObjects
Source:
  - data/service/data-service.js, line 1646

#### changesPropertyName

name of the schema property that stores the changes made to the object in this operation

Source:
  - data/service/persistent-data-service.js, line 167

#### 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:

- Set.<DataService>

Inherited From:
  - DataService#childServices
Source:
  - data/service/data-service.js, line 209

#### contextPropertyName

name of the schema property that stores unstructured/custom data for a service to stash what it may need for further use.

Source:
  - data/service/persistent-data-service.js, line 186

#### 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>

Inherited From:
  - DataService#createdDataObjects
Source:
  - data/service/data-service.js, line 1620

#### databaseByModel

Returns the WeakMap keeping track of the storage objects used for objectDescriptors

Source:
  - data/service/persistent-data-service.js, line 370

#### databaseForModel

Benoit: 8/8/2017. We are going to use a single database for an App model-group. If a persistent service is used for a single model, no pbm, to workaround possible name conflicts in ObjectDescriptors coming from different packages, we'll use the full moduleId of these ObjectDescriptors to name object stores / tables avoid name conflicts. Even if different databases end up being used, this choice will work as well. This API allows for one subclass to decide to use differrent databases for storing different ObjectDescriptors, or a subclass can decide to use only one. Returns a Promise for the persistence storage used to store objects described by the objectDescriptor passed as an argument. may need to introduce an _method used internally to minimize use of super()

Source:
  - data/service/persistent-data-service.js, line 404

#### dataIDPropertyName

name of the schema property that stores the primary key of the object the operation impacts

Source:
  - data/service/persistent-data-service.js, line 176

#### 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

Inherited From:
  - DataService#dataMaxAge
Source:
  - data/service/data-service.js, line 753

#### emptyArrayPromise

Inherited From:
  - DataService#emptyArrayPromise
Source:
  - data/service/data-service.js, line 2415
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

Inherited From:
  - DataService#eventLoopPromise
Source:
  - data/service/data-service.js, line 2436

#### initWithModel

Inherited From:
  - RawDataService#initWithModel
Deprecated:
  - Yes
Source:
  - data/service/raw-data-service.js, line 46

#### 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

Inherited From:
  - DataService#isOffline
Source:
  - data/service/data-service.js, line 2033

#### isRootService :Boolean

Convenience method to assess if a dataService is the rootService

##### Type:

- Boolean

Inherited From:
  - DataService#isRootService
Source:
  - data/service/data-service.js, line 193

#### lastFetchedPropertyName

name of the schema property that stores the last time the operation's object (dataID) was last fetched.

Source:
  - data/service/persistent-data-service.js, line 129

#### lastModifiedPropertyName

name of the schema property that stores the last time the operation's object was last modified.

Source:
  - data/service/persistent-data-service.js, line 139

#### mappings :Array.<DataMapping>

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

##### Type:

- Array.<DataMapping>

Inherited From:
  - DataService#mappings
Source:
  - data/service/data-service.js, line 131

#### mappingWithType

Return the mapping to use for the specified type.

Inherited From:
  - DataService#mappingWithType
Source:
  - data/service/data-service.js, line 699

#### model

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

Inherited From:
  - DataService#model
Source:
  - data/service/data-service.js, line 742

#### 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

Inherited From:
  - DataService#nullFunction
Source:
  - data/service/data-service.js, line 2385

#### 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

Inherited From:
  - DataService#nullPromise
Source:
  - data/service/data-service.js, line 2399

#### 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.

Inherited From:
  - DataService#objectDescriptorForObject
Source:
  - data/service/data-service.js, line 876

#### offlineService :OfflineService

##### Type:

- OfflineService

Inherited From:
  - RawDataService#offlineService
Deprecated:
  - Yes
Source:
  - data/service/raw-data-service.js, line 1157
To Do:
  - Remove any dependency and delete.

#### operationPropertyName

name of the schema property that stores the type of operation: This will be create or update or delete

Source:
  - data/service/persistent-data-service.js, line 149

#### operationTableName

table/property/index name that tracks the date the record was last updated

Source:
  - data/service/persistent-data-service.js, line 110

#### (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:

- DataService

Inherited From:
  - DataService#parentService
Source:
  - data/service/data-service.js, line 154

#### persistentPropertyDescriptors

returns the list of all property descriptors that should persist for the objectDescriptor passed as an argument. By default, return all propertyDescriptors. This can be customized and configured when a PersistentDataService is instanciated.

Source:
  - data/service/persistent-data-service.js, line 326

#### persistsObjectDescriptor

returns true or false depending on wether PersistentDataService has been instructed to persist the objectDescriptor passed as an argument.

Source:
  - data/service/persistent-data-service.js, line 305

#### 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

Inherited From:
  - DataService#providesAuthorization
Source:
  - data/service/data-service.js, line 835

#### provideStorageForObjectDescriptor

Returns a Promise for the persistence storage used to store objects described by the objectDescriptor passed as an argument. may need to introduce an _method used internally to minimize use of super()

Source:
  - data/service/indexed-d-b-data-service.js, line 102

#### 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:

- DataService

Inherited From:
  - DataService#rootService
Source:
  - data/service/data-service.js, line 181

#### storageByObjectDescriptor

Returns the WeakMap keeping track of the storage objects used for objectDescriptors

Source:
  - data/service/persistent-data-service.js, line 434

#### storageForObjectDescriptor

Returns a Promise for the persistence storage used to store objects described by the objectDescriptor passed as an argument. Benoit: 8/8/2017: Ideally we want to create these storage lazily, on-demand. may need to introduce an _method used internally to minimize use of super()

Source:
  - data/service/persistent-data-service.js, line 462

#### storageForQuery

This is the opportunity for a PersistentDataService to lazily create the storage needed to execute this query, or to optimize it if it turns out indexes don't exist for optimally execute a passed query. This could also be lazily and on frequency of request being used, as well as time spent executing it without. Traversing the query's criteria's syntactic tree and looking up property descriptors' valueDescriptors to navigate the set of persistentStorage needed and make sure they exit before attempting to fetch from it.

Source:
  - data/service/persistent-data-service.js, line 342

#### typePropertyName

name of the schema property that stores the name of the type/object store of the object the operation impacts

Source:
  - data/service/persistent-data-service.js, line 119

#### 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:

- Array.<DataObjectDescriptor>

Inherited From:
  - DataService#types
Source:
  - data/service/data-service.js, line 118

### Methods

#### _fetchRawData(stream)

Fetch the raw data of this service. This method should not be called directly from anyone other than this service's fetchData(). Subclasses that don't override fetchData() should override this method to: 1. Fetch the raw records needed to generate the requested data object. 2. Add those records to the specified stream with calls to addRawData(). 3. Indicate that the fetching is done with a call to rawDataDone(). This method must be asynchronous and return as soon as possible even if it takes a while to obtain the raw data. The raw data can be provided to the service at any point after this method is called, even after it returns, with calls to addRawData() and rawDataDone(). The default implementation of this method simply calls rawDataDone() immediately.

##### Parameters:

Name | Type | Description
--- | --- | ---
`stream` | DataStream | The stream to which the data objects corresponding to the raw data should be added. This stream must contain a reference to the selector defining what raw data to fetch.

Inherited From:
  - RawDataService#_fetchRawData
Source:
  - data/service/raw-data-service.js, line 396

#### _mapObjectToRawData()

Inherited From:
  - RawDataService#_mapObjectToRawData
Source:
  - data/service/raw-data-service.js, line 1060
To Do:
  - Document.
  - Make this method overridable by type name with methods like `mapHazardToRawData()` and `mapProductToRawData()`.

#### _mapRawDataToObject(record, object, context)

Convert raw data to data objects of an appropriate type. Subclasses should override this method to map properties of the raw data to data objects, as in the following: mapRawDataToObject: { value: function (object, record) { object.firstName = record.GIVEN_NAME; object.lastName = record.FAMILY_NAME; } } Alternatively, subclasses can define a mapping to do this mapping. The default implementation of this method uses the service's mapping if the service has one, and otherwise calls the deprecated mapFromRawData(), whose default implementation does nothing.

##### Parameters:

Name | Type | Description
--- | --- | ---
`record` | Object | An object whose properties' values hold the raw data.
`object` | Object | An object whose properties must be set or modified to represent the raw data.
`context` | ? | The value that was passed in to the addRawData() call that invoked this method.

Inherited From:
  - RawDataService#_mapRawDataToObject
Source:
  - data/service/raw-data-service.js, line 1007
To Do:
  - Make this method overridable by type name with methods like `mapRawDataToHazard()` and `mapRawDataToProduct()`.

#### _persistFetchedDataStream(stream, rawDataArray, context)

Called every time addRawData() is called while online to optionally cache that data for offline use. The default implementation does nothing. This is appropriate for subclasses that do not support offline operation or which operate the same way when offline as when online. Other subclasses may override this method to cache data fetched when online so fetchOfflineData can use that data when offline.

##### Parameters:

Name | Type | Description
--- | --- | ---
`stream` | DataStream | The stream to which the fetched data is being added.
`rawDataArray` | Array | An array of objects whose properties' values hold the raw data.
`context` | ? | The context value passed to the addRawData() call that is invoking this method.

Source:
  - data/service/persistent-data-service.js, line 788

#### _propertyDescriptorForObjectAndName()

Fetch the value of a data object's property, possibly asynchronously. The default implementation of this method just return a fulfilled promise for `null`. Subclasses should override this method to perform any fetch or other operation required to get the requested data. The subclass implementations should only use calls to their root service's fetchData() to fetch data.

Inherited From:
  - RawDataService#_propertyDescriptorForObjectAndName
Source:
  - data/service/raw-data-service.js, line 131

#### 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.

Inherited From:
  - DataService#addChildService
Source:
  - data/service/data-service.js, line 249

#### addRawData(stream, records, context)

To be called by fetchData() or fetchRawData() when raw data records are received. This method should never be called outside of those methods. This method creates and registers the data objects that will represent the raw records with repeated calls to getDataObject(), maps the raw data to those objects with repeated calls to mapRawDataToObject(), and then adds those objects to the specified stream. Subclasses should not override this method and instead override their getDataObject() method, their mapRawDataToObject() method, their mapping's mapRawDataToObject() method, or several of these.

##### Parameters:

Name | Type | Description
--- | --- | ---
`stream` | DataStream | - The stream to which the data objects created from the raw data should be added.
`records` | Array | An array of objects whose properties' values hold the raw data. This array will be modified by this method.
`context` | ? | An arbitrary value that will be passed to getDataObject() and mapRawDataToObject() if it is provided.

Inherited From:
  - RawDataService#addRawData
Source:
  - data/service/raw-data-service.js, line 626

#### authorize()

Inherited From:
  - DataService#authorize
Source:
  - data/service/data-service.js, line 846

##### 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.

Inherited From:
  - DataService#cancelDataStream
Source:
  - data/service/data-service.js, line 1850

#### cancelRawDataStream(dataStreamopt, reasonopt)

Called through MainService when consumer has indicated that he 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.

Inherited From:
  - RawDataService#cancelRawDataStream
Source:
  - data/service/raw-data-service.js, line 446

#### createData(objects, type) → {external:Promise}

Save new data passed in objects of type

##### Parameters:

Name | Type | Description
--- | --- | ---
`objects` | Object | objects whose data should be created.
`type` | String | type of objects, likely to mean a "table" in storage

Source:
  - data/service/persistent-data-service.js, line 954

##### Returns:

- A promise fulfilled when all of the data in the changed object has been saved.

Type
  external:Promise

#### 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.

Inherited From:
  - DataService#createDataObject
Source:
  - data/service/data-service.js, line 1541

##### 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.

Inherited From:
  - DataService#dataIdentifierForObject
Source:
  - data/service/data-service.js, line 1450

##### 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.

Inherited From:
  - DataService#decacheObjectProperties
Source:
  - data/service/data-service.js, line 1065
To Do:
  - Rename and document API and implementation.

#### deleteData(objects, type) → {external:Promise}

Delete data passed in array.

##### Parameters:

Name | Type | Description
--- | --- | ---
`objects` | Object | objects whose data should be saved.
`type` | String | type of objects, likely to mean a "table" in storage

Source:
  - data/service/persistent-data-service.js, line 1159

##### Returns:

- A promise fulfilled when all of the data in the changed object has been saved.

Type
  external:Promise

#### deleteDataObject(object) → {external:Promise}

Subclasses should override this method to delete a data object when that object's raw data wouldn't be useful to perform the deletion. The default implementation maps the data object to raw data and calls deleteRawData() with the data object passed in as the `context` argument of that method.

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | The object to delete.

Inherited From:
  - RawDataService#deleteDataObject
Source:
  - data/service/raw-data-service.js, line 468

##### Returns:

- A promise fulfilled when the object has been deleted. The promise's fulfillment value is not significant and will usually be `null`.

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> |

Overrides:
  - RawDataService#deleteOfflineOperations
Source:
  - data/service/data-service.js, line 2363

##### Returns:

- A promise fulfilled with a null value when the operations have been deleted.

Type
  Promise

#### deleteRawData(record, context) → {external:Promise}

Subclasses should override this method to delete a data object when that object's raw data would be useful to perform the deletion.

##### Parameters:

Name | Type | Description
--- | --- | ---
`record` | Object | An object whose properties hold the raw data of the object to delete.
`context` | ? | An arbitrary value sent by deleteDataObject(). By default this is the object to delete.

Inherited From:
  - RawDataService#deleteRawData
Source:
  - data/service/raw-data-service.js, line 490

##### Returns:

- A promise fulfilled when the object's data has been deleted. The promise's fulfillment value is not significant and will usually be `null`.

Type
  external: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 {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.

Overrides:
  - RawDataService#fetchData
Source:
  - data/service/data-service.js, line 1717

##### 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.

Inherited From:
  - DataService#fetchObjectProperty
Source:
  - data/service/data-service.js, line 1273

##### 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.

Inherited From:
  - DataService#getDataObject
Source:
  - data/service/data-service.js, line 1394

##### 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.

Inherited From:
  - DataService#getObjectProperties
Source:
  - data/service/data-service.js, line 1127

##### 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()

Inherited From:
  - DataService#logOut
Source:
  - data/service/data-service.js, line 857

##### Returns:

Promise

#### mapFromRawData()

Inherited From:
  - RawDataService#mapFromRawData
Deprecated:
  - Yes
Source:
  - data/service/raw-data-service.js, line 1132
To Do:
  - Document deprecation in favor of mapRawDataToObject()

#### mapObjectToRawData(object, record, context)

Public method invoked by the framework during the conversion from an object to a raw data. Designed to be overriden by concrete RawDataServices to allow fine-graine control when needed, beyond transformations offered by an ObjectDescriptorDataMapping or an ExpressionDataMapping

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | An object whose properties must be set or modified to represent the raw data.
`record` | Object | An object whose properties' values hold the raw data.
`context` | ? | The value that was passed in to the addRawData() call that invoked this method.

Inherited From:
  - RawDataService#mapObjectToRawData
Source:
  - data/service/raw-data-service.js, line 1047

#### mappingForObject(record, object, context)

Convert raw data to data objects of an appropriate type.

##### Parameters:

Name | Type | Description
--- | --- | ---
`record` | Object | An object whose properties' values hold the raw data.
`object` | Object | An object whose properties must be set or modified to represent the raw data.
`context` | ? | The value that was passed in to the addRawData() call that invoked this method.

Inherited From:
  - RawDataService#mappingForObject
Source:
  - data/service/raw-data-service.js, line 936
To Do:
  - Make this method overridable by type name with methods like `mapRawDataToHazard()` and `mapRawDataToProduct()`.

#### mapRawDataToObject(record, object, context)

Convert raw data to data objects of an appropriate type. Subclasses should override this method to map properties of the raw data to data objects:

##### Parameters:

Name | Type | Description
--- | --- | ---
`record` | Object | An object whose properties' values hold the raw data.
`object` | Object | An object whose properties must be set or modified to represent the raw data.
`context` | ? | The value that was passed in to the addRawData() call that invoked this method.

Inherited From:
  - RawDataService#mapRawDataToObject
Source:
  - data/service/raw-data-service.js, line 969

#### mapSelectorToRawDataQuery(selector) → {DataQuery}

Convert a selector for data objects to a selector for raw data. The selector returned by this method will be the selector used by methods that deal with raw data, like fetchRawData(), addRawData(), rawDataDone(), and writeOfflineData(). Any [stream]stream available to these methods will have their selector references temporarly replaced by references to the mapped selector returned by this method. The default implementation of this method returns the passed in selector.

##### Parameters:

Name | Type | Description
--- | --- | ---
`selector` | DataQuery | A selector defining data objects to select.

Inherited From:
  - RawDataService#mapSelectorToRawDataQuery
Source:
  - data/service/raw-data-service.js, line 908

##### Returns:

- A selector defining raw data to select.

Type
  DataQuery

#### mapToRawData()

Inherited From:
  - RawDataService#mapToRawData
Deprecated:
  - Yes
Source:
  - data/service/raw-data-service.js, line 1145
To Do:
  - Document deprecation in favor of mapObjectToRawData()

#### 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

Inherited From:
  - DataService#objectForDataIdentifier
Source:
  - data/service/data-service.js, line 1499

##### 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 |

Inherited From:
  - DataService#performOfflineOperation
Source:
  - data/service/data-service.js, line 2326

##### 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

Inherited From:
  - DataService#performOfflineOperations
Source:
  - data/service/data-service.js, line 2202

##### 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

#### rawDataDone(stream, context)

To be called once for each fetchData() or fetchRawData() call received to indicate that all the raw data meant for the specified stream has been added to that stream. Subclasses should not override this method.

##### Parameters:

Name | Type | Description
--- | --- | ---
`stream` | DataStream | The stream to which the data objects corresponding to the raw data have been added.
`context` | ? | An arbitrary value that will be passed to writeOfflineData() if it is provided.

Overrides:
  - RawDataService#rawDataDone
Source:
  - data/service/raw-data-service.js, line 833

#### rawDataServiceDidAddOneRawData(dataService, dataStream, rawData, object) → {void}

Delegate method allowing the persistent service to do the ground work as objects are created, avoiding to loop again later

##### Parameters:

Name | Type | Description
--- | --- | ---
`dataService` | DataService |
`dataStream` | DataStream |
`rawData` | Object |
`object` | Object |

Source:
  - data/service/persistent-data-service.js, line 677

##### Returns:

Type
  void

#### 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.

Overrides:
  - RawDataService#readOfflineOperations
Source:
  - data/service/data-service.js, line 2120

#### recordDataIdentifierForObject(object, dataIdentifier)

Records an object's DataIdentifier

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | object | an Object.
`dataIdentifier` | DataIdentifier | The object whose property values are

Inherited From:
  - DataService#recordDataIdentifierForObject
Source:
  - data/service/data-service.js, line 1463

#### recordObjectForDataIdentifier(dataIdentifier, object)

Records an object's DataIdentifier

##### Parameters:

Name | Type | Description
--- | --- | ---
`dataIdentifier` | DataIdentifier | DataIdentifier
`object` | object | object represented by dataIdentifier

Inherited From:
  - DataService#recordObjectForDataIdentifier
Source:
  - data/service/data-service.js, line 1511

#### 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> |

Inherited From:
  - DataService#registerChildService
Source:
  - data/service/data-service.js, line 337

##### 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.

Inherited From:
  - DataService#removeChildService
Source:
  - data/service/data-service.js, line 517

#### removeDataIdentifierForObject(object)

Remove an object's DataIdentifier

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | object | an object

Inherited From:
  - DataService#removeDataIdentifierForObject
Source:
  - data/service/data-service.js, line 1475

#### removeObjectForDataIdentifier(object)

Remove an object's DataIdentifier

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | object | an object

Inherited From:
  - DataService#removeObjectForDataIdentifier
Source:
  - data/service/data-service.js, line 1523

#### saveDataObject(object) → {external:Promise}

Save changes made to a data object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | The object whose data should be saved.

Inherited From:
  - DataService#saveDataObject
Source:
  - data/service/data-service.js, line 1903

##### Returns:

- A promise fulfilled when all of the data in the changed object has been saved.

Type
  external:Promise

#### saveRawData(record, context) → {external:Promise}

Subclasses should override this method to save a data object when that object's raw data would be useful to perform the save.

##### Parameters:

Name | Type | Description
--- | --- | ---
`record` | Object | An object whose properties hold the raw data of the object to save.
`context` | ? | An arbitrary value sent by saveDataObject(). By default this is the object to save.

Inherited From:
  - RawDataService#saveRawData
Source:
  - data/service/raw-data-service.js, line 533

##### Returns:

- A promise fulfilled when the object's data has been saved. The promise's fulfillment value is not significant and will usually be `null`.

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`.

Inherited From:
  - DataService#spliceWithArray
Source:
  - data/service/data-service.js, line 2463

#### 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.

Inherited From:
  - DataService#unregisterChildService
Source:
  - data/service/data-service.js, line 565

##### Returns:

Type
  Promise

#### updateData(objects, type, context) → {external:Promise}

Save updates made to an array of existing data objects.

##### Parameters:

Name | Type | Description
--- | --- | ---
`objects` | Array | objects whose data should be updated.
`type` | String | type of objects, likely to mean a "table" in storage
`context` | Object | an object that will be associated with operations

Source:
  - data/service/persistent-data-service.js, line 1083

##### Returns:

- A promise fulfilled when all of the data in objects has been saved.

Type
  external: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.

Inherited From:
  - DataService#updateObjectProperties
Source:
  - data/service/data-service.js, line 1224

##### 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

#### writeOfflineData(records, selectornullable, context) → {external:Promise}

Called with all the data passed to addRawData() to allow storing of that data for offline use. The default implementation does nothing. This is appropriate for subclasses that do not support offline operation or which operate the same way when offline as when online. Other subclasses may override this method to store data fetched when online so fetchData can use that data when offline.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`records` | Object |  | An array of objects whose properties' values hold the raw data.
`selector` | DataQuery | <nullable> | - Describes how the raw data was selected.
`context` | ? |  | The value that was passed in to the rawDataDone() call that invoked this method.

Inherited From:
  - RawDataService#writeOfflineData
Source:
  - data/service/raw-data-service.js, line 582

##### Returns:

- A promise fulfilled when the raw data has been saved. The promise's fulfillment value is not significant and will usually be `null`.

Type
  external:Promise