From c4419d0cee2de902de55f5809c75f64a0fb81066 Mon Sep 17 00:00:00 2001 From: "igor.petrenko" Date: Thu, 25 Jun 2026 22:01:21 +0300 Subject: [PATCH] add oap-application-annotation docs --- oap-application/README.md | 37 +++++++++++++++++++++++++++++++++++++ pom.xml | 2 +- 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/oap-application/README.md b/oap-application/README.md index f1a773c992..71f26d2a00 100644 --- a/oap-application/README.md +++ b/oap-application/README.md @@ -11,6 +11,7 @@ Services are plain Java classes — no framework annotations required. Everythin - [Application Configuration (application.conf)](#application-configuration-applicationconf) - [Reference Syntax](#reference-syntax) - [Supervision and Service Lifecycle](#supervision-and-service-lifecycle) +- [Lifecycle Annotations](#lifecycle-annotations) - [Dependency Injection Mechanics](#dependency-injection-mechanics) - [Abstract Services](#abstract-services) - [Module Discovery](#module-discovery) @@ -322,6 +323,42 @@ On `kernel.stop()`, the `Supervisor` stops services in reverse registration orde `shutdown.serviceTimeout` (default `5s`) is the warn threshold per service. Set `shutdown.serviceAsyncShutdownAfterTimeout = true` to continue shutdown after a timeout rather than waiting. +### Lifecycle Annotations + +As an alternative to relying on method names (`preStart`, `start`, etc.), lifecycle hooks can be declared with annotations from the `oap.application.annotation` package. The kernel discovers annotated methods at startup regardless of their name. + +| Annotation | Phase | Equivalent supervision field | +|---|---|---| +| `@PreStart` | Before service start | `preStartWith` | +| `@Start` | Service start | `startWith` | +| `@PreStop` | Before service stop | `preStopWith` | +| `@Stop` | Service stop | `stopWith` | + +Annotations and name-based discovery are independent — both are applied. An annotated method named `start` is invoked by both paths; an annotated method with any other name is invoked only via the annotation. + +```java +import oap.application.annotation.PreStart; +import oap.application.annotation.Start; +import oap.application.annotation.PreStop; +import oap.application.annotation.Stop; + +public class MyService { + @PreStart + public void onBeforeStart() { /* runs before start */ } + + @Start + public void onStart() { /* runs on start */ } + + @PreStop + public void onBeforeStop() { /* runs before stop */ } + + @Stop + public void onStop() { /* runs on stop */ } +} +``` + +The service still needs `supervision.supervise = true` in its `oap-module.oap` declaration. + --- ## Dependency Injection Mechanics diff --git a/pom.xml b/pom.xml index 6c15d30555..6f8c5043b8 100644 --- a/pom.xml +++ b/pom.xml @@ -66,7 +66,7 @@ - 25.7.5 + 25.7.6 25.0.1 25.0.0