My Approach for "Support Provider instances with Pico Container"

CHANGELOG.md

@@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- [Java] Support Provider instances with Pico Container ([#2879](https://github.com/cucumber/cucumber-jvm/issues/2879), [#3128](https://github.com/cucumber/cucumber-jvm/pull/3128) Stefan Gasterstädt)
+
 ## [7.33.0] - 2025-12-09
 ### Added
 - [Java] Add `Scenario.getLanguage()` to return the current language ([#3124](https://github.com/cucumber/cucumber-jvm/pull/3124) Stefan Gasterstädt)

cucumber-picocontainer/README.md

@@ -123,3 +123,27 @@ customization. If you want to customize your dependency injection context,
 it is recommended to provide your own implementation of 
 `io.cucumber.core.backend.ObjectFactory` and make it available through
 SPI.
+
+However it is possible to configure additional PicoContainer `Provider`s. For
+example, some step definition classes might require a database connection as a
+constructor argument.
+
+```java
+package com.example.app;
+
+import java.sql.*;
+import io.cucumber.picocontainer.CucumberPicoProvider;
+import org.picocontainer.injectors.Provider;
+
+@CucumberPicoProvider
+public class DatabaseConnectionProvider implements Provider {
+
+    public Connection provide() throws ClassNotFoundException, ReflectiveOperationException, SQLException {
+        // Connecting to MySQL Using the JDBC DriverManager Interface
+        // https://dev.mysql.com/doc/connector-j/en/connector-j-usagenotes-connect-drivermanager.html
+        Class.forName("com.mysql.cj.jdbc.Driver").getDeclaredConstructor().newInstance();
+        return DriverManager.getConnection("jdbc:mysql://localhost:3306/mydb", "mydbuser", "mydbpassword");
+    }
+
+}
+```

cucumber-picocontainer/pom.xml

@@ -16,6 +16,7 @@
         <picocontainer.version>2.15.2</picocontainer.version>
         <apiguardian-api.version>1.1.2</apiguardian-api.version>
         <junit-jupiter.version>5.14.1</junit-jupiter.version>
+        <mockito.version>5.20.0</mockito.version>
     </properties>
 
     <dependencyManagement>
@@ -72,6 +73,12 @@
             <artifactId>junit-vintage-engine</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <version>${mockito.version}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

cucumber-picocontainer/src/main/java/io/cucumber/picocontainer/CucumberPicoProvider.java

@@ -0,0 +1,78 @@
+package io.cucumber.picocontainer;
+
+import org.apiguardian.api.API;
+import org.picocontainer.MutablePicoContainer;
+import org.picocontainer.injectors.Provider;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation is used to provide some additional PicoContainer
+ * {@link Provider} classes.
+ * <p>
+ * An example is:
+ *
+ * <pre>
+ * package some.example;
+ *
+ * import java.sql.*;
+ * import io.cucumber.picocontainer.CucumberPicoProvider;
+ * import org.picocontainer.injectors.Provider;
+ *
+ * &#64;CucumberPicoProvider
+ * public class DatabaseConnectionProvider implements Provider {
+ *     public Connection provide() throws ClassNotFoundException, ReflectiveOperationException, SQLException {
+ *         // Connecting to MySQL Using the JDBC DriverManager Interface
+ *         // https://dev.mysql.com/doc/connector-j/en/connector-j-usagenotes-connect-drivermanager.html
+ *         Class.forName("com.mysql.cj.jdbc.Driver").getDeclaredConstructor().newInstance();
+ *         return DriverManager.getConnection("jdbc:mysql://localhost:3306/mydb", "mydbuser", "mydbpassword");
+ *     }
+ * }
+ * </pre>
+ * <p>
+ * In order to re-use existing {@link Provider}s, you can refer to those like
+ * this:
+ *
+ * <pre>
+ * package some.example;
+ *
+ * import io.cucumber.picocontainer.CucumberPicoProvider;
+ * import some.other.namespace.SomeExistingProvider.class;
+ *
+ * &#64;CucumberPicoProvider(providers = { SomeExistingProvider.class })
+ * public class MyCucumberPicoProviders {
+ * }
+ * </pre>
+ * <p>
+ * Notes:
+ * <ul>
+ * <li>Currently, there is no limitation to the number of
+ * {@link CucumberPicoProvider} annotations. All of these annotations will be
+ * considered when preparing the {@link org.picocontainer.PicoContainer
+ * PicoContainer}.</li>
+ * <li>If there is no {@link CucumberPicoProvider} annotation at all then
+ * (beside the basic preparation) no additional PicoContainer preparation will
+ * be done.</li>
+ * <li>Cucumber PicoContainer uses PicoContainer's {@link MutablePicoContainer}
+ * internally. Doing so, all {@link #providers() Providers} will be added by
+ * {@link MutablePicoContainer#addAdapter(org.picocontainer.ComponentAdapter)
+ * MutablePicoContainer#addAdapter(new ProviderAdapter(provider))}. (If any of
+ * the providers additionally extends
+ * {@link org.picocontainer.injectors.ProviderAdapter ProviderAdapter} then
+ * these will be added directly without being wrapped again.)</li>
+ * <li>For each class there can be only one {@link Provider}. Otherwise an
+ * according exception will be thrown (e.g. {@code PicoCompositionException}
+ * with message "Duplicate Keys not allowed ..."</li>
+ * </ul>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@API(status = API.Status.EXPERIMENTAL)
+public @interface CucumberPicoProvider {
+
+    Class<? extends Provider>[] providers() default {};
+
+}

cucumber-picocontainer/src/main/java/io/cucumber/picocontainer/PicoBackend.java

@@ -0,0 +1,65 @@
+package io.cucumber.picocontainer;
+
+import io.cucumber.core.backend.Backend;
+import io.cucumber.core.backend.Container;
+import io.cucumber.core.backend.Glue;
+import io.cucumber.core.backend.Snippet;
+import io.cucumber.core.resource.ClasspathScanner;
+import io.cucumber.core.resource.ClasspathSupport;
+
+import java.net.URI;
+import java.util.Collection;
+import java.util.List;
+import java.util.function.Supplier;
+import java.util.stream.Stream;
+
+import static io.cucumber.core.resource.ClasspathSupport.CLASSPATH_SCHEME;
+import static io.cucumber.picocontainer.PicoFactory.isProvider;
+import static java.util.Arrays.stream;
+import static java.util.stream.Stream.concat;
+
+final class PicoBackend implements Backend {
+
+    private final Container container;
+    private final ClasspathScanner classFinder;
+
+    PicoBackend(Container container, Supplier<ClassLoader> classLoaderSupplier) {
+        this.container = container;
+        this.classFinder = new ClasspathScanner(classLoaderSupplier);
+    }
+
+    @Override
+    public void loadGlue(Glue glue, List<URI> gluePaths) {
+        gluePaths.stream()
+                .filter(gluePath -> CLASSPATH_SCHEME.equals(gluePath.getScheme()))
+                .map(ClasspathSupport::packageName)
+                .map(classFinder::scanForClassesInPackage)
+                .flatMap(Collection::stream)
+                .filter(clazz -> clazz.isAnnotationPresent(CucumberPicoProvider.class))
+                .flatMap(clazz -> {
+                    CucumberPicoProvider annotation = clazz.getAnnotation(CucumberPicoProvider.class);
+                    if (isProvider(clazz)) {
+                        return concat(Stream.of(clazz), stream(annotation.providers()));
+                    } else {
+                        return stream(annotation.providers());
+                    }
+
+                })
+                .distinct()
+                .forEach(container::addClass);
+    }
+
+    @Override
+    public void buildWorld() {
+    }
+
+    @Override
+    public void disposeWorld() {
+    }
+
+    @Override
+    public Snippet getSnippet() {
+        return null;
+    }
+
+}

cucumber-picocontainer/src/main/java/io/cucumber/picocontainer/PicoBackendProviderService.java

@@ -0,0 +1,17 @@
+package io.cucumber.picocontainer;
+
+import io.cucumber.core.backend.Backend;
+import io.cucumber.core.backend.BackendProviderService;
+import io.cucumber.core.backend.Container;
+import io.cucumber.core.backend.Lookup;
+
+import java.util.function.Supplier;
+
+public final class PicoBackendProviderService implements BackendProviderService {
+
+    @Override
+    public Backend create(Lookup lookup, Container container, Supplier<ClassLoader> classLoader) {
+        return new PicoBackend(container, classLoader);
+    }
+
+}

cucumber-picocontainer/src/main/java/io/cucumber/picocontainer/PicoFactory.java

@@ -1,10 +1,14 @@
 package io.cucumber.picocontainer;
 
+import io.cucumber.core.backend.CucumberBackendException;
 import io.cucumber.core.backend.ObjectFactory;
 import org.apiguardian.api.API;
 import org.picocontainer.MutablePicoContainer;
 import org.picocontainer.PicoBuilder;
+import org.picocontainer.PicoException;
 import org.picocontainer.behaviors.Cached;
+import org.picocontainer.injectors.Provider;
+import org.picocontainer.injectors.ProviderAdapter;
 import org.picocontainer.lifecycle.DefaultLifecycleState;
 
 import java.lang.reflect.Constructor;
@@ -31,34 +35,90 @@ public void start() {
                     .withCaching()
                     .withLifecycle()
                     .build();
+            Set<Class<?>> providers = new HashSet<>();
+            Set<Class<?>> providedClasses = new HashSet<>();
             for (Class<?> clazz : classes) {
-                pico.addComponent(clazz);
+                if (isProvider(clazz)) {
+                    providers.add(clazz);
+                    ProviderAdapter adapter = adapterForProviderClass(clazz);
+                    pico.addAdapter(adapter);
+                    providedClasses.add(adapter.getComponentImplementation());
+                }
+            }
+            for (Class<?> clazz : classes) {
+                // do not add the classes that represent a picocontainer
+                // Provider, and also do not add those raw classes that are
+                // already provided (otherwise this causes exceptional
+                // situations, e.g. PicoCompositionException with message
+                // "Duplicate Keys not allowed. Duplicate for 'class XXX'")
+                if (!providers.contains(clazz) && !providedClasses.contains(clazz)) {
+                    pico.addComponent(clazz);
+                }
             }
         } else {
             // we already get a pico container which is in "disposed" lifecycle,
             // so recycle it by defining a new lifecycle and removing all
             // instances
             pico.setLifecycleState(new DefaultLifecycleState());
-            pico.getComponentAdapters()
-                    .forEach(cached -> ((Cached<?>) cached).flush());
+            pico.getComponentAdapters().forEach(adapters -> {
+                if (adapters instanceof Cached) {
+                    ((Cached<?>) adapters).flush();
+                }
+            });
         }
         pico.start();
     }
 
+    static boolean isProvider(Class<?> clazz) {
+        return Provider.class.isAssignableFrom(clazz);
+    }
+
+    static boolean isProviderAdapter(Class<?> clazz) {
+        return ProviderAdapter.class.isAssignableFrom(clazz);
+    }
+
+    private static ProviderAdapter adapterForProviderClass(Class<?> clazz) {
+        try {
+            Provider provider = (Provider) clazz.getDeclaredConstructor().newInstance();
+            return isProviderAdapter(clazz) ? (ProviderAdapter) provider : new ProviderAdapter(provider);
+        } catch (ReflectiveOperationException | IllegalArgumentException | SecurityException | PicoException e) {
+            throw new CucumberBackendException(e.getMessage(), e);
+        }
+    }
+
     @Override
     public void stop() {
-        pico.stop();
+        if (pico.getLifecycleState().isStarted()) {
+            pico.stop();
+        }
         pico.dispose();
     }
 
     @Override
     public boolean addClass(Class<?> clazz) {
+        checkMeaningfulPicoAnnotation(clazz);
         if (isInstantiable(clazz) && classes.add(clazz)) {
             addConstructorDependencies(clazz);
         }
         return true;
     }
 
+    private static void checkMeaningfulPicoAnnotation(Class<?> clazz) {
+        if (clazz.isAnnotationPresent(CucumberPicoProvider.class)) {
+            CucumberPicoProvider annotation = clazz.getAnnotation(CucumberPicoProvider.class);
+            if (!isProvider(clazz) && (annotation.providers().length == 0)) {
+                throw new CucumberBackendException(String.format("" +
+                        "Glue class %1$s was annotated with @CucumberPicoProvider; marking it as a candidate for declaring "
+                        +
+                        "PicoContainer Provider classes. Please ensure that at least one the following requirements is satisfied:\n"
+                        +
+                        "1) the class implements org.picocontainer.injectors.Provider\n" +
+                        "2) the annotation #providers() refers to at least one class implementing org.picocontainer.injectors.Provider",
+                    clazz.getName()));
+            }
+        }
+    }
+
     @Override
     public <T> T getInstance(Class<T> type) {
         return pico.getComponent(type);

cucumber-picocontainer/src/main/resources/META-INF/services/io.cucumber.core.backend.BackendProviderService

@@ -0,0 +1 @@
+io.cucumber.picocontainer.PicoBackendProviderService