Aggregate (server 1.8.2 API)

java.lang.Object
- io.spine.server.entity.AbstractEntity<I,S>
- - io.spine.server.entity.TransactionalEntity<I,S,B>
  - - io.spine.server.command.CommandHandlingEntity<I,S,B>
    - - io.spine.server.aggregate.Aggregate<I,S,B>

Type 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

All Implemented Interfaces:

CommandHandler, CommandReceiver, Entity<I,S>, WithLifecycle, EventReactor, EventReceiver, EventProducer, HandlerLifecycle

Direct Known Subclasses:

AggregatePart
```
public abstract class Aggregate<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
extends CommandHandlingEntity<I,S,B>
implements 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:
1. 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.
2. Define the structure of the aggregate state as a Protobuf message.
3. Generate Java code for ID and state types.
4. 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 Aggregate.builder().
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 AggregateRepository.setSnapshotTrigger(int) for details.

Nested Class Summary
- Nested classes/interfaces inherited from interface io.spine.server.entity.Entity
  Entity.GenericParameter

Constructor Summary

Constructors
Modifier Constructor and Description

protected Aggregate()
Creates a new instance.

protected Aggregate(I id)
Creates a new instance.

Constructors
Modifier	Constructor and Description
`protected`	`Aggregate()` Creates a new instance.
`protected`	`Aggregate(I id)` Creates a new instance.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected B`	`builder()` Obtains the instance of the state builder.
`protected void`	`clearRecentHistory()` Clears recent history.
`protected io.spine.server.dispatch.DispatchOutcome`	`dispatchCommand(CommandEnvelope command)` Obtains a method for the passed command and invokes it.
`protected java.util.Iterator<io.spine.core.Event>`	`historyBackward()` Creates an iterator of the aggregate event history with reverse traversal.
`protected boolean`	`historyContains(java.util.function.Predicate<io.spine.core.Event> predicate)` Verifies if the aggregate history contains an event which satisfies the passed predicate.
`protected java.lang.String`	`missingTxMessage()` Instructs to modify the state of an aggregate only within an event applier method.
`io.spine.server.dispatch.BatchDispatchOutcome`	`play(java.lang.Iterable<io.spine.core.Event> events)`
`protected RecentHistory`	`recentHistory()` Obtains recent history of events of this entity.
`protected AggregateClass<?>`	`thisClass()` Obtains model class for this aggregate.
`protected int`	`versionNumber()` Obtains the version number of the entity.

Methods inherited from class io.spine.server.command.CommandHandlingEntity
expectedDefault, expectedEmpty, expectedNotDefault, expectedNotDefault, expectedNotEmpty, producerId, unexpectedValue, unexpectedValue

Methods inherited from class io.spine.server.entity.TransactionalEntity
getLifecycleFlags, remember, setArchived, setDeleted, setInitialState, tx

Methods inherited from class io.spine.server.entity.AbstractEntity
afterInvoke, at, beforeInvoke, checkEntityState, checkNotArchived, checkNotDeleted, defaultState, equals, hashCode, id, idAsString, isArchived, isDeleted, lifecycleFlagsChanged, state, toString, version, whenModified

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.spine.server.EventProducer
nothing, producedEvents, producerId, version

Methods inherited from interface io.spine.server.entity.WithLifecycle
isActive, lifecycleFlags

- Constructor Detail
  - Aggregate
```
protected Aggregate()
```
    Creates a new instance.
    API Note:
    Constructors of derived classes are likely to have package-private access level because of the following reasons:
    
    These constructors are not public API of an application. Commands and aggregate IDs are.
    These constructors need to be accessible from tests in the same package.
    
    If you do have tests that create aggregates using constructors, consider annotating them with @VisibleForTesting. Otherwise, aggregate constructors (that are invoked by AggregateRepository using Reflection) may be left private.
  - Aggregate
```
protected Aggregate(I id)
```
    Creates a new instance.
    Parameters:
    
    id - the ID for the new aggregate
    
    API Note:
    Constructors of derived classes are likely to have package-private access level because of the following reasons:
    
    These constructors are not public API of an application. Commands and aggregate IDs are.
    These constructors need to be accessible from tests in the same package.
    
    If you do have tests that create aggregates via constructors, consider annotating them with @VisibleForTesting. Otherwise, aggregate constructors (that are invoked by AggregateRepository via Reflection) may be left private.
- Method Detail
  - thisClass
```
protected AggregateClass<?> thisClass()
```
    Obtains model class for this aggregate.
    
    Overrides:
    
    thisClass in class AbstractEntity<I,S extends io.spine.base.EntityState>
  - builder
```
protected final B builder()
```
    Obtains the instance of the state builder.
    This method must be called only from within an active transaction.
    In Aggregate this method must be called only from within an event applier.
    
    Overrides:
    
    builder in class TransactionalEntity<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
    
    Returns:
    
    the instance of the new state builder
    
    Throws:
    
    java.lang.IllegalStateException - if the method is called from outside an event applier
  - dispatchCommand
```
protected io.spine.server.dispatch.DispatchOutcome dispatchCommand(CommandEnvelope command)
```
    Obtains a method for the passed command and invokes it.
    Dispatching the commands results in emitting event messages. All the empty messages are filtered out from the result.
    
    Specified by:
    
    dispatchCommand in class CommandHandlingEntity<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
    
    Parameters:
    
    command - the envelope with the command to dispatch
    
    Returns:
    
    a list of event messages that the aggregate produces by handling the command
  - play
```
public final io.spine.server.dispatch.BatchDispatchOutcome play(java.lang.Iterable<io.spine.core.Event> events)
```
  - missingTxMessage
```
protected final java.lang.String missingTxMessage()
```
    Instructs to modify the state of an aggregate only within an event applier method.
    
    Overrides:
    
    missingTxMessage in class TransactionalEntity<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
  - clearRecentHistory
```
protected final void clearRecentHistory()
```
    Clears recent history.
    Opens the method for the repository.
    
    Overrides:
    
    clearRecentHistory in class TransactionalEntity<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
  - recentHistory
```
protected final RecentHistory recentHistory()
```
    Obtains recent history of events of this entity.
    Opens the method to this package for testing.
    
    Overrides:
    
    recentHistory in class TransactionalEntity<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>
  - historyBackward
```
protected final java.util.Iterator<io.spine.core.Event> historyBackward()
```
    Creates an iterator of the aggregate event history with reverse traversal.
    The records are returned sorted by timestamp in a descending order (from newer to older).
    The iterator is empty if there's no history for the aggregate.
    
    Returns:
    
    new iterator instance
  - historyContains
```
protected final boolean historyContains(java.util.function.Predicate<io.spine.core.Event> predicate)
```
    Verifies if the aggregate history contains an event which satisfies the passed predicate.
  - versionNumber
```
protected final int versionNumber()
```
    Obtains the version number of the entity.
    Overrides to expose the method to the package.
    
    Overrides:
    
    versionNumber in class AbstractEntity<I,S extends io.spine.base.EntityState>

Class Aggregate<I,S extends io.spine.base.EntityState,B extends io.spine.protobuf.ValidatingBuilder<S>>

Creating an aggregate class

Adding command handler methods

Adding event applier methods

Performance considerations

Nested Class Summary

Nested classes/interfaces inherited from interface io.spine.server.entity.Entity

Constructor Summary

Method Summary

Methods inherited from class io.spine.server.command.CommandHandlingEntity

Methods inherited from class io.spine.server.entity.TransactionalEntity

Methods inherited from class io.spine.server.entity.AbstractEntity

Methods inherited from class java.lang.Object

Methods inherited from interface io.spine.server.EventProducer

Methods inherited from interface io.spine.server.entity.WithLifecycle

Constructor Detail

Aggregate

Aggregate

Method Detail

thisClass

builder

dispatchCommand

play

missingTxMessage

clearRecentHistory

recentHistory

historyBackward

historyContains

versionNumber