Update transactions documentation for native transaction support.

Closes #1454,#1512.

Author: mikereiche

README.adoc

@@ -179,6 +179,29 @@ Building the documentation builds also the project without running tests.
 
 The generated documentation is available from `target/site/reference/html/index.html`.
 
+=== Building and staging reference documentation for review
+
+[source,bash]
+----
+  export MY_GIT_USER=<github-user>
+  mvn generate-resources
+  docs=`pwd`/target/site/reference/html
+  pushd /tmp 
+  mkdir $$
+  cd $$
+  # see https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
+  # this examples uses a repository named "staged"
+  git clone [email protected]:${MY_GIT_USER}/staged.git -b gh-pages
+  cd staged
+  cp -R $docs/* .
+  git add .
+  git commit --message "stage for review"
+  git push origin gh-pages
+  popd
+----
+
+The generated documentation is available from `target/site/reference/html/index.html`.
+
 == Examples
 
 * https://github.com/spring-projects/spring-data-examples/[Spring Data Examples] contains example projects that explain specific features in more detail.

pom.xml

@@ -301,8 +301,20 @@
                 <artifactId>maven-assembly-plugin</artifactId>
             </plugin>
             <plugin>
+                <!-- generate asciidoc to stage for review  -->
                 <groupId>org.asciidoctor</groupId>
                 <artifactId>asciidoctor-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>target/site/reference/html</outputDirectory>
+                        </configuration>
+                    </execution>
+                </executions>
             </plugin>
             <plugin>
                 <groupId>com.mysema.maven</groupId>

src/main/asciidoc/transactions.adoc

@@ -1,114 +1,189 @@
 [[couchbase.transactions]]
-= Transaction Support
+= Couchbase Transactions
 
-Couchbase supports https://docs.couchbase.com/server/6.5/learn/data/transactions.html[Distributed Transactions]. This section documents on how to use it with Spring Data Couchbase.
+Couchbase supports https://docs.couchbase.com/server/current/learn/data/transactions.html[Distributed Transactions]. This section documents how to use it with Spring Data Couchbase.
 
 == Requirements
 
- - Couchbase Server 6.5 or above.
- - Couchbase Java client 3.0.0 or above. It is recommended to follow the transitive dependency for the transactions library from maven.
+ - Couchbase Server 6.6.1 or aabove.
+ - Spring Data Couchbase 5.0.0-M5 or above.
  - NTP should be configured so nodes of the Couchbase cluster are in sync with time. The time being out of sync will not cause incorrect behavior, but can impact metadata cleanup.
 
-== Getting Started & Configuration
-
-The `couchbase-transactions` artifact needs to be included into your `pom.xml` if maven is being used (or equivalent).
+== Overview
+The Spring Data Couchbase template operations insert, find, replace and delete and repository methods that use those calls can participate in a Couchbase Transaction. They can be executed in a transaction by using the @Transactional annotation, the CouchbaseTransactionalOperator, or in the lambda of a Couchbase Transaction.  
 
- - Group: `com.couchbase.client`
- - Artifact: `couchbase-transactions`
- - Version: latest one, i.e. `1.0.0`
+== Getting Started & Configuration
 
-Once it is included in your project, you need to create a single `Transactions` object. Conveniently, it can be part of
-your spring data couchbase `AbstractCouchbaseConfiguration` implementation:
+Couchbase Transactions are normally leveraged with a method annotated with @Transactional.
+The @Transactional operator is implemented with the CouchbaseTransactionManager which is supplied as a bean in the AbstractCouchbaseConfiguration.
+Couchbase Transactions can be used without defining a service class by using CouchbaseTransactionOperator which is also supplied as a bean in AbtractCouchbaseConfiguration.
+Couchbase Transactions can also be used directly using Spring Data Couchbase operations within a lambda https://docs.couchbase.com/server/current/learn/data/transactions.html#using-transactions[Using Transactions]
 
 .Transaction Configuration
 ====
 [source,java]
 ----
 @Configuration
+@EnableCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
+@EnableReactiveCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
+@EnableTransactionManagement <1>
 static class Config extends AbstractCouchbaseConfiguration {
 
-    // Usual Setup
-    @Override public String getConnectionString() { /* ... */ }
-    @Override public String getUserName() { /* ... */ }
-    @Override public String getPassword() { /* ... */ }
-    @Override public String getBucketName() { /* ... */ }
-
-	@Bean
-	public Transactions transactions(final Cluster couchbaseCluster) {
-		return Transactions.create(couchbaseCluster, TransactionConfigBuilder.create()
-			// The configuration can be altered here, but in most cases the defaults are fine.
-			.build());
-	}
-
+  // Usual Setup
+  @Override public String getConnectionString() { /* ... */ }
+  @Override public String getUserName() { /* ... */ }
+  @Override public String getPassword() { /* ... */ }
+  @Override public String getBucketName() { /* ... */ }
+
+  // Customization of transaction behavior is via the configureEnvironment() method
+  @Override protected void configureEnvironment(final Builder builder) {
+    builder.transactionsConfig(
+      TransactionsConfig.builder().timeout(Duration.ofSeconds(30)));
+  }
 }
 ----
 ====
 
-Once the `@Bean` is configured, you can autowire it from your service (or any other class) to make use of it. Please
-see the https://docs.couchbase.com/java-sdk/3.0/howtos/distributed-acid-transactions-from-the-sdk.html[Reference Documentation]
-on how to use the `Transactions` class. Since you need access to the current `Collection` as well, we recommend you to also
-autowire the `CouchbaseClientFactory` and access it from there:
+
+Functioning of the  @Transactional method annotation requires 
+[start=1]
+. the configuration class to be annotated with @EnableTransactionManagement;
+. the service object with the annotated methods must be annotated with @Service and @Component;
+. the service object with the annotated methods must be obtained as an @Bean either via @Autowire or
+from the application context;
+. the call to the method must be made from a different class than service because calling an annotated
+method from the same class will not invoke the Method Interceptor that does the transaction processing.
+
+== Transactions with @Transactional
+
+@Transactional defines as transactional a method or all methods on a class. 
+ 
+When this annotation is declared at the class level, it applies as a default
+to all methods of the declaring class and its subclasses.
+ 
+===  Attribute Semantics
+ 
+In this release, the Couchbase Transactions ignores the rollback attributes. 
+The transaction isoloation level is read committed;
+ 
+=== Transaction Management
+ 
+Blocking transactions are thread-bound and therefore do not propagate to newly started threads within the method.
+Non-blocking transactions are bound to the reactive context.
 
 .Transaction Access
 ====
 [source,java]
 ----
-@Autowired
-Transactions transactions;
+// this object must be provided by the Spring framework by @Autowire.
+// If created directly with its constructor, the method interceptor will not be called.
+@Autowired PersonService personService;
+
+Person walterWhite = new Person( "Walter", "White");
+Person p = personService.save(walterWhite);
+
+----------
+
+import reactor.core.publisher.Mono;
+import reactor.core.publisher.Flux;
+
+import org.springframework.stereotype.Component;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+final CouchbaseOperations personOperations;
+final ReactiveCouchbaseOperations reactivePersonOperations;
+
+@Service
+@Component
+public class PersonService {
+
+  final CouchbaseOperations operations;
+  final ReactiveCouchbaseOperations reactiveOperations;
+
+  // This method will be called for @Autowired using the 
+  // CouchbaseOperations and ReactiveCouchbaseOperations @Beans
+  public PersonService(CouchbaseOperations ops, ReactiveCouchbaseOperations reactiveOps) {
+    operations = ops;
+    reactiveOperations = reactiveOps;
+  }
+
+  @Transactional
+  public Person save(Person p) {
+    return operations.save(p);
+  }
+
+  @Transactional
+  public Person changeFirstName(String id, String newFirstName) {
+    Person p = operations.findById(Person.class).one(id);
+    return operations.replaceById(Person.class).one(p.withFirstName(newFirstName);
+  }
+
+  @Transactional
+  public Mono<Person> reactiveChangeFirstName(String id, String newFirstName) {
+    return personOperationsRx.findById(Person.class).one(person.id())
+        .flatMap(p -> personOperationsRx.replaceById(Person.class).one(p.withFirstName(newFirstName)));
+  }
 
-@Autowired
-CouchbaseClientFactory couchbaseClientFactory;
 
-public void doSomething() {
- transactions.run(ctx -> {
-  ctx.insert(couchbaseClientFactory.getDefaultCollection(), "id", "content");
-  ctx.commit();
- });
 }
 ----
 ====
 
-== Object Conversions
+== Transactions with CouchbaseTransactionalOperator
 
-Since the transactions library itself has no knowledge of your spring data entity types, you need to convert it back and
-forth when reading/writing to interact properly. Fortunately, all you need to do is autowire the `MappingCouchbaseConverter` and
-utilize it:
+CouchbaseTransactionalOperator can be used to construct a tansaction in-line without creating a service class that uses @Transactional.
+CouchbaseTransactionalOperator is available as a bean and can be instantiated with @Autowire.
+If creating one explicitly, it must be created with the following (and not TransactionalOperator.create(manager) as described in general Spring Data transaction documenation).
 
-.Transaction Conversion on Write
+.TransactionalOperator Construction
 ====
 [source,java]
 ----
-@Autowired
-MappingCouchbaseConverter mappingCouchbaseConverter;
+public static CouchbaseTransactionalOperator create(CouchbaseCallbackTransactionManager manager) 
+====
 
-public void doSomething() {
-  transactions.run(ctx -> {
+.Transaction Access Using TransactionalOperator.execute()
+====
+[source,java]
+----
+@Autowired TransactionalOperator txOperator;
+@Autowired ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
 
-   Airline airline = new Airline("demo-airline", "at");
-   CouchbaseDocument target = new CouchbaseDocument();
-   mappingCouchbaseConverter.write(airline, target);
+Person person = reactiveCouchbaseTemplate.insertById(Person.class).inCollection(cName).one(WalterWhite).block();
+Flux<Person> result = txOperator.execute((ctx) -> reactiveCouchbaseTemplate.findById(Person.class).one(person.id())
+  .flatMap(p -> reactiveCouchbaseTemplate.replaceById(Person.class).one(p.withFirstName("Walt"))));
+result.blockLast();
+----
+====
 
-   ctx.insert(couchbaseClientFactory.getDefaultCollection(), target.getId(), target.getContent());
+== Transactions Directly with the SDK
 
-   ctx.commit();
-  });
-}
-----
+Please see the https://docs.couchbase.com/java-sdk/current/howtos/distributed-acid-transactions-from-the-sdk.html[Reference Documentation]
+
+.Transaction Access - Blocking
 ====
+[source,java]
+----
+@Autowired ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
 
-The same approach can be used on read:
+TransactionResult result = reactiveCouchbaseTemplate.getCouchbaseClientFactory().getCluster().transactions().run(ctx -> {
+  return reactiveCouchbaseTemplate.insertById(Person.class).one(WalterWhite);
+});
+----
+====
 
-.Transaction Conversion on Read
+.Transaction Access - Reactive
 ====
 [source,java]
 ----
-TransactionGetResult getResult = ctx.get(couchbaseClientFactory.getDefaultCollection(), "doc-id");
+@Autowired ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
 
-CouchbaseDocument source = new CouchbaseDocument(getResult.id());
-source.setContent(getResult.contentAsObject());
-Airline read = mappingCouchbaseConverter.read(Airline.class, source);
+TransactionResult result = reactiveCouchbaseTemplate.getCouchbaseClientFactory().getCluster().reactive().transactions()
+    .run(ctx -> TransactionalSupport.checkForTransactionInThreadLocalStorage().then(Mono.defer(() -> {
+      reactiveCouchbaseTemplate.insertById(Person.class).one(WalterWhite);
+    }))).block();
 ----
 ====
 
-We are also looking into tighter integration of the transaction library into the spring data library
-ecosystem.
+

src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java

@@ -51,6 +51,7 @@
 import org.springframework.transaction.annotation.AnnotationTransactionAttributeSource;
 import org.springframework.transaction.interceptor.TransactionAttributeSource;
 import org.springframework.transaction.interceptor.TransactionInterceptor;
+import org.springframework.transaction.support.TransactionTemplate;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.StringUtils;
 
@@ -330,6 +331,16 @@ CouchbaseCallbackTransactionManager couchbaseTransactionManager(CouchbaseClientF
 		return new CouchbaseCallbackTransactionManager(clientFactory);
 	}
 
+	/**
+	 * The default transaction template manager.
+	 *
+	 * @param couchbaseTransactionManager
+	 * @return
+	 */
+	@Bean(BeanNames.COUCHBASE_TRANSACTION_TEMPLATE)
+	TransactionTemplate couchbaseTransactionTemplate(CouchbaseCallbackTransactionManager couchbaseTransactionManager) {
+		return new TransactionTemplate(couchbaseTransactionManager);
+	}
 	/**
 	 * The default TransactionalOperator.
 	 *

src/main/java/org/springframework/data/couchbase/config/BeanNames.java

@@ -64,5 +64,7 @@ public class BeanNames {
 
 	public static final String COUCHBASE_TRANSACTION_MANAGER = "couchbaseTransactionManager";
 
+	public static final String COUCHBASE_TRANSACTION_TEMPLATE = "couchbaseTransactionTemplate";
+
 	public static final String COUCHBASE_TRANSACTIONAL_OPERATOR = "couchbaseTransactionalOperator";
 }

src/test/java/org/springframework/data/couchbase/transactions/CouchbasePersonTransactionReactiveIntegrationTests.java

@@ -108,7 +108,7 @@ public void shouldRollbackAfterException() {
 
 	@Test
 	public void shouldRollbackAfterExceptionOfTxAnnotatedMethod() {
-		assertThrowsWithCause(() -> personService.declarativeSavePersonErrors(WalterWhite).blockLast(),
+		assertThrowsWithCause(() -> personService.declarativeSavePersonErrors(WalterWhite).block(),
 				TransactionSystemUnambiguousException.class, SimulateFailureException.class);
 	}
 

src/test/java/org/springframework/data/couchbase/transactions/CouchbaseTransactionalRepositoryIntegrationTests.java

@@ -114,7 +114,6 @@ public void saveRolledBack() {
 		String id = UUID.randomUUID().toString();
 
 		assertThrowsWithCause(() -> {
-			;
 			userService.run(repo -> {
 				User user = repo.save(new User(id, "Ada", "Lovelace"));
 				SimulateFailureException.throwEx("fail");