GH-2562 - Restructure documentation.

Especially pull up the parts explaining the differences between SDN6 and SDN+OGM, make the FAQ more visible and have only one appendix in one place.

Closes #2562.

pom.xml

@@ -744,25 +744,13 @@
 								<version>${asciidoctorj-diagram.version}</version>
 							</dependency>
 						</dependencies>
-						<configuration>
-							<backend>html</backend>
-							<doctype>book</doctype>
-							<imagesDir>img</imagesDir>
-							<sourceDirectory>${project.basedir}/src/main/asciidoc</sourceDirectory>
-							<sourceDocumentName>index.adoc</sourceDocumentName>
-							<sourceHighlighter>coderay</sourceHighlighter>
+						<configuration combine.self="append">
 							<attributes>
-								<icons>font</icons>
-								<toc>left</toc>
-								<setanchors/>
-								<idprefix/>
-								<idseparator/>
 								<spring-data-commons-docs>${spring-data-commons-docs.dir}</spring-data-commons-docs>
 							</attributes>
 							<requires>
 								<require>asciidoctor-diagram</require>
 							</requires>
-							<outputDirectory>${project.build.docs}</outputDirectory>
 						</configuration>
 					</plugin>
 					<plugin>

src/main/asciidoc/appendix/conversions.adoc

@@ -1,6 +1,9 @@
 [[conversions]]
 = Conversions
 
+[[build-in.conversions]]
+== Built-in conversions
+
 We support a broad range of conversions out of the box.
 Find the list of supported cypher types in the official drivers manual: https://neo4j.com/docs/driver-manual/current/cypher-values/[Working with Cypher values].
 

src/main/asciidoc/appendix/index.adoc

@@ -1,9 +1,7 @@
-:leveloffset: +1
-
 [[sdn-appendix]]
-= Spring Data Neo4j Appendix
+[appendix]
+= Spring Data Neo4j
 
-:numbered!:
 :leveloffset: +1
 
 include::conversions.adoc[]
@@ -21,4 +19,3 @@ include::migrating.adoc[]
 include::build.adoc[]
 
 :leveloffset: -1
-:leveloffset: -1

src/main/asciidoc/appendix/migrating.adoc

@@ -125,7 +125,7 @@ You're then ready to replace annotations:
 |No replacement, not needed
 
 |`org.springframework.data.neo4j.annotation.QueryResult`
-|Use <<projections.sdn, projections>>; arbitrary result mapping not supported anymore
+|Use <<projections, projections>>; arbitrary result mapping not supported anymore
 
 |===
 

src/main/asciidoc/index.adoc

@@ -62,12 +62,16 @@ include::testing/index.adoc[]
 
 include::{spring-data-commons-docs}/auditing.adoc[leveloffset=+1]
 
-include::faq/index.adoc[]
+[[faq]]
+= Frequently Asked Questions
 
-include::appendix/index.adoc[]
+:numbered!:
+include::faq/index.adoc[]
 
 [[appendix]]
 = Appendix
+
 :numbered!:
+include::appendix/index.adoc[leveloffset=+1]
 include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1]
 include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1]

src/main/asciidoc/introduction-and-preface/building-blocks.adoc

@@ -1,5 +1,5 @@
 [[building-blocks]]
-= Building blocks
+= Building blocks of Spring Data Neo4j
 
 == Overview
 

src/main/asciidoc/introduction-and-preface/index.adoc

@@ -1,5 +1,9 @@
 include::introduction.adoc[leveloffset=+1]
 
-include::preface.adoc[leveloffset=+1]
+include::preface-neo4j.adoc[leveloffset=+1]
+
+include::preface-sd.adoc[leveloffset=+1]
+
+include::preface-sdn.adoc[leveloffset=+1]
 
 include::building-blocks.adoc[leveloffset=+1]

src/main/asciidoc/introduction-and-preface/introduction.adoc

@@ -1,6 +1,22 @@
 [[introduction]]
 = Your way through this document
 
+This documentation tries to bridge between a broad spectrum of possible users:
+
+* People new to all the Spring ecosystem, including Spring Framework, Spring Data, the concrete module (in this case Spring Data Neo4j)
+and Neo4j.
+* Experienced Neo4j developers that are new to Spring Data and want to make best use of their Neo4j knowledge but are unfamiliar
+with declarative transactions for example and how to incorporate the latter with Neo4j cluster requirements.
+* Experienced Spring Data developers who are new to this specific module and Neo4j and need to learn how the building blocks
+interact together. While the programming paradigm of this module is very much in line with Spring Data JDBC, Mongo and others,
+the query language (Cypher), transactional and clustering behaviour is different and can't be abstracted away.
+
+Here's how we address those different needs:
+
+A lot of Neo4j specific questions can be found in the <<faq, Frequently Asked Questions>>. These questions are
+particular relevant for people who well aware of Neo4j specific requirements and want to know how to address them
+with Spring Data Neo4j.
+
 If you are already familiar with the core concepts of Spring Data, head straight to <<getting-started>>.
 This chapter will walk you through different options of configuring an application to connect to a Neo4j instance and how to model your domain.
 
@@ -12,7 +28,10 @@ Choices are Neo4j repositories, the Neo4j Template or on a lower level, the Neo4
 All of them are available in a reactive fashion as well.
 Apart from the paging mechanism, all the features of standard repositories are available in the reactive variant.
 
-You will find the building blocks in the next <<building-blocks,chapter>>.
+If you come from older versions of Spring Data Neo4j - which are usually abbreviated SDN+OGM or SDN5 -
+you will most likely be interested in the <<preface.sdn, introduction to SDN>> and especially in the relationship
+<<faq.sdn-related-to-ogm, between SDN+OGM and the current SDN>>. In the same chapter, you will find out about the
+<<building-blocks, building blocks>> of SDN6.
 
 To learn more about the general concepts of repositories, head over to <<repositories>>.
 

src/main/asciidoc/introduction-and-preface/preface-neo4j.adoc

@@ -0,0 +1,25 @@
+[[preface.neo4j]]
+= Introducing Neo4j
+
+A graph database is a storage engine that specializes in storing and retrieving vast networks of information.
+It efficiently stores data as nodes with relationships to other or even the same nodes, thus allowing high-performance retrieval and querying of those structures.
+Properties can be added to both nodes and relationships.
+Nodes can be labelled by zero or more labels, relationships are always directed and named.
+
+Graph databases are well suited for storing most kinds of domain models.
+In almost all domains, there are certain things connected to other things.
+In most other modeling approaches, the relationships between things are reduced to a single link without identity and attributes.
+Graph databases allow to keep the rich relationships that originate from the domain equally well-represented in the database without resorting to also modeling the relationships as "things".
+There is very little "impedance mismatch" when putting real-life domains into a graph database.
+
+https://neo4j.com/[Neo4j] is an open source NoSQL graph database.
+It is a fully transactional database (ACID) that stores data structured as graphs consisting of nodes, connected by relationships.
+Inspired by the structure of the real world, it allows for high query performance on complex data, while remaining intuitive and simple for the developer.
+
+The starting point for learning about Neo4j is https://neo4j.com/[neo4j.com].
+Here is a list of useful resources:
+
+* The https://neo4j.com/docs/[Neo4j documentation] introduces Neo4j and contains links to getting started guides, reference documentation and tutorials.
+* The https://neo4j.com/sandbox/[online sandbox] provides a convenient way to interact with a Neo4j instance in combination with the online https://neo4j.com/developer/get-started/[tutorial].
+* Neo4j https://neo4j.com/developer/java/[Java Bolt Driver]
+* Several https://neo4j.com/books/[books] available for purchase and https://www.youtube.com/neo4j[videos] to watch.

src/main/asciidoc/introduction-and-preface/preface-sd.adoc

@@ -0,0 +1,17 @@
+[[preface.spring-data]]
+= Introducing Spring Data
+
+Spring Data uses Spring Framework's {spring-framework-ref}/core.html[core] functionality, such as the {spring-framework-ref}/core.html#beans[IoC] container,
+{spring-framework-ref}/core.html#core-convert[type conversion system],
+{spring-framework-ref}/core.html#expressions[expression language],
+{spring-framework-ref}/integration.html#jmx[JMX integration], and portable {spring-framework-ref}/data-access.html#dao-exceptions[DAO exception hierarchy].
+While it is not necessary to know all the Spring APIs, understanding the concepts behind them is.
+At a minimum, the idea behind IoC should be familiar.
+
+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://spring.io/docs[home page ] for more information.
+
+The beauty of Spring Data is that it applies the same programming model to a variety of different stores, such as JPA, JDBC
+Mongo and others. For that reason, parts of the general Spring Data documentations are included in this document, especially the
+general chapter about <<repositories, working with Spring Data repositories>>. Make sure to have a look at that if you haven't
+worked with a Spring Data module in the past.

src/main/asciidoc/introduction-and-preface/preface-sdn.adoc

@@ -0,0 +1,46 @@
+[[preface.sdn]]
+= Introducing Spring Data Neo4j
+
+Spring Data Neo4j or in short SDN is the next-generation https://spring.io/projects/spring-data[Spring Data] module, created and maintained by https://neo4j.com[Neo4j, Inc.] in close collaboration with https://www.vmware.com/[VMware's] Spring Data Team.
+It supports all officially supported releases of Neo4j, including Neo4j AuraDB.
+The Spring Data Neo4j project applies aforementioned Spring Data concepts to the development of solutions using the Neo4j graph data store.
+
+SDN relies completely on the https://github.com/neo4j/neo4j-java-driver[Neo4j Java Driver], without introducing another "driver" or "transport" layer between the mapping framework and the driver. The Neo4j Java Driver - sometimes dubbed Bolt or the Bolt driver - is used as a protocol much like JDBC is with relational databases.
+
+SDN is an Object-Graph-Mapping (OGM) library.
+An OGM maps nodes and relationships in the graph to objects and references in a domain model.
+Object instances are mapped to nodes while object references are mapped using relationships, or serialized to properties (e.g. references to a Date).
+JVM primitives are mapped to node or relationship properties.
+An OGM abstracts the database and provides a convenient way to persist your domain model in the graph and query it without having to use low level drivers directly.
+It also provides the flexibility to the developer to supply custom queries where the queries generated by SDN are insufficient.
+
+SDN is the *official successor* to prior SDN version 5, to which this documentation refers as SDN+OGM.
+SDN version 5 used a separate object mapping framework, much in the way Spring Data JPA relates to JPA.
+That separate layer aka Neo4j-OGM (Neo4j Object Graph Mapper) is now contained in this module itself.
+Spring Data Neo4j itself is an object mapper, dedicated to be used in Spring and Spring Boot applications and in some supported Jakarta EE environments.
+It does not require or support a separate implementation of an object mapper.
+
+Noteworthy features that differentiate the current SDN version from prior SDN+OGM are
+
+* SDN is a complete OGM on its own
+* Full support for immutable entities and thus full support for Kotlin's data classes
+* Full support for the reactive programming model in the Spring Framework itself and Spring Data
+* Neo4j client and reactive client feature, resurrecting the idea of a template over the plain driver, easing database access
+
+We provide _repositories_ as a high-level abstraction for storing and querying documents as well as templates and clients for generic domain access or generic query execution.
+All of them are integrated with Spring's application transactions.
+
+The core functionality of the Neo4j support can be used directly, through either the `Neo4jClient` or the `Neo4jTemplate` or the reactive variants thereof.
+All of them provide integration with Spring's application level transactions.
+On a lower level, you can grab the Bolt driver instance, but than you have to manage your own transactions in these cases.
+
+NOTE: You still can use Neo4j-OGM, even in modern Spring Boot applications.
+      But you *cannot* use it with SDN 6.
+      If you tried you would have two different sets of entities in two different - and unrelated - persistence context.
+      Hence, if you want to stick to Neo4j-OGM 3.2.x, you would use the Java driver instantiated by Spring Boot and pass it onto a Neo4j-OGM session.
+      Neo4j-OGM 3.2.x is still supported, and we recommend its use in frameworks such as Quarkus.
+      In a Spring Boot application however your primary choice should be SDN 6.
+
+Please make sure you read the <<faq, Frequently Asked Questions>> where we address many reoccurring questions about our mapping decisions but also how interaction with Neo4j cluster instances such as https://neo4j.com/cloud/platform/aura-graph-database/[Neo4j AuraDB] and on-premise cluster deployments can be significantly improved.
+
+Concepts that are important to understand are Neo4j Bookmarks, https://medium.com/neo4j/try-and-then-retry-there-can-be-failure-30bf336383da[the potential need] for incorporating a proper retry mechanism such as https://github.com/spring-projects/spring-retry[Spring Retry] or https://github.com/resilience4j/resilience4j[Resilience4j] (we recommend the latter, as this knowledge is applicable outside Spring, too) and the importance of read-only vs write queries in the context of Neo4j cluster.

src/main/asciidoc/introduction-and-preface/preface.adoc

@@ -1,148 +0,0 @@
-[[preface.nosql]]
-= NoSQL and Graph databases
-
-A graph database is a storage engine that specializes in storing and retrieving vast networks of information.
-It efficiently stores data as nodes with relationships to other or even the same nodes, thus allowing high-performance retrieval and querying of those structures.
-Properties can be added to both nodes and relationships.
-Nodes can be labelled by zero or more labels, relationships are always directed and named.
-
-Graph databases are well suited for storing most kinds of domain models.
-In almost all domains, there are certain things connected to other things.
-In most other modeling approaches, the relationships between things are reduced to a single link without identity and attributes.
-Graph databases allow to keep the rich relationships that originate from the domain equally well-represented in the database without resorting to also modeling the relationships as "things".
-There is very little "impedance mismatch" when putting real-life domains into a graph database.
-
-[[preface.nosql.neo4j]]
-== Introducing Neo4j
-
-https://neo4j.com/[Neo4j] is an open source NoSQL graph database.
-It is a fully transactional database (ACID) that stores data structured as graphs consisting of nodes, connected by relationships.
-Inspired by the structure of the real world, it allows for high query performance on complex data, while remaining intuitive and simple for the developer.
-
-The starting point for learning about Neo4j is https://neo4j.com/[neo4j.com].
-Here is a list of useful resources:
-
-* The https://neo4j.com/docs/[Neo4j documentation] introduces Neo4j and contains links to getting started guides, reference documentation and tutorials.
-* The https://neo4j.com/sandbox/[online sandbox] provides a convenient way to interact with a Neo4j instance in combination with the online https://neo4j.com/developer/get-started/[tutorial].
-* Neo4j https://neo4j.com/developer/java/[Java Bolt Driver]
-* Several https://neo4j.com/books/[books] available for purchase and https://www.youtube.com/neo4j[videos] to watch.
-
-[[preface.spring-data]]
-== Spring and Spring Data
-
-Spring Data uses Spring Framework's {spring-framework-ref}/core.html[core] functionality, such as the {spring-framework-ref}/core.html#beans[IoC] container,
-{spring-framework-ref}/core.html#core-convert[type conversion system],
-{spring-framework-ref}/core.html#expressions[expression language],
-{spring-framework-ref}/integration.html#jmx[JMX integration], and portable {spring-framework-ref}/data-access.html#dao-exceptions[DAO exception hierarchy].
-While it is not necessary to know all the Spring APIs, understanding the concepts behind them is.
-At a minimum, the idea behind IoC should be familiar.
-
-The Spring Data Neo4j project applies Spring Data concepts to the development of solutions using the Neo4j graph data store.
-We provide _repositories_ as a high-level abstraction for storing and querying documents as well as templates and clients for generic domain access or generic query execution.
-All of them are integrated with Spring's application transactions.
-
-The core functionality of the Neo4j support can be used directly, through either the `Neo4jClient` or the `Neo4jTemplate` or the reactive variants thereof.
-All of them provide integration with Spring's application level transactions.
-On a lower level, you can grab the Bolt driver instance, but than you have to manage your own transactions.
-
-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://spring.io/docs[home page ] for more information.
-
-This documentation tries to bridge between a broad spectrum of possible users:
-
-* People new to all the Spring ecosystem, including Spring Framework, Spring Data, the concrete module (in this case Spring Data Neo4j)
-  and Neo4j.
-* Experienced Neo4j developers that are new to Spring Data and want to make best use of their Neo4j knowledge but are unfamiliar
-  with declarative transactions for example and how to incorporate the latter with Neo4j cluster requirements.
-* Experienced Spring Data developers who are new to this specific module and Neo4j and need to learn how the building blocks
-  interact together. While the programming paradigm of this module is very much in line with Spring Data JDBC, Mongo and others,
-  the query language (Cypher), transactional and clustering behaviour is different and can't be abstracted away.
-
-We decided to move a lot of Neo4j specific questions into the <<faq, Frequently Asked Questions>>.
-
-
-[[what-is-sdn]]
-== What is Spring Data Neo4j
-
-The current Spring Data Neo4j is the successor to Spring Data Neo4j + Neo4j-OGM.
-The separate layer of Neo4j-OGM (Neo4j Object Graph Mapper) has been replaced by Spring infrastructure, but the basic concepts of an Object Graph Mapper (OGM) still apply.
-
-An OGM maps nodes and relationships in the graph to objects and references in a domain model.
-Object instances are mapped to nodes while object references are mapped using relationships, or serialized to properties (e.g. references to a Date).
-JVM primitives are mapped to node or relationship properties.
-An OGM abstracts the database and provides a convenient way to persist your domain model in the graph and query it without having to use low level drivers directly.
-It also provides the flexibility to the developer to supply custom queries where the queries generated by SDN are insufficient.
-
-TIP: Please make sure you read the <<faq, Frequently Asked Questions>> where we address many reoccurring questions about our
-     mapping decisions but also how interaction with Neo4j cluster instances such as https://neo4j.com/cloud/platform/aura-graph-database/[Neo4j AuraDB]
-     and on-premise cluster deployments can be significantly improved.
-     +
-     Concepts that are important to understand are Neo4j Bookmarks, https://medium.com/neo4j/try-and-then-retry-there-can-be-failure-30bf336383da[the potential need]
-     for incorporating a proper retry mechanism such as https://github.com/spring-projects/spring-retry[Spring Retry] or
-     https://github.com/resilience4j/resilience4j[Resilience4j] (we recommend the latter, as this knowledge is applicable outside
-     Spring, too) and the importance of read-only vs write queries in the context of Neo4j cluster.
-
-
-[[what-is-in-the-box-sdn]]
-=== What's in the box?
-
-Spring Data Neo4j or in short SDN is a next-generation https://spring.io/projects/spring-data[Spring Data] module, created and maintained by https://neo4j.com[Neo4j, Inc.] in close collaboration with https://www.vmware.com/[VMware's] Spring Data Team.
-
-SDN relies completely on the https://github.com/neo4j/neo4j-java-driver[Neo4j Java Driver], without introducing another "driver" or "transport" layer between the mapping framework and the driver.
-The Neo4j Java Driver - sometimes dubbed Bolt or the Bolt driver - is used as a protocol much like JDBC is with relational databases.
-
-Noteworthy features that differentiate the new SDN from Spring Data Neo4j + OGM are
-
-* Full support for immutable entities and thus full support for Kotlin's data classes
-* Full support for the reactive programming model in the Spring Framework itself and Spring Data
-* Brand new Neo4j client and reactive client feature, resurrecting the idea of a template over the plain driver, easing database access
-
-[[why-should-you-favor-sdn]]
-=== Why should I use SDN in favor of SDN+OGM
-
-SDN has several features not present in SDN+OGM, notably
-
-* Full support for Springs reactive story, including reactive transaction
-* Full support for https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#query-by-example[Query By Example]
-* Full support for fully immutable entities
-* Support for all modifiers and variations of derived finder methods, including spatial queries
-
-[[sdn-related-to-ogm]]
-=== How does SDN relate to Neo4j-OGM?
-
-https://neo4j.com/docs/ogm-manual/current/[Neo4j-OGM] is an Object Graph Mapping library, which is mainly used by previous versions of Spring Data Neo4j as its backend for the heavy lifting of mapping nodes and relationships into domain object.
-The current SDN *does not need* and *does not support* Neo4j-OGM.
-SDN uses Spring Data's mapping context exclusively for scanning classes and building the meta model.
-
-While this pins SDN to the Spring ecosystem, it has several advantages, among them the smaller footprint regarding CPU and memory usage and especially, all the features of Spring's mapping context.
-
-[[sdn-and-http-support]]
-=== Does SDN support connections over HTTP to Neo4j?
-
-No.
-
-[[sdn-and-embedded-support]]
-=== Does SDN support embedded Neo4j?
-
-Embedded Neo4j has multiple facets to it:
-
-[[sdn-and-embedded-instances-support]]
-==== Does SDN provide an embedded instance for your application?
-
-No.
-
-[[sdn-interact-with-embedded-instances]]
-==== Does SDN interact directly with an embedded instance?
-
-No.
-An embedded database is usually represented by an instance of `org.neo4j.graphdb.GraphDatabaseService` and has no Bolt connector out of the box.
-
-SDN can however work very much with Neo4j's test harness, the test harness is specially meant to be a drop-in replacement for the real database.
-Support for both Neo4j 3.5 and 4.x test harness is implemented via link:{java-driver-starter-href}[the Spring Boot starter for the driver].
-Have a look at the corresponding module `org.neo4j.driver:neo4j-java-driver-test-harness-spring-boot-autoconfigure`.
-
-[[sdn-without-spring-boot]]
-==== Can I use SDN without Spring Boot?
-
-Yes, see our `README`.
-We provide `org.springframework.data.neo4j.config.AbstractNeo4jConfig` and `org.springframework.data.neo4j.config.AbstractReactiveNeo4jConfig` for that purpose.

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

@@ -288,7 +288,7 @@ On the other hand, we want to be able to pull all people from the database witho
 Please consider your application's use case before you try to map every relationship in your database in every direction.
 While you can do this, you may end up rebuilding a graph database inside your object graph and this is not the intention of a mapping framework.
 If you have to model your circular or bidirectional domain and don't want to fetch the whole graph,
-you can define a fine-grained description of the data that you want to fetch by using <<projections.sdn, projections>>.
+you can define a fine-grained description of the data that you want to fetch by using <<projections, projections>>.
 
 [[mapping.id-handling]]
 == Handling and provisioning of unique IDs

src/main/asciidoc/object-mapping/projections.adoc

@@ -1,4 +1,4 @@
-[[projections.sdn]]
+[[projections]]
 = Projections
 
 [[projections.sdn.general-remarks]]