Helidon Inject documentation (#9742)

Helidon Inject documentation

Signed-off-by: David Kral <david.k.kral@oracle.com>

docs/src/main/asciidoc/includes/attributes.adoc

@@ -229,9 +229,11 @@ endif::[]
 :scheduling-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.scheduling
 :security-integration-jersey-base-url: {javadoc-base-url}/io.helidon.security.integration.jersey
 :security-integration-webserver-base-url: {javadoc-base-url}/io.helidon.webserver.security
+:service-registry-base-url: {javadoc-base-url}/io.helidon.service.registry
 :telemetry-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.telemetry
 :tracing-javadoc-base-url: {javadoc-base-url}/io.helidon.tracing
 :tracing-otel-provider-javadoc-base-url: {javadoc-base-url}/io.helidon.tracing.providers.opentelemetry
+:types-javadoc-base-url: {javadoc-base-url}/io.helidon.common.types
 
 :webclient-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient
 :webserver-javadoc-base-url: {javadoc-base-url}/io.helidon.webserver

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

@@ -78,6 +78,13 @@ Build gRPC servers and clients.
 --
 Expose health statuses of your applications.
 --
+//Injection
+[CARD]
+.Injection
+[icon=colorize,link=injection.adoc]
+--
+Use of the Helidon injection in your applications.
+--
 //Metrics
 [CARD]
 .Metrics

docs/src/main/asciidoc/sitegen.yaml

@@ -405,6 +405,12 @@ backend:
                   - "oci.adoc"
                   - "hcv.adoc"
                   - "neo4j.adoc"
+              - type: "PAGE"
+                title: "Injection"
+                source: "injection.adoc"
+                glyph:
+                  type: "icon"
+                  value: "colorize"
               - type: "MENU"
                 title: "Metrics"
                 dir: "metrics"

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

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.docs.se.inject;
+
+import io.helidon.service.registry.Service;
+import io.helidon.service.registry.ServiceRegistryManager;
+import io.helidon.service.registry.Services;
+
+class BasicExample {
+
+    // tag::snippet_1[]
+    @Service.Singleton
+    class Greeter {
+
+        String greet(String name) {
+            return "Hello %s!".formatted(name);
+        }
+
+    }
+    // end::snippet_1[]
+
+    // tag::snippet_2[]
+    @Service.Singleton
+    class GreetingInjectionService {
+
+        private final Greeter greeter;
+
+        @Service.Inject
+        GreetingInjectionService(Greeter greeter) {
+            this.greeter = greeter;
+        }
+
+        void printGreeting(String name) {
+            System.out.println(greeter.greet(name));
+        }
+    }
+    // end::snippet_2[]
+
+    // tag::snippet_3[]
+    public static void main(String[] args) {
+        var greetings = Services.get(GreetingInjectionService.class);
+        greetings.printGreeting("David");
+    }
+    // end::snippet_3[]
+
+}

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

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.docs.se.inject;
+
+import java.util.concurrent.CompletionStage;
+
+import io.helidon.docs.se.inject.Qualifier2Example.Blue;
+import io.helidon.service.registry.Event;
+import io.helidon.service.registry.Service;
+
+class EventsExample {
+
+    // tag::snippet_1[]
+    /**
+     * A custom event payload.
+     * @param msg message
+     */
+    record MyEvent(String msg) {
+    }
+    // end::snippet_1[]
+
+    // tag::snippet_2[]
+    @Service.Singleton
+    record MyEventProducer(Event.Emitter<MyEvent> emitter) {
+
+        void produce(String msg) {
+            emitter.emit(new MyEvent(msg));
+        }
+    }
+    // end::snippet_2[]
+
+
+    // tag::snippet_3[]
+    @Service.Singleton
+    class MyEventObserver {
+
+        @Event.Observer
+        void event(MyEvent event) {
+            //Do something with the event
+        }
+    }
+    // end::snippet_3[]
+
+
+    // tag::snippet_4[]
+    @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
+        }
+    }
+    // end::snippet_4[]
+
+    // tag::snippet_5[]
+    @Service.Singleton
+    class MyEventAsyncObserver {
+
+        @Event.AsyncObserver
+        void event(MyEvent event) {
+            //Do something with the event
+        }
+    }
+    // end::snippet_5[]
+
+    // tag::snippet_6[]
+    @Service.Singleton
+    record MyBlueProducer(@Blue Event.Emitter<String> emitter) {
+
+        void produce(String msg) {
+            emitter.emit(msg);
+        }
+    }
+    // end::snippet_6[]
+
+    // tag::snippet_7[]
+    @Service.Singleton
+    class MyBlueObserver {
+
+        @Event.Observer
+        @Blue
+        void event(MyEvent event) {
+            //Do something with the event
+        }
+    }
+    // end::snippet_7[]
+
+}

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

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.docs.se.inject;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Supplier;
+
+import io.helidon.common.GenericType;
+import io.helidon.service.registry.Lookup;
+import io.helidon.service.registry.Qualifier;
+import io.helidon.service.registry.Service;
+
+class FactoryExample {
+
+    record MyService() {}
+
+    // tag::snippet_1[]
+    /**
+     * Supplier service factory.
+     */
+    @Service.Singleton
+    class MyServiceProvider implements Supplier<MyService> {
+
+        @Override
+        public MyService get() {
+            return new MyService();
+        }
+    }
+    // end::snippet_1[]
+
+    // tag::snippet_2[]
+    @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);
+        }
+    }
+    // end::snippet_2[]
+
+    // tag::snippet_3[]
+    @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));
+        }
+
+    }
+    // end::snippet_3[]
+
+    // tag::snippet_4[]
+    @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));
+        }
+    }
+    // end::snippet_4[]
+}