Move logger property to autoprop package

The `logger` property conflicts with explicitly defined logger properties.
Given the performance considerations of the `logger` property, move it to
a separate package so imports of it are explicit and non-conflicting.

Resolves #136

Author: rocketraman

log4j-api-kotlin-sample/src/main/kotlin/org/apache/logging/log4j/kotlin/sample/LoggingAppExtensionProperty.kt

@@ -18,8 +18,8 @@ package org.apache.logging.log4j.kotlin.sample
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings
 import org.apache.logging.log4j.kotlin.ContextMap
-import org.apache.logging.log4j.kotlin.logger
-import java.util.Random
+import org.apache.logging.log4j.kotlin.autoprop.logger
+import kotlin.random.Random
 
 @SuppressFBWarnings("PREDICTABLE_RANDOM", "DMI_RANDOM_USED_ONLY_ONCE")
 object LoggingAppExtensionProperty {
@@ -45,7 +45,7 @@ object LoggingAppExtensionProperty {
     }
 
     fun getKey(): Int = logger.runInTrace {
-      Random().nextInt(10)
+      Random.nextInt(10)
     }
 
     @SuppressFBWarnings("NP_ALWAYS_NULL")

log4j-api-kotlin/src/main/kotlin/org/apache/logging/log4j/kotlin/LoggingFactory.kt

@@ -34,6 +34,11 @@ inline fun <reified T : Any> T.logger() = loggerOf(T::class.java)
  *
  * @since 1.3.0
  */
+@Deprecated(
+  "Replace with autoprop.logger to avoid unintended consequences with explicitly declared logger properties. This will be removed in the next major release.",
+  replaceWith = ReplaceWith("logger", "org.apache.logging.log4j.kotlin.autoprop.logger"),
+  level = DeprecationLevel.WARNING
+)
 inline val <reified T> T.logger: KotlinLogger
   get() = cachedLoggerOf(T::class.java)
 

log4j-api-kotlin/src/main/kotlin/org/apache/logging/log4j/kotlin/autoprop/LoggingFactoryAutoProp.kt

@@ -0,0 +1,27 @@
+package org.apache.logging.log4j.kotlin.autoprop
+
+import org.apache.logging.log4j.kotlin.KotlinLogger
+import org.apache.logging.log4j.kotlin.cachedLoggerOf
+
+/**
+ * Provides a logger named after the receiver object's class.
+ *
+ * Simply import this property and use it.
+ *
+ * ```
+ * import org.apache.logging.log4j.kotlin.autoprop.logger
+ *
+ * class MyClass {
+ *   // use `logger` as necessary
+ * }
+ * ```
+ *
+ * Note that this is significantly slower than creating a logger explicitly, as it requires a lookup of the
+ * logger on each call via the property getter. We attempt to minimize the overhead of this by caching the
+ * loggers, but according to microbenchmarks, it is still about 3.5 times slower than creating a logger once
+ * and using it (about 4.2 nanoseconds per call instead of 1.2 nanoseconds).
+ *
+ * @since 1.3.0
+ */
+inline val <reified T> T.logger: KotlinLogger
+  get() = cachedLoggerOf(T::class.java)