Convenience Methods

Beside long store(Object instance) MicroStream provides some convenience methods to store several objects at once:

void storeAll(Iterable<?> instances)

Stores the passed instance in any case and all referenced instances of persistable references recursively, but stores referenced instances only if they are newly encountered (e.g. don't have an id associated with them in the object registry, yet and are therefore required to be handled). This is useful for the common case of just storing an updated instance and potentially newly created instances along with it while skipping all existing (and normally unchanged) referenced instances.

List subset = myCollection.getSubset();
subset.foreach(item -> item.modify());
storage.storeAll(subset);

long[] storeAll(Object... instances)

Convenience method to store multiple instances. The passed array (maybe implicitly created by the compiler) itself is NOT stored.

storage.storeAll(itemA, iteamB, iteamC);

Transactions

MicroStream does not provide explicit transactions, every call to a store method is automatically a transaction. A store operation is an atomic all or nothing operation. if the store call is successful all data is written to the storage. Otherwise no data is persisted. Partially persisted data will be reverted.

The default MicroStream implementation fully supports the Java transient field modifier. Class members marked transient will not be persisted.

public class User 
{
	private String username;
	
	//do not persist the users password
	private transient String password; 
}

It is possible to override the default behavior by implementing a custom PersistenceFieldEvaluator.

PersistenceFieldEvaluator fieldEvaluator = 
	(clazz, field) -> !field.getName().startsWith("_");
			
EmbeddedStorageManager storage = EmbeddedStorage.Foundation()
	.onConnectionFoundation(
		c -> c.setFieldEvaluatorPersistable(fieldEvaluator)
	)
	.createEmbeddedStorageManager()
	.start();

Storing Hidden Encapsulated Objects

In some cases, it can be necessary to store modified encapsulated objects that cannot be a accessed from your code.

public class ForeignObject
{
    ...
    private HiddenObject hidden;
    ...
}

In the upper code snippet the "hidden" object cannot be accessed by store(myForeignObject.hidden) if no getter is available. To allow such hidden objects to be stored after they have been modified you have to options:

1. Set the global storing strategy of the MicroStream instance to eager storing or

2. Implement and set a custom PersistenceEagerStoringFieldEvaluator for this field.

EmbeddedStorageManager storage = EmbeddedStorage.Foundation()
	.onConnectionFoundation(
		f -> f.setReferenceFieldEagerEvaluator(
			new CustomEagerStoringFieldEvaluator()
		)
	)
	.start();

Use Immutable data models

To increase performance use immutable sub-graphs as often as possible. Storing those with the provided convenience storing methods or using a thread local storer to insert those sub-graphs concurrently can give a great performance boost.

The MicroStream engine supports two general storing strategies: lazy and eager storing. By default, MicroStream uses the lazy storing strategy.

These storing strategies differ in the way how objects, referenced by the object to be stored are handled if those referenced objects had already been stored.

Lazy Storing

Lazy storing is the default storing mode of the MicroStream engine.

Referenced instances are stored only if they have not been stored yet. If a referenced instance has been stored previously it is not stored again even if it has been modified.

Eager Storing

In eager storing mode referenced instances are stored even if they had been stored before. Contrary to Lazy storing this will also store modified child objects at the cost of performance.

Usage

To use lazy or eager storing explicitly, get an instance of the required Storer and use it's store methods:

Storer storer = storage.createEagerStorer();
storer.store(myData);
storer.commit();

Available Storers are:

storage.createLazyStorer()

storage.createEagerStorer()

Standard storing:

storage.createStorer()

will provide corresponding Storer instances.

Custom Handling

Beside the 'global' lazy or eager storing strategies MicroStream allows to implement an individual handling for the storing behavior. See PersistenceEagerStoringFieldEvaluator for details.

MicroStream is designed to work with object graphs. Thus, storing data means to store an object graph. This includes the object's value fields and references to other objects. Storing an object will also store all instances referenced by this objects that have not been stored before. While storing your data most of the work MicroStream performs for you. You only need to call the store method on the correct object. The rule is: "The Object that has been modified has to be stored!".

Storing objects that are not part of an object graph is most likely pointless.

Storing Root Instances

See Getting Started how to create a database with a root instance.

To store the registered root instance just call the storeRoot() method of a EmbeddedStorageManager instance.

// Init storage manager
final EmbeddedStorageManager storageManager = EmbeddedStorage.start(root);
    
// Store the root object
storageManager.storeRoot();

Storing New Objects

To store a newly created object, store the "owner" of the object. In the example below a new object is created and added to the myObjects list of the root object. Then the modified list gets stored. This will also store the new object.

// Add a new data object to the list in root
MyData dataItem = new MyData("Alice");
root.myObjects.add(dataItem);
    	
// Store the modified list
storageManager.store(root.myObjects);

Storing Modified Objects

Before storing a modified object keep in your mind that the modified object needs to be stored.

In case of a value types, like int, it is the object that has the int field as a member:

// Modify a value type memeber and store it
dataItem.setIntValue(100);
storageManager.store(dataItem);

// Change a string object and store it
dataItem.setName("Bob");
storageManager.store(dataItem);