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,191 @@
 [[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).
-
- - Group: `com.couchbase.client`
- - Artifact: `couchbase-transactions`
- - Version: latest one, i.e. `1.0.0`
-
-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 the @Transactional operator.
+The @Transactional operator is implemented with the CouchbaseTransactionManager which is supplied as a bean in the AbstractCouchbaseConfiguration.
 
 .Transaction Configuration
 ====
 [source,java]
 ----
 @Configuration
+@EnableCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
+@EnableReactiveCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
+@EnableTransactionManagement // Add for @Transactional annotation support
 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
+public void configureEnvironment(ClusterEnvironment.Builder builder) {
+  // allow really long transactions
+  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. Note that it does not
+apply to ancestor classes up the class hierarchy; inherited methods need to be
+locally redeclared in order to participate in a subclass-level annotation. For
+details on method visibility constraints, consult the
+https://docs.spring.io/spring-framework/docs/current/reference/html/data-access.html#transaction[Transaction Management]
+section of the reference manual.
+ 
+===  Attribute Semantics
+ 
+In this release, he Couchbase Transactions implementation in 
+Spring Data Couchbase ignores all @Transactional attributes.
+The transaction will roll back on uncaught exceptions. 
+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 either by @Autowire or from ac.getBean().
+// 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).
+.TransactionalOperator Construction
+====
+[source,java]
+----
+public static CouchbaseTransactionalOperator create(CouchbaseCallbackTransactionManager manager) 
+====
 
-.Transaction Conversion on Write
+.Transaction Access Using TransactionalOperator.execute()
 ====
 [source,java]
 ----
-@Autowired
-MappingCouchbaseConverter mappingCouchbaseConverter;
+@Autowired TransactionalOperator txOperator;
+@Autowired ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
 
-public void doSomething() {
-  transactions.run(ctx -> {
+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();
+----
+====
 
-   Airline airline = new Airline("demo-airline", "at");
-   CouchbaseDocument target = new CouchbaseDocument();
-   mappingCouchbaseConverter.write(airline, target);
+== Transactions Directly with the SDK
 
-   ctx.insert(couchbaseClientFactory.getDefaultCollection(), target.getId(), target.getContent());
+Please see the https://docs.couchbase.com/java-sdk/current/howtos/distributed-acid-transactions-from-the-sdk.html[Reference Documentation]
 
-   ctx.commit();
-  });
-}
-----
+.Transaction Access - Blocking
 ====
+[source,java]
+----
+@Autowired ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
 
-The same approach can be used on read:
-
-.Transaction Conversion on Read
+TransactionResult result = reactiveCouchbaseTemplate.getCouchbaseClientFactory().getCluster().transactions().run(ctx -> {
+  return reactiveCouchbaseTemplate.insertById(Person.class).one(WalterWhite);
+});
+----
+====
+.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");