Skip to content

Commit d7e2be2

Browse files
whoweswhowes
authored
feat(gax): add ResumableUploadClient.startUpload() and supporting types (#14138)
HTTP/JSON client implementation for startUpload is in #14139.
1 parent 865a15b commit d7e2be2

3 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/ResumableUploadClient.java‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
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.resumable;
31+
32+
import com.google.api.core.InternalApi;
33+
import com.google.api.gax.rpc.UnaryCallable;
34+
import org.jspecify.annotations.NullMarked;
35+
36+
/**
37+
* Client interface for executing low-level resumable upload operations.
38+
*
39+
* @param <RequestT> request type for starting an upload
40+
* @param <ResponseT> response type of the upload operation
41+
*/
42+
@NullMarked
43+
@InternalApi
44+
public interface ResumableUploadClient<RequestT, ResponseT> {
45+
46+
/** Returns a {@link UnaryCallable} to initiate a resumable upload session. */
47+
UnaryCallable<RequestT, ResumableUploadSession> startUploadCallable();
48+
}

‎sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/ResumableUploadSession.java‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
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.resumable;
31+
32+
import com.google.api.core.InternalApi;
33+
import com.google.auto.value.AutoValue;
34+
import org.jspecify.annotations.NullMarked;
35+
36+
/** Represents the session metadata returned after starting a resumable upload. */
37+
@NullMarked
38+
@InternalApi
39+
@AutoValue
40+
public abstract class ResumableUploadSession {
41+
42+
private static final long DEFAULT_CHUNK_GRANULARITY = 1L;
43+
44+
/** Returns the server-provided URL to which data uploads are directed. */
45+
public abstract String getUploadUrl();
46+
47+
/**
48+
* Returns the server-mandated chunk granularity in bytes.
49+
*
50+
* <p>When specified by the server (via {@code X-Goog-Upload-Chunk-Granularity}), intermediate
51+
* upload chunks must have a size and offset that are an exact multiple of this value (the final
52+
* chunk may be smaller). If not specified by the server, this defaults to 1 byte, indicating no
53+
* alignment or granularity requirements apply.
54+
*
55+
* @return the chunk granularity in bytes
56+
*/
57+
public abstract long getChunkGranularity();
58+
59+
public abstract Builder toBuilder();
60+
61+
public static Builder newBuilder() {
62+
return new AutoValue_ResumableUploadSession.Builder()
63+
.setChunkGranularity(DEFAULT_CHUNK_GRANULARITY);
64+
}
65+
66+
@AutoValue.Builder
67+
public abstract static class Builder {
68+
public abstract Builder setUploadUrl(String uploadUrl);
69+
70+
public abstract Builder setChunkGranularity(long chunkGranularity);
71+
72+
public abstract ResumableUploadSession build();
73+
}
74+
}

‎sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/resumable/ResumableUploadSessionTest.java‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
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.resumable;
31+
32+
import static com.google.common.truth.Truth.assertThat;
33+
34+
import org.junit.jupiter.api.Test;
35+
36+
class ResumableUploadSessionTest {
37+
38+
private static final String UPLOAD_URL = "https://storage.googleapis.com/upload/session/12345";
39+
40+
@Test
41+
void build_withUploadUrl_setsDefaultChunkGranularity() {
42+
ResumableUploadSession session =
43+
ResumableUploadSession.newBuilder().setUploadUrl(UPLOAD_URL).build();
44+
45+
assertThat(session.getUploadUrl()).isEqualTo(UPLOAD_URL);
46+
assertThat(session.getChunkGranularity()).isEqualTo(1L);
47+
}
48+
49+
@Test
50+
void build_withExplicitChunkGranularity_preservesGranularity() {
51+
long customChunkGranularity = 256 * 1024L;
52+
53+
ResumableUploadSession session =
54+
ResumableUploadSession.newBuilder()
55+
.setUploadUrl(UPLOAD_URL)
56+
.setChunkGranularity(customChunkGranularity)
57+
.build();
58+
59+
assertThat(session.getUploadUrl()).isEqualTo(UPLOAD_URL);
60+
assertThat(session.getChunkGranularity()).isEqualTo(customChunkGranularity);
61+
}
62+
}

0 commit comments

Comments
 (0)