Injection is a way to automatically provide instances of dependencies without having to create them manually. Instead of a class creating an object itself, something else (like a service registry) hands it over when needed. This makes code cleaner, easier to manage, and more flexible.

For example, if a Car needs an Engine, instead of the Car making an Engine itself, it just asks for one, and the system provides it. This is called Dependency Injection (DI).

In a declarative approach, you use annotations on classes, constructors, and constructor arguments to express your intent.

For example, instead of manually managing dependencies, you declare that a class should be injectable using annotations like @Service.Singleton (More about that later).

See Helidon Declarative

A service registry is a tool that enables declarative programming by supporting inversion of control (IoC).

It manages the lifecycle of services, handles dependency injection, and ensures that the correct instances are provided where needed and without requiring manual instantiation.

Instead of manually creating an instance of a certain type, you can delegate its creation to the service registry.

This allows the registry to handle the entire instantiation process and provide the instance when needed, ensuring proper lifecycle management and dependency resolution.

A contract is a type that defines what the service registry should provide. It represents an API that will be used.

For simplicity, a contract can be thought of as an interface, but it can also be an abstract class or even a concrete class.

interface GreetingContract {

    String greet(String name);

}

This can be either a concrete class, which implements the contract (or is contract itself if it was a concrete class), or it can be a factory/producer (more about Factories), which creates a new instances to be registered into the service registry.

@Service.Singleton
class MyGreetingService implements GreetingContract {

    @Override
    public String greet(String name) {
        return "Hello %s!".formatted(name);
    }

}

Contract and service can be the same thing, but also separate entities. It all depends on the design of your application and which approach you choose.

Dependencies can be injected in different formats, depending on the required behavior:

• Contract - Retrieves an instance of another service.

• Optional<Contract> - Retrieves an instance, but if there is no service providing the contract, an empty optional is provided.

• List<Contract> - Retrieves all available instances of a given service.

• Supplier<Contract>, Supplier<Optional<Contract>>, Supplier<List<Contract>> - Similar to the above, but the value is only resolved when get() is called, allowing lazy evaluation to resolve cyclic dependencies and a "storm" of initializations when a service is looked up from the registry. When suppliers aren’t used, all instances MUST be created when the service instance is created (during construction).

Annotation processor helidon-service-codegen generates a service descriptor (ServiceProvider__ServiceDescriptor) for each discovered service. This descriptor is discovered at runtime and is used to instantiate the service without relying on reflection, improving performance and reducing overhead during service creation.

Services can be assigned names, allowing them to be specified by name during injection. This ensures that the correct service is injected. To achieve this, we use the @Service.Named annotation.

interface Color {
    String hexCode();
}

@Service.Named("blue")
@Service.Singleton
public class Blue implements Color {

    @Override
    public String hexCode() {
        return "0000FF";
    }
}

@Service.Named("green")
@Service.Singleton
public class Green implements Color {

    @Override
    public String hexCode() {
        return "008000";
    }
}

These named services can now be injected at specific injection points using their assigned names

@Service.Singleton
record BlueCircle(@Service.Named("blue") Color color) {
}

@Service.Singleton
record GreenCircle(@Service.Named("green") Color color) {
}

Alternatively, instead of using string-based names for services, a specific class can be used to "name" them. For this purpose, we use the @Service.NamedByType annotation.

@Service.NamedByType(Green.class)
@Service.Singleton
public class GreenNamedByType implements Color {

    @Override
    public String hexCode() {
        return "008000";
    }
}

The way it is used on the injection point, it is the same as it was in case of the @Service.Named.

@Service.Singleton
record GreenCircleType(@Service.NamedByType(Green.class) Color color) {
}

@Service.Named and @Service.NamedByType are even interchangeable. So it is possible to use @Service.Named annotation with fully qualified class name of a class we used before. Let’s assume for this example, that our previously used class Green was in the my.test package. Now we can specify it as any other String name.

@Service.Singleton
record GreenCircleStringType(@Service.Named("my.test.Green") Color color) {
}

To make custom qualifiers, it is necessary to "meta-annotated" it with @Service.Qualifier.

@Service.Qualifier
public @interface Blue {
}

@Service.Qualifier
public @interface Green {
}

The @Blue and @Green annotations serve as our new qualifiers. It can now be used to qualify services in the same way as @Service.Named.

interface Color {
    String name();
}

@Blue
@Service.Singleton
static class BlueColor implements Color {

    @Override
    public String name() {
        return "blue";
    }
}

@Green
@Service.Singleton
static class GreenColor implements Color {

    @Override
    public String name() {
        return "green";
    }
}

Once the services are created and qualified, they can be injected in the same way as before using the following approach

@Service.Singleton
record BlueCircle(@Blue Color color) {
}

@Service.Singleton
record GreenCircle(@Green Color color) {
}

A factory that supplies a single instance (it can also return Optional<MyContract>)

/**
 * Supplier service factory.
 */
@Service.Singleton
class MyServiceProvider implements Supplier<MyService> {

    @Override
    public MyService get() {
        return new MyService();
    }
}

The ServicesFactory should be used to create zero to n instances at runtime, each assigned different qualifiers if needed. This allows for dynamic and flexible service creation while ensuring proper differentiation between instances based on their qualifiers.

@Service.Singleton
class MyServiceFactory implements Service.ServicesFactory<MyService> {
    @Override
    public List<Service.QualifiedInstance<MyService>> services() {
        var named = Service.QualifiedInstance.create(new MyService(), Qualifier.createNamed("name"));
        var named2 = Service.QualifiedInstance.create(new MyService(), Qualifier.createNamed("name2"));
        return List.of(named, named2);
    }
}

QualifiedFactory is strictly bound to a specific qualifier type. It will get executed only for injection points that are annotated with this selected qualifier and are intended for a selected contract. It will be ignored for any other injection points.

However, there is one special case. If the selected contract is java.lang.Object, the factory will be used for any contract, as long as the qualifier matches.

It receives:

• Qualifier - metadata of the qualifier that is on the annotated injection point, with each annotation property available

• Lookup - information about injection request

• GenericType - injection point type

This allows the factory to create instances dynamically based on the injection point information.

@Service.Qualifier
@interface SystemProperty {
    String value();
}

@Service.Singleton
class SystemProperties {

    private final String httpHost;
    private final String httpPort;

    SystemProperties(@SystemProperty("http.host") String httpHost,
                     @SystemProperty("http.port") String httpPort) {
        this.httpHost = httpHost;
        this.httpPort = httpPort;
    }

}

@Service.Singleton
class SystemPropertyFactory implements Service.QualifiedFactory<String, SystemProperty> {

    @Override
    public Optional<Service.QualifiedInstance<String>> first(Qualifier qualifier,
                                                             Lookup lookup,
                                                             GenericType<String> genericType) {
        return qualifier.stringValue()
                .map(System::getProperty)
                .map(propertyValue -> Service.QualifiedInstance.create(propertyValue, qualifier));
    }

}

InjectionPointFactory is very similar to QualifiedFactory, but with one key difference—it is executed for each injection point and is not bound to a specific qualifier/s (unless specified).

It receives a Lookup object as a parameter, which contains all necessary information about the injection point. This allows the factory to create instances dynamically based on the injection point information. If the factory type T is java.lang.Object, the factory can handle ANY contract - such as when injecting configuration properties, which may be of any type (boolean, int, String etc.)

It is possible to restrict this factory to specific qualifiers by specifying them at the class level of the factory.

This ensures that the factory is executed only for injection points that match the intended contract and qualifier.

@Service.Singleton
class TestClass {

    private final System.Logger logger;

    TestClass(System.Logger logger) {
        this.logger = logger;
    }

}

@Service.Singleton
class LoggerFactory implements Service.InjectionPointFactory<System.Logger> {
    private static final System.Logger DEFAULT_LOGGER = System.getLogger(LoggerFactory.class.getName());

    @Override
    public Optional<Service.QualifiedInstance<System.Logger>> first(Lookup lookup) {
        System.Logger logger = lookup.dependency()
                .map(dep -> System.getLogger(dep.service().fqName()))
                .orElse(DEFAULT_LOGGER);

        return Optional.of(Service.QualifiedInstance.create(logger));
    }
}

The Interception.Intercepted annotation is a marker used to indicate that an annotation should trigger interception.

/**
 * An annotation to mark methods to be intercepted.
 */
@Interception.Intercepted
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Traced {
}

The Interception.Interceptor interface defines an interceptor service that intercepts methods/constructors/fields annotated with the configured marker annotation. The interceptor service must be named by the fully qualified name of the Interception.Intercepted annotation (either via @Service.Named or @Service.NamedByType).

To properly handle the interception chain, the interceptor must always invoke the proceed method if the invocation should continue normally. However, it is also possible to return a custom value directly from the interceptor and effectively bypass the original method execution.

@Service.Singleton
@Service.NamedByType(Traced.class) 
class MyServiceInterceptor implements Interception.Interceptor {
    @Override
    public <V> V proceed(InterceptionContext ctx, Chain<V> chain, Object... args) throws Exception {
        //Do something
        return chain.proceed(args); 
    }
}

• Binds this Interceptor to process elements annotated with @Traced
• Passing interceptor processing to another interceptor in the chain

The @Interception.Delegate annotation enables interception for classes that aren’t created through the service registry but are instead produced by a factory (More about factories can be found here - Factory chapter).

Let’s make the same @Traced annotation and Interceptor as in the previous examples

@Interception.Intercepted
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Traced {
}

@Service.Singleton
@Service.NamedByType(Traced.class)
class MyServiceInterceptor implements Interception.Interceptor {

    @Override
    public <V> V proceed(InterceptionContext ctx, Chain<V> chain, Object... args) throws Exception {
        //Do something
        return chain.proceed(args);
    }
}

Now, let’s create the factory of the service instance.

@Service.Singleton
class MyServiceProvider implements Supplier<MyService> {
    @Override
    public MyService get() {
        return new MyService();
    }
}

Method calls on an instance created this way can’t be intercepted. To enable interception in such cases, we use the @Interception.Delegate annotation. However, keep in mind that usage of this annotation doesn’t add the ability to intercept constructor calls. To enable interception, this annotation must be present on the class that the factory produces. While it is not required on interfaces, it will still work correctly if applied there.

If you need to enable interception for classes using delegation, you should make sure about the following:

• The class must have accessible no-arg constructor (at least package local)

• The class must be extensible (not final)

• The constructor should have no side effects, as the instance will act only as a wrapper for the delegate

• All invoked methods must be accessible (at least package local) and non-final

@Service.Contract
@Interception.Delegate
class MyService {

    @Traced
    String sayHello(String name) {
        return "Hello %s!".formatted(name);
    }

}

The @Interception.ExternalDelegate annotation works similarly to @Interception.Delegate. However, the key difference is that @Interception.ExternalDelegate is designed for classes that you don’t have control over. This means it allows you to apply the interception mechanism even to third-party classes.

It is not required to apply this annotation on the interfaces, however, it needs to be present for classes.

Let’s make the same @Traced annotation and Interceptor as in the previous examples

@Interception.Intercepted
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Traced {
}

@Service.Singleton
@Service.NamedByType(Traced.class)
class MyServiceInterceptor implements Interception.Interceptor {

    @Override
    public <V> V proceed(InterceptionContext ctx, Chain<V> chain, Object... args) throws Exception {
        //Do something
        return chain.proceed(args);
    }
}

In this example, we can’t change the class we’re intercepting in any way. Let’s assume we have this external class, and we need to add an interception mechanism to it.

/**
 * Assume this is the class we have no control over.
 */
class SomeExternalClass {
    @Traced
    String sayHello(String name) {
        return "Hello %s!".formatted(name);
    }
}

Now we need to apply the @Interception.ExternalDelegate annotation on the factory class. Once this is done, interception will work as expected

@Service.Singleton
@Interception.ExternalDelegate(SomeExternalClass.class)
class SomeExternalClassProvider implements Supplier<SomeExternalClass> {
    @Override
    public SomeExternalClass get() {
        return new SomeExternalClass();
    }
}

To begin emitting events, the first step is to define the event type itself.

/**
 * A custom event payload.
 * @param msg message
 */
record MyEvent(String msg) {
}

Event emitters are code generated by Helidon when an injection point is discovered that expects it.

All the emitters are generated as implementations of the Event.Emitter interface.

An event producer is a service that triggers the event by using the event emitter.

To emit an event, inject the desired Event.Emitter Event.Emitter instance, construct the corresponding event object, and call the emit method on the emitter instance.

@Service.Singleton
record MyEventProducer(Event.Emitter<MyEvent> emitter) {

    void produce(String msg) {
        emitter.emit(new MyEvent(msg));
    }
}

The method returns only after all event observers have been notified. If any observer throws an exception, an EventDispatchException is thrown, with all caught exceptions added as suppressed. This ensures that all observers are invoked, even if an exception occurs.

An event observer is a service which processes fired event.

To create an event observer:

• create an observer method, with a single parameter of the event type you want to observe

• annotate the method with @Event.Observer

@Service.Singleton
class MyEventObserver {

    @Event.Observer
    void event(MyEvent event) {
        //Do something with the event
    }
}

A qualified event can be produced with two options:

1. The injection point of @Event.Emitter (the constructor parameter, or field) is annotated with a qualifier annotation
2. The Event.Emitter.emit(..) method is called with explicit qualifier(s), note that if combined, the qualifier specified by the injection point will always be present!

We are using qualifier created in the chapter Custom qualifier, to demonstrate how events work with qualifiers. Now we need to create a new event producer, which fires event only to observers qualified with @Blue.

@Service.Singleton
record MyBlueProducer(@Blue Event.Emitter<String> emitter) {

    void produce(String msg) {
        emitter.emit(msg);
    }
}

To consume a qualified event, observer method must be annotated with the correct qualifier(s). If we want to consume the same messages which are produced by the producer in the example above, our observer needs to be annotated with the same qualifier. In this case it is @Blue.

@Service.Singleton
class MyBlueObserver {

    @Event.Observer
    @Blue
    void event(MyEvent event) {
        //Do something with the event
    }
}

All asynchronous event producers must use the Event.Emitter.emitAsync(..) method instead of the synchronous Event.Emitter.emit(..).

The emitAsync method returns a CompletionStage<MyEvent> instance. When executed, it completes once all event observers have been submitted to the executor service. However, there is no guarantee that any event has been delivered—it may have been sent to anywhere from 0 to n observers (where n represents the number of synchronous observers).

@Service.Singleton
record MyAsyncProducer(Event.Emitter<MyEvent> emitter) {

    void produce(String msg) {
        CompletionStage<MyEvent> completionStage = emitter.emitAsync(new MyEvent(msg));
        //Do something with the completion stage
    }
}

Asynchronous observer methods are invoked from separate threads (through the executor service mentioned above), and their results are ignored by the Event Emitter; if there is an exception thrown from the observer method, it is logged with WARNING log level into logger named EventManager.

To declare an asynchronous observer use annotation @Event.AsyncObserver instead of @Event.Observer.

@Service.Singleton
class MyEventAsyncObserver {

    @Event.AsyncObserver
    void event(MyEvent event) {
        //Do something with the event
    }
}

It is also possible to inject ServiceRegistry. Keep in mind that when injected, the provided instance will be the same one, which is used to create the service instance.

It is possible to create custom ServiceRegistry instance. Keep in mind, this whole process is advanced and should be used only when you know what you are doing.

To create a custom registry and manager instance:

// create an instance of a registry manager - can be configured and shut down
var registryManager = ServiceRegistryManager.create();
// get the associated service registry
var registry = registryManager.registry();

Keep in mind, that custom ServiceRegistryManager must be shut down, once it is not needed.

// create an instance of a registry manager - can be configured and shut down
var registryManager = ServiceRegistryManager.create();
// Your desired logic with ServiceRegistry

// Once ServiceRegistryManager is no longer needed, it needs to be closed
registryManager.shutdown();

Manager is responsible for managing the state of a single ServiceRegistry instance.

When created programmatically, two possible methods can be chosen.

• create - Creates a new ServiceRegistry instance, but does not create any service instance. Service instances are created only when needed.

• start - Creates a new ServiceRegistry instance and creates all services annotated with @Service.RunLevel. See RunLevel chapter.

It is important to note, that once you don’t need your service registry, method shutdown on the manager must be called to ensure proper termination of the service registry.

@Service.RunLevel is the annotation used for specifying the steps in which certain services should be started. It always starts from the lowest number to the highest. It is possible to have one or more services in each run level. When more than one service is defined to a specific run level, the order of creation is defined by @Weight from highest weight to lowest.

When the service manager shuts down it destroys services in the opposite order, from highest run-level value to lowest and, within a single run level, from lowest weight to highest.

We can also add methods which are executed after service construction and before service destruction, respectively.

@Service.RunLevel(1)
@Service.Singleton
class Level1 {

    @Service.PostConstruct
    void onCreate() {
        System.out.println("level1 created");
    }

    @Service.PreDestroy
    void onDestroy() {
        System.out.println("level1 destroyed"); }
}

@Service.RunLevel(2)
@Service.Singleton
class Level2 {

    @Service.PostConstruct
    void onCreate() {
        System.out.println("level2 created");
    }

    @Service.PreDestroy
    void onDestroy() {
        System.out.println("level2 destroyed"); }
}

The easiest way for us to use these annotations, is to use start method on the ServiceRegistryManager.

public static void main(String[] args) {
    ServiceRegistryManager registryManager = ServiceRegistryManager.start();
    registryManager.shutdown();
}

Once executed, we get the following output:

level1 created
level2 created
level2 destroyed
level1 destroyed