Persistence Introduction | Persistence API Overview | Persistence Example
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.
Data volume for initial download should not exceed 1 MB.
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.
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.
Avoid any complex operations within getEntity() / setInstance() / getInstance(). Prefer simple reference assignments.
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:
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.
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:
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:
Result: For "Activity A2", the resulting transaction will
be "insert", with the modified values from "transaction 2".
For modification operations, the modified entities will be checked by following rules:
Table 2: Modification rules
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:
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".
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.
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
|