Creates a clean set of Pico examples

examples/pico/README.md

@@ -0,0 +1,12 @@
+
+# Helidon Pico Examples
+
+Each subdirectory contains example code that highlights specific aspects of
+Helidon Pico.
+
+Suggested path to follow:
+1. [basics](./basics)
+2. [providers](./providers)
+3. [configdriven](./configdriven)
+4. [interceptors](./interceptors)
+5. [application](./application)

examples/pico/application/README.md

@@ -0,0 +1,50 @@
+# Helidon Pico Application Example
+
+This example shows how a multi-module application can be created using Helidon Pico. The
+[Main.java](./src/main/java/io/helidon/examples/pico/application/Main.java) class shows:
+
+* multi-module usage (i.e., this module amalgamates [basics](../basics), [providers](../providers), [configdriven](../configdriven), and [interceptors](../interceptors) ).
+* compile-time generation of the DI model for the entire multi-module project using the _pico-maven-plugin_ (see [pom.xml](./pom.xml)).
+* TestingSupport in [ApplicationTest](src/test/java/io/helidon/examples/pico/application/PicoApplicationTest.java)
+
+## Build and run
+
+```bash
+mvn package
+java -jar target/helidon-examples-pico-application.jar
+```
+
+Expected Output:
+```
+Startup service providers (ranked according to weight, pre-activated): [ToolBox:INIT, CircularSaw:INIT, NailGun:INIT, TableSaw:INIT]
+Highest weighted service provider: NailGun:INIT
+-----
+Nail Gun: (nail provider=NailProvider:INIT); initialized
+Highest weighted service provider (after activation): io.helidon.examples.pico.providers.NailGun@7cbd9d24
+-----
+Preferred Big Tool: Big Hammer
+Optional Little Hammer: Optional[Little Hammer]
+-----
+ToolBox Contents:
+Hammer:INIT
+BigHammer:ACTIVE
+LittleHammer:ACTIVE
+Drill{root}:PENDING
+AngleGrinderSaw:INIT
+CircularSaw:INIT
+HandSaw:INIT
+NailGun:ACTIVE
+TableSaw:INIT
+-----
+io.helidon.examples.pico.providers.CircularSaw::<init> will be injected with Optional.empty
+Circular Saw: (blade=null); initialized
+io.helidon.examples.pico.providers.TableSaw::<init> will be injected with Optional[LARGE Blade]
+Table Saw: (blade=LARGE Blade); initialized
+All service providers (after all activations): [ToolBox:ACTIVE, CircularSaw:ACTIVE, NailGun:ACTIVE, TableSaw:ACTIVE]
+-----
+Service lookup count: 2
+```
+
+While the output of this example may look similar to the previous [providers](../providers) example, the implementation is different since this example builds (at compile time) [Application.java](target/generated-sources/annotations/io/helidon/examples/pico/application/Pico$$Application.java). This establishes direct bindings to each and every injection point in your application avoiding runtime resolution with the exception for truly dynamic runtime providers (i.e., anything that is config-driven services or _Provider_ type implementations).
+
+Note that the lookup count is 2 based upon the direct lookup calls used in the delegated [Main](../basics/src/main/java/io/helidon/examples/pico/basics/Main.java).

examples/pico/application/pom.xml

@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2023 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.
+
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.applications</groupId>
+        <artifactId>helidon-nima</artifactId>
+        <version>4.0.0-SNAPSHOT</version>
+        <relativePath>../../../applications/nima/pom.xml</relativePath>
+    </parent>
+    <groupId>io.helidon.examples.pico</groupId>
+    <artifactId>helidon-examples-pico-application</artifactId>
+    <name>Helidon Pico Examples Application</name>
+
+    <description>
+        Example usages of a Pico Application.
+    </description>
+
+    <properties>
+        <mainClass>io.helidon.examples.pico.providers.Main</mainClass>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.helidon.examples.pico</groupId>
+            <artifactId>helidon-examples-pico-providers</artifactId>
+            <version>${helidon.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.examples.pico</groupId>
+            <artifactId>helidon-examples-pico-configdriven</artifactId>
+            <version>${helidon.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.annotation</groupId>
+            <artifactId>jakarta.annotation-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.pico</groupId>
+            <artifactId>helidon-pico-testing</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>io.helidon.pico</groupId>
+                <artifactId>helidon-pico-maven-plugin</artifactId>
+                <version>${helidon.version}</version>
+                <executions>
+                    <execution>
+                        <id>compile</id>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>application-create</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>testCompile</id>
+                        <phase>test-compile</phase>
+                        <goals>
+                            <goal>test-application-create</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <packageName>io.helidon.examples.pico.application</packageName>
+                    <!-- choice of NAMED, NONE, ALL - see PermittedProviderType -->
+                    <permittedProviderTypes>NAMED</permittedProviderTypes>
+                    <permittedProviderTypeNames>
+                        <permittedProviderTypeName>io.helidon.examples.pico.providers.BladeProvider</permittedProviderTypeName>
+                        <permittedProviderTypeName>io.helidon.examples.pico.providers.NailProvider</permittedProviderTypeName>
+                    </permittedProviderTypeNames>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-libs</id>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

examples/pico/application/src/main/java/io/helidon/examples/pico/application/Main.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2023 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.examples.pico.application;
+
+import io.helidon.pico.api.Metrics;
+import io.helidon.pico.api.PicoServices;
+
+/**
+ * Application example. Uses the same {@code main()} as {@link io.helidon.examples.pico.basics.Main}.
+ */
+public class Main extends io.helidon.examples.pico.basics.Main {
+
+    /**
+     * Executes the example.
+     *
+     * @param args arguments
+     */
+    public static void main(String... args) {
+        io.helidon.examples.pico.basics.Main.main(args);
+
+        Metrics metrics = PicoServices.picoServices().orElseThrow().metrics().get();
+        System.out.println("Service lookup count: " + metrics.lookupCount().get());
+    }
+
+}

examples/pico/application/src/main/java/io/helidon/examples/pico/application/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2023 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.
+ */
+
+/**
+ * Examples of multi-module Application generation in Pico.
+ */
+package io.helidon.examples.pico.application;

examples/pico/application/src/main/resources/logging.properties

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2023 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.
+#
+
+
+handlers = java.util.logging.ConsoleHandler
+
+java.util.logging.ConsoleHandler.level = FINEST
+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+java.util.logging.SimpleFormatter.format = [%1$tc] %4$s: %2$s - %5$s %6$s%n
+
+.level = INFO
+io.helidon.config.level = WARNING
+io.helidon.config.examples.level = FINEST

examples/pico/application/src/test/java/io/helidon/examples/pico/application/PicoApplicationTest.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2023 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.examples.pico.application;
+
+import io.helidon.config.Config;
+import io.helidon.config.ConfigSources;
+import io.helidon.pico.api.PicoServices;
+import io.helidon.pico.api.Services;
+import io.helidon.pico.testing.PicoTestingSupport;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Test;
+
+import static io.helidon.pico.testing.PicoTestingSupport.testableServices;
+
+class PicoApplicationTest {
+
+    protected PicoServices picoServices;
+    protected Services services;
+
+    @AfterAll
+    static void tearDown() {
+        PicoTestingSupport.resetAll();
+    }
+
+    protected void resetWith(Config config) {
+        PicoTestingSupport.resetAll();
+        this.picoServices = testableServices(config);
+        this.services = picoServices.services();
+    }
+
+    @Test
+    void main() {
+        Config config = Config.builder()
+                .addSource(ConfigSources.classpath("application.yaml"))
+                .disableSystemPropertiesSource()
+                .disableEnvironmentVariablesSource()
+                .build();
+        resetWith(config);
+        Main.main();
+    }
+
+}

examples/pico/basics/README.md

@@ -0,0 +1,35 @@
+# Helidon Pico Basic Example
+
+This example shows the basics of using Helidon Pico. The
+[Main.java](./src/main/java/io/helidon/examples/pico/basics/Main.java) class shows:
+
+* programmatic lookup of services in Pico's Services registry in [Main](./src/main/java/io/helidon/examples/pico/basics/Main.java).
+* declarative injection in [ToolBox.java](./src/main/java/io/helidon/examples/pico/basics/ToolBox.java).
+* lifecycle via <b>PostConstruct</b> and <b>RunLevel</b> in [Main](./src/main/java/io/helidon/examples/pico/basics/Main.java).
+* annotation processing and source code generation (see [pom.xml](pom.xml) and [generated-sources](./target/generated-sources/annotations/io/helidon/examples/pico/basics)).
+
+## Build and run
+
+```bash
+mvn package
+java -jar target/helidon-examples-pico-basics.jar
+```
+
+Expected Output:
+```
+Startup service providers (ranked according to weight, pre-activated): [ToolBox:INIT]
+Highest weighted service provider: ToolBox:INIT
+-----
+Preferred Big Tool: Big Hammer
+Optional Little Hammer: Optional[Little Hammer]
+-----
+ToolBox Contents:
+Hammer:INIT
+BigHammer:ACTIVE
+LittleHammer:ACTIVE
+-----
+Highest weighted service provider (after activation): ToolBox
+-----
+All service providers (after all activations): [ToolBox:ACTIVE]
+-----
+```