Create an Entity

One of the most common tasks in Zest™ is the management of the life cycle of Entities. Since Zest™ is capable of
delivering much higher performance than traditional Object-Relational Mapping technologies, we also expect that people
use Entities more frequently in Zest™ applications, so it is a very important topic to cover.

If you want to reproduce what’s explained in this tutorial, remember to depend on the Core Bootstrap artifact:

Table 12. Artifact

Group ID

Artifact ID

Version

org.qi4j.core

org.qi4j.core.bootstrap

2.1

Moreover, you’ll need an EntityStore for persistence and an Indexing engine for querying. Choose among the available
implementations listed in the Extensions section.

Basics First

All Entity operations MUST be done within a UnitOfWork. UnitOfWorks can be nested and if underlying UnitOfWorks are not
completed (method complete()), then none of the operations will be persisted permanently.

Entity composites are subtypes of the EntityComposite interface.

Domain code typically don’t need to know of the EntityComposite types directly, and is instead using the domain specific
interface. The Visibility rules will be applied to associate the right EntityComposite when a domain type is requested.
Ambiguities are not accepted and will result in runtime exceptions.

Zest™ supports that each entity instance can have more than one entity type, and it is managed per instance. This feature
is beyond the scope of this HowTO and will be covered subsequently.

Good Practice

We have made the observation that it is good practice to separate the internal state from the observable behavior. By
this we mean that it is not a good practice to allow client code to manipulate or even view the internal states of
objects, which is such a common (bad) practice in the so called POJO world.

Instead, we recommend that the programmer defines the client requirement of what each participant within the client
context needs to conform to, and then create composites accordingly and hide all the state internal to the composite in
private mixins. By doing so, the same entity can participate in multiple contexts with different behavioral requirements
but using the same internal state.

We recommend limited use of primitive types for Properties and instead subtype the Property.

And try to use ValueComposites instead of Entities.

The Entity

We need an entity to illustrate how we recommend to separate internal state from public behavior and observable state.
We will for the sake of simplicity use a trivial example. Please refer to other (possibly future) HowTos on patterns on
Entity management.

For this case, we define both the Car and the Manufacturer as Entities, whereas the Accident is a Value, since it is an
immutable event that can not be modified.

Assembly

All of the above must also be declared in the assembly. We MUST associate the EntityComposites with a relevant Module.
We must also assemble an EntityStore for the entire application, but that is outside the scope of this HowTo.

So far so good. But how about the Manufacturer input into the create() method?

DDD promotes the use of Repositories. They are the type-safe domain interfaces into locating entities without getting
bogged down with querying infrastructure details. And one Repository per Entity type, so we keep it nice, tidy and
re-usable. So let’s create one for the Manufacturer type.

But now we have introduced 2 services that also are required to be declared in the assembly. In this case, we want the
Services to be available to the application layer above, and not restricted to within this domain model.

The UnitOfWork

If you notice, there is a couple of calls to Module.currentUnitOfWork(), but what is current UnitOfWork, and
who is setting that up?

Well, the domain layer should not worry about UoW, it is probably the responsibility of the application/service layer
sitting on top. That could be a web application creating and completing a UoW per request, or some other co-ordinator
doing long-running UnitOfWorks.

There are of course a lot more details to get all this completed, but that is beyond the scope of this HowTo.
See UnitOfWork in Core API.