Correlated encoding/decoding log messages via hints

Issue: SPR-16966

Author: rstoyanchev

spring-core/src/main/java/org/springframework/core/codec/AbstractEncoder.java

@@ -18,7 +18,6 @@
 
 import java.util.Arrays;
 import java.util.List;
-import java.util.Map;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
@@ -60,17 +59,4 @@ public boolean canEncode(ResolvableType elementType, @Nullable MimeType mimeType
 		return this.encodableMimeTypes.stream().anyMatch(candidate -> candidate.isCompatibleWith(mimeType));
 	}
 
-	/**
-	 * Helper method to obtain the logger to use from the Map of hints, or fall
-	 * back on the default logger. This may be used for example to override
-	 * logging, e.g. for a multipart request where the full map of part values
-	 * has already been logged.
-	 * @param hints the hints passed to the encode method
-	 * @return the logger to use
-	 * @since 5.1
-	 */
-	protected Log getLogger(@Nullable Map<String, Object> hints) {
-		return hints != null ? ((Log) hints.getOrDefault(Log.class.getName(), logger)) : logger;
-	}
-
 }

spring-core/src/main/java/org/springframework/core/codec/ByteArrayDecoder.java

@@ -54,7 +54,7 @@ protected byte[] decodeDataBuffer(DataBuffer dataBuffer, ResolvableType elementT
 		dataBuffer.read(result);
 		DataBufferUtils.release(dataBuffer);
 		if (logger.isDebugEnabled()) {
-			logger.debug("Read " + result.length + " bytes");
+			logger.debug(Hints.getLogPrefix(hints) + "Read " + result.length + " bytes");
 		}
 		return result;
 	}

spring-core/src/main/java/org/springframework/core/codec/ByteArrayEncoder.java

@@ -55,9 +55,10 @@ public Flux<DataBuffer> encode(Publisher<? extends byte[]> inputStream,
 
 		return Flux.from(inputStream).map(bytes -> {
 			DataBuffer dataBuffer = bufferFactory.wrap(bytes);
-			Log logger = getLogger(hints);
-			if (logger.isDebugEnabled()) {
-				logger.debug("Writing " + dataBuffer.readableByteCount() + " bytes");
+			Log theLogger = Hints.getLoggerOrDefault(hints, logger);
+			if (theLogger.isDebugEnabled()) {
+				theLogger.debug(Hints.getLogPrefix(hints) +
+						"Writing " + dataBuffer.readableByteCount() + " bytes");
 			}
 			return dataBuffer;
 		});

spring-core/src/main/java/org/springframework/core/codec/ByteBufferDecoder.java

@@ -58,7 +58,7 @@ protected ByteBuffer decodeDataBuffer(DataBuffer dataBuffer, ResolvableType elem
 		copy.flip();
 		DataBufferUtils.release(dataBuffer);
 		if (logger.isDebugEnabled()) {
-			logger.debug("Read " + byteCount + " bytes");
+			logger.debug(Hints.getLogPrefix(hints) + "Read " + byteCount + " bytes");
 		}
 		return copy;
 	}

spring-core/src/main/java/org/springframework/core/codec/ByteBufferEncoder.java

@@ -56,9 +56,10 @@ public Flux<DataBuffer> encode(Publisher<? extends ByteBuffer> inputStream,
 
 		return Flux.from(inputStream).map(byteBuffer -> {
 			DataBuffer dataBuffer = bufferFactory.wrap(byteBuffer);
-			Log logger = getLogger(hints);
-			if (logger.isDebugEnabled()) {
-				logger.debug("Writing " + dataBuffer.readableByteCount() + " bytes");
+			Log theLogger = Hints.getLoggerOrDefault(hints, logger);
+			if (theLogger.isDebugEnabled()) {
+				theLogger.debug(Hints.getLogPrefix(hints) +
+						"Writing " + dataBuffer.readableByteCount() + " bytes");
 			}
 			return dataBuffer;
 		});

spring-core/src/main/java/org/springframework/core/codec/CharSequenceEncoder.java

@@ -69,9 +69,9 @@ public Flux<DataBuffer> encode(Publisher<? extends CharSequence> inputStream,
 		Charset charset = getCharset(mimeType);
 
 		return Flux.from(inputStream).map(charSequence -> {
-			Log logger = getLogger(hints);
-			if (logger.isDebugEnabled()) {
-				logger.debug("Writing '" + charSequence + "'");
+			Log theLogger = Hints.getLoggerOrDefault(hints, logger);
+			if (theLogger.isDebugEnabled()) {
+				theLogger.debug(Hints.getLogPrefix(hints) + "Writing '" + charSequence + "'");
 			}
 			CharBuffer charBuffer = CharBuffer.wrap(charSequence);
 			ByteBuffer byteBuffer = charset.encode(charBuffer);

spring-core/src/main/java/org/springframework/core/codec/DataBufferDecoder.java

@@ -63,7 +63,7 @@ protected DataBuffer decodeDataBuffer(DataBuffer buffer, ResolvableType elementT
 			@Nullable MimeType mimeType, @Nullable Map<String, Object> hints) {
 
 		if (logger.isDebugEnabled()) {
-			logger.debug("Read " + buffer.readableByteCount() + " bytes");
+			logger.debug(Hints.getLogPrefix(hints) + "Read " + buffer.readableByteCount() + " bytes");
 		}
 		return buffer;
 	}

spring-core/src/main/java/org/springframework/core/codec/DataBufferEncoder.java

@@ -55,9 +55,11 @@ public Flux<DataBuffer> encode(Publisher<? extends DataBuffer> inputStream,
 
 		Flux<DataBuffer> flux = Flux.from(inputStream);
 
-		Log logger = getLogger(hints);
-		if (logger.isDebugEnabled()) {
-			flux = flux.doOnNext(buffer -> logger.debug("Writing " + buffer.readableByteCount() + " bytes"));
+		Log theLogger = Hints.getLoggerOrDefault(hints, logger);
+		if (theLogger.isDebugEnabled()) {
+			flux = flux.doOnNext(buffer ->
+					theLogger.debug(Hints.getLogPrefix(hints) +
+							"Writing " + buffer.readableByteCount() + " bytes"));
 		}
 
 		return flux;

spring-core/src/main/java/org/springframework/core/codec/Hints.java

@@ -0,0 +1,153 @@
+/*
+ * 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.core.codec;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.apache.commons.logging.Log;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Constants and convenience methods for working with hints.
+ *
+ * @author Rossen Stoyanchev
+ * @since 5.1
+ * @see ResourceRegionEncoder#BOUNDARY_STRING_HINT
+ */
+public abstract class Hints {
+
+	/**
+	 * Name of hint exposing a prefix to use for correlating log messages.
+	 * @since 5.1
+	 */
+	public static final String LOG_PREFIX_HINT = Log.class.getName() + ".PREFIX";
+
+	/**
+	 * Name of hint for a preferred {@link Log logger} to use. This can be used
+	 * by a composite encoder (e.g. multipart requests) to control or suppress
+	 * logging by individual part encoders.
+	 * @since 5.1
+	 */
+	public static final String LOGGER_HINT = Log.class.getName();
+
+
+	/**
+	 * Create a map wit a single hint via {@link Collections#singletonMap}.
+	 * @param hintName the hint name
+	 * @param value the hint value
+	 * @return the created map
+	 */
+	public static Map<String, Object> from(String hintName, Object value) {
+		return Collections.singletonMap(hintName, value);
+	}
+
+	/**
+	 * Return an empty map of hints via {@link Collections#emptyMap()}.
+	 * @return the empty map
+	 */
+	public static Map<String, Object> none() {
+		return Collections.emptyMap();
+	}
+
+	/**
+	 * Obtain the value for a required hint.
+	 * @param hints the hints map
+	 * @param hintName the required hint name
+	 * @param <T> the hint type to cast to
+	 * @return the hint value
+	 * @throws IllegalArgumentException if the hint is not found
+	 */
+	@SuppressWarnings("unchecked")
+	public static <T> T getRequiredHint(@Nullable Map<String, Object> hints, String hintName) {
+		if (hints == null) {
+			throw new IllegalArgumentException("No hints map for required hint '" + hintName + "'");
+		}
+		T hint = (T) hints.get(hintName);
+		if (hint == null) {
+			throw new IllegalArgumentException("Hints map must contain the hint '" + hintName + "'");
+		}
+		return hint;
+	}
+
+	/**
+	 * Obtain the hint {@link #LOG_PREFIX_HINT}, if present, or an empty String.
+	 * @param hints the hints passed to the encode method
+	 * @return the log prefix
+	 */
+	public static String getLogPrefix(@Nullable Map<String, Object> hints) {
+		return hints != null ? (String) hints.getOrDefault(LOG_PREFIX_HINT, "") : "";
+	}
+
+	/**
+	 * Obtain the hint {@link #LOGGER_HINT}, if present, or the given logger.
+	 * @param hints the hints passed to the encode method
+	 * @param defaultLogger the logger to return if a hint is not found
+	 * @return the logger to use
+	 */
+	public static Log getLoggerOrDefault(@Nullable Map<String, Object> hints, Log defaultLogger) {
+		return hints != null ? (Log) hints.getOrDefault(LOGGER_HINT, defaultLogger) : defaultLogger;
+	}
+
+	/**
+	 * Merge two maps of hints, creating and copying into a new map if both have
+	 * values, or returning the non-empty map, or an empty map if both are empty.
+	 * @param hints1 1st map of hints
+	 * @param hints2 2nd map of hints
+	 * @return a single map with hints from both
+	 */
+	public static Map<String, Object> merge(Map<String, Object> hints1, Map<String, Object> hints2) {
+		if (hints1.isEmpty() && hints2.isEmpty()) {
+			return Collections.emptyMap();
+		}
+		else if (hints2.isEmpty()) {
+			return hints1;
+		}
+		else if (hints1.isEmpty()) {
+			return hints2;
+		}
+		else {
+			Map<String, Object> result = new HashMap<>(hints1.size() + hints2.size());
+			result.putAll(hints1);
+			result.putAll(hints2);
+			return result;
+		}
+	}
+
+	/**
+	 * Merge a single hint into a map of hints, possibly creating and copying
+	 * all hints into a new map, or otherwise if the map of hints is empty,
+	 * creating a new single entry map.
+	 * @param hints a map of hints to be merge
+	 * @param hintName the hint name to merge
+	 * @param hintValue the hint value to merge
+	 * @return a single map with all hints
+	 */
+	public static Map<String, Object> merge(Map<String, Object> hints, String hintName, Object hintValue) {
+		if (hints.isEmpty()) {
+			return Collections.singletonMap(hintName, hintValue);
+		}
+		else {
+			Map<String, Object> result = new HashMap<>(hints.size() + 1);
+			result.putAll(hints);
+			result.put(hintName, hintValue);
+			return result;
+		}
+	}
+
+}

spring-core/src/main/java/org/springframework/core/codec/ResourceDecoder.java

@@ -73,7 +73,7 @@ protected Resource decodeDataBuffer(DataBuffer dataBuffer, ResolvableType elemen
 		Assert.state(clazz != null, "No resource class");
 
 		if (logger.isDebugEnabled()) {
-			logger.debug("Read " + bytes.length + " bytes");
+			logger.debug(Hints.getLogPrefix(hints) + "Read " + bytes.length + " bytes");
 		}
 
 		if (InputStreamResource.class == clazz) {