Add Collections to Reference Documentation. (#1296)

Closes #1295.

Author: mikereiche

src/main/asciidoc/collections.adoc

@@ -0,0 +1,80 @@
+[[couchbase.collections]]
+= Collection Support
+
+Couchbase supports https://docs.couchbase.com/server/current/learn/data/scopes-and-collections.html[Scopes and Collections]. This section documents on how to use it with Spring Data Couchbase.
+
+The https://github.com/couchbaselabs/try-cb-spring[try-cb-spring] sample application is a working example of using Scopes and Collections in Spring Data Couchbase.
+
+The 2021 Couchbase Connect presentation on Collections in Spring Data can be found at https://www.youtube.com/watch?v=MrplTeEFItk[Presentation Only] and https://web.cvent.com/hub/events/1dce8283-986d-4de9-8368-94c98f60df01/sessions/9ee89a85-833c-4e0c-81b0-807864fa351b?goBackHref=%2Fevents%2F1dce8283-986d-4de9-8368-94c98f60df01%2Fsessions&goBackName=Add%2FView+Sessions&goBackTab=all[Presentation with Slide Deck]
+
+== Requirements
+
+ - Couchbase Server 7.0 or above.
+ - Spring Data Couchbase 4.3.1 or above.
+
+== Getting Started & Configuration
+
+
+=== Scope and Collection Specification
+There are several mechanisms of specifying scopes and collections, and these may be combined, or one mechanism may override another. 
+First some definitions for scopes and collections. An unspecified scope indicates that the default scope is to be used, likewise, an 
+unspecified collection indicates that the default collection is to be used.
+There are only three combinations of scopes and collections that are valid. (1) the default scope and the default collection; (2) the default
+scope and a non-default collection; and (3) a non-default scope and a non-default collection. It is not possible to have a non-default 
+scope and a default collection as non-default scopes do not contain a default collections, neither can one be created.
+
+A scope can be specified in the configuration:
+[source,java]
+----
+@Configuration
+static class Config extends AbstractCouchbaseConfiguration {
+
+    // Usual Setup
+    @Override public String getConnectionString() { /* ... */ }
+
+    // optionally specify the scope in the Configuration
+    @Override
+    protected String getScopeName() {
+        return "myScope"; // or a variable etc.;
+    }
+
+}
+----
+Scopes and Collections can be specified as annotations on entity classes and repositories:
+[source,java]
+----
+@Document
+@Scope("travel")
+@Collection("airport")
+public class Airport {...
+----
+
+[source,java]
+----
+@Scope("travel")
+@Collection("airport")
+public interface AirportRepository extends CouchbaseRepository<Airport, String> ...
+----
+
+Scopes and Collections can be specified on templates using the inScope(scopeName) and inCollection(collectionName) fluent APIs:
+[source,java]
+----
+List<Airport> airports = template.findByQuery(Airport.class).inScope("archived").all()
+----
+
+Scopes and Collections can be specified on repositories that extend DynamicProxyable using the withScope(scopeName) and withCollection(collectionName) APIs:
+[source,java]
+----
+public interface AirportRepository extends CouchbaseRepository<Airport, String>, DynamicProxyable<AirportRepository>{...}
+...
+List<Airport> airports = airportRepository.withScope("archived").findByName(iata);  
+----
+
+.The order of precedence is:
+. inScope()/inCollection() of the template fluent api
+. withScope()/withCollection() of the template/repository object
+. annotation of the repository method
+. annotation of the repository interface
+. annotation of the entity object
+. getScope() of the configuration
+

src/main/asciidoc/index.adoc

@@ -1,10 +1,10 @@
 = Spring Data Couchbase - Reference Documentation
-Michael Nitschinger, Oliver Gierke, Simon Baslé
+Michael Nitschinger, Oliver Gierke, Simon Baslé, Michael Reiche
 :revnumber: {version}
 :revdate: {localdate}
 :spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
 
-(C) 2014-2019 The original author(s).
+(C) 2014-2022 The original author(s).
 
 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.
 
@@ -24,8 +24,8 @@ include::repository.adoc[]
 include::reactiverepository.adoc[]
 include::template.adoc[]
 include::transactions.adoc[]
-// (daschl) disabled the ansijoins docs since it is being overhauled for 4.x
-// include::ansijoins.adoc[]
+include::collections.adoc[]
+include::ansijoins.adoc[]
 :leveloffset: -1
 
 [[appendix]]