Skip to content

Commit d6044a1

Browse files
BenWhiteheadBenWhitehead
committed
chore: add javadocs for new BlobReadSession surface
1 parent eebc6c6 commit d6044a1

12 files changed

Lines changed: 512 additions & 10 deletions

‎google-cloud-storage/src/main/java/com/google/cloud/storage/BlobReadSession.java‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,22 +18,57 @@
1818

1919
import com.google.api.core.BetaApi;
2020
import com.google.api.core.InternalExtensionOnly;
21+
import com.google.cloud.storage.Storage.BlobSourceOption;
2122
import com.google.cloud.storage.TransportCompatibility.Transport;
2223
import java.io.Closeable;
2324
import java.io.IOException;
2425

26+
/**
27+
* A session for reading bytes from a Blob
28+
*
29+
* @see Storage#blobReadSession(BlobId, BlobSourceOption...)
30+
* @see ReadProjectionConfigs
31+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
32+
*/
2533
@BetaApi
2634
@InternalExtensionOnly
2735
@TransportCompatibility({Transport.GRPC})
2836
public interface BlobReadSession extends AutoCloseable, Closeable {
2937

38+
/**
39+
* The resolved metadata for the object being read
40+
*
41+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
42+
*/
3043
@BetaApi
44+
@TransportCompatibility({Transport.GRPC})
3145
BlobInfo getBlobInfo();
3246

47+
/**
48+
* Read from this session as a specific {@code Projection} as dictated by the provided {@code
49+
* config}
50+
*
51+
* @see ReadProjectionConfig
52+
* @see ReadProjectionConfigs
53+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
54+
*/
3355
@BetaApi
56+
@TransportCompatibility({Transport.GRPC})
3457
<Projection> Projection readAs(ReadProjectionConfig<Projection> config);
3558

59+
/**
60+
* Close this session and any {@code Projection}s produced by {@link
61+
* #readAs(ReadProjectionConfig)}.
62+
*
63+
* <p>If a projection is not fully consumed/resolved it will be transitioned to a failed state.
64+
*
65+
* <p>This method MUST be closed to ensure cleanup of any inflight buffers, and to avoid a memory
66+
* leak.
67+
*
68+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
69+
*/
3670
@Override
3771
@BetaApi
72+
@TransportCompatibility({Transport.GRPC})
3873
void close() throws IOException;
3974
}

‎google-cloud-storage/src/main/java/com/google/cloud/storage/LinearExponentialRangeSpecFunction.java‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,14 @@
2626
import java.util.OptionalLong;
2727
import javax.annotation.concurrent.Immutable;
2828

29+
/**
30+
* Produce a new {@link RangeSpec} relative to the provided {@code offset} and {@code prev}. Scaling
31+
* up the maxLength if a sequential match.
32+
*
33+
* <p>Instances of this class are immutable and thread safe.
34+
*
35+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
36+
*/
2937
@BetaApi
3038
@Immutable
3139
public final class LinearExponentialRangeSpecFunction extends RangeSpecFunction {
@@ -40,24 +48,75 @@ private LinearExponentialRangeSpecFunction(long initialMaxLength, double maxLeng
4048
this.maxLengthScalar = maxLengthScalar;
4149
}
4250

51+
/**
52+
* Initial maxLength a {@link RangeSpec}s maxLength should be set to if no previous maxLength is
53+
* specified, or if the provided offset is not a sequential match.
54+
*
55+
* <p><i>Default:</i> {@code 2097152 (2 MiB)}
56+
*
57+
* @see #withInitialMaxLength(long)
58+
* @see RangeSpec#maxLength()
59+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
60+
*/
4361
public long getInitialMaxLength() {
4462
return initialMaxLength;
4563
}
4664

65+
/**
66+
* Return an instance with the {@code initialMaxLength} set to the specified value.
67+
*
68+
* <p><i>Default:</i> {@code 2097152 (2 MiB)}
69+
*
70+
* @param initialMaxLength The number of bytes a {@link RangeSpec}s maxLength should be set to if
71+
* no previous maxLength is specified, or if the provided offset is not a sequential match.
72+
* Must be &gt; {@code 0}.
73+
* @see #getInitialMaxLength()
74+
* @see RangeSpec#maxLength()
75+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
76+
*/
4777
public LinearExponentialRangeSpecFunction withInitialMaxLength(long initialMaxLength) {
4878
checkArgument(initialMaxLength > 0, "initialMaxLength > 0 (%s > 0)", initialMaxLength);
4979
return new LinearExponentialRangeSpecFunction(initialMaxLength, maxLengthScalar);
5080
}
5181

82+
/**
83+
* The scalar value used to scale the max length of a {@link RangeSpec} when the provided offset
84+
* is a sequential match.
85+
*
86+
* <p><i>Default:</i> {@code 4.0}
87+
*
88+
* @see #withMaxLengthScalar(double)
89+
* @see RangeSpec#maxLength()
90+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
91+
*/
5292
public double getMaxLengthScalar() {
5393
return maxLengthScalar;
5494
}
5595

96+
/**
97+
* Return an instance with the {@code maxLengthScalar} set to the specified value.
98+
*
99+
* <p><i>Default:</i> {@code 4.0}
100+
*
101+
* @param maxLengthScalar The scalar to apply to the max length of a previous {@link RangeSpec}
102+
* when the provided offset is a sequential match. Must be $gt;= {@code 1.0}.
103+
* @see #getMaxLengthScalar()
104+
* @see RangeSpec#maxLength()
105+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
106+
*/
56107
public LinearExponentialRangeSpecFunction withMaxLengthScalar(double maxLengthScalar) {
57108
checkArgument(maxLengthScalar >= 1.0, "maxLengthScalar >= 1.0 (%s >= 1.0)", maxLengthScalar);
58109
return new LinearExponentialRangeSpecFunction(initialMaxLength, maxLengthScalar);
59110
}
60111

112+
/**
113+
* Produce a new {@link RangeSpec} relative to the provided {@code offset} and {@code prev}.
114+
*
115+
* <p>If {@code prev} is null, a {@code RangeSpec} beginning at {@code offset} and maxLength set
116+
* to {@link #getInitialMaxLength()}. If {@code offset == (prev.begin + prev.maxLength)} create a
117+
* new {@code RangeSpec} beginning at {@code offset} and maxLength set to {@code prev.maxLength *
118+
* maxLengthScalar}
119+
*/
61120
@Override
62121
public RangeSpec apply(long offset, RangeSpec prev) {
63122
if (prev == null) {

‎google-cloud-storage/src/main/java/com/google/cloud/storage/MaxLengthRangeSpecFunction.java‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,20 @@
2121
import com.google.api.core.BetaApi;
2222
import com.google.common.base.MoreObjects;
2323
import java.util.Objects;
24+
import javax.annotation.concurrent.Immutable;
2425
import org.checkerframework.checker.nullness.qual.Nullable;
2526

27+
/**
28+
* Produce a new {@link RangeSpec} relative to the provided {@code offset} and {@code prev}, where
29+
* the RangeSpec will have a maxLength set to the lesser of {@code prev.maxLength} and {@code
30+
* this.maxLength}.
31+
*
32+
* <p>Instances of this class are immutable and thread safe.
33+
*
34+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
35+
*/
2636
@BetaApi
37+
@Immutable
2738
public final class MaxLengthRangeSpecFunction extends RangeSpecFunction {
2839
static final MaxLengthRangeSpecFunction INSTANCE = new MaxLengthRangeSpecFunction(0);
2940
private final long maxLength;
@@ -32,21 +43,47 @@ public final class MaxLengthRangeSpecFunction extends RangeSpecFunction {
3243
this.maxLength = maxLength;
3344
}
3445

46+
/**
47+
* The maximum maxLength for any RangeSpec returned from {@link #apply(long, RangeSpec)}
48+
*
49+
* <p><i>Default:</i> {@code 0} -- no max length
50+
*
51+
* @see #withMaxLength(long)
52+
* @see RangeSpec#maxLength()
53+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
54+
*/
3555
public long getMaxLength() {
3656
return maxLength;
3757
}
3858

59+
/**
60+
* Return an instance with the {@code maxLength} set to the specified value.
61+
*
62+
* <p><i>Default:</i> {@code 0} -- no max length
63+
*
64+
* @param maxLength The number of bytes a {@link RangeSpec}s maxLength should be limited to. Must
65+
* be &gt; {@code 0}.
66+
* @see #getMaxLength()
67+
* @see RangeSpec#maxLength()
68+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
69+
*/
3970
public MaxLengthRangeSpecFunction withMaxLength(long maxLength) {
4071
checkArgument(maxLength >= 0, "maxLength >= 0 (%s >= 0)", maxLength);
4172
return new MaxLengthRangeSpecFunction(maxLength);
4273
}
4374

75+
/**
76+
* Produce a new {@link RangeSpec} relative to the provided {@code offset} and {@code prev}, where
77+
* the RangeSpec will have a maxLength set to the lesser of {@code prev.maxLength} and {@code
78+
* this.maxLength}.
79+
*/
4480
@Override
4581
public RangeSpec apply(long offset, @Nullable RangeSpec prev) {
4682
if (prev == null || !prev.maxLength().isPresent()) {
4783
return RangeSpec.of(offset, maxLength);
4884
}
4985
long limit = prev.maxLength().getAsLong();
86+
// TODO: add special handling for 0
5087
return RangeSpec.of(offset, Math.min(limit, maxLength));
5188
}
5289

‎google-cloud-storage/src/main/java/com/google/cloud/storage/RangeSpec.java‎

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,49 +25,74 @@
2525
import javax.annotation.concurrent.Immutable;
2626
import org.checkerframework.checker.nullness.qual.NonNull;
2727

28-
/** Defines a range with a begin offset and optional maximum length. */
28+
/**
29+
* Defines a range with a begin offset and optional maximum length.
30+
*
31+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
32+
*/
2933
@BetaApi
3034
@Immutable
3135
public abstract class RangeSpec {
3236
// seal this class to extension
3337
private RangeSpec() {}
3438

35-
/** The beginning of the range. */
39+
/**
40+
* The beginning of the range.
41+
*
42+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
43+
*/
3644
@BetaApi
3745
public abstract long begin();
3846

3947
/**
4048
* The max length of the range if defined.
4149
*
4250
* @see RangeSpecWithMaxLength
51+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
4352
*/
4453
@BetaApi
4554
public abstract OptionalLong maxLength();
4655

4756
/**
4857
* Create a new instance of {@link RangeSpec} keeping {@code this.begin()} and with {@code
4958
* maxLength} as its new maxLength.
59+
*
60+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
5061
*/
5162
@NonNull
5263
@BetaApi
5364
public abstract RangeSpec withMaxLength(long maxLength);
5465

55-
/** {@inheritDoc} */
66+
/**
67+
* {@inheritDoc}
68+
*
69+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
70+
*/
5671
@Override
5772
public abstract boolean equals(Object o);
5873

59-
/** {@inheritDoc} */
74+
/**
75+
* {@inheritDoc}
76+
*
77+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
78+
*/
6079
@Override
6180
public abstract int hashCode();
6281

63-
/** {@inheritDoc} */
82+
/**
83+
* {@inheritDoc}
84+
*
85+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
86+
*/
6487
@Override
6588
public abstract String toString();
6689

6790
/**
6891
* Create a new RangeSpec with the provided {@code begin}.
6992
*
93+
* @param begin The beginning of the range, must be >= 0
7094
* @throws IllegalArgumentException if begin is &lt; 0
95+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
7196
*/
7297
@NonNull
7398
@BetaApi
@@ -79,7 +104,10 @@ public static RangeSpec beginAt(long begin) {
79104
/**
80105
* Create a new RangeSpec with the provided {@code begin} and {@code maxLength}.
81106
*
107+
* @param begin The beginning of the range, must be >= 0
108+
* @param maxLength The max length of the range, must be >= 0. 0 means no limit.
82109
* @throws IllegalArgumentException if begin is &lt; 0, or if maxLength is &lt; 0
110+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
83111
*/
84112
@NonNull
85113
@BetaApi
@@ -92,7 +120,11 @@ public static RangeSpec of(long begin, long maxLength) {
92120
return new RangeSpecWithMaxLength(begin, maxLength);
93121
}
94122

95-
/** A RangeSpec that represents to read from {@code 0} to {@code EOF} */
123+
/**
124+
* A RangeSpec that represents to read from {@code 0} to {@code EOF}
125+
*
126+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
127+
*/
96128
@NonNull
97129
@BetaApi
98130
public static RangeSpec all() {

‎google-cloud-storage/src/main/java/com/google/cloud/storage/RangeSpecFunction.java‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@
2626
/**
2727
* A specialized BiFunction to produce a {@link RangeSpec} given an offset and a possible previous
2828
* {@code RangeSpec}.
29+
*
30+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
2931
*/
3032
@BetaApi
3133
@Immutable
@@ -37,21 +39,49 @@ public abstract class RangeSpecFunction {
3739
/**
3840
* Given an offset to read from, and the previously read {@link RangeSpec} return a new {@code
3941
* RangeSpec} representing the range to read next.
42+
*
43+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
4044
*/
4145
@BetaApi
4246
abstract RangeSpec apply(long offset, @Nullable RangeSpec prev);
4347

48+
/**
49+
* Returns a composed function that first applies this function to its input, and then applies the
50+
* {@code then} function to the result.
51+
*
52+
* <p>Both functions will be called with the same {@code offset}.
53+
*
54+
* <p>The returned instance is equivalent to the following:
55+
*
56+
* <pre>
57+
* {@code then.apply(offset, this.apply(offset, prev))}
58+
* </pre>
59+
*
60+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
61+
*/
4462
@BetaApi
4563
public RangeSpecFunction andThen(RangeSpecFunction then) {
4664
requireNonNull(then, "then must be non null");
4765
return new AndThenRangeSpecFunction(this, then);
4866
}
4967

68+
/**
69+
* Get the default instance of {@link LinearExponentialRangeSpecFunction}.
70+
*
71+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
72+
*/
5073
@BetaApi
5174
public static LinearExponentialRangeSpecFunction linearExponential() {
5275
return LinearExponentialRangeSpecFunction.INSTANCE;
5376
}
5477

78+
/**
79+
* Produce a new {@link MaxLengthRangeSpecFunction} where the maximum possible length of any
80+
* returned {@link RangeSpec} is set to the lesser of {@code prev.maxLength} and {@code
81+
* this.maxLength}.
82+
*
83+
* @since 2.51.0 This new api is in preview and is subject to breaking changes.
84+
*/
5585
@BetaApi
5686
public static MaxLengthRangeSpecFunction maxLength(long maxLength) {
5787
return MaxLengthRangeSpecFunction.INSTANCE.withMaxLength(maxLength);

0 commit comments

Comments
 (0)