Helidon Inject documentation #9742

Verdent · 2025-02-06T14:33:31Z

Description

Fixes #9741

Documentation

Adds user documentation for Helidon Inject

Signed-off-by: David Kral <[email protected]>

edbratt · 2025-02-14T00:09:50Z

docs/src/main/asciidoc/se/injection.adoc

+
+== Overview
+
+Injection is the basic building stone for inversion of control. Dependency injection provides a mechanism to get


I would recommend we start with the basics of Injection and IoC. SE developers, prior to 4.2 would be focused only on procedural coding thus a very brief introduction to what is Injection, what IoC is, why use Injection; why consider adopting IoC will help users. Include why we didn't just adopt CDI (light-weight, smaller, faster, easier to understand, ...) I also think we should describe the goals achieved with Helidon Inject (How/Why is Helidon Inject different from other Injection frameworks that a reader might have used/heard about. Some potential differentiators: -- compile-time generation (immutable images, more secure)-- source-code, not byte-code (easier debugging/stack traces) ... (add more beneficial facets as you think is appropriate).
Give the reader a bit of a primer on Inject, IoC, and set up reason to read further.

Signed-off-by: David Kral <[email protected]>

tomas-langer

Review of examples (injection.adoc will come later).

docs/src/main/java/io/helidon/docs/se/inject/BasicExample.java

tomas-langer · 2025-02-18T10:45:14Z

docs/src/main/java/io/helidon/docs/se/inject/EventsExample.java

+
+    // tag::snippet_6[]
+    @Service.Singleton
+    record MyIdProducer(@Service.Named("id") Event.Emitter<String> emitter) {


It would be better to use custom qualifiers instead of a named qualifier.

If I want this to make sense, I would need to paste custom qualifier creation there as well. What I am trying to do, is to examplain the emitter with qualifier. Since we do provider named one out of the box, it does not need to be made and this is te simplest example from my point of view.

docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java

tomas-langer · 2025-02-18T10:50:05Z

docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java

+    class InjectionPointFactory implements Service.InjectionPointFactory<MyService> {
+
+        @Override
+        public Optional<Service.QualifiedInstance<MyService>> first(Lookup lookup) {


This example is just showing that you can implement a method of an interface, not how to query the lookup, which is the reason this factory exists.

tomas-langer · 2025-02-18T10:50:44Z

docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java

+
+    // tag::snippet_6[]
+    @Service.Singleton
+    @Service.Named("name")


Again, using a name qualifier does not work nicely in this example.

docs/src/main/java/io/helidon/docs/se/inject/InterceptorExample.java

docs/src/main/java/io/helidon/docs/se/inject/ServiceRegistryExample.java

Signed-off-by: David Kral <[email protected]>

tomas-langer · 2025-02-18T10:56:17Z

docs/src/main/asciidoc/se/injection.adoc

+----
+
+== Usage
+To start using Helidon Inject, you need to create both:


It is not really called Helidon Inject anywhere right now. Not sure if that is what we want to use

tomas-langer · 2025-02-18T16:19:13Z

docs/src/main/asciidoc/se/injection.adoc

+@Service.Singleton
+class MyGreetingService implements GreetingContract {
+
+    public String greet(String name) {


Missing @Override

tomas-langer · 2025-02-18T16:45:13Z

docs/src/main/asciidoc/se/injection.adoc

+1. Through a constructor annotated with `@Service.Inject` - each parameter is considered an injection point; this is the recommended way of injecting dependencies (as it can be unit tested easily, and fields can be declared private final)
+2. Through field(s) annotated with `@Service.Inject` - each field is considered an injection point; this is not recommended, as the fields must be accessible (at least package local), and can’t be declared as final
+
+Injected services are picked by the highest weight and implementing the requested contract.


This message seems to be missing something. Weight is suddenly introduced without a link to explanation (or inlined explanation).
Also picked is not very deterministic here.
This is the definition:

Injection points are satisfied by services that match the required contract and qualifiers. If more than one service satisfies an injection point, the service with the highest weight is chosen (see `@Weight`, `Weighted`). If two services have the same weight, the order is undefined. If the injection point accepts a `java.util.List` of contracts, all available services are used to satisfy the injection point ordered by weight.

Weight, Weighted - this should have proper links

tomas-langer · 2025-02-18T16:46:04Z

docs/src/main/asciidoc/se/injection.adoc

+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 the service is unavailable, an empty optional is provided.


"but if the service is unavailable" - if there is no service providing the contract

The injection point asks for a contract, not for a service.

tomas-langer · 2025-02-18T16:47:33Z

docs/src/main/asciidoc/se/injection.adoc

+- `Contract` - Retrieves an instance of another service.
+- `Optional<Contract>` - Retrieves an instance, but if the service is unavailable, 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 for more control.


Not "for more control", but to resolve:

cyclic dependencies

a "storm" of initializations when a service is looked up from the registry

When suppliers are not used, all instances MUST be created when the service instance is created (during construction).

tomas-langer · 2025-02-18T18:01:56Z

docs/src/main/asciidoc/se/injection.adoc

+If you want to use programmatic lookup, there are two main ways to access a `ServiceRegistry` instance:
+
+- Create a new ServiceRegistry instance and search for the desired service.
+- Inject the existing ServiceRegistry instance currently used by Helidon and retrieve services from it.


This should only be used for advanced use cases, as it bypasses a lot of optimizations of the service registry (i.e. build time binding of services to injection points when using the Maven plugin)

tomas-langer · 2025-02-18T18:02:45Z

docs/src/main/asciidoc/se/injection.adoc

+If a service performs any actions during construction or post-construction,
+you must first retrieve an instance from the registry to trigger its initialization.
+
+Special registry operations:


These are advanced methods, which we should not even mention in documentation. Just document the methods that operate on contracts.

tomas-langer · 2025-02-18T18:04:14Z

docs/src/main/asciidoc/se/injection.adoc

+- `TypeName` - the same, but using Helidon abstraction of type names (may have type arguments)
+- `Lookup` - a full search criteria for a registry lookup
+
+== Startup


This seems to be a bit unfinished, as we need explanation of RunLevel and how it is used in generated main class, and in io.helidon.Main.

tomas-langer · 2025-02-18T18:05:33Z

docs/src/main/asciidoc/se/injection.adoc

+All options to start a Helidon application that uses service registry:
+
+- A custom Main method using `ServiceRegistryManager.start(...)` methods, or `ServiceRegistryManager.create(...)` methods
+- A generated `ApplicationMain` - optional feature of the Maven plugin, requires property `generateMain` to be set to `true`


also mention it uses RunLevel actively, but via code generated class.
This is the only approach that is fully reflection free and skips lookups for injection points.

tomas-langer · 2025-02-18T18:08:09Z

docs/src/main/asciidoc/se/injection.adoc

+== Startup
+
+Helidon provides a Maven plugin (`io.helidon.service:helidon-service-maven-plugin`, goal `create-application`) to generate
+build time bindings, that can be used to start the service registry without any classpath discovery and reflection.


ApplicationBinding provides build time bindings of service providers to injection points - this is to avoid lookup at runtime.
It does NOT elimiminate classpath discovery and reflection. To avoid that you need to use the generated ApplicationMain class.

Also classpath discovery does not mean classpath scanning (it sounds a bit bad in here) - we lookup all service.registry and service.loader resources from the classpath - we are not scanning for them (i.e. using only Java features that do not depend on how the classpath is created, so it works in native image as well)

Not sure how much of this should be in the docs, but it seems a bit misleading right now.

Verdent added 4 commits February 6, 2025 12:38

inject documentation first

dbbc4ca

Signed-off-by: David Kral <[email protected]>

lookup and start chapters added

89454d2

Signed-off-by: David Kral <[email protected]>

changed the title level structure

0ea7c60

Signed-off-by: David Kral <[email protected]>

minor improvements to not finished parts and currently skipped ones

51e65ba

Signed-off-by: David Kral <[email protected]>

Verdent self-assigned this Feb 6, 2025

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Feb 6, 2025

Verdent added 6 commits February 6, 2025 15:35

copyright added

05d4b19

Signed-off-by: David Kral <[email protected]>

Factory types clarified

fffc317

Signed-off-by: David Kral <[email protected]>

minor adjustments

0c4f701

Signed-off-by: David Kral <[email protected]>

another improvements

3a69c4b

Signed-off-by: David Kral <[email protected]>

minor adjustments

f006b95

Signed-off-by: David Kral <[email protected]>

some changes from the monday meeting added

feac872

Signed-off-by: David Kral <[email protected]>

edbratt reviewed Feb 14, 2025

View reviewed changes

Minor adjustments and wording updates

6ab68c0

Signed-off-by: David Kral <[email protected]>

tomas-langer self-requested a review February 18, 2025 10:09

tomas-langer requested changes Feb 18, 2025

View reviewed changes

Verdent added 2 commits February 18, 2025 12:53

The first part of example suggestions implemented

21551f0

Signed-off-by: David Kral <[email protected]>

copyright fix

112e22f

Signed-off-by: David Kral <[email protected]>

tomas-langer requested changes Feb 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Helidon Inject documentation #9742

Helidon Inject documentation #9742

Verdent commented Feb 6, 2025

edbratt Feb 14, 2025

tomas-langer left a comment

tomas-langer Feb 18, 2025

Verdent Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025

tomas-langer Feb 18, 2025


		== Overview

		Injection is the basic building stone for inversion of control. Dependency injection provides a mechanism to get

Helidon Inject documentation #9742

Are you sure you want to change the base?

Helidon Inject documentation #9742

Conversation

Verdent commented Feb 6, 2025

Description

Documentation

Choose a reason for hiding this comment

tomas-langer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment