Refine transaction documentation.

Author: mp911de

spring-graphql-docs/modules/ROOT/pages/data.adoc

@@ -477,252 +477,171 @@ you need to declare a `SortStrategy` bean.
 [[data.transaction-management]]
 == Transaction Management
 
-At some point when working with data then transactional boundaries start to matter.
-GraphQL itself does not define any transaction semantics, so it is up to the server
-and your application to decide how to handle transactions.
+At some point when working with data atomicity and isolation of operations start to
+matter. These are both properties of transactions. GraphQL itself does not define any
+transaction semantics, so it is up to the server and your application to decide how to
+handle transactions.
 
-Spring Data repositories use implicit transactions for individual operations resulting
-in starting and commiting a transaction for each repository method call. This is the
-normal mode of operation for most NoSQL databases but not necessarily what you
-would want for relational databases.
+GraphQL and specifically GraphQL Java are designed to be non-opinionated about how data
+is fetched. A core property of GraphQL is that clients drive the query; Fields
+can be resolved independently of their original source to allow for composition.
+A reduced fieldset can require less data to be fetched resulting in better performance.
 
-You have several options how you could manage transactions in a GraphQL server:
+Applying the concept of distributed field resolution within transactions is not a good fit:
 
-1. <<data.transaction-management.transactional-service-methods,Use transactional service methods>>
-2. <<data.transaction-management.instrumentation,Using a `Instrumentation` that manages transactions programmatically>>
-3. <<data.transaction-management.execution-strategy,Implement a custom `ExecutionStrategy` that manages transactions programmatically>>
+* Transactions keep a unit of work together resulting typically in fetching the entire
+object graph (like a typical object-relational mapper would behave) within a single
+transaction. This is at odds with GraphQL's core design to let the client drive queries.
+
+* Keeping a transaction open across multiple data fetchers of which each one would
+fetch only its flat object mitigates the performance aspect and aligns with decoupled
+field resolution, but it can lead to long-running transactions that hold on to resources
+for longer than necessary.
+
+Generally speaking, transactions are best applied to mutations that change state and not
+necessarily to queries that just read data. However, there are use cases where
+transactional reads are required.
+
+GraphQL is designed to support multiple mutations within a single query. Depending on
+the use case, you might want to:
+
+* Run each mutation within its own transaction.
+* Keep some mutations within a single transaction to ensure a consistent state.
+* Span a single transaction over all involved mutations.
+
+Each approach requires a slightly different transaction management strategy.
+
+By default, (and without any further instrumentation) Spring Data repositories use implicit
+transactions for individual operations resulting in starting and commiting a transaction
+for each repository method call. This is the normal mode of operation for most databases.
+
+The following sections are outlining two different strategies to manage transactions in a
+GraphQL server:
+
+1. <<data.transaction-management.transactional-service-methods,Transaction per Controller Method>>
+2. <<data.transaction-management.transactional-instrumentation,Spanning a Transaction programmatically over the entire request>>
 
-We generally recommend isolating transaction management in the controller or service.
-Any extended use (such as batch loading) might have their own requirements to transaction
-management and so you might want to consider the other two options.
 
 [[data.transaction-management.transactional-service-methods]]
 === Transactional Service Methods
 
-Use Spring's `@Transactional` annotation on service methods that are
-invoked from your `@QueryMapping` controller method. This is the recommended approach
-as it gives you full control over the transaction boundaries with a clearly defined
-entrypoint, for example:
+The simplest approach to manage transactions is to use Spring's Transaction Management
+together with `@MutationMapping` controller methods (or any other `@SchemaMapping` method)
+for example:
 
-[source,java,indent=0,subs="verbatim,quotes"]
+[tabs]
+======
+Declarative::
++
+[source,java,indent=0,subs="verbatim,quotes,attributes",role="primary"]
 ----
 @Controller
 public class AccountController {
 
-	@QueryMapping
+	@MutationMapping
 	@Transactional
-	public Account accountById(@Argument String id) {
-		... // fetch the entire account object within a single transaction
+	public Account addAccount(@Argument AccountInput input) {
+		// ...
 	}
 }
 ----
 
-A transaction spans from entering the `accountById` method until it returns meaning
-that the entire object must be materialized within that method. Taking GraphQL's core
-design principles into account, this is not idiomatic as it limits the ability of the
-client to drive the query and forces the server to load the entire object graph upfront.
-
-Another aspect to consider is that subsequent data fetching for nested fields is not part
-of the transactional method `accountById` as the transaction is cleaned up after leaving
-the method.
-
-[source,java,indent=0,subs="verbatim,quotes"]
+Programmatic::
++
+[source,java,indent=0,subs="verbatim,quotes,attributes",role="secondary"]
 ----
 @Controller
 public class AccountController {
 
-	@QueryMapping
-	@Transactional
-	public Account accountById(@Argument String id) {
-		... // fetch the account within a transaction
-	}
+	private final TransactionOperations transactionOperations;
 
-	@SchemaMapping
-	@Transactional
-	public Person person(Account account) {
-		... // fetching the person within a separate transaction
+	@MutationMapping
+	public Account addAccount(@Argument AccountInput input) {
+		return transactionOperations.execute(status -> {
+			// ...
+		});
 	}
 }
 ----
+======
 
-Using `@Transactional` on multiple controller methods is possible and in fact
-recommended when applying mutations. Any transactional queries that would resolve nested
-fields fall into their own transaction.
-
-You can replace Spring's `@Transactional` with `TransactionOperations` or
-`TransactionalOperator` if you wish to manage the transaction programmatically instead
-of using Spring's aspect-oriented programming (AOP) support for transactions.
-
-
-[[data.transaction-management.instrumentation]]
-=== Transactional Instrumentation
-
-GraphQL Java's `Instrumentation` contract allows you to hook into the execution lifecycle
-at various stages. The Instrumentation SPI was designed with observability in mind, yet it
-serves as execution-agnostic extension points regardless of whether you're using synchronous
-reactive, or any other asynchronous form to invoke data fetchers.
-
-Spanning an instrumentation over the entire execution creates an enclosing transaction.
-Ideally, the underlying `ExecutionStrategy` runs `DataFetcher` invocations serially so
-that all invocations are executed on the same `Thread`. This is mandatory: Synchronous
-transaction management uses `ThreadLocal` state to allow participation in transactions.
+A transaction spans from entering the `addAccount` method until it returns its return value.
+All invocations to transactional resources are part of the same transaction resulting in
+atomicity and isolation of the mutation.
 
-Another aspect of creating an outer transaction is that it spans across the entire execution.
-All `@SchemaMapping` controller methods participate in the transaction regardless whether
-they are invoked for the root, nested fields, or as part of a mutation. When participating
-in an ongoing transaction, transactional controller or service methods can declare
-transactional attributes such as propagation behavior `REQUIRES_NEW` to start
-a new transaction.
+This is the recommended approach as it gives you full control over the transaction
+boundaries with a clearly defined entrypoint without the need to instrument GraphQL
+server infrastructure.
 
-An example transactional `Instrumentation` must start a transaction before execution and
-clean up the transaction after execution completes. An example instrumentation could look
-like as follows:
+Another aspect to consider is that subsequent data fetching for nested fields is not part
+of the transactional method `addAccount` as the transaction is cleaned up after leaving
+the method as shown below:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
-class TransactionalInstrumentation implements Instrumentation {
-
-	private final Log logger = LogFactory.getLog(getClass());
-
-	private final PlatformTransactionManager txManager;
-	private final TransactionDefinition definition;
-
-	TransactionalInstrumentation(PlatformTransactionManager txManager, TransactionDefinition definition) {
-		this.transactionManager = transactionManager;
-		this.definition = definition;
-	}
+@Controller
+public class AccountController {
 
-	@Override
-	public @Nullable InstrumentationContext<ExecutionResult> beginExecution(
-			InstrumentationExecutionParameters parameters, InstrumentationState state) {
-
-		TransactionStatus status = this.transactionManager.getTransaction(definition);
-
-		return SimpleInstrumentationContext.whenCompleted((result, t) -> {
-			if (t != null) {
-				rollbackOnException(status, t);
-			} else {
-				for (GraphQLError error : result.getErrors()) {
-					if (error instanceof ExceptionWhileDataFetching e) {
-						rollbackOnException(status, e.getException());
-						return;
-					}
-				}
-				this.transactionManager.commit(status);
-			}
-		});
+	@MutationMapping
+	@Transactional
+	public Account addAccount(@Argument AccountInput input) {    <1>
+		// ...
 	}
 
-	private void rollbackOnException(TransactionStatus status, Throwable ex) throws TransactionException {
-
-		logger.debug("Initiating transaction rollback on application exception", ex);
-		try {
-			this.transactionManager.rollback(status);
-		} catch (TransactionSystemException ex2) {
-			logger.error("Application exception overridden by rollback exception", ex);
-			ex2.initApplicationException(ex);
-			throw ex2;
-		} catch (RuntimeException | Error ex2) {
-			logger.error("Application exception overridden by rollback exception", ex);
-		}
+	@SchemaMapping
+	@Transactional
+	public Person person(Account account) {                      <2>
+		... // fetching the person within a separate transaction
 	}
 }
 ----
+<1> The `addAccount` method invocation runs within its own transaction.
+<2> The `person` method invocation creates its own, separate transaction that is not
+tied to the `addAccount` method in case both methods were invoked as part of the same
+GraphQL request. A separate transaction comes with all possible drawbacks of not
+being part of the same transaction, such as non-repeatable reads or inconsistencies
+in case the data has been modified between the `addAcount` and `person` method invocations.
 
-This implementation repeats parts that reside in `TransactionTemplate` for proper
-transaction management. Another aspect to consider is that the above implementation relies
-on `ExceptionWhileDataFetching` that is only available if the underlying
-`ExecutionStrategy` uses `SimpleDataFetcherExceptionHandler`. By default, Spring GraphQL
-falls back to an internal `GraphQLError` that doesn't expose the original exception.
-
-If there is already an `Instrumentation` configured, then you need to go a step further
-and use the `ExecutionStrategy` method.
-
-[[data.transaction-management.execution-strategy]]
-=== Transactional `ExecutionStrategy`
 
-Implementing an own transactional `ExecutionStrategy` is similar to the `Instrumentation`
-approach, but it gives you more control over the execution.
-
-It can also serve as good entry point to implement custom directives that allow clients
-specifying transactional attributes through directives or using directives in your schema
-to demarcate transactional boundaries for certain queries or mutations.
-
-An `ExecutionStrategy` provides full control over the execution and opens a multitude
-of possibilities over how to communicate failed transactions or errors during transaction
-cleanup back to the client.
-
-The following block shows a rather simple example implementation without considering
-all invariants of exception handling:
-
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-static class TransactionalExecutionStrategy extends AsyncSerialExecutionStrategy {
-
-	protected final Log logger = LogFactory.getLog(getClass());
+[[data.transaction-management.transactional-instrumentation]]
+=== Transactional Instrumentation
 
-	private final PlatformTransactionManager transactionManager;
-	private final TransactionDefinition definition;
+Applying a Transactional Instrumentation is a more advanced approach to span a
+transaction over the entire execution of a GraphQL request. By stating a transaction
+before the first data fetcher is invoked your application can ensure that all data
+fetchers can participate in the same transaction.
 
-	public TransactionalExecutionStrategy(PlatformTransactionManager transactionManager,
-			TransactionDefinition definition) {
-		this.transactionManager = transactionManager;
-		this.definition = definition;
-	}
+When instrumenting the server, you need to ensure an `ExecutionStrategy` runs
+`DataFetcher` invocations serially so that all invocations are executed on the same
+`Thread`. This is mandatory: Synchronous transaction management uses `ThreadLocal` state
+to allow participation in transactions. Considering `AsyncSerialExecutionStrategy` as
+starting point is a good choice as it executes data fetchers serially.
 
-	@Override
-	public CompletableFuture<ExecutionResult> execute(ExecutionContext executionContext,
-			ExecutionStrategyParameters parameters) throws NonNullableFieldWasNullException {
-
-		TransactionStatus status = this.transactionManager.getTransaction(definition);
-		try {
-			return super.execute(executionContext, parameters).whenComplete((result, exception) -> {
-
-				if (exception != null) {
-					rollbackOnException(status, exception);
-				} else {
-
-					for (GraphQLError error : result.getErrors()) {
-						if (error instanceof ExceptionWhileDataFetching e) {
-							rollbackOnException(status, e.getException());
-							return;
-						}
-					}
-
-					this.transactionManager.commit(status);
-				}
-			});
-		} catch (RuntimeException | Error ex) {
-			// Transactional code threw application exception -> rollback
-			return CompletableFuture.failedFuture(rollbackOnException(status, ex));
-		} catch (Throwable ex) {
-			// Transactional code threw unexpected exception -> rollback
-			return CompletableFuture.failedFuture(new UndeclaredThrowableException(rollbackOnException(status, ex),
-					"TransactionCallback threw undeclared checked exception"));
-		}
-	}
+You have two general options to implement transactional instrumentation:
 
-	/**
-	 * Perform a rollback, handling rollback exceptions properly.
-	 *
-	 * @param status object representing the transaction
-	 * @param ex the thrown application exception or error
-	 */
-	private Throwable rollbackOnException(TransactionStatus status, Throwable ex) {
-
-		logger.debug("Initiating transaction rollback on application exception", ex);
-		try {
-			this.transactionManager.rollback(status);
-		} catch (TransactionSystemException ex2) {
-			logger.error("Application exception overridden by rollback exception", ex);
-			ex2.initApplicationException(ex);
-			return ex2;
-		} catch (RuntimeException | Error ex2) {
-			logger.error("Application exception overridden by rollback exception", ex);
-			return ex2;
-		}
-
-		return ex;
-	}
-}
-----
+1. GraphQL Java's `Instrumentation` contract allows to hook into the execution lifecycle
+at various stages. The Instrumentation SPI was designed with observability in mind, yet it
+serves as execution-agnostic extension points regardless of whether you're using
+synchronous reactive, or any other asynchronous form to invoke data fetchers and is less
+opinionated in that regard.
+
+2. An `ExecutionStrategy` provides full control over the execution and opens a variety
+of possibilities how to communicate failed transactions or errors during transaction
+cleanup back to the client. It can also serve as good entry point to implement custom
+directives that allow clients specifying transactional attributes through directives or
+using directives in your schema to demarcate transactional boundaries for certain queries
+or mutations.
+
+When manually managing transactions, ensure to cleanup the transaction, that is either
+commiting or rolling back, after completing the unit of work.
+`ExceptionWhileDataFetching` can be a useful `GraphQLError` to obtain an underlying
+`Exception`. This error is constructed when using `SimpleDataFetcherExceptionHandler`.
+By default, Spring GraphQL falls back to an internal `GraphQLError` that doesn't expose
+the original exception.
+
+Applying transactional instrumentation creates opportunities to rethink transaction
+participation: All `@SchemaMapping` controller methods participate in the transaction
+regardless whether they are invoked for the root, nested fields, or as part of a mutation.
+Transactional controller methods (or service methods within the invocation chain) can
+declare transactional attributes such as propagation behavior `REQUIRES_NEW` to start
+a new transaction if required.