Deprecate split, update documentation and add changelog entries

Author: zoewangg

.changes/next-release/deprecation-AWSSDKforJavav2-6069419.json

@@ -0,0 +1,6 @@
+{
+    "type": "deprecation",
+    "category": "AWS SDK for Java v2",
+    "contributor": "",
+    "description": "Deprecate `AsyncRequestBody#split` in favor of `AsyncRequestBody#splitCloseable` that takes the same input but returns `SdkPublisher<CloseableAsyncRequestBody>`"
+}

.changes/next-release/feature-AWSSDKforJavav2-500254f.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS SDK for Java v2",
+    "contributor": "",
+    "description": "Add `AsyncRequestBody#splitCloseable` API that returns a Publisher of `ClosableAsyncRequestBody`"
+}

.changes/next-release/feature-AWSSDKforJavav2-72c5f55.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS SDK for Java v2",
+    "contributor": "",
+    "description": "Introduce CloseableAsyncRequestBody interface that extends both AsyncRequestBody and SdkAutoClosable interfaces"
+}

.changes/next-release/feature-AWSSDKforJavav2-ed2c57a.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS SDK for Java v2",
+    "contributor": "",
+    "description": "Introduce BufferedSplittableAsyncRequestBody that enables splitting into retryable sub-request bodies."
+}

core/sdk-core/src/main/java/software/amazon/awssdk/core/async/AsyncRequestBody.java

@@ -512,8 +512,9 @@ static AsyncRequestBody empty() {
      * than or equal to {@code chunkSizeInBytes}. Note that this behavior may be different if a specific implementation of this
      * interface overrides this method.
      *
-     * @see AsyncRequestBodySplitConfiguration
+     * @deprecated use {@link #splitCloseable(AsyncRequestBodySplitConfiguration)} instead.
      */
+    @Deprecated
     default SdkPublisher<AsyncRequestBody> split(AsyncRequestBodySplitConfiguration splitConfiguration) {
         Validate.notNull(splitConfiguration, "splitConfiguration");
         return SplittingPublisher.builder()
@@ -537,6 +538,10 @@ default SdkPublisher<AsyncRequestBody> split(AsyncRequestBodySplitConfiguration
      * Caller is responsible for closing {@link CloseableAsyncRequestBody} when it is ready to be disposed to release any
      * resources.
      *
+     * <p><b>Note:</b> This method is primarily intended for use by AWS SDK high-level libraries and internal components.
+     * SDK customers should typically use higher-level APIs provided by service clients rather than calling this method directly.
+     *
+     * @see #splitCloseable(Consumer)
      * @see AsyncRequestBodySplitConfiguration
      */
     default SdkPublisher<CloseableAsyncRequestBody> splitCloseable(AsyncRequestBodySplitConfiguration splitConfiguration) {
@@ -553,7 +558,9 @@ default SdkPublisher<CloseableAsyncRequestBody> splitCloseable(AsyncRequestBodyS
      * avoiding the need to create one manually via {@link AsyncRequestBodySplitConfiguration#builder()}.
      *
      * @see #split(AsyncRequestBodySplitConfiguration)
+     * @deprecated use {@link #splitCloseable(Consumer)} instead
      */
+    @Deprecated
     default SdkPublisher<AsyncRequestBody> split(Consumer<AsyncRequestBodySplitConfiguration.Builder> splitConfiguration) {
         Validate.notNull(splitConfiguration, "splitConfiguration");
         return split(AsyncRequestBodySplitConfiguration.builder().applyMutation(splitConfiguration).build());
@@ -563,7 +570,10 @@ default SdkPublisher<AsyncRequestBody> split(Consumer<AsyncRequestBodySplitConfi
      * This is a convenience method that passes an instance of the {@link AsyncRequestBodySplitConfiguration} builder,
      * avoiding the need to create one manually via {@link AsyncRequestBodySplitConfiguration#builder()}.
      *
-     * @see #splitCloseable(Consumer)
+     * <p><b>Note:</b> This method is primarily intended for use by AWS SDK high-level libraries and internal components.
+     * SDK customers should typically use higher-level APIs provided by service clients rather than calling this method directly.
+     *
+     * @see #splitCloseable(AsyncRequestBodySplitConfiguration)
      */
     default SdkPublisher<CloseableAsyncRequestBody> splitCloseable(
         Consumer<AsyncRequestBodySplitConfiguration.Builder> splitConfiguration) {

core/sdk-core/src/main/java/software/amazon/awssdk/core/async/BufferedSplittableAsyncRequestBody.java

@@ -35,18 +35,11 @@
  * subsequent retry attempts will fail since the complete data set is not available for resubscription.</p>
  *
  * <p><b>Usage Example:</b></p>
- * <pre>{@code
+ * {@snippet :
  * AsyncRequestBody originalBody = AsyncRequestBody.fromString("Hello World");
  * BufferedSplittableAsyncRequestBody retryableBody =
  *     BufferedSplittableAsyncRequestBody.create(originalBody);
- *
- * AsyncRequestBodySplitConfiguration config = AsyncRequestBodySplitConfiguration.builder()
- *     .chunkSizeInBytes(1024)
- *     .bufferSizeInBytes(2048)
- *     .build();
- *
- * SdkPublisher<ClosableAsyncRequestBody> parts = retryableBody.splitClosable(config);
- * }</pre>
+ * }
  *
  * <p><b>Performance Considerations:</b></p>
  * <p>This implementation buffers data in memory to enable retries, but memory usage is controlled by