Package software.amazon.awssdk.crt.s3

Interface S3MetaRequestResponseHandler

  • public interface S3MetaRequestResponseHandler
    Interface called by native code to provide S3MetaRequest responses.

    • Method Detail

      • onResponseHeaders

        default void onResponseHeaders​(int statusCode,
                               HttpHeader[] headers)
        Invoked to provide response headers received during the execution of the meta request. Note: the statusCode in this callback is not the final statusCode. It is possible that the statusCode in `onResponseHeaders` is 200, and then the request fail leading to a different statusCode in the final `onFinished` callback.
        Parameters:
        statusCode - statusCode of the HTTP response
        headers - the headers received

      • onResponseBody

        default int onResponseBody​(ByteBuffer bodyBytesIn,
                           long objectRangeStart,
                           long objectRangeEnd)
        Invoked to provide the response body as it is received.

        Note that if the client was created with S3ClientOptions.withReadBackpressureEnabled(boolean) set true, you must maintain the flow-control window. The flow-control window shrinks as you receive body data via this callback. Whenever the flow-control window reaches zero, data will stop downloading. To keep data flowing, you must increment the window by returning a number from this method, or by calling S3MetaRequest.incrementReadWindow(long).

        If backpressure is disabled, you do not need to maintain the flow-control window, data will arrive as fast as possible.
        Parameters:
        bodyBytesIn - The body data for this chunk of the object
        objectRangeStart - The byte index of the object that this refers to. For example, for an HTTP message that has a range header, the first chunk received will have a range_start that matches the range header's range-start
        objectRangeEnd - corresponds to the past-of-end chunk offset, i.e. objectRangeStart + the chunk length
        Returns:
        The number of bytes to increment the flow-control window by (calling S3MetaRequest.incrementReadWindow(long) has the same effect). This value is ignored if backpressure is disabled.
        See Also:
        S3ClientOptions.withReadBackpressureEnabled(boolean)

      • onFinished

        default void onFinished​(S3FinishedResponseContext context)
        Invoked when the entire meta request execution is complete.
        Parameters:
        context - a wrapper object containing the following fields

      • onProgress

        default void onProgress​(S3MetaRequestProgress progress)
        Invoked to report progress of the meta request execution. The meaning of "progress" depends on the S3MetaRequestOptions.MetaRequestType. For PUT_OBJECT, it refers to bytes uploaded. For COPY_OBJECT, it refers to bytes copied. For GET_OBJECT, it refers to bytes downloaded. For anything else, it refers to response body bytes received.
        Parameters:
        progress - information about the progress of the meta request execution

      • onTelemetry

        default void onTelemetry​(S3RequestMetrics requestMetrics)
        Invoked to report telemetry of every request made to S3. Each meta request may or may not be split into multiple requests for faster execution. However, when it is split, each request is considered as an independent ranged_get/upload_part and receives its own set of metrics with details irrespective of success or failure. More details on the specific metrics collected is provided on S3RequestMetrics
        Parameters:
        requestMetrics - telemetry data for an individual http request attempt within the meta request

      • onErrorResumeToken

        default void onErrorResumeToken​(int errorCode,
                                ResumeToken resumeToken)
        Invoked with a resume token when the meta request fails unexpectedly. Allows persisting state for later resume without re-transferring completed parts. Supported for both upload (PUT) and download (GET) meta requests. Always invoked exactly once on unexpected failure; not invoked on success or explicit pause (use S3MetaRequest.pauseAsync() for that). The token is null when no resumable state was captured.

        WARNING: for a file download with S3MetaRequestOptions.withResponseFileDeleteOnFailure(boolean) set true, the deletion is respected — the partial file is deleted on error, leaving nothing to resume on, and this callback fires with a null token. Do not set responseFileDeleteOnFailure if you intend to resume from this callback's token.

        Parameters:
        errorCode - the CRT error code that caused the meta request to fail
        resumeToken - resumable state captured at failure time, null if no resumable state was captured