Document how to use SessionBuilderConfigurer.

Closes #1447

Author: mp911de

src/main/antora/modules/ROOT/examples/CassandraConfiguration.java

@@ -25,13 +25,15 @@ public class CassandraConfiguration extends AbstractCassandraConfiguration {
 	/*
 	 * Provide a contact point to the configuration.
 	 */
+	@Override
 	public String getContactPoints() {
 		return "localhost";
 	}
 
 	/*
 	 * Provide a keyspace name to the configuration.
 	 */
+	@Override
 	public String getKeyspaceName() {
 		return "mykeyspace";
 	}

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[]

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