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, simply call store, just like usual.

storageManager.store(gigaMap);

or this way:

gigaMap.store();

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.

Concurrency

When using GigaMap in a multi-threaded environment, it is important to understand how storing interacts with the GigaMap’s internal locking.

gigaMap.store() is the recommended way to store. It is synchronized on the GigaMap instance, which guarantees that no other thread can modify the GigaMap while the store operation is running.

Storing the GigaMap through any other path, such as storageManager.store(gigaMap) or storageConnection.storeAll(…), does not acquire the GigaMap’s lock. If another thread modifies the GigaMap concurrently (e.g. by calling add, remove, or update), the internal data structures can be modified while they are being serialized, leading to errors such as BinaryPersistenceException: Inconsistent element count.

If you need to store the GigaMap through an external path, you must 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.