FMWK-617 Update documentation

README.adoc

@@ -111,7 +111,7 @@ Add the `spring-data-aerospike` Maven dependency:
 
 Notes:
 
-* It is recommended to use the latest version of Spring Data Aerospike, checkout Spring Data Aerospike
+* 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
@@ -148,8 +148,8 @@ In order to configure Spring Data Aerospike you will need to create a configurat
 annotation.
 
 To set the connection details you can either override `getHosts()` and `nameSpace()` methods
-of the `AbstractAerospikeDataConfiguration` class or define `spring-data-aerospike.connection.hosts` and
-`spring-data-aerospike.connection.namespace` in `application.properties` file.
+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`].
 

src/main/asciidoc/index.adoc

@@ -1,11 +1,11 @@
+[[aerospike.index]]
 = Spring Data Aerospike - Documentation
 :doctype: book
 :revnumber: 4.8.0
 :revdate: {localdate}
 :toc:
 :toc-placement!:
 :toclevels: 1
-:spring-data-commons-docs-online: https://docs.spring.io/spring-data/commons/docs/current/reference/html
 
 (C) 2018-2024 The original authors.
 
@@ -26,28 +26,24 @@ include::preface.adoc[]
 
 include::reference/functionality.adoc[]
 include::reference/installation-and-usage.adoc[]
-include::spring-data-commons-docs/repositories.adoc[]
 include::reference/aerospike-repositories.adoc[]
 include::reference/aerospike-reactive-repositories.adoc[]
-include::spring-data-commons-docs/repository-projections.adoc[]
 include::reference/aerospike-projections.adoc[]
-include::spring-data-commons-docs/query-by-example.adoc[]
 include::reference/query-methods-preface.adoc[]
 include::reference/query-methods-simple-property.adoc[]
 include::reference/query-methods-collection.adoc[]
 include::reference/query-methods-map.adoc[]
 include::reference/query-methods-pojo.adoc[]
 include::reference/query-methods-id.adoc[]
+include::reference/query-methods-combined.adoc[]
 include::reference/query-methods-modification.adoc[]
-include::spring-data-commons-docs/object-mapping.adoc[]
 include::reference/aerospike-object-mapping.adoc[]
+include::reference/aerospike-custom-converters.adoc[]
 include::reference/template.adoc[]
 include::reference/secondary-indexes.adoc[]
 include::reference/indexed-annotation.adoc[]
 include::reference/caching.adoc[]
 include::reference/configuration.adoc[]
-include::spring-data-commons-docs/dependencies.adoc[]
-include::spring-data-commons-docs/auditing.adoc[]
 
 :leveloffset: -1
 
@@ -56,9 +52,8 @@ include::spring-data-commons-docs/auditing.adoc[]
 
 :leveloffset: +1
 
-include::spring-data-commons-docs/repository-namespace-reference.adoc[]
-include::spring-data-commons-docs/repository-populator-namespace-reference.adoc[]
-include::spring-data-commons-docs/repository-query-keywords-reference.adoc[]
-include::spring-data-commons-docs/repository-query-return-types-reference.adoc[]
+link:https://docs.spring.io/spring-data/commons/reference/index.html[Spring Data Commons Documentation Reference]
+
+link:https://docs.spring.io/spring-framework/reference/[Spring Framework Documentation Overview]
 
 :leveloffset: -1

src/main/asciidoc/preface.adoc

@@ -7,11 +7,9 @@ This chapter provides some basic introduction to Spring and Aerospike, it explai
 
 [[get-started:first-steps:spring]]
 == Knowing Spring
-Spring Data uses Spring framework's https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/beans.html[IoC] container, https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/validation.html#core-convert[type conversion system], https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/expressions.html[expression language], https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/jmx.html[JMX integration], and portable https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar regardless of IoC container you choose to use.
+Spring Data uses Spring framework's https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/beans.html[IoC] container, https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/validation.html#core-convert[type conversion system], https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy] etc. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar regardless of IoC container you choose to use.
 
-The core functionality of the Aerospike support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like `JdbcTemplate` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of the Spring Data document, such as the repository support, you will need to configure some parts of the library using Spring.
-
-To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework https://docs.spring.io/spring-framework/reference/[documentation reference] for more information.
+To learn more about Spring, you can refer to the comprehensive documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework https://docs.spring.io/spring-framework/reference/[documentation reference] for more information.
 
 [[get-started:first-steps:nosql]]
 == Knowing NoSQL and Aerospike
@@ -28,7 +26,7 @@ The jumping off ground for learning about Aerospike is https://www.aerospike.com
 
 Spring Data Aerospike binaries require JDK level 17.0 and above.
 
-In terms of server, it is required to use  at least https://www.aerospike.com/download/server/[Aerospike server] version 5.2 (recommended to use the latest version when possible).
+In terms of server, it is required to use  at least https://www.aerospike.com/download/server/[Aerospike server] version 6.1 (recommended to use the latest version when possible).
 
 == Additional Help Resources
 

src/main/asciidoc/reference/aerospike-custom-converters.adoc

@@ -0,0 +1,55 @@
+[[aerospike.custom-converters]]
+= Aerospike Custom Converters
+
+Spring type converters are components used to convert data between different types, particularly when interacting with databases or binding data from external sources. They facilitate seamless transformation of data, such as converting between String and database-specific types (e.g., LocalDate to DATE or String to enumerations).
+
+For more details, see link:https://docs.spring.io/spring-framework/reference/core/validation/convert.html[Spring Type Conversion].
+
+Spring provides a set of default type converters for common conversions. Spring Data Aerospike has its own built-in converters in `DateConverters` and `AerospikeConverters` classes.
+
+However, in certain cases, custom converters are necessary to handle specific logic or custom serialization requirements. Custom converters allow developers to define precise conversion rules, ensuring data integrity and compatibility between application types and database representations.
+
+In order to add a custom converter you can leverage Spring's `Converter` SPI to implement type conversion logic and override `customConverters()` method available in `AerospikeDataConfigurationSupport`. Here is an example:
+
+[source,java]
+----
+public class BlockingTestConfig extends AbstractAerospikeDataConfiguration {
+
+    @Override
+    protected List<Object> customConverters() {
+        return List.of(
+            CompositeKey.CompositeKeyToStringConverter.INSTANCE,
+            CompositeKey.StringToCompositeKeyConverter.INSTANCE
+        );
+    }
+
+    @Value
+    public static class CompositeKey {
+
+        String firstPart;
+        long secondPart;
+
+        @WritingConverter
+        public enum CompositeKeyToStringConverter implements Converter<CompositeKey, String> {
+            INSTANCE;
+
+            @Override
+            public String convert(CompositeKey source) {
+                return source.firstPart + "::" + source.secondPart;
+            }
+        }
+
+        @ReadingConverter
+        public enum StringToCompositeKeyConverter implements Converter<String, CompositeKey> {
+            INSTANCE;
+
+            @Override
+            public CompositeKey convert(String source) {
+                String[] split = source.split("::");
+                return new CompositeKey(split[0], Long.parseLong(split[1]));
+            }
+        }
+    }
+}
+----
+

src/main/asciidoc/reference/aerospike-object-mapping.adoc

@@ -1,26 +1,30 @@
 [[aerospike.object-mapping]]
 = Aerospike Object Mapping
 
-Rich mapping support is provided by the `AerospikeMappingConverter`. `AerospikeMappingConverter` has a rich metadata model that provides a full feature set of functionality to map domain objects to Aerospike clusters and objects.The mapping metadata model is populated using annotations on your domain objects. However, the infrastructure is not limited to using annotations as the only source of metadata information. The `AerospikeMappingConverter` also allows you to map objects without providing any additional metadata, by following a set of conventions.
+Rich mapping support is provided by the `AerospikeMappingConverter` which has a rich metadata model that provides a full feature set of functionality to map domain objects to Aerospike objects. The mapping metadata model is populated using annotations on your domain objects.
+However, the infrastructure is not limited to using annotations as the only source of metadata information.
+The `AerospikeMappingConverter` also allows you to map objects without providing any additional metadata, by following a set of conventions.
 
 In this section, we will describe the features of the `AerospikeMappingConverter`, how to use conventions for mapping objects to documents and how to override those conventions with annotation-based mapping metadata.
 
-For more details refer to SpringData documentation:
-<<mapping.fundamentals, Object Mapping>>.
+For more details, refer to Spring Data documentation:
+link:https://docs.spring.io/spring-data/commons/reference/object-mapping.html[Object Mapping].
 
 [[mapping-conventions]]
 == Convention Based Mapping
 
-`AerospikeMappingConverter` has a few conventions for mapping objects to documents when no additional mapping metadata is provided. The conventions are:
+`AerospikeMappingConverter` has a few conventions for mapping objects to documents when no additional mapping metadata is provided.
+The conventions are:
 
 [[mapping-conventions-id-field]]
 === How the 'id' Field Is Handled in the Mapping Layer
 
-Aerospike DB requires that you have an `id` field for all objects. The `id` field can be of any primitive type as well as `String` or `byte[]`.
+Aerospike DB requires that you have an `id` field for all objects.
+The `id` field can be of any primitive type as well as `String` or `byte[]`.
 
 The following table outlines the requirements for the `id` field:
 
-[cols="1,2", options="header"]
+[cols="1,2",options="header"]
 .Examples for the translation of '_id'-field definitions
 |===
 | Field definition
@@ -29,49 +33,50 @@ The following table outlines the requirements for the `id` field:
 | `String` id
 | A field named 'id' without an annotation
 
-| `@Field` `String` id
+| `@Id` `String` myId
 | A field annotated with `@Id` (`org.springframework.data.annotation.Id`)
 
-| `@Id` `String` customNamedIdField
-
 |===
 
 The following description outlines what type of conversion, if any, will be done on the property mapped to the `id` document field:
 
 * By default, the type of the field annotated with `@id` is turned into a `String` to be stored in Aerospike database.
 If the original type cannot be persisted (see xref:#configuration.keep-original-key-types[keepOriginalKeyTypes]
-for details), it must be convertible to `String` and will be stored in the database as such,
-then converted back to the original type when the object is read. This is transparent to the application
-but needs to be considered if using external tools like `AQL` to view the data.
+for details), it must be convertible to `String` and will be stored in the database as such, then converted back to the original type when the object is read.
+This is transparent to the application but needs to be considered if using external tools like `AQL` and the Aerospike JDBC Driver to view the data.
 * If no field named "id" is present in the Java class then an implicit '_id' file will be generated by the driver but not mapped to a property or field of the Java class.
 
 When querying and updating `AerospikeTemplate` will use the converter to handle conversions of the `Query` and `Update` objects that correspond to the above rules for saving documents so field names and types used in your queries will be able to match what is in your domain classes.
 
 [[mapping-configuration]]
 == Mapping Configuration
 
-Unless explicitly configured, an instance of `AerospikeMappingConverter` is created by default when creating a `AerospikeTemplate`. You can create your own instance of the `MappingAerospikeConverter` so as to tell it where to scan the classpath at the startup of your domain classes in order to extract metadata and construct indexes.
+Unless explicitly configured, an instance of `AerospikeMappingConverter` is created by default when creating a `AerospikeTemplate`.
+You can create your own instance of the `MappingAerospikeConverter` so as to tell it where to scan the classpath at the startup of your domain classes in order to extract metadata and construct indexes.
 Also, to have more control over the conversion process (if needed), you can register converters to use for mapping specific classes to and from the database.
 
 NOTE: AbstractAerospikeConfiguration will create an AerospikeTemplate instance and register with the container under the name 'AerospikeTemplate'.
 
 [[mapping-usage-annotations]]
 === Mapping Annotation Overview
 
-The MappingAerospikeConverter can use metadata to drive the mapping of objects to documents using annotations. An overview of the annotations is provided below
+The MappingAerospikeConverter can use metadata to drive the mapping of objects to documents using annotations.
+An overview of the annotations is provided below
 
 * `@Id` - applied at the field level to mark the field used for identity purposes.
 * `@Field` - applied at the field level, describes the name of the field as it will be represented in the AerospikeDB BSON document thus allowing the name to be different from the field name of the class.
-* `@Version` - applied at the field level to mark record modification count. The value must be effectively integer.
+* `@Version` - applied at the field level to mark record modification count.
+The value must be effectively integer.
 In Spring Data Aerospike, documents come in two forms – non-versioned and versioned.
 Documents with an `@Version` annotation have a version field populated by the corresponding record’s generation count.
 Version can be passed to a constructor or not (in that case it stays equal to zero).
 * `@Expiration` - applied at the field level to mark a property to be used as expiration field.
-Expiration can be specified in two flavors: as an offset in seconds from the current time (then field value must be
-effectively integer) or as an absolute Unix timestamp. Client system time must be synchronized
-with Aerospike server system time, otherwise expiration behaviour will be unpredictable.
+Expiration can be specified in two flavors: as an offset in seconds from the current time (then field value must be effectively integer) or as an absolute Unix timestamp.
+Client system time must be synchronized with Aerospike server system time, otherwise expiration behaviour will be unpredictable.
 
-The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology-agnostic. Specific subclasses are used in the AerospikeDB support to support annotation-based metadata. Other strategies are also possible to put in place if there is demand.
+The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology-agnostic.
+Specific subclasses are used in the AerospikeDB support to support annotation-based metadata.
+Other strategies are also possible to put in place if there is demand.
 
 Here is an example of a more complex mapping.
 

src/main/asciidoc/reference/aerospike-projections.adoc

@@ -3,7 +3,7 @@
 
 Spring Data Aerospike supports Projections, a mechanism that allows you to fetch only relevant fields from Aerospike for a particular use case. This results in better performance, less network traffic, and a better understanding of what is required for the rest of the flow.
 
-For more details refer to SpringData documentation: <<projections, Projections>>.
+For more details, refer to Spring Data documentation: link:https://docs.spring.io/spring-data/rest/reference/data-commons/repositories/projections.html[Projections].
 
 For example, consider a Person class:
 

src/main/asciidoc/reference/aerospike-repositories.adoc

@@ -9,7 +9,7 @@ One of the main goals of the Spring Data is to significantly reduce the amount o
 One of the core interfaces of Spring Data is `Repository`.
 This interface acts primarily to capture the types to work with and to help user to discover interfaces that extend Repository.
 
-In other words, it allows user to have basic and complicated queries without writing the implementation. This builds on the <<repositories, Core SpringData Repository Support>>, so make sure you've got a sound understanding of this concept.
+In other words, it allows user to have basic and complicated queries without writing the implementation. This builds on the link:https://docs.spring.io/spring-data/rest/reference/data-commons/repositories.html[Core Spring Data Repository Support], so make sure you've got a sound understanding of this concept.
 
 [[aerospike-repo-usage]]
 == Usage