Add LogUtils and HttpLogging

SPR-17012

Author: rstoyanchev

spring-web/src/main/java/org/springframework/http/HttpLog.java renamed to spring-core/src/main/java/org/springframework/util/log/CompositeLog.java

@@ -13,36 +13,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.http;
+package org.springframework.util.log;
 
-import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 import java.util.function.Predicate;
 
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 import org.apache.commons.logging.impl.NoOpLog;
 
-import org.springframework.util.ObjectUtils;
-
 /**
- * Composite {@link Log} configured with a primary logger and a list of secondary
- * ones to fall back on if the main one is not enabled.
- *
- * <p>This class also declares {@link #webLogger} for use as fallback when
- * logging in the "org.springframework.http" package.
+ * Implementation of {@link Log} that wraps a list of loggers and delegates to
+ * the first one for which logging is enabled at the given level.
  *
  * @author Rossen Stoyanchev
  * @since 5.1
+ * @see LogUtils#getCompositeLog
  */
-public final class HttpLog implements Log {
-
-	/**
-	 * Logger with category "org.springframework.web.HTTP" to use as fallback
-	 * if "org.springframework.web" is on.
-	 */
-	public static final Log webLogger = LogFactory.getLog("org.springframework.web.HTTP");
+class CompositeLog implements Log {
 
 	private static final Log noOpLog = new NoOpLog();
 
@@ -60,7 +47,12 @@ public final class HttpLog implements Log {
 	private final Log traceLogger;
 
 
-	private HttpLog(List<Log> loggers) {
+	/**
+	 * Constructor with list of loggers. For optimal performance, the constructor
+	 * checks and remembers which logger is on for each log category.
+	 * @param loggers the loggers to use
+	 */
+	public CompositeLog(List<Log> loggers) {
 		this.fatalLogger = initLogger(loggers, Log::isFatalEnabled);
 		this.errorLogger = initLogger(loggers, Log::isErrorEnabled);
 		this.warnLogger  = initLogger(loggers, Log::isWarnEnabled);
@@ -163,33 +155,4 @@ public void trace(Object message) {
 	public void trace(Object message, Throwable ex) {
 		this.traceLogger.trace(message, ex);
 	}
-
-
-	/**
-	 * Create a composite logger that uses the given primary logger, if enabled,
-	 * or falls back on {@link #webLogger}.
-	 * @param primaryLogger the primary logger
-	 * @return a composite logger
-	 */
-	public static Log create(Log primaryLogger) {
-		return createWith(primaryLogger, webLogger);
-	}
-
-	/**
-	 * Create a composite logger that uses the given primary logger, if enabled,
-	 * or falls back on one of the given secondary loggers..
-	 * @param primaryLogger the primary logger
-	 * @param secondaryLoggers fallback loggers
-	 * @return a composite logger
-	 */
-	public static Log createWith(Log primaryLogger, Log... secondaryLoggers) {
-		if (ObjectUtils.isEmpty(secondaryLoggers)) {
-			return primaryLogger;
-		}
-		List<Log> loggers = new ArrayList<>(1 + secondaryLoggers.length);
-		loggers.add(primaryLogger);
-		Collections.addAll(loggers, secondaryLoggers);
-		return new HttpLog(loggers);
-	}
-
 }

spring-core/src/main/java/org/springframework/util/log/LogUtils.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2002-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.util.log;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+/**
+ * Utilities to assist with logging. Mainly for internal use within the framework
+ * with Appache Commons Logging.
+ *
+ * @author Rossen Stoyanchev
+ * @since 5.1
+ */
+public abstract class LogUtils {
+
+	/**
+	 * Create a composite logger that delegates to a primary or falls back on a
+	 * secondary logger if logging for the primary logger is not enabled.
+	 * <p>This may be used for fallback logging from lower level packages that
+	 * logically should log together with some higher level package but the two
+	 * don't happen to share a suitable parent package (e.g. logging for the web
+	 * and lower level http and codec packages). For such cases the primary,
+	 * class-based logger can be wrapped with a shared fallback logger.
+	 * @param primaryLogger primary logger to try first
+	 * @param secondaryLogger secondary logger
+	 * @param tertiaryLoggers optionally, more fallback loggers
+	 * @return the resulting logger to use
+	 */
+	public static Log getCompositeLog(Log primaryLogger, Log secondaryLogger, Log... tertiaryLoggers) {
+		List<Log> loggers = new ArrayList<>(2 + tertiaryLoggers.length);
+		loggers.add(primaryLogger);
+		loggers.add(secondaryLogger);
+		Collections.addAll(loggers, tertiaryLoggers);
+		return new CompositeLog(loggers);
+	}
+
+	/**
+	 * Create a "hidden" logger whose name is intentionally prefixed with "_"
+	 * because its output is either too verbose or otherwise deemed as optional
+	 * or unnecessary to see at any log level by default under the normal package
+	 * based log hierarchy.
+	 * @param clazz the class for which to create a logger
+	 * @return the created logger
+	 */
+	public static Log getHiddenLog(Class<?> clazz) {
+		return LogFactory.getLog("_" + clazz.getName());
+	}
+
+}

spring-core/src/main/java/org/springframework/util/log/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * Useful helper classes for logging.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.util.log;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/HttpLogging.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2002-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.http;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import org.springframework.util.log.LogUtils;
+
+/**
+ * Holds the shared logger named "org.springframework.web.HttpLogging" for HTTP
+ * related logging when "org.springframework.http" is not enabled but
+ * "org.springframework.web" is.
+ *
+ * <p>That means "org.springframework.web" enables all web logging including
+ * from lower level packages such as "org.springframework.http" and modules
+ * such as codecs from {@literal "spring-core"} when those are wrapped with
+ * {@link org.springframework.http.codec.EncoderHttpMessageWriter EncoderHttpMessageWriter} or
+ * {@link org.springframework.http.codec.DecoderHttpMessageReader DecoderHttpMessageReader}.
+ *
+ * <p>To see logging from the primary class loggers simply enable logging for
+ * "org.springframework.http" and "org.springframework.codec".
+ *
+ * @author Rossen Stoyanchev
+ * @since 5.1
+ */
+public abstract class HttpLogging {
+
+	private static final Log fallbackLogger =
+			LogFactory.getLog("org.springframework.web." + HttpLogging.class.getSimpleName());
+
+
+	/**
+	 * Create a primary logger for the given class and wrap it with a composite
+	 * that delegates to it or to the fallback logger
+	 * "org.springframework.web.HttpLogging", if the primary is not enabled.
+	 * @param primaryLoggerClass the class for the name of the primary logger
+	 * @return the resulting composite logger
+	 */
+	public static Log forLogName(Class<?> primaryLoggerClass) {
+		Log primaryLogger = LogFactory.getLog(primaryLoggerClass);
+		return forLog(primaryLogger);
+	}
+
+	/**
+	 * Wrap the given primary logger with a composite logger that delegates to
+	 * it or to the fallback logger "org.springframework.web.HttpLogging", if
+	 * the primary is not enabled.
+	 * @param primaryLogger the primary logger to use
+	 * @return the resulting composite logger
+	 */
+	public static Log forLog(Log primaryLogger) {
+		return LogUtils.getCompositeLog(primaryLogger, fallbackLogger);
+	}
+
+}

spring-web/src/main/java/org/springframework/http/client/support/AsyncHttpAccessor.java

@@ -20,8 +20,8 @@
 import java.net.URI;
 
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 
+import org.springframework.http.HttpLogging;
 import org.springframework.http.HttpMethod;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
@@ -44,7 +44,7 @@
 public class AsyncHttpAccessor {
 
 	/** Logger available to subclasses. */
-	protected final Log logger = LogFactory.getLog(getClass());
+	protected final Log logger = HttpLogging.forLogName(getClass());
 
 	@Nullable
 	private org.springframework.http.client.AsyncClientHttpRequestFactory asyncRequestFactory;

spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java

@@ -20,8 +20,8 @@
 import java.net.URI;
 
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 
+import org.springframework.http.HttpLogging;
 import org.springframework.http.HttpMethod;
 import org.springframework.http.client.ClientHttpRequest;
 import org.springframework.http.client.ClientHttpRequestFactory;
@@ -45,7 +45,7 @@
 public abstract class HttpAccessor {
 
 	/** Logger available to subclasses. */
-	protected final Log logger = LogFactory.getLog(getClass());
+	protected final Log logger = HttpLogging.forLogName(getClass());
 
 	private ClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
 

spring-web/src/main/java/org/springframework/http/codec/DecoderHttpMessageReader.java

@@ -27,7 +27,7 @@
 import org.springframework.core.codec.AbstractDecoder;
 import org.springframework.core.codec.Decoder;
 import org.springframework.core.codec.Hints;
-import org.springframework.http.HttpLog;
+import org.springframework.http.HttpLogging;
 import org.springframework.http.HttpMessage;
 import org.springframework.http.MediaType;
 import org.springframework.http.ReactiveHttpInputMessage;
@@ -70,7 +70,7 @@ private void initLogger(Decoder<T> decoder) {
 		if (decoder instanceof AbstractDecoder &&
 				decoder.getClass().getPackage().getName().startsWith("org.springframework.core.codec")) {
 
-			Log logger = HttpLog.create(((AbstractDecoder) decoder).getLogger());
+			Log logger = HttpLogging.forLog(((AbstractDecoder) decoder).getLogger());
 			((AbstractDecoder) decoder).setLogger(logger);
 		}
 	}

spring-web/src/main/java/org/springframework/http/codec/EncoderHttpMessageWriter.java

@@ -30,7 +30,7 @@
 import org.springframework.core.codec.Hints;
 import org.springframework.core.io.buffer.DataBuffer;
 import org.springframework.http.HttpHeaders;
-import org.springframework.http.HttpLog;
+import org.springframework.http.HttpLogging;
 import org.springframework.http.MediaType;
 import org.springframework.http.ReactiveHttpOutputMessage;
 import org.springframework.http.server.reactive.ServerHttpRequest;
@@ -76,7 +76,7 @@ private void initLogger(Encoder<T> encoder) {
 		if (encoder instanceof AbstractEncoder &&
 				encoder.getClass().getPackage().getName().startsWith("org.springframework.core.codec")) {
 
-			Log logger = HttpLog.create(((AbstractEncoder) encoder).getLogger());
+			Log logger = HttpLogging.forLog(((AbstractEncoder) encoder).getLogger());
 			((AbstractEncoder) encoder).setLogger(logger);
 		}
 	}

spring-web/src/main/java/org/springframework/http/codec/LoggingCodecSupport.java

@@ -16,9 +16,8 @@
 package org.springframework.http.codec;
 
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 
-import org.springframework.http.HttpLog;
+import org.springframework.http.HttpLogging;
 
 /**
  * Base class for {@link org.springframework.core.codec.Encoder},
@@ -31,7 +30,7 @@
  */
 public class LoggingCodecSupport {
 
-	protected final Log logger = HttpLog.create(LogFactory.getLog(getClass()));
+	protected final Log logger = HttpLogging.forLogName(getClass());
 
 	/** Whether to log potentially sensitive info (form data at DEBUG and headers at TRACE). */
 	private boolean enableLoggingRequestDetails = false;

spring-web/src/main/java/org/springframework/http/codec/ResourceHttpMessageWriter.java

@@ -23,7 +23,6 @@
 import java.util.Optional;
 
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 import org.reactivestreams.Publisher;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
@@ -39,7 +38,7 @@
 import org.springframework.core.io.buffer.DataBufferFactory;
 import org.springframework.core.io.support.ResourceRegion;
 import org.springframework.http.HttpHeaders;
-import org.springframework.http.HttpLog;
+import org.springframework.http.HttpLogging;
 import org.springframework.http.HttpRange;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
@@ -73,7 +72,7 @@ public class ResourceHttpMessageWriter implements HttpMessageWriter<Resource> {
 
 	private static final ResolvableType REGION_TYPE = ResolvableType.forClass(ResourceRegion.class);
 
-	private static final Log logger = HttpLog.create(LogFactory.getLog(ResourceHttpMessageWriter.class));
+	private static final Log logger = HttpLogging.forLogName(ResourceHttpMessageWriter.class);
 
 
 	private final ResourceEncoder encoder;

spring-web/src/main/java/org/springframework/http/codec/json/Jackson2CodecSupport.java

@@ -29,13 +29,12 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.type.TypeFactory;
 import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 
 import org.springframework.core.GenericTypeResolver;
 import org.springframework.core.MethodParameter;
 import org.springframework.core.ResolvableType;
 import org.springframework.core.codec.Hints;
-import org.springframework.http.HttpLog;
+import org.springframework.http.HttpLogging;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.MimeType;
@@ -66,7 +65,7 @@ public abstract class Jackson2CodecSupport {
 					new MimeType("application", "*+json", StandardCharsets.UTF_8)));
 
 
-	protected final Log logger = HttpLog.create(LogFactory.getLog(getClass()));
+	protected final Log logger = HttpLogging.forLogName(getClass());
 
 	private final ObjectMapper objectMapper;