Helidon Inject documentation #9742
Conversation
oracle-contributor-agreement
bot
added
the
OCA Verified
|
|
||
| == Overview | ||
|
|
||
| Injection is the basic building stone for inversion of control. Dependency injection provides a mechanism to get |
There was a problem hiding this comment.
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.
docs/src/main/java/io/helidon/docs/se/inject/EventsExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/FactoryExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/InterceptorExample.java
Outdated
Show resolved
Hide resolved
docs/src/main/java/io/helidon/docs/se/inject/ServiceRegistryExample.java
Show resolved
Hide resolved
| 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. |
There was a problem hiding this comment.
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)
| == 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. |
There was a problem hiding this comment.
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.
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Verdent
force-pushed
the
inject-documentation
branch
from
cf603dd to
b27b204
Compare
| //Injection | ||
| [CARD] | ||
| .Injection | ||
| [icon=message,link=injection.adoc] |
There was a problem hiding this comment.
The only reference to injection document is in the "overview" of Helidon SE. Maybe we need to add a separate node in the SE tree
There was a problem hiding this comment.
Ah... yes, I did not do this yet :-)
| but aligns with concepts like an HTTP request-response cycle or message consumption in a messaging system. | ||
|
|
||
| == Build time | ||
| To ensure everything works correctly, |
There was a problem hiding this comment.
I think it would be good to explain first why we use build time approach and what are the benefits, and then mention what needs to be done.
Or prepare the user for "build time" somewhere in the overview above.
|
|
||
| === RunLevel | ||
| link:{service-registry-base-url}/io/helidon/service/registry/Service.RunLevel.html[`@Service.RunLevel`] | ||
| is the annotation used for specifying the order in which certain services should be created. |
There was a problem hiding this comment.
I would not use "order .. be created".
The run level provides steps in which an application is started, and within each step (i.e. @Service.RunLevel(10)), you may have zero to n services to be started.
The order of creation is defined by @Weight; Run level creates "groups" of services.
| include::{sourcedir}/se/inject/RunLevelExample.java[tag=snippet_1, indent=0] | ||
| ---- | ||
|
|
||
| For better understanding, we can also add helpful method, which get executed upon service construction. |
There was a problem hiding this comment.
This is probably obsoleted by switching to start method.
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Signed-off-by: David Kral <[email protected]>
Description
Fixes #9741
Documentation
Adds user documentation for Helidon Inject