RMS Failsafe Recovery

We've added the ability to take a complete and exact snapshot of the application's RMS, and write this snapshot to a memory card on the phone. This is useful if the application becomes wedged (i.e., crashes on start-up or is otherwise unusable), as we can both recover all the data on the phone, and restore the exact state of the application in a debug environment to solve the original cause of the problem.

We can also restore the application's RMS from a snapshot file, so that the state of the application will precisely match a previously imaged snapshot. This can be used, for example, to redeploy a JavaRosa instance to another phone (with all data intact) if the first phone develops hardware problems. (Note that this capability is distinct from backup/restore, and is not meant to transition data across versions that break RMS format compatibility.)

How to Use

The failsafe capability lies dormant in the JavaRosa application at all times, provided that support for it has been enabled in your shell (see below). Actually activating the RMS recovery, however, requires no change to the JAR or re-compilation at all.

RMS recovery is activated via properties in the .jad file for the application. To enable/disable RMS recovery:

1. edit the .jad file appropriately 1. reinstall the application on the phone (DON'T delete the installed version, as this will destroy the RMS; install over the currently installed version). this will require access to the original JAR (unless your phone supports pulling it back off the phone; Nokias don't) 1. if you have enabled RMS recovery: 1. make sure the phone has a memory card 1. give the app file permissions ([wiki:WorkingWithFiles#WorkingwiththePhone instructions]) 1. run the app

When RMS recovery is enabled, the respective operation (dump, restore) will happen EVERY time the application is opened. This will render the app unusable (or at least very annoying to use) during normal usage, so the common use case will be:

1. leave it disabled most of the time 1. enable it once needed 1. run the application once with recovery enabled 1. disable it again and resume normal usage

Enabling RMS dumping

Add the line RMS-Image: dump to the .jad file. This will cause the contents of the entire RMS to be written to a file every time the application is started. By default, the file is written to E:/rmsdump.[timestamp] where timestamp is in the format yyyymmddhhmmss.

A different prefix can be specified via the RMS-Image-Path property. For example RMS-Image-Path: MEMCARD/backups/bk will cause the dump files to be written to MEMCARD/backups/bk.[timestamp]. Omit any leading / from the prefix. E:/ is the default memory card location for Nokias.

Enabling RMS restore

Add the line RMS-Image: restore to the .jad file. This will cause the application's entire RMS to be replaced with the contents of the snapshot file, every time the application is opened. This will '''completely destroy''' all data currently saved in the application. By default, the snapshot file at E:/rmsrestore is used.

A different snapshot file can be specified via the RMS-Image-Path property. Specify the full path and omit any leading /. For example, RMS-Image-Path: MEMCARD/backups/snapshot. If the file cannot be found, the application will quit immediately. E:/ is the default memory card location for Nokias.

Disabling RMS recovery

Remove the RMS-Image: line from the .jad file or set it to RMS-Image: none

How to Enable in the Shell

Add the line DumpRMS.RMSRecoveryHook(midlet); as the ''very first'' line in the init() method of your shell. It is possible to run it later, but that runs the risk that unrecoverable exceptions may occur before the recovery is executed, in which case you won't be able to recover your RMS should the phone become wedged due to those exceptions. Running it as the absolute first thing your shell does is the safest course of action.

Make sure the shell has a reference to the parent midlet before calling run()

So far, all CommCare projects and the demo project have been enabled.

What do I do with the output?

Beyond restoring the dumpfile to an emulator or another phone, you can also analyze its contents. The python script rmsdump.py in /trunk/desktoprosa/org.javarosa.rmsdump.util can pretty-print the file's contents, and extract the raw byte data of individual records for further processing.