Package software.amazon.awssdk.crt.s3

Interface S3BorrowedBufferDelivery

public interface S3BorrowedBufferDelivery

Opts a response handler into zero-copy delivery, where each body chunk arrives as a view into the client's direct buffer pool rather than being copied into a heap byte[]. Implement it alongside S3MetaRequestResponseHandler:

 class MyHandler implements S3MetaRequestResponseHandler, S3BorrowedBufferDelivery {
     public int onResponseBodyBorrowed(S3BorrowedBuffer buffer,
                                       long objectRangeStart, long objectRangeEnd) {
         try (S3BorrowedBuffer b = buffer) {   // MUST be closed on every path
             // read b.asByteBuffer() here
         }
         return (int) (objectRangeEnd - objectRangeStart);
     }
 }
 

A direct buffer pool on the client and this interface on the handler are both required. With only one of the two, chunks keep arriving via S3MetaRequestResponseHandler.onResponseBody(java.nio.ByteBuffer, long, long). Because the opt-in is an interface, a wrong method name or signature fails the build rather than quietly reverting to heap delivery.

See Also:

S3BorrowedBuffer, S3ClientOptions.withDirectBufferPoolOptions(software.amazon.awssdk.crt.s3.S3DirectBufferPoolOptions)

Method Summary

Modifier and Type	Method	Description
int	onResponseBodyBorrowed(S3BorrowedBuffer buffer, long objectRangeStart, long objectRangeEnd)	Invoked with one chunk of the response body, read straight from pool memory, instead of S3MetaRequestResponseHandler.onResponseBody(java.nio.ByteBuffer, long, long).

Method Detail

onResponseBodyBorrowed

int onResponseBodyBorrowed(S3BorrowedBuffer buffer,
                           long objectRangeStart,
                           long objectRangeEnd)

Invoked with one chunk of the response body, read straight from pool memory, instead of S3MetaRequestResponseHandler.onResponseBody(java.nio.ByteBuffer, long, long). Throwing from here fails the meta request.

Return promptly. The pool slot backing buffer stays leased for as long as this method runs, and then until S3BorrowedBuffer.close(). Time spent here is pool capacity withheld from every other request: a ceiling of N parts allows only N deliveries at once, so a handler that hashes, compresses, or writes to slow storage inline can stall unrelated requests, and the sizing guidance on S3ClientOptions.withDirectBufferPoolOptions(software.amazon.awssdk.crt.s3.S3DirectBufferPoolOptions) assumes it does not. Do that work after the buffer is closed, or on a copy taken with S3BorrowedBuffer.toByteArray(), which is safe to hand to another thread.

Parameters:

buffer - a borrowed view into pool memory, which MUST always be closed. See S3BorrowedBuffer for the lifetime, leak-detection and flow-control rules.

objectRangeStart - the byte index of the object this chunk starts at

objectRangeEnd - objectRangeStart + buffer.asByteBuffer().remaining()

Returns:

bytes to increment the read window by, as for S3MetaRequestResponseHandler.onResponseBody(java.nio.ByteBuffer, long, long)