refactor(api): Improve clarity of transaction options in ClientWriteOptions

[curfew-marathon]

The Problem

The current public API for configuring transaction behavior in ClientWriteOptions is counter-intuitive and can lead to developer confusion.

Confusing Boolean Setter: The method disableTransactions(boolean) requires developers to parse a double negative when they want to enable transactions. The call options.disableTransactions(false) reads poorly and requires extra cognitive load to understand its intent (i.e., "not disabling" means "enabling").

Ambiguous Getter: The original getter disableTransactions() shares the same name as the new action-based setter, creating ambiguity. Standard Java conventions prefer isPropertyName() for boolean getters (e.g., isTransactionsDisabled()).

Poor Discoverability: The API doesn't make the two distinct transaction modes (atomic vs. individual) immediately obvious.

These issues hurt the overall developer experience and make the API less ergonomic than it could be.

Proposed Solution

To improve clarity and align with modern API design principles, we should refactor the transaction-related methods in ClientWriteOptions. The underlying private boolean disableTransactions primitive will be retained for internal state, but the public interface will be changed.

The implementation in the provided POC is the correct path forward:

Deprecate Ambiguous Methods:

@deprecated public ClientWriteOptions disableTransactions(boolean disableTransactions)

@deprecated public boolean disableTransactions()

Introduce Explicit Action Methods: Add two new methods that clearly state their intent without requiring a boolean parameter.

public ClientWriteOptions enableTransactions(): Sets the internal state to be transactional (default).

public ClientWriteOptions disableTransactions(): Sets the internal state to be non-transactional.

Introduce Unambiguous Getters: Add new getters that follow standard Java conventions and have clear, positive names.

public boolean isTransactionModeEnabled(): Returns true if writes are atomic.

public boolean isTransactionModeDisabled(): Returns true if writes are processed individually.

Update JavaDoc: Ensure all new and existing methods have comprehensive JavaDoc explaining the behavior, defaults, and usage, as demonstrated in the POC.

[joonseolee]

I agree with you, but do you think it’s okay if I take this on?