Annotation Interface Association
@Documented
@Target({FIELD,METHOD})
@Retention(RUNTIME)
@Inherited
@SearchInclude
public @interface Association
Declares how a message should be routed to a stateful handler instance (typically annotated with
Stateful
).
@Association
enables matching of incoming messages with persisted handler instances. Matching handlers are
automatically loaded and the message is applied to them.
Usage
This annotation can be placed on:- A field or getter in a stateful handler — this declares which part of the handler's state is used for association.
- A handler method — this declares which message field(s) should be matched against handler state.
Matching Semantics
A message is associated with a handler if:- The value of the property in the message equals the value in the handler's state, and
- The name of the message property matches the name (or explicitly declared
value()
) of the handler field.
Multiple Handler Matches
A single message may match multiple handlers. All matching handlers will be loaded and the message will be applied to each.Example: Associating by field
@Value
@Stateful
public class PaymentProcess {
@EntityId String id;
@Association
String pspReference;
}
In this example, any message with a `pspReference` field matching the handler’s field will be routed to it.
Example: Method-level association
@HandleEvent
@Association("userId")
void on(UserDeleted event) {
...
}
Associates based on the `userId` field in the message payload.
Advanced Configuration
path()
can be used to match nested or computed properties in the handler state.includedClasses()
andexcludedClasses()
can restrict association to specific message types.excludeMetadata()
disables metadata-based matching.always()
applies the message to all persisted handlers regardless of association (use with care).
- See Also:
-
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionboolean
Returns whether the message matched by this handler should always be applied to any stored handlers.Class<?>[]
Returns payload classes for which this association is active.boolean
Returns whether metadata properties of messages should be checked for possible association with a stored handler.Class<?>[]
Returns payload classes for which this association can be used.Returns path of the property to match on in the handler state.String[]
Returns names of properties in the message payload to associate with.
-
Element Details
-
value
String[] valueReturns names of properties in the message payload to associate with. If the annotation is placed on a property of the Handler this may be left empty to associate using the name of the Handler property.- Default:
{}
-
path
String pathReturns path of the property to match on in the handler state. A message is only associated with a stored Handler if the associated value can be found in a stored Handler at the given path.If this is left empty and the annotation is on a field or getter, the name of field is used to filter any matches. If this is left empty and the annotation is on a handler method, any Handler containing the associated value is matched, regardless of the path of the value in the matched Handler.
- Default:
""
-
includedClasses
Class<?>[] includedClassesReturns payload classes for which this association can be used. If this array is empty or the payload of a message is assignable to any of these classes, AND the class is not excluded viaexcludedClasses()
, an association with the message is attempted.- Default:
{}
-
excludedClasses
Class<?>[] excludedClassesReturns payload classes for which this association is active. If the payload of a message is assignable to any of these classes an association with the message is NOT attempted.- Default:
{}
-
excludeMetadata
boolean excludeMetadataReturns whether metadata properties of messages should be checked for possible association with a stored handler.- Default:
false
-
always
boolean alwaysReturns whether the message matched by this handler should always be applied to any stored handlers. All other configuration in this annotation will be ignored. This setting only has an effect if it is used in an annotation of a handler method. I.e. it has no effect if the association is on a field or getter of the handler.Note: be very careful using this when there are many stored handlers, as each handler will be fetched and updated. In that case it is prudent to look for alternatives.
- Default:
false
-