1 /**
2  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3  * SPDX-License-Identifier: Apache-2.0.
4  */
5 package software.amazon.awssdk.crt.s3;
6 
7 import java.nio.ByteBuffer;
8 import software.amazon.awssdk.crt.http.HttpHeader;
9 
10 /**
11  * Interface called by native code to provide S3MetaRequest responses.
12  */
13 public interface S3MetaRequestResponseHandler {
14 
15     /**
16      * Invoked to provide response headers received during the execution of the meta request.
17      * Note: the statusCode in this callback is not the final statusCode. It is possible that the statusCode in `onResponseHeaders`
18      * is 200, and then the request fail leading to a different statusCode in the final `onFinished` callback.
19      *
20      * @param statusCode statusCode of the HTTP response
21      * @param headers the headers received
22      */
onResponseHeaders(final int statusCode, final HttpHeader[] headers)23     default void onResponseHeaders(final int statusCode, final HttpHeader[] headers) {
24     }
25 
26     /**
27      * Invoked to provide the response body as it is received.
28      * <p>
29      * Note that if the client was created with {@link S3ClientOptions#withReadBackpressureEnabled} set true,
30      * you must maintain the flow-control window.
31      * The flow-control window shrinks as you receive body data via this callback.
32      * Whenever the flow-control window reaches zero, data will stop downloading.
33      * To keep data flowing, you must increment the window by returning a number
34      * from this method, or by calling {@link S3MetaRequest#incrementReadWindow}.
35      * </p>
36      * If backpressure is disabled, you do not need to maintain the flow-control window,
37      * data will arrive as fast as possible.
38      *
39      * @param bodyBytesIn The body data for this chunk of the object
40      * @param objectRangeStart The byte index of the object that this refers to. For example, for an HTTP message that
41      *  has a range header, the first chunk received will have a range_start that matches the range header's range-start
42      * @param objectRangeEnd corresponds to the past-of-end chunk offset, i.e. objectRangeStart + the chunk length
43      * @return The number of bytes to increment the flow-control window by
44      * (calling {@link S3MetaRequest#incrementReadWindow} has the same effect).
45      * This value is ignored if backpressure is disabled.
46      *
47      * @see S3ClientOptions#withReadBackpressureEnabled
48      */
onResponseBody(ByteBuffer bodyBytesIn, long objectRangeStart, long objectRangeEnd)49     default int onResponseBody(ByteBuffer bodyBytesIn, long objectRangeStart, long objectRangeEnd) {
50         return 0;
51     }
52 
53     /**
54      * Invoked when the entire meta request execution is complete.
55      * @param context a wrapper object containing the following fields
56      */
onFinished(S3FinishedResponseContext context)57     default void onFinished(S3FinishedResponseContext context) {
58     }
59 
60     /**
61      * Invoked to report progress of the meta request execution.
62      * The meaning of "progress" depends on the {@link S3MetaRequestOptions.MetaRequestType}.
63      * For PUT_OBJECT, it refers to bytes uploaded.
64      * For COPY_OBJECT, it refers to bytes copied.
65      * For GET_OBJECT, it refers to bytes downloaded.
66      * For anything else, it refers to response body bytes received.
67      * @param progress information about the progress of the meta request execution
68      */
onProgress(final S3MetaRequestProgress progress)69     default void onProgress(final S3MetaRequestProgress progress) {
70     }
71 }
72