Spring Data support for Apache Cassandra contains a wide range of features:
Spring Data support for MongoDB contains a wide range of features:
* Spring configuration support with xref:cassandra/configuration.adoc[Java-based `@Configuration` classes or the XML namespace].
* The xref:cassandra/cql-template.adoc[`CqlTemplate`, `AsyncCqlTemplate`, and `ReactiveCqlTemplate`] helper classes that increases productivity by properly handling common Cassandra data access operations.
* The xref:cassandra/template.adoc[`CassandraTemplate`, `AsyncCassandraTemplate`, and `ReactiveCassandraTemplate`] helper classes that provide object mapping between CQL Tables and POJOs.
* xref:cassandra/cql-template.adoc#exception-translation[Exception translation] into Spring's portable {springDocsUrl}data-access.html#dao-exceptions[Data Access Exception Hierarchy].
* Feature rich xref:object-mapping.adoc[object mapping] integrated with _Spring's_ {springDocsUrl}core.html#core-convert[Conversion Service].
* xref:object-mapping.adoc#mapping.usage-annotations[Annotation-based mapping] metadata that is extensible to support other metadata formats.
* 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].
* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets.
* `MongoTemplate` helper class that increases productivity when performing common Mongo operations. Includes integrated object mapping between documents and POJOs.
* Exception translation into Spring's portable Data Access Exception hierarchy.
* Feature-rich Object Mapping integrated with Spring's Conversion Service.
* Annotation-based mapping metadata that is extensible to support other metadata formats.
* Persistence and mapping lifecycle events.
* Java-based Query, Criteria, and Update DSLs.
* Automatic implementation of Repository interfaces, including support for custom finder methods.
* QueryDSL integration to support type-safe queries.
* Multi Document Transactions.
* GeoSpatial integration.
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.
For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality.
`MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations.
`MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongodb.client.MongoDatabase`, to communicate directly with MongoDB.
The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs.
An easy way to bootstrap setting up a working environment is to create a Spring-based project in https://spring.io/tools/[STS].
An easy way to bootstrap setting up a working environment is to create a Spring-based project via https://start.spring.io/#!type=maven-project&dependencies=data-mongodb[start.spring.io] or create a Spring project in https://spring.io/tools[Spring Tools].
First, you need to set up a running MongoDB server. Refer to the https://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of running the following command: `${MONGO_HOME}/bin/mongod`
[[mongo.examples-repo]]
== Examples Repository
To create a Spring project in STS:
The GitHub https://github.com/spring-projects/spring-data-examples[spring-data-examples repository] hosts several examples that you can download and play around with to get a feel for how the library works.
. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted. Then enter a project and a package name, such as `org.spring.mongodb.example`.
. Add the following to the pom.xml files `dependencies` element:
+
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-mongodb</artifactId>
<version>{version}</version>
</dependency>
</dependencies>
----
. Change the version of Spring in the pom.xml to be
. Add the following location of the Spring Milestone repository for Maven to your `pom.xml` such that it is at the same level of your `<dependencies/>` element:
+
[source,xml]
----
<repositories>
<repository>
<id>spring-milestone</id>
<name>Spring Maven MILESTONE Repository</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
----
[[mongodb.hello-world]]
== Hello World
The repository is also https://repo.spring.io/milestone/org/springframework/data/[browseable here].
You may also want to set the logging level to `DEBUG` to see some additional information. To do so, edit the `log4j.properties` file to have the following content:
First, you need to set up a running MongoDB server. Refer to the https://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance.
Once installed, starting MongoDB is typically a matter of running the following command: `${MONGO_HOME}/bin/mongod`
Then you can create a `Person` class to persist:
====
[source,java]
----
package org.spring.mongodb.example;
public class Person {
private String id;
private String name;
private int age;
public Person(String name, int age) {
this.name = name;
this.age = age;
}
public String getId() {
return id;
}
public String getName() {
return name;
}
public int getAge() {
return age;
}
@Override
public String toString() {
return "Person [id=" + id + ", name=" + name + ", age=" + age + "]";
Even in this simple example, there are few things to notice:
* You can instantiate the central helper class of Spring Mongo, xref:reference/mongodb/mongo-template.adoc[`MongoTemplate`], by using the standard `com.mongodb.client.MongoClient` object and the name of the database to use.
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:reference/mapping.adoc[here].).
* You can instantiate the central helper class of Spring Mongo, xref:mongodb/mongo-template.adoc[`MongoTemplate`], by using the standard or reactive `MongoClient` object and the name of the database to use.
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:mongodb/mapping.adoc[here].).
* Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database.
* Mapping conventions can use field access. Notice that the `Person` class has only getters.
* If the constructor argument names match the field names of the stored document, they are used to instantiate the object
There is a https://github.com/spring-projects/spring-data-examples[GitHub repository with several examples] that you can download and play around with to get a feel for how the library works.
The MongoDB support contains a wide range of features:
* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets.
* `MongoTemplate` helper class that increases productivity when performing common Mongo operations.Includes integrated object mapping between documents and POJOs.
* Exception translation into Spring's portable Data Access Exception hierarchy.
* Feature-rich Object Mapping integrated with Spring's Conversion Service.
* Annotation-based mapping metadata that is extensible to support other metadata formats.
* Persistence and mapping lifecycle events.
* Java-based Query, Criteria, and Update DSLs.
* Automatic implementation of Repository interfaces, including support for custom finder methods.
* QueryDSL integration to support type-safe queries.
* Cross-store persistence support for JPA Entities with fields transparently persisted and retrieved with MongoDB (deprecated - to be removed without replacement).
* GeoSpatial integration.
For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. `MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongodb.client.MongoDatabase`, to communicate directly with MongoDB. The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs.
Christoph Strobl
2 years ago