Documentation 3.0 Beta
Storing Persistent Data on the Client
The Akula client-side persistence mechanism lets you store data on a client device that persists across executions of the app. In your app, you define the data to persist and then use the persistence mechanism to read, write, update, and delete data in the persistent data store.
This document provides an overview of using persistence on clients. It contains the following sections:
For details on using the persistence mechanism with particular clients, see the following:
About client-side persistence
In a client app, persistent data is preserved across executions of the app. That means that you can run the app and store information to the persistent data store. When you next run the app, that persistent data is available to be loaded back into the client app. The Akula client-side persistence mechanism supports CRUD (Create, Read, Update, Delete) operations on the persistent data store.
Data stores and entity stores
To understand persistence, you should understand the following concepts:
- An entity class defines the structure of the data to persist. For example, you can define a Customer entity as having a first name and a last name field.
- Entities are objects that contain the data you want to persist. An entity is an instance of the entity class. In your application, you might define a new Customer object with a first name of "Fred" and a last name of "Rogers". This entity can be persisted by adding it to the entity store.
- An entity store is a storage location for a set of entities.
- A data store maintains a set of entity stores.
- The persistence manager maintains a set of named data stores, and manages the connections to those data stores.
The actual implementation of the data store and entity store on the client depends on the plugin. For example, the SQLite plugin creates a database and tables to store persistent data. In this case, the database is the data store, and the entity stores are the tables within the database. Entities are stored as records in the tables. A future plugin could use a file system as a data store, with directories acting as the entity store and files acting as the entities.
When defining data stores and entities, you should only use alpha-numeric UTF-8 characters and underscores. Start the name with an alpha character. Do not start the data store name or the entity name with an underscore or numeric character.
To define an entity store, you create a schema. The schema is used by Akula to structure the data within the entity store. For example, the SQLite plugin creates a table from the fields in a schema. Each field in the schema becomes a column in the table.
The following image shows what an entity store for a Customer entity might look like as a table in a database:
The Customer entity class defines the
lastName fields. Akula's persistence mechanism adds the
AKULA_LOCAL_KEY field. This field contains a unique value that Akula uses to track entities in the entity store. The Customer entity class might also define fields such as phone number and address, but only data you define in the schema is persisted.
Defining data for persistence
To simplify the process of persisting data on native clients, Akula provides a simple concrete implementation of AKModel called AKBasicModel, which you can extend, rather than implementing AKModel on your own. For example, you define a class called Customer that contains contact information about your customers. This information could include the customer's name, address, phone number and other information. If your Customer class implements the AKModel interface, or is a subclass of AKBasicModel, it can be written to the persistent data store.
For more information on models for native clients, see Modelling Data for Persistence.
About implementing client-side persistence
The following steps list the tasks that you perform to add persistence to a client app:
- Initialize a connection to the data store as described in Initializing a Connection to the Akula Server.
- Build the schema that represents your persistent class in the Akula persistence mechanism. The schema defines the class data to persist. It can include all class properties, or only a subset. For example, you define a class with many different properties, but you only want to persist a subset of those properties. Therefore, the schema for that class only include a subset of the class properties.
- Initialize the persistence mechanism with a class schema for each class that you want to persist. If your app defines four persistent classes, you call the method four times to initialize the persistence mechanism for the four classes.
- Get an instance of the persistence manager class in your client app. The persistence manager defines the methods that you use to perform CRUD operations on persistent data. Most of the work you do with the persistence mechanism in a client app is through an instance of the persistence manager.
- Call methods of the persistence manager to add, remove, or update persistent data in the data store.
- Before exiting the app, close all instances of the persistence manager.
Opening and closing the persistence manager
A persistence manager instance can have two states:
- Open- You use the persistence manager instance to access the persistent data store. The following persistence manager methods create an open instance:
- Android –
- iOS –
newInstance: of the AKPersistenceManger class
If the encryption manager locks access to an encrypted persistent data store, calling these methods results in an error. For more information on using the encrypted persistent data store, see Encrypting Data in the Persistent Data Store.
- Android –
- Closed- You cannot use the persistence manager to access the persistent data store. You should close the persistence manager as soon as you are done using it. You should not leave connections open. To close the persistence manager instance, call the following methods on the persistence manager instance:
- Android –
- iOS –
close:of the AKPersistenceManger class
Any attempt to use a closed persistence manager to access the encrypted persistent data store results in an error.
After you close a persistence manager instance, you must create a new persistence manager instance to access the persistent data store.
- Android –
To determine the persistence manager's state, use the following methods:
- Android –
- iOS –
isOpenof the AKPersistenceManger class
Using an unencrypted or encrypted persistent data store
The Akula persistence mechanism lets you use an unencrypted persistent data store or an encrypted persistent data store in a client app. Encryption prevents unauthorized users from reading your data.
At app design time, you decide which type of data store to use. Then, at implementation time, you must link the correct libraries with your client app to either support encryption or not. For more information on configuring your client development environment to use an encrypted or unencrypted persistent data store, see Configuring the Client Development Environment.
The remaining pages in this section describe how to use an unencrypted persistent data store. You should be familiar with these concepts before converting your app to use an encrypted data store. For more information on using an encrypted persistent data store, see Encrypting Data in the Persistent Data Store.