Class SchedulingInterceptor

java.lang.Object

io.fluxzero.sdk.scheduling.SchedulingInterceptor

All Implemented Interfaces:

DispatchInterceptor, HandlerDecorator, HandlerInterceptor

public class SchedulingInterceptor
extends Object
implements DispatchInterceptor, HandlerInterceptor

Intercepts scheduled messages to handle periodic scheduling logic.

This interceptor enables powerful scheduling features such as:

• Initial scheduling of @Periodic types: When a handler method or its parameter type is annotated with Periodic, this interceptor will automatically initialize the schedule at startup if autoStart=true.
• Rescheduling on success or failure: Upon successful or failed invocation of a scheduled handler, this interceptor can reschedule the next invocation based on the result or according to cron/delay rules.
• Metadata injection: Adds the scheduleId metadata to outgoing scheduled messages to support correlation and rescheduling.
• Dynamic behavior based on handler return value: Supports dynamic rescheduling based on return types like TemporalAmount, TemporalAccessor, Schedule, or even a replacement payload object.

Additionally, if the scheduled handler throws a CancelPeriodic exception, the schedule is permanently cancelled without logging an error.

This interceptor is registered automatically with Fluxzero.

See Also:

• Periodic
• CancelPeriodic
• Schedule

Nested Class Summary

Nested classes/interfaces inherited from interface HandlerDecorator

HandlerDecorator.MergedDecorator

Nested classes/interfaces inherited from interface HandlerInterceptor

HandlerInterceptor.InterceptedHandler, HandlerInterceptor.PreparedHandlerFunction, HandlerInterceptor.PreparedHandlerInputFunction, HandlerInterceptor.PreparedHandlerInputInterceptor, HandlerInterceptor.PreparedHandlerInterceptor, HandlerInterceptor.PreparedInterceptedHandler

Field Summary

Fields inherited from interface DispatchInterceptor

defaultInterceptors, noOp

Fields inherited from interface HandlerDecorator

noOp

Fields inherited from interface HandlerInterceptor

defaultInterceptors

Constructor Summary

Constructors

Constructor	Description
SchedulingInterceptor()

Method Summary

Modifier and Type	Method	Description
protected Instant	firstDeadline(Periodic periodic, Instant now)
protected Object	handleExceptionalResult(Throwable result, DeserializingMessage schedule, Instant now, Periodic periodic)
protected Object	handleResult(Object result, DeserializingMessage schedule, Instant now, Periodic periodic)
protected void	initializePeriodicSchedule(MessageScheduler messageScheduler, Schedule schedule, Periodic periodic)
protected void	initializePeriodicSchedule(Class<?> payloadType, Periodic periodic)
protected void	initializePeriodicSchedule(Class<?> payloadType, Periodic periodic, String namespace)
void	initializePeriodicSchedules(Object target, String namespace)	Initializes auto-start schedules for one handler in the namespace of the consumer it was assigned to.
Message	interceptDispatch(Message message, MessageType messageType, String topic)	Intercepts the dispatch of a message before it is serialized and published or locally handled.
Function<DeserializingMessage, Object>	interceptHandling(Function<DeserializingMessage, Object> function, HandlerInvoker invoker)	Intercepts the message handling logic.
protected Instant	nextDeadline(Periodic periodic, Instant now)
HandlerInterceptor.PreparedHandlerInterceptor	prepare(HandlerDescriptor handler)	Prepares this interceptor for a specific handler method.
protected boolean	shouldReplacePeriodicSchedule(Schedule currentSchedule, Periodic periodic)
boolean	supportsPreparation()	Indicates whether this interceptor opts into the prepared, mergeable handler wrapper.
Handler<DeserializingMessage>	wrap(Handler<DeserializingMessage> handler)	Wraps a Handler with this interceptor, producing an intercepted handler.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface DispatchInterceptor

andThen, interceptDispatch, modifySerializedMessage, monitorDispatch, prepareLocalDispatch, withNamespace

Methods inherited from interface HandlerDecorator

andThen

Methods inherited from interface HandlerInterceptor

prepareInput, prepareInput

Constructor Details

SchedulingInterceptor

public SchedulingInterceptor()

Method Details

wrap

public Handler<DeserializingMessage> wrap(Handler<DeserializingMessage> handler)

Description copied from interface: HandlerInterceptor

Wraps a Handler with this interceptor, producing an intercepted handler.

Specified by:

wrap in interface HandlerDecorator

Specified by:

wrap in interface HandlerInterceptor

Parameters:

handler - the original handler to wrap

Returns:

an intercepted handler that applies this interceptor to all handled messages

initializePeriodicSchedules

public void initializePeriodicSchedules(Object target,
 String namespace)

Initializes auto-start schedules for one handler in the namespace of the consumer it was assigned to.

initializePeriodicSchedule

protected void initializePeriodicSchedule(Class<?> payloadType,
 Periodic periodic)

initializePeriodicSchedule

protected void initializePeriodicSchedule(Class<?> payloadType,
 Periodic periodic,
 String namespace)

initializePeriodicSchedule

protected void initializePeriodicSchedule(MessageScheduler messageScheduler,
 Schedule schedule,
 Periodic periodic)

shouldReplacePeriodicSchedule

protected boolean shouldReplacePeriodicSchedule(Schedule currentSchedule,
 Periodic periodic)

firstDeadline

protected Instant firstDeadline(Periodic periodic,
 Instant now)

nextDeadline

protected Instant nextDeadline(Periodic periodic,
 Instant now)

interceptDispatch

public Message interceptDispatch(Message message,
 MessageType messageType,
 String topic)

Description copied from interface: DispatchInterceptor

Intercepts the dispatch of a message before it is serialized and published or locally handled.

You may modify the message or return null to block dispatching. Throwing an exception also prevents dispatching.

Specified by:

interceptDispatch in interface DispatchInterceptor

Parameters:

message - the message to be dispatched

messageType - the type of the message (e.g., COMMAND, EVENT, etc.)

topic - the target topic or null if not applicable

Returns:

the modified message, the same message, or null to prevent dispatch

interceptHandling

public Function<DeserializingMessage, Object> interceptHandling(Function<DeserializingMessage, Object> function,
 HandlerInvoker invoker)

Description copied from interface: HandlerInterceptor

Intercepts the message handling logic.

The function parameter represents the next step in the handling chain— typically the actual message handler. The invoker provides metadata and invocation logic for the underlying handler method.

Within this method, an interceptor may:

• Modify the DeserializingMessage before passing it to the handler
• Bypass the handler entirely and return a value directly
• Wrap the result after the handler is invoked

Note: Interceptors may return a different DeserializingMessage, but it must be compatible with a handler method in the same target class. If no suitable handler is found, an exception will be thrown.

Specified by:

interceptHandling in interface HandlerInterceptor

Parameters:

function - the next step in the handler chain (typically the handler itself)

invoker - the metadata and execution strategy for the actual handler method

Returns:

a decorated function that wraps handling behavior

prepare

public HandlerInterceptor.PreparedHandlerInterceptor prepare(HandlerDescriptor handler)

Description copied from interface: HandlerInterceptor

Prepares this interceptor for a specific handler method.

The returned interceptor is cached and reused concurrently for invocations with the same stable handler metadata. Implementations may use this hook to resolve annotation- or signature-based policy once while keeping message-dependent decisions inside HandlerInterceptor.PreparedHandlerInterceptor.interceptHandling(DeserializingMessage, HandlerDescriptor, BiFunction, HandlerInterceptor.PreparedHandlerFunction).

The default adapter preserves the existing HandlerInterceptor.interceptHandling(Function, HandlerInvoker) contract and deliberately disables the reusable HandlerMethod path. Custom interceptors therefore retain their current behavior unless they explicitly opt into preparation.

Specified by:

prepare in interface HandlerInterceptor

Parameters:

handler - stable metadata for the handler method

Returns:

a thread-safe prepared interceptor

supportsPreparation

public boolean supportsPreparation()

Description copied from interface: HandlerInterceptor

Indicates whether this interceptor opts into the prepared, mergeable handler wrapper.

The default is false, preserving the exact wrapper behavior of existing custom interceptors. An interceptor should return true only when HandlerInterceptor.prepare(HandlerDescriptor) returns a thread-safe plan that fully represents its handling behavior. If a subclass overrides only the legacy HandlerInterceptor.interceptHandling(Function, HandlerInvoker) method, the legacy wrapper is retained automatically.

Specified by:

supportsPreparation in interface HandlerInterceptor

Returns:

true when this interceptor may be merged into a prepared wrapper

handleResult

protected Object handleResult(Object result,
 DeserializingMessage schedule,
 Instant now,
 Periodic periodic)

handleExceptionalResult

protected Object handleExceptionalResult(Throwable result,
 DeserializingMessage schedule,
 Instant now,
 Periodic periodic)