Annotation Interface Association

@Documented @Target({FIELD,METHOD,PARAMETER,ANNOTATION_TYPE}) @Retention(RUNTIME) @Inherited @SearchInclude public @interface Association
Declares how a message should be associated with handler instances.

@Association enables matching of incoming messages with handler instances whose state matches the incoming message. Matching handlers are then selected and the message is applied to them. This is currently used for persisted handlers annotated with Stateful and for active session instances of SocketEndpoint.

Usage

This annotation can be placed on:
  • A field or getter in a handler instance — 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.
  • A handler parameter — this declares which property of the handled message should be used for matching while keeping the handler signature explicit.

Matching Semantics

A message is associated with a handler instance 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.
This dual condition prevents false positives when different fields share similar values.

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.

Example: Parameter-level association

@HandleError
void retry(Throwable error, @Trigger @Association("orderId") SendOrder command) {
    ...
}
On parameters, @Association reads the association property from the resolved parameter value.

Advanced Configuration

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    always
    Returns whether the message matched by this handler should always be applied to any stored handlers.
    Class<?>[]
    excludedClasses
    Returns payload classes for which this association is active.
    boolean
    excludeMetadata
    Returns whether metadata properties of messages should be checked for possible association with a stored handler.
    Class<?>[]
    includedClasses
    Returns payload classes for which this association can be used.
    String
    path
    Returns path of the property to match on in the handler state.
    String[]
    value
    Returns names of properties in the message payload to associate with.

  • Element Details

    • value

      String[] value
      Returns 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 path
      Returns 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<?>[] includedClasses
      Returns 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 via excludedClasses(), an association with the message is attempted.
      Default:
      {}

    • excludedClasses

      Class<?>[] excludedClasses
      Returns 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 excludeMetadata
      Returns whether metadata properties of messages should be checked for possible association with a stored handler.
      Default:
      false

    • always

      boolean always
      Returns 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