Custom type handlers allow taking control over the storing and loading procedure of specific java types. This is useful to optimize the performance for storing complex objects or in the rare case that it is not possible to store a type with the default type handlers.

Implementation

There are two strategies for a simplified type handler implementation.

A Custom Binary Handler

Implementing a class that extends CustomBinaryHandler and defines a sequence of BinaryFields via the #Field~ static pseudo-constructor methods. Everything else like setting the name, calculating the binary offsets, etc. is then done implicitly via reflection.

The custom type handler must be registered in the CustomTypeHandlerRegistry to enable it:

EmbeddedStorageManager storage = EmbeddedStorage
     .Foundation(WORKINGDIR)
     .onConnectionFoundation(f ->
          f.registerCustomTypeHandlers(new CustomBufferedImageHandler())
     )
     .start(ROOT);

A Static Provider Method

Implementing a class can be skipped altogether by using the method Binary#TypeHandler and passing the BinaryFields directly. Registering such a generically created TypeHandler is not required, either, since Version 3 of MicroStream brought a solution to just define a static method in the entity class that will be recognized and used by MicroStream.

The following is a simple technical example on how a custom binary handler can be easily defined and technically leveraged to optimize storage behavior. E.g. imagine having millions of such objects that now only create 1 database record with a fraction of the required storage space instead of 4 records but hold the same information.

public class Employee
{
	/*
	 * Fields with primitive data are (for whatever reason, e.g. project 
	 * design rules) all object types, but records should be stored as 
	 * efficient as possible, i.e. without overhead of references and value objects.
	 * 
	 * MicroStream's generic type analysis does not know of this and hence cannot 
	 * do it. But defining a custom type handler can
	 */

	String id         ;
	Double salary     ;
	Date   dateOfBirth;
	
	// constructor, getters, setters, etc
	
	/*
	 * The entity class must just contain "any" method returning a suitable type 
	 * handler and MicroStream will recognize it and use the returned handler 
	 * automatically.
	 * 
	 * Type type handler just needs to specify the entity class and define a list 
	 * of fields comprised of (name, getter, setter) in arbitrary order.
	 */
	static BinaryTypeHandler<Employee> provideTypeHandler()
	{
		return Binary.TypeHandler(
		  Employee.class,
			Binary.Field_long("id",
				e -> Long.parseLong(e.id),
				(e, value) -> e.id = String.valueOf(value)
			),
			Binary.Field_long("dateOfBirth",
				e -> e.dateOfBirth.getTime(),
				(e, value) -> e.dateOfBirth = new Date(value)
			),
			Binary.Field_double("salary",
				e -> e.salary.longValue(),
				(e, value) -> e.salary = Double.valueOf(value)
			)
		);
	}
	
}

In addition to the methods for legacy type mapping described in chapter there is also the possibility to implement custom legacy type handlers. Those handlers are the most flexible way to do the mapping from old to new types.

The basic interface that has to be implemented is one.microstream.persistence.types.PersistenceLegacyTypeHandler.

Fortunately the standard persistence implementation provides the abstract class one.microstream.persistence.binary.types.BinaryLegacyTypeHandler.AbstractCustom that should be sufficient to start with a custom implementation in most cases.

Implementing the PersistenceEagerStoringFieldEvaluator interface allows you to handle the eager/lazy storing behavior of any known member. The default implementation of the MicroStream engine threads all fields as lazy storing. See for details on lazy and eager storing.

The PersistenceEagerStoringFieldEvaluator has only one method to be implemented: public boolean isEagerStoring(Class<?> t, Field u) return true if the field has to be eager, otherwise return false.

To register the customized PersistenceEagerStoringFieldEvaluator add it using the one.microstream.persistence.types.PersistenceFoundation .setReferenceFieldEagerEvaluator(PersistenceEagerStoringFieldEvaluator) method during the storage initialization.

In certain environments or setups it is necessary to provide specific ClassLoader instances. This can be done by customizing the connection foundation.

If a single ClassLoader is sufficient, just create a new provider by handing over the instance:

Or return a ClassLoader depending on the requested type:

Class Loader in Application Server

Most application servers load the session's classes with the context class loader. Just use the one of the current thread:

When a reference to the loading storage is needed in entities, e.g. usage of different tenants or to store its internal state in a tailored fashion, this can be done by this little trick.

If an entity type contains one or more transient fields with field type compatible to Persister, the updating processing during loading will set the Persister instance (e.g. an EmbeddedStorageManager instance) used to load the entity instance to those fields.

The fields must be transient to exclude them from the persistent form of the entity. Checking for transient fields is only the default implementation. The checking logic can be customized via PersistenceFoundation#setFieldEvaluatorPersistable.

A more precise check for Persister fields can be customized via PersistenceFoundation#setFieldEvaluatorPersister. Note, however, that the check for compatibility with the Persister type is done in any case to avoid inconsistencies/crashes.

If no applicable field is found, nothing happens and no additional meta data is kept in memory. This feature is completely optional.

class MyEntity
{
	String name ;
	int    value;
	
	transient EmbeddedStorageManager storage;
}

Upon loading an instance of class MyEntity, a reference to the EmbeddedStorageManager used to load it is set to its field storage.