Export and import entities

A mobile application may have to operate where connectivity is poor or non-existent. The user may push it into the background to make room for another application; the operating system to could then evict the application from memory in a process called “tomb-stoning”.  A device could lose power, crash or reboot without warning.

A reliable, responsive application can to save work to local storage and restore the data when the app is revived or re-launched.

In Breeze it’s easy to export and re-import cached entities to any destination, including local storage or another EntityManager.

Export to string

The Breeze EntityManager can export some or all of its cached contents as a serialized string. Here’s how to export its entire cache.

var exportData = manager.exportEntities();

The exportData value is a serialization of every entity in the manager’s cache plus the associated metadata.

You are free to store that string anywhere, such as:

• browser local storage
• browser global storage
• cloud storage
• lawnchair – a popular mobile device storage library

Let’s store it in browser local storage:

var stashName = "stash_everything";
window.localStorage.setItem(stashName, exportData);

Import to a manager

We can recover that string later, perhaps after re-launching the application, and import it into another manager.

var importData = window.localStorage.getItem(stashName);
manager2.importEntities(importData);

If the second manager already has some of the same entities, the import will overwrite their values. If some of those entities have pending unsaved changes and you want to keep those changes despite the import, you should express your intention with an explicit MergeStrategy configuration object.

manager2.importEntities(
    importData,
    {mergeStrategy: breeze.MergeStrategy.PreserveChanges});

Export selected entities

You don’t have to export the entire cache. You can specify which entities to export. Here are some examples:

var exportData1 = manager.exportEntities([someCustomer]); // array with 1 customer

var exportData2 = manager.exportEntities([cust1, cust2]); // array of 2 customers

var exportData3 = manager.exportEntities(manager.getChanges()); // all pending changes

var selectedCusts = EntityQuery.from("Customers")
    .where("CompanyName", "startsWith", "C")
    .using(manager)
    .executeLocally(); // cache-only query returns synchronously

var exportData4 = manager.exportEntities(selectedCusts ); // 'C' customers

Export to another manager

Many developers find keep several managers around so they can isolate parallel workflows. For example, a user can edit customer ‘A’ information in one manager and customer ‘B’ in a different manager and then cancel changes to ‘A’ without reverting pending changes to ‘B’.

In such cases, you may need to flow entities from one manager to another. That’s easy: export from one and import to the other:

var exportData = manager1.exportEntities(selectedEntities);
manager2.importEntities(exportData);

Repeated imports

You can import repeated from several sources. Each successive import plays on top of the other. For example, you might have saved stable reference entities under one name and held unsaved pending changes under another. When the application re-launches, you first pull in the references, then the pending changes, and then resume the user’s editing session:

var importData = window.localStorage.getItem(references);
manager.importEntities(importData);

importData = window.localStorage.getItem(changes_2012100123121822123);
manager.importEntities(importData);

Offline considerations

The ability to export reference entities and unsaved changes to local storage is especially useful in offline and mobile scenarios. Of course there is always a risk of losing data that exist only on the local device. When that risk is worth taking, you can often offer a substantial subset of application value while disconnected for extended periods.

A note of caution: the entities you store locally conform to the metadata that were current when they were exported. If you update the model and change the metadata, you probably won’t be able to reimport the entities you exported and saved under the old metadata. You must keep track of model changes and take steps to recover/migrate the data you exported with prior metadata versions.

Importing new entities

You can export and import entities with pending changes, changes that have not yet been saved to permanent storage.

There is a nuance regarding new entities whose keys are store generated. Such entities have temporary keys until they are saved to the database; then the database provides permanent keys which breeze propagates back to the cached entities. The temporary keys are held in a key map that is part of the Breeze serialization format.

Please note that when Breeze importData such new entities into a manager, these new entities are assigned new temporary keys. That is necessary to prevent the keys of imported new entities from conflicting with the temporary keys of new entities that are already in the target manager.

The following example drives home the point.

var exportData = manager1.exportEntities([newCust1a]);

// create a new manager and populate it with the exported entity
var manager2 = EntityManager.ImportEntities(exportData);
var newCust1b = manager2.getChanges()[0];

var isSameName = newCust1a.CompanyName() === newCust1b.CompanyName(); // true

var isSameId = newCust1a.CustomerID() === newCust1b.CustomerID(); // false