[Core] Include DefaultObjectFactory as part of the API (#2400)

Cucumber can be used with different ObjectFactory implementations. When
multiple implementations are available the `cucumber.object-factory` property
allows Cucumber to disambiguate between the preferred choice.

Because the `DefaultObjectFactory` was not actually loaded via SPI it was not
possible to explicitly select the default implementation. By using
`cucumber.object-factory=io.cucumber.core.backend.DefaultObjectFactory`
users can now select the `DefaultObjectFactory` implementation.

This may benefit users who use Cucumber in both unit and integration tests.
Some object factory implementations such as Cucumber Spring are slow to startup
using the `DefaultObjectFactory` would allow the suite of unit tests to be
executed faster.

Author: mpkorstanje

core/README.md

@@ -74,10 +74,10 @@ Each property also has an `UPPER_CASE` and `snake_case` variant. For example
 
 ## Backend ##
 
-Backends consist of two components: a `Backend`, and an `ObjectFactory`. They are
-respectively responsible for discovering glue classes, registering step definitions,
-and creating instances of said glue classes. Backend and object factory
-implementations are discovered via SPI.
+Backends consist of two components: a `Backend`, and an optional `ObjectFactory`.
+They are  respectively responsible for discovering glue classes, registering
+step definitions, and creating instances of said glue classes. Backend and
+object factory implementations are discovered via SPI.
 
 ## Plugin ##
 

core/src/main/java/io/cucumber/core/backend/DefaultObjectFactory.java

@@ -0,0 +1,71 @@
+package io.cucumber.core.backend;
+
+import io.cucumber.core.exception.CucumberException;
+import org.apiguardian.api.API;
+
+import java.lang.reflect.Constructor;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Default factory to instantiate glue classes. Loaded via SPI.
+ * <p>
+ * This object factory instantiates glue classes by using their public
+ * no-argument constructor. As such it does not provide any dependency
+ * injection.
+ * <p>
+ * Note: This class is intentionally an explicit part of the public api. It
+ * allows the default object factory to be used even when another object factory
+ * implementation is present through the
+ * {@value io.cucumber.core.options.Constants#OBJECT_FACTORY_PROPERTY_NAME}
+ * property or equivalent configuration options.
+ *
+ * @see ObjectFactory
+ */
+@API(status = API.Status.STABLE, since = "7.1.0")
+public final class DefaultObjectFactory implements ObjectFactory {
+
+    private final Map<Class<?>, Object> instances = new HashMap<>();
+
+    public void start() {
+        // No-op
+    }
+
+    public void stop() {
+        instances.clear();
+    }
+
+    public boolean addClass(Class<?> clazz) {
+        return true;
+    }
+
+    public <T> T getInstance(Class<T> type) {
+        T instance = type.cast(instances.get(type));
+        if (instance == null) {
+            instance = cacheNewInstance(type);
+        }
+        return instance;
+    }
+
+    private <T> T cacheNewInstance(Class<T> type) {
+        try {
+            Constructor<T> constructor = type.getConstructor();
+            T instance = constructor.newInstance();
+            instances.put(type, instance);
+            return instance;
+        } catch (NoSuchMethodException e) {
+            throw new CucumberException(String.format("" +
+                    "%s does not have a public zero-argument constructor.\n" +
+                    "\n" +
+                    "To use dependency injection add an other ObjectFactory implementation such as:\n" +
+                    " * cucumber-picocontainer\n" +
+                    " * cucumber-spring\n" +
+                    " * cucumber-jakarta-cdi\n" +
+                    " * ...ect\n",
+                type), e);
+        } catch (Exception e) {
+            throw new CucumberException(String.format("Failed to instantiate %s", type), e);
+        }
+    }
+
+}

core/src/main/java/io/cucumber/core/backend/ObjectFactory.java

@@ -7,10 +7,8 @@
  * <p>
  * Cucumber scenarios are executed against a test context that consists of
  * multiple glue classes. These must be instantiated and may optionally be
- * injected with dependencies.
- * <p>
- * When multiple {@code ObjectFactory} implementations are available Cucumber
- * will look for a preference in the provided properties or options.
+ * injected with dependencies. The object factory facilitates the creation of
+ * both the glue classes and dependencies.
  *
  * @see java.util.ServiceLoader
  * @see io.cucumber.core.runtime.ObjectFactoryServiceLoader

core/src/main/java/io/cucumber/core/runtime/ObjectFactoryServiceLoader.java

@@ -1,20 +1,30 @@
 package io.cucumber.core.runtime;
 
+import io.cucumber.core.backend.DefaultObjectFactory;
 import io.cucumber.core.backend.ObjectFactory;
 import io.cucumber.core.backend.Options;
 import io.cucumber.core.exception.CucumberException;
 
-import java.lang.reflect.Constructor;
-import java.util.HashMap;
 import java.util.Iterator;
-import java.util.Map;
 import java.util.ServiceLoader;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Loads an instance of {@link ObjectFactory} using the {@link ServiceLoader}
+ * mechanism.
+ * <p>
+ * Will load an instance of the class provided by
+ * {@link Options#getObjectFactoryClass()}. If
+ * {@link Options#getObjectFactoryClass()} does not provide a class and there is
+ * exactly one {@code ObjectFactory} instance available that instance will be
+ * used.
+ * <p>
+ * Otherwise {@link DefaultObjectFactory} with no dependency injection
+ */
 public final class ObjectFactoryServiceLoader {
 
     private final Supplier<ClassLoader> classLoaderSupplier;
@@ -25,28 +35,12 @@ public ObjectFactoryServiceLoader(Supplier<ClassLoader> classLoaderSupplier, Opt
         this.options = requireNonNull(options);
     }
 
-    /**
-     * Loads an instance of {@link ObjectFactory} using the
-     * {@link ServiceLoader} mechanism.
-     * <p>
-     * Will load an instance of the class provided by
-     * {@link Options#getObjectFactoryClass()}. If
-     * {@link Options#getObjectFactoryClass()} does not provide a class and
-     * there is exactly one {@code ObjectFactory} instance available that
-     * instance will be used.
-     * <p>
-     * Otherwise {@link DefaultJavaObjectFactory} with no dependency injection
-     * capabilities will be used.
-     *
-     * @return an instance of {@link ObjectFactory}
-     */
     ObjectFactory loadObjectFactory() {
         Class<? extends ObjectFactory> objectFactoryClass = options.getObjectFactoryClass();
         ClassLoader classLoader = classLoaderSupplier.get();
         ServiceLoader<ObjectFactory> loader = ServiceLoader.load(ObjectFactory.class, classLoader);
         if (objectFactoryClass == null) {
             return loadSingleObjectFactoryOrDefault(loader);
-
         }
 
         return loadSelectedObjectFactory(loader, objectFactoryClass);
@@ -55,17 +49,34 @@ ObjectFactory loadObjectFactory() {
     private static ObjectFactory loadSingleObjectFactoryOrDefault(ServiceLoader<ObjectFactory> loader) {
         Iterator<ObjectFactory> objectFactories = loader.iterator();
 
-        ObjectFactory objectFactory;
-        if (objectFactories.hasNext()) {
+        // Find the first non-default object factory,
+        // or the default as a side effect.
+        ObjectFactory objectFactory = null;
+        while (objectFactories.hasNext()) {
             objectFactory = objectFactories.next();
-        } else {
-            objectFactory = new DefaultJavaObjectFactory();
+            if (!(objectFactory instanceof DefaultObjectFactory)) {
+                break;
+            }
+        }
+
+        if (objectFactory == null) {
+            throw new CucumberException("" +
+                    "Could not find any object factory.\n" +
+                    "\n" +
+                    "Cucumber uses SPI to discover object factory implementations.\n" +
+                    "This typically happens when using shaded jars. Make sure\n" +
+                    "to merge all SPI definitions in META-INF/services correctly");
         }
 
-        if (objectFactories.hasNext()) {
+        // Check if there are no other non-default object factories
+        while (objectFactories.hasNext()) {
             ObjectFactory extraObjectFactory = objectFactories.next();
+            if (extraObjectFactory instanceof DefaultObjectFactory) {
+                continue;
+            }
             throw new CucumberException(getMultipleObjectFactoryLogMessage(objectFactory, extraObjectFactory));
         }
+
         return objectFactory;
     }
 
@@ -80,8 +91,10 @@ private static ObjectFactory loadSelectedObjectFactory(
 
         throw new CucumberException("" +
                 "Could not find object factory " + objectFactoryClass.getName() + ".\n" +
+                "\n" +
                 "Cucumber uses SPI to discover object factory implementations.\n" +
-                "Has the class been registered with SPI and is it available on the classpath?");
+                "Has the class been registered with SPI and is it available on\n" +
+                "the classpath?");
     }
 
     private static String getMultipleObjectFactoryLogMessage(ObjectFactory... objectFactories) {
@@ -90,60 +103,15 @@ private static String getMultipleObjectFactoryLogMessage(ObjectFactory... object
                 .map(Class::getName)
                 .collect(Collectors.joining(", "));
 
-        return "More than one Cucumber ObjectFactory was found in the classpath\n" +
+        return "More than one Cucumber ObjectFactory was found on the classpath\n" +
                 "\n" +
                 "Found: " + factoryNames + "\n" +
                 "\n" +
-                "You may have included, for instance, cucumber-spring AND cucumber-guice as part of\n" +
-                "your dependencies. When this happens, Cucumber can't decide which to use.\n" +
-                "In order to enjoy dependency injection features, either remove the unnecessary dependencies" +
-                "from your classpath or use the `cucumber.object-factory` property or `@CucumberOptions(objectFactory=...)` to select one.\n";
-    }
-
-    /**
-     * Creates glue instances. Does not provide Dependency Injection.
-     * <p>
-     * All glue classes must have a public no-argument constructor.
-     */
-    static class DefaultJavaObjectFactory implements ObjectFactory {
-
-        private final Map<Class<?>, Object> instances = new HashMap<>();
-
-        public void start() {
-            // No-op
-        }
-
-        public void stop() {
-            instances.clear();
-        }
-
-        public boolean addClass(Class<?> clazz) {
-            return true;
-        }
-
-        public <T> T getInstance(Class<T> type) {
-            T instance = type.cast(instances.get(type));
-            if (instance == null) {
-                instance = cacheNewInstance(type);
-            }
-            return instance;
-        }
-
-        private <T> T cacheNewInstance(Class<T> type) {
-            try {
-                Constructor<T> constructor = type.getConstructor();
-                T instance = constructor.newInstance();
-                instances.put(type, instance);
-                return instance;
-            } catch (NoSuchMethodException e) {
-                throw new CucumberException(String.format(
-                    "%s doesn't have an empty constructor. If you need dependency injection, put cucumber-picocontainer on the classpath",
-                    type), e);
-            } catch (Exception e) {
-                throw new CucumberException(String.format("Failed to instantiate %s", type), e);
-            }
-        }
-
+                "You may have included, for instance, cucumber-spring AND cucumber-guice as part\n" +
+                "of your dependencies. When this happens, Cucumber can't decide which to use.\n" +
+                "In order to enjoy dependency injection features, either remove the unnecessary\n" +
+                "dependencies from your classpath or use the `cucumber.object-factory` property\n" +
+                "or `@CucumberOptions(objectFactory=...)` to select one.\n";
     }
 
 }

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

@@ -0,0 +1 @@
+io.cucumber.core.backend.DefaultObjectFactory

core/src/test/java/io/cucumber/core/backend/DefaultObjectFactoryTest.java

@@ -0,0 +1,64 @@
+package io.cucumber.core.backend;
+
+import io.cucumber.core.exception.CucumberException;
+import org.junit.jupiter.api.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsEqual.equalTo;
+import static org.hamcrest.core.IsNot.not;
+import static org.hamcrest.core.IsNull.notNullValue;
+import static org.junit.jupiter.api.Assertions.assertAll;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class DefaultObjectFactoryTest {
+    final ObjectFactory factory = new DefaultObjectFactory();
+
+    @Test
+    void shouldGiveUsNewInstancesForEachScenario() {
+        factory.addClass(StepDefinition.class);
+
+        // Scenario 1
+        factory.start();
+        StepDefinition o1 = factory.getInstance(StepDefinition.class);
+        factory.stop();
+
+        // Scenario 2
+        factory.start();
+        StepDefinition o2 = factory.getInstance(StepDefinition.class);
+        factory.stop();
+
+        assertAll(
+            () -> assertThat(o1, is(notNullValue())),
+            () -> assertThat(o1, is(not(equalTo(o2)))),
+            () -> assertThat(o2, is(not(equalTo(o1)))));
+    }
+
+    @Test
+    void shouldThrowForNonZeroArgPublicConstructors() {
+        CucumberException exception = assertThrows(CucumberException.class,
+            () -> factory.getInstance(NoAccessibleConstructor.class));
+
+        assertThat(exception.getMessage(), is("" +
+                "class io.cucumber.core.backend.DefaultObjectFactoryTest$NoAccessibleConstructor does not have a public zero-argument constructor.\n"
+                +
+                "\n" +
+                "To use dependency injection add an other ObjectFactory implementation such as:\n" +
+                " * cucumber-picocontainer\n" +
+                " * cucumber-spring\n" +
+                " * cucumber-jakarta-cdi\n" +
+                " * ...ect\n"));
+    }
+
+    public static class StepDefinition {
+        // we just test the instances
+    }
+
+    public static class NoAccessibleConstructor {
+        private NoAccessibleConstructor() {
+
+        }
+
+    }
+
+}