Integration

Firefly exposes three primary integration paths: traditional Java projects, Spring Boot projects, and standalone Server. Remote executors connect through transports/netty.

Traditional Java

try (FireflyScheduler scheduler = FireflyScheduler.create()) {
    JobDefinition job = JobDefinition.builder()
            .id("daily-report")
            .name("Daily Report")
            .handlerName("reportHandler")
            .schedule(new CronSchedule("0 0 9 * * *"))
            .zoneId(ZoneId.of("Asia/Shanghai"))
            .build();

    scheduler.register(FireflyJobRegistration.of(job, context -> {
        // run your task here
    }));

    scheduler.start();
}

Spring Boot Starter

Spring Boot applications only need one Starter. It auto-configures the Netty client, handler discovery, job synchronization, heartbeats, reconnection, and Spring lifecycle integration.

Version 1.0.1 is available from Maven Central, with no additional Maven repository required.

<dependency>
    <groupId>io.github.fishered</groupId>
    <artifactId>firefly-spring-boot-starter</artifactId>
    <version>1.0.1</version>
</dependency>

The business service runs as a remote Executor and connects to Gateway. Generate an Integration Key in Admin UI for Executor registration and declarative job synchronization.

spring:
  application:
    name: billing-service
firefly:
  executor:
    name: billing-executor
    gateway-addresses:
      - 127.0.0.1:9700
    integration-key: ${FIREFLY_INTEGRATION_KEY}

Declare jobs on methods of regular Spring beans. Methods must return void and may accept no arguments or one ExecutionContext:

@Component
public class BillingJobs {
    @FireflyJob(
            name = "Daily billing",
            cron = "0 0 2 * * *",
            zoneId = "Asia/Shanghai"
    )
    public void billingHandler(ExecutionContext context) {
        // run business code
    }
}

The fully qualified method name, for example com.example.BillingJobs#billingHandler, becomes the default job ID and handler entrypoint. Programmatic FireflyJobRegistration remains available for dynamic jobs but is not the recommended entrypoint for fixed schedules.

Remote Executor

Non-Spring services can use the Netty client directly, connect to Gateway, register handlers, and wait for trigger commands.

NettyExecutorClient client = NettyExecutorClient.builder()
        .gatewayAddresses(List.of("firefly-1:9700", "firefly-2:9700"))
        .executorName("billing-executor")
        .serviceName("billing-service")
        .build()
        .registerHandler("billingHandler", context -> {
            // run business code
        });

client.start();

Standalone Server

Node roles are configured with firefly.node.roles:

firefly.node.mode=standalone
firefly.node.name=firefly-standalone
firefly.node.roles=api,gateway,scheduler

In production, API, Gateway, and Scheduler roles can be split across different nodes.