Add support for initializing via system property

Author: ataggart

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ([despite its flaws](https://www.youtube.com/watch?v=oyLBGkS5ICk)).
 
 ## [Unreleased]
+### Added
+- Add support for explicitly selecting a logger factory by setting the
+ `clojure.tools.logging.factory` system property.
 
 ## [0.5.0] - 2019-07-22
 ### Added

README.md

@@ -1,104 +1,114 @@
 # Logging
 
-Logging macros which delegate to a specific logging implementation. At runtime a specific implementation is selected from, in order, slf4j, Apache commons-logging, log4j2, log4j, and finally java.util.logging.
+Logging macros which delegate to a specific logging implementation, selected
+at runtime when the `clojure.tools.logging` namespace is first loaded.
 
-Logging levels are specified by clojure keywords, in increasingly severe order:
+## Installation
+
+Lastest stable release is [0.5.0]
+
+Leiningen:
 
 ```clojure
-:trace, :debug, :info, :warn, :error, :fatal
+[org.clojure/tools.logging "0.5.0"]
+```
+
+Maven:
+
+```xml
+<dependency>
+  <groupId>org.clojure</groupId>
+  <artifactId>tools.logging</artifactId>
+  <version>0.5.0</version>
+</dependency>
 ```
 
-Logging occurs with the `log` macro, or the level-specific convenience macros (e.g., `debug`, `debugf`). Only when the specified logging level is enabled will the message arguments be evaluated and the underlying logging implementation be invoked. By default that invocation will occur via an agent when inside a running STM transaction.
+Gradle:
 
-Unless otherwise specified, the current namespace (as identified by `*ns*`) will be used as the log-ns (similar to how the java class name is usually used).  Note: you should configure your logging implementation to display the name that was passed to it; if it instead performs stack-inspection you'll see some ugly and unhelpful text in your logs.
+```clojure
+compile "org.clojure:tools.logging:0.5.0"
+```
 
-You can redirect all java writes of `System.out` and `System.err` to the log system by calling `log-capture!`.  To bind `*out*` and `*err*` to the log system invoke `with-logs`.  In both cases a log-ns value must be specified in order to namespace the output.
 
 ## Usage
 
-The latest API documentation can be found at http://clojure.github.com/tools.logging
+[Latest API Documentation](http://clojure.github.com/tools.logging)
 
-The following short example should give you what you need to get started:
+Logging occurs with the `log` macro, or the level-specific convenience macros
+(e.g., `debug`, `debugf`). Only when the specified logging level is enabled will
+the message arguments be evaluated and the underlying logging implementation be
+invoked. By default that invocation will occur via an agent when inside a running
+STM transaction.
 
-```clojure
-(ns example.math
-  (:require [clojure.tools.logging :as log]))
-
-(defn divide [x y]
-  (log/info "dividing" x "by" y)
-  (try
-    (log/spyf "result is %s" (/ x y)) ; yields the result
-    (catch Exception ex
-      (log/error ex "There was an error in calculation"))))
-```
+### Namespacing of log entries
 
-Example repl output using the configuration below:
+Unless otherwise specified, the current namespace (as identified by `*ns*`) will
+be used as the log-ns. This value can be emitted in the log entry, and used by most
+logging implementations when using namespace-specific logging levels.
 
-```
-user=> (use 'my.example)
-nil
-user=> (divide 1 2)
-INFO  example.math: dividing 1 by 2
-DEBUG example.math: result is 1/2
-1/2
-user=> (divide 2 0)
-INFO  example.math: dividing 2 by 0
-ERROR example.math: There was an error in calculation
-java.lang.ArithmeticException: Divide by zero
-	at clojure.lang.Numbers.divide(Numbers.java:156)
-    ...
-```
+Note: You should configure your logging implementation to display the name that
+was passed to it. If it instead performs stack-inspection you'll see some ugly
+and unhelpful text in your logs.
 
-For those new to using a java logging library, the following is a very basic configuration for log4j. Place it in a file called `log4j.properties` and place that file (and the log4j JAR) on the classpath.
+### Redirecting output to logs
 
-```
-log4j.rootLogger=INFO, console
-log4j.logger.example=DEBUG
-log4j.appender.console=org.apache.log4j.ConsoleAppender
-log4j.appender.console.layout=org.apache.log4j.PatternLayout
-log4j.appender.console.layout.ConversionPattern=%-5p %c: %m%n
-```
+You can redirect all java writes of `System.out` and `System.err` to the log
+system by calling `log-capture!`.  To bind `*out*` and `*err*` to the log system
+invoke `with-logs`.  In both cases a log-ns value must be specified in order to
+namespace the output.
 
-The above will print messages to the console for `:debug` or higher if one is in the `example` namespace, and `:info` or higher in all other namespaces.
+## Configuration
 
-### Installation
+_NOTE: Logging configuration (e.g., setting of logging levels, formatting) is
+specific to the underlying logging implementation, and is out of scope for this
+library._
 
-Logging is available in Maven central.  Add it to your Maven project's `pom.xml`:
+### Selecting a logging implementation
 
-```xml
-<dependency>
-  <groupId>org.clojure</groupId>
-  <artifactId>tools.logging</artifactId>
-  <version>0.5.0</version>
-</dependency>
-```
+To control which logging implementation is used, set the `clojure.tools.logging.factory`
+system property to the fully-qualified name of a no-arg function that returns an
+instance of `clojure.tools.logging.impl/LoggerFactory`. There are a number of
+factory functions provided in the `clojure.tools.logging.impl` namespace.
 
-or your leiningen project.clj:
+[Leiningen example]:
 
 ```clojure
-[org.clojure/tools.logging "0.5.0"]
+:jvm-opts ["-Dclojure.tools.logging.factory=clojure.tools.logging.impl/slf4j-factory"]
 ```
 
-Please note the changelog below.
+If the system property is unset, an implementation will be automatically chosen
+based on whichever of the following implementations is successfully loaded first:
 
-### Building Logging
+1. [SLF4J]
+2. [Apache Commons Logging]
+3. [Log4J 2]
+4. [Log4J]
+5. [java.util.logging]
+
+The above approach is problematic given that applications often inadvertently pull
+in multiple logging implementations as transitive dependencies. As such, it is
+_strongly_ advised that you set the system property.
 
-0. Clone the repo
-1. Make sure you have maven installed
-2. Run the maven build; run either:
-    1. `mvn install`: This will produce a logging jar file in the `target`
-directory, and run all tests with the most recently-released build
-of Clojure.
 
 ## Thanks
 
 * Chris Dean
 * Phil Hagelberg
 * Richard Newman
+* Sean Corfield
 * Timothy Pratley
 
 ## License
 
 Copyright © 2009 Alex Taggart
 
 Licensed under the EPL. (See the file epl.html.)
+
+
+[0.5.0]: https://github.com/clojure/tools.logging/tree/tools.logging-0.5.0
+[Leiningen example]: https://github.com/technomancy/leiningen/blob/master/doc/TUTORIAL.md#setting-jvm-options
+[SLF4J]: http://www.slf4j.org/
+[Apache Commons Logging]: https://commons.apache.org/logging
+[Log4J 2]: https://logging.apache.org/log4j/2.x/
+[Log4J]: http://logging.apache.org/log4j/1.2/
+[java.util.logging]: https://docs.oracle.com/en/java/javase/13/docs/api/java.logging/java/util/logging/package-summary.html 

src/main/clojure/clojure/tools/logging.clj

@@ -11,14 +11,13 @@
 ;; agreeing to be bound by the terms of this license.  You must not
 ;; remove this notice, or any other, from this software.
 (ns ^{:author "Alex Taggart"
-      :doc "Logging macros which delegate to a specific logging implementation. At
-            runtime a specific implementation is selected by invoking
-            clojure.tools.logging.impl/find-factory.
-
-            The logging implementation can be explicitly provided by using
-            binding or alter-var-root to change the value of *logger-factory* to
-            another implementation of clojure.tools.logging.impl/LoggerFactory
-            (see also the *-factory functions in the impl namespace)."}
+      :doc "Logging macros which delegate to a specific logging implementation.
+
+  A logging implementation is selected at runtime when this namespace is first
+  loaded. For more details, see the documentation for *logger-factory*.
+
+  If you want to test that your code emits specific log messages, see the
+  clojure.tools.logging.test namespace."}
   clojure.tools.logging
   (:use
    [clojure.string :only [trim-newline]]
@@ -283,9 +282,42 @@
   [& args]
   `(logf :fatal ~@args))
 
-(def ^{:doc
-  "An instance satisfying the impl/LoggerFactory protocol. Used internally to
-   obtain an impl/Logger. Defaults to the value returned from impl/find-factory."
-  :dynamic true}
-  *logger-factory*
-  (impl/find-factory))
+(defn- call-str [str]
+  (let [fq-sym (symbol str)
+        ns-str (or (namespace fq-sym)
+                   (throw (RuntimeException.
+                            (format "The value of the clojure.tools.logging.factory system property is not fully-qualified: %s"
+                                    (pr-str str)))))
+        ns-sym (symbol ns-str)
+        _      (try
+                 (require ns-sym)
+                 (catch Exception ex
+                   (throw (RuntimeException.
+                            (format "Could not resolve namespace for %s. Either it does not exist or it has a (circular) dependency on clojure.tools.logging."
+                                    (pr-str str))))))
+        fn-sym (symbol (name fq-sym))
+        fn-var (ns-resolve ns-sym fn-sym)]
+    (if fn-var
+      (fn-var)
+      (throw (RuntimeException.
+               (format "Could not resolve var for %s."
+                       (pr-str str)))))))
+
+(defn- find-factory []
+  (if-let [factory-fn-str (System/getProperty "clojure.tools.logging.factory")]
+    (call-str factory-fn-str)
+    (impl/find-factory)))
+
+(def ^:dynamic *logger-factory*
+  "An instance satisfying the clojure.tools.logging.impl/LoggerFactory protocol,
+  which allows uniform access to an underlying logging implementation.
+
+  The default value will be obtained by invoking a no-arg function named by the
+  \"clojure.tools.logging.factory\" system property, or if unset, by invoking
+  clojure.tools.logging.impl/find-factory.
+
+  After loading, this var can be programmatically changed to a different
+  LoggerFactory implementation via binding or alter-var-root.
+
+  See the various factory functions in clojure.tools.logger.impl."
+  (find-factory))

src/test/clojure/clojure/tools/test_logging.clj

@@ -1,8 +1,8 @@
 (ns clojure.tools.test-logging
-  (:use clojure.test
-        clojure.tools.logging)
+  (:use clojure.test)
   (:require
     [clojure.set :as set]
+    [clojure.tools.logging :as log :refer :all]
     [clojure.tools.logging.impl :as impl]
     [clojure.tools.logging.test :as log-test :refer [logged?
                                                      matches]]))
@@ -357,3 +357,34 @@
       warnf :warn
       errorf :error
       fatalf :fatal)))
+
+
+(deftest test-call-str
+  (testing "throws exception if input is not fully-qualified"
+    (is (thrown-with-msg? RuntimeException #"fully-qualified"
+                          (#'log/call-str "foobar"))))
+
+  (testing "throws exception if ns does not exist"
+    (is (thrown-with-msg? RuntimeException #"resolve namespace"
+                          (#'log/call-str "missing.ns/some-fn"))))
+
+  (testing "throws exception if fn does not exist"
+    (is (thrown-with-msg? RuntimeException #"resolve var"
+                          (#'log/call-str "external.ns/does-not-exist-fn"))))
+
+  (testing "yields the right factory when specified"
+    (is (= "external.ns/good-fn"
+           (impl/name (#'log/call-str "external.ns/factory"))))))
+
+
+(deftest test-find-factory
+  (testing "when system property is unset, invokes impl/find-factory"
+    (System/clearProperty "clojure.tools.logging.factory")
+    (is (= (impl/name (impl/find-factory)) (impl/name (#'log/find-factory)))))
+
+  (testing "when system propery is set, yields the results"
+    (System/setProperty "clojure.tools.logging.factory" "external.ns/factory")
+    (is (= "external.ns/good-fn" (impl/name (#'log/find-factory)))))
+
+  (System/clearProperty "clojure.tools.logging.factory"))
+

src/test/clojure/external/ns.clj

@@ -0,0 +1,8 @@
+(ns external.ns
+  "Used by clojure.tools.logging.test-logging."
+  (:require [clojure.tools.logging.impl :as impl]))
+
+(defn factory []
+  (reify impl/LoggerFactory
+    (name [_] "external.ns/good-fn")
+    (get-logger [_ _] (impl/disabled-logger))))