From e9f0a08481fbedfef7c4b129e3c090710b9910de Mon Sep 17 00:00:00 2001
From: Mark Paluch <mpaluch@vmware.com>
Date: Wed, 25 Oct 2023 15:20:28 +0200
Subject: [PATCH] Document how to use `SessionBuilderConfigurer`.

Closes #1447
---
 .../ROOT/examples/CassandraConfiguration.java |  2 +
 .../CustomizedCassandraConfiguration.java     | 46 +++++++++++++++++++
 .../ROOT/pages/cassandra/configuration.adoc   | 19 +++++++-
 3 files changed, 65 insertions(+), 2 deletions(-)
 create mode 100644 src/main/antora/modules/ROOT/examples/CustomizedCassandraConfiguration.java

diff --git a/src/main/antora/modules/ROOT/examples/CassandraConfiguration.java b/src/main/antora/modules/ROOT/examples/CassandraConfiguration.java
index 6c63e995e..3e316cc32 100644
--- a/src/main/antora/modules/ROOT/examples/CassandraConfiguration.java
+++ b/src/main/antora/modules/ROOT/examples/CassandraConfiguration.java
@@ -25,6 +25,7 @@ public class CassandraConfiguration extends AbstractCassandraConfiguration {
 	/*
 	 * Provide a contact point to the configuration.
 	 */
+	@Override
 	public String getContactPoints() {
 		return "localhost";
 	}
@@ -32,6 +33,7 @@ public String getContactPoints() {
 	/*
 	 * Provide a keyspace name to the configuration.
 	 */
+	@Override
 	public String getKeyspaceName() {
 		return "mykeyspace";
 	}
diff --git a/src/main/antora/modules/ROOT/examples/CustomizedCassandraConfiguration.java b/src/main/antora/modules/ROOT/examples/CustomizedCassandraConfiguration.java
new file mode 100644
index 000000000..820a5c0f1
--- /dev/null
+++ b/src/main/antora/modules/ROOT/examples/CustomizedCassandraConfiguration.java
@@ -0,0 +1,46 @@
+/*
+ * Copyright 2020-2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.cassandra.example;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.data.cassandra.config.AbstractCassandraConfiguration;
+
+// tag::class[]
+@Configuration
+public class CustomizedCassandraConfiguration extends AbstractCassandraConfiguration {
+
+	/*
+	 * Customize the CqlSession through CqlSessionBuilder.
+	 */
+	@Override
+	protected SessionBuilderConfigurer getSessionBuilderConfigurer() {
+
+		Path connectBundlePath = …;
+
+		return builder -> builder
+				.withCloudSecureConnectBundle(Path.of(connectBundlePath));
+	}
+
+	/*
+	 * Provide a keyspace name to the configuration.
+	 */
+	@Override
+	public String getKeyspaceName() {
+		return "mykeyspace";
+	}
+
+}
+// end::class[]
diff --git a/src/main/antora/modules/ROOT/pages/cassandra/configuration.adoc b/src/main/antora/modules/ROOT/pages/cassandra/configuration.adoc
index 31f5c9e89..199c6d1b3 100644
--- a/src/main/antora/modules/ROOT/pages/cassandra/configuration.adoc
+++ b/src/main/antora/modules/ROOT/pages/cassandra/configuration.adoc
@@ -10,7 +10,7 @@ https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/new-in-
 as well as the detailed documentation {springDocsUrl}core.html#beans-java-instantiating-container[here].
 
 [[cassandra.cassandra-java-config]]
-== Registering a Session Instance by Using Java-based Metadata
+== Registering a Session Instance by using Java-based Metadata
 
 The following example shows how to use Java-based bean metadata to register an instance of a `com.datastax.oss.driver.api.core.CqlSession`:
 
@@ -68,11 +68,26 @@ include::example$CassandraConfiguration.java[tags=class]
 ----
 ====
 
+`Abstract…Configuration` classes wire all the necessary beans for using Cassandra from your application.
+The configuration assumes a single `CqlSession` and wires it through `SessionFactory` into the related components such as `CqlTemplate`.
+If you want to customize the creation of the `CqlSession`, then you can provide a `SessionBuilderConfigurer` function to customize `CqlSessionBuilder`.
+This is useful to provide e.g. a Cloud Connection Bundle for Astra.
+
+.Connecting to Astra through `AbstractCassandraConfiguration`
+====
+[source,java]
+----
+include::example$CustomizedCassandraConfiguration.java[tags=class]
+----
+====
+
 [[cassandra-connectors.xmlconfig]]
-=== XML Configuration
+== XML Configuration
 
 This section describes how to configure Spring Data Cassandra with XML.
 
+WARNING: While we still support Namespace Configuration, we generally recommend using <<cassandra.cassandra-java-config,Java-based Configuration>>.
+
 [[cassandra-connectors.xmlconfig.ext_properties]]
 === Externalizing Connection Properties