mozilla-b2g/gaia-email-libs-and-more — pull request #232 by jrburke (2013-08-12 23:21:05+00:00)
Title: Bug 892519 - [email] Notifications - Email App Not Foreground

Preliminary GELAM pull request. While this code works and has had some end-to-end testing on a phone, there is a high likelihood it will need some changes before it is merge-worthy. Most importantly, it is lacking tests. Doing a pull request now though to work through any higher level design issues first.

Terms:

* BE: back end: usually means GELAM itself, including the main-frame-setup.js and code under that, the worker code.
* FE: front end: the code in gaia for showing the email UI and front end logic.

### General notes

The general approach: use cronsync as an instance property of mailuniverse to manage syncing. cronsyn-main is outside the worker, so it can set alarms and receive notifications of triggered alarms.

mailuniverse is the facade in front of the cron work, with it handling the triggering of "cron start" and "cron stop" events that go through the mailbridge and mailapi that are then visible to the FE. The "cron stop" event will have any data about new messsages. Right now that data is: for each account that has new messages, how many new and then

There are debug statements that should probably be removed or at least
switched off.

### evt.js

evt.js from the FE was added to the BE, and used by cronsync-main.js to send out the list of wake locks. When copying the files into gaia, the evt.js in GELAM is not copied over, the FE copy is used.

This was done because acquiring the wake locks need to happen during the alarm event loop tick as further ones may be shut down by the system, but the release of the locks need to occur after the FE has figured out how to notify. So a evt.js is used as a pub/sub method in this case with the receiver not being known to GELAM (but wired up by the gaia FE).

### New account properties

**syncInterval**: defaults to 0 for upgrades, meaning no syncing.

**notifyOnNew**: defaults to false for upgrades (if new account is created by FE
after this patch lands, FE defaults to true)

### cron changes

Updates cronslice to latest slice expectations, and pulls it out as a separate file from cronsync.

It also uses $sync.INITIAL_FILL_SIZE for desiredHeaders, felt it was better to use an existing constant than one that may not match if that constant it is related to changes later.

cronsync talks to cronsync-main over postMessage via $router.

Syncing tries to group account IDs that are on the same interval together, so all the cron-related methods accept an array of account IDs.

cronsync is driven by two mechanisms:

* **mailuniverse**: on account startup, if there is a syncInterval on the account, then ensureSync will be called to make sure alarm is still set and set correctly for the account. This should help in cases where the mail app gets killed or dies at inopportune times before the next sync alarm is set.

* as mozAlarms fire, **cronsync-main** listens for them, and tells cronsync about it.

### mailapi/malapi

* passes through the new sync-related account variables.
* Removes modifyConfig, as it only seemed to be used for syncInterval when that value was global. This may have been too aggressive.
* exposes an oncronsyncstart and oncronsyncstop that the FE can use to get notifications of when cronsyncing starts and stops.

### mailuniverse

* makeBridgeFn: just encapsulates some boilerplate for setting up some pass-through messaging functions.
* Renamed _cronSyncer to _cronSync to better match module name. I wonder if this should go further and perhaps cronsync should be a singleton as the cronsync-main.js sends messages in a way that it assumes a static entity receiving them.
* Calls _cronSync.ensureSync if syncInterval is in play, otherwise, it does the old syncFolderList call.
* Bridges the notifications coming out of _cronSync with what is sent over the mailbridge, as the "cronstop" state needs to wait for a final DB account save (usually for the snippets) before sending out the cronstop event. Without this, the FE was shutting down the app before final DB write was done.