Persistence API overview   |  Persistence Rules  |  Performance Tips  |  Persistence Example

 

Data Persistence API

Introduction

For the data persistence needs of a mobile client applications, MI offers the Persistence API which is located in the packagecom.sap.ip.me.api.persist.*. The Persistence API lets you persist and retrieve any Java object on the local database or file system and basically serves as an abstraction layer to hide the technicalities (like creation of database-dependent SQL-statements, efficient search and retrieval of stored objects, transaction concept and so on) involved with data persistence . The Persistence API supports multi-user access by offering user-individual and user-independent data persistence and will support persistence for J2ME CLDC record storage in the future.

The Persistence API must not be used in MI applications that use the SmartSync API. Please also check the latest SAP Note 717510 for restrictions.

Overview on Persistence API

The Persistence API targets following areas:

The following graphic explains the general architecture concept:

Mobile client applications should use the Persistence API to storing data - the MI framework itself also stores all its data via the Persistence API and specially the Smart Synchronization makes extensive use of it. The Persistence API let you store, change, delete and query data. The storage medium used and the technicality of its access is entirely transparent to users of the Persistence API. The MI uses 'bridges' - one for every storage type - to access the physical storage. The bridges dynamically create the necessary statements (for example, SQL-statements to access a JDBC databases) to access the data.

Mobile client applications have full control of the object tree and which part of it should be persisted. The strength of this concept becomes obvious when you compare it to the standard Java serialization mechanism which always persists (and retrieves!) the entire object tree (the object together with all referenced objects) which uses a lot of resources and lowers the performance. The Persistence API also ensures that objects with mutual references (for example, a brother object referencing his sister object and the sister object referencing its brother object) do not cause conflicts on retrieval and avoids that the information is persisted twice.

Advantages of using the Persistence API

Using the Persistence API bears tremendous advantage for application developers

Persistence Concept

The general concept of the Persistence API is that application objects are mapped to a generic format, in which they are persisted. On retrieval, the generic format needs to be mapped back to the original object instance, considering all relevant attributes and object references.

The overall process for is described in the following graphic

We start with an application object, in this example with an object having several attributes (represented as the big star) and containing two references to other objects (represented as small stars). As example for the scenario we can use a car. The car object has attributes (manufacturer, number of seats and so on) and references to the passenger object sitting in the car.

  1. Preparation for data persistence
    Before an application object can be persisted, it needs to be mapped to a generic format understood by the MI Persistence Layer. This mapping is defined and done by the application object itself (!), because it implements a special interface (com.sap.ip.me.api.persist.app.Entity). Before saving an application object to disc, the application object is asked to map itself to persist able format. All referenced objects that shall be persisted are also mapped to the generic format (and therefor need to implement the above interface). The application can decide to store only certain object attributes or references (for example temporary data, internal counters and so on do not have to be stored necessarily).
    The persistence-relevant attributes and referenced objects of the application object need to be described on a meta level by implementing the methods of package com.sap.ip.me.api.persist.meta.
  2. Saving the object to persistent storage
    Now that the object can be persisted, the application calls the Persistence Runtime and persists the persist able object via the Persistence Manager. Both are located in package com.sap.ip.me.api.persist.core. Beware, that the storage type and data format used by the Persistence Runtime is entirely transparent to the application. The application can decide, whether the object shall be persisted 'by user' (visible only to the current user) or shared (visible to all users of the application).
  3. Retrieving the object from persistent storage
    On retrieval of the object, the MI Persistence Layer reads the data from persistent storage and recreates instances of the object and the referenced objects in their generic format (see 1.).
  4. Re-creation of the application object
    Then an application object is created that receives the generic instance containing the application data. The application object is then asked to reconstruct itself from these data.

Queries

Queries to the persisted data is possible via the package com.sap.ip.me.api.persist.query. A query consists of conditions (for example, seat number > 4) and optionally sort orders (for example, by manufacturer in alphabetic order). Queries are managed by the QueryRuntime for file I/0 and JQueryFactory for DB (for example, DB2) and high performance queries. The QueryRuntime/JQueryFactory creates the condition and executes the query and returns the generic object instances. The QueryRuntime/JQueryFactory is called from the Persistence Manager. Queries are also used to define a sort order (ascending, descending) for the stored objects.

The Persistence and SmartSync examples of the MDK use the QueryRuntime to set up queries. The JQueryFactory works indentical to the QueryRuntime. Click here for a JQuery code snippet.

 

More information

Persistence API overview

Persistence rules

Persistence example