Skip to content

Commit

Permalink
docs: add @SInCE to all new public surface
Browse files Browse the repository at this point in the history
  • Loading branch information
@BenWhitehead
BenWhitehead committed Oct 2, 2023
1 parent 632d51e commit a5327f3
Showing 1 changed file with 36 additions and 2 deletions.
38 changes: 36 additions & 2 deletions ...src/main/java/com/google/cloud/storage/ParallelCompositeUploadBlobWriteSessionConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,11 @@
import org.checkerframework.checker.nullness.qual.NonNull;

/**
* Immutable config builder for a Parallel Composite Upload todo: include note about object lock and
* retention policy todo: fix this formatting
* Immutable config builder to configure BlobWriteSession instances to perform Parallel Composite
* Uploads.
*
* <p>Parallel Composite Uploads can yield higher throughput when uploading large objects. However,
* there are some things which must be kept in mind when choosing to use this strategy.
*
* <ol>
* <li>Performing parallel composite uploads costs more money. <a
Expand All @@ -76,6 +79,9 @@
* {@link PartCleanupStrategy#never()} to {@link
* ParallelCompositeUploadBlobWriteSessionConfig#withPartCleanupStrategy(PartCleanupStrategy)}
* will prevent automatic cleanup.
* <li>Please see the <a href="https://cloud.google.com/storage/docs/parallel-composite-uploads">
* Parallel composite uploads</a> documentation for a more in depth explanation of the
* limitations of Parallel composite uploads.
* <li>A failed upload can leave part and intermediary compose objects behind which will count as
* storage usage, and you will be billed for it. <br>
* By default if an upload fails, an attempt to cleanup the part and intermediary compose will
Expand All @@ -102,6 +108,7 @@
* @see Storage#blobWriteSession(BlobInfo, BlobWriteOption...)
* @see <a
* href="https://cloud.google.com/storage/docs/parallel-composite-uploads">https://cloud.google.com/storage/docs/parallel-composite-uploads</a>
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@Immutable
@BetaApi
Expand Down Expand Up @@ -146,6 +153,8 @@ ParallelCompositeUploadBlobWriteSessionConfig withMaxPartsPerCompose(int maxPart
* composite upload.
*
* <p><i>Default: </i> {@link ExecutorSupplier#cachedPool()}
*
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public ParallelCompositeUploadBlobWriteSessionConfig withExecutorSupplier(
Expand All @@ -164,6 +173,8 @@ public ParallelCompositeUploadBlobWriteSessionConfig withExecutorSupplier(
* when performing a parallel composite upload.
*
* <p><i>Default: </i> {@link BufferStrategy#simple(int) BufferStrategy#simple(16MiB)}
*
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public ParallelCompositeUploadBlobWriteSessionConfig withBufferStrategy(
Expand All @@ -182,6 +193,8 @@ public ParallelCompositeUploadBlobWriteSessionConfig withBufferStrategy(
* compose objects will be named when performing a parallel composite upload.
*
* <p><i>Default: </i> {@link PartNamingStrategy#noPrefix()}
*
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public ParallelCompositeUploadBlobWriteSessionConfig withPartNamingStrategy(
Expand All @@ -200,6 +213,8 @@ public ParallelCompositeUploadBlobWriteSessionConfig withPartNamingStrategy(
* automatically when performing a parallel composite upload.
*
* <p><i>Default: </i> {@link PartCleanupStrategy#always()}
*
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public ParallelCompositeUploadBlobWriteSessionConfig withPartCleanupStrategy(
Expand Down Expand Up @@ -237,6 +252,7 @@ WriterFactory createFactory(Clock clock) throws IOException {
* {@link Storage}.
*
* @see #withBufferStrategy(BufferStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
@Immutable
Expand All @@ -250,6 +266,7 @@ private BufferStrategy() {}
*
* @param capacity the number of bytes each buffer should be
* @see #withBufferStrategy(BufferStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static BufferStrategy simple(int capacity) {
Expand All @@ -263,6 +280,7 @@ public static BufferStrategy simple(int capacity) {
* @param bufferCount the number of buffers the pool will be
* @param bufferCapacity the number of bytes each buffer should be
* @see #withBufferStrategy(BufferStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static BufferStrategy fixedPool(int bufferCount, int bufferCapacity) {
Expand Down Expand Up @@ -305,6 +323,7 @@ BufferHandlePool get() {
* parallel composite upload.
*
* @see #withExecutorSupplier(ExecutorSupplier)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
@Immutable
Expand All @@ -317,6 +336,7 @@ private ExecutorSupplier() {}
* Use a cached thread pool for submitting work
*
* @see #withExecutorSupplier(ExecutorSupplier)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static ExecutorSupplier cachedPool() {
Expand All @@ -334,6 +354,7 @@ Executor get() {
*
* @param poolSize the number of threads in the pool
* @see #withExecutorSupplier(ExecutorSupplier)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static ExecutorSupplier fixedPool(int poolSize) {
Expand All @@ -349,7 +370,12 @@ Executor get() {
/**
* Wrap an existing executor instance which will be used for submitting work
*
* <p><b><i>Choosing to use this supplier type will make your instance of {@link StorageOptions}
* unable to be serialized.</i></b>
*
* @param executor the executor to use
* @see #withExecutorSupplier(ExecutorSupplier)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static ExecutorSupplier useExecutor(Executor executor) {
Expand Down Expand Up @@ -384,6 +410,7 @@ Executor get() {
* object.
*
* @see #withPartNamingStrategy(PartNamingStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
@Immutable
Expand Down Expand Up @@ -424,6 +451,7 @@ String fmtName(String ultimateObjectName, PartRange partRange) {
* </code></pre>
*
* @see #withPartNamingStrategy(PartNamingStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static PartNamingStrategy noPrefix() {
Expand All @@ -447,6 +475,7 @@ public static PartNamingStrategy noPrefix() {
* Convention Guidelines</a> for more details.
*
* @see #withPartNamingStrategy(PartNamingStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static PartNamingStrategy prefix(String prefixPattern) {
Expand Down Expand Up @@ -504,6 +533,7 @@ protected String fmtFields(String randomKey, String nameDigest, String partRange
* performing a parallel composite upload.
*
* @see #withPartCleanupStrategy(PartCleanupStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
@Immutable
Expand All @@ -529,6 +559,8 @@ boolean isDeleteOnError() {
* parts already uploaded.
*
* <p><i>Default:</i> {@code true}
*
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public PartCleanupStrategy withDeleteOnError(boolean deleteOnError) {
Expand All @@ -540,6 +572,7 @@ public PartCleanupStrategy withDeleteOnError(boolean deleteOnError) {
* either on success or on error.
*
* @see #withPartCleanupStrategy(PartCleanupStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static PartCleanupStrategy always() {
Expand All @@ -551,6 +584,7 @@ public static PartCleanupStrategy always() {
* either on success or on error.
*
* @see #withPartCleanupStrategy(PartCleanupStrategy)
* @since 2.28.0 This new api is in preview and is subject to breaking changes.
*/
@BetaApi
public static PartCleanupStrategy never() {
Expand Down

0 comments on commit a5327f3

Please sign in to comment.