Merge branch 'develop': release 1.0

README.md

@@ -16,6 +16,7 @@ It is a final class provided by the library, that has a bunch of convenient meth
 
 `LogLevel` is an enumeration describing the importance of a log message.
 There are 4 log levels:
+
 * `DEBUG`  
   Detailed messages that can help in debugging an application's subsystem.
   Such messages allow a developer to trace the execution path or figure out the current state of the system.
@@ -60,12 +61,12 @@ Contexts are immutable and hierarchical. A nested context contains all elements
 
 ## Basic usage
 
-In order to log messages, one should define a `Logger`:  // todo: questionable
+In order to log messages, one should define a `Logger`:
 ```kotlin
 val logger = Logger.currentClass()
 ```
 This way, a `Logger` will be obtained from the default `LoggerFactory`.
-The logger will be tied to the class declaring this property.
+The logger will be named corresponding to the class or file declaring this property.
 
 There is a `Logger.log(level: LogLevel, error: Throwable? = null, messageBuilder: () -> String)` method
 that can be used for logging messages:
@@ -135,7 +136,7 @@ Result:
 ```
 
 It is incorrect to add to a context an element with a key that already present in the context.
-Execution of the following code with lead to an `IllegalStateException`:
+Execution of the following code with lead to an `IllegalArgumentException`:
 ```kotlin
 withLoggingContext("id", "foo") {
     withLoggingContext("id", "bar")

build.gradle

@@ -2,8 +2,8 @@ plugins {
     id 'java-library'
     id 'maven-publish'
     id 'jacoco'
-    id 'org.jetbrains.kotlin.jvm' version '1.4.21'
-    id 'ru.kontur.kinfra.presets' version '1.4'
+    id 'org.jetbrains.kotlin.jvm' version '1.4.32'
+    id 'ru.kontur.kinfra.presets' version '1.5'
     id 'me.champeau.gradle.jmh' version '0.5.3'
 }
 
@@ -23,7 +23,7 @@ ext {
 }
 
 group = "ru.kontur.kinfra"
-version = "0.3"
+version = "1.0"
 
 dependencies {
     implementation libs.slf4jApi
@@ -41,6 +41,14 @@ dependencies {
     }
 }
 
+kotlin {
+    explicitApi()
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile) {
+    kotlinOptions.freeCompilerArgs += "-Xopt-in=kotlin.RequiresOptIn"
+}
+
 jar {
     manifest.attributes "Automatic-Module-Name": "ru.kontur.kinfra.logging"
 }

src/main/kotlin/ru/kontur/kinfra/logging/DefaultLoggerFactory.kt

@@ -5,7 +5,7 @@ import ru.kontur.kinfra.logging.builtin.BuiltinLoggerFactory
 /**
  * Default [logger factory][LoggerFactory].
  */
-object DefaultLoggerFactory : LoggerFactory.Wrapper() {
+public object DefaultLoggerFactory : LoggerFactory.Wrapper() {
 
     /**
      * Actual factory in use.

src/main/kotlin/ru/kontur/kinfra/logging/LogLevel.kt

@@ -3,14 +3,14 @@ package ru.kontur.kinfra.logging
 /**
  * Importance level of a log message.
  */
-enum class LogLevel {
+public enum class LogLevel {
     DEBUG,
     INFO,
     WARN,
     ERROR,
     ;
 
     // for user extensions
-    companion object
+    public companion object
 
 }

src/main/kotlin/ru/kontur/kinfra/logging/Logger.kt

@@ -20,28 +20,28 @@ import kotlin.reflect.KClass
  *  * [Logger.forName] obtains a logger with arbitrary name.
  *    Use when none of the above is appropriate.
  */
-class Logger internal constructor(
+public class Logger internal constructor(
     private val backend: LoggerBackend,
     private val factory: LoggerFactory
 ) {
 
     /** [Log][log] a message with [DEBUG][LogLevel.DEBUG] level. */
-    inline fun debug(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
+    public inline fun debug(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
         log(LogLevel.DEBUG, error, lazyMessage)
     }
 
     /** [Log][log] a message with [INFO][LogLevel.INFO] level. */
-    inline fun info(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
+    public inline fun info(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
         log(LogLevel.INFO, error, lazyMessage)
     }
 
     /** [Log][log] a message with [WARN][LogLevel.WARN] level. */
-    inline fun warn(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
+    public inline fun warn(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
         log(LogLevel.WARN, error, lazyMessage)
     }
 
     /** [Log][log] a message with [ERROR][LogLevel.ERROR] level. */
-    inline fun error(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
+    public inline fun error(error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
         log(LogLevel.ERROR, error, lazyMessage)
     }
 
@@ -52,8 +52,13 @@ class Logger internal constructor(
      *
      * @param error a [Throwable] that should be logged with the message
      */
-    // crossinline disallows non-local returns in the lambda
-    inline fun log(level: LogLevel, error: Throwable? = null, crossinline lazyMessage: MessageBuilder.() -> String) {
+    public inline fun log(
+        level: LogLevel,
+        error: Throwable? = null,
+        // crossinline disallows non-local returns in the lambda
+        crossinline lazyMessage: MessageBuilder.() -> String
+    ) {
+
         if (isEnabled(level)) {
             val messageBuilder = MessageBuilder.STUB
             val message = lazyMessage.invoke(messageBuilder)
@@ -99,7 +104,7 @@ class Logger internal constructor(
         return "Logger(backend: $backend)"
     }
 
-    companion object {
+    public companion object {
 
         private val callerInfo = CallerInfo(facadeClassName = Logger::class.java.name)
 
@@ -116,14 +121,14 @@ class Logger internal constructor(
          *
          * Note that [Logger.currentClass] would return a logger for `BaseClass`.
          */
-        fun forClass(kClass: KClass<*>): Logger {
+        public fun forClass(kClass: KClass<*>): Logger {
             return DefaultLoggerFactory.getLogger(kClass)
         }
 
         /**
          * Obtains a [Logger] instance with a given [name] using default [LoggerFactory].
          */
-        fun forName(name: String): Logger {
+        public fun forName(name: String): Logger {
             return DefaultLoggerFactory.getLogger(name)
         }
 
@@ -156,7 +161,7 @@ class Logger internal constructor(
          * ```
          */
         @Suppress("NOTHING_TO_INLINE")
-        inline fun currentClass(): Logger {
+        public inline fun currentClass(): Logger {
             return DefaultLoggerFactory.currentClassLogger()
         }
 

src/main/kotlin/ru/kontur/kinfra/logging/LoggerFactory.kt

@@ -25,7 +25,7 @@ import kotlin.reflect.KClass
  *
  *     * `getEmptyDecor()`: provides a [MessageDecor] to render context data in log messages.
  */
-abstract class LoggerFactory {
+public abstract class LoggerFactory {
 
     /**
      * Obtains a [Logger] with a given [name].
@@ -34,7 +34,7 @@ abstract class LoggerFactory {
      *
      * This method is thread safe. Calls [getLoggerBackend] internally.
      */
-    open fun getLogger(name: String): Logger {
+    public open fun getLogger(name: String): Logger {
         val backend = getLoggerBackend(name)
         return Logger(backend, this)
     }
@@ -44,7 +44,7 @@ abstract class LoggerFactory {
      *
      * This method is thread safe. Calls [getLoggerBackend] internally.
      */
-    fun getLogger(kClass: KClass<*>): Logger {
+    public open fun getLogger(kClass: KClass<*>): Logger {
         val name = requireNotNull(kClass.qualifiedName) {
             "Class $kClass does not have a fully qualified name"
         }
@@ -73,26 +73,26 @@ abstract class LoggerFactory {
      * Custom wrapping factories should extend this class to properly implement
      * new methods that may be added in the future.
      */
-    abstract class Wrapper : LoggerFactory() {
+    public abstract class Wrapper : LoggerFactory() {
 
         protected abstract val delegate: LoggerFactory
 
         override fun getLoggerBackend(name: String): LoggerBackend = delegate.getLoggerBackend(name)
 
-        override fun getEmptyDecor() = delegate.getEmptyDecor()
+        override fun getEmptyDecor(): MessageDecor = delegate.getEmptyDecor()
 
     }
 
     // for user extensions
-    companion object
+    public companion object
 
 }
 
 /**
  * Obtains [Logger] instance to use in the current class (that is the class calling this method).
  */
 @Suppress("NOTHING_TO_INLINE")
-inline fun LoggerFactory.currentClassLogger(): Logger {
+public inline fun LoggerFactory.currentClassLogger(): Logger {
     /*
      * All internal callers of this function must be inline!
      * It is required for MethodHandles.lookup() to work correctly.