Prefer Java configuration over XML.

Closes #1308

Author: mp911de

spring-data-cassandra-distribution/pom.xml

@@ -112,6 +112,14 @@
 				<enabled>false</enabled>
 			</snapshots>
 		</repository>
+		<repository>
+			<id>spring-release</id>
+			<name>Spring Release</name>
+			<url>https://repo.spring.io/release</url>  <!-- For Releases -->
+			<snapshots>
+				<enabled>false</enabled>
+			</snapshots>
+		</repository>
 	</repositories>
 
 	<pluginRepositories>
@@ -134,6 +142,14 @@
 				<enabled>false</enabled>
 			</snapshots>
 		</pluginRepository>
+		<pluginRepository>
+			<id>spring-release</id>
+			<name>Spring Release</name>
+			<url>https://repo.spring.io/release</url>  <!-- For Releases -->
+			<snapshots>
+				<enabled>false</enabled>
+			</snapshots>
+		</pluginRepository>
 	</pluginRepositories>
 
 </project>

spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorConfiguration.java

@@ -16,6 +16,7 @@
 package org.springframework.data.cassandra.example;
 
 import org.springframework.context.annotation.Configuration;
+import org.springframework.core.io.ClassPathResource;
 import org.springframework.data.cassandra.config.AbstractCassandraConfiguration;
 import org.springframework.data.cassandra.core.cql.session.init.KeyspacePopulator;
 import org.springframework.data.cassandra.core.cql.session.init.ResourceKeyspacePopulator;
@@ -28,7 +29,8 @@ public class KeyspacePopulatorConfiguration extends AbstractCassandraConfigurati
 	@Nullable
 	@Override
 	protected KeyspacePopulator keyspacePopulator() {
-		return new ResourceKeyspacePopulator(scriptOf("CREATE TABLE my_table …"));
+		return new ResourceKeyspacePopulator(new ClassPathResource("com/foo/cql/db-schema.cql"),
+				new ClassPathResource("com/foo/cql/db-test-data.cql"));
 	}
 
 	@Nullable

spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorFailureConfiguration.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2020-2022 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.core.io.ClassPathResource;
+import org.springframework.data.cassandra.config.AbstractCassandraConfiguration;
+import org.springframework.data.cassandra.core.cql.session.init.KeyspacePopulator;
+import org.springframework.data.cassandra.core.cql.session.init.ResourceKeyspacePopulator;
+import org.springframework.lang.Nullable;
+
+// tag::class[]
+@Configuration
+public class KeyspacePopulatorFailureConfiguration extends AbstractCassandraConfiguration {
+
+	@Nullable
+	@Override
+	protected KeyspacePopulator keyspacePopulator() {
+
+		ResourceKeyspacePopulator populator = new ResourceKeyspacePopulator(
+				new ClassPathResource("com/foo/cql/db-schema.cql"));
+
+		populator.setIgnoreFailedDrops(true);
+
+		return populator;
+	}
+
+	// ...
+	// end::class[]
+
+	@Override
+	protected String getKeyspaceName() {
+		return null;
+	}
+	// tag::class[]
+}
+// end::class[]

src/main/asciidoc/index.adoc

@@ -3,9 +3,9 @@ David Webb, Matthew Adams, John Blum, Mark Paluch, Jay Bryant
 :revnumber: {version}
 :revdate: {localdate}
 ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
-:spring-data-commons-docs: ../../../../../spring-data-commons/src/main/asciidoc
-:example-root: ../../../../spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example
-:example-resources: ../../../../spring-data-cassandra/src/test/resources/org/springframework/data/cassandra/example
+:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
+:example-root: ../../../spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example
+:example-resources: ../../../spring-data-cassandra/src/test/resources/org/springframework/data/cassandra/example
 :tabsize: 2
 :spring-framework-docs: https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/
 

src/main/asciidoc/preface.adoc

@@ -78,7 +78,7 @@ The two key tags to search for related answers to this project are https://stack
 [[get-started:help:professional]]
 Professional Support::
 Professional, from-the-source support, with guaranteed response time, is available from
-https://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
+https://pivotal.io/[Pivotal Software, Inc.], the company behind Spring Data and Spring.
 
 [[get-started:up-to-date]]
 === Following Development

src/main/asciidoc/reference/cassandra-auditing.adoc

@@ -1,21 +1,12 @@
 [[cassandra.auditing]]
 == General Auditing Configuration for Cassandra
 
-To activate auditing functionality, add the Spring Data for Apache Cassandra `auditing` namespace element to your configuration, as the following example shows:
+To activate auditing functionality, create a configuration as the following example shows:
 
 .Activating auditing by using XML configuration
 ====
-[source,xml]
-----
-<cassandra:auditing mapping-context-ref="customMappingContext" auditor-aware-ref="yourAuditorAwareImpl"/>
-----
-====
-
-Alternatively, auditing can be enabled by annotating a configuration class with the `@EnableCassandraAuditing` annotation, as the following example shows:
-
-.Activating auditing using JavaConfig
-====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 @Configuration
 @EnableCassandraAuditing
@@ -27,6 +18,23 @@ class Config {
   }
 }
 ----
+
+.XML
+[source,xml,role="secondary"]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
+  xsi:schemaLocation="
+    http://www.springframework.org/schema/data/cassandra
+    https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
+    http://www.springframework.org/schema/beans
+    https://www.springframework.org/schema/beans/spring-beans.xsd">
+
+    <cassandra:auditing mapping-context-ref="customMappingContext" auditor-aware-ref="yourAuditorAwareImpl"/>
+</beans>
+----
 ====
 
 If you expose a bean of type `AuditorAware` to the `ApplicationContext`, the auditing infrastructure picks it up automatically and uses it to determine the current user to be set on domain types.

src/main/asciidoc/reference/cassandra-repositories.adoc

@@ -54,9 +54,10 @@ The annotation carries the same attributes as the namespace element.
 If no base package is configured, the infrastructure scans the package of the annotated configuration class.
 The following example shows how to use the `@EnableCassandraRepositories` annotation:
 
-.Java configuration for repositories
+.Configuration for repositories
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 @Configuration
 @EnableCassandraRepositories
@@ -72,13 +73,9 @@ class ApplicationConfig extends AbstractCassandraConfiguration {
   }
 }
 ----
-====
 
-If you want to use XML configuration, then the following example shows a minimal configuration snippet:
-
-.Cassandra repository Spring XML configuration
-====
-[source,xml]
+.XML
+[source,xml,role="secondary"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"

src/main/asciidoc/reference/cassandra.adoc

@@ -291,30 +291,38 @@ Declaring a keyspace with a specification allows creating and dropping of the Ke
 It derives CQL from the specification so that you need not write CQL yourself.
 The following example specifies a Cassadra keyspace by using XML:
 
-.Specifying a Cassandra keyspace by using XML
+.Specifying a Cassandra keyspace
 ====
-[source,xml]
+.Java
+[source,java,role="primary"]
+----
+include::../{example-root}/CreateKeyspaceConfiguration.java[tags=class]
 ----
-<cassandra:session>
-
-    <cassandra:keyspace action="CREATE_DROP" durable-writes="true" name="my_keyspace">
-        <cassandra:replication class="NETWORK_TOPOLOGY_STRATEGY">
-          <cassandra:data-center name="foo" replication-factor="1" />
-          <cassandra:data-center name="bar" replication-factor="2" />
-        </cassandra:replication>
-  </cassandra:keyspace>
 
-</cassandra:session>
+.XML
+[source,xml,role="secondary"]
 ----
-====
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
+  xsi:schemaLocation="
+    http://www.springframework.org/schema/data/cassandra
+    https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
+    http://www.springframework.org/schema/beans
+    https://www.springframework.org/schema/beans/spring-beans.xsd">
 
-You can also specify a Cassandra keyspace by using Java configuration, as the following example shows:
+    <cassandra:session>
 
-.Specifying a Cassandra keyspace by using Java configuration
-====
-[source,java]
-----
-include::../{example-root}/CreateKeyspaceConfiguration.java[tags=class]
+        <cassandra:keyspace action="CREATE_DROP" durable-writes="true" name="my_keyspace">
+            <cassandra:replication class="NETWORK_TOPOLOGY_STRATEGY">
+              <cassandra:data-center name="foo" replication-factor="1" />
+              <cassandra:data-center name="bar" replication-factor="2" />
+            </cassandra:replication>
+      </cassandra:keyspace>
+
+    </cassandra:session>
+</beans>
 ----
 ====
 
@@ -334,16 +342,14 @@ You may sometimes need to initialize a keyspace that runs on a server somewhere.
 You can provide arbitrary CQL that is executed on `CqlSession` initialization and shutdown in the configured keyspace, as the following Java configuration example shows:
 
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 include::../{example-root}/KeyspacePopulatorConfiguration.java[tags=class]
 ----
-====
-
-If you want to initialize a database using XML configuration and you can provide a reference to a `SessionFactory` bean, you can use the `initialize-keyspace` tag in the `cassandra` namespace:
 
-====
-[source,xml,indent=0,subs="verbatim,quotes"]
+.XML
+[source,xml,indent=0,subs="verbatim,quotes",role="secondary"]
 ----
 <cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory">
     <cassandra:script location="classpath:com/foo/cql/db-schema.cql"/>
@@ -382,7 +388,14 @@ The second option to control what happens with existing data is to be more toler
 To this end, you can control the ability of the initializer to ignore certain errors in the CQL it executes from the scripts, as the following example shows:
 
 ====
-[source,xml,indent=0,subs="verbatim,quotes"]
+.Java
+[source,java,role="primary"]
+----
+include::../{example-root}/KeyspacePopulatorFailureConfiguration.java[tags=class]
+----
+
+.XML
+[source,xml,indent=0,subs="verbatim,quotes",role="secondary"]
 ----
 <cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory" ignore-failures="DROPS">
     <cassandra:script location="..."/>
@@ -401,27 +414,24 @@ Each statement should be separated by `;` or a new line if the `;` character is
 You can control that globally or script by script, as the following example shows:
 
 ====
-[source,java]
+.Java
+[source,java,role="primary"]
 ----
 include::../{example-root}/SessionFactoryInitializerConfiguration.java[tags=class]
 ----
-====
-
-Alternatively, you can use XML to configure the `SessionFactoryInitializer`:
 
-====
-[source,xml,indent=0,subs="verbatim,quotes"]
+.XML
+[source,xml,indent=0,subs="verbatim,quotes",role="secondary"]
 ----
-<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory" separator="@@">        <1>
-    <cassandra:script location="classpath:com/myapp/cql/db-schema.cql" separator=";"/>     <2>
+<cassandra:initialize-keyspace session-factory-ref="cassandraSessionFactory" separator="@@">
+    <cassandra:script location="classpath:com/myapp/cql/db-schema.cql" separator=";"/>
     <cassandra:script location="classpath:com/myapp/cql/db-test-data-1.cql"/>
     <cassandra:script location="classpath:com/myapp/cql/db-test-data-2.cql"/>
 </cassandra:initialize-keyspace>
 ----
-<1> Set the separator scripts to `@@`.
-<2> Set the separator for `db-schema.cql` to `;`.
 ====
 
+
 In this example, the two `test-data` scripts use `@@` as statement separator and only the `db-schema.cql` uses `;`.
 This configuration specifies that the default separator is `@@` and overrides that default for the `db-schema` script.
 
@@ -490,23 +500,29 @@ to specify the desired column type.
 
 The following example shows how to specify entity base packages in XML configuration:
 
-.Specifying entity base packages with XML configuration
+.Specifying entity base packages
 ====
-[source,xml]
+.Java
+[source,java,role="primary"]
 ----
-
-<cassandra:mapping entity-base-packages="com.foo,com.bar"/>
-
+include::../{example-root}/EntityBasePackagesConfiguration.java[tags=class]
 ----
-====
-
-The following example shows how to specify entity base packages in Java configuration:
 
-.Specifying entity base packages with Java configuration
-====
-[source,java]
+.XML
+[source,xml,role="secondary"]
 ----
-include::../{example-root}/EntityBasePackagesConfiguration.java[tags=class]
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:cassandra="http://www.springframework.org/schema/data/cassandra"
+  xsi:schemaLocation="
+    http://www.springframework.org/schema/data/cassandra
+    https://www.springframework.org/schema/data/cassandra/spring-cassandra.xsd
+    http://www.springframework.org/schema/beans
+    https://www.springframework.org/schema/beans/spring-beans.xsd">
+
+    <cassandra:mapping entity-base-packages="com.foo,com.bar"/>
+</beans>
 ----
 ====