server/io.spine.server.aggregate/Aggregate

Aggregate

public abstract class Aggregate<I, S extends EntityState, B extends ValidatingBuilder<S>> extends CommandHandlingEntity<I, S, B> implements EventPlayer, EventReactor

Abstract base for aggregates.

An aggregate is the main building block of a business model. Aggregates guarantee consistency of data modifications in response to commands they receive.

An aggregate modifies its state in response to a command and produces one or more events. These events are used later to restore the state of the aggregate.

Creating an aggregate class

To create a new aggregate class:

Select a type for identifiers of the aggregate. If you select to use a typed identifier (which is recommended), define a protobuf message for the ID type.
Define the structure of the aggregate state as a Protobuf message.
Generate Java code for ID and state types.
Create new Java class derived from Aggregate passing ID and state types as generic parameters.

Adding command handler methods

Command handling methods of an Aggregate are defined in the same way as described in CommandHandlingEntity.

Event(s) returned by command handling methods are posted to the EventBus automatically by AggregateRepository.

Adding event applier methods

Aggregate data is stored as a sequence of events it produces. The state of the aggregate is restored by re-playing the history of events and invoking corresponding event applier methods.

An event applier is a method that changes the state of the aggregate in response to an event. An event applier takes a single parameter of the event message it handles and returns void.

The modification of the state is done using a builder instance obtained from builder. All changes to state become reflected in state(), after all events (obtained from aggregate's history when loading an aggregate, or emitted by command handlers during the command dispatching) are played.

End-users must not call state() method within an event applier. It is so, because event appliers are invoked in scope of an active transaction, which accumulates the model updates in aggregate's builder(), and not in state(). Therefore, state() invocation from the applier's code may return some inconsistent result, and in general is prone to errors. All such attempts will result in a RuntimeException.

An Aggregate class must have applier methods for all types of the events that it produces.

Performance considerations

To improve performance of loading aggregates, an AggregateRepository periodically stores aggregate snapshots. See setSnapshotTrigger for details.

Parameters

<I>

the type for IDs of this class of aggregates

<S>

the type of the state held by the aggregate

<B>

the type of the aggregate state builder

Inheritors

AggregatePart

Constructors

Aggregate

protected void Aggregate()

Creates a new instance.

protected void Aggregate(I id)

Creates a new instance.

Inherited properties

lifecycleFlags

public volatile LifecycleFlags lifecycleFlags

The lifecycle flags of the entity.

Functions

builder

protected final B builder()

Obtains the instance of the state builder.

clearRecentHistory

protected final void clearRecentHistory()

Clears #recentHistory() recent history.

dispatchCommand

protected DispatchOutcome dispatchCommand(CommandEnvelope command)

Obtains a method for the passed command and invokes it.

ensureAccessToState

protected void ensureAccessToState()

Prohibits invoking state() method from within an applier method.

historyBackward

protected final Iterator<Event> historyBackward()

Creates an iterator of the aggregate event history with reverse traversal.

historyContains

protected final boolean historyContains(Predicate<Event> predicate)

Verifies if the aggregate history contains an event which satisfies the passed predicate.

missingTxMessage

protected final String missingTxMessage()

Instructs to modify the state of an aggregate only within an event applier method.

modelClass

protected AggregateClass<? extends Object> modelClass()

Obtains the model class.

play

public final BatchDispatchOutcome play(Iterable<Event> events)

Plays the given events against the underlying entity.

producedEvents

public ImmutableSet<EventClass> producedEvents()

Obtains classes of the events produced by this object.

recentHistory

protected final RecentHistory recentHistory()

Obtains recent history of events of this entity.

thisClass

protected AggregateClass<? extends Object> thisClass()

Obtains model class for this aggregate.

versionNumber

protected final int versionNumber()

Obtains the version number of the entity.

Inherited functions

afterInvoke

public void afterInvoke(HandlerMethod<? extends Object, ? extends Object, ? extends Object, ? extends Object> method)

A callback for a handler method invocation end.

public final Api at(Level logLevel)

Obtains a new fluent logging API at the given level.

beforeInvoke

public void beforeInvoke(HandlerMethod<? extends Object, ? extends Object, ? extends Object, ? extends Object> method)

A callback for a handler method invocation start.

changed

public final boolean changed()

Determines whether the state of this entity or its lifecycle flags have been modified since this entity instance creation.

checkEntityState

protected final List<ConstraintViolation> checkEntityState(S newState)

Verifies the new entity state and returns ConstraintViolations, if any.

checkNotArchived

protected void checkNotArchived()

Ensures that the entity is not marked as archived.

checkNotDeleted

protected void checkNotDeleted()

Ensures that the entity is not marked as deleted.

defaultState

protected final S defaultState()

Obtains the default state of the entity.

equals

public boolean equals(Object o)

expectedDefault

protected ValueMismatch expectedDefault(Message actual, Message newValue)

Creates ValueMismatch for the case of discovering a non-default value when the default value was expected by a command.

expectedEmpty

protected ValueMismatch expectedEmpty(String actual, String newValue)

Creates ValueMismatch for the case of discovering a non-empty value, when an empty string was expected by a command.

expectedNotDefault

protected ValueMismatch expectedNotDefault(Message expected)

Creates a ValueMismatch for a command that wanted to clear a value, but discovered that the field already has the default value.

protected ValueMismatch expectedNotDefault(Message expected, Message newValue)

Creates a ValueMismatch for a command that wanted to change a field value, but discovered that the field has the default value.

expectedNotEmpty

protected ValueMismatch expectedNotEmpty(String expected)

Creates a ValueMismatch for a command that wanted to clear a string value but discovered that the field is already empty.

forTransactionOf

public static EventPlayer forTransactionOf(TransactionalEntity<? extends Object, ? extends Object, ? extends Object> entity)

Creates a transactional EventPlayer for the given entity.

getLifecycleFlags

public final LifecycleFlags getLifecycleFlags()

Obtains the current state of the entity lifecycle flags.

hashCode

public int hashCode()

public I id()

Obtains the identifier of the entity.

idAsString

public String idAsString()

Obtains ID of the entity in the string form.

isActive

public boolean isActive()

Verifies if any of the lifecycle attributes is set.

isArchived

public final boolean isArchived()

Tests whether the entity is marked as archived.

isDeleted

public final boolean isDeleted()

Tests whether the entity is marked as deleted.

lifecycleFlags

public LifecycleFlags lifecycleFlags()

Obtains current lifecycle flags.

lifecycleFlagsChanged

public boolean lifecycleFlagsChanged()

Tells whether lifecycle flags of the entity changed since its initialization.

nothing

public Nothing nothing()

Obtains the io.spine.server.model.

play

public DispatchOutcome play(Event event)

Plays the given event.

producerId

public Any producerId()

The object identity packed into Any.

remember

protected void remember(Iterable<Event> events)

Adds events to the recent history.

setArchived

protected final void setArchived(boolean archived)

Sets archived} status flag to the passed value.

setDeleted

protected final void setDeleted(boolean deleted)

Sets deleted} status flag to the passed value.

setInitialState

protected final void setInitialState(S initialState, Version version)

Sets an initial state for the entity.

state

public final S state()

Obtains the state of the entity.

toString

public String toString()

protected Transaction<I, ? extends TransactionalEntity<I, S, B>, S, B> tx()

Obtains the transaction used for modifying the entity.

unexpectedValue

protected ValueMismatch unexpectedValue(Message expected, Message actual, Message newValue)

Creates ValueMismatch for the case of discovering a value different than by a command.

protected ValueMismatch unexpectedValue(String expected, String actual, String newValue)

Creates ValueMismatch for the case of discovering a value different than expected by a command.

version

public Version version()

Obtains the version of the entity.

whenModified

public Timestamp whenModified()

Obtains timestamp of the entity version.