= Spring Data Aerospike
:maven-image: https://img.shields.io/maven-central/v/com.aerospike/spring-data-aerospike.svg?maxAge=259200
:maven-url: https://search.maven.org/#search%7Cga%7C1%7Ca%3A%22spring-data-aerospike%22
:ci-image: https://github.com/aerospike/spring-data-aerospike/workflows/Build%20project/badge.svg
:ci-url: https://github.com/aerospike/spring-data-aerospike/actions?query=branch%3Amain
:javadoc-image: https://javadoc.io/badge2/com.aerospike/spring-data-aerospike/javadoc.svg
:javadoc-url: https://javadoc.io/doc/com.aerospike/spring-data-aerospike
{maven-url}[image:{maven-image}[maven]]
{ci-url}[image:{ci-image}[ci]]
{javadoc-url}[image:{javadoc-image}[javadoc]]
The Spring Data Aerospike project aims to provide a familiar and consistent Spring-based programming model for new data
stores while retaining store-specific features and capabilities. It provides integration with the Aerospike database.
Key functional areas of Spring Data Aerospike are a POJO centric model for interacting with Aerospike DB and easily
writing a repository style data access layer.
== Documentation
* Spring Data Aerospike https://aerospike.github.io/spring-data-aerospike[Documentation Reference]
* Java code documentation on https://www.javadoc.io/doc/com.aerospike/spring-data-aerospike[javadoc.io]
* Aerospike https://docs.aerospike.com/[Official Documentation]
* If you are new to Spring as well as to Spring Data, look for information
about https://projects.spring.io/[Spring Projects]
== Examples
Demo repository with detailed guides is located
https://github.com/aerospike-community/spring-data-aerospike-demo[here]
== Getting Started
. https://github.com/aerospike-community/spring-data-aerospike-demo/blob/main/asciidoc/getting-started.adoc[How to set up Spring Data Aerospike in a Spring Boot application for basic CRUD operations]
. https://github.com/aerospike-community/spring-data-aerospike-demo/blob/main/asciidoc/creating-secondary-index.adoc[How
to create secondary index in Spring Data Aerospike]
. https://github.com/aerospike-community/spring-data-aerospike-demo/blob/main/asciidoc/basic-error-handling.adoc[Basic
error handling in Spring Data Aerospike]
. https://github.com/aerospike-community/spring-data-aerospike-demo/blob/main/asciidoc/custom-converters.adoc[Creating custom converters]
. https://github.com/aerospike-community/spring-data-aerospike-demo/blob/main/asciidoc/optimistic-locking.adoc[Handling concurrent updates using optimistic locking]
. https://medium.com/aerospike-developer-blog/caching-with-spring-boot-and-aerospike-17b91267d6c?source=friends_link&sk=e166b4592c9c00e3d996663f4c47e2b5[Caching
with Spring Boot and Aerospike]
. https://medium.com/aerospike-developer-blog/spring-data-aerospike-reactive-repositories-fb6478acea41?source=friends_link&sk=66541b82192ded459a537261e9a38bd5[Spring
Data Aerospike: Reactive Repositories]
. https://medium.com/aerospike-developer-blog/spring-data-aerospike-projections-951382bc07b5?source=friends_link&sk=d0a3be4fd171bbc9e072d09ccbcf056f[Spring
Data Aerospike - Projections]
. https://aerospike.com/blog/spring-data-aerospike-5-new-features[Spring
Data Aerospike 5.0.0: New Features]
. https://aerospike.com/blog/spring-data-aerospike-5-updates[Spring
Data Aerospike 5.0.0: Important Updates]
== Spring Data Aerospike Compatibility
.Compatibility Table
[%collapsible]
====
[width="100%",cols="<24%,<14%,<18%,<26%,<18%",options="header",]
|===
|Spring Data Aerospike |Spring Boot |Aerospike Client |Aerospike Reactor Client |Aerospike Server
|5.0.x |3.4.x |9.0.x |9.0.x |6.1.x.x +
|4.8.x |3.3.x |7.2.x |7.1.x |5.2.x.x +
|4.7.x |3.2.x |7.2.x |7.1.x |5.2.x.x +
|4.6.x |3.2.x |7.2.x |7.1.x |5.2.x.x +
|4.5.x |3.1.x |7.1.x |7.0.x |5.2.x.x +
|4.4.x |3.1.x |7.0.x |7.0.x |5.2.x.x +
|4.3.x |3.1.x |6.1.x |6.1.x |5.2.x.x +
|4.2.x |3.0.x |6.1.x |6.1.x |5.2.x.x +
|4.1.x |3.0.x |6.1.x |6.1.x |5.2.x.x +
|3.5.x |2.7.x |6.1.x |6.1.x |5.2.x.x +
|3.4.x |2.6.x |5.1.x |5.1.x |5.2.x.x +
|3.3.x |2.5.x |5.1.x |5.1.x |5.2.x.x +
|3.2.x |2.5.x |5.1.x |5.0.x |5.2.x.x +
|3.0.x, 3.1.x |2.5.x |5.1.x |5.0.x |
|2.5.x |2.5.x |4.4.x |4.4.x |
|2.4.2.RELEASE |2.3.x |4.4.x |4.4.x |
|2.3.5.RELEASE |2.2.x |4.4.x |4.4.x |
|2.1.1.RELEASE |2.1.x, 2.0.x |4.4.x |3.2.x |
|1.2.1.RELEASE |1.5.x |4.1.x | |
|===
====
== Quick Start
=== 1. Maven configuration
Add the `spring-data-aerospike` Maven dependency:
[source,xml]
----
<dependency>
<groupId>com.aerospike</groupId>
<artifactId>spring-data-aerospike</artifactId>
<version>${spring-data-aerospike.version}</version>
</dependency>
----
Notes:
* It is recommended to use the latest version. Check out Spring Data Aerospike
https://github.com/aerospike/spring-data-aerospike/releases[GitHub releases]
* Spring Data Aerospike uses the https://github.com/aerospike/aerospike-client-java[Aerospike Java Client]
(and https://github.com/aerospike/aerospike-client-java-reactive[Aerospike Reactive Java Client]) under the hood
=== 2. AerospikeRepository
`AerospikeRepository` is the simplest way to interact with Aerospike using Spring Data Aerospike.
Create your own custom repository that extends `AerospikeRepository` which will provide out-of-the-box CRUD operations
and query implementations, so you can easily save, find, delete and query single entities and collections of them.
Implementation will be determined by the method names automatically, no need to write any implementation.
For example, given a `Person` class with first and last name properties,
a `PersonRepository` interface that can query for `Person` by last name
and when the first name matches a like expression is shown below:
[source,java]
----
public interface PersonRepository extends AerospikeRepository<Person, Long> {
List<Person> findByLastname(String lastname);
List<Person> findByFirstnameLike(String firstname);
}
----
For non-blocking reactive API use `ReactiveAerospikeRepository`.
=== 3. Configuration
In order to configure Spring Data Aerospike you will need to create a configuration class that extends
`AbstractAerospikeDataConfiguration` and defines the relevant Spring Data Repositories via `@EnableAerospikeRepositories`
annotation.
To set the connection details you can either override `getHosts()` and `nameSpace()` methods
of the `AbstractAerospikeDataConfiguration` class or define `spring.aerospike.hosts` and
`spring.data.aerospike.namespace` in `application.properties` file.
NOTE: You can further customize your configuration by changing other xref:#configuration[`settings`].
Here is a simple example of a configuration class that sets up a connection to a local Aerospike DB instance:
[source,java]
----
@Configuration
@EnableAerospikeRepositories(basePackageClasses = PersonRepository.class)
class ApplicationConfig extends AbstractAerospikeDataConfiguration {
@Override
protected Collection<Host> getHosts() {
return Collections.singleton(new Host("localhost", 3000));
}
@Override
protected String nameSpace() {
return "test";
}
}
----
=== Usage
Below is an example of a service that uses `PersonRepository` operations.
* `deleteAll` and `save` are provided automatically by extending `AerospikeRepository` interface
* `findByFirstnameLike` and `findByLastname` methods were defined in `PersonRepository` but there was no need to write
the actual implementation, it is determined automatically from the method names
[source,java]
----
@Service
public class PersonService {
private final PersonRepository personRepository;
@Autowired
public PersonService(PersonRepository personRepository) {
this.personRepository = personRepository;
}
public void example() {
// Delete all existing persons
personRepository.deleteAll();
Person person = new Person();
person.setFirstname("John");
person.setLastname("Smith");
// Save the new created person
personRepository.save(person);
// Get all persons whose first name starts with "Jo"
List<Person> firstNameResults = personRepository.findByFirstnameLike("Jo*");
// Get all persons whose last name is equal to "Smith"
List<Person> lastNameResults = personRepository.findByLastname("Smith");
}
}
----
=== AerospikeOperations
`AerospikeOperations` is the base interface for Aerospike database operations. It is implemented by
`AerospikeTemplate` class.
As a lower-level alternative to `AerospikeRepository`, `AerospikeOperations` supports wider variety of operations and
greater flexibility, but requires a bit more code writing and less out-of-the-box functionality.
Features supported by `AerospikeOperations`:
* Basic support for mapping POJOs to and from Aerospike bins
* Convenience CRUD (Create, Read, Update and Delete) methods for interacting with Aerospike
* Rich query API
* Access to the native Aerospike Java Client (reactive and non-reactive)
* Translating exceptions into Spring's
https://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions[technology-agnostic
DAO exception hierarchy]
For non-blocking reactive API use `ReactiveAerospikeOperations`.
== Getting Help
* See <<Documentation, documentation section>>
* Ask a specific question using
https://stackoverflow.com/questions/tagged/spring-data-aerospike[Spring Data Aerospike tag on StackOverflow]
== Contributing to Spring Data Aerospike
Here are some ways you can get involved:
* Help out on the StackOverflow https://stackoverflow.com/questions/tagged/spring-data-aerospike[spring-data-aerospike]
tag by responding to questions and joining the debate
* Create a
https://github.com/aerospike/spring-data-aerospike/issues[GitHub
issue] for a feature request or bug fixing, comment and vote on the ones that
you are interested in
* GitHub is for social coding: we encourage contributions through pull requests from
https://help.github.com/forking/[forks of this repository]. When contributing code, please reference a specific
GitHub issue you are addressing
* Watch for upcoming articles by
https://www.aerospike.com/forms/subscribe-the-aerospike-standup/[subscribing]
to Aerospike Stand-Up