ArC: introduce Arc.requireContainer()

- introduce Arc.requireContainer()
- introduce the quarkus.arc.log-no-container system property to
log diagnostics when Arc.container() returns null

Co-authored-by: Matej Novotny <[email protected]>

Author: mkouba

independent-projects/arc/runtime/src/main/java/io/quarkus/arc/Arc.java

@@ -1,7 +1,12 @@
 package io.quarkus.arc;
 
+import java.lang.StackWalker.StackFrame;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.jboss.logging.Logger;
 
 import io.quarkus.arc.impl.ArcContainerImpl;
 
@@ -12,6 +17,16 @@ public final class Arc {
 
     private static final AtomicReference<ArcContainerImpl> INSTANCE = new AtomicReference<>();
 
+    /**
+     * If this system property is set then log a warning with diagnostic information when {@link Arc#container()} returns
+     * {@code null}.
+     *
+     * @see #container()
+     */
+    private static final String LOG_NO_CONTAINER = "quarkus.arc.log-no-container";
+
+    private static final Logger LOG = Logger.getLogger(Arc.class);
+
     /**
      * Initializes {@link ArcContainer} with default settings.
      * This is equal to using {@code Arc#initialize(ArcInitConfig.INSTANCE)}
@@ -46,15 +61,35 @@ public static ArcContainer initialize(ArcInitConfig config) {
     }
 
     public static void setExecutor(ExecutorService executor) {
-        INSTANCE.get().setExecutor(executor);
+        ArcContainerImpl container = INSTANCE.get();
+        if (container == null) {
+            throw containerNotInitialized();
+        }
+        container.setExecutor(executor);
     }
 
     /**
      *
-     * @return the container instance
+     * @return the container instance or {@code null} if the container is not initialized
      */
     public static ArcContainer container() {
-        return INSTANCE.get();
+        ArcContainer container = INSTANCE.get();
+        if (container == null && System.getProperty(LOG_NO_CONTAINER) != null) {
+            LOG.warn(gatherDiagnosticInfo());
+        }
+        return container;
+    }
+
+    /**
+     * @return the container instance
+     * @throws IllegalStateException if the container is not initialized
+     */
+    public static ArcContainer requireContainer() {
+        ArcContainer container = INSTANCE.get();
+        if (container == null) {
+            throw containerNotInitialized();
+        }
+        return container;
     }
 
     public static void shutdown() {
@@ -70,4 +105,38 @@ public static void shutdown() {
         }
     }
 
+    private static IllegalStateException containerNotInitialized() {
+        String msg = "ArC container not initialized: the container is not started, already shut down, or a wrong class loader was used to load the io.quarkus.arc.Arc class\n"
+                + "\t- CL:  %s\n"
+                + "\t- TCCL: %s";
+        ClassLoader tccl = Thread.currentThread().getContextClassLoader();
+        ClassLoader cl = Arc.class.getClassLoader();
+        return new IllegalStateException(msg.formatted(cl, tccl));
+    }
+
+    private static String gatherDiagnosticInfo() {
+        ClassLoader tccl = Thread.currentThread().getContextClassLoader();
+        ClassLoader cl = Arc.class.getClassLoader();
+        String msg = "\n"
+                + "==============================\n"
+                + "ArC: container not initialized\n"
+                + "------------------------------\n"
+                + "The container is not started, already shut down, or a wrong class loader was used to load the io.quarkus.arc.Arc class.\n"
+                + "\n"
+                + "CL:   %1$s\n"
+                + "TCCL: %2$s\n"
+                + "Stack:\n\t%3$s"
+                + "\n"
+                + "===================================\n";
+        StackWalker walker = StackWalker.getInstance();
+        return msg.formatted(cl, tccl, walker.walk(Arc::collectStack));
+    }
+
+    private static String collectStack(Stream<StackFrame> stream) {
+        return stream
+                .skip(1)
+                .map(Object::toString)
+                .collect(Collectors.joining("\n\t"));
+    }
+
 }

independent-projects/arc/runtime/src/test/java/io/quarkus/arc/impl/ArcContainerTest.java

@@ -0,0 +1,46 @@
+package io.quarkus.arc.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import java.util.logging.LogRecord;
+import java.util.logging.Logger;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.arc.Arc;
+
+public class ArcContainerTest {
+
+    @Test
+    public void testContainer() {
+        InMemoryLogHandler handler = new InMemoryLogHandler();
+        Logger rootLogger = Logger.getLogger("");
+        rootLogger.addHandler(handler);
+        try {
+            System.clearProperty("quarkus.arc.log-no-container");
+            // By default, no action is performed
+            assertNull(Arc.container());
+            assertTrue(handler.records.isEmpty());
+
+            IllegalStateException ise = assertThrows(IllegalStateException.class, () -> Arc.requireContainer());
+            assertTrue(ise.getMessage().contains("ArC container not initialized"));
+
+            // quarkus.arc.log-no-containe=true -> log a warning
+            System.setProperty("quarkus.arc.log-no-container", "true");
+            assertNull(Arc.container());
+            List<LogRecord> records = handler.getRecords();
+            assertEquals(1, records.size());
+            LogRecord record = records.get(0);
+            assertTrue(record.getMessage().contains("ArC: container not initialized"));
+        } finally {
+            System.clearProperty("quarkus.arc.log-no-container");
+            handler.clearRecords();
+            rootLogger.removeHandler(handler);
+        }
+    }
+
+}

independent-projects/arc/runtime/src/test/java/io/quarkus/arc/impl/InMemoryLogHandler.java

@@ -0,0 +1,39 @@
+package io.quarkus.arc.impl;
+
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.logging.Handler;
+import java.util.logging.Level;
+import java.util.logging.LogRecord;
+
+public class InMemoryLogHandler extends Handler {
+
+    final List<LogRecord> records = new CopyOnWriteArrayList<>();
+
+    @Override
+    public void publish(LogRecord record) {
+        records.add(record);
+    }
+
+    @Override
+    public void flush() {
+    }
+
+    @Override
+    public Level getLevel() {
+        return Level.FINE;
+    }
+
+    @Override
+    public void close() throws SecurityException {
+        this.records.clear();
+    }
+
+    public List<LogRecord> getRecords() {
+        return records;
+    }
+
+    void clearRecords() {
+        this.records.clear();
+    }
+}