From 09c3c58ec7bc00ea7d0fec85354bae8555ffbf2d Mon Sep 17 00:00:00 2001 From: q3769 Date: Sat, 8 Jun 2024 20:41:44 -0500 Subject: [PATCH] + javadoc --- pom.xml | 18 +---- .../engine/NativeLogServiceProvider.java | 75 ++++++++++++++++++- .../service/EventingNativeLoggerService.java | 32 +++++++- .../java/elf4j/engine/service/LogEvent.java | 18 ++++- .../service/NativeLogServiceManager.java | 40 +++++++--- .../engine/service/NativeLoggerService.java | 14 +++- .../engine/service/PerformanceSensitive.java | 11 ++- .../LogServiceConfiguration.java | 2 + .../LoggerOutputLevelThreshold.java | 36 ++++++++- .../service/pattern/ContextElement.java | 23 +++++- .../engine/service/pattern/LogPattern.java | 20 ++++- .../service/util/Elf4jPostTestProcessor.java | 14 +++- .../engine/service/util/StackTraces.java | 12 ++- .../engine/service/writer/GroupWriter.java | 2 + .../java/org/slf4j/MdcAdapterInitializer.java | 5 +- 15 files changed, 276 insertions(+), 46 deletions(-) diff --git a/pom.xml b/pom.xml index 610e64a..d143ddc 100644 --- a/pom.xml +++ b/pom.xml @@ -185,25 +185,13 @@ semver-maven-plugin 20240116.0.202402 - - org.projectlombok - lombok-maven-plugin - 1.18.20.0 - - - generate-sources - - delombok - - - - org.apache.maven.plugins maven-javadoc-plugin 3.6.3 **/_*.java + all,-missing @@ -230,12 +218,12 @@ - 2.44.0 + 2.46.0 true - + diff --git a/src/main/java/elf4j/engine/NativeLogServiceProvider.java b/src/main/java/elf4j/engine/NativeLogServiceProvider.java index ed3710b..ed7fbc0 100644 --- a/src/main/java/elf4j/engine/NativeLogServiceProvider.java +++ b/src/main/java/elf4j/engine/NativeLogServiceProvider.java @@ -44,12 +44,26 @@ import lombok.NonNull; import org.slf4j.MdcAdapterInitializer; -/** */ +/** + * The NativeLogServiceProvider class implements the LogServiceProvider and NativeLogServiceManager.Refreshable + * interfaces. It is responsible for managing and providing NativeLogger instances for logging purposes. It also + * provides methods for refreshing the properties of the log service. + * + *

This class contains a map of native loggers, categorized by their level, and a reference to the class or interface + * that the API client calls first to get a logger instance. The client caller class of this class will be the declaring + * class of the logger instances this factory produces. + * + *

For this native implementation, the service access class is the {@link Logger} interface itself as the client + * calls the static factory method {@link Logger#instance()} first to get a logger instance. If this library is used as + * the engine of another logging API, then this access class would be the class in that API that the client calls first + * to get a logger instance of that API. + */ public class NativeLogServiceProvider implements LogServiceProvider, NativeLogServiceManager.Refreshable { private static final Level DEFAULT_LOGGER_SEVERITY_LEVEL = Level.INFO; /** Made injectable for extensions other than this native ELF4J implementation */ @NonNull private final Level defaultLoggerLevel; + /** A map of native loggers, categorized by their level. */ private final Map> nativeLoggers = EnumSet.allOf(Level.class).stream().collect(toMap(Function.identity(), level -> new ConcurrentHashMap<>())); /** @@ -72,12 +86,21 @@ public NativeLogServiceProvider() { } /** + * NativeLogServiceProvider constructor with the default logger level and the service access class. + * * @param serviceAccessClass the class or interface that the API client application calls first to a logger instance */ public NativeLogServiceProvider(@NonNull Class serviceAccessClass) { this(DEFAULT_LOGGER_SEVERITY_LEVEL, serviceAccessClass, new ConfiguredNativeLoggerServiceFactory()); } + /** + * Constructor for the NativeLogServiceProvider class. + * + * @param defaultLoggerLevel the default logger level + * @param serviceAccessClass the class or interface that the API client application calls first to a logger instance + * @param nativeLoggerServiceFactory the factory for creating native logger services + */ NativeLogServiceProvider( @NonNull Level defaultLoggerLevel, @NonNull Class serviceAccessClass, @@ -101,49 +124,99 @@ public NativeLogger logger() { defaultLoggerLevel, StackTraces.callerOf(serviceAccessClass).getClassName()); } + /** + * Refreshes the properties of the log service. + * + * @param properties the new properties for the log service + */ @Override public void refresh(@Nullable Properties properties) { nativeLoggerServiceFactory.reset(properties); } + /** Reloads the log service. */ @Override public void refresh() { nativeLoggerServiceFactory.reload(); } + /** + * Gets the log service. + * + * @return the log service + */ @NonNull NativeLoggerService getLogService() { return nativeLoggerServiceFactory.getLogService(); } + /** + * Gets a logger with the specified level and declaring class name. + * + * @param level the level of the logger + * @param declaringClassName the name of the declaring class + * @return the logger + */ NativeLogger getLogger(Level level, String declaringClassName) { return nativeLoggers.get(level).computeIfAbsent(declaringClassName, k -> new NativeLogger(k, level, this)); } + /** + * The NativeLoggerServiceFactory interface provides methods for getting the log service, reloading the log service, + * and resetting the log service with the specified properties. + */ interface NativeLoggerServiceFactory { + /** + * Gets the log service. + * + * @return the log service + */ NativeLoggerService getLogService(); + /** Reloads the log service. */ void reload(); + /** + * Resets the log service with the specified properties. + * + * @param properties the new properties for the log service + */ void reset(Properties properties); } + /** + * The ConfiguredNativeLoggerServiceFactory class implements the NativeLoggerServiceFactory interface and provides a + * concrete implementation for getting the log service, reloading the log service, and resetting the log service + * with the specified properties. + */ static class ConfiguredNativeLoggerServiceFactory implements NativeLoggerServiceFactory { private NativeLoggerService nativeLoggerService; + /** Constructor for the ConfiguredNativeLoggerServiceFactory class. */ private ConfiguredNativeLoggerServiceFactory() { nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.byLoading()); } + /** + * Gets the log service. + * + * @return the log service + */ @Override public NativeLoggerService getLogService() { return nativeLoggerService; } + /** Reloads the log service. */ @Override public void reload() { nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.byLoading()); } + /** + * Resets the log service with the specified properties. + * + * @param properties the new properties for the log service + */ @Override public void reset(Properties properties) { nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.bySetting(properties)); diff --git a/src/main/java/elf4j/engine/service/EventingNativeLoggerService.java b/src/main/java/elf4j/engine/service/EventingNativeLoggerService.java index 81f8479..82dbd14 100644 --- a/src/main/java/elf4j/engine/service/EventingNativeLoggerService.java +++ b/src/main/java/elf4j/engine/service/EventingNativeLoggerService.java @@ -37,14 +37,22 @@ import java.util.concurrent.ConcurrentHashMap; import lombok.NonNull; -/** converts a log request into an event for async processing */ +/** + * The EventingNativeLoggerService class implements the NativeLoggerService interface and is responsible for converting + * a log request into an event for async processing. It provides methods for checking if the log should include caller + * detail, for checking if a logger is enabled, and for logging a log event. + */ public class EventingNativeLoggerService implements NativeLoggerService { private final boolean noop; private final LogWriter logWriter; private final LoggerOutputLevelThreshold loggerOutputLevelThreshold; private final Map loggerEnabled = new ConcurrentHashMap<>(); - /** @param logServiceConfiguration parsed configuration for the logger service */ + /** + * Constructor for the EventingNativeLoggerService class. + * + * @param logServiceConfiguration parsed configuration for the logger service + */ public EventingNativeLoggerService(@NonNull LogServiceConfiguration logServiceConfiguration) { if (logServiceConfiguration.isAbsent() || logServiceConfiguration.isTrue("noop")) { noop = true; @@ -58,11 +66,22 @@ public EventingNativeLoggerService(@NonNull LogServiceConfiguration logServiceCo loggerOutputLevelThreshold = LoggerOutputLevelThreshold.from(logServiceConfiguration); } + /** + * Checks if the log should include caller detail such as method, line number, etc. + * + * @return false as the context element does not include caller detail + */ @Override public boolean includeCallerDetail() { return logWriter.includeCallerDetail(); } + /** + * Checks if a logger is enabled. + * + * @param nativeLogger the logger to check + * @return true if the logger is enabled, false otherwise + */ @Override public boolean isEnabled(NativeLogger nativeLogger) { if (noop) { @@ -75,6 +94,15 @@ public boolean isEnabled(NativeLogger nativeLogger) { }); } + /** + * Logs a log event. + * + * @param nativeLogger the logger to use + * @param serviceInterfaceClass the class of the service interface + * @param throwable the throwable to log + * @param message the message to log + * @param arguments the arguments to the message + */ @Override public void log( @NonNull NativeLogger nativeLogger, diff --git a/src/main/java/elf4j/engine/service/LogEvent.java b/src/main/java/elf4j/engine/service/LogEvent.java index 6336b98..0479c26 100644 --- a/src/main/java/elf4j/engine/service/LogEvent.java +++ b/src/main/java/elf4j/engine/service/LogEvent.java @@ -84,17 +84,25 @@ public class LogEvent { return o instanceof Supplier ? ((Supplier) o).get() : o; } - /** @return the name of the application client class calling the logging method of this logger instance */ + /** + * Returns the name of the application client class calling the logging method of this logger instance. + * + * @return the name of the caller class + */ public String getCallerClassName() { return callerFrame != null ? callerFrame.getClassName() : nativeLogger.getDeclaringClassName(); } - /** @return log message text with all placeholder arguments resolved and replaced by final values */ + /** + * Returns the log message text with all placeholder arguments resolved and replaced by final values. + * + * @return the resolved log message + */ public CharSequence getResolvedMessage() { return resolve(this.message, this.arguments); } - /** */ + /** Represents a value representing a call stack element. */ @Value @Builder public static class StackFrameValue { @@ -107,6 +115,8 @@ public static class StackFrameValue { @Nullable String fileName; /** + * Creates a StackFrameValue instance from a StackTraceElement. + * * @param stackTraceElement call stack element * @return log render-able value representing the call stack element */ @@ -120,7 +130,7 @@ public static StackFrameValue from(@NonNull StackTraceElement stackTraceElement) } } - /** */ + /** Represents the value of a thread. */ @Value public static class ThreadValue { @NonNull String name; diff --git a/src/main/java/elf4j/engine/service/NativeLogServiceManager.java b/src/main/java/elf4j/engine/service/NativeLogServiceManager.java index d096140..f59418e 100644 --- a/src/main/java/elf4j/engine/service/NativeLogServiceManager.java +++ b/src/main/java/elf4j/engine/service/NativeLogServiceManager.java @@ -35,10 +35,13 @@ import lombok.NonNull; import lombok.ToString; -/** */ +/** + * The NativeLogServiceManager class is responsible for managing the log service. It provides methods for registering + * and deregistering Refreshable and Stoppable instances, refreshing the configuration, and shutting down the service. + */ @ToString public enum NativeLogServiceManager { - /** */ + /** The singleton instance of the NativeLogServiceManager. */ INSTANCE; private final Set refreshables = new HashSet<>(); @@ -47,13 +50,21 @@ public enum NativeLogServiceManager { @ToString.Exclude private final Lock lock = new ReentrantLock(); - /** @param refreshable added to be accessible for management */ + /** + * Registers a Refreshable instance with the NativeLogServiceManager. + * + * @param refreshable added to be accessible for management + */ public void register(Refreshable refreshable) { lockAndRun(() -> refreshables.add(refreshable)); IeLogger.INFO.log("Registered Refreshable {} in {}", refreshable, this); } - /** @param stoppable added to be accessible for management */ + /** + * Registers a Stoppable instance with the NativeLogServiceManager. + * + * @param stoppable added to be accessible for management + */ public void register(Stoppable stoppable) { lockAndRun(() -> stoppables.add(stoppable)); IeLogger.INFO.log("Registered Stoppable {} in {}", stoppable, this); @@ -70,6 +81,8 @@ public void refresh() { } /** + * Refreshes the configuration for each registered Refreshable instance. + * * @param properties if non-null, replaces current configuration with the specified properties, instead of reloading * from the original properties source; otherwise, reloads the original properties source for each refreshable. */ @@ -82,7 +95,7 @@ public void refresh(Properties properties) { IeLogger.INFO.log("Refreshed elf4j service by {} with properties {}", this, properties); } - /** */ + /** Stops all registered Stoppable instances and clears the set of registered Stoppable instances. */ public void shutdown() { IeLogger.INFO.log("Start shutting down elf4j service by {}", this); lockAndRun(() -> { @@ -93,6 +106,9 @@ public void shutdown() { } /** + * Returns a thread that orderly stops the entire log service. As an alternative to calling {@link #shutdown()}, the + * returned thread can be registered as a JVM shutdown hook. + * * @return a thread that orderly stops the entire log service. As an alternative to calling {@link #shutdown()}, the * returned thread can be registered as a JVM shutdown hook. */ @@ -100,7 +116,11 @@ public void shutdown() { return new Thread(this::shutdown); } - /** @param refreshable to be deregistered */ + /** + * Deregisters the specified Refreshable instance from the NativeLogServiceManager. + * + * @param refreshable to be deregistered + */ public void deregister(Refreshable refreshable) { lockAndRun(() -> refreshables.remove(refreshable)); IeLogger.INFO.log("De-registered Refreshable {}", refreshable); @@ -115,9 +135,11 @@ private void lockAndRun(@NonNull Runnable runnable) { } } - /** */ + /** The Refreshable interface defines the contract for components that can refresh their configuration. */ public interface Refreshable { /** + * Refreshes the configuration of the component. + * * @param properties used to refresh the logging configuration. If null, only properties reloaded * from the configuration file will be used. Otherwise, the specified properties will replace all current * properties and configuration file is ignored. @@ -128,9 +150,9 @@ public interface Refreshable { void refresh(); } - /** */ + /** The Stoppable interface defines the contract for components that can be stopped. */ public interface Stoppable { - /** */ + /** Stops the component. */ void stop(); } } diff --git a/src/main/java/elf4j/engine/service/NativeLoggerService.java b/src/main/java/elf4j/engine/service/NativeLoggerService.java index e490aba..b63183a 100644 --- a/src/main/java/elf4j/engine/service/NativeLoggerService.java +++ b/src/main/java/elf4j/engine/service/NativeLoggerService.java @@ -27,15 +27,23 @@ import elf4j.engine.NativeLogger; -/** */ +/** + * The NativeLoggerService interface is a part of the ELF4J logging service. It provides methods for checking if a + * logger is enabled and for logging a message with the specified logger, service interface class, throwable, message, + * and arguments. + */ public interface NativeLoggerService extends PerformanceSensitive { /** - * @param nativeLogger to check for enablement - * @return true if the logger's level is at or above configured threshold + * Checks if the logger's level is at or above the configured threshold. + * + * @param nativeLogger the logger to check for enablement + * @return true if the logger's level is at or above the configured threshold, false otherwise */ boolean isEnabled(NativeLogger nativeLogger); /** + * Logs a message with the specified logger, service interface class, throwable, message, and arguments. + * * @param nativeLogger the serviced logger * @param serviceInterfaceClass The concrete logging service (logger) implementation class that the client calls * directly at runtime to make log requests. For the native ELF4J service implementation, this is always the diff --git a/src/main/java/elf4j/engine/service/PerformanceSensitive.java b/src/main/java/elf4j/engine/service/PerformanceSensitive.java index 5d0f463..e007f64 100644 --- a/src/main/java/elf4j/engine/service/PerformanceSensitive.java +++ b/src/main/java/elf4j/engine/service/PerformanceSensitive.java @@ -25,8 +25,15 @@ package elf4j.engine.service; -/** */ +/** + * The PerformanceSensitive interface defines the contract for components that are sensitive to performance. It provides + * a method to check if the log should include caller detail such as method, line number, etc. + */ public interface PerformanceSensitive { - /** @return true if log should include caller detail such as method, line number... */ + /** + * Checks if the log should include caller detail such as method, line number, etc. + * + * @return true if the log should include caller detail, false otherwise + */ boolean includeCallerDetail(); } diff --git a/src/main/java/elf4j/engine/service/configuration/LogServiceConfiguration.java b/src/main/java/elf4j/engine/service/configuration/LogServiceConfiguration.java index 939f2f2..5f92aa4 100644 --- a/src/main/java/elf4j/engine/service/configuration/LogServiceConfiguration.java +++ b/src/main/java/elf4j/engine/service/configuration/LogServiceConfiguration.java @@ -164,6 +164,8 @@ public Properties getProperties() { } /** + * Checks if a named property exists and has a true value. + * * @param name the name to check * @return true only when the named property exists, and has a true value */ diff --git a/src/main/java/elf4j/engine/service/configuration/LoggerOutputLevelThreshold.java b/src/main/java/elf4j/engine/service/configuration/LoggerOutputLevelThreshold.java index 697e859..aaba051 100644 --- a/src/main/java/elf4j/engine/service/configuration/LoggerOutputLevelThreshold.java +++ b/src/main/java/elf4j/engine/service/configuration/LoggerOutputLevelThreshold.java @@ -40,7 +40,11 @@ import lombok.NonNull; import lombok.ToString; -/** */ +/** + * The LoggerOutputLevelThreshold class is responsible for managing the threshold output levels for caller classes. It + * provides methods to get the threshold output level for a given logger and to create a new instance from a given + * configuration. + */ @ToString public class LoggerOutputLevelThreshold { private static final String CONFIGURED_ROOT_LOGGER_NAME_SPACE = ""; @@ -48,6 +52,11 @@ public class LoggerOutputLevelThreshold { private final Map configuredLevels; private final List sortedCallerClassNameSpaces; + /** + * Constructor for the LoggerOutputLevelThreshold class. + * + * @param configuredLevels a map of configured levels + */ private LoggerOutputLevelThreshold(@NonNull Map configuredLevels) { this.configuredLevels = new ConcurrentHashMap<>(configuredLevels); this.sortedCallerClassNameSpaces = configuredLevels.keySet().stream() @@ -57,6 +66,8 @@ private LoggerOutputLevelThreshold(@NonNull Map configuredLevels) } /** + * Creates a new LoggerOutputLevelThreshold instance from a given configuration. + * * @param logServiceConfiguration configuration source of all threshold output levels for caller classes * @return the overriding caller levels */ @@ -72,6 +83,13 @@ private LoggerOutputLevelThreshold(@NonNull Map configuredLevels) return new LoggerOutputLevelThreshold(configuredLevels); } + /** + * Converts a given level key to a Level instance. + * + * @param levelKey the level key + * @param properties the properties + * @return an Optional containing the Level instance if the level key is valid, otherwise an empty Optional + */ private static Optional getAsLevel(String levelKey, @NonNull Properties properties) { String levelValue = properties.getProperty(levelKey); return levelValue == null @@ -80,7 +98,7 @@ private static Optional getAsLevel(String levelKey, @NonNull Properties p } /** - * Assuming the declaring and caller class of the specified logger is the same + * Returns the threshold output level for a given logger. * * @param nativeLogger to search for configured threshold output level * @return If the threshold level is configured for the nativeLogger's caller class, return the configured level. @@ -94,18 +112,30 @@ public Level getThresholdOutputLevel(@NonNull NativeLogger nativeLogger) { .orElse(DEFAULT_THRESHOLD_OUTPUT_LEVEL); } + /** + * The ByClassNameSpace class is a comparator for class name spaces. It sorts class name spaces by the number of + * package levels and then by length and lexicographic order. + */ static class ByClassNameSpace implements Comparator { + /** + * Returns the number of package levels in a given class name space. + * + * @param classNameSpace the class name space + * @return the number of package levels + */ private static int getPackageLevels(@NonNull String classNameSpace) { return classNameSpace.split("\\.").length; } /** - * More specific name space goes first. + * Compares two class name spaces. More specific name space goes first. * *

Note: this comparator imposes orderings that are inconsistent with equals. * * @param classNameSpace1 can be fqcn or just package name * @param classNameSpace2 can be fqcn or just package name + * @return a negative integer, zero, or a positive integer as the first argument is less than, equal to, or + * greater than the second. */ @Override public int compare(@NonNull String classNameSpace1, @NonNull String classNameSpace2) { diff --git a/src/main/java/elf4j/engine/service/pattern/ContextElement.java b/src/main/java/elf4j/engine/service/pattern/ContextElement.java index 9af0459..f941b40 100644 --- a/src/main/java/elf4j/engine/service/pattern/ContextElement.java +++ b/src/main/java/elf4j/engine/service/pattern/ContextElement.java @@ -5,29 +5,48 @@ import lombok.NonNull; import org.slf4j.MDC; -/** */ +/** + * The ContextElement class implements the PatternElement interface and represents a context element in a log pattern. + * It provides methods for checking if the log should include caller detail, for creating a new instance from a pattern + * segment, and for rendering the log event. + */ public class ContextElement implements PatternElement { final String key; - /** @param key whose value will be printed out from the thread context */ + /** + * Constructor for the ContextElement class. + * + * @param key whose value will be printed out from the thread context + */ public ContextElement(String key) { this.key = key; } + /** + * Checks if the log should include caller detail such as method, line number, etc. + * + * @return false as the context element does not include caller detail + */ @Override public boolean includeCallerDetail() { return false; } /** + * Creates a new ContextElement instance from a given pattern segment. + * * @param patternSegment the pattern text to config the context logging * @return the element that can render context log + * @throws NoSuchElementException if no key is configured in the 'context' pattern element */ public static @NonNull ContextElement from(String patternSegment) { return new ContextElement(PatternElements.getPatternElementDisplayOption(patternSegment) .orElseThrow(() -> new NoSuchElementException("No key configured in 'context' pattern element"))); } + /** + * Renders the log event and appends it to the specified StringBuilder. + * * @param logEvent entire log content data source to render * @param target logging text aggregator of the final log message */ diff --git a/src/main/java/elf4j/engine/service/pattern/LogPattern.java b/src/main/java/elf4j/engine/service/pattern/LogPattern.java index 44b6a95..ac5e991 100644 --- a/src/main/java/elf4j/engine/service/pattern/LogPattern.java +++ b/src/main/java/elf4j/engine/service/pattern/LogPattern.java @@ -32,14 +32,21 @@ import lombok.NonNull; import lombok.Value; -/** Composite of individual patterns, intended to form the entire log layout */ +/** + * The LogPattern class implements the PatternElement interface and represents a composite of individual patterns, + * intended to form the entire log layout. It provides methods for checking if the log should include caller detail, for + * creating a new instance from a pattern segment, and for rendering the log event. + */ @Value public class LogPattern implements PatternElement { List patternElements; /** + * Creates a new LogPattern instance from a given pattern segment. + * * @param pattern layout pattern text for entire log entry from configuration * @return composite pattern object for the entire final log message output layout + * @throws IllegalArgumentException if the pattern is blank */ public static @Nonnull LogPattern from(@NonNull String pattern) { if (pattern.trim().isEmpty()) { @@ -76,11 +83,22 @@ public class LogPattern implements PatternElement { return new LogPattern(elements); } + /** + * Checks if the log should include caller detail such as method, line number, etc. + * + * @return true if any of the pattern elements include caller detail, false otherwise + */ @Override public boolean includeCallerDetail() { return patternElements.stream().anyMatch(PatternElement::includeCallerDetail); } + /** + * Renders the log event and appends it to the specified StringBuilder. + * + * @param logEvent the log event to render + * @param target the StringBuilder to append the rendered log event to + */ @Override public void render(LogEvent logEvent, StringBuilder target) { for (PatternElement pattern : patternElements) { diff --git a/src/main/java/elf4j/engine/service/util/Elf4jPostTestProcessor.java b/src/main/java/elf4j/engine/service/util/Elf4jPostTestProcessor.java index 510666b..150d40a 100644 --- a/src/main/java/elf4j/engine/service/util/Elf4jPostTestProcessor.java +++ b/src/main/java/elf4j/engine/service/util/Elf4jPostTestProcessor.java @@ -30,9 +30,19 @@ import org.junit.platform.launcher.TestExecutionListener; import org.junit.platform.launcher.TestPlan; -/** */ +/** + * The Elf4jPostTestProcessor class implements the TestExecutionListener interface and is responsible for shutting down + * the elf4j service after a test plan execution is finished. This is particularly useful in a testing environment where + * resources need to be cleaned up after tests are run to prevent memory leaks or other issues. + */ public class Elf4jPostTestProcessor implements TestExecutionListener { - + /** + * This method is called when the execution of a test plan is finished. It logs the completion of the test plan and + * then shuts down the elf4j service. This ensures that the service does not continue running and consuming + * resources after the tests have completed. + * + * @param testPlan the TestPlan object representing the finished test plan + */ @Override public void testPlanExecutionFinished(TestPlan testPlan) { IeLogger.INFO.log("Shutting down elf4j service after finishing {}", testPlan); diff --git a/src/main/java/elf4j/engine/service/util/StackTraces.java b/src/main/java/elf4j/engine/service/util/StackTraces.java index 1c465ff..6d61fb2 100644 --- a/src/main/java/elf4j/engine/service/util/StackTraces.java +++ b/src/main/java/elf4j/engine/service/util/StackTraces.java @@ -30,11 +30,17 @@ import java.util.NoSuchElementException; import lombok.NonNull; -/** */ +/** + * The StackTraces class provides utility methods for working with stack traces. It provides methods for getting the + * caller of a specified class and for getting the stack trace of a throwable as a string. + */ public class StackTraces { + // Private constructor to prevent instantiation of utility class private StackTraces() {} /** + * Returns the immediate caller frame of the specified callee class. + * * @param calleeClass whose caller is being searched for * @return immediate caller frame of the specified callee class */ @@ -44,6 +50,8 @@ public static StackTraceElement callerOf(@NonNull Class calleeClass) { } /** + * Returns the caller frame of the specified callee class in the given stack trace. + * * @param calleeClass whose caller is being searched for * @param stackTrace to walk in search for the caller * @return the caller frame in the stack trace @@ -61,6 +69,8 @@ public static StackTraceElement getCallerFrame( } /** + * Returns the stack trace of the specified throwable as a string. + * * @param throwable to extract stack trace text from * @return stack trace buffer as the specified throwable prints it */ diff --git a/src/main/java/elf4j/engine/service/writer/GroupWriter.java b/src/main/java/elf4j/engine/service/writer/GroupWriter.java index aa3da78..fa886c0 100644 --- a/src/main/java/elf4j/engine/service/writer/GroupWriter.java +++ b/src/main/java/elf4j/engine/service/writer/GroupWriter.java @@ -68,6 +68,8 @@ private GroupWriter(@NonNull List writers, ConseqExecutor conseqExecu } /** + * Creates a GroupWriter instance from the provided LogServiceConfiguration. + * * @param logServiceConfiguration entire configuration * @return the composite writer containing all writers configured in the specified properties */ diff --git a/src/main/java/org/slf4j/MdcAdapterInitializer.java b/src/main/java/org/slf4j/MdcAdapterInitializer.java index 89443b5..b4e56a9 100644 --- a/src/main/java/org/slf4j/MdcAdapterInitializer.java +++ b/src/main/java/org/slf4j/MdcAdapterInitializer.java @@ -8,7 +8,10 @@ public class MdcAdapterInitializer { private MdcAdapterInitializer() {} - /** */ + /** + * Initializes the MDC implementation for SLF4J. If no MDC adapter is set or if the current adapter is a + * NOPMDCAdapter, it sets the MDC adapter to a BasicMDCAdapter instance. + */ public static void initialize() { MDCAdapter byOtherSlf4jProvider = MDC.mdcAdapter; if (byOtherSlf4jProvider == null || byOtherSlf4jProvider instanceof NOPMDCAdapter) {