Persistence

GigaMap seamlessly integrates with EclipseStore. All required type handlers are registered automatically.

Loading

The loading process is fully automatic, as usual. Even the lazy loading is handled internally.

Storing

After updating the contents of the GigaMap, call gigaMap.store() to persist the changes:

gigaMap.store();

This is the recommended way to store. gigaMap.store() is synchronized internally — it acquires the GigaMap’s lock, ensuring that no other thread can modify the GigaMap while the store operation is running.

The GigaMap monitors changes internally, ensuring that only the modified parts are written to the storage.

This applies to all internal changes of the GigaMap as well as to added and removed entities.

Entities modified through the update or apply methods are automatically included in the store operation. There is no need to store them separately.

gigaMap.update(person, p -> {
    p.setLastName("Smith"),
    p.setAddress(newAddress)
});
gigaMap.store();
Changes made to entities directly (outside of update or apply) are not tracked by the GigaMap and must be stored manually.

Why not storageManager.store(gigaMap)?

Storing the GigaMap through storageManager.store(gigaMap) or storageConnection.storeAll(…​) does not acquire the GigaMap’s internal lock. This means other threads can modify the GigaMap (e.g. by calling add, remove, or update) while it is being serialized, leading to errors such as BinaryPersistenceException: Inconsistent element count.

Always prefer gigaMap.store().

If you must store the GigaMap through an external path, you need to synchronize on the GigaMap instance yourself:

synchronized (gigaMap) {
    storageManager.store(gigaMap);
}

This is the same principle as the classic problem with synchronized JDK collections like Vector: synchronizing individual methods is not sufficient when multiple operations need to be atomic. In this case, the entire store traversal must be protected from concurrent modifications.

Concurrency

As with any EclipseStore application, modifying the object graph and storing the changes must be done under the same lock. The gigaMap.store() method handles this for you by acquiring the GigaMap’s internal lock.

However, if your application modifies other parts of the object graph alongside the GigaMap, you are responsible for synchronizing those modifications and their corresponding store() calls as well. See Locking for details on application-level synchronization strategies.