JavaScript Client SDK
Class Index | File Index

Classes


Class PersistenceManager

The PersistenceManager is the central interface for reading and writing objects into persistable storage and for synchronizing data in the persistent storage with the Akula Server. Call the initializeDataStore() method to initialize and create the underlying data storage for a given data store plugin. Call the initializeEntityStore() method to initialize the persistence mechanism with the schema for each class that you want to persist. For example, if your app defines four persistent classes, you call initializeEntityStore() four times to initialize the persistence mechanism for the four classes. Call the getInstance() method to get a reference to the PersistenceManager class in your client app. A PersistenceManager instance can have two states:

Many of the PersistenceManager methods return an object of type promise as defined by the q.min.js library. A promise object lets an asynchronous method define functions to handle the return value or handle a thrown exception. For example, you can use a promise object returned by the add() method of the PersistenceManager as shown below:
    // Define an object constructor for a "Customer" object.
    function Customer(firstname, lastname, custid) {
        this.firstname = firstname;
        this.lastname = lastname;
        this.custid = custid;
    }

    var o = new Customer("Nick", "Danger", 42);

    persistenceManager.add("Customer", o)
        .then(function(result) {
            // onFulfilled: "result" is a Boolean set to true.
            alert("item added");
        }, function(reason) {
            // failure: "reason" is a String with an error message.
            alert("failure: " + reason);
        }
    ); 

Akula also supports other core methods of the promises implementation, including done(), finally(), catch(), and progress().


Defined in: PersistenceManager.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Method Summary
Method Attributes Method Name and Description
 
add(entityClass, entity)
Adds the data object to the persistent data store.
 
Closes this instance of PersistenceManager, making it unusable.
 
getAllLocalChanges(entityClass)
Returns an object containing all local changes to syncable objects of type class since the last sync.
 
Get the unique persisted client ID that identifies the device to the sync server.
 
getFilteredObjects(entityClass, whereClause, values)
Return a list of entities in the persistent store for all instances of the supplied entityClass filtered by the supplied where clause and values.
 
getObjectByLocalKey(entityClass, id)
Return an entity in the persistent store by using the value of the entity's local key.
 
getObjects(entityClass)
Return a list of entities in the persistent store for all instances of the supplied entityClass.
 
getObjectsBySqlQuery(pluginName, sqlString, params, fields)
Returns the objects from a given SQL query.
 
getSqlTableName(entityClass)
Get the backend SQL Table name for a given entity.
 
Determine whether this PersistenceManager instance is open.
 
isPersisted(entity)
Check whether a given model has been added to the persistent store.
 
remove(entityClass, entity)
Deletes an entity in the persistent store.
 
sync(entityClass, syncType, syncEndpoint)
Initiates sync with the remote server and processes the response for a given class.
 
update(entityClass, entity)
Updates the data object in the persistent store.
Class Detail
PersistenceManager()
Method Detail
{promise} add(entityClass, entity)
Adds the data object to the persistent data store.
Parameters:
{string} entityClass
The class name of the entity object.
{Object} entity
The entity to persist.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single Boolean argument with a value of true for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} close()
Closes this instance of PersistenceManager, making it unusable. This method closes all open connections. Further operations require the retrieval of a new PersistenceManager instance.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object takes no arguments. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} getAllLocalChanges(entityClass)
Returns an object containing all local changes to syncable objects of type class since the last sync.
Parameters:
{string} entityClass
The class name of the entity object.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument of type AK.ServerChangeSet. The argument to the failure method is an Object that specifies the reason for the failure.
See:
ServerChangeSet
{string} getClientSyncID()
Get the unique persisted client ID that identifies the device to the sync server.
Since:
1.0.1
Returns:
{string} The client sync ID.
{promise} getFilteredObjects(entityClass, whereClause, values)
Return a list of entities in the persistent store for all instances of the supplied entityClass filtered by the supplied where clause and values.
Parameters:
{string} entityClass
The class name of the entity object.
{string} whereClause
The parameterized where clause to be passed into the plugin. example: "name=? AND date
{string} values
The list of values to be inserted into the where clause.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument containing an Array of entityClass objects for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} getObjectByLocalKey(entityClass, id)
Return an entity in the persistent store by using the value of the entity's local key.
Parameters:
{string} entityClass
The class name of the entity object.
{string} id
The local key for the entity.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument containing the entityClass object for id for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} getObjects(entityClass)
Return a list of entities in the persistent store for all instances of the supplied entityClass.
Parameters:
{string} entityClass
The class name of the entity object.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument containing an Array of entityClass objects for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} getObjectsBySqlQuery(pluginName, sqlString, params, fields)
Returns the objects from a given SQL query.
Parameters:
{string} pluginName
The name of the plugin.
{string} sqlString
The custom query to execute against the persistent store. Can contain '?' characters which will be replaced by the given param values.
{array} params
The values to replace in the query.
{array} fields
The mapping of field names to their expected data types for the returned data models.
Since:
2.5.0
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument containing an Array of entityClass objects for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} getSqlTableName(entityClass)
Get the backend SQL Table name for a given entity.
Parameters:
{string} entityClass
The class name of the entity object.
Since:
2.5.0
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single argument containing an Array of entityClass objects for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.
{Boolean} isOpen()
Determine whether this PersistenceManager instance is open.
Since:
1.0.1
Returns:
{Boolean} true if the instance is open, and false if not.
{Boolean} isPersisted(entity)
Check whether a given model has been added to the persistent store.
Parameters:
{Object} entity
the entity to check.
Since:
2.0.0
Returns:
{Boolean} true if the entity has been stored, and its contents should be updated.
{promise} remove(entityClass, entity)
Deletes an entity in the persistent store.
Parameters:
{string} entityClass
The class name of the entity object.
{Object} entity
The entity to remove.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object takes no arguments. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} sync(entityClass, syncType, syncEndpoint)
Initiates sync with the remote server and processes the response for a given class.

The first sync that you perform downloads data from the server and writes it directly to the persistent data store on the client. You then use the PersistenceManager class to get, update, and remove data in the persistent data store. You can also add new data objects to the persistent data store.

On the next sync, the sync operation uses a SyncSerializer to serialize any modifications to the data, which are then uploaded. The sync also downloads a response object from the server that contains any updates to the previously downloaded data. The persistence manager parses the response object using a SyncSerializer, and then applies the changes from the server to the data in the persistent data store.

Parameters:
{string} entityClass
The class name of the entity object.
{string} syncType
The type of sync to request from the sync server as "incremental", or "full".
{string} syncEndpoint
The location of the route that carries out sync operations. This value is relative to the base URL that you defined when you called the AK.init() method. This argument is optional. You can also specify the sync endpoint in the initializeEntityStore() method.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object takes the argument that is an AK.SyncResult object. This object contains the sync type and the records from the back-end that will be persisted on the client. The argument to the failure method is an Object that specifies the reason for the failure.
{promise} update(entityClass, entity)
Updates the data object in the persistent store.
Parameters:
{string} entityClass
The class name of the entity object.
{Object} entity
The entity to update.
Since:
1.0.1
Returns:
{promise} A promise object, as defined by the q.min.js library. The onFulfilled method of the promise object receives a single Boolean argument with a value of true for a successful operation. The argument to the failure method is an Object that specifies the reason for the failure.

©2013 Verivo Software, Inc. Documentation generated by JsDoc Toolkit 2.4.0 on Mon Apr 27 2015 15:06:19 GMT-0400 (EDT)