feat: add support for JUL

Author: netmikey

README.md

@@ -10,29 +10,36 @@ A Java library for unit-testing logging.
 
 Sometimes, writing specific information into its log(file) is an important part of an application's functionality. As such, it's probably a good idea to cover that behavior in the application's unit tests.
 
-Although there are other solutions to achieve this (like e.g. using mocks and test for the methods to be called), LogUnit aims at testing on another level: right within the logging framework, so you can still see all your logs while testing. No matter how you generate your log messages in your project, if they end up in the popular [Slf4j](https://www.slf4j.org) library, you can use LogUnit (\*).
+Although there are other solutions to achieve this (like e.g. using mocks and test for the methods to be called), LogUnit aims at testing on another level: right within the logging framework, so you can still see all your logs while testing. No matter how you generate your log messages in your project, if they end up in the popular [Slf4j](https://www.slf4j.org) library or in java.util.logging, you can use LogUnit (\*).
 
 
 ## Requirements
 
 - Java 8 or above
 - JUnit 5
-- You must be using Slf4j for logging
-- You must be using Logback as log binding (\*)
+- You must be using Slf4j or java.util.logging for logging
+- You must be using Logback or java.util.logging as log binding (\*)
 
 
 ## Installation
 
 Add LogUnit to your project's dependencies.
 
 * Declare `logunit-core` as compile-time dependency
-* Declare the binding-specific module (e.g. `logunit-logback` (\*) as test-runtime dependency
+* Declare the binding-specific module (e.g. `logunit-logback` or `logunit-jul` (\*)) as test-runtime dependency
 
 ```
 dependencies {
     ...
-    testImplementation("io.github.netmikey.logunit:logunit-core:1.0.1")
-    testRuntimeOnly("io.github.netmikey.logunit:logunit-logback:1.0.1")
+    testImplementation("io.github.netmikey.logunit:logunit-core:1.1.0")
+
+    // Choose one (and only one) of the following:
+
+    // for Logback:
+    // testRuntimeOnly("io.github.netmikey.logunit:logunit-logback:1.1.0")
+
+    // for JUL:
+    // testRuntimeOnly("io.github.netmikey.logunit:logunit-jul:1.1.0")
 }
 ```
 
@@ -92,9 +99,9 @@ See [LogCapturerWithLogbackTest.java](https://github.com/netmikey/logunit/blob/m
 
 LogUnit wants to remain as transparent as possible. That means your unit tests' logs should stay the way they are (or at least as close as possible). As such, we don't want to bring and force our own Slf4j binding implementation onto consuming projects.
 
-Therefor, LogUnit's architecture is similar to Slf4j's: At it's core, it uses the Slf4j API but in order to work at runtime, it provides binding-specific modules for the most popular logging frameworks (\*).
+Therefor, LogUnit's architecture is similar to Slf4j's: At it's core, it uses the Slf4j API but in order to work at runtime, it provides binding-specific modules for hooking into the most popular logging frameworks (\*).
 
 
 ## Limitations
 
-(\*) Currently, only Logback is supported.
+(\*) Currently, only Logback and java.util.logging are supported.

logunit-jul/build.gradle

@@ -0,0 +1,12 @@
+
+description = "LogUnit's JUL (java.util.logging) implementation."
+
+apply from: new File(rootProject.projectDir, 'publishing-build.gradle')
+
+dependencies {
+    api project(':logunit-core')
+
+    implementation("org.junit.jupiter:junit-jupiter-api:${junitVersion}")
+
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:${junitVersion}")
+}

logunit-jul/src/main/java/io/github/netmikey/logunit/jul/JulLogProvider.java

@@ -0,0 +1,180 @@
+package io.github.netmikey.logunit.jul;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.logging.Level;
+import java.util.logging.LogRecord;
+import java.util.logging.Logger;
+import java.util.stream.Collectors;
+import java.util.stream.StreamSupport;
+
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.slf4j.Marker;
+import org.slf4j.event.LoggingEvent;
+
+import io.github.netmikey.logunit.api.LogCapturer;
+import io.github.netmikey.logunit.api.LogProvider;
+
+/**
+ * {@link LogCapturer} implementation based on JUL.
+ */
+public class JulLogProvider implements LogProvider {
+
+    private static final Map<org.slf4j.event.Level, java.util.logging.Level> LEVEL_MAPPING;
+
+    private static final Map<java.util.logging.Level, org.slf4j.event.Level> LEVEL_MAPPING_REVERSE;
+
+    static {
+        Map<org.slf4j.event.Level, java.util.logging.Level> levelMapping = new HashMap<>();
+        levelMapping.put(org.slf4j.event.Level.TRACE, java.util.logging.Level.FINEST);
+        levelMapping.put(org.slf4j.event.Level.DEBUG, java.util.logging.Level.FINE);
+        levelMapping.put(org.slf4j.event.Level.INFO, java.util.logging.Level.INFO);
+        levelMapping.put(org.slf4j.event.Level.WARN, java.util.logging.Level.WARNING);
+        levelMapping.put(org.slf4j.event.Level.ERROR, java.util.logging.Level.SEVERE);
+
+        LEVEL_MAPPING = Collections.unmodifiableMap(levelMapping);
+
+        Map<java.util.logging.Level, org.slf4j.event.Level> levelMappingReverse = new HashMap<>();
+        levelMapping.forEach((key, value) -> levelMappingReverse.put(value, key));
+        levelMappingReverse.put(java.util.logging.Level.CONFIG, org.slf4j.event.Level.INFO);
+        levelMappingReverse.put(java.util.logging.Level.FINER, org.slf4j.event.Level.DEBUG);
+
+        LEVEL_MAPPING_REVERSE = Collections.unmodifiableMap(levelMappingReverse);
+    }
+
+    private final ListHandler listHandler = new ListHandler();
+
+    private final Map<String, Level> loggerNames = new HashMap<>();
+
+    private final Map<String, Level> originalLevels = new HashMap<>();
+
+    @Override
+    public void provideForType(Class<?> type, org.slf4j.event.Level level) {
+        provideForLogger(type.getName(), level);
+    }
+
+    @Override
+    public void provideForLogger(String name, org.slf4j.event.Level level) {
+        if (loggerNames.containsKey(name)) {
+            throw new IllegalArgumentException("LogProvider already providing LogEvents for Logger with name "
+                + name + ". Each logger must only be captured once!");
+        }
+        loggerNames.put(name, mapLevel(level));
+    }
+
+    @Override
+    public List<LoggingEvent> getEvents() {
+        return StreamSupport.stream(listHandler.spliterator(), false)
+            .map(this::mapEvent)
+            .collect(Collectors.toList());
+    }
+
+    @Override
+    public void beforeTestExecution(ExtensionContext context) {
+        addAppenderToLoggingSources();
+    }
+
+    @Override
+    public void afterTestExecution(ExtensionContext context) {
+        listHandler.flush();
+        listHandler.close();
+        detachAppenderFromLoggingSources();
+    }
+
+    private void addAppenderToLoggingSources() {
+        for (Map.Entry<String, Level> logSource : loggerNames.entrySet()) {
+            addAppenderToLogger(logSource.getKey(), logSource.getValue());
+        }
+    }
+
+    private void detachAppenderFromLoggingSources() {
+        for (Map.Entry<String, Level> logSource : loggerNames.entrySet()) {
+            detachAppenderFromLogger(logSource.getKey());
+        }
+    }
+
+    private void addAppenderToLogger(String name, Level level) {
+        addAppenderToLogger((Logger) Logger.getLogger(name), level);
+    }
+
+    private void addAppenderToLogger(Logger logger, Level level) {
+        logger.addHandler(listHandler);
+        originalLevels.put(logger.getName(), logger.getLevel());
+        logger.setLevel(level);
+    }
+
+    private void detachAppenderFromLogger(String name) {
+        detachAppenderFromLogger((Logger) Logger.getLogger(name));
+    }
+
+    private void detachAppenderFromLogger(Logger logger) {
+        logger.removeHandler(listHandler);
+        Level originalLevel = originalLevels.get(logger.getName());
+        if (originalLevel != null) {
+            logger.setLevel(originalLevel);
+        }
+    }
+
+    private LoggingEvent mapEvent(LogRecord record) {
+        return new LoggingEvent() {
+
+            @Override
+            public long getTimeStamp() {
+                return record.getMillis();
+            }
+
+            @Override
+            public Throwable getThrowable() {
+                return record.getThrown();
+            }
+
+            @Override
+            public String getThreadName() {
+                return String.valueOf(record.getThreadID());
+            }
+
+            @Override
+            public String getMessage() {
+                return record.getMessage();
+            }
+
+            @Override
+            public Marker getMarker() {
+                return null;
+            }
+
+            @Override
+            public String getLoggerName() {
+                return record.getLoggerName();
+            }
+
+            @Override
+            public org.slf4j.event.Level getLevel() {
+                return mapLevel(record.getLevel());
+            }
+
+            @Override
+            public Object[] getArgumentArray() {
+                return record.getParameters();
+            }
+        };
+    }
+
+    private Level mapLevel(org.slf4j.event.Level level) {
+        Level result = LEVEL_MAPPING.get(level);
+        if (result == null) {
+            throw new IllegalArgumentException("Cannot map log level " + level + " to a JUL log level");
+        }
+        return result;
+    }
+
+    private org.slf4j.event.Level mapLevel(Level level) {
+        org.slf4j.event.Level result = LEVEL_MAPPING_REVERSE.get(level);
+        if (result == null) {
+            throw new IllegalArgumentException("Cannot map JUL log level " + level + " to an slf4j log level");
+        }
+        return result;
+    }
+}

logunit-jul/src/main/java/io/github/netmikey/logunit/jul/JulLogProviderFactory.java

@@ -0,0 +1,16 @@
+package io.github.netmikey.logunit.jul;
+
+import io.github.netmikey.logunit.api.LogProvider;
+import io.github.netmikey.logunit.api.LogProviderFactory;
+
+/**
+ * JUL implementation of the {@link LogProviderFactory} SPI.
+ */
+public class JulLogProviderFactory implements LogProviderFactory {
+
+    @Override
+    public LogProvider create() {
+        return new JulLogProvider();
+    }
+
+}

logunit-jul/src/main/java/io/github/netmikey/logunit/jul/ListHandler.java

@@ -0,0 +1,39 @@
+package io.github.netmikey.logunit.jul;
+
+import java.util.Spliterator;
+import java.util.concurrent.ConcurrentLinkedQueue;
+import java.util.logging.Handler;
+import java.util.logging.LogRecord;
+
+/**
+ * A {@link Handler} implementation that captures {@link LogRecord}s in a
+ * thread-safe list.
+ */
+public class ListHandler extends Handler {
+
+    private ConcurrentLinkedQueue<LogRecord> list = new ConcurrentLinkedQueue<>();
+
+    @Override
+    public void publish(LogRecord record) {
+        list.add(record);
+    }
+
+    @Override
+    public void flush() {
+        // Nothing to do.
+    }
+
+    @Override
+    public void close() throws SecurityException {
+        // Nothing to do.
+    }
+
+    /**
+     * Get the items.
+     * 
+     * @return A {@link Spliterator} over the items.
+     */
+    public Spliterator<LogRecord> spliterator() {
+        return list.spliterator();
+    }
+}

logunit-jul/src/main/resources/META-INF/services/io.github.netmikey.logunit.api.LogProviderFactory

@@ -0,0 +1 @@
+io.github.netmikey.logunit.jul.JulLogProviderFactory

logunit-jul/src/test/java/io/github/netmikey/logunit/jul/LogCapturerWithJulTest.java

@@ -0,0 +1,86 @@
+package io.github.netmikey.logunit.jul;
+
+import java.util.logging.Logger;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.MethodOrderer.Alphanumeric;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+import org.junit.jupiter.api.extension.RegisterExtension;
+import org.slf4j.event.Level;
+
+import io.github.netmikey.logunit.api.LogCapturer;
+
+/**
+ * Unit test that uses JUL, applies {@link LogCapturer}s and validates their
+ * behavior.
+ */
+@TestMethodOrder(Alphanumeric.class)
+public class LogCapturerWithJulTest {
+
+    @RegisterExtension
+    LogCapturer testLoggerInfoCapturer = LogCapturer.create().captureForType(LogCapturerWithJulTest.class);
+
+    @RegisterExtension
+    LogCapturer namedLoggerWarnCapturer = LogCapturer.create().captureForLogger(LOGGER_NAME, Level.WARN);
+
+    private static final String LOGGER_NAME = "CUSTOM_LOGGER";
+
+    private Logger testLogger = Logger.getLogger(LogCapturerWithJulTest.class.getName());
+
+    private Logger namedLogger = Logger.getLogger(LOGGER_NAME);
+
+    /**
+     * Test
+     * <ul>
+     * <li>that the testLogger (by logger type) captures the INFO level and
+     * above when no level is specified</li>
+     * <li>that the namedLogger (by logger name) captures only the WARN level
+     * and above as specified</li>
+     * <li>both loggers and their capturers don't affeact each other</li>
+     * </ul>
+     */
+    @Test
+    public void test1CaptureMessages() {
+        logEverythingOnce(testLogger);
+        logEverythingOnce(namedLogger);
+
+        Assertions.assertEquals(3, testLoggerInfoCapturer.size(),
+            "should contain each one of INFO, WARNING and SEVERE");
+        testLoggerInfoCapturer.assertDoesNotContain("finest");
+        testLoggerInfoCapturer.assertDoesNotContain("finer");
+        testLoggerInfoCapturer.assertDoesNotContain("fine");
+        testLoggerInfoCapturer.assertDoesNotContain("config");
+        testLoggerInfoCapturer.assertContains("info message");
+        testLoggerInfoCapturer.assertContains("Some warning");
+        testLoggerInfoCapturer.assertContains("severe");
+
+        Assertions.assertEquals(2, namedLoggerWarnCapturer.size(), "should contain each one of WARNING and SEVERE");
+        namedLoggerWarnCapturer.assertDoesNotContain("finest");
+        namedLoggerWarnCapturer.assertDoesNotContain("finer");
+        namedLoggerWarnCapturer.assertDoesNotContain("fine");
+        namedLoggerWarnCapturer.assertDoesNotContain("config");
+        namedLoggerWarnCapturer.assertDoesNotContain("info message");
+        namedLoggerWarnCapturer.assertContains("Some warning");
+        namedLoggerWarnCapturer.assertContains("severe");
+    }
+
+    /**
+     * Test that {@link LogCapturer}s are being reset after each test.
+     */
+    @Test
+    public void test2CapturerReset() {
+        Assertions.assertEquals(0, testLoggerInfoCapturer.size());
+        Assertions.assertEquals(0, namedLoggerWarnCapturer.size());
+    }
+
+    private void logEverythingOnce(Logger logger) {
+        logger.finest("Some finest message");
+        logger.finer("Some finer message");
+        logger.fine("Some fine message");
+        logger.config("Some config message");
+        logger.info("Some info message");
+        logger.warning("Some warning message");
+        logger.severe("Some severe message");
+    }
+}