FMWK-193 Merge SpringDataCommons documentation

src/main/asciidoc/index.adoc

@@ -1,54 +1,57 @@
-= Spring Data Aerospike - Reference Documentation
+= Spring Data Aerospike - Documentation
+:doctype: book
 :revnumber: 4.3.0
 :revdate: {localdate}
 :toc:
 :toc-placement!:
-:spring-data-commons-docs: https://github.com/spring-projects/spring-data-commons/tree/main/src/main/asciidoc
+:toclevels: 1
+:spring-data-commons-docs-online: https://docs.spring.io/spring-data/commons/docs/current/reference/html
 
 (C) 2018-2023 The original authors.
 
 NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
 
 toc::[]
 
+:leveloffset: +1
+
 include::preface.adoc[]
 
+:leveloffset: -1
+
 [[reference-documentation]]
-== Reference documentation
+= Reference documentation
 
 :leveloffset: +1
 
 include::reference/introduction.adoc[]
 include::reference/aerospike.adoc[]
-include::reference/mapping.adoc[]
+include::reference/getting-started.adoc[]
+include::spring-data-commons-docs/repositories.adoc[]
 include::reference/aerospike-repositories.adoc[]
 include::reference/aerospike-reactive-repositories.adoc[]
-include::reference/template.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.adoc[]
-include::reference/projections.adoc[]
+include::spring-data-commons-docs/object-mapping.adoc[]
+include::reference/aerospike-object-mapping.adoc[]
+include::reference/template.adoc[]
 include::reference/secondary-indexes.adoc[]
 include::reference/caching.adoc[]
-include::reference/getting-started.adoc[]
+include::spring-data-commons-docs/dependencies.adoc[]
+include::spring-data-commons-docs/auditing.adoc[]
 
 :leveloffset: -1
 
 [[appendix]]
-== Appendix
+= Appendix
 
 :leveloffset: +1
 
-General SpringData information:
-
-include::{spring-data-commons-docs}/dependencies.adoc[]
-
-include::{spring-data-commons-docs}/repositories.adoc[]
-
-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[]
+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[]
 
 :leveloffset: -1

src/main/asciidoc/preface.adoc

@@ -1,5 +1,5 @@
 [[preface]]
-== Preface
+= Preface
 
 The Spring Data Aerospike project applies core Spring concepts and provides interface for using Aerospike key-value style data store.  We provide a "repository" and a "template" as high-level abstractions for storing and querying data. You will notice similarities to the JDBC support in the Spring Framework.
 
@@ -35,19 +35,19 @@ In terms of server, https://www.aerospike.com/download/server/[Aerospike] versio
 Learning a new framework is not always straightforward. In this section, we try to provide what we think is an easy-to-follow guide for starting with Spring Data Aerospike module. However, if you encounter issues, or you are just looking for advice, feel free to use one of the links below:
 
 [[get-started:help]]
-=== Support
+== Support
 
 There are a few support options available:
 
 [[get-started:help:community]]
-==== Questions & Answers
+=== Questions & Answers
 
 Developers post questions and answers on Stack Overflow. The two key tags to search for related answers to this project are:
 
 * https://stackoverflow.com/questions/tagged/spring-data[spring-data]
 * https://stackoverflow.com/questions/tagged/spring-data-aerospike[spring-data-aerospike]
 
 [[get-started:up-to-date]]
-==== Following Development
+=== Following Development
 
 If you encounter a bug or want to suggest an improvement, please create an https://github.com/aerospike/spring-data-aerospike/issues[issue on GitHub].

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

@@ -1,20 +1,21 @@
 [[mapping-chapter]]
-= 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.
 
 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.
 
-include::{spring-data-commons-docs}/object-mapping.adoc[leveloffset=+1]
+For more details refer to SpringData documentation:
+<<mapping.fundamentals, Object Mapping>>.
 
 [[mapping-conventions]]
-== Convention based Mapping
+== Convention Based Mapping
 
 `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
+=== How the '_id' Field Is Handled in the Mapping Layer
 
 AerospikeDB requires that you have an '_id' field for all objects. If you don't provide one the driver will assign a ObjectId with a generated value. The "_id" field can be of any type, other than arrays, so long as it is unique. The driver naturally supports all primitive types and Dates. When using the `AerospikeMappingConverter` there are certain rules that govern how properties from the Java class are mapped to this '_id' field.
 
@@ -59,12 +60,10 @@ When querying and updating `AerospikeTemplate` will use the converter to handle
 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.
 
-include::{spring-data-commons-docs}/custom-conversions.adoc[leveloffset=+3]
-
 NOTE: AbstractAerospikeConfiguration will create an AerospikeTemplate instance and register with the container under the name 'AerospikeTemplate'.
 
 [[mapping-usage-annotations]]
-=== Mapping annotation overview
+=== Mapping Annotation Overview
 
 The MappingAerospikeConverter can use metadata to drive the mapping of objects to documents. An overview of the annotations is provided below
 
@@ -121,4 +120,5 @@ public class Person<T extends Address> {
   }
 
 // other getters/setters omitted
+}
 ----

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

@@ -1,8 +1,9 @@
+[[aerospike.projections]]
 = Projections with Aerospike
 
 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.
 
-include::{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2]
+For more details refer to SpringData documentation: <<projections, Projections>>.
 
 For example, consider a Person class:
 

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

@@ -4,7 +4,7 @@
 [[aerospike-repo-intro]]
 == Introduction
 
-This chapter will point out the specialties for repository support for Aerospike. This builds on the https://docs.spring.io/spring-data/data-commons/docs/1.6.1.RELEASE/reference/html/repositories.html[core SpringData repository support], so make sure you've got a sound understanding of the basic concepts explained there.
+This chapter will point out the specialties for repository support for Aerospike. This builds on the <<repositories, Core SpringData Repository Support>>, so make sure you've got a sound understanding of the basic concepts explained there.
 
 [[aerospike-repo-usage]]
 == Usage
@@ -159,6 +159,7 @@ public class RepositoryExample {
 	AerospikeOperations aerospikeOperations;
 	@Autowired
 	AerospikeClient client;
+
 	/**
 	 * @param ctx
 	 */
@@ -167,9 +168,7 @@ public class RepositoryExample {
 		repository = (PersonRepository) ctx.getBean("personRepository");
 		client = ctx.getBean(AerospikeClient.class);
 	}
-	/**
-	 * @param args
-	 */
+
 	protected void setUp() {
 		repository.deleteAll();
 		Person dave = new Person("Dave-01", "Matthews", 42);
@@ -187,15 +186,10 @@ public class RepositoryExample {
 				dave, donny, carter, boyd, stefan, leroi, leroi2, alicia));
 	}
 
-	/**
-	 * @param args
-	 */
 	protected void cleanUp() {
 		repository.deleteAll();
 	}
-	/**
-	 * 
-	 */
+
 	protected void executeRepositoryCall() {
 		List<Person> result = repository.findByName("Beauford");
 		System.out.println("Results for exact match of 'Beauford'");
@@ -208,8 +202,8 @@ public class RepositoryExample {
 			System.out.println(person.toString());
 		}
 	}
-	public static void main(String[] args) {
 
+	public static void main(String[] args) {
 		ApplicationContext ctx = new AnnotationConfigApplicationContext(
 				TestRepositoryConfig.class);
 		RepositoryExample repositoryExample = new RepositoryExample(ctx);

src/main/asciidoc/reference/aerospike.adoc

@@ -1,7 +1,7 @@
 [[aerospike.functionality]]
-= Aerospike Support
+= Aerospike Functionality
 
-Aerospike support contains a wide range of features summarized below:
+Aerospike supports a wide range of features summarized below:
 
 * Feature Rich Object Mapping integrated with Spring's Conversion Service
 * Automatic implementation of Repository interfaces including support for custom finder methods
@@ -14,7 +14,7 @@ Aerospike support contains a wide range of features summarized below:
 
 Spring Data Aerospike uses Java Client, Aerospike’s Java client enables you to build applications in Java that store and retrieve data from an Aerospike cluster. It contains both synchronous and asynchronous calls to the database.
 
-The Java Client runs on any platform with Java 1.6 version and above.
+The Java Client runs on any platform with Java 1.8 version and above.
 
 First, you need to set up a running Aerospike server.
 
@@ -100,14 +100,14 @@ public class Person {
 	 public final int age;
 
 	 public Person(String id, String name, int age) {
-	  this.id = id;
-	  this.name = name;
-	  this.age = age;
+            this.id = id;
+            this.name = name;
+            this.age = age;
 	 }
 
 	 @Override
 	 public String toString() {
-	  return "Person [id=" + id + ", name=" + name + ", age=" + age + "]";
+            return "Person [id=" + id + ", name=" + name + ", age=" + age + "]";
 	 }
 }
 ----