Introduce Pico SPI module

bom/pom.xml

@@ -1402,6 +1402,11 @@
                 <artifactId>helidon-pico-types</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.pico</groupId>
+                <artifactId>helidon-pico-spi</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
 
             <!-- Pico Builder -->
             <dependency>

pico/pom.xml

@@ -46,7 +46,7 @@
     <!-- this will show the progression of what has come over, and what is left to come over -->
     <modules>
         <module>api</module>
-<!--        <module>spi</module>-->
+        <module>spi</module>
         <module>types</module>
         <module>builder</module>
 <!--        <module>config</module>-->

pico/spi/pom.xml

@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2022 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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>io.helidon.pico</groupId>
+        <artifactId>helidon-pico-project</artifactId>
+        <version>4.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>helidon-pico-spi</artifactId>
+    <name>Helidon Pico SPI</name>
+
+    <properties>
+        <!-- jtrent note: enable this once this PR is merged on Builder - https://github.com/helidon-io/helidon/pull/5228 -->
+        <maven.javadoc.skip>true</maven.javadoc.skip>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.helidon.pico</groupId>
+            <artifactId>helidon-pico-types</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.common</groupId>
+            <artifactId>helidon-common</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.inject</groupId>
+            <artifactId>jakarta.inject-api</artifactId>
+            <scope>compile</scope> <!-- because we have Provider<> dependencies -->
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.pico</groupId>
+            <artifactId>helidon-pico-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.pico.builder</groupId>
+            <artifactId>helidon-pico-builder-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.annotation</groupId>
+            <artifactId>jakarta.annotation-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>javax.inject</groupId>
+            <artifactId>javax.inject</artifactId>
+            <version>${javax.injection.version}</version>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </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>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>io.helidon.pico.builder</groupId>
+                            <artifactId>helidon-pico-builder-processor</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

pico/spi/src/main/java/io/helidon/pico/spi/ActivationLog.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2022 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.pico.spi;
+
+import java.util.Optional;
+
+/**
+ * Tracks the transformations of {@link ServiceProvider}'s {@link ActivationStatus} in lifecycle activity (i.e., activation startup
+ * and deactivation shutdown).
+ *
+ * @see Activator
+ * @see DeActivator
+ */
+public interface ActivationLog {
+
+    /**
+     * Expected to be called during service creation and activation to capture the activation log transcripts.
+     *
+     * @param entry the log entry to record
+     * @return the activation log entry
+     */
+    ActivationLogEntry<?> recordActivationEvent(ActivationLogEntry<?> entry);
+
+    /**
+     * Optionally provide a means to query the activation log.
+     *
+     * @return the optional query API of log activation records
+     */
+    default Optional<ActivationLogQuery> toQuery() {
+        return Optional.empty();
+    }
+
+}

pico/spi/src/main/java/io/helidon/pico/spi/ActivationLogEntry.java

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2022 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.pico.spi;
+
+import java.time.OffsetDateTime;
+import java.util.Optional;
+
+import io.helidon.pico.builder.api.Builder;
+
+/**
+ * Log entry for lifecycle related events  (i.e., activation startup and deactivation shutdown).
+ *
+ * @see io.helidon.pico.spi.ActivationLog
+ * @see io.helidon.pico.spi.Activator
+ * @see io.helidon.pico.spi.DeActivator
+ * @param <T> the service type
+ */
+@Builder
+interface ActivationLogEntry<T> {
+
+    /**
+     * The activation event.
+     */
+    enum Event {
+
+        /**
+         * Starting.
+         */
+        STARTING,
+
+        /**
+         * Finished.
+         */
+        FINISHED
+    }
+
+    /**
+     * The managing service provider.
+     *
+     * @return the managing service provider
+     */
+    ServiceProvider<T> serviceProvider();
+
+    /**
+     * The event.
+     *
+     * @return the event
+     */
+    Event event();
+
+    /**
+     * The starting activation phase.
+     *
+     * @return the starting activation phase
+     */
+    ActivationPhase startingActivationPhase();
+
+    /**
+     * The eventual/desired/target activation phase.
+     *
+     * @return the eventual/desired/target activation phase
+     */
+    ActivationPhase targetActivationPhase();
+
+    /**
+     * The finishing phase at the time of this event / log entry.
+     *
+     * @return the actual finishing phase
+     */
+    ActivationPhase finishingActivationPhase();
+
+    /**
+     * The finishing activation status at the time of this event / log entry.
+     *
+     * @return the activation status
+     */
+    ActivationStatus finishingStatus();
+
+    /**
+     * The time this event was generated.
+     *
+     * @return the time of the event
+     */
+    OffsetDateTime time();
+
+    /**
+     * Any observed error during activation.
+     *
+     * @return any observed error
+     */
+    Optional<Throwable> error();
+
+    /**
+     * The thread id that the event occurred on.
+     *
+     * @return the thread id
+     */
+    Long getThreadId();
+
+}

pico/spi/src/main/java/io/helidon/pico/spi/ActivationLogQuery.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2022 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.pico.spi;
+
+import java.util.List;
+
+/**
+ * Provide a means to query the activation log.
+ *
+ * @see ActivationLog
+ */
+public interface ActivationLogQuery {
+
+    /**
+     * Clears the activation log.
+     */
+    void clear();
+
+    /**
+     * The full transcript of all services phase transitions being managed.
+     *
+     * @return the activation log if log capture is enabled
+     */
+    List<ActivationLogEntry<?>> fullActivationLog();
+
+    /**
+     * A filtered list only including service providers.
+     *
+     * @param serviceProviders the filter
+     * @return the filtered activation log if log capture is enabled
+     */
+    List<ActivationLogEntry<?>> serviceProviderActivationLog(ServiceProvider<?>... serviceProviders);
+
+    /**
+     * A filtered list only including service providers.
+     *
+     * @param serviceTypeNames the filter
+     * @return the filtered activation log if log capture is enabled
+     */
+    List<ActivationLogEntry<?>> serviceProviderActivationLog(String... serviceTypeNames);
+
+    /**
+     * A filtered list only including service providers.
+     *
+     * @param instances the filter
+     * @return the filtered activation log if log capture is enabled
+     */
+    List<ActivationLogEntry<?>> managedServiceActivationLog(Object... instances);
+
+}