Package io.fluxcapacitor.javaclient.publishing

Interface ErrorGateway

All Superinterfaces:

HasLocalHandlers

All Known Implementing Classes:

DefaultErrorGateway

public interface ErrorGateway
extends HasLocalHandlers

Gateway interface for reporting errors during message handling.

The ErrorGateway is responsible for publishing error messages that occur during the processing of commands, queries, schedules, web requests, or other types of messages. These error messages are typically forwarded to a centralized error stream, which may be consumed for diagnostics, alerting, auditing, or automated handling.

This interface provides methods to report errors as plain objects or as Message instances, along with optional Metadata and a Guarantee that controls the dispatching behavior (e.g. SENT vs STORED).

Automatic Error Reporting

Flux Capacitor automatically reports exceptions that are thrown during handler method invocation. This includes both RuntimeExceptions and checked exceptions wrapped in runtime exceptions. In most cases, users do not need to manually report errors using this gateway.

Flux can also integrate with popular logging frameworks (e.g. Logback, Log4j, SLF4J) to monitor and report any logged warnings or errors as ERROR messages, depending on configuration. This provides deep visibility into both application logic failures and operational anomalies.

Manual Use Cases

Manual usage of this gateway is only necessary in edge cases such as:

• Forwarding functional errors from external systems that are not raised as exceptions.
• Publishing structured error messages for use in dashboards, alerting systems, or external consumers.
• Custom pipelines where message handling does not involve regular handler mechanisms.

See Also:

• HasLocalHandlers
• Guarantee
• FunctionalException
• TechnicalException
• for sending command/query results instead of errors

Method Summary

Modifier and Type	Method	Description
default void	report(Object error)	Reports an error using the provided object.
default void	report(Object payload, Metadata metadata)	Reports an error with the given payload and metadata using the default Guarantee.NONE.
CompletableFuture<Void>	report(Object payload, Metadata metadata, Guarantee guarantee)	Reports an error with the given payload, metadata, and delivery guarantee.

Methods inherited from interface io.fluxcapacitor.javaclient.tracking.handling.HasLocalHandlers

hasLocalHandlers, registerHandler, registerHandler, setSelfHandlerFilter

Method Details

report

default void report(Object error)

Reports an error using the provided object. If the object is a Message, it is passed through with its payload and metadata intact. Otherwise, it is wrapped in a new message with empty metadata.

Parameters:

error - the error object or Message to report

report

default void report(Object payload,
 Metadata metadata)

Reports an error with the given payload and metadata using the default Guarantee.NONE.

This method blocks until the reporting operation is completed or fails.

Parameters:

payload - the error payload

metadata - context metadata for the error

report

CompletableFuture<Void> report(Object payload,
 Metadata metadata,
 Guarantee guarantee)

Reports an error with the given payload, metadata, and delivery guarantee.

Returns a future that completes once the error message is sent or stored based on the provided guarantee.

Parameters:

payload - the error payload

metadata - metadata describing the context of the error

guarantee - whether to ensure message is sent (Guarantee.SENT) or stored (Guarantee.STORED)

Returns:

a future that completes once the message has been handled appropriately