Aggregate Persistence

Introduction

Persisting business data in a database is required in most of the common use cases within a domain service. Making use of DDD concepts like Aggregates or Root Entities is usually a good fit to represent items that should be persisted.

Aggregate Persistence Support

The Aggregate Persistence Support extension offers various capabilities to support in the modelling and implementation of persisting business data.

The extension is available for the following stacks:

Java Spring Boot Stack 2.0.0 and later
- Supports both MongoDB and DB2 (RDBMS) as database type
Java Spring Boot Stack 1.0.0 (only for Domain services and always enabled)
- Supports both MongoDB and DB2 (RDBMS) as database type
NodeJS TypeScript Stack (only for Domain services and always enabled)
- Supports only MongoDB as database type

ℹ️note

The extension is only available if Domain Modelling Extension is enabled as well.

Aggregate Persistence Support provides the possibility to model root entities and external entities in domain namespaces, offering the capability to store data in a database. Besides that, the root entities come with the possibility to define commands, which are used to represent business logic that describe the behavior of an aggregate. To learn more about the modelling please inspect the related articels around Root Entities, Commands and Database Collections.

e Persistence Support extension also offers convenient functionality while implementation. It takes care that all necessary dependencies are added to the project and also ensures that the connection to the chosen database is established automatically. Besides that, it allows to easily persist aggregates in the database through implementing commands while staying compliant with the domain model. It also offers further capabilities around accessing the data in the database through an automatically generated Repository. To find out more about the implementation capabilities please check Java Spring Boot Implementation and NodeJS TypeScript Implementation.

Root Entities

Root entities are special entity types, which can be defined for a business use case. They consist out of properties and can be modeled within the Solution Designer. Contrary to entities, they have their own lifecycle (creation/life/deletion), contain a unique ID and can persist in / delete from a database collection.

See also introduction to Domain Driven Design for further details.

The creation and editing of root entities are done within a domain namespace in the Solution Designer.

Create root entities

You can access an overview page of the existing entities by visiting the entities tab on the domain namespace's Overview page. You can create a new entity by using the Create entity capability.

Root entities are defined using the following master data:

Local Identifier: This is the local identifier (name) of the entity. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming entities! Furthermore, local identifiers may not begin with a digit and the first character must be uppercase. The local identifier cannot be changed after creation (required)
Abstract: This is a checkbox field. When checked, it indicates that the entity will be abstract. If the field is checked, no instances of this entity can be created by the Solution Envoy environment. The default value is unchecked.
Label: This is used to name the entity (required)
Short Label: This is used to give an even shorter label (optional)
Notes: This is a long description of the entity and its lifecycle (optional)
Parents: This specifies one or more entities from which the new entity will inherit properties and commands. Root entities can only add other root entities as parents
Database Collection: This is the name of the collection of resources (instances) in the database of the specific root entity (only visible and required for MongoDB support)
Table Name: This is the name of the table of resources (instances) in the database of the specific root entity (only visible and required for MongoDB support). Should a table name be used that contains more than 30 characters, this may cause problems with some database systems when creating the tables. In this case, we display a warning in the Problems section. Please consult with your database administrator
Annotations: This allows to adjust default persistence annotations for Mongo and RDBMS.

You can also use the Open after creation checkbox to open the entity for further editing after saving.

ℹ️note

Every change on a root entity (aggregate) is done by an associated command.

Edit root entities

You can edit the master data of the root entity by clicking the Edit entity details button in the Entity Details section on the entity's instance page. Alternatively, you can use the Edit capability of each table row on the Entities tab of a domain namespace's Overview page. The fields that can be edited are Type, Label, Short Label, Notes and Abstract (only for entities and root entities).

ℹ️note

It is not possible to change the Local Identifier.

⚠warning

If the Type of an entity is changed, the type-specific values are deleted. When changing from a Root Entity to an Entity, the Commands and the Database collection are removed. In a Java (Spring Boot) project with the RDBMS support, the Table Name is deleted if a parent is added.

Delete root entities

You can delete a root entity by clicking the Delete entity button in the upper right corner of the entity instance page. Alternatively, you can use the Delete capability of each table row on the Entities tab of a domain namespace's Overview page.

⚠warning

You can only delete an entity if it is not in use. You can check the usages of an entity by using the Information capability and navigating to the Usages section. You will need to confirm the action before the selected entity is permanently deleted.

Entity inheritance

You can assign any number of parent entities while creating root entities. It is also possible to add parents after creation in the Parents section of the Details view. Please see Entity Inheritance for further details.

ℹ️note

All children inherit Commands from their parents.

Associate and remove properties to root entities

You can associate new or existing properties to the entity by navigating to the entity's instance page and using the Add button within the Associated Properties at this Level section. Please see Associate properties to entities and Remove property associationsfor further details.

Course Model Entities

External Entities

External entities are special entity types, which can be defined for a business use case. They are used for mapping and interacting with another entity from an external source which was integrated and modelled in an integration namespace. Since they represent a pointer to an entity that resides in another domain/system, they don't have to contain all definitions of the original external entity, just some identifier properties that help loading the external entity from wherever it resides through the external entity's load functionality. It can also contain its own properties.

The creation and editing of external entities are done within a domain namespace in the Solution Designer.

Create external entities

You can access an overview page of the existing entities by visiting the entities tab on the domain namespace's Overview page. You can create a new external entity by using the Create entity capability.

External entities are defined using the following master data:

Local Identifier: This is the local identifier (name) of the entity. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming entities! Furthermore, local identifiers may not begin with a digit and the first character must be uppercase. The local identifier cannot be changed after creation (required)
Abstract: This is a checkbox field. When checked, it indicates that the entity will be abstract. If the field is checked, no instances of this entity can be created by the Solution Envoy environment. The default value is unchecked. This field is only available for entities and root entities
Label: This is used to name the entity (required)
Short Label: This is used to give an even shorter label (optional)
Notes: This is a long description of the entity and its lifecycle (optional)

An external entity has two types of properties, the Associated Properties and the Constructor Properties. The associated properties are those assigned to the local instance of the external entity. You can add and associate properties by using the Add button. The constructor properties are used as input to the constructor function of the external entities. See Domain Properties for further details on properties.

You can also use the Open after creation checkbox to open the entity for further editing after saving.

Edit external entities

ℹ️note

It is not possible to change the Local Identifier.

Delete external entities

You can delete an external entity by clicking the Delete entity button in the upper right corner of the entity instance page. Alternatively, you can use the Delete capability of each table row on the Entities tab of a domain namespace's Overview page.

⚠warning

Entity inheritance

For external entities, inheritance is not supported.

Associate and remove properties to external entities

You can associate new or existing properties to the external entity by navigating to the entity's instance page and using the Add button within the Associated Properties at this Level section. Please see Associate properties to entities and Remove property associationsfor further details.

Course Model Entities

Commands

Commands are used to either create a new instance or manipulate an already existing instance of a root entity. While modelling, commands can only be created within a root entity.

Command types

Solution Designer provides two different command types for root entities:

Factory Command: This type of command will be used to create new instances of the root entity to which it is assigned
Instance Command: This type of command is used to manipulate the current state of an existing instance of the root entity to which it is assigned

Both command types accept an Input entity (new or existing) and can raise Business Events as well as Business Errors.

Create commands

A command can be added on the instance page of a root entity by using the Add Command capability which can be found in the Associated Commands at this Level section.

Commands are defined using the following master data:

Local Identifier: Identifier of the command. this value must be unique within the namespace and cannot be changed afterwards. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
Label: Label of the command (optional)
Short Label: Short label of the command (optional)
Tags: To tag the command (optional)
Notes: Useful information regarding the command definition (optional)

⚠warning

Commands cannot have the same Local Identifier as a Service or an Agent in the same namespace.

Edit commands

You can edit a command by visiting a Root Entity's instance page and clicking on the Command in the Associated Commands at this Level section.

Edit master data

You can edit the master data of a command by clicking the Edit command details button in the Command Details section on the command's instance page. The fields that can be edited are Label, Short Label and Notes.

ℹ️note

It's not possible to edit the Type and the Local Identifier of a command.

Add input entity

It is possible to assign an Input entity to a command by either clicking on Create new private entity or Select existing entity in the Input section of the command's instance page. To add properties to the input entity click on the Add capability and choose

Create new property
Associate existing property

See properties for further details on creating properties.

Add business events

To add a Business Event to a command that will get published each time the command is executed, click on Add event in the Business Events section of the command's instance page. There are two options when adding an Event to a command:

Add new event
Add existing event

Regarding already existing events, a list of all the events that have been created in a project is shown. It is also possible to search for a specific event using the Search capability. One or more events can be selected in order to be added to the command.

Add business errors

To add a Business Error to a command that will get returned each time the command cannot be executed, click on Add error in the Business Errors section of the command's instance page. There are two options when adding an Error to a command:

Add new error
Add existing error

Regarding already existing errors, a list of all the errors that have been created in a project is shown. It is also possible to search for a specific error using the Search capability. One or more errors can be selected in order to be added to the command.

Delete commands

You can delete a command by clicking the Delete command button in the upper right corner of the command instance page. Alternatively, you can use the Delete capability in the Associated Commands at this Level section of the root entity's Overview page.

⚠warning

You will need to confirm the action before the selected command gets permanently deleted.

Course Model Commands

Database Collections

The domain namespace's Infrastructure tab provides information on the database collections used to persist Root Entities.

Database collections are used to persist root entities. Therefore, whenever you create a root entity, you have to specify a database collection for it.

ℹ️note

Although you can persist multiple root entities into the same database collection, there must be at least one database collection set up for the current project if you want to model one or more root entities.

Create database collections

You can create database collections by using the Create database collection capability in the Database Collections section on the Infrastructure tab of a domain namespace's Overview page.

Database collections are defined using the following master data:

Local Identifier: This is the identifier (name) of the database collection. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming database collections! Furthermore, identifiers may not begin with a digit and the first character must be lowercase (required)
Notes: This is a description of the database collection (optional)

Edit database collections

You can edit the master data of a database collection by clicking the Edit database collection details button in the Database Collection Details section on the database collection's instance page. Alternatively, you can use the Edit capability of each table row on the Infrastructure tab of a domain namespace's Overview page. The fields that can be edited are Local Identifier and Notes.

Delete database collections

You can delete a database collection by clicking the Delete database collection button in the upper right corner of the database collection instance page. Alternatively, you can use the Delete capability of each table row on the Infrastructure tab of a domain namespace's Overview page.

⚠warning

You can only delete a database collection if it is not in use. You can check the usages of a database collection by using the Info capability and navigating to the Usages section. You will need to confirm the action before the selected database collection is permanently deleted.

Java Persistence Annotations (JPA)

IBM Industry Solutions Workbench generates default annotations whenever entities are created or edited. In Java domain services based on Java Stack 2.0 and with RDBMS enabled, it is possible to flexibly add custom annotations and customize data persistence, e.g. by adding additional attributes to fields, tables, and columns. Additionally, you can override other JPA behavior by selecting different primary keys and define composite primary keys.

Custom JPA can be directly added to root entities, as well as to property associations of root entities. These are fully optional settings.

You can find more information on JPA in the official JPA documentation.

Root entity annotations

When creating or editing a root entity, you can create custom JPA table settings for the entity directly in the Designer:

Name, catalog and schema
Unique constraints
Indexes

Apart from these settings, you can add arbitrary annotations to the entity. These annotations should be fully qualified.

After creation, these settings are editable at any time under Edit entity details or Edit JPA table settings in the entity overview. You can also display which entities have custom JPA annotations in the Entities overview table of the namespace.

ℹ️note

An index for a primary key (default and custom) will be created automatically.

Property association annotations

When adding a property to a root entity, you can create corresponding custom annotations directly in the Designer, defining columns and their properties as well as the collection table. Depending on the type of the associated property, different options are offered.

For properties, you have the following customization options:

Columns: name, length (if string-based), precision and scale (if numeric), uniqueness, nullability, insertability, updatability
Collection table: name, catalog, schema, unique constraints, indexes
Join columns: join columns

Apart from these settings, you can add arbitrary annotations to the property association. These annotations should be fully qualified.

After association, these settings are editable at any time under Edit property association of each property in the Associated properties at this level table in the entity overview. You can also display which properties are associated using custom annotations, or are used as a (composite) primary key in the Associated properties at this level table.

ℹ️note

The type of the property association determines which JPA options are available.

Primary key

IBM Industry Solutions Workbench automatically generates a primary key for the entity. You can, however, also select one property of the type text, decimal, or integer as a custom primary key.

ℹ️note

You can only mark one property as the (composite) primary key at the same time.

For the primary key, you have the following customization options:

Generation strategy: GenerationType.SEQUENCE, GenerationType.IDENTITY, GenerationType.TABLE, GenerationType.AUTO, GenerationType.UUID
Generator

For more information on the generated value, see here.

Composite key

You can also define a composite key for an entity.

Create a simple entity. Root entities and external entities cannot be used.
Associate the properties that should be part of the composite key to this entity.
Associate the entity as a linked entity to the root entity you want to add the composite key to.
Set the Composite key setting to true.

The properties of the entity are automatically added to the composite key.

🔥danger

The composite key entity must not be used by any other entity as a non-primary key and must not have parents or children.

ℹ️note

You can only mark one property/linked entity as the (composite) primary key at the same time.

Visualize modelled elements in markdown

You can easily create plantUML diagrams by either inserting native plantUML syntax in a codeblock or auto-generate a diagram by clicking on the "Insert diagram" button or using the k5 command.

For all kinds of diagrams the placeholder, ns has to be replaced with the name of the namespace that holds the object for which the diagram should be generated.

Root entities

    aggregate ns:EntityName parents children properties commands

Replace EntityName with the name of the Root Entity you want to generate a diagram for.

Options:

parents: Shows direct parent entities of the root entity that should be displayed.
children: Shows all direct children of the root entity that should be displayed.
properties: Shows all direct associated properties of each entity displayed in the diagram.
commands: Shows all associated commands for each root entity displayed in the diagram.
all: Shows direct parents, children, associated properties and commands.

ℹ️note

By using the command without any extension the default is to show the aggregate with direct parents, without children, with properties and commands.

Introduction​