Skip to content

Commit ff6d5d1

Browse files
blakeli0blakeli0
committed
feat(gax): add ResumableUploadCallable and ResumableUploadCallSettings
Add ResumableUploadCallSettings with chunkSize and mergeWith 3-tier precedence logic. Add ResumableUploadCallable abstract base class with single futureCall method.
1 parent 49be37a commit ff6d5d1

3 files changed

Lines changed: 266 additions & 0 deletions

File tree

‎sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/ResumableUploadCallSettings.java‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.rpc;
31+
32+
import com.google.api.core.BetaApi;
33+
import javax.annotation.Nullable;
34+
35+
/**
36+
* A settings class to configure a {@link ResumableUploadCallable} for executing resumable
37+
* uploads. Encapsulates protocol options such as payload chunk size.
38+
*
39+
* @param <RequestT> request type
40+
* @param <ResponseT> response type
41+
*/
42+
@BetaApi
43+
public final class ResumableUploadCallSettings<RequestT, ResponseT> {
44+
private static final int DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
45+
46+
@Nullable private final Integer chunkSize;
47+
48+
private ResumableUploadCallSettings(Builder<RequestT, ResponseT> builder) {
49+
this.chunkSize = builder.chunkSize;
50+
}
51+
52+
/** Returns the configured chunk size in bytes, or {@code null} if unconfigured. */
53+
@Nullable
54+
public Integer getChunkSize() {
55+
return chunkSize;
56+
}
57+
58+
/** Returns the configured chunk size, or the GAX default (8 MB / 8,388,608 bytes). */
59+
public int getChunkSizeOrDefault() {
60+
return chunkSize != null ? chunkSize : DEFAULT_CHUNK_SIZE;
61+
}
62+
63+
/**
64+
* Merges another {@code ResumableUploadCallSettings} instance with this one.
65+
* Fields set in {@code perRequestSettings} override fields in this instance.
66+
*
67+
* @param perRequestSettings settings to overlay; may be {@code null}
68+
* @return a new, resolved {@code ResumableUploadCallSettings} instance
69+
*/
70+
public ResumableUploadCallSettings<RequestT, ResponseT> mergeWith(
71+
ResumableUploadCallSettings<RequestT, ResponseT> perRequestSettings) {
72+
if (perRequestSettings == null) {
73+
return this;
74+
}
75+
Builder<RequestT, ResponseT> builder = toBuilder();
76+
if (perRequestSettings.getChunkSize() != null) {
77+
builder.setChunkSize(perRequestSettings.getChunkSize());
78+
}
79+
return builder.build();
80+
}
81+
82+
public Builder<RequestT, ResponseT> toBuilder() {
83+
return new Builder<>(this);
84+
}
85+
86+
public static <RequestT, ResponseT> Builder<RequestT, ResponseT> newBuilder() {
87+
return new Builder<>();
88+
}
89+
90+
/** Builder for {@link ResumableUploadCallSettings}. */
91+
public static class Builder<RequestT, ResponseT> {
92+
private Integer chunkSize;
93+
94+
private Builder() {}
95+
96+
private Builder(ResumableUploadCallSettings<RequestT, ResponseT> settings) {
97+
this.chunkSize = settings.chunkSize;
98+
}
99+
100+
public Builder<RequestT, ResponseT> setChunkSize(Integer chunkSize) {
101+
this.chunkSize = chunkSize;
102+
return this;
103+
}
104+
105+
@Nullable
106+
public Integer getChunkSize() {
107+
return chunkSize;
108+
}
109+
110+
public ResumableUploadCallSettings<RequestT, ResponseT> build() {
111+
return new ResumableUploadCallSettings<>(this);
112+
}
113+
}
114+
}

‎sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/ResumableUploadCallable.java‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.rpc;
31+
32+
import com.google.api.core.ApiFuture;
33+
import com.google.api.core.BetaApi;
34+
import java.io.InputStream;
35+
36+
/**
37+
* A ResumableUploadCallable is an API-transport-independent wrapper for the Resumable Upload
38+
* protocol. Operates directly on the request object and input stream payload.
39+
*
40+
* @param <RequestT> request type
41+
* @param <ResponseT> response type
42+
*/
43+
@BetaApi
44+
public abstract class ResumableUploadCallable<RequestT, ResponseT> {
45+
46+
protected ResumableUploadCallable() {}
47+
48+
/**
49+
* Performs the resumable upload asynchronously with custom per-request settings.
50+
*
51+
* @param request the request message
52+
* @param payload the data payload input stream
53+
* @param perRequestSettings request-level call settings overrides; may be {@code null}
54+
* @return future for the response
55+
*/
56+
public abstract ApiFuture<ResponseT> futureCall(
57+
RequestT request,
58+
InputStream payload,
59+
ResumableUploadCallSettings<RequestT, ResponseT> perRequestSettings);
60+
}

‎sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/rpc/ResumableUploadCallSettingsTest.java‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.rpc;
31+
32+
import static org.junit.Assert.assertEquals;
33+
import static org.junit.Assert.assertNull;
34+
import static org.junit.Assert.assertSame;
35+
36+
import org.junit.Test;
37+
import org.junit.runner.RunWith;
38+
import org.junit.runners.JUnit4;
39+
40+
@RunWith(JUnit4.class)
41+
public class ResumableUploadCallSettingsTest {
42+
43+
@Test
44+
public void testDefaultChunkSize() {
45+
ResumableUploadCallSettings<String, String> settings =
46+
ResumableUploadCallSettings.<String, String>newBuilder().build();
47+
48+
assertNull(settings.getChunkSize());
49+
assertEquals(8 * 1024 * 1024, settings.getChunkSizeOrDefault());
50+
}
51+
52+
@Test
53+
public void testCustomInitialization() {
54+
ResumableUploadCallSettings<String, String> settings =
55+
ResumableUploadCallSettings.<String, String>newBuilder()
56+
.setChunkSize(16 * 1024 * 1024)
57+
.build();
58+
59+
assertEquals(Integer.valueOf(16 * 1024 * 1024), settings.getChunkSize());
60+
assertEquals(16 * 1024 * 1024, settings.getChunkSizeOrDefault());
61+
}
62+
63+
@Test
64+
public void testMergeWith_NullPerRequestSettings() {
65+
ResumableUploadCallSettings<String, String> stubSettings =
66+
ResumableUploadCallSettings.<String, String>newBuilder()
67+
.setChunkSize(4 * 1024 * 1024)
68+
.build();
69+
70+
ResumableUploadCallSettings<String, String> merged = stubSettings.mergeWith(null);
71+
72+
assertSame(stubSettings, merged);
73+
}
74+
75+
@Test
76+
public void testMergeWith_PerRequestOverrides() {
77+
ResumableUploadCallSettings<String, String> stubSettings =
78+
ResumableUploadCallSettings.<String, String>newBuilder()
79+
.setChunkSize(4 * 1024 * 1024)
80+
.build();
81+
82+
ResumableUploadCallSettings<String, String> perRequestSettings =
83+
ResumableUploadCallSettings.<String, String>newBuilder()
84+
.setChunkSize(32 * 1024 * 1024)
85+
.build();
86+
87+
ResumableUploadCallSettings<String, String> merged = stubSettings.mergeWith(perRequestSettings);
88+
89+
// Chunk size overridden by Tier-1 per-request settings
90+
assertEquals(Integer.valueOf(32 * 1024 * 1024), merged.getChunkSize());
91+
}
92+
}

0 commit comments

Comments
 (0)