Spring/spring-data-cassandra
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Refine documentation.

Browse Source 
Remove links to absent headers. Merge introduction to Cassandra section page.

Closes #1475
This commit is contained in:
Mark Paluch
2024-02-07 09:28:56 +01:00
parent b751a816a4
commit eb4402c8ab
3 changed files with 74 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
src/main/antora/modules/ROOT/pages/cassandra.adoc
View File

@@ -2,6 +2,7 @@
= Cassandra Support
:page-section-summary-toc: 1
This part of the reference documentation explains the core functionality offered by Spring Data for Apache Cassandra.
Spring Data support for Apache Cassandra contains a wide range of features:
* Spring configuration support with xref:cassandra/configuration.adoc[Java-based `@Configuration` classes or the XML namespace].
@@ -13,5 +14,77 @@ Spring Data support for Apache Cassandra contains a wide range of features:
* Java-based xref:cassandra/template.adoc#cassandra.template.query[query, criteria, and update DSLs].
* Automatic implementation of xref:repositories.adoc[imperative and reactive `Repository` interfaces] including support for xref:repositories/custom-implementations.adoc[custom query methods].
[[cassandra.abstractions]]
== Abstractions
Spring Data for Apache Cassandra allows interaction on both the CQL and the entity level.
The value provided by the Spring Data for Apache Cassandra abstraction is perhaps best shown by the sequence of actions outlined in the table below.
The table shows which actions Spring take care of and which actions are the responsibility of you, the application developer.
[[cassandra.modules.who-does-what]]
.Spring Data for Apache Cassandra - who does what?
|===
| Action| Spring| You
| Define connection parameters.
|
| X
| Open the connection.
| X
|
| Specify the CQL statement.
|
| X
| Declare parameters and provide parameter values
|
| X
| Prepare and run the statement.
| X
|
| Set up the loop to iterate through the results (if any).
| X
|
| Do the work for each iteration.
|
| X
| Process any exception.
| X
|
| Close the Session.
| X
|
|===
The core CQL support takes care of all the low-level details that can make Cassandra and CQL such a tedious API with which to develop.
Using mapped entity objects allows schema generation, object mapping, and repository support.
[[cassandra.choose-style]]
=== Choosing an Approach for Cassandra Database Access
You can choose among several approaches to use as a basis for your Cassandra database access.
Spring's support for Apache Cassandra comes in different flavors.
Once you start using one of these approaches, you can still mix and match to include a feature from a different approach.
The following approaches work well:
* xref:cassandra/cql-template.adoc[`CqlTemplate`] and xref:cassandra/reactive-cassandra.adoc[`ReactiveCqlTemplate`] are the classic Spring CQL approach and the most popular.
This is the "`lowest-level`" approach.
Note that components like `CassandraTemplate`
use `CqlTemplate` under-the-hood.
* xref:cassandra/template.adoc[`CassandraTemplate`] wraps a `CqlTemplate` to provide query result-to-object mapping and the use of `SELECT`, `INSERT`, `UPDATE`, and `DELETE` methods instead of writing CQL statements.
This approach provides better documentation and ease of use.
* xref:cassandra/reactive-cassandra.adoc[`ReactiveCassandraTemplate`] wraps a `ReactiveCqlTemplate` to provide query result-to-object mapping and the use of `SELECT`, `INSERT`, `UPDATE`, and `DELETE` methods instead of writing CQL statements.
This approach provides better documentation and ease of use.
* Repository Abstraction lets you create repository declarations in your data access layer.
The goal of Spring Data's repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.
For most data-oriented tasks, you can use the `[Reactive|Async]CassandraTemplate` or the `Repository` support, both of which use the rich object-mapping functionality. `[Reactive|Async]CqlTemplate` is commonly used to increment counters or perform ad-hoc CRUD operations. `[Reactive|Async]CqlTemplate` also provides callback methods that make it easy to get low-level API objects, such as `com.datastax.oss.driver.api.core.CqlSession`, which lets you communicate directly with Cassandra.
Spring Data for Apache Cassandra uses consistent naming conventions on objects in various APIs to those found in the DataStax Java Driver so that they are familiar and so that you can map your existing knowledge onto the Spring APIs.

2
src/main/antora/modules/ROOT/pages/cassandra/cql-template.adoc
View File

@@ -21,7 +21,7 @@ Defaults apply if the particular query option is not set.
NOTE: `CqlTemplate` comes in different execution model flavors.
The basic `CqlTemplate` uses a blocking execution model.
You can use `AsyncCqlTemplate` for asynchronous execution and synchronization with `ListenableFuture` instances or
<<cassandra.reactive.cql-template,`ReactiveCqlTemplate`>> for reactive execution.
`ReactiveCqlTemplate` for reactive execution.
[[cassandracql-template.examples]]
== Examples of `CqlTemplate` Class Usage

80
src/main/antora/modules/ROOT/pages/cassandra/introduction.adoc
View File

@@ -1,80 +0,0 @@
[[cassandra.introduction]]
= Introduction
This part of the reference documentation explains the core functionality offered by Spring Data for Apache Cassandra.
* xref:cassandra.adoc[Cassandra Support] introduces the Cassandra module feature set.
* xref:cassandra/reactive-cassandra.adoc[Reactive Cassandra Support] explains reactive Cassandra specifics.
* xref:repositories.adoc[Cassandra Repositories] introduces repository support for Cassandra.
[[cassandra.modules]]
== Spring CQL and Spring Data for Apache Cassandra Modules
Spring Data for Apache Cassandra allows interaction on both the CQL and the entity level.
The value provided by the Spring Data for Apache Cassandra abstraction is perhaps best shown by the sequence of actions outlined in the table below.
The table shows which actions Spring take care of and which actions are the responsibility of you, the application developer.
[[cassandra.modules.who-does-what]]
.Spring Data for Apache Cassandra (CQL Core)- who does what?
|===
| Action| Spring| You
| Define connection parameters.
|
| X
| Open the connection.
| X
|
| Specify the CQL statement.
|
| X
| Declare parameters and provide parameter values
|
| X
| Prepare and run the statement.
| X
|
| Set up the loop to iterate through the results (if any).
| X
|
| Do the work for each iteration.
|
| X
| Process any exception.
| X
|
| Close the Session.
| X
|
|===
The core CQL support takes care of all the low-level details that can make Cassandra and CQL such a tedious API with which to develop.
Using mapped entity objects allows schema generation, object mapping, and repository support.
[[cassandra.choose-style]]
=== Choosing an Approach for Cassandra Database Access
You can choose among several approaches to use as a basis for your Cassandra database access.
Spring's support for Apache Cassandra comes in different flavors.
Once you start using one of these approaches, you can still mix and match to include a feature from a different approach.
The following approaches work well:
* xref:cassandra/cql-template.adoc[`CqlTemplate`] and xref:cassandra/reactive-cassandra.adoc#cassandra.reactive.cql-template[`ReactiveCqlTemplate`] are the classic Spring CQL approach and the most popular.
This is the "`lowest-level`" approach.
Note that components like `CassandraTemplate`
use `CqlTemplate` under-the-hood.
* xref:cassandra/template.adoc[`CassandraTemplate`] wraps a `CqlTemplate` to provide query result-to-object mapping and the use of `SELECT`, `INSERT`, `UPDATE`, and `DELETE` methods instead of writing CQL statements.
This approach provides better documentation and ease of use.
* xref:cassandra/reactive-cassandra.adoc#cassandra.reactive.template[`ReactiveCassandraTemplate`] wraps a `ReactiveCqlTemplate` to provide query result-to-object mapping and the use of `SELECT`, `INSERT`, `UPDATE`, and `DELETE` methods instead of writing CQL statements.
This approach provides better documentation and ease of use.
* Repository Abstraction lets you create repository declarations in your data access layer.
The goal of Spring Data's repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.