Skip to content
19. Job handler annotations in their own module

19. Job handler annotations in their own module

Date: 2026-10-05

Status

Accepted

Context

A planned Spring integration should discover job handlers declared as annotated methods. Finding and invoking such methods needs reflection, which core does not use, and plain Java applications could use the same mechanism without Spring. The obvious annotation name @Job clashes with the org.bikesched.job.Job interface, which annotated methods take as a parameter.

Decision

A module bikesched-annotations (package org.bikesched.annotation, depending on core only) provides @JobHandler(type = …) for public, non-static void methods with at most two parameters: the Job and the payload, both optional, in any order. Any parameter other than Job is the payload; its class must be non-generic and not primitive. JobHandlers.scan(target) checks all annotated methods of an object (and its superclasses) and returns them; register(bikesched, target) also registers them, typed (JobType.of(type, payloadClass)) if the method has a payload parameter. Methods are invoked via MethodHandle, so exceptions reach bikesched unwrapped. Recurring jobs and job settings are not part of the annotation yet.

Consequences

  • Core stays free of reflection; the Spring module only adds bean discovery and lifecycle.
  • Signature errors fail at startup, not when a job runs.
  • On the module path, users open the handler packages to org.bikesched.annotation.