Skip to content

Commit

Permalink
FMWK-258 Refactor Operations/Template (#651)
Browse files Browse the repository at this point in the history 
* Re-add deprecated reactive delete variations with deprecated warning message to use the new ones "deleteAll" and "deleteById".

* 1. Refactor Aerospike Operations/Template for both reactive and non-reactive flows
2. Improve README
3. Add missing reactive operation methods
4. Polish API (methods naming, fields naming, javadocs, interface and implementation ordering...)

* Add numbering to simplify the flow

* Polish README (code review comments)

* Link to aerospike clients (reactive and non-reactive), polish

* README rephrases

* Minor fixes

* Polish README and Operations/Template
  • Loading branch information
@roimenashe
roimenashe authored Nov 6, 2023
1 parent 0e6f00a commit 107339d
Show file tree
Hide file tree
Showing 16 changed files with 1,764 additions and 1,514 deletions.
180 changes: 93 additions & 87 deletions README.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,24 +18,21 @@ writing a repository style data access layer.

== Documentation

* The https://aerospike.github.io/spring-data-aerospike[Documentation Reference]
* 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]
* https://docs.aerospike.com/[Aerospike documentation]
* 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]

If you are new to Spring as well as to Spring Data, look for information
about https://projects.spring.io/[Spring projects].
== Examples

== Demo Projects

[arabic]
. Demo project with detailed guides is located
https://github.com/aerospike-community/spring-data-aerospike-demo[here].
. Demo project example with a step-by-step tutorial can be found
https://github.com/aerospike-examples/simple-springboot-aerospike-demo[here].
https://github.com/aerospike-examples/simple-springboot-aerospike-demo[here]
. Demo project with detailed guides is located
https://github.com/aerospike-community/spring-data-aerospike-demo[here]

== Getting Started blog posts
== Getting Started Blog Posts

[arabic]
. https://medium.com/aerospike-developer-blog/simple-web-application-using-java-spring-boot-aerospike-database-and-docker-ad13795e0089?source=friends_link&sk=43d747f5f55e527248125eeb18748d92[Simple
Web Application Using Java, Spring Boot, Aerospike and Docker]
. https://medium.com/aerospike-developer-blog/how-to-setup-spring-data-aerospike-in-spring-boot-application-afa8bcb59224?source=friends_link&sk=e16a3b69c814bfb22f200634c743e476[How
Expand All @@ -51,8 +48,11 @@ Data Aerospike: Reactive Repositories]
. https://medium.com/aerospike-developer-blog/spring-data-aerospike-projections-951382bc07b5?source=friends_link&sk=d0a3be4fd171bbc9e072d09ccbcf056f[Spring
Data Aerospike - Projections]

== Spring Data Aerospike compatibility
== 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
Expand Down Expand Up @@ -86,55 +86,38 @@ Data Aerospike - Projections]
|1.2.1.RELEASE |1.5.x |4.1.x | |
|===
====

== Quick Start

=== Maven configuration
=== 1. Maven configuration

Add the Maven dependency:
Add the `spring-data-aerospike` Maven dependency:

[source,xml]
----
<dependency>
<groupId>com.aerospike</groupId>
<artifactId>spring-data-aerospike</artifactId>
<version>4.5.0</version>
<version>${spring-data-aerospike.version}</version>
</dependency>
----

The Aerospike Spring Data connector depends on the Aerospike Client
project:
Notes:

[source,xml]
----
<dependency>
<groupId>com.aerospike</groupId>
<artifactId>aerospike-client</artifactId>
</dependency>
----

Dependency will be provided for you by `spring-data-aerospike`, so no
need to declare it additionally.
* It is recommended to use the latest version of Spring Data Aerospike, checkout 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

=== AerospikeTemplate
=== 2. AerospikeRepository

`AerospikeTemplate` is the central support class for Aerospike database
operations. It provides:
`AerospikeRepository` is the simplest way to interact with Aerospike using Spring Data Aerospike.

* Basic POJO mapping support to and from Bins
* Convenience methods to interact with the store (insert object, update
objects) and Aerospike specific ones.
* Connection callback
* Exception translation into Spring’s
https://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions[technology-agnostic
DAO exception hierarchy].

=== Spring Data repositories
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.

To simplify the creation of data repositories Spring Data Aerospike
provides a generic repository programming model. It will automatically
create a repository proxy for you that adds implementations of finder
methods you specify on an interface.
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
Expand All @@ -150,13 +133,17 @@ public interface PersonRepository extends AerospikeRepository<Person, Long> {
}
----

The queries issued on execution will be derived from the method name.
Extending `AerospikeRepository` causes CRUD methods being pulled into
the interface so that you can easily save and find single entities and
collections of them.
For non-blocking reactive API use `ReactiveAerospikeRepository`.

=== 3. Configuration

You can have Spring automatically create a proxy for the interface by
using the following JavaConfig:
In order to configure Spring Data Aerospike you will need to create a configuration class that extends
`AbstractAerospikeDataConfiguration`, defines the relevant Spring Data Repositories via `@EnableAerospikeRepositories`
annotation and overrides `getHosts()` and `nameSpace()` methods with the required connection details.

You can optionally override other methods of `AbstractAerospikeDataConfiguration` to customize your configuration.

Here is a simple example of a configuration class that sets up a connection to a local Aerospike instance:

[source,java]
----
Expand All @@ -171,69 +158,88 @@ class ApplicationConfig extends AbstractAerospikeDataConfiguration {
@Override
protected String nameSpace() {
return "TEST";
return "test";
}
}
----

This sets up a connection to a local Aerospike instance and enables the
detection of Spring Data repositories (through
`@EnableAerospikeRepositories`).
=== Usage

Below is an example of a service that uses `PersonRepository` operations.

This will find the repository interface and register a proxy object in
the container. You can use it as shown below:
* `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 MyService {
public class PersonService {
private final PersonRepository repository;
private final PersonRepository personRepository;
@Autowired
public MyService(PersonRepository repository) {
this.repository = repository;
public PersonService(PersonRepository personRepository) {
this.personRepository = personRepository;
}
public void doWork() {
repository.deleteAll();
public void example() {
// Delete all existing persons
personRepository.deleteAll();
Person person = new Person();
person.setFirstname("Oliver");
person.setLastname("Gierke");
repository.save(person);
List<Person> lastNameResults = repository.findByLastname("Gierke");
List<Person> firstNameResults = repository.findByFirstnameLike("Oli*");
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");
}
}
----

== Getting Help
=== AerospikeOperations

`AerospikeOperations` is the base interface for Aerospike database operations. It is implemented by
`AerospikeTemplate` class.

See <<Documentation, documentation>>.
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

For more detailed questions you can use
https://stackoverflow.com/questions/tagged/spring-data-aerospike[Spring
Data Aerospike on Stackoverflow].
* 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
== Contributing to Spring Data Aerospike

Here are some ways you can get involved:

* Get involved with the Spring community on Stackoverflow and help out
on the
https://stackoverflow.com/questions/tagged/spring-data-aerospike[spring-data-aerospike]
tag by responding to questions and joining the debate.
* Create
* 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 bugs and new features and comment and vote on the ones that
you are interested in.
* GitHub is for social coding: if you want to write code, we encourage
contributions through pull requests from
https://help.github.com/forking/[forks of this repository]. If you want
to contribute code this way, please reference a GitHub ticket as well
covering the specific issue you are addressing.
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.
to Aerospike Stand-Up
93 changes: 0 additions & 93 deletions src/main/java/org/springframework/data/aerospike/core/AerospikeInternalOperations.java
View file

This file was deleted.

Loading

0 comments on commit 107339d

Please sign in to comment.