From ece928728a6bb97e9227d413bf608698b837571f Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Tue, 27 Sep 2022 14:30:20 +0200 Subject: [PATCH] Prefer Java configuration over XML. Closes #1308 --- spring-data-cassandra-distribution/pom.xml | 16 +++ .../KeyspacePopulatorConfiguration.java | 4 +- ...KeyspacePopulatorFailureConfiguration.java | 50 ++++++++ src/main/asciidoc/index.adoc | 6 +- src/main/asciidoc/preface.adoc | 2 +- .../reference/cassandra-auditing.adoc | 32 +++-- .../reference/cassandra-repositories.adoc | 13 +- src/main/asciidoc/reference/cassandra.adoc | 120 ++++++++++-------- 8 files changed, 166 insertions(+), 77 deletions(-) create mode 100644 spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorFailureConfiguration.java diff --git a/spring-data-cassandra-distribution/pom.xml b/spring-data-cassandra-distribution/pom.xml index 8d96be266..c08ddfa12 100644 --- a/spring-data-cassandra-distribution/pom.xml +++ b/spring-data-cassandra-distribution/pom.xml @@ -112,6 +112,14 @@ false + + spring-release + Spring Release + https://repo.spring.io/release + + false + + @@ -134,6 +142,14 @@ false + + spring-release + Spring Release + https://repo.spring.io/release + + false + + diff --git a/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorConfiguration.java b/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorConfiguration.java index b3c047917..415dec3c3 100644 --- a/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorConfiguration.java +++ b/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 diff --git a/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorFailureConfiguration.java b/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/KeyspacePopulatorFailureConfiguration.java new file mode 100644 index 000000000..cf7eb0752 --- /dev/null +++ b/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[] diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 5b9ae82e3..7b94208a6 100644 --- a/src/main/asciidoc/index.adoc +++ b/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/ diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 9e6683569..6b6e8421c 100644 --- a/src/main/asciidoc/preface.adoc +++ b/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 diff --git a/src/main/asciidoc/reference/cassandra-auditing.adoc b/src/main/asciidoc/reference/cassandra-auditing.adoc index ed48773de..5791f3677 100644 --- a/src/main/asciidoc/reference/cassandra-auditing.adoc +++ b/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] ----- - ----- -==== - -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"] +---- + + + + + +---- ==== 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. diff --git a/src/main/asciidoc/reference/cassandra-repositories.adoc b/src/main/asciidoc/reference/cassandra-repositories.adoc index 149c7ddbc..cb217c812 100644 --- a/src/main/asciidoc/reference/cassandra-repositories.adoc +++ b/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"] ---- - - - - - - - - - ----- -==== - -You can also specify a Cassandra keyspace by using Java configuration, as the following example shows: - -.Specifying a Cassandra keyspace by using Java configuration -==== -[source,java] +.Java +[source,java,role="primary"] ---- include::../{example-root}/CreateKeyspaceConfiguration.java[tags=class] ---- + +.XML +[source,xml,role="secondary"] +---- + + + + + + + + + + + + + + +---- ==== NOTE: Keyspace creation allows rapid bootstrapping without the need of external keyspace management. @@ -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"] ---- @@ -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"] ---- @@ -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"] ---- - <1> - <2> + + ---- -<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,24 +500,30 @@ 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] ----- - - - ----- -==== - -The following example shows how to specify entity base packages in Java configuration: - -.Specifying entity base packages with Java configuration -==== -[source,java] +.Java +[source,java,role="primary"] ---- include::../{example-root}/EntityBasePackagesConfiguration.java[tags=class] ---- + +.XML +[source,xml,role="secondary"] +---- + + + + + +---- ==== [[cassandra.cql-template]]