diff --git a/README.md b/README.md index 957f2dd..ee383a5 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A lightweight library containing shared and generic utility classes for Java-bas ## 1) What is this repository for? ### 1.1) Quick summary -Version: `1.0.4` +Version: `1.0.5` **White_Utils** is a public Java library that provides standardized and generic utility classes to simplify common operations such as logging, formatting, and general helper functions across Java and Maven projects. It is published for public consumption and is also used as a standard within White Organization. @@ -25,30 +25,31 @@ WhiteUtils is designed to be as generic and dependency-minimal as possible so it mx.whiteweb.sdev white-utils - 1.0.4 + 1.0.5 ``` **Primary utilities (examples):** -- `WhiteLogger` — standardized logging helpers (SLF4J-friendly usage). +- `WhiteLoggeable` — standardized logging helpers (SLF4J-friendly usage). -**Example (placeholder — to be updated when `WhiteLogger` API is finalized):** +**Example:** ```java @Slf4j public class MyService implements WhiteLoggeable { @Override public org.slf4j.Logger getLogger() { return log;} public void myProcess(String name, int age) { - var log = withSignature("myProcess(name, age)"); - log.start("Processing user {} with age {}", name, age); - + // Method chaining is supported - all logging methods return LogContext + var log = withSignature("myProcess(name, age)") + .start("Processing user {} with age {}", name, age) + log.debug("User age is {}", age); if (age < 18) { log.warn("User {} is a minor", name); } - log.info("User processed successfully"); - log.end("age is now {}", age); + log.info("User processed successfully") + .end("age is now {}", age); } } ``` @@ -109,4 +110,3 @@ _Please ask for the code standard to use as a guideline and reflect it in the pr >Please, contact me if you want to help; In general, I'm developing, maintaining, and supporting this project on my own with no help or support from anyone; any tip, comment, change, or help in general is well-received. - diff --git a/pom.xml b/pom.xml index ffc4323..ffa63ff 100644 --- a/pom.xml +++ b/pom.xml @@ -7,7 +7,7 @@ mx.whiteweb.sdev white-utils - 1.0.4 + 1.0.5 ${project.groupId}:${project.artifactId} A lightweight library containing shared and generic utility classes for Java-based projects. https://github.com/WhiteOrganization/white-utils diff --git a/src/main/java/org/white_sdev/utils/logging/WhiteLoggeable.java b/src/main/java/org/white_sdev/utils/logging/WhiteLoggeable.java index 60be79b..0c16737 100644 --- a/src/main/java/org/white_sdev/utils/logging/WhiteLoggeable.java +++ b/src/main/java/org/white_sdev/utils/logging/WhiteLoggeable.java @@ -2,82 +2,95 @@ @SuppressWarnings("unused") public interface WhiteLoggeable { - + /** * Creates a logging context bound to a specific method signature. * This allows logging multiple messages without repeating the method signature. * - * @param methodSignatureRepresentation the method signature to use for all logs in this context + * @param methodSignatureRepresentation the method signature to use for all logs + * in this context * @return a LogContext instance bound to the provided method signature */ default LogContext withSignature(String methodSignatureRepresentation) { return new LogContext(this, methodSignatureRepresentation); } - + /** * Logs a message at TRACE level with method signature. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void trace(String methodSignatureRepresentation, String message, Object... args){ + default void trace(String methodSignatureRepresentation, String message, Object... args) { log(org.slf4j.event.Level.TRACE, methodSignatureRepresentation, message, args); } /** * Logs a message at DEBUG level with method signature. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void debug(String methodSignatureRepresentation, String message, Object... args){ + default void debug(String methodSignatureRepresentation, String message, Object... args) { log(org.slf4j.event.Level.DEBUG, methodSignatureRepresentation, message, args); } /** * Logs a message at INFO level with method signature. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void info(String methodSignatureRepresentation, String message, Object... args){ + default void info(String methodSignatureRepresentation, String message, Object... args) { log(org.slf4j.event.Level.INFO, methodSignatureRepresentation, message, args); } /** * Logs a message at WARN level with method signature. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void warn(String methodSignatureRepresentation, String message, Object... args){ + default void warn(String methodSignatureRepresentation, String message, Object... args) { log(org.slf4j.event.Level.WARN, methodSignatureRepresentation, message, args); } /** * Logs a message at ERROR level with method signature. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void error(String methodSignatureRepresentation, String message, Object... args){ + default void error(String methodSignatureRepresentation, String message, Object... args) { log(org.slf4j.event.Level.ERROR, methodSignatureRepresentation, message, args); } /** * Logs a message at ERROR level with method signature and exception. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param throwable the exception to log - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param throwable the exception to log + * @param args the arguments to replace placeholders in + * the message */ - default void error(String methodSignatureRepresentation, String message, Throwable throwable, Object... args){ + default void error(String methodSignatureRepresentation, String message, Throwable throwable, Object... args) { getLogger().error("::{}: " + message, combineArgs(methodSignatureRepresentation, args), throwable); } @@ -85,21 +98,25 @@ default void error(String methodSignatureRepresentation, String message, Throwab * Logs a message at ERROR level with method signature and exception. * Alternative parameter order for convenience. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param throwable the exception to log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param throwable the exception to log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void error(String methodSignatureRepresentation, Throwable throwable, String message, Object... args){ + default void error(String methodSignatureRepresentation, Throwable throwable, String message, Object... args) { getLogger().error("::{}: " + message, combineArgs(methodSignatureRepresentation, args), throwable); } /** * Logs the start of a method execution with additional details. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ default void start(String methodSignatureRepresentation, String message, Object... args) { trace(methodSignatureRepresentation, "Start - " + message, args); @@ -108,7 +125,8 @@ default void start(String methodSignatureRepresentation, String message, Object. /** * Logs the start of a method execution. * - * @param methodSignatureRepresentation the method signature to include in the log + * @param methodSignatureRepresentation the method signature to include in the + * log */ default void start(String methodSignatureRepresentation) { trace(methodSignatureRepresentation, "Start"); @@ -117,9 +135,11 @@ default void start(String methodSignatureRepresentation) { /** * Logs the end of a method execution with additional details. * - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ default void end(String methodSignatureRepresentation, String message, Object... args) { trace(methodSignatureRepresentation, "End - " + message, args); @@ -128,7 +148,8 @@ default void end(String methodSignatureRepresentation, String message, Object... /** * Logs the end of a method execution. * - * @param methodSignatureRepresentation the method signature to include in the log + * @param methodSignatureRepresentation the method signature to include in the + * log */ default void end(String methodSignatureRepresentation) { trace(methodSignatureRepresentation, "End"); @@ -137,21 +158,34 @@ default void end(String methodSignatureRepresentation) { /** * Logs a message at the specified level with method signature. * - * @param level the logging level - * @param methodSignatureRepresentation the method signature to include in the log - * @param message the log message with placeholders - * @param args the arguments to replace placeholders in the message + * @param level the logging level + * @param methodSignatureRepresentation the method signature to include in the + * log + * @param message the log message with placeholders + * @param args the arguments to replace placeholders in + * the message */ - default void log(org.slf4j.event.Level level, String methodSignatureRepresentation, String message, Object... args){ + default void log(org.slf4j.event.Level level, String methodSignatureRepresentation, String message, + Object... args) { org.slf4j.Logger logger = getLogger(); String formatted = "::{}: " + message; Object[] combinedArgs = combineArgs(methodSignatureRepresentation, args); switch (level) { - case TRACE : logger.trace(formatted, combinedArgs); break; - case DEBUG : logger.debug(formatted, combinedArgs); break; - case INFO : logger.info(formatted, combinedArgs); break; - case WARN : logger.warn(formatted, combinedArgs); break; - case ERROR : logger.error(formatted, combinedArgs); break; + case TRACE: + logger.trace(formatted, combinedArgs); + break; + case DEBUG: + logger.debug(formatted, combinedArgs); + break; + case INFO: + logger.info(formatted, combinedArgs); + break; + case WARN: + logger.warn(formatted, combinedArgs); + break; + case ERROR: + logger.error(formatted, combinedArgs); + break; } } @@ -160,7 +194,7 @@ default void log(org.slf4j.event.Level level, String methodSignatureRepresentati * Used internally to prepend the method signature to the logging arguments. * * @param first the first object to include - * @param rest the remaining objects to include + * @param rest the remaining objects to include * @return a new array containing all objects */ default Object[] combineArgs(Object first, Object... rest) { @@ -191,52 +225,64 @@ class LogContext { this.methodSignature = methodSignature; } - public void trace(String message, Object... args) { + public LogContext trace(String message, Object... args) { loggeable.trace(methodSignature, message, args); + return this; } - public void debug(String message, Object... args) { + public LogContext debug(String message, Object... args) { loggeable.debug(methodSignature, message, args); + return this; } - public void info(String message, Object... args) { + public LogContext info(String message, Object... args) { loggeable.info(methodSignature, message, args); + return this; } - public void warn(String message, Object... args) { + public LogContext warn(String message, Object... args) { loggeable.warn(methodSignature, message, args); + return this; } - public void error(String message, Object... args) { + public LogContext error(String message, Object... args) { loggeable.error(methodSignature, message, args); + return this; } - public void error(String message, Throwable throwable, Object... args) { + public LogContext error(String message, Throwable throwable, Object... args) { loggeable.error(methodSignature, message, throwable, args); + return this; } - public void error(Throwable throwable, String message, Object... args) { + public LogContext error(Throwable throwable, String message, Object... args) { loggeable.error(methodSignature, throwable, message, args); + return this; } - public void start(String message, Object... args) { + public LogContext start(String message, Object... args) { loggeable.start(methodSignature, message, args); + return this; } - public void start() { + public LogContext start() { loggeable.start(methodSignature); + return this; } - public void end(String message, Object... args) { + public LogContext end(String message, Object... args) { loggeable.end(methodSignature, message, args); + return this; } - public void end() { + public LogContext end() { loggeable.end(methodSignature); + return this; } - public void log(org.slf4j.event.Level level, String message, Object... args) { + public LogContext log(org.slf4j.event.Level level, String message, Object... args) { loggeable.log(level, methodSignature, message, args); + return this; } } }