io.spine.core

Annotation Type Subscribe

@Retention(value=RUNTIME)
 @Target(value=METHOD)
 @Documented
 @AcceptsFilters
 @AcceptsExternal
public @interface Subscribe

Marks a method as a subscriber for the command output.

Use it to subscribe to either events, business rejections, or entity state updates.

Subscribing to Events

An event subscriber method:

• is annotated with Subscribe;
• returns void;
• accepts an event derived from EventMessage as the first parameter;
• (optional) accepts an EventContext as the second parameter.

Subscribing to Rejections

A rejection subscriber method:

• is annotated with Subscribe;
• returns void;
• accepts a rejection message derived from RejectionMessage as the first parameter;
• (optional) accepts a command derived from CommandMessage as the second parameter;
• (optional) accepts an CommandContext as the second or the third parameter.

Therefore, if the subscriber method specifies both the command message and the command context, it must have the parameters exactly is that order, i.e. (RejectionMessage, CommandMessage, CommandContext). Otherwise, an exception may be thrown at runtime.

The type of the command argument, if specified, acts as a filter, i.e. the subscriber receives the rejection if:

• the rejection type matches the first argument type;
• the command, which processing caused the rejection, has the same type as the command message argument if it is present;
• if the command message argument is absent, any rejection of a matching type is received by the subscriber.

Subscribing to Entity State Updates

An entity state subscriber method:

• is annotated with Subscribe;
• returns void;
• accepts an entity state message marked with the (entity) option as the only parameter.

If the annotation is applied to a method which doesn't satisfy either of these requirements, this method is not considered a subscriber and is not registered for the command output delivery.

Event subscriber methods 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.

When subscribing to events, field filtering is supported.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	external Deprecated. please use @External annotation for the first method parameter.
ByField	filter Deprecated. please use @Where annotation for the first method parameter.

Element Detail

external

@Deprecated
public abstract boolean external

Deprecated. please use @External annotation for the first method parameter.

When true, the annotated method receives an event generated from outside of the Bounded Context to which the annotated method's class belongs.

Default:

false

filter

@Deprecated
public abstract ByField filter

Deprecated. please use @Where annotation for the first method parameter.

Filter to apply to all the event messages.

If an event does not match this filter, it is not passed to the subscriber method.

If the @ByField.path if empty, the filter is not applied.

Default:

@io.spine.core.ByField(path="", value="")