Converting Recorders To Services

Converting Recorders to Services

Architecture

The ServiceRegistrar service system replaces @Recorder with typed service. Services declare dependencies explicitly and execute in dependency order, not build step order. The system is designed for incremental migration — converted and unconverted extensions may coexist.

Key principles

1. Explicit dependencies only. Services get NO implicit ordering from the build step graph. All ordering comes from require(), after(), before(), or afterBuildItem().
2. Services are independent from recorders in the same step. Even if a build step method contains both a @Record call and an ServiceRegistrar call, the service and recorder are separate nodes with no implicit ordering between them.
3. Values flow through the dependency graph. Service values are passed from producer to consumer via indexed dependency access on ServiceNode, not through the StartupContext maps (except for recorder proxy bridges).

Node types in the service graph

Legacy recorders and aliases use step-graph ordering for compatibility. Service nodes use only explicit declarations.

Prerequisites

Before converting, verify that all runtime dependencies are available as services:

Conversion steps

1. Analyze the recorder

For each @Recorder method, determine:

• Return type — becomes the service type. RuntimeValue<X> unwraps to X. void becomes Void.class with a descriptive name.
• Parameters — RuntimeValue<X> params become require(X.class). Simple values (String, int, boolean, enum) can be captured. Immutable collections (List.of(), Set.of(), etc.) can be captured.
• Instance fields — config RuntimeValues injected via constructor become require() dependencies.
• Trivial methods — inline directly into the lambda.

2. Convert the recorder class

• Trivial methods — delete; inline into the lambda.
• Complex methods — remove @Recorder, make methods static, unwrap RuntimeValue parameters and return types.
• If all methods are converted, delete the class. Otherwise keep @Recorder for remaining methods.

3. Convert the build step

Before:

@BuildStep
@Record(ExecutionTime.RUNTIME_INIT)
ServiceStartBuildItem setup(MyRecorder recorder, SomeBuildItem item) {
    recorder.initialize(item.getValue());
    return new ServiceStartBuildItem("my-feature");
}

After:

@BuildStep
ServiceStartBuildItem setup(ServiceRegistrar serviceRegistrar, SomeBuildItem item) {
    serviceRegistrar
        .forService("io.quarkus.my-feature.setup")
        .onStart(ctx -> MyRecorder.initialize());
    return new ServiceStartBuildItem("my-feature");
}

Key changes:

• Remove @Record(ExecutionTime.*) annotation.
• Replace recorder parameter with ServiceRegistrar serviceRegistrar.
• Use .atPhase(Phase.STATIC_INIT) for static-init services (default is runtime-init / Phase.APPLICATION).
• For void services, use hierarchical dot-separated names: "io.quarkus.<extension>.<purpose>".

4. Declare dependencies

Every dependency must be explicit. There is no implicit ordering from the build step graph.

afterBuildItem() — bridging to build step ordering

When a service depends on state produced by a legacy recorder (e.g., synthetic beans must be initialized), declare the dependency via afterBuildItem():

serviceRegistrar
    .forService("io.quarkus.arc.lifecycle")
    .afterBuildItem(SyntheticBeansRuntimeInitBuildItem.class)
    .onStart(ctx -> ArcRecorder.fireLifecycleEvent(new StartupEvent()));

This resolves the producing step's nodes (with passthrough resolution for steps that have no service graph nodes) and creates ordering edges.

afterBuildItem() is deprecated — it exists only for recorder coexistence. Once the producing recorder is converted to a service, replace with require() or after(), or drop it, as appropriate.

Cross-phase dependencies

Runtime services can require() static-init services. The framework automatically creates a CROSS_PHASE_PROXY node that reads the value from the serviceValues map (populated during static-init and retained via retainServiceValues()).

// static-init service
serviceRegistrar.forService(ArcContainer.class)
    .atPhase(Phase.STATIC_INIT)
    .afterBuildItem(ResourcesGeneratedPhaseBuildItem.class)
    .onStart(ctx -> Arc.initialize());

// runtime service that depends on it
serviceRegistrar.forService("io.quarkus.my-ext.setup")
    .require(ArcContainer.class)  // cross-phase: resolved via proxy
    .onStart((ctx, container) -> { ... });

Config mappings

• BUILD_TIME — extract values into locals before the lambda.
• BUILD_AND_RUN_TIME_FIXED — use .require(ConfigType.class) (resolved directly from SmallRye Config, no graph edge).
• RUN_TIME — use .require(ConfigType.class) (same mechanism).

5. Stop ordering with before()

before(X) declares "X depends on me" — this service starts before X and stops after X. Use it for cleanup services that must outlive their dependents:

serviceRegistrar
    .forService("io.quarkus.vertx.netty-thread-local-cleanup")
    .atPhase(Phase.STATIC_INIT)
    .before(IOThreadDetector.class)
    .before(ArcContainer.class)
    .onStart(ctx -> {
        ctx.onStop(() -> InternalThreadLocalMap.remove());
    });

6. Bridge to legacy build items

Build items consumed by unconverted extensions need bridge proxies:

Recorder proxies resolve via startupContext.getServiceValue() (for __service$$value() proxies) or startupContext.getValue() (for standard recorder proxies). The service deploy body stores values in the serviceValues map for this resolution.

7. Synthetic beans

Before:

Supplier<MyBean> supplier = recorder.createBeanSupplier(args);
SyntheticBeanBuildItem.configure(MyBean.class).supplier(supplier).done();

After:

serviceRegistrar.forService(MyBean.class, "my-bean-name")
    .onStart(ctx -> new MyBean(args));

SyntheticBeanBuildItem.configure(MyBean.class)
    .serviceValue(MyBean.class, "my-bean-name")
    .done();

8. Shutdown handlers

Register cleanup via ctx.onStop(Runnable) or ctx.onStopAsync(Consumer<AsyncStopContext>). Stop handlers run in reverse dependency order.

addLastShutdownTask() is deprecated — its per-node "last" semantics don't provide global ordering. Use before() to ensure your service stops after the services it cleans up for.

9. Runtime-optional services

A value-producing service must return a non-null value — the generated code throws "...returned null; use a void service if no value is produced" otherwise. For a service whose identity is known at build time but which may be absent at runtime (e.g. a handler gated by quarkus.log.file.enabled), declare optional() before onStart(). This flips the service's return type from T to Optional<T>; returning Optional.empty() marks the service absent (nothing constructed, no side effects) instead of failing.

serviceRegistrar.forService(Handler.class, "file")
    .atPhase(Phase.LOGGING)
    .require(LogRuntimeConfig.class)
    .optional()
    .onStart((ctx, config) -> config.file().enabled()
        ? Optional.of(buildFileHandler(config.file()))
        : Optional.empty());

Consuming an optional service:

• consumeAll(T.class) skips absent producers (the map omits them).
• request(T.class) yields Optional.empty() when absent.
• require(T.class) on an optional service is a build error — a mandatory dependency cannot depend on a maybe-absent value. Use request() or consumeAll() instead.

Do not return null from a normal (non-optional) service, and do not use a sentinel value — optional() is the supported mechanism. (The null tolerance in consumeAll applies only to aliased recorder values that resolve to null, not to direct services.)

10. Lambda capture rules

Supported captures:

• Primitives, String, Class, enum values
• Immutable collections: List.of(), Set.of(), Map.of(), Collections.singletonList/Set/Map(), Collections.empty*(), Collections.unmodifiable*(), Set.copyOf(), List.copyOf(), Map.copyOf()
• BUILD_AND_RUN_TIME_FIXED config mappings (via ConfigCaptureInterceptor)
• Constable values — any type implementing java.lang.constant.Constable is captured via its describeConstable(). To make a custom value type capturable, implement Constable with a describeConstable() that reconstructs it (e.g. a DynamicConstantDesc invoking a static factory), rather than registering a recorder ObjectSubstitution. Immutable collections of Constable values (via Map.copyOf/List.copyOf) are themselves capturable.
• record values — captured by reconstructing via the canonical constructor, as long as every component is itself capturable (recursively). Note this is the capture path; it is unrelated to the proxy path — a record still cannot be used as an aliased recorder return type (see "Aliased recorder return types must be proxyable" below).

Not capturable:

• Mutable collections — use Set.copyOf() / List.copyOf() first
• BUILD_TIME config objects — extract values into locals
• RUN_TIME config objects — use require() instead
• Arbitrary runtime objects — use require() instead

Common pitfalls

No implicit ordering from build steps

Services get NO ordering from @Consume/@Produce annotations or build item parameters on their build step method. Every ordering dependency must be declared on the service itself.

If a service needs to run after a legacy recorder step, use afterBuildItem() to depend on a build item that step produces.

Concrete class proxying

staticInitServiceAsRecorderValue(ConcreteClass.class) fails if the class has a non-trivial constructor. Use staticInitServiceAsRuntimeValue() instead — RuntimeValue is always proxyable.