Update java doc on ContentLength in requestBody for s3 uploads (#6051)

* Java doc related to contentLength updated

* doc updated

* doc updated

* deleted unnecessary test

Author: Fred1155

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

@@ -356,6 +356,15 @@ static AsyncRequestBody fromRemainingByteBuffersUnsafe(ByteBuffer... byteBuffers
      *
      * <p>An {@link ExecutorService} is required in order to perform the blocking data reads, to prevent blocking the
      * non-blocking event loop threads owned by the SDK.
+     *
+     * @param inputStream The input stream containing the data to be sent
+     * @param contentLength The content length. If a content length smaller than the actual size of the object is set, the client
+     *                      will truncate the stream to the specified content length and only send exactly the number of bytes
+     *                      equal to the content length.
+     * @param executor The executor
+     *
+     * @return An AsyncRequestBody instance for the input stream
+     *
      */
     static AsyncRequestBody fromInputStream(InputStream inputStream, Long contentLength, ExecutorService executor) {
         return fromInputStream(b -> b.inputStream(inputStream).contentLength(contentLength).executor(executor));
@@ -386,6 +395,7 @@ static AsyncRequestBody fromInputStream(Consumer<AsyncRequestBodyFromInputStream
      *
      * <p>By default, it will time out if streaming hasn't started within 10 seconds, and use application/octet-stream as
      * content type. You can configure it via {@link BlockingInputStreamAsyncRequestBody#builder()}
+     *
      * <p><b>Example Usage</b>
      *
      * <p>
@@ -408,6 +418,10 @@ static AsyncRequestBody fromInputStream(Consumer<AsyncRequestBodyFromInputStream
      *     // Wait for the service to respond.
      *     PutObjectResponse response = responseFuture.join();
      * }
+     * @param contentLength The content length. If a content length smaller than the actual size of the object is set, the client
+     *                      will truncate the stream to the specified content length and only send exactly the number of bytes
+     *                      equal to the content length.
+     * @return The created {@code BlockingInputStreamAsyncRequestBody}.
      */
     static BlockingInputStreamAsyncRequestBody forBlockingInputStream(Long contentLength) {
         return BlockingInputStreamAsyncRequestBody.builder()
@@ -447,6 +461,11 @@ static BlockingInputStreamAsyncRequestBody forBlockingInputStream(Long contentLe
      *     PutObjectResponse response = responseFuture.join();
      * }
      * @see BlockingOutputStreamAsyncRequestBody
+     *
+     * @param contentLength The content length. If a content length smaller than the actual size of the object is set, the client
+     *                      will truncate the stream to the specified content length and only send exactly the number of bytes
+     *                      equal to the content length.
+     * @return The created {@code BlockingOutputStreamAsyncRequestBody}.
      */
     static BlockingOutputStreamAsyncRequestBody forBlockingOutputStream(Long contentLength) {
         return BlockingOutputStreamAsyncRequestBody.builder()

core/sdk-core/src/main/java/software/amazon/awssdk/core/sync/RequestBody.java

@@ -128,10 +128,11 @@ public static RequestBody fromFile(File file) {
      * To support resetting via {@link ContentStreamProvider}, this uses {@link InputStream#reset()} and uses a read limit of
      * 128 KiB. If you need more control, use {@link #fromContentProvider(ContentStreamProvider, long, String)} or
      * {@link #fromContentProvider(ContentStreamProvider, String)}.
-     * <p>
      *
      * @param inputStream   Input stream to send to the service. The stream will not be closed by the SDK.
-     * @param contentLength Content length of data in input stream.
+     * @param contentLength Content length of data in input stream. If a content length smaller than the actual size of the
+     *                      object is set, the client will truncate the stream to the specified content length and only send
+     *                      exactly the number of bytes equal to the content length.
      * @return RequestBody instance.
      */
     public static RequestBody fromInputStream(InputStream inputStream, long contentLength) {
@@ -220,9 +221,14 @@ public static RequestBody empty() {
      * S3's documentation for
      * <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_Scenario_UploadStream_section.html">alternative
      * methods</a>.
+     * <p>
+     * If a content length smaller than the actual size of the object is set, the client will truncate the stream to the
+     * specified content length and only send exactly the number of bytes equal to the content length.
      *
      * @param provider The content provider.
-     * @param contentLength The content length.
+     * @param contentLength The content length. If a content length smaller than the actual size of the object is set, the client
+     *                      will truncate the stream to the specified content length and only send exactly the number of bytes
+     *                      equal to the content length.
      * @param mimeType The MIME type of the content.
      *
      * @return The created {@code RequestBody}.