1 of 8

Layered Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

Concept to separate the basic aspects of what defines an entity into separate instances of different layers:

Identity, a never to be replaced instance representing an entity in terms of references to it
Logic, nestable in an arbitrary number of dynamically created logic layers, e.g. logging, locking, versioning, etc.
Data, always immutable

Entity graphs are constructed by stricly only referencing identity instances (the "outer shell" of an entity), while every inner layer instance is unshared. This also allows the actual data instance to be immutable, while at the same time leaving referencial integrity of an entity graph intact.

MicroStream provides ready-to-use logic layers for:

Logging
Versioning

While the layers admittedly introduce considerable technical complexity and runtime overhead, this concept is a production ready solution for nearly all requirements regarding cross cutting concerns and aspects.

To use this concept in your code, there need to be at least implementations for the entity's identity and data.

Let's say the entity looks like this:

public interface Person extends Entity
{
	public String firstName();
	 
	public String lastName();
}

There needs to be a identity class:

public class PersonEntity extends EntityLayerIdentity implements Person
{
	protected PersonEntity()
	{
		super();
	}

	@Override
	protected Person entityData()
	{
		return (Person)super.entityData();
	}

	@Override
	public final String firstName()
	{
		return this.entityData().firstName();
	}

	@Override
	public final String lastName()
	{
		return this.entityData().lastName();
	}
}

And a data class:

public class PersonData extends EntityData implements Person
{
	private final String firstName;
	private final String lastName ;

	protected PersonData(final Person entity,
		final String firstName,
		final String lastName )
	{
		super(entity);

		this.firstName = firstName;
		this.lastName  = lastName ;
	}

	@Override
	public String firstName()
	{
		return this.firstName;
	}

	@Override
	public String lastName()
	{
		return this.lastName;
	}
}

A lot of code to write to get an entity with two properties!

But don't worry, there is a code generator for that. An annotation processor to be precise. The only code you have to provide are the entity interfaces, all the other stuff will be generated.

Just add the annotation processor typeone.microstream.entity.codegen.EntityProcessor to your compiler configuration. That's it.

The generator also builds a creator:

public interface PersonCreator extends Entity.Creator<Person, PersonCreator>
{
	public PersonCreator firstName(String firstName);

	public PersonCreator lastName(String lastName);

	public static PersonCreator New()
	{
		return new Default();
	}

	public static PersonCreator New(final Person other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Person, PersonCreator>
		implements PersonCreator
	{
		private String firstName;
		private String lastName ;

		protected Default()
		{
			super();
		}

		@Override
		public PersonCreator firstName(final String firstName)
		{
			this.firstName = firstName;
			return this;
		}

		@Override
		public PersonCreator lastName(final String lastName)
		{
			this.lastName = lastName;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new PersonEntity();
		}

		@Override
		public Person createData(final Person entityInstance)
		{
			return new PersonData(entityInstance,
				this.firstName,
				this.lastName );
		}

		@Override
		public PersonCreator copy(final Person other)
		{
			final Person data = Entity.data(other);
			this.firstName = data.firstName();
			this.lastName  = data.lastName ();
			return this;
		}
	}
}

An Updater:

public interface PersonUpdater extends Entity.Updater<Person, PersonUpdater>
{
	public static boolean setFirstName(final Person person, final String firstName)
	{
		return New(person).firstName(firstName).update();
	}

	public static boolean setLastName(final Person person, final String lastName)
	{
		return New(person).lastName(lastName).update();
	}

	public PersonUpdater firstName(String firstName);

	public PersonUpdater lastName(String lastName);

	public static PersonUpdater New(final Person person)
	{
		return new Default(person);
	}

	public class Default
		extends Entity.Updater.Abstract<Person, PersonUpdater>
		implements PersonUpdater
	{
		private String firstName;
		private String lastName ;

		protected Default(final Person person)
		{
			super(person);
		}

		@Override
		public PersonUpdater firstName(final String firstName)
		{
			this.firstName = firstName;
			return this;
		}

		@Override
		public PersonUpdater lastName(final String lastName)
		{
			this.lastName = lastName;
			return this;
		}

		@Override
		public Person createData(final Person entityInstance)
		{
			return new PersonData(entityInstance,
				this.firstName,
				this.lastName );
		}

		@Override
		public PersonUpdater copy(final Person other)
		{
			final Person data = Entity.data(other);
			this.firstName = data.firstName();
			this.lastName  = data.lastName ();
			return this;
		}
	}
}

An optional equalator, with equals and hashCode methods:

public interface PersonHashEqualator extends HashEqualator<Person>
{
	public static PersonHashEqualator New()
	{
		return new Default();
	}

	public final class Default implements PersonHashEqualator, Stateless
	{
		public static boolean equals(final Person person1, final Person person2)
		{
			return X.equal(person1.firstName(), person2.firstName())
				&& X.equal(person1.lastName (), person2.lastName ())
			;
		}

		public static int hashCode(final Person person)
		{
			return Objects.hash(
				person.firstName(),
				person.lastName ()
			);
		}

		Default()
		{
			super();
		}

		@Override
		public boolean equal(final Person person1, final Person person2)
		{
			return equals(person1, person2);
		}

		@Override
		public int hash(final Person person)
		{
			return hashCode(person);
		}
	}
}

And an optional Appendable:

public interface PersonAppendable extends VarString.Appendable
{
	public static String toString(final Person person)
	{
		return New(person).appendTo(VarString.New()).toString();
	}

	public static PersonAppendable New(final Person person)
	{
		return new Default(person);
	}

	public static class Default implements PersonAppendable
	{
		private final Person person;

		Default(final Person person)
		{
			super();

			this.person = person;
		}

		@Override
		public VarString appendTo(final VarString vs)
		{
			return vs.append(this.person.getClass().getSimpleName())
				.append(" [lastName = ")
				.append(this.person.lastName())
				.append(", firstName = ")
				.append(this.person.firstName())
				.append(']');
		}
	}
}

Configuration

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

The layered entities code generator is an annotation processor, provided by the base module.

The maven configuration looks like this:

<dependencies>
	<dependency>
		<groupId>one.microstream</groupId>
		<artifactId>base</artifactId>
		<version>04.00.00-MS-GA</version>
	</dependency>
</dependencies>

<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<version>3.8.1</version>
			<configuration>
				<source>1.8</source>
				<target>1.8</target>
				<encoding>UTF-8</encoding>
				<annotationProcessors>
					<annotationProcessor>one.microstream.entity.codegen.EntityProcessor</annotationProcessor>
				</annotationProcessors>
				<compilerArgs>
					<arg>-Amicrostream.entity.hashequalator=true</arg>
					<arg>-Amicrostream.entity.appendable=true</arg>
				</compilerArgs>
			</configuration>
		</plugin>
	</plugins>
</build>

If you don't want the HashEqualator to be generated, just set the microstream.entity.hashequalator argument to false. You can leave it out otherwise, the default value is true.

The same applies to the Appendable.

Defining Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

The entity types are just simple interfaces with value methods, which have following requirements:

A return type, no void
No parameters
No type parameters
No declared checked exceptions

You are not limited otherwise. Use any types you want. Inheritance and generics are supported as well.

Entities

public interface Beeing<B>
{
	public B partner();
}

public interface Named
{
	public String name();
}

public interface Animal extends Beeing<Animal>, Entity
{
	public String species();
}

public interface Pet extends Animal, Named
{
}

public interface Human extends Beeing<Human>, Named, Entity
{
}

There is one base type (Beeing), one feature interface (Named) and three entities (Animal, Pet, Human).

Generated Code

The code generator takes care of the three entities, and its output looks like this:

public class AnimalEntity extends EntityLayerIdentity implements Animal
{
	protected AnimalEntity()
	{
		super();
	}

	@Override
	protected Animal entityData()
	{
		return (Animal)super.entityData();
	}

	@Override
	public final String species()
	{
		return this.entityData().species();
	}

	@Override
	public final Animal partner()
	{
		return this.entityData().partner();
	}
}

public class AnimalData extends EntityData implements Animal
{
	private final String species;
	private final Animal partner;

	protected AnimalData(final Animal entity,
		final String species,
		final Animal partner)
	{
		super(entity);

		this.species = species;
		this.partner = partner;
	}

	@Override
	public String species()
	{
		return this.species;
	}

	@Override
	public Animal partner()
	{
		return this.partner;
	}
}

public interface AnimalCreator extends Entity.Creator<Animal, AnimalCreator>
{
	public AnimalCreator species(String species);

	public AnimalCreator partner(Animal partner);

	public static AnimalCreator New()
	{
		return new Default();
	}

	public static AnimalCreator New(final Animal other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Animal, AnimalCreator>
		implements AnimalCreator
	{
		private String species;
		private Animal partner;

		protected Default()
		{
			super();
		}

		@Override
		public AnimalCreator species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public AnimalCreator partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new AnimalEntity();
		}

		@Override
		public Animal createData(final Animal entityInstance)
		{
			return new AnimalData(entityInstance,
				this.species,
				this.partner);
		}

		@Override
		public AnimalCreator copy(final Animal other)
		{
			final Animal data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			return this;
		}
	}
}

public interface AnimalUpdater extends Entity.Updater<Animal, AnimalUpdater>
{
	public static boolean setSpecies(final Animal animal, final String species)
	{
		return New(animal).species(species).update();
	}

	public static boolean setPartner(final Animal animal, final Animal partner)
	{
		return New(animal).partner(partner).update();
	}

	public AnimalUpdater species(String species);

	public AnimalUpdater partner(Animal partner);

	public static AnimalUpdater New(final Animal animal)
	{
		return new Default(animal);
	}

	public class Default
		extends Entity.Updater.Abstract<Animal, AnimalUpdater>
		implements AnimalUpdater
	{
		private String species;
		private Animal partner;

		protected Default(final Animal animal)
		{
			super(animal);
		}

		@Override
		public AnimalUpdater species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public AnimalUpdater partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public Animal createData(final Animal entityInstance)
		{
			return new AnimalData(entityInstance,
				this.species,
				this.partner);
		}

		@Override
		public AnimalUpdater copy(final Animal other)
		{
			final Animal data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			return this;
		}
	}
}

public class PetEntity extends EntityLayerIdentity implements Pet
{
	protected PetEntity()
	{
		super();
	}

	@Override
	protected Pet entityData()
	{
		return (Pet)super.entityData();
	}

	@Override
	public final String species()
	{
		return this.entityData().species();
	}

	@Override
	public final Animal partner()
	{
		return this.entityData().partner();
	}

	@Override
	public final String name()
	{
		return this.entityData().name();
	}
}

public class PetData extends EntityData implements Pet
{
	private final String species;
	private final Animal partner;
	private final String name   ;

	protected PetData(final Pet entity,
		final String species,
		final Animal partner,
		final String name   )
	{
		super(entity);

		this.species = species;
		this.partner = partner;
		this.name    = name   ;
	}

	@Override
	public String species()
	{
		return this.species;
	}

	@Override
	public Animal partner()
	{
		return this.partner;
	}

	@Override
	public String name()
	{
		return this.name;
	}
}

public interface PetCreator extends Entity.Creator<Pet, PetCreator>
{
	public PetCreator species(String species);

	public PetCreator partner(Animal partner);

	public PetCreator name(String name);

	public static PetCreator New()
	{
		return new Default();
	}

	public static PetCreator New(final Pet other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Pet, PetCreator>
		implements PetCreator
	{
		private String species;
		private Animal partner;
		private String name   ;

		protected Default()
		{
			super();
		}

		@Override
		public PetCreator species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public PetCreator partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public PetCreator name(final String name)
		{
			this.name = name;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new PetEntity();
		}

		@Override
		public Pet createData(final Pet entityInstance)
		{
			return new PetData(entityInstance,
				this.species,
				this.partner,
				this.name   );
		}

		@Override
		public PetCreator copy(final Pet other)
		{
			final Pet data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			this.name    = data.name   ();
			return this;
		}
	}
}

public interface PetUpdater extends Entity.Updater<Pet, PetUpdater>
{
	public static boolean setSpecies(final Pet pet, final String species)
	{
		return New(pet).species(species).update();
	}

	public static boolean setPartner(final Pet pet, final Animal partner)
	{
		return New(pet).partner(partner).update();
	}

	public static boolean setName(final Pet pet, final String name)
	{
		return New(pet).name(name).update();
	}

	public PetUpdater species(String species);

	public PetUpdater partner(Animal partner);

	public PetUpdater name(String name);

	public static PetUpdater New(final Pet pet)
	{
		return new Default(pet);
	}

	public class Default
		extends Entity.Updater.Abstract<Pet, PetUpdater>
		implements PetUpdater
	{
		private String species;
		private Animal partner;
		private String name   ;

		protected Default(final Pet pet)
		{
			super(pet);
		}

		@Override
		public PetUpdater species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public PetUpdater partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public PetUpdater name(final String name)
		{
			this.name = name;
			return this;
		}

		@Override
		public Pet createData(final Pet entityInstance)
		{
			return new PetData(entityInstance,
				this.species,
				this.partner,
				this.name   );
		}

		@Override
		public PetUpdater copy(final Pet other)
		{
			final Pet data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			this.name    = data.name   ();
			return this;
		}
	}
}

public class HumanEntity extends EntityLayerIdentity implements Human
{
	protected HumanEntity()
	{
		super();
	}

	@Override
	protected Human entityData()
	{
		return (Human)super.entityData();
	}

	@Override
	public final Human partner()
	{
		return this.entityData().partner();
	}

	@Override
	public final String name()
	{
		return this.entityData().name();
	}
}

Creating Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

Given is the following entity:

public interface Person extends Entity
{
	public String firstName();
	 
	public String lastName();
}

So how is it done? Since the code generator provides a creator, we can use it to create a new Person.

Person john = PersonCreator.New()
    .firstName("John")
    .lastName("Doe")
    .create();

Let's see what the debugger displays if we run this code:

There's always an entity chain, with

The identity (PersonEntity) as outer layer
Then the logic layers, none here in our example
And the inner most layer is always the data (PersonData), which holds the properties.

The properties can be accessed like defined in the entity's interface:

String firstName = john.firstName(); // -> John
String lastName  = john.lastName();  // -> Doe

The creator can also be used to create copies. Just hand over the existing one as template:

Person mike = PersonCreator.New(john) // use John as template
			.firstName("Mike")
			.create();

This will create a "Mike Doe".

Updating Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

The data layer is always immutable. In order to update the values we have to replace the data layer completely. This is done with the updater. The property setter methods can be chained, so it is easy to update multiple properties, for example:

If only one property needs to be updated, the updater class offers static convenience methods for that:

Versioning

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

An arbitrary amount of logic layers can be added to entities. Let's use the predefined versioning layer. It will keep track of all changes. Technically every new data layer which is added by the updater, will create a new version entry.

EntityVersionContext<Long> versionContext = 
	EntityVersionContext.AutoIncrementingLong();
		
Person john = PersonCreator.New()
	.addLayer(versionContext)
	.firstName("John")
	.lastName("Doe")
	.create();

Let's have a look at the debugger:

Now the versioning layer is chained between the identity layer and the data layer.

If we update the entity a few times, we will see how the versioning layer works. In this case we use an auto-incrementing Long as key.

PersonUpdater.setLastName(john, "Smith");
PersonUpdater.setLastName(john, "Archer");
PersonUpdater.setLastName(john, "Bennett");

john.lastName() // now returns "Bennett"

If you want to access older versions use the context:

versionContext.versions(john).get(1L); // -> "John Smith"

To limit the amount of preserved versions, a cleaner can be utilized:

EntityVersionCleaner<Long> versionCleaner = 
    EntityVersionCleaner.AmountPreserving(10);
EntityVersionContext<Long> versionContext = 
    EntityVersionContext.AutoIncrementingLong(cleaner);

This will keep only the last ten versions of the person.

Additionally to number keys, timestamps can be used as well.

EntityVersionContext<Long> systemTimeContext = 
    EntityVersionContext.AutoIncrementingSystemTimeMillis();
EntityVersionContext<Long> nanoTimeContext = 
    EntityVersionContext.AutoIncrementingSystemNanoTime();
EntityVersionContext<Instant> instantContext = 
    EntityVersionContext.AutoIncrementingInstant();

They can be preserved for a specific time range:

EntityVersionCleaner<Instant> cleaner = 
    EntityVersionCleaner.AgePreservingInstant(Duration.of(1, ChronoUnit.YEARS));
EntityVersionContext<Instant> context = 
    EntityVersionContext.AutoIncrementingInstant(cleaner);

The version context can be used as a shared state object. So you can control versioning for multiple entities at once, or even for the hole entity graph.

The auto-incrementing contexts take care of the key creation. If you need to control it by yourself, use the mutable context. But be aware that you have to set the version before updating any data, otherwise the current one will be overwritten.

EntityVersionContext.Mutable<String> versionContext = 
    EntityVersionContext.Mutable();

versionContext.currentVersion("rev-1");

Person john = PersonCreator.New()
    .addLayer(versionContext)
    .firstName("John")
    .lastName("Doe")
    .create();

versionContext.currentVersion("rev-2");
PersonUpdater.setLastName(john, "Smith");

versionContext.currentVersion("rev-3");
PersonUpdater.setLastName(john, "Archer");

versionContext.currentVersion("rev-4");
PersonUpdater.setLastName(john, "Bennett");

Logging

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

Another predefined logic layer is for logging purposes. Since there is a myriad of loggers out there, MicroStream doesn't provide any special adapter, but a generic type which can be used to adapt to the logging framework of your choice.

Just create a class and implement EntityLogger, and you are good to go.

public class JulLogger implements EntityLogger
{
	@Override
	public void afterUpdate(
		final Entity identity, 
		final Entity data, 
		final boolean successful)
	{
		Logger.getLogger(identity.getClass().getName())
			.info("Entity updated");
	}
}

Additional to afterUpdate there are further hooks:

entityCreated
afterRead
beforeUpdate

Now just add the logger when creating entities:

JulLogger logger = new JulLogger();

Person john = PersonCreator.New()
	.addLayer(logger)
	.firstName("John")
	.lastName("Doe")
	.create();

When you call

PersonUpdater.setLastName(john, "Smith");

the logger's output is

Oct 15, 2019 11:17:53 AM JulLogger afterUpdate
INFO: Entity updated

Multiple Layers

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

Entities can be created with an arbitrary amount of layers, so feel free to combine them as you like:

The example on makes use of all the described features.

Defining Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

The entity types are just simple interfaces with value methods, which have following requirements:

A return type, no void
No parameters
No type parameters
No declared checked exceptions

You are not limited otherwise. Use any types you want. Inheritance and generics are supported as well.

Entities

public interface Beeing<B>
{
	public B partner();
}

public interface Named
{
	public String name();
}

public interface Animal extends Beeing<Animal>, Entity
{
	public String species();
}

public interface Pet extends Animal, Named
{
}

public interface Human extends Beeing<Human>, Named, Entity
{
}

There is one base type (Beeing), one feature interface (Named) and three entities (Animal, Pet, Human).

Generated Code

The code generator takes care of the three entities, and its output looks like this:

public class AnimalEntity extends EntityLayerIdentity implements Animal
{
	protected AnimalEntity()
	{
		super();
	}

	@Override
	protected Animal entityData()
	{
		return (Animal)super.entityData();
	}

	@Override
	public final String species()
	{
		return this.entityData().species();
	}

	@Override
	public final Animal partner()
	{
		return this.entityData().partner();
	}
}

public class AnimalData extends EntityData implements Animal
{
	private final String species;
	private final Animal partner;

	protected AnimalData(final Animal entity,
		final String species,
		final Animal partner)
	{
		super(entity);

		this.species = species;
		this.partner = partner;
	}

	@Override
	public String species()
	{
		return this.species;
	}

	@Override
	public Animal partner()
	{
		return this.partner;
	}
}

public interface AnimalCreator extends Entity.Creator<Animal, AnimalCreator>
{
	public AnimalCreator species(String species);

	public AnimalCreator partner(Animal partner);

	public static AnimalCreator New()
	{
		return new Default();
	}

	public static AnimalCreator New(final Animal other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Animal, AnimalCreator>
		implements AnimalCreator
	{
		private String species;
		private Animal partner;

		protected Default()
		{
			super();
		}

		@Override
		public AnimalCreator species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public AnimalCreator partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new AnimalEntity();
		}

		@Override
		public Animal createData(final Animal entityInstance)
		{
			return new AnimalData(entityInstance,
				this.species,
				this.partner);
		}

		@Override
		public AnimalCreator copy(final Animal other)
		{
			final Animal data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			return this;
		}
	}
}

public interface AnimalUpdater extends Entity.Updater<Animal, AnimalUpdater>
{
	public static boolean setSpecies(final Animal animal, final String species)
	{
		return New(animal).species(species).update();
	}

	public static boolean setPartner(final Animal animal, final Animal partner)
	{
		return New(animal).partner(partner).update();
	}

	public AnimalUpdater species(String species);

	public AnimalUpdater partner(Animal partner);

	public static AnimalUpdater New(final Animal animal)
	{
		return new Default(animal);
	}

	public class Default
		extends Entity.Updater.Abstract<Animal, AnimalUpdater>
		implements AnimalUpdater
	{
		private String species;
		private Animal partner;

		protected Default(final Animal animal)
		{
			super(animal);
		}

		@Override
		public AnimalUpdater species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public AnimalUpdater partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public Animal createData(final Animal entityInstance)
		{
			return new AnimalData(entityInstance,
				this.species,
				this.partner);
		}

		@Override
		public AnimalUpdater copy(final Animal other)
		{
			final Animal data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			return this;
		}
	}
}

public class PetEntity extends EntityLayerIdentity implements Pet
{
	protected PetEntity()
	{
		super();
	}

	@Override
	protected Pet entityData()
	{
		return (Pet)super.entityData();
	}

	@Override
	public final String species()
	{
		return this.entityData().species();
	}

	@Override
	public final Animal partner()
	{
		return this.entityData().partner();
	}

	@Override
	public final String name()
	{
		return this.entityData().name();
	}
}

public class PetData extends EntityData implements Pet
{
	private final String species;
	private final Animal partner;
	private final String name   ;

	protected PetData(final Pet entity,
		final String species,
		final Animal partner,
		final String name   )
	{
		super(entity);

		this.species = species;
		this.partner = partner;
		this.name    = name   ;
	}

	@Override
	public String species()
	{
		return this.species;
	}

	@Override
	public Animal partner()
	{
		return this.partner;
	}

	@Override
	public String name()
	{
		return this.name;
	}
}

public interface PetCreator extends Entity.Creator<Pet, PetCreator>
{
	public PetCreator species(String species);

	public PetCreator partner(Animal partner);

	public PetCreator name(String name);

	public static PetCreator New()
	{
		return new Default();
	}

	public static PetCreator New(final Pet other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Pet, PetCreator>
		implements PetCreator
	{
		private String species;
		private Animal partner;
		private String name   ;

		protected Default()
		{
			super();
		}

		@Override
		public PetCreator species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public PetCreator partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public PetCreator name(final String name)
		{
			this.name = name;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new PetEntity();
		}

		@Override
		public Pet createData(final Pet entityInstance)
		{
			return new PetData(entityInstance,
				this.species,
				this.partner,
				this.name   );
		}

		@Override
		public PetCreator copy(final Pet other)
		{
			final Pet data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			this.name    = data.name   ();
			return this;
		}
	}
}

public interface PetUpdater extends Entity.Updater<Pet, PetUpdater>
{
	public static boolean setSpecies(final Pet pet, final String species)
	{
		return New(pet).species(species).update();
	}

	public static boolean setPartner(final Pet pet, final Animal partner)
	{
		return New(pet).partner(partner).update();
	}

	public static boolean setName(final Pet pet, final String name)
	{
		return New(pet).name(name).update();
	}

	public PetUpdater species(String species);

	public PetUpdater partner(Animal partner);

	public PetUpdater name(String name);

	public static PetUpdater New(final Pet pet)
	{
		return new Default(pet);
	}

	public class Default
		extends Entity.Updater.Abstract<Pet, PetUpdater>
		implements PetUpdater
	{
		private String species;
		private Animal partner;
		private String name   ;

		protected Default(final Pet pet)
		{
			super(pet);
		}

		@Override
		public PetUpdater species(final String species)
		{
			this.species = species;
			return this;
		}

		@Override
		public PetUpdater partner(final Animal partner)
		{
			this.partner = partner;
			return this;
		}

		@Override
		public PetUpdater name(final String name)
		{
			this.name = name;
			return this;
		}

		@Override
		public Pet createData(final Pet entityInstance)
		{
			return new PetData(entityInstance,
				this.species,
				this.partner,
				this.name   );
		}

		@Override
		public PetUpdater copy(final Pet other)
		{
			final Pet data = Entity.data(other);
			this.species = data.species();
			this.partner = data.partner();
			this.name    = data.name   ();
			return this;
		}
	}
}

public class HumanEntity extends EntityLayerIdentity implements Human
{
	protected HumanEntity()
	{
		super();
	}

	@Override
	protected Human entityData()
	{
		return (Human)super.entityData();
	}

	@Override
	public final Human partner()
	{
		return this.entityData().partner();
	}

	@Override
	public final String name()
	{
		return this.entityData().name();
	}
}

Layered Entities

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

https://docs.microstream.one/

Concept to separate the basic aspects of what defines an entity into separate instances of different layers:

Identity, a never to be replaced instance representing an entity in terms of references to it
Logic, nestable in an arbitrary number of dynamically created logic layers, e.g. logging, locking, versioning, etc.
Data, always immutable

MicroStream provides ready-to-use logic layers for:

Logging
Versioning

To use this concept in your code, there need to be at least implementations for the entity's identity and data.

Let's say the entity looks like this:

public interface Person extends Entity
{
	public String firstName();
	 
	public String lastName();
}

There needs to be a identity class:

public class PersonEntity extends EntityLayerIdentity implements Person
{
	protected PersonEntity()
	{
		super();
	}

	@Override
	protected Person entityData()
	{
		return (Person)super.entityData();
	}

	@Override
	public final String firstName()
	{
		return this.entityData().firstName();
	}

	@Override
	public final String lastName()
	{
		return this.entityData().lastName();
	}
}

And a data class:

public class PersonData extends EntityData implements Person
{
	private final String firstName;
	private final String lastName ;

	protected PersonData(final Person entity,
		final String firstName,
		final String lastName )
	{
		super(entity);

		this.firstName = firstName;
		this.lastName  = lastName ;
	}

	@Override
	public String firstName()
	{
		return this.firstName;
	}

	@Override
	public String lastName()
	{
		return this.lastName;
	}
}

A lot of code to write to get an entity with two properties!

But don't worry, there is a code generator for that. An annotation processor to be precise. The only code you have to provide are the entity interfaces, all the other stuff will be generated.

Just add the annotation processor typeone.microstream.entity.codegen.EntityProcessor to your compiler configuration. That's it.

The generator also builds a creator:

public interface PersonCreator extends Entity.Creator<Person, PersonCreator>
{
	public PersonCreator firstName(String firstName);

	public PersonCreator lastName(String lastName);

	public static PersonCreator New()
	{
		return new Default();
	}

	public static PersonCreator New(final Person other)
	{
		return new Default().copy(other);
	}

	public class Default
		extends Entity.Creator.Abstract<Person, PersonCreator>
		implements PersonCreator
	{
		private String firstName;
		private String lastName ;

		protected Default()
		{
			super();
		}

		@Override
		public PersonCreator firstName(final String firstName)
		{
			this.firstName = firstName;
			return this;
		}

		@Override
		public PersonCreator lastName(final String lastName)
		{
			this.lastName = lastName;
			return this;
		}

		@Override
		protected EntityLayerIdentity createEntityInstance()
		{
			return new PersonEntity();
		}

		@Override
		public Person createData(final Person entityInstance)
		{
			return new PersonData(entityInstance,
				this.firstName,
				this.lastName );
		}

		@Override
		public PersonCreator copy(final Person other)
		{
			final Person data = Entity.data(other);
			this.firstName = data.firstName();
			this.lastName  = data.lastName ();
			return this;
		}
	}
}

An Updater:

public interface PersonUpdater extends Entity.Updater<Person, PersonUpdater>
{
	public static boolean setFirstName(final Person person, final String firstName)
	{
		return New(person).firstName(firstName).update();
	}

	public static boolean setLastName(final Person person, final String lastName)
	{
		return New(person).lastName(lastName).update();
	}

	public PersonUpdater firstName(String firstName);

	public PersonUpdater lastName(String lastName);

	public static PersonUpdater New(final Person person)
	{
		return new Default(person);
	}

	public class Default
		extends Entity.Updater.Abstract<Person, PersonUpdater>
		implements PersonUpdater
	{
		private String firstName;
		private String lastName ;

		protected Default(final Person person)
		{
			super(person);
		}

		@Override
		public PersonUpdater firstName(final String firstName)
		{
			this.firstName = firstName;
			return this;
		}

		@Override
		public PersonUpdater lastName(final String lastName)
		{
			this.lastName = lastName;
			return this;
		}

		@Override
		public Person createData(final Person entityInstance)
		{
			return new PersonData(entityInstance,
				this.firstName,
				this.lastName );
		}

		@Override
		public PersonUpdater copy(final Person other)
		{
			final Person data = Entity.data(other);
			this.firstName = data.firstName();
			this.lastName  = data.lastName ();
			return this;
		}
	}
}

An optional equalator, with equals and hashCode methods:

public interface PersonHashEqualator extends HashEqualator<Person>
{
	public static PersonHashEqualator New()
	{
		return new Default();
	}

	public final class Default implements PersonHashEqualator, Stateless
	{
		public static boolean equals(final Person person1, final Person person2)
		{
			return X.equal(person1.firstName(), person2.firstName())
				&& X.equal(person1.lastName (), person2.lastName ())
			;
		}

		public static int hashCode(final Person person)
		{
			return Objects.hash(
				person.firstName(),
				person.lastName ()
			);
		}

		Default()
		{
			super();
		}

		@Override
		public boolean equal(final Person person1, final Person person2)
		{
			return equals(person1, person2);
		}

		@Override
		public int hash(final Person person)
		{
			return hashCode(person);
		}
	}
}

And an optional Appendable:

public interface PersonAppendable extends VarString.Appendable
{
	public static String toString(final Person person)
	{
		return New(person).appendTo(VarString.New()).toString();
	}

	public static PersonAppendable New(final Person person)
	{
		return new Default(person);
	}

	public static class Default implements PersonAppendable
	{
		private final Person person;

		Default(final Person person)
		{
			super();

			this.person = person;
		}

		@Override
		public VarString appendTo(final VarString vs)
		{
			return vs.append(this.person.getClass().getSimpleName())
				.append(" [lastName = ")
				.append(this.person.lastName())
				.append(", firstName = ")
				.append(this.person.firstName())
				.append(']');
		}
	}
}