Add tests and update javadocs

Author: davidh44

core/sdk-core/src/main/java/software/amazon/awssdk/core/ResponseBytes.java

@@ -70,11 +70,24 @@ public static <ResponseT> ResponseBytes<ResponseT> fromByteArrayUnsafe(ResponseT
     }
 
     /**
-     * Creates ResponseBytes from a ByteBuffer without copying the underlying data.
+     * Create {@link ResponseBytes} from a {@link ByteBuffer} with minimal copying. This method attempts to avoid
+     * copying data when possible, but introduces concurrency risks in specific scenarios.
      *
-     * @param response the response object containing metadata
-     * @param buffer the ByteBuffer containing the response body data
-     * @return ResponseBytes wrapping the buffer data
+     * <p><b>Behavior by buffer type:</b>
+     * <ul>
+     *   <li><b>Array-backed ByteBuffer (perfect match):</b> When the buffer represents the entire backing array
+     *       (offset=0, remaining=array.length), the array is shared <b>without</b> copying. This introduces the same
+     *       concurrency risks as {@link #fromByteArrayUnsafe(Object, byte[])}: modifications to the original
+     *       backing array will affect the returned {@link ResponseBytes}.</li>
+     *   <li><b>Array-backed ByteBuffer (partial):</b> When the buffer represents only a portion of the backing array,
+     *       data is copied to a new array. No concurrency risks.</li>
+     *   <li><b>Direct ByteBuffer:</b> Data is always copied to a heap array. No concurrency risks.</li>
+     * </ul>
+     *
+     * <p>The buffer's position is preserved and not modified by this operation.
+     *
+     * <p>As the method name implies, this is unsafe in the first scenario. Use a safe alternative unless you're
+     * sure you know the risks.
      */
     public static <ResponseT> ResponseBytes<ResponseT> fromByteBufferUnsafe(ResponseT response, ByteBuffer buffer) {
         byte[] array;
@@ -91,7 +104,9 @@ public static <ResponseT> ResponseBytes<ResponseT> fromByteBufferUnsafe(Response
         } else {
             // Direct buffer - must copy to array
             array = new byte[buffer.remaining()];
+            int originalPosition = buffer.position();
             buffer.get(array);
+            buffer.position(originalPosition);
         }
         return new ResponseBytes<>(response, array);
     }

core/sdk-core/src/test/java/software/amazon/awssdk/core/ResponseBytesTest.java

@@ -49,20 +49,57 @@ public void fromByteArrayUnsafeAndAsByteArrayUnsafeDoNotCopy() {
     }
 
     @Test
-    public void fromByteBufferUnsafe_doNotCopy() {
+    public void fromByteBufferUnsafe_fullBuffer_doesNotCopy() {
         byte[] inputBytes = {'a'};
         ByteBuffer inputBuffer = ByteBuffer.wrap(inputBytes);
 
         ResponseBytes<Object> responseBytes = ResponseBytes.fromByteBufferUnsafe(OBJECT, inputBuffer);
-
-        ByteBuffer outputBuffer = responseBytes.asByteBuffer();
         byte[] outputBytes = responseBytes.asByteArrayUnsafe();
 
-        assertThat(outputBuffer).isEqualTo(inputBuffer);
+        assertThat(inputBuffer.hasArray()).isTrue();
+        assertThat(inputBuffer.isDirect()).isFalse();
         assertThat(outputBytes).isSameAs(inputBytes);
 
         inputBytes[0] = 'b';
-        assertThat(outputBuffer).isEqualTo(inputBuffer);
+        assertThat(outputBytes[0]).isEqualTo((byte) 'b');
+    }
+
+    @Test
+    public void fromByteBufferUnsafe_directBuffer_createsCopy() {
+        byte[] inputBytes = {'a'};
+        ByteBuffer directBuffer = ByteBuffer.allocateDirect(1);
+        directBuffer.put(inputBytes);
+        directBuffer.flip();
+
+        ResponseBytes<Object> responseBytes = ResponseBytes.fromByteBufferUnsafe(OBJECT, directBuffer);
+        ByteBuffer outputBuffer = responseBytes.asByteBuffer();
+        byte[] outputBytes = responseBytes.asByteArrayUnsafe();
+
+        assertThat(directBuffer.hasArray()).isFalse();
+        assertThat(directBuffer.isDirect()).isTrue();
+        assertThat(outputBuffer.isDirect()).isFalse();
         assertThat(outputBytes).isEqualTo(inputBytes);
+        assertThat(outputBytes).isNotSameAs(inputBytes);
+
+        inputBytes[0] = 'b';
+        assertThat(outputBytes[0]).isNotEqualTo((byte) 'b');
+    }
+
+    @Test
+    public void fromByteBufferUnsafe_bufferWithOffset_createsCopy() {
+        byte[] inputBytes = "abcdefgh".getBytes();
+
+        ByteBuffer slicedBuffer = ByteBuffer.wrap(inputBytes, 2, 3); // "cde"
+
+        ResponseBytes<Object> responseBytes = ResponseBytes.fromByteBufferUnsafe(OBJECT, slicedBuffer);
+        byte[] outputBytes = responseBytes.asByteArrayUnsafe();
+
+        assertThat(slicedBuffer.hasArray()).isTrue();
+        assertThat(outputBytes).isEqualTo("cde".getBytes());
+        assertThat(outputBytes.length).isEqualTo(3);
+        assertThat(outputBytes).isNotSameAs(inputBytes);
+
+        inputBytes[0] = 'X';
+        assertThat(outputBytes[0]).isEqualTo((byte) 'c');
     }
 }