Annotation Interface LocalHandler

@Documented @Target({METHOD,TYPE,PACKAGE}) @Retention(RUNTIME) @Inherited public @interface LocalHandler
Marks a message handler method, class, or package as a **local handler**—one that is invoked immediately in the publishing thread rather than asynchronously through tracking.

Local handling is useful for:

  • Requests that require ultra-low latency (e.g., frequent queries, projections, or quick lookups)
  • Lightweight processing that doesn’t need to be logged or retried
  • Messages that should be handled exclusively in the current application instance

When a handler is marked with @LocalHandler, messages it can handle will be processed **immediately after publication** if a matching local handler exists. In most cases, this also means:

  • The message is not persisted by default
  • Other non-local handlers will not see it

Example: Fast local query handling

@LocalHandler
@HandleQuery
Product handle(GetProduct query) {
    return Fluxzero.search(Product.class).match(query.getProductId()).fetchFirst().orElse(null);
}

Note: If you annotate a class or package with @LocalHandler, all handler methods within it are local by default. To opt out for a specific method, use @LocalHandler(false) on that method.

Local handling normally falls back to the Fluxzero Runtime when no handler matches. Use @LocalOnly sparingly when external publication would cross a security boundary.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    allowExternalMessages
    If true, this handler may also receive **externally published messages** (i.e. from other application instances).
    boolean
    logMessage
    Whether messages handled locally should also be **logged and published** to the event bus or event store.
    boolean
    logMetrics
    Whether handling metrics (such as HandleMessageEvent) should be logged for this handler if monitoring is enabled.
    boolean
    value
    Whether the handler is local.

  • Element Details

    • value

      boolean value
      Whether the handler is local. This allows overriding the behavior declared at a higher level (e.g. disabling local behavior for a specific method while the enclosing class is marked local).

      Defaults to true.

      Default:
      true

    • logMessage

      boolean logMessage
      Whether messages handled locally should also be **logged and published** to the event bus or event store.

      This is useful when:

      • You want local processing for speed, but still need visibility or downstream processing
      • Auditability is important (e.g. admin interfaces)

      Defaults to false.

      Default:
      false

    • logMetrics

      boolean logMetrics
      Whether handling metrics (such as HandleMessageEvent) should be logged for this handler if monitoring is enabled.

      Defaults to false.

      Default:
      false

    • allowExternalMessages

      boolean allowExternalMessages
      If true, this handler may also receive **externally published messages** (i.e. from other application instances).

      Normally, a @LocalHandler is used for messages published and handled within the same instance only. Set this to true if the handler should also participate in regular (remote) message tracking.

      Ignored if value() is false.

      Default:
      false