Persistence Introduction  |  Persistence API Overview   |  Persistence Example

 

Rules for Persistence

Transactions and "Commit"

The "commit" method finalizes a write or delete transaction. On a "write" transaction it would cause to physically write all entities to disk. When ever possible, you should perform a "commit" after the "write" transactions is finished and NOT after every "write" transaction.

Example (Persistence used with file IO): When you write 500 entities and perform a "commit" after every write, you easily can end up with about 40 minutes of processing time. When you perform the "commit" after all 500 entities are "written", you bring down the processing time to less than two minutes.

 

Bottleneck Operations

Initial Download and Persistence Layer with File I/O

Data volume for initial download should not exceed 1 MB.

Operations with DEPENDENT/COMPLETE Depth

Do not read an entity as "COMPLETE" if it is not definitely sure that all linked entities will be accessed.

Do not read an entity as "DEPENDENT", if it is not definitely sure that all linked entities defined as dependent will be accessed.

Read Operations

If you read entities several times you should think about keeping the references in your application instead. Be careful storing the references in your application. The object has to be released again when it is not needed anymore, otherwise "out of memory" exceptions are more likely to occur on a PDA.

Query operations are time consuming as well. Storing Query results has the same restrictions as storing references mentiond above.

Interface Entity

Avoid any complex operations within getEntity() / setInstance() / getInstance(). Prefer simple reference assignments.

 

Rules for Entity Trees in Persistence

General Processing of Linked Entities

Persistence tries to process linked entities like the root entity. If a transaction is performed one of the following TransactionManager settings:

methods will be invoked for the actual root entity as well as for the corresponding linked entities.

Example:

  1. Entity "PM Order P1" has linked entities "Activity A1" and "Activity A2".
  2. "Activity A1" has linked Entities "Component C1" and "Component C2".
  3. TransactionManager.insert() is called for "PM Order P1" with TreeOptionType = COMPLETE

    Result: Entity "PM Order P1" is inserted as well as all Entities "Activity A1", "Activity A2", "Component C1" and "Component C2".

In the following we discuss exceptions to this rule.

Processing of Competing Modification Operations

Modification operations ("insert", "modify" and "delete") are physically processed when the "commit" method is called. When you perform several transactions on an entity (See Transactions and "Commit") before you call the "commit" method, the persistence API merges the modifications according to following rules:

Operation 1 (first transaction)

Operation 2 (next transaction) Results in transaction (Operation R)
insert insert insert
insert modify insert
insert delete No operation
modify insert modify
modify modify modify
modify delete delete
delete insert modify
delete modify modify
delete delete delete
Table 1: Operation merging rules

 

If there are more operations to perform on an entity, you can extend the operation chain by taking "Operation R" as "Operation 1" and the next transaction as "Operation 2" and so on.

The entity values for the resulting operations will be taken from the last operation. The merging rules apply to root entities and linked entities.

Example:

  1. Entity "PM Order P1" has linked Entities "Activity A1" and "Activity A2".
  2. "Activity A1" has linked Entities "Component C1" and "Component C2".

    transaction 1: TransactionManager.insert() is called for "PM Order P1" with TreeOptionType = COMPLETE (which will insert "PM Order P1", "Activity A1", "Activity A2", "Component C1" and "Component C2").
    transaction 2: TransactionManager.modify() is called for "Activity A2".


    Result: For "Activity A2", the resulting transaction will be "insert", with the modified values from "transaction 2".

 

General plausibility check at modification operations

For modification operations, the modified entities will be checked by following rules:

Operation

Rule
insert Entity with equal key must not exist before operation execution.
modify Entity with equal key must exist before operation execution.
delete Entity with equal key must exist before operation execution.

Table 2: Modification rules

 

Tolerant modification operations for linked Entities

When a linked entity violates a rule shown in table 2 above, the persistence API determines a save transaction for the linked entity, according to following rules:

OR = Original operation for root entity.
OLX = Operation for linked entity if linked entity exists before operation execution.
OLNX = Operation for linked entity if linked entity does NOT exist before the operation is executed.

OR

OLX OLNX
insert modify insert
modify modify insert
delete delete No operation

 

Example:

  1. Entity "PM Order P1" has linked Entities "Activity A1" and "Activity A2".
  2. "Activity A1" has linked Entities "Component C1" and "Component C2".


    transaction 1: "PM Order P1" is inserted with TreeOptionType = COMPLETE (which will insert "PM Order P1", "Activity A1", "Activity A2", "Component C1" and "Component C2").
    transaction 2: "Activity A1" is deleted with TreeOptionType = SKELETON (which will delete "Activity A1" only).
    transaction 3: "PM Order P1" is modified with TreeOptionType = COMPLETE (which should modify "PM Order P1", "Activity A1", "Activity A2", "Component C1" and "Component C2").

    Result: Since "Activity A1" does not exist at transaction 3, the transaction "insert" be chosen to process "Activity A1". The linked entities of "Activity A1" (that is "Component C1" and "Component C2") however will be processed with transaction "modify".

 

Performance Enhancers in SP3

In SP3 new packages are released to enhance the performance. The enhancements will take effect in the Persistence and SmartSync API. SmartSync applications take immediate effect from the changes. Existing Mobile Infrastructure applications that use the Persistance layer can be used without any changes, to benefit from the enhancements however, code changes are necessary.

The changes in the Persistence layer are addressing mainly "out of memory" exceptions and "memory leaks". Because of the relations of entities the garbage collection usually can not clean up all objects that are not used anymore - the result is, that the garbage collection itself takes away system resources (because it runs longer) and the memory is not cleaned up.

Major changes

Compatibility chart:

 
File I/O
old DB
new DB
Implementation based on "old" Persistence package
X
X
-
Implementation based on "new" Persistence package
X
-
X