@Retention(value=RUNTIME)
@Target(value=METHOD)
@Documented
@AcceptsExternal
public @interface React
A reacting method must be annotated @React
.
Like other message-handling methods, event reactors are designed to be called by the framework only. Therefore, it is recommended to declare a them as package-private. It discourages a developer from calling these methods directly from anywhere.
Package-private access level still declares that an event reactor method is a part
of the Bounded Context-level API. See the BoundedContext
description on how the packages and Bounded Contexts relate.
Each reacting method must accept an event message derived
from EventMessage
as the first parameter.
Optionally, one may pass some additional parameters and put the incoming message into
some perspective.
Here are the available sets of parameters:
@React EngineStopped on(CarStopped event) { ... }
context
; the context
brings some system properties related to event, such as the actor ID and the timestamp of
the event emission:
@React ProjectOwnerAssigned on(ProjectCreated event, EventContext context) { ... }
// Only rejections of `CannotAllocateCargo` type caused by the rejected `DeliverOrder` command will be dispatched. @React OrderDeliveryFailed on(CannotAllocateCargo event, DeliverOrder command) { ... }
It is also possible to add the context of the origin command to access even more properties:
@React ProjectRenameFailed on(ProjectAlreadyCompleted event, RenameProject command, CommandContext ctx) { ... }
The essence of a reacting method is an emission of one or several events in a reaction to
the dispatched event. The emitted events must derive from EventMessage
in order to make the code less error-prone.
As long as an entity may have a complex logic of determining which event to emit in reaction,
the React
-marked methods allow a variety of options for the returning values.
A reacting method must return either
@React TaskReassigned on(UserDeactivated event) { ... }
Optional
event message:
@React Optional<PersonAllowedToBuyAlcohol> on(PersonAgeChanged event) { ... }
Nothing
event stating
that the entity may choose not to react at all:
@React EitherOf3<ProjectCompleted, ProjectEstimateUpdated, Nothing> on(TaskCompleted event) { ... }
Iterable
of event messages:
@React Iterable<StoryMovedToBacklog> on(SprintCompleted event) { ... }
tuple
of event messages; being similar
to Iterable
, tuples allow to declare the exact types of returning values, including
Optional
values:
@React Pair<ProjectOwnerAssigned, ProjectDueDateChanged> on(ProjectCreated event) { ... } @React Pair<TaskAssigned, Optional<TaskStarted>> on(TaskAdded event) { ... }
If the annotation is applied to a method which does not satisfy either of these requirements, this method will not be registering for receiving events.
Modifier and Type | Optional Element and Description |
---|---|
boolean |
external
Deprecated.
please use
@External annotation for the first
method parameter. |
@Deprecated public abstract boolean external
@External
annotation for the first
method parameter.true
, the annotated method of the entity reacts on the event generated from
outside of the Bounded Context to which this entity belongs.