FMWK-258 Refactor Operations/Template

README.adoc

@@ -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
@@ -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
@@ -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
@@ -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]
 ----
@@ -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