From a4540c64b07d7a992c18ee61c839b58c902c2dcd Mon Sep 17 00:00:00 2001 From: curfew-marathon Date: Sun, 28 Jun 2026 14:39:40 -0400 Subject: [PATCH 1/4] fix: deprecate disableTransactions in favour of transactions and isTransactionsEnabled --- .../api/configuration/ClientWriteOptions.java | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java index 67093c68..e0b97b02 100644 --- a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java +++ b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java @@ -31,11 +31,57 @@ public String getAuthorizationModelId() { return authorizationModelId; } + /** + * Sets whether transactions should be used when writing tuples. + * + *

When {@code true}, writes are sent as a single transactional request. When {@code false}, + * writes are split into chunks and sent as individual non-transactional requests, with chunk + * size controlled by {@link #transactionChunkSize(int)}. + * + * @param enabled {@code true} to enable transactions (default), {@code false} to disable them + * @return this {@code ClientWriteOptions} instance for method chaining + * @see #isTransactionsEnabled() + */ + public ClientWriteOptions transactions(boolean enabled) { + this.disableTransactions = !enabled; + return this; + } + + /** + * Returns whether transactions are enabled for write operations. + * + * @return {@code true} if transactions are enabled (default), {@code false} if disabled + * @see #transactions(boolean) + */ + public boolean isTransactionsEnabled() { + return disableTransactions == null || !disableTransactions; + } + + /** + * Sets whether transactions should be disabled when writing tuples. + * + * @param disableTransactions {@code true} to disable transactions, {@code false} to enable them + * @return this {@code ClientWriteOptions} instance for method chaining + * @deprecated Use {@link #transactions(boolean)} instead. This method will be removed in a + * future release. Replace {@code disableTransactions(true)} with + * {@code transactions(false)}, and {@code disableTransactions(false)} with + * {@code transactions(true)}. + */ + @Deprecated public ClientWriteOptions disableTransactions(boolean disableTransactions) { this.disableTransactions = disableTransactions; return this; } + /** + * Returns whether transactions are disabled for write operations. + * + * @return {@code true} if transactions are disabled, {@code false} if enabled (default) + * @deprecated Use {@link #isTransactionsEnabled()} instead. This method will be removed in a + * future release. Note that {@code isTransactionsEnabled()} returns the inverse of + * this method. + */ + @Deprecated public boolean disableTransactions() { return disableTransactions != null && disableTransactions; } From 3306f75d28aa4baa5938421415f789c08e82a931 Mon Sep 17 00:00:00 2001 From: curfew-marathon Date: Sun, 28 Jun 2026 14:44:31 -0400 Subject: [PATCH 2/4] fix: use boolean primitive, rename internal field, add full Javadoc --- .../api/configuration/ClientWriteOptions.java | 76 +++++++++++++++++-- 1 file changed, 71 insertions(+), 5 deletions(-) diff --git a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java index e0b97b02..6231bc32 100644 --- a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java +++ b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java @@ -4,14 +4,26 @@ import dev.openfga.sdk.api.model.WriteRequestWrites; import java.util.Map; +/** + * Options for controlling the behavior of write operations on the OpenFGA client. + * + *

Use this class to configure how tuples are written, including whether to use transactions, + * how writes are chunked, and how duplicate or missing tuples are handled. + */ public class ClientWriteOptions implements AdditionalHeadersSupplier { private Map additionalHeaders; private String authorizationModelId; - private Boolean disableTransactions = false; + private boolean transactionsEnabled = true; private int transactionChunkSize; private WriteRequestWrites.OnDuplicateEnum onDuplicate; private WriteRequestDeletes.OnMissingEnum onMissing; + /** + * Sets additional HTTP headers to include in write requests. + * + * @param additionalHeaders a map of header names to values + * @return this {@code ClientWriteOptions} instance for method chaining + */ public ClientWriteOptions additionalHeaders(Map additionalHeaders) { this.additionalHeaders = additionalHeaders; return this; @@ -22,11 +34,24 @@ public Map getAdditionalHeaders() { return this.additionalHeaders; } + /** + * Sets the authorization model ID to use for write operations. + * + *

If not set, the client will use the authorization model ID from its configuration. + * + * @param authorizationModelId the authorization model ID + * @return this {@code ClientWriteOptions} instance for method chaining + */ public ClientWriteOptions authorizationModelId(String authorizationModelId) { this.authorizationModelId = authorizationModelId; return this; } + /** + * Returns the authorization model ID configured for write operations. + * + * @return the authorization model ID, or {@code null} if not set + */ public String getAuthorizationModelId() { return authorizationModelId; } @@ -43,7 +68,7 @@ public String getAuthorizationModelId() { * @see #isTransactionsEnabled() */ public ClientWriteOptions transactions(boolean enabled) { - this.disableTransactions = !enabled; + this.transactionsEnabled = enabled; return this; } @@ -54,7 +79,7 @@ public ClientWriteOptions transactions(boolean enabled) { * @see #transactions(boolean) */ public boolean isTransactionsEnabled() { - return disableTransactions == null || !disableTransactions; + return transactionsEnabled; } /** @@ -69,7 +94,7 @@ public boolean isTransactionsEnabled() { */ @Deprecated public ClientWriteOptions disableTransactions(boolean disableTransactions) { - this.disableTransactions = disableTransactions; + this.transactionsEnabled = !disableTransactions; return this; } @@ -83,32 +108,73 @@ public ClientWriteOptions disableTransactions(boolean disableTransactions) { */ @Deprecated public boolean disableTransactions() { - return disableTransactions != null && disableTransactions; + return !transactionsEnabled; } + /** + * Sets the number of tuples to include in each non-transactional write chunk. + * + *

Only applies when transactions are disabled via {@link #transactions(boolean)}. Writes + * and deletes are split into chunks of this size and sent as separate requests. + * + * @param transactionChunkSize the chunk size; must be greater than zero + * @return this {@code ClientWriteOptions} instance for method chaining + * @see #transactions(boolean) + */ public ClientWriteOptions transactionChunkSize(int transactionChunkSize) { this.transactionChunkSize = transactionChunkSize; return this; } + /** + * Returns the chunk size for non-transactional writes. + * + *

Defaults to {@code 1} if not explicitly set. + * + * @return the configured chunk size, or {@code 1} if none was set + */ public int getTransactionChunkSize() { return transactionChunkSize > 0 ? transactionChunkSize : 1; } + /** + * Sets the behavior when a duplicate tuple is encountered during a write. + * + * @param onDuplicate the action to take on duplicate tuples + * @return this {@code ClientWriteOptions} instance for method chaining + * @see WriteRequestWrites.OnDuplicateEnum + */ public ClientWriteOptions onDuplicate(WriteRequestWrites.OnDuplicateEnum onDuplicate) { this.onDuplicate = onDuplicate; return this; } + /** + * Returns the configured behavior for duplicate tuples during writes. + * + * @return the on-duplicate action, or {@code null} if not set + */ public WriteRequestWrites.OnDuplicateEnum getOnDuplicate() { return onDuplicate; } + /** + * Sets the behavior when a tuple to be deleted is not found. + * + * @param onMissing the action to take when a tuple is missing during delete + * @return this {@code ClientWriteOptions} instance for method chaining + * @see WriteRequestDeletes.OnMissingEnum + */ public ClientWriteOptions onMissing(WriteRequestDeletes.OnMissingEnum onMissing) { this.onMissing = onMissing; return this; } + /** + * Returns the configured behavior for missing tuples during deletes. + * + * @return the on-missing action, or {@code null} if not set + */ public WriteRequestDeletes.OnMissingEnum getOnMissing() { return onMissing; } From 0f1b2593a22b24fd0d5a12d5201afdcd1cc3aaab Mon Sep 17 00:00:00 2001 From: curfew-marathon Date: Sun, 28 Jun 2026 14:46:12 -0400 Subject: [PATCH 3/4] =?UTF-8?q?fix:=20clarify=20transactions=20Javadoc=20?= =?UTF-8?q?=E2=80=94=20chunks=20are=20atomic=20individually,=20not=20acros?= =?UTF-8?q?s=20the=20full=20set?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../openfga/sdk/api/configuration/ClientWriteOptions.java | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java index 6231bc32..04686fd9 100644 --- a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java +++ b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java @@ -59,9 +59,10 @@ public String getAuthorizationModelId() { /** * Sets whether transactions should be used when writing tuples. * - *

When {@code true}, writes are sent as a single transactional request. When {@code false}, - * writes are split into chunks and sent as individual non-transactional requests, with chunk - * size controlled by {@link #transactionChunkSize(int)}. + *

When {@code true}, all writes and deletes are sent as a single atomic request — if any + * tuple fails, the entire operation is rolled back. When {@code false}, tuples are split into + * chunks and sent as separate requests, each chunk atomic on its own but with no atomicity + * guarantee across the full set. Chunk size is controlled by {@link #transactionChunkSize(int)}. * * @param enabled {@code true} to enable transactions (default), {@code false} to disable them * @return this {@code ClientWriteOptions} instance for method chaining From 244558fd4db1a0d0b75f3bc99f7a0e04a93f8085 Mon Sep 17 00:00:00 2001 From: curfew-marathon Date: Sun, 28 Jun 2026 22:27:13 -0400 Subject: [PATCH 4/4] fix: remove deprecation from disableTransactions, keep dual paths Roll out transactions/isTransactionsEnabled alongside the existing disableTransactions methods without marking them deprecated yet. --- .../sdk/api/configuration/ClientWriteOptions.java | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java index 04686fd9..b3c7af46 100644 --- a/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java +++ b/src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java @@ -88,12 +88,7 @@ public boolean isTransactionsEnabled() { * * @param disableTransactions {@code true} to disable transactions, {@code false} to enable them * @return this {@code ClientWriteOptions} instance for method chaining - * @deprecated Use {@link #transactions(boolean)} instead. This method will be removed in a - * future release. Replace {@code disableTransactions(true)} with - * {@code transactions(false)}, and {@code disableTransactions(false)} with - * {@code transactions(true)}. */ - @Deprecated public ClientWriteOptions disableTransactions(boolean disableTransactions) { this.transactionsEnabled = !disableTransactions; return this; @@ -103,11 +98,7 @@ public ClientWriteOptions disableTransactions(boolean disableTransactions) { * Returns whether transactions are disabled for write operations. * * @return {@code true} if transactions are disabled, {@code false} if enabled (default) - * @deprecated Use {@link #isTransactionsEnabled()} instead. This method will be removed in a - * future release. Note that {@code isTransactionsEnabled()} returns the inverse of - * this method. */ - @Deprecated public boolean disableTransactions() { return !transactionsEnabled; }