diff --git a/.gitignore b/.gitignore index adadb46a..5006394a 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,9 @@ target/ *.iml .idea + +build/ +node_modules +node +package.json +package-lock.json diff --git a/README.adoc b/README.adoc index 85d487ae..ede33955 100644 --- a/README.adoc +++ b/README.adoc @@ -1,5 +1,3 @@ -image:https://spring.io/badges/spring-data-couchbase/ga.svg[Spring Data Couchbase,link=https://projects.spring.io/spring-data-couchbase#quick-start] image:https://spring.io/badges/spring-data-couchbase/snapshot.svg[Spring Data Couchbase,link=https://projects.spring.io/spring-data-couchbase#quick-start] - = Spring Data Couchbase image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-couchbase%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-couchbase/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]] The primary goal of the https://www.springsource.org/spring-data[Spring Data] project is to make it easier to build @@ -32,16 +30,15 @@ This project is lead and maintained by Couchbase, Inc. == Version compatibility -`Spring-Data Couchbase 3.0.x` is the Spring Data connector for the `Couchbase Java SDK 2.x` generation. +`Spring-Data Couchbase` is the Spring Data connector for the `Couchbase Java SDK 2.x` generation. -Both the SDK and this Spring Data community project are major version changes with lots of differences from their -respective previous versions. +Both the SDK and this Spring Data community project are major version changes with lots of differences from their respective previous versions. Notably, this version is compatible with `Couchbase Server 4.0`, bringing support for the `N1QL` query language. == Code of Conduct -This project is governed by the https://github.com/spring-projects/.github/blob/e3cc2ff230d8f1dca06535aa6b5a4a23815861d4/CODE_OF_CONDUCT.md[Spring Code of Conduct]. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. +This project is governed by the https://github.com/spring-projects/.github/blob/e3cc2ff230d8f1dca06535aa6b5a4a23815861d4/CODE_OF_CONDUCT.md[Spring Code of Conduct].By participating, you are expected to uphold this code of conduct.Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. == Getting Started @@ -144,14 +141,16 @@ You can also chat with the community on https://gitter.im/spring-projects/spring == Reporting Issues -Spring Data uses JIRA as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below: +Spring Data uses GitHub as issue tracking system to record bugs and feature requests. +If you want to raise an issue, please follow the recommendations below: * Before you log a bug, please search the https://github.com/spring-projects/spring-data-couchbase/issues[issue tracker] to see if someone has already reported the problem. -* If the issue doesn’t already exist, https://github.com/spring-projects/spring-data-couchbase/issues/new[create a new issue]. +* If the issue does not already exist, https://github.com/spring-projects/spring-data-couchbase/issues/new[create a new issue]. * Please provide as much information as possible with the issue report, we like to know the version of Spring Data that you are using and JVM version. -* If you need to paste code, or include a stack trace use JIRA `{code}…{code}` escapes before and after your text. -* If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code. +* If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text. +* If possible try to create a test-case or project that replicates the issue. +Attach a link to your code or a compressed file containing your code. == Building from Source @@ -173,10 +172,10 @@ Building the documentation builds also the project without running tests. [source,bash] ---- - $ ./mvnw clean install -Pdistribute + $ ./mvnw clean install -Pantora ---- -The generated documentation is available from `target/site/reference/html/index.html`. +The generated documentation is available from `target/antora/site/index.html`. === Building and staging reference documentation for review diff --git a/pom.xml b/pom.xml index eec5745e..8b5ef066 100644 --- a/pom.xml +++ b/pom.xml @@ -319,6 +319,31 @@ + + + antora-process-resources + + + + src/main/antora/resources/antora-resources + true + + + + + + antora + + + + io.spring.maven.antora + antora-maven-plugin + + + + + + spring-snapshot diff --git a/src/main/antora/.github/workflows/deploy-docs.yml b/src/main/antora/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..9d272779 --- /dev/null +++ b/src/main/antora/.github/workflows/deploy-docs.yml @@ -0,0 +1,33 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # FIXME: enable when pushed to spring-projects + # if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml new file mode 100644 index 00000000..1c58efae --- /dev/null +++ b/src/main/antora/antora-playbook.yml @@ -0,0 +1,42 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'data-couchbase' +site: + title: Spring Data Couchbase + url: https://docs.spring.io/spring-data-couchbase/reference/ +content: + sources: + - url: ./../../.. + branches: HEAD + start_path: src/main/antora + worktrees: true + - url: https://github.com/spring-projects/spring-data-commons + # Refname matching: + # https://docs.antora.org/antora/latest/playbook/content-refname-matching/ + branches: [ main, 3.2.x ] + start_path: src/main/antora +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip + snapshot: true diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml new file mode 100644 index 00000000..e6cba971 --- /dev/null +++ b/src/main/antora/antora.yml @@ -0,0 +1,12 @@ +name: data-couchbase +version: true +title: Spring Data Couchbase +nav: + - modules/ROOT/nav.adoc +ext: + collector: + - run: + command: ./mvnw validate process-resources -am -Pantora-process-resources + local: true + scan: + dir: target/classes/ diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc new file mode 100644 index 00000000..2d32ec48 --- /dev/null +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -0,0 +1,31 @@ +* xref:index.adoc[Overview] +** xref:commons/upgrade.adoc[] +** xref:commons/migrating.adoc[] + +* xref:couchbase.adoc[] +** xref:couchbase/configuration.adoc[] +** xref:couchbase/entity.adoc[] +** xref:couchbase/autokeygeneration.adoc[] +** xref:couchbase/template.adoc[] +** xref:couchbase/transactions.adoc[] +** xref:couchbase/collections.adoc[] +** xref:couchbase/fieldlevelencryption.adoc[] +** xref:couchbase/ansijoins.adoc[] +** xref:couchbase/caching.adoc[] + +* xref:repositories.adoc[] +** xref:repositories/core-concepts.adoc[] +** xref:repositories/definition.adoc[] +** xref:couchbase/repository.adoc[] +** xref:couchbase/reactiverepository.adoc[] +** xref:repositories/create-instances.adoc[] +** xref:repositories/query-methods-details.adoc[] +** xref:repositories/projections.adoc[] +** xref:repositories/custom-implementations.adoc[] +** xref:repositories/core-domain-events.adoc[] +** xref:repositories/core-extensions.adoc[] +** xref:repositories/null-handling.adoc[] +** xref:repositories/query-keywords-reference.adoc[] +** xref:repositories/query-return-types-reference.adoc[] + +* https://github.com/spring-projects/spring-data-commons/wiki[Wiki] diff --git a/src/main/asciidoc/migrating.adoc b/src/main/antora/modules/ROOT/pages/commons/migrating.adoc similarity index 72% rename from src/main/asciidoc/migrating.adoc rename to src/main/antora/modules/ROOT/pages/commons/migrating.adoc index 1c399611..e2406ee3 100644 --- a/src/main/asciidoc/migrating.adoc +++ b/src/main/antora/modules/ROOT/pages/commons/migrating.adoc @@ -12,45 +12,48 @@ Since the main objective was to migrate from the Java SDK 2 to 3, configuration IMPORTANT: XML Configuration support has been dropped, so only java/annotation based configuration is supported. -Your configuration still has to extend the `AbstractCouchbaseConfiguration`, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: `getConnectionString`, `getUserName`, `getPassword` and `getBucketName`. If you want to use a non-default scope optionally you can override the `getScopeName` method. Note that if you want to use certificate based authentication or you need to customize the password authentication, the `authenticator` method can be overridden to perform this task. +Your configuration still has to extend the `AbstractCouchbaseConfiguration`, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: `getConnectionString`, `getUserName`, `getPassword` and `getBucketName`.If you want to use a non-default scope optionally you can override the `getScopeName` method.Note that if you want to use certificate based authentication or you need to customize the password authentication, the `authenticator` method can be overridden to perform this task. The new SDK still has an environment that is used to configure it, so you can override the `configureEnvironment` method and supply custom configuration if needed. -For more information, see <>. +For more information, see xref:couchbase/configuration.adoc[Installation & Configuration]. +[[spring-boot-version-compatibility]] === Spring Boot Version Compatibility -Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x. Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath. +Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x.Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath. [[couchbase.migrating.entities]] +[[entities]] == Entities How to deal with entities has not changed, although since the SDK now does not ship annotations anymore only Spring-Data related annotations are supported. Specifically: - - `com.couchbase.client.java.repository.annotation.Id` became `import org.springframework.data.annotation.Id` - - `com.couchbase.client.java.repository.annotation.Field` became `import org.springframework.data.couchbase.core.mapping.Field` +- `com.couchbase.client.java.repository.annotation.Id` became `import org.springframework.data.annotation.Id` +- `com.couchbase.client.java.repository.annotation.Field` became `import org.springframework.data.couchbase.core.mapping.Field` The `org.springframework.data.couchbase.core.mapping.Document` annotation stayed the same. -For more information, see <>. +For more information, see xref:couchbase/entity.adoc[Modeling Entities]. [[couchbase.migrating.indexes]] == Automatic Index Management -Automatic Index Management has been redesigned to allow more flexible indexing. New annotations have been introduced and old ones like `@ViewIndexed`, `@N1qlSecondaryIndexed` and `@N1qlPrimaryIndexed` were removed. +Automatic Index Management has been redesigned to allow more flexible indexing. +New annotations have been introduced and old ones like `@ViewIndexed`, `@N1qlSecondaryIndexed` and `@N1qlPrimaryIndexed` were removed. -For more information, see <>. +For more information, see xref:couchbase/repository.adoc#couchbase.repository.indexing[Automatic Index Management]. [[couchbase.migrating.template]] == Template and ReactiveTemplate Since the Couchbase SDK 3 removes support for `RxJava` and instead adds support for `Reactor`, both the `couchbaseTemplate` as well as the `reactiveCouchbaseTemplate` can be directly accessed from the `AbstractCouchbaseConfiguration`. -The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads. This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate. +The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads.This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate. The following table describes the method names in 3.x and compares them to their 4.x equivalents: @@ -113,14 +116,14 @@ In addition, the following methods have been added which were not available in 3 We tried to unify and align the APIs more closely to the underlying SDK semantics so they are easier to correlate and navigate. -For more information, see <>. +For more information, see xref:couchbase/template.adoc[Template & direct operations]. [[couchbase.migrating.repository]] == Repositories & Queries - - `org.springframework.data.couchbase.core.query.Query` became `org.springframework.data.couchbase.repository.Query` - - `org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository` has been removed. Consider extending `ReactiveSortingRepository` or `ReactiveCouchbaseRepository` - - `org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository` has been removed. Consider extending `PagingAndSortingRepository` or `CouchbaseRepository` +- `org.springframework.data.couchbase.core.query.Query` became `org.springframework.data.couchbase.repository.Query` +- `org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository` has been removed.Consider extending `ReactiveSortingRepository` or `ReactiveCouchbaseRepository` +- `org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository` has been removed.Consider extending `PagingAndSortingRepository` or `CouchbaseRepository` IMPORTANT: Support for views has been removed and N1QL queries are now the first-class citizens for all custom repository methods as well as the built-in ones by default. @@ -151,9 +154,10 @@ public class MyService { ---- ==== -See <> for more information. +See xref:couchbase/repository.adoc[Couchbase repositories] for more information. +[[full-text-search-fts]] == Full Text Search (FTS) The FTS API has been simplified and now can be accessed via the `Cluster` class: @@ -193,4 +197,4 @@ public class MyService { ---- ==== -See link:https://docs.couchbase.com/java-sdk/current/howtos/full-text-searching-with-sdk.html[the FTS Documentation] for more information. \ No newline at end of file +See link:https://docs.couchbase.com/java-sdk/current/howtos/full-text-searching-with-sdk.html[the FTS Documentation] for more information. diff --git a/src/main/antora/modules/ROOT/pages/commons/upgrade.adoc b/src/main/antora/modules/ROOT/pages/commons/upgrade.adoc new file mode 100644 index 00000000..51a9189a --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/commons/upgrade.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$upgrade.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/couchbase.adoc b/src/main/antora/modules/ROOT/pages/couchbase.adoc new file mode 100644 index 00000000..0b1c813e --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/couchbase.adoc @@ -0,0 +1,15 @@ +[[couchbase.core]] += Couchbase Support +:page-section-summary-toc: 1 + +Spring Data support for Couchbase contains a wide range of features: + +* Spring configuration support with xref:couchbase/configuration.adoc[Java-based `@Configuration` classes]. +* The xref:couchbase/template.adoc[`CouchbaseTemplate` and `ReactiveCouchbaseTemplate`] helper classes that provide object mapping between Couchbase collections and POJOs. +* xref:couchbase/template.adoc#exception-translation[Exception translation] into Spring's portable {spring-data-commons-docs-url}data-access.html#dao-exceptions[Data Access Exception Hierarchy]. +* Feature rich object mapping integrated with _Spring's_ {spring-data-commons-docs-url}core.html#core-convert[Conversion Service]. +* Annotation-based mapping metadata that is extensible to support other metadata formats. +* Automatic implementation of xref:repositories.adoc[imperative and reactive `Repository` interfaces] including support for xref:repositories/custom-implementations.adoc[custom query methods]. + +For most data-oriented tasks, you can use the `[Reactive]CouchbaseTemplate` or the `Repository` support, both of which use the rich object-mapping functionality. +Spring Data Couchbase uses consistent naming conventions on objects in various APIs to those found in the Couchbase Java SDK so that they are familiar and so that you can map your existing knowledge onto the Spring APIs. diff --git a/src/main/asciidoc/ansijoins.adoc b/src/main/antora/modules/ROOT/pages/couchbase/ansijoins.adoc similarity index 95% rename from src/main/asciidoc/ansijoins.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/ansijoins.adoc index 732f39ae..11c75694 100644 --- a/src/main/asciidoc/ansijoins.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/ansijoins.adoc @@ -58,16 +58,19 @@ List books; [[couchbase.ansijoins.joinhints]] == ANSI Join Hints +[[use-index-hint]] === Use Index Hint `index` element on the `@N1qlJoin` can be used to provided the hint for the `lks` (current entity) index and `rightIndex` element can be used to provided the `rks` (associated entity) index. +[[hash-join-hint]] === Hash Join Hint If the join type is going to be hash join, the hash side can be specified for the `rks` (associated entity). If the associated entity is on the build side, it can be specified as `HashSide.BUILD` else `HashSide.PROBE`. +[[use-keys-hint]] === Use Keys Hint -`keys` element on the `@N1qlJoin` annotation can be used to specify unique document keys to restrict the join key space. \ No newline at end of file +`keys` element on the `@N1qlJoin` annotation can be used to specify unique document keys to restrict the join key space. diff --git a/src/main/asciidoc/autokeygeneration.adoc b/src/main/antora/modules/ROOT/pages/couchbase/autokeygeneration.adoc similarity index 90% rename from src/main/asciidoc/autokeygeneration.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/autokeygeneration.adoc index 8ddf7cce..03cc71f0 100644 --- a/src/main/asciidoc/autokeygeneration.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/autokeygeneration.adoc @@ -4,8 +4,8 @@ This chapter describes how couchbase document keys can be auto-generated using builtin mechanisms. There are two types of auto-generation strategies supported. -- <> -- <> +- xref:couchbase/autokeygeneration.adoc#couchbase.autokeygeneration.usingattributes[Key generation using attributes] +- xref:couchbase/autokeygeneration.adoc#couchbase.autokeygeneration.unique[Key generation using uuid] NOTE: The maximum key length supported by couchbase is 250 bytes. @@ -75,4 +75,4 @@ public class User { ... } ---- -==== \ No newline at end of file +==== diff --git a/src/main/asciidoc/caching.adoc b/src/main/antora/modules/ROOT/pages/couchbase/caching.adoc similarity index 100% rename from src/main/asciidoc/caching.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/caching.adoc diff --git a/src/main/asciidoc/collections.adoc b/src/main/antora/modules/ROOT/pages/couchbase/collections.adoc similarity index 97% rename from src/main/asciidoc/collections.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/collections.adoc index d6fbf18d..fc49b4db 100644 --- a/src/main/asciidoc/collections.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/collections.adoc @@ -7,14 +7,17 @@ The https://github.com/couchbaselabs/try-cb-spring[try-cb-spring] sample applica 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]] == Requirements - Couchbase Server 7.0 or above. - Spring Data Couchbase 4.3.1 or above. +[[getting-started-configuration]] == Getting Started & Configuration +[[scope-and-collection-specification]] === 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 diff --git a/src/main/asciidoc/configuration.adoc b/src/main/antora/modules/ROOT/pages/couchbase/configuration.adoc similarity index 90% rename from src/main/asciidoc/configuration.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/configuration.adoc index 24fd7583..8ecfb793 100644 --- a/src/main/asciidoc/configuration.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/configuration.adoc @@ -9,6 +9,7 @@ This chapter describes the common installation and configuration steps needed wh All versions intended for production use are distributed across Maven Central and the Spring release repository. As a result, the library can be included like any other maven dependency: +[[configuration]] == Configuration .Including the dependency through maven ==== @@ -27,6 +28,7 @@ This will pull in several dependencies, including the underlying Couchbase Java You can also grab snapshots from the https://repo.spring.io/ui/repos/tree/General/snapshot/org/springframework/data/spring-data-couchbase[spring snapshot repository] ( \https://repo.spring.io/snapshot ) and milestone releases from the https://repo.spring.io/ui/repos/tree/General/milestone/org/springframework/data/spring-data-couchbase[spring milestone repository] ( \https://repo.spring.io/milestone ). Here is an example on how to use the current SNAPSHOT dependency: +[[snapshot-configuration]] == Snapshot Configuration .Using a snapshot version @@ -47,6 +49,7 @@ Here is an example on how to use the current SNAPSHOT dependency: ---- ==== +[[overriding-the-couchbase-sdk-version]] == Overriding the Couchbase SDK Version Some users may wish to use a Couchbase Java SDK version different from the one referenced in a Spring Data Couchbase release for the purpose of obtaining bug and vulnerability fixes. Since Couchbase Java SDK minor version releases are backwards compatible, this version of Spring Data Couchbase is compatible and supported with any 3.x version of the Couchbase Java SDK newer than the one specified in the release dependencies. To change the Couchbase Java SDK version used by Spring Data Couchbase, simply override the dependency in the application pom.xml as follows: @@ -111,7 +114,7 @@ Only Java config is supported (XML config has been removed in 4.0). [[configuration-java]] == Annotation-based Configuration ("JavaConfig") -To get started, all you need to do is subclcass the `AbstractCouchbaseConfiguration` and implement the abstract methods. +To get started, all you need to do is subclass the `AbstractCouchbaseConfiguration` and implement the abstract methods. .Extending the `AbstractCouchbaseConfiguration` ==== @@ -165,27 +168,31 @@ Override `typeKey()` (for example to return `MappingCouchbaseConverter.TYPEKEY_S name of said attribute. If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying -Couchbase Java SDK is connecting to the database. If any errors are reported, make sure that the given credentials +Couchbase Java SDK is connecting to the database.If any errors are reported, make sure that the given credentials and host information are correct. +[[configuring-multiple-buckets]] == Configuring Multiple Buckets -To leverage multi-bucket repositories, implement the methods below in your Config class. The config*OperationsMapping methods configure the mapping of entity-objects to buckets. Be careful with the method names - using a method name that is a Bean will result in the value of that bean being used instead of the result of the method. +To leverage multi-bucket repositories, implement the methods below in your Config class. +The config*OperationsMapping methods configure the mapping of entity-objects to buckets. +Be careful with the method names - using a method name that is a Bean will result in the value of that bean being used instead of the result of the method. -This example maps Person -> protected, User -> mybucket, and everything else goes to getBucketName(). Note that this only maps calls through the Repository. +This example maps Person -> protected, User -> mybucket, and everything else goes to getBucketName(). +Note that this only maps calls through the Repository. ==== [source,java] ---- -@Override +@Override public void configureReactiveRepositoryOperationsMapping(ReactiveRepositoryOperationsMapping baseMapping) { try { ReactiveCouchbaseTemplate personTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("protected"),new MappingCouchbaseConverter()); baseMapping.mapEntity(Person.class, personTemplate); // Person goes in "protected" bucket ReactiveCouchbaseTemplate userTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter()); baseMapping.mapEntity(User.class, userTemplate); // User goes in "mybucket" - // everything else goes in getBucketName() + // everything else goes in getBucketName() } catch (Exception e) { throw e; } @@ -197,7 +204,7 @@ public void configureRepositoryOperationsMapping(RepositoryOperationsMapping bas baseMapping.mapEntity(Person.class, personTemplate); // Person goes in "protected" bucket CouchbaseTemplate userTemplate = myCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter()); baseMapping.mapEntity(User.class, userTemplate); // User goes in "mybucket" - // everything else goes in getBucketName() + // everything else goes in getBucketName() } catch (Exception e) { throw e; } @@ -210,7 +217,7 @@ public ReactiveCouchbaseTemplate myReactiveCouchbaseTemplate(CouchbaseClientFact return new ReactiveCouchbaseTemplate(couchbaseClientFactory, mappingCouchbaseConverter); } -// do not use couchbaseTemplate for the name of this method, otherwise the value of that been +// do not use couchbaseTemplate for the name of this method, otherwise the value of that been // will be used instead of the result from this call (the client factory arg is different) public CouchbaseTemplate myCouchbaseTemplate(CouchbaseClientFactory couchbaseClientFactory, MappingCouchbaseConverter mappingCouchbaseConverter) { diff --git a/src/main/asciidoc/entity.adoc b/src/main/antora/modules/ROOT/pages/couchbase/entity.adoc similarity index 99% rename from src/main/asciidoc/entity.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/entity.adoc index 3273d0e8..c4b1dc74 100644 --- a/src/main/asciidoc/entity.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/entity.adoc @@ -3,7 +3,7 @@ This chapter describes how to model Entities and explains their counterpart representation in Couchbase Server itself. -include::{spring-data-commons-docs}/object-mapping.adoc[leveloffset=+1] +include::{commons}@data-commons::page$object-mapping.adoc[leveloffset=+1] [[basics]] == Documents and Fields diff --git a/src/main/asciidoc/fieldlevelencryption.adoc b/src/main/antora/modules/ROOT/pages/couchbase/fieldlevelencryption.adoc similarity index 96% rename from src/main/asciidoc/fieldlevelencryption.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/fieldlevelencryption.adoc index b39704fb..124d1895 100644 --- a/src/main/asciidoc/fieldlevelencryption.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/fieldlevelencryption.adoc @@ -3,16 +3,20 @@ Couchbase supports https://docs.couchbase.com/java-sdk/current/howtos/encrypting-using-sdk.html[Field Level Encryption]. This section documents how to use it with Spring Data Couchbase. +[[requirements]] == Requirements - Spring Data Couchbase 5.0.0-RC1 or above. +[[overview]] == Overview Fields annotated with com.couchbase.client.java.encryption.annotation.Encrypted (@Encrypted) will be automatically encrypted on write and decrypted on read. Unencrypted fields can be migrated to encrypted by specifying @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED). +[[getting-started-configuration]] == Getting Started & Configuration +[[dependencies]] === Dependencies Field Level Encryption is available with the dependency ( see https://docs.couchbase.com/java-sdk/current/howtos/encrypting-using-sdk.html[Field Level Encryption] ) @@ -25,6 +29,7 @@ HashiCorp Vault Transit integration requires https://docs.spring.io/spring-vault org.springframework.vault spring-vault-core ``` +[[providing-a-cryptomanager]] === Providing a CryptoManager A CryptoManager needs to be provided by overriding the cryptoManager() method in AbstractCouchbaseConfiguration. This CryptoManager will be used by Spring Data Couchbase and also by Couchbase Java SDK direct calls made from a CouchbaseClientFactory. @@ -47,12 +52,14 @@ protected CryptoManager cryptoManager() { } ``` +[[defining-a-field-as-encrypted-]] === Defining a Field as Encrypted. 1. @Encrypted defines a field as encrypted. 2. @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED) defines a field that may or may not be encrypted when read. It will be encrypted when written. 3. @Encrypted(encrypter = "") specifies the alias of the encrypter to use for encryption. Note this is not the algorithm, but the name specified when adding the encrypter to the CryptoManager. +[[example]] === Example .AbstractCouchbaseConfiguration ==== diff --git a/src/main/asciidoc/reactiverepository.adoc b/src/main/antora/modules/ROOT/pages/couchbase/reactiverepository.adoc similarity index 92% rename from src/main/asciidoc/reactiverepository.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/reactiverepository.adoc index b4f0c368..25bbc24f 100644 --- a/src/main/asciidoc/reactiverepository.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/reactiverepository.adoc @@ -5,7 +5,7 @@ == Introduction This chapter describes the reactive repository support for couchbase. -This builds on the core repository support explained in <>. +This builds on the core repository support explained in xref:couchbase/repository.adoc[Couchbase repositories]. So make sure you’ve got a sound understanding of the basic concepts explained there. [[couchbase.reactiverepository.libraries]] @@ -101,4 +101,4 @@ public class PersonRepositoryTests { [[couchbase.reactiverepository.querying]] == Repositories and Querying -Spring Data's Reactive Couchbase comes with full querying support already provided by the blocking <> +Spring Data's Reactive Couchbase comes with full querying support already provided by the blocking xref:couchbase/repository.adoc#couchbase.repository.querying[Repositories and Querying] diff --git a/src/main/asciidoc/repository.adoc b/src/main/antora/modules/ROOT/pages/couchbase/repository.adoc similarity index 97% rename from src/main/asciidoc/repository.adoc rename to src/main/antora/modules/ROOT/pages/couchbase/repository.adoc index 5e3471e3..2efe9dc5 100644 --- a/src/main/asciidoc/repository.adoc +++ b/src/main/antora/modules/ROOT/pages/couchbase/repository.adoc @@ -3,9 +3,10 @@ The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores. -By default, operations are backed by Key/Value if they are single-document operations and the ID is known. For all other operations by default N1QL queries are generated, and as a result proper indexes must be created for performant data access. +By default, operations are backed by Key/Value if they are single-document operations and the ID is known. +For all other operations by default N1QL queries are generated, and as a result proper indexes must be created for performant data access. -Note that you can tune the consistency you want for your queries (see <>) and have different repositories backed by different buckets (see <>) +Note that you can tune the consistency you want for your queries (see xref:couchbase/repository.adoc#couchbase.repository.consistency[Querying with consistency]) and have different repositories backed by different buckets (see <>) [[couchbase.repository.configuration]] == Configuration @@ -360,6 +361,7 @@ public interface AirportRepository extends PagingAndSortingRepository result = txOperator.execute((ctx) -> ---- ==== +[[transactions-directly-with-the-sdk]] == Transactions Directly with the SDK Spring Data Couchbase works seamlessly with the Couchbase Java SDK for transaction processing. Spring Data Couchbase operations that diff --git a/src/main/antora/modules/ROOT/pages/index.adoc b/src/main/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..d4e3b82e --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,20 @@ +[[spring-data-couchbase-reference-documentation]] += Spring Data Couchbase +:revnumber: {version} +:revdate: {localdate} +:feature-scroll: true + +_Spring Data Couchbase provides repository support for the Couchbase database. +It eases development of applications with a consistent programming model that need to access Couchbase data sources._ + +[horizontal] +xref:couchbase.adoc[Couchbase] :: Couchbase support and connectivity +xref:repositories.adoc[Repositories] :: Couchbase Repositories +xref:commons/migrating.adoc[Migration] :: Migration Guides +https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information. + +Michael Nitschinger, Oliver Gierke, Simon Basle, Michael Reiche, Tigran Babloyan + +(C) 2014-2023 The original author(s) + +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. diff --git a/src/main/antora/modules/ROOT/pages/repositories.adoc b/src/main/antora/modules/ROOT/pages/repositories.adoc new file mode 100644 index 00000000..f7fc60fb --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories.adoc @@ -0,0 +1,8 @@ +[[couchbase.repositories]] += Repositories +:page-section-summary-toc: 1 + +This chapter explains the basic foundations of Spring Data repositories and Couchbase specifics. +Before continuing to the Couchbase specifics, make sure you have a sound understanding of the basic concepts. + +The goal of the Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores. diff --git a/src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc b/src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc new file mode 100644 index 00000000..579ae7da --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc @@ -0,0 +1,4 @@ +include::{commons}@data-commons::page$repositories/core-concepts.adoc[] + +[[couchbase.entity-persistence.state-detection-strategies]] +include::{commons}@data-commons::page$is-new-state-detection.adoc[leveloffset=+1] diff --git a/src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc b/src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc new file mode 100644 index 00000000..f84313e9 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/core-domain-events.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc b/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc new file mode 100644 index 00000000..a7c2ff8d --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/core-extensions.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc b/src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc new file mode 100644 index 00000000..2ae01801 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/create-instances.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc b/src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc new file mode 100644 index 00000000..c7615191 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/custom-implementations.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/definition.adoc b/src/main/antora/modules/ROOT/pages/repositories/definition.adoc new file mode 100644 index 00000000..bd65a8af --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/definition.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/definition.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc b/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc new file mode 100644 index 00000000..081bac9f --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/null-handling.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/projections.adoc b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc new file mode 100644 index 00000000..6168b162 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/projections.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc new file mode 100644 index 00000000..e495eddc --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc new file mode 100644 index 00000000..dfe48149 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/query-methods-details.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc b/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc new file mode 100644 index 00000000..a73c3201 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc @@ -0,0 +1 @@ +include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[] diff --git a/src/main/antora/resources/antora-resources/antora.yml b/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 00000000..6bf20087 --- /dev/null +++ b/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,18 @@ +version: ${antora-component.version} +prerelease: ${antora-component.prerelease} + +asciidoc: + attributes: + version: ${project.version} + springversionshort: ${spring.short} + springversion: ${spring} + attribute-missing: 'warn' + commons: ${springdata.commons.docs} + include-xml-namespaces: false + spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference + spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/ + spring-framework-docs: https://docs.spring.io/spring-framework/reference/{springversionshort} + spring-framework-javadoc: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api + springhateoasversion: ${spring-hateoas} + releasetrainversion: ${releasetrain} + store: Couchbase diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc deleted file mode 100644 index 11dae730..00000000 --- a/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= Spring Data Couchbase - Reference Documentation -Michael Nitschinger, Oliver Gierke, Simon Basle, Michael Reiche, Tigran Babloyan -:revnumber: {version} -:revdate: {localdate} -:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc - -(C) 2014-2023 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. - -toc::[] - -include::preface.adoc[] -include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] - -[[reference]] -= Reference Documentation - -:leveloffset: +1 -include::configuration.adoc[] -include::entity.adoc[] -include::autokeygeneration.adoc[] -include::{spring-data-commons-docs}/repositories.adoc[] -include::repository.adoc[] -include::reactiverepository.adoc[] -include::template.adoc[] -include::transactions.adoc[] -include::collections.adoc[] -include::fieldlevelencryption.adoc[] -include::ansijoins.adoc[] -include::caching.adoc[] -:leveloffset: -1 - -[[appendix]] -= Appendix - -:numbered!: -: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[] -:leveloffset: -1 diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc deleted file mode 100644 index d4f5b45d..00000000 --- a/src/main/asciidoc/preface.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[[couchbase.preface]] -= Preface - -This reference documentation describes the general usage of the Spring Data Couchbase library. - -[[metadata]] -[preface] -== Project Information - -* Version control - https://github.com/spring-projects/spring-data-couchbase -* Bugtracker - https://github.com/spring-projects/spring-data-couchbase/issues -* Release repository - https://repo1.maven.org/maven2 -* Milestone repository - https://repo.spring.io/milestone -* Snapshot repository - https://repo.spring.io/snapshot - -[preface] -include::migrating.adoc[leveloffset=+1] -