Offer restricted access to DataBuffer's ByteBuffer

This commit introduces DataBuffer::readableByteBuffers and
DataBuffer::writableByteBuffers, allowing restricted access to the
ByteBuffer used internally by DataBuffer implementations.

Closes gh-29943

Author: poutsma

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -51,9 +51,11 @@ public boolean canDecode(ResolvableType elementType, @Nullable MimeType mimeType
 	public ByteBuffer decode(DataBuffer dataBuffer, ResolvableType elementType,
 			@Nullable MimeType mimeType, @Nullable Map<String, Object> hints) {
 
-		ByteBuffer result = dataBuffer.toByteBuffer();
+		int len = dataBuffer.readableByteCount();
+		ByteBuffer result = ByteBuffer.allocate(len);
+		dataBuffer.toByteBuffer(result);
 		if (logger.isDebugEnabled()) {
-			logger.debug(Hints.getLogPrefix(hints) + "Read " + dataBuffer.readableByteCount() + " bytes");
+			logger.debug(Hints.getLogPrefix(hints) + "Read " + len + " bytes");
 		}
 		DataBufferUtils.release(dataBuffer);
 		return result;

spring-core/src/main/java/org/springframework/core/io/buffer/DataBuffer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -16,14 +16,18 @@
 
 package org.springframework.core.io.buffer;
 
+import java.io.Closeable;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.UncheckedIOException;
 import java.nio.ByteBuffer;
 import java.nio.CharBuffer;
+import java.nio.charset.CharacterCodingException;
 import java.nio.charset.Charset;
 import java.nio.charset.CharsetEncoder;
 import java.nio.charset.CoderResult;
 import java.nio.charset.CodingErrorAction;
+import java.util.Iterator;
 import java.util.function.IntPredicate;
 
 import org.springframework.util.Assert;
@@ -265,27 +269,28 @@ default DataBuffer write(CharSequence charSequence, Charset charset) {
 			CharsetEncoder charsetEncoder = charset.newEncoder()
 					.onMalformedInput(CodingErrorAction.REPLACE)
 					.onUnmappableCharacter(CodingErrorAction.REPLACE);
-			CharBuffer inBuffer = CharBuffer.wrap(charSequence);
-			int estimatedSize = (int) (inBuffer.remaining() * charsetEncoder.averageBytesPerChar());
-			ByteBuffer outBuffer = ensureCapacity(estimatedSize)
-					.asByteBuffer(writePosition(), writableByteCount());
-			while (true) {
-				CoderResult cr = (inBuffer.hasRemaining() ?
-						charsetEncoder.encode(inBuffer, outBuffer, true) : CoderResult.UNDERFLOW);
-				if (cr.isUnderflow()) {
-					cr = charsetEncoder.flush(outBuffer);
+			CharBuffer src = CharBuffer.wrap(charSequence);
+			int length = (int) (src.remaining() * charsetEncoder.maxBytesPerChar());
+			ensureWritable(length);
+			try (ByteBufferIterator iterator = writableByteBuffers()) {
+				Assert.state(iterator.hasNext(), "No ByteBuffer available");
+				ByteBuffer dest = iterator.next();
+				int pos = dest.position();
+				CoderResult cr = charsetEncoder.encode(src, dest, true);
+				if (!cr.isUnderflow()) {
+					cr.throwException();
 				}
-				if (cr.isUnderflow()) {
-					break;
-				}
-				if (cr.isOverflow()) {
-					writePosition(writePosition() + outBuffer.position());
-					int maximumSize = (int) (inBuffer.remaining() * charsetEncoder.maxBytesPerChar());
-					ensureCapacity(maximumSize);
-					outBuffer = asByteBuffer(writePosition(), writableByteCount());
+				cr = charsetEncoder.flush(dest);
+				if (!cr.isUnderflow()) {
+					cr.throwException();
 				}
+				length = dest.position() - pos;
+			}
+			catch (CharacterCodingException ex) {
+				// should not happen, because the encoder uses action REPLACE
+				throw new UncheckedIOException(ex);
 			}
-			writePosition(writePosition() + outBuffer.position());
+			writePosition(writePosition() + length);
 		}
 		return this;
 	}
@@ -353,8 +358,8 @@ default DataBuffer retainedSlice(int index, int length) {
 	 * changes in the returned buffer's {@linkplain ByteBuffer#position() position}
 	 * will not be reflected in the reading nor writing position of this data buffer.
 	 * @return this data buffer as a byte buffer
-	 * @deprecated as of 6.0, in favor of {@link #toByteBuffer()}, which does
-	 * <strong>not</strong> share data and returns a copy.
+	 * @deprecated as of 6.0, in favor of {@link #toByteBuffer(ByteBuffer)},
+	 * {@link #readableByteBuffers()}, or {@link #writableByteBuffers()}.
 	 */
 	@Deprecated(since = "6.0")
 	ByteBuffer asByteBuffer();
@@ -368,8 +373,8 @@ default DataBuffer retainedSlice(int index, int length) {
 	 * @param length the length of the returned byte buffer
 	 * @return this data buffer as a byte buffer
 	 * @since 5.0.1
-	 * @deprecated as of 6.0, in favor of {@link #toByteBuffer(int, int)}, which
-	 * does <strong>not</strong> share data and returns a copy.
+	 * @deprecated as of 6.0, in favor of {@link #toByteBuffer(int, ByteBuffer, int, int)},
+	 * {@link #readableByteBuffers()}, or {@link #writableByteBuffers()}.
 	 */
 	@Deprecated(since = "6.0")
 	ByteBuffer asByteBuffer(int index, int length);
@@ -380,7 +385,11 @@ default DataBuffer retainedSlice(int index, int length) {
 	 * <strong>not</strong> shared.
 	 * @return this data buffer as a byte buffer
 	 * @since 6.0
+	 * @see #readableByteBuffers()
+	 * @see #writableByteBuffers()
+	 * @deprecated as of 6.0.5, in favor of {@link #toByteBuffer(ByteBuffer)}
 	 */
+	@Deprecated(since = "6.0.5")
 	default ByteBuffer toByteBuffer() {
 		return toByteBuffer(readPosition(), readableByteCount());
 	}
@@ -391,9 +400,67 @@ default ByteBuffer toByteBuffer() {
 	 * {@code ByteBuffer} is <strong>not</strong> shared.
 	 * @return this data buffer as a byte buffer
 	 * @since 6.0
+	 * @see #readableByteBuffers()
+	 * @see #writableByteBuffers()
+	 * @deprecated as of 6.0.5, in favor of
+	 * {@link #toByteBuffer(int, ByteBuffer, int, int)}
 	 */
+	@Deprecated(since = "6.0.5")
 	ByteBuffer toByteBuffer(int index, int length);
 
+	/**
+	 * Copies this entire data buffer into the given destination
+	 * {@code ByteBuffer}, beginning at the current
+	 * {@linkplain #readPosition() reading position}, and the current
+	 * {@linkplain ByteBuffer#position() position} of destination byte buffer.
+	 * @param dest the destination byte buffer
+	 * @since 6.0.5
+	 */
+	default void toByteBuffer(ByteBuffer dest) {
+		toByteBuffer(readPosition(), dest, dest.position(), readableByteCount());
+	}
+
+	/**
+	 * Copies the given length from this data buffer into the given destination
+	 * {@code ByteBuffer}, beginning at the given source position, and the
+	 * given destination position in the destination byte buffer.
+	 * @param srcPos the position of this data buffer from where copying should
+	 * start
+	 * @param dest the destination byte buffer
+	 * @param destPos the position in {@code dest} to where copying should
+	 * start
+	 * @param length the amount of data to copy
+	 * @since 6.0.5
+	 */
+	void toByteBuffer(int srcPos, ByteBuffer dest, int destPos, int length);
+
+	/**
+	 * Returns a closeable iterator over each {@link ByteBuffer} in this data
+	 * buffer that can be read. Calling this method is more efficient than
+	 * {@link #toByteBuffer()}, as no data is copied. However, the byte buffers
+	 * provided can only be used during the iteration.
+	 *
+	 * <p><b>Note</b> that the returned iterator must be used in a
+	 * try-with-resources clause or explicitly
+	 * {@linkplain ByteBufferIterator#close() closed}.
+	 * @return a closeable iterator over the readable byte buffers contained in this data buffer
+	 * @since 6.0.5
+	 */
+	ByteBufferIterator readableByteBuffers();
+
+	/**
+	 * Returns a closeable iterator over each {@link ByteBuffer} in this data
+	 * buffer that can be written to. The byte buffers provided can only be used
+	 * during the iteration.
+	 *
+	 * <p><b>Note</b> that the returned iterator must be used in a
+	 * try-with-resources clause or explicitly
+	 * {@linkplain ByteBufferIterator#close() closed}.
+	 * @return a closeable iterator over the writable byte buffers contained in this data buffer
+	 * @since 6.0.5
+	 */
+	ByteBufferIterator writableByteBuffers();
+
 	/**
 	 * Expose this buffer's data as an {@link InputStream}. Both data and read position are
 	 * shared between the returned stream and this data buffer. The underlying buffer will
@@ -450,4 +517,20 @@ default String toString(Charset charset) {
 	 */
 	String toString(int index, int length, Charset charset);
 
+
+	/**
+	 * A dedicated iterator type that ensures the lifecycle of iterated
+	 * {@link ByteBuffer} elements. This iterator must be used in a
+	 * try-with-resources clause or explicitly {@linkplain #close() closed}.
+	 *
+	 * @see DataBuffer#readableByteBuffers()
+	 * @see DataBuffer#writableByteBuffers()
+	 */
+	interface ByteBufferIterator extends Iterator<ByteBuffer>, Closeable {
+
+		@Override
+		void close();
+
+	}
+
 }