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:
- Combine strengths of object orientation and relational databases
- Persists most objects with a minimum of transformations
- Make persisted data transparent to all applications
- Support queries on data
- Achieve platform / storage independence
- Storage implementation is a black box for application
- Storage implementation can be based on
- File-serialization
- any JDBC-enabled database
- Record store (J2ME CLDC)
- One standard API for mobile applications AND MI framework
- Upgrade strategy supported
- Multi-user support
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
- Independence of the technical background of data persistence
Robust, performing, multi-user data persistence is pretty tricky and requires
a a lot of basic knowledge of fields in databases, file systems, performance
and the core of Java. Using the Persistence API, application developers can
concentrate on the (already complicated :-) business scenario and does not
have to worry about the technicalities.
- Independence of storage medium
The Persistence API can store data on databases as well as on the file system
(that means via standard Java serialization). The currently activated storage
type is detected automatically by the MI at runtime. Applications using the
Persistence API therefore make best use of the current device features (that
means storing on the database if it's there and doing without it, if it's
not there), while being fully portable to devices with other features (that
means where possibly a database is currently not installed). If a future port
of the application to J2ME CLDC devices is considered, the data access layer
of the application can also be reused entirely, as MI takes care of the correct
data handling in this environment also.
- Higher Performance
While designing the Persistence API, SAP concentrated on high performance
to cope with the limited resources of mobile devices. Applications profit
immediately of SAP's experience and investment in performance by using the
Persistence API.
- Transaction concept
Several modifying data access can be bundled in a transaction. The framework
ensures that all data accesses are executed jointly on commit of the transaction
or otherwise be rolled back jointly.
- Reduced testing effort
Especially when using JDBC, extensive testing of data persistence is required
as errors in generated SQL-statements can only be detected at runtime. Any
generator for SQL-statements therefore needs to be tested very thoroughly
to ensure its robustness. Using the Persistence API, applications leverage
SAP's testing efforts and avoid additional investments in this realm.
- Multi-user support
The Persistence API plays a key role in the multi-user
concept of the MI. It allows to store data ' by user' (invisible and inaccessible
to other users) and 'shared' (visible and accessible to all users of the device).
- Participation in future improvements
SAP will continue to enhance the functionality of MI client API which includes
the Persistence API. Subsequently, applications using the Persistence API
will instantly profit of the performance improvements and make use of new
features easily.
- Ensured upgrade support
By using the persistence API, the MI gains control over the application data,
which is mandatory for any application upgrade strategy. If the MI has no
knowledge about application data, it is obvious that it cannot take care for
its data handling during the application's upgrade. Applications therefore
need to take care for their upgrade itself, which is both complicated and
error-prone. Using the Persistence API, the application ensures that it can
be upgraded easily without data loss.
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.
- 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.
- 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).
- 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.).
- 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