From 34d99c65ee5ff3aba4aa245ccd994fad7266f7d7 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Fri, 24 Feb 2017 07:44:05 +0100 Subject: [PATCH] improve docs for logging with more than 4 args, #17895 * it was already supported by using an Array --- .../src/main/scala/akka/event/Logging.scala | 56 +++++++++++++++++-- akka-docs/rst/scala/logging.rst | 2 +- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/akka-actor/src/main/scala/akka/event/Logging.scala b/akka-actor/src/main/scala/akka/event/Logging.scala index 1717bd2d51..a9bfd02e14 100644 --- a/akka-actor/src/main/scala/akka/event/Logging.scala +++ b/akka-actor/src/main/scala/akka/event/Logging.scala @@ -1061,6 +1061,9 @@ object Logging { * {{{ * log.error(exception, "Exception while processing {} in state {}", msg, state) * }}} + * + * More than four arguments can be defined by using an `Array` with the method with + * one argument parameter. */ trait LoggingAdapter { @@ -1097,6 +1100,9 @@ trait LoggingAdapter { def error(cause: Throwable, message: String): Unit = { if (isErrorEnabled) notifyError(cause, message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def error(cause: Throwable, template: String, arg1: Any): Unit = { if (isErrorEnabled) notifyError(cause, format1(template, arg1)) } @@ -1123,6 +1129,9 @@ trait LoggingAdapter { def error(message: String): Unit = { if (isErrorEnabled) notifyError(message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def error(template: String, arg1: Any): Unit = { if (isErrorEnabled) notifyError(format1(template, arg1)) } @@ -1149,6 +1158,9 @@ trait LoggingAdapter { def warning(message: String): Unit = { if (isWarningEnabled) notifyWarning(message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def warning(template: String, arg1: Any): Unit = { if (isWarningEnabled) notifyWarning(format1(template, arg1)) } @@ -1175,6 +1187,9 @@ trait LoggingAdapter { def info(message: String) { if (isInfoEnabled) notifyInfo(message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def info(template: String, arg1: Any): Unit = { if (isInfoEnabled) notifyInfo(format1(template, arg1)) } @@ -1201,6 +1216,9 @@ trait LoggingAdapter { def debug(message: String) { if (isDebugEnabled) notifyDebug(message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def debug(template: String, arg1: Any): Unit = { if (isDebugEnabled) notifyDebug(format1(template, arg1)) } @@ -1226,6 +1244,9 @@ trait LoggingAdapter { def log(level: Logging.LogLevel, message: String) { if (isEnabled(level)) notifyLog(level, message) } /** * Message template with 1 replacement argument. + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. */ def log(level: Logging.LogLevel, template: String, arg1: Any): Unit = { if (isEnabled(level)) notifyLog(level, format1(template, arg1)) } /** @@ -1258,6 +1279,10 @@ trait LoggingAdapter { case Logging.DebugLevel ⇒ if (isDebugEnabled) notifyDebug(message) } + /** + * If `arg` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. + */ private def format1(t: String, arg: Any): String = arg match { case a: Array[_] if !a.getClass.getComponentType.isPrimitive ⇒ format(t, a: _*) case a: Array[_] ⇒ format(t, (a map (_.asInstanceOf[AnyRef]): _*)) @@ -1433,10 +1458,13 @@ class MarkerLoggingAdapter( /** * Message template with 1 replacement argument. * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special". + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def error(marker: LogMarker, cause: Throwable, template: String, arg1: Any): Unit = - if (isErrorEnabled) bus.publish(Error(logSource, logClass, format(template, arg1), mdc, marker)) + if (isErrorEnabled) bus.publish(Error(logSource, logClass, format1(template, arg1), mdc, marker)) /** * Message template with 2 replacement arguments. @@ -1473,10 +1501,13 @@ class MarkerLoggingAdapter( /** * Message template with 1 replacement argument. * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special". + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def error(marker: LogMarker, template: String, arg1: Any): Unit = - if (isErrorEnabled) bus.publish(Error(logSource, logClass, format(template, arg1), mdc, marker)) + if (isErrorEnabled) bus.publish(Error(logSource, logClass, format1(template, arg1), mdc, marker)) /** * Message template with 2 replacement arguments. @@ -1513,10 +1544,13 @@ class MarkerLoggingAdapter( /** * Message template with 1 replacement argument. * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special". + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def warning(marker: LogMarker, template: String, arg1: Any): Unit = - if (isWarningEnabled) bus.publish(Warning(logSource, logClass, format(template, arg1), mdc, marker)) + if (isWarningEnabled) bus.publish(Warning(logSource, logClass, format1(template, arg1), mdc, marker)) /** * Message template with 2 replacement arguments. @@ -1553,10 +1587,13 @@ class MarkerLoggingAdapter( /** * Message template with 1 replacement argument. * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special". + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def info(marker: LogMarker, template: String, arg1: Any): Unit = - if (isInfoEnabled) bus.publish(Info(logSource, logClass, format(template, arg1), mdc, marker)) + if (isInfoEnabled) bus.publish(Info(logSource, logClass, format1(template, arg1), mdc, marker)) /** * Message template with 2 replacement arguments. @@ -1593,10 +1630,13 @@ class MarkerLoggingAdapter( /** * Message template with 1 replacement argument. * The marker argument can be picked up by various logging frameworks such as slf4j to mark this log statement as "special". + * + * If `arg1` is an `Array` it will be expanded into replacement arguments, which is useful when + * there are more than four arguments. * @see [[LoggingAdapter]] */ def debug(marker: LogMarker, template: String, arg1: Any): Unit = - if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format(template, arg1), mdc, marker)) + if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format1(template, arg1), mdc, marker)) /** * Message template with 2 replacement arguments. @@ -1622,6 +1662,12 @@ class MarkerLoggingAdapter( def debug(marker: LogMarker, template: String, arg1: Any, arg2: Any, arg3: Any, arg4: Any): Unit = if (isDebugEnabled) bus.publish(Debug(logSource, logClass, format(template, arg1, arg2, arg3, arg4), mdc, marker)) + // Copy of LoggingAdapter.format1 due to binary compatibility restrictions + private def format1(t: String, arg: Any): String = arg match { + case a: Array[_] if !a.getClass.getComponentType.isPrimitive ⇒ format(t, a: _*) + case a: Array[_] ⇒ format(t, (a map (_.asInstanceOf[AnyRef]): _*)) + case x ⇒ format(t, x) + } } final class DiagnosticMarkerBusLoggingAdapter( diff --git a/akka-docs/rst/scala/logging.rst b/akka-docs/rst/scala/logging.rst index 63cb25af2e..9632951c24 100644 --- a/akka-docs/rst/scala/logging.rst +++ b/akka-docs/rst/scala/logging.rst @@ -40,7 +40,7 @@ The source object is translated to a String according to the following rules: The log message may contain argument placeholders ``{}``, which will be substituted if the log level is enabled. Giving more arguments as there are placeholders results in a warning being appended to the log statement (i.e. on -the same line with the same severity). You may pass a Java array as the only +the same line with the same severity). You may pass an array as the only substitution argument to have its elements be treated individually: .. includecode:: code/docs/event/LoggingDocSpec.scala#array