Chronos project

스레드의 톱니바퀴를 가장 우아하게 움직이는 시간의 신, Chronos.

Chronos는 Java SE 환경에서 외부 의존성(Zero Dependencies) 없이 동작하는 초경량 하이브리드 태스크 스케줄러 라이브러리입니다.

문자열 오타로 인한 런타임 에러를 컴파일 타임에 완벽히 방지하는 Fluent Chain API 방식과 복잡한 주기 설정에 유리한 Cron 표현식 방식을 모두 지원하며, 선언적 개발을 위한 어노테이션 스캔 기능까지 내장하고 있습니다.

핵심 기능 (Key Features)

• 제로 의존성 (Zero Dependencies): 외부 라이브러리를 일절 포함하지 않고 JDK 표준 API(JDK 11 이상 권장)만으로 빌드되어 가볍고 안전합니다.
• 컴파일 타임 안전 보장 (Step Builder): IDE 자동완성에 의존하여 문법 오류 없이 완벽한 스케줄 체인을 구성할 수 있습니다.
• 하이브리드 모드 지원: 직관적인 Fluent Chain API와 정교한 Cron 표현식 파서를 선택적으로 결합할 수 있습니다.
• 유연한 오버랩 정책 (Overlap Policy): 작업이 밀렸을 때의 동작을 CONCURRENT, SKIP, DELAY 옵션으로 정교하게 제어합니다.
• 동적 제어 및 관측 가능성: 실시간 일시정지(pause), 재개(resume), 취소(cancel) 및 라이프사이클 이벤트 리스너를 제공합니다.
• 어노테이션 자동 스캔: 스프링 스타일의 선언적 배치 환경을 순수 자바 코드로 지원합니다.

아키텍처 및 워크플로우

Chronos는 자바 내장 ScheduledExecutorService를 심장으로 채택하고 있으며, 매 실행 시점마다 실제 현재 시각(LocalDateTime.now())을 기준으로 다음 타점을 정밀 연산하여 스레드 오차 누적을 원천 차단합니다.

[Builder / Annotation] ──> [TaskContext] ──> [Chronos] ──> [ChronosEngine]

시작하기 (Quick Start)

repositories {
    maven {
        name = "Elex Repository"
        url = uri("https://artifacts.elex-project.com/repository/maven/")
    }
}
dependencies {
    implementation("com.elex-project:chronos:1.0.0")
}

1. 환경 설정 (Configuration)

애플리케이션이 켜지는 시점(예: 메인 메서드 진입부)에 프로젝트 규모에 맞는 스레드 풀 크기를 지정합니다. (기본값: 4)

// 대규모 배치를 위해 스레드 풀 크기를 8개로 지정
Chronos.init(8);

2. 기본 사용법 (Fluent Chain API)

// 1초 뒤 시작하여 5초마다 반복 실행하는 작업
Chronos.scheduler()
       .id("sync-task")
       .task(() -> System.out.println("데이터 동기화 중..."))
       .every(5, TimeUnit.SECONDS)
       .initialDelay(1, TimeUnit.SECONDS)
       .withPolicy(OverlapPolicy.SKIP) // 이전 작업이 끝나지 않았으면 패스
       .schedule();

3. 크론 표현식 연동 (Cron Expression)

// 평일(월~금) 오전 9시부터 오후 6시 사이에 10분마다 실행
Chronos.scheduler()
       .id("cron-batch")
       .task(() -> System.out.println("정기 지표 계산..."))
       .cron("0 */10 9-18 * * ?")
       .onStart(ctx -> System.out.println("작업 시작: " + ctx.getTaskId()))
       .onSuccess((ctx, time) -> System.out.println("완료! 소요시간: " + time + "ms"))
       .onFailure((ctx, ex) -> System.err.println("에러: " + ex.getMessage()))
       .schedule();

4. 어노테이션 기반 자동 스캔 (Annotation Scanning)

배치 클래스에 @ChronosScheduler를, 메서드에 @Task를 마킹하여 한 번에 등록할 수 있습니다.

@ChronosScheduler
public class SystemJobs {

    @Task(every = 1, unit = TimeUnit.HOURS, initialDelay = 5)
    public void clearTemporaryFiles() {
        System.out.println("임시 파일 청소 중...");
    }
}

// 메인 메서드에서 패키지 스캔 시작
Chronos.startScan("com.example.app.jobs");

런타임 동적 제어 (Runtime Management)

Chronos를 활용하면 애플리케이션을 재부팅하지 않고 런타임 도중에 특정 태스크를 주무를 수 있습니다.

Chronos manager = Chronos.getInstance();

// 특정 작업 일시 정지 및 재개
manager.pause("sync-task");
manager.resume("sync-task");

// 특정 작업 완전히 취소 및 예약 제거
manager.cancel("sync-task");

// 전체 스케줄러 엔진 안전 종료 (Graceful Shutdown)
manager.shutdown();

오버랩 정책 (Overlap Policy) 소개

정책	설명
CONCURRENT	(기본값) 이전 작업 완료 여부와 상관없이 주기마다 새 스레드에서 즉시 실행
SKIP	이전 작업이 아직 실행 중이라면 이번 주기에 도래한 작업은 과감히 건너뜀
DELAY	이전 작업이 지연된 만큼 대기한 후, 끝난 시점부터 다음 주기를 다시 계산하여 지연 실행

---

Copyrght 2026© Elex. All rights reserved.