Tech Tip: Checkpointing

Level 200
DevForce Express

Aug 22, 06

New in DevForce Release 3.2, checkpointing is the local cache equivalent of a database transaction. You set a checkpoint with the new BeginCheckpoint() method of the DevForce PersistenceManager. Call the PM’s RollbackCheckpoint() method if you want to restore the cache to its checkpointed state. Fetches, modifications, merges, deletions, additions, removals – all are reversed!

C#:

MyPersistenceManager.BeginCheckpoint();

<any intervening sequence of operations affecting entities in cache>

MyPersistenceManager.RollbackCheckpoint();

VB.NET:

MyPersistenceManager.BeginCheckpoint()

<any intervening sequence of operations affecting entities in cache>

MyPersistenceManager.RollbackCheckpoint()

Checkpointing makes cross-entity undo a snap. It's usually a nasty business to track and undo changes when the user cancels out of a dialog or wizard, especially if there are many different business objects in play. Now we just set a checkpoint when the dialog begins and turn the user loose. If the dialog ends happily, we discard the checkpoint. If the user cancels, we rollback. Either way, it's one call to start and one call to finish. No bookkeeping required.

We can stack checkpoints with additional BeginCheckpoint() calls. Each subsequent RollbackCheckpoint() undoes the most recent checkpoint. We can cut back the stack by calling RollbackCheckpoint(count) where "count" is the number of checkpoints to rollback. Both overloads return the remaining checkpoint depth.

The RollbackCheckpoints() method rolls all the way back while ClearCheckpoints() wipes the checkpoint slate clean. ClearCheckpoints() is kind of like “commit” in that we are accepting the present state of the entity cache. But take care: our pending changes are still in the cache; they won't become permanent until we save them to the database!

Note also that the PersistenceManager's Clear() and SaveChanges() methods call ClearCheckpoints() automatically before proceeding with their respective tasks.

Checkpointing is lightweight. A checkpoint session records changes to the cache - not images of the cache. Clearing checkpoints to accept changes is virtually instantaneous; rollbacks, which are comparatively rare, are very fast.