diff --git a/README.adoc b/README.adoc index 58dccfd1..72b45dc7 100644 --- a/README.adoc +++ b/README.adoc @@ -1,9 +1,9 @@ = Couchbase Java SDK Documentation -This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.11/hello-world/overview.html[Couchbase Java SDK]. +This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.13/hello-world/overview.html[Couchbase Java SDK]. -This branch documents the 3.11 release of the SDK. -It follows the https://docs.couchbase.com/java-sdk/3.11/project-docs/compatibility.html#api-version[SDK 3.9 API]. +This branch documents the 3.13 release of the SDK. +It follows the https://docs.couchbase.com/java-sdk/3.13/project-docs/compatibility.html#api-version[SDK 3.10 API]. This branch reflects the new Information Architecture for the SDK docs, helping to guide new-to-Couchbase users through the pitfalls of a complex distributed system. @@ -121,7 +121,7 @@ Update the following files: === New Branches -Production branches use the *release/x.y* naming pattern (e.g. `release/3.10`, `release/3.11`). +Production branches use the *release/x.y* naming pattern (e.g. `release/3.12`, `release/3.11`). Antora uses the branch names in the playbook, but also uses the `version` given in the antor.yml file, to create the version navigation -- so this version number must be unique within the repo for any branches included in the playbook. When creating a new branch for a new release, remember to update the antora.yml file before trying to build. diff --git a/antora.yml b/antora.yml index 3d876fe1..2ae892ae 100644 --- a/antora.yml +++ b/antora.yml @@ -1,5 +1,5 @@ name: java-sdk -version: '3.11' +version: '3.13' title: Java SDK start_page: hello-world:overview.adoc nav: @@ -7,16 +7,19 @@ nav: asciidoc: attributes: page-nav-header-levels: 2 - server_version: '8.0.0' - sdk_current_version: '3.11.1' - sdk_dot_minor: '3.11' + server_version: '8.0.3' + sdk_current_version: '3.13.0' + sdk_dot_minor: '3.13' sdk_dot_major: '3.x' version-server: '8.0' - version-common: '8.0.1' + version-common: '3.10' java_latest_lts_version: '25' name_platform: 'Java' name_platform_lc: 'java' + lang-code: 'java' name-sdk: Java SDK - sdk_api: '3.9' + archive_version: 2.7 + archive_major: 2.x + sdk_api: '3.10' sdk-api-link: https://docs.couchbase.com/sdk-api/couchbase-java-client/ sdk-gh-link: https://github.com/couchbase/couchbase-jvm-clients/ diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 1e0114a4..18e25ce5 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -64,6 +64,7 @@ *** https://docs-archive.couchbase.com/home/index.html[Older Versions Archive^] ** xref:project-docs:compatibility.adoc[] *** xref:project-docs:migrating-sdk-code-to-3.n.adoc[] +**** xref:howtos:view-queries-with-sdk.adoc[] *** xref:project-docs:distributed-acid-transactions-migration-guide.adoc[] *** xref:project-docs:third-party-integrations.adoc[] ** xref:project-docs:sdk-full-installation.adoc[] @@ -81,107 +82,3 @@ ** xref:ref:glossary.adoc[Glossary] ** xref:ref:travel-app-data-model.adoc[] ** xref:project-docs:metadoc-about-these-sdk-docs.adoc[About These Docs] - - - - - - - - - -//// -.Getting Started -* xref:hello-world:start-using-sdk.adoc[] -* xref:howtos:kv-operations.adoc[] -* xref:howtos:n1ql-queries-with-sdk.adoc[] -* xref:howtos:full-text-searching-with-sdk.adoc[] -* xref:hello-world:sample-application.adoc[] -* xref:hello-world:spring-data-sample-application.adoc[] - -.Transactions -* xref:howtos:distributed-acid-transactions-from-the-sdk.adoc[] -** xref:howtos:transactions-single-query.adoc[] -** xref:howtos:transactions-tracing.adoc[] -* xref:concept-docs:transactions.adoc[] -** xref:concept-docs:transactions-cleanup.adoc[] -** xref:concept-docs:transactions-error-handling.adoc[] - -.Further Data Ops -* xref:howtos:json.adoc[] -* xref:howtos:subdocument-operations.adoc[] -// ** xref:howtos:sdk-xattr-example.adoc[Extended Attributes] -* xref:howtos:analytics-using-sdk.adoc[] -// ** xref:howtos:advanced-analytics-querying.adoc[Advanced Analytics Querying] -* xref:howtos:view-queries-with-sdk.adoc[] -* xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs] -* xref:howtos:concurrent-document-mutations.adoc[] -* xref:howtos:encrypting-using-sdk.adoc[] -* xref:howtos:transcoders-nonjson.adoc[Transcoders & Non-JSON Documents] - -.Managing Couchbase -* xref:howtos:managing-connections.adoc[] -** xref:howtos:sdk-authentication.adoc[] -** xref:howtos:troubleshooting-cloud-connections.adoc[Troubleshooting Cloud Connections] -* xref:howtos:provisioning-cluster-resources.adoc[] -** xref:howtos:sdk-user-management-example.adoc[] - -.Errors & Diagnostics -* xref:howtos:error-handling.adoc[] -* xref:howtos:collecting-information-and-logging.adoc[] -* xref:howtos:health-check.adoc[] -* Observability -** xref:howtos:slow-operations-logging.adoc[] -** xref:howtos:observability-metrics.adoc[] -** xref:howtos:observability-orphan-logger.adoc[] -** xref:howtos:observability-tracing.adoc[] - -.Learn -* xref:concept-docs:concepts.adoc[] -* xref:concept-docs:buckets-and-clusters.adoc[Buckets & Clusters] -* xref:concept-docs:collections.adoc[Collections & Scopes] -* xref:concept-docs:compression.adoc[] -* xref:concept-docs:data-model.adoc[] -** xref:concept-docs:documents.adoc[] -** xref:concept-docs:nonjson.adoc[] -** xref:concept-docs:subdocument-operations.adoc[Sub-Documents] -** xref:concept-docs:xattr.adoc[XATTR & Virtual XATTR] -* xref:concept-docs:errors.adoc[Errors & Diagnostics] -** xref:concept-docs:health-check.adoc[] -** xref:concept-docs:response-time-observability.adoc[] -* xref:concept-docs:durability-replication-failure-considerations.adoc[] -* xref:concept-docs:encryption.adoc[Field Level Encryption] -* xref:concept-docs:data-services.adoc[Service Selection] -** xref:concept-docs:analytics-for-sdk-users.adoc[] -** xref:concept-docs:understanding-views.adoc[Views] -** xref:concept-docs:n1ql-query.adoc[] -** xref:concept-docs:full-text-search-overview.adoc[Search] -* xref:concept-docs:sdk-user-management-overview.adoc[User Management] -** xref:concept-docs:certificate-based-authentication.adoc[Cert Auth] -** xref:concept-docs:rbac.adoc[RBAC] - -.References -* https://docs.couchbase.com/sdk-api/couchbase-java-client[API Reference] -* https://docs.couchbase.com/sdk-api/couchbase-core-io/[JVM Core IO API] -* https://docs.couchbase.com/sdk-api/couchbase-transactions-java/index.html?overview-summary.html[Transactions API Reference] -* xref:ref:client-settings.adoc[] -// * xref:ref:data-structures[Data Structures] -* xref:ref:error-codes.adoc[] -* xref:ref:glossary.adoc[Glossary] -* xref:ref:travel-app-data-model.adoc[] - -.Project Docs -* xref:project-docs:sdk-release-notes.adoc[SDK Release Notes] -* xref:project-docs:compatibility.adoc[] -** xref:project-docs:migrating-sdk-code-to-3.n.adoc[] -*** xref:howtos:working-with-collections.adoc[Working with Collections] -** xref:project-docs:distributed-acid-transactions-migration-guide.adoc[] -** xref:project-docs:third-party-integrations.adoc[] -* xref:project-docs:sdk-full-installation.adoc[] -// ** xref:hello-world:platform-help.adoc[] -* https://docs-archive.couchbase.com/home/index.html[Older Versions Archive] -* xref:project-docs:sdk-licenses.adoc[] -* xref:project-docs:get-involved.adoc[] - ** https://docs.couchbase.com/home/contribute/index.html[Improve the Docs] -* xref:project-docs:metadoc-about-these-sdk-docs.adoc[About These Docs] -//// diff --git a/modules/concept-docs/pages/analytics-for-sdk-users.adoc b/modules/concept-docs/pages/analytics-for-sdk-users.adoc deleted file mode 100644 index 878180fd..00000000 --- a/modules/concept-docs/pages/analytics-for-sdk-users.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Analytics -:description: Parallel data management for complex queries over many records, using a familiar SQL-like syntax. -:nav-title: Analytics for SDK Users -:page-topic-type: concept -:page-aliases: analytics.adoc - -[abstract] -{description} - - -For complex and long-running queries, involving large ad hoc join, set, aggregation, and grouping operation. - - -//// -== MetaData - -=== List of Metrics - -//// - - -== Additional Resources - -* Start with our xref:{version-server}@server:analytics:primer-beer.adoc[introductory primer]. -* Read the practical introduction xref:howtos:analytics-using-sdk.adoc[using analytics from the SDK]. diff --git a/modules/concept-docs/pages/best-practices.adoc b/modules/concept-docs/pages/best-practices.adoc index 1b2612e4..ec19043f 100644 --- a/modules/concept-docs/pages/best-practices.adoc +++ b/modules/concept-docs/pages/best-practices.adoc @@ -7,11 +7,12 @@ // Note to editors // -// This page pulls in content from -sdk-common- +// This page pulls in content from +// https://github.com/couchbase/docs-sdk-common/blob/api/3.10/modules/shared/partials/best-practices-sdk.adoc // and code samples from -example-dir- // -// It can be seen built at wwww. - +// It can be seen built at +// https://docs.couchbase.com/java-sdk/3.13/concept-docs/best-practices.html [abstract] {description} @@ -27,84 +28,53 @@ There's plenty that can be done to remove bottlenecks in development and in perf == Security -But before worrying about bottlenecks, let's put security concerns first. - -Security is a process, and not just a set of checkboxes -- but there are key areas you must check off as you move from development, through testing, to deploying in production. -// - -=== Roles and RBAC - -Self-managed Couchbase Server uses Role-Based Access Control (RBAC), which is reflected in our managed service (Capella) as a nuanced set of Roles. -Data security depends in part on only giving access to the minimum amount of data and permissions required to do the job. -// +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=security] +// === Roles and RBAC + +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=rbac] -// concept snippet -// include::{version-common}@sdk:pages:partial$rbac.adoc[] -RBAC restrict resources on a Couchbase cluster to an identified user, allocated by role. +== Performance -==== Capella Security & Priveleges +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=performance] -Capella, our managed service, likewise has a concept of roles. -In addition to this, clusters within Capella are grouped into -xref:cloud:organizations:organization-projects-overview.adoc[organizations and projects], -to maintain separation of concerns, as well as access priveleges. +=== Dealing with Timeout Errors -==== Users, Resources, Roles, and Privileges +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-debug] -Couchbase Server Enterprise Edition uses _Role-Based Access Control_ for applications to restrict _resources_ on a Couchbase cluster to an identified _user_. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-wait] -Each user who attempts resource-access is identified by means of the _credentials_ they pass to Couchbase Server, for purposes of _authentication_: these consist of a _username_ and (typically) a _password_. -Once the user is authenticated, an _authorization_ process checks the _roles_ with which the user is associated. -If one or more of these roles correspond to _privileges_ that permit the user-requested level of resource-access, access is duly granted; otherwise, it is denied. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=timeout-more] -Users who have been assigned the *Admin* role for the cluster are able to create, edit, and remove users. -The SDK provides APIs to support these activities. -NOTE: Introductory examples in the SDK documentation use the _Administrator_ user to ensure that developers can quickly get up and running; this _should not be used in production_. -Elsewhere we use a general "user" which represents whichever permission levels are appropriate to your application. -== Performance +=== Concurrency and Async APIs -Couchbase's Data Service uses a fast binary protocol, which will always outperform JSON streamed over HTTP from {sqlpp} queries. -If you know the key (ID) of a document, then use the xref:howtos:kv-operations.adoc[Data Service]. +// ....this paragraph different for each SDK. -If you need pessimistic logging, in particular if you need to lock documents for multi-document ACID transactions, then anything you can do at the schema level to reduce the number of documents locked simultaneously wil remvoe a bottleneck to updating the affected documents. +We recommend using the reactive API over the `CompletableFuture` counterpart. +See the xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs page] for discussion and practical examples. -=== Dealing with Timeout Errors +=== Bulk Get, Multi-Get, and Network Latency -// see also -// https://couchbasecloud.atlassian.net/wiki/spaces/CST/pages/1993769712/Java+-+Debugging+KV+Timeouts -// in Support wiki +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get] -* `waitUntilReady` should be the default setting for `Cluster.connect` and `Cluster.bucket` in most cases, so that resources are fully loaded before the client proceeds with CRUD calls to the cluster. -* LAN-type connection of client and server is recommended in production, but WAN development is a reality pre-production. -Ensure that you're familiar with the -xref:ref:client-settings.adoc#constrained-network-environments[best timeout options for WAN environments], -or at least set a xref:ref:client-settings.adoc#wan-development[WAN development Configuration Profile]. +==== When to Use Bulk Get +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get-async-platform] -// Something on longer timeouts and fewer retries? -// ... reading the logs to find the pattern? -// & Something on polling rate the SDK uses to fetch an updated cluster map whenever a topology change occurs. -//// -By default the Java SDK polls every 2.5 seconds, regardless of server version or SDK version. -This interval is configurable via the io.configPollInterval client setting. -https://docs.couchbase.com/java-sdk/current/ref/client-settings.html#io.configPollInterval -When Java SDK 3.5.0 or later is used with Couchbase Server 7.6 or later, the SDK also listens for config change notifications from the server. In this case the polling acts as a failsafe, so it's probably okay to set it significantly higher than 2.5 seconds. -//// // write after more LZA added //// @@ -114,14 +84,6 @@ Advanced zone aware.... //// -=== Concurrency and Async APIs - -// ....this paragraph different for each SDK. - -We recommend using the reactive API over the `CompletableFuture` counterpart. -See the xref:howtos:concurrent-async-apis.adoc[Async & Reactive APIs page] for discussion and practical examples. - - == Error Handling @@ -132,12 +94,6 @@ See also the xref:howtos:error-handling.adoc[error handling guide], which covers specific errors, along with a broader look at error handling strategies. -== Testing - -Integrate developing with the {name-sdk} into your accustomed test framework. - - - //// == General Approach to Scala Exceptions @@ -156,6 +112,8 @@ include::{version-common}@sdk:shared:partial$errors.adoc[tag=diag] + + // Slow Operations Logging include::{version-common}@sdk:shared:partial$errors.adoc[tag=observability] @@ -166,6 +124,14 @@ include::{version-common}@sdk:shared:partial$errors.adoc[tag=observability] +== Testing + +Integrate developing with the {name-sdk} into your accustomed test framework. + + + + + // Missing APIs // For anything that is not covered by the SDK, // for example @@ -216,25 +182,8 @@ Example usage: == Additional Information -SDKs are client to Couchbase Server -- whether Capella Database-As-A-Service, or self-managed -- and in some areas it would be wise to take a fully rounded approach. -Read up on security and performance considerations relevant to your use case. - -=== Couchbase Security Best Practices - -* xref:cloud:security:security.adoc[Security Best Practices in Capella] -* xref:server:learn:security/security-overview.adoc[Security for self-managed Couchbase Server] - -=== Role-Based Access Control - -For Capella, Roles, Cluster Access Credentials, and Authentication options are covered in the xref:cloud:security:security.adoc[Capella Security docs]. - - -For self-managed Couchbase Server, all aspects of the Couchbase RBAC system are covered in the section xref:{version-server}@server:learn:security/authorization-overview.adoc[Authorization]. -Specifically, for information on: -* Adding _Users_ and assigning _roles_, by means of the Couchbase Web Console, see xref:{version-server}@server:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles]. -* _Roles_ required for resource-access, and the privileges they entail, see xref:{version-server}@server:learn:security/roles.adoc[Roles]. -* _Resources_ controlled by Couchbase RBAC, see xref:{version-server}@server:learn:security/resources-under-access-control.adoc[Resources Under Access Control]. +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=additional] diff --git a/modules/concept-docs/pages/buckets-and-clusters.adoc b/modules/concept-docs/pages/buckets-and-clusters.adoc deleted file mode 100644 index b7de9176..00000000 --- a/modules/concept-docs/pages/buckets-and-clusters.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= Buckets and Clusters -:description: The Couchbase Java SDK provides an API for managing a Couchbase cluster programmatically. -:navtitle: Buckets & Clusters -:page-topic-type: concept -:page-aliases: managing-clusters.adoc - -include::project-docs:partial$attributes.adoc[] - -[abstract] -{description} - -include::{version-common}@sdk:shared:partial$clusters-buckets.adoc[tag=management] - -Management operations in the Java SDK may be performed through several interfaces depending on the object: - -== Creating and Removing Buckets - -To create or delete a bucket, call the bucket manager with the `buckets()` call on the cluster: - -[source,java] ----- -include::example$BucketsAndClustersExample.java[tag=buckets_and_clusters_1,indent=0] ----- - -// The `BucketSettings` can be created via a builder, [.api]`DefaultBucketSettings.builder()`. -This class is also used to expose information about an existing bucket (`manager.getBucket(string)`) or to update an existing bucket (`manager.updateBucket(bucketSettings)`). - -The default Collection & Default Scope will be used automatically. - diff --git a/modules/concept-docs/pages/collections.adoc b/modules/concept-docs/pages/collections.adoc deleted file mode 100644 index ce12a00a..00000000 --- a/modules/concept-docs/pages/collections.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Collections and Scopes -:description: pass:q[Fully supported in Couchbase Server 7.x] -:page-topic-type: concept -:nav-title: Collections - -[abstract] -{description} - -The Collections feature in Couchbase Server is fully implemented in the 3.x API versions of the Couchbase SDK. - -Information on _Collections_ can be found in the xref:{version-server}@server:learn:data/scopes-and-collections.adoc[server docs]. - -== Using Collections & Scopes - -Access a non-default collection, in the default scope, with: - -[source,java] ----- -include::example$CollectionsExample.java[tag=collections_1,indent=0] ----- - -And for a non-default scope: -[source,java] ----- -include::example$CollectionsExample.java[tag=collections_2,indent=0] ----- - - -== Further Reading - -To see Collections in action, take a look at our xref:howtos:working-with-collections.adoc[Collections-enabled Travel Sample page]. diff --git a/modules/concept-docs/pages/data-durability-acid-transactions.adoc b/modules/concept-docs/pages/data-durability-acid-transactions.adoc index 273dcfc7..f33e8fc6 100644 --- a/modules/concept-docs/pages/data-durability-acid-transactions.adoc +++ b/modules/concept-docs/pages/data-durability-acid-transactions.adoc @@ -1,5 +1,6 @@ = Data Modelling, Durability, and Consistency // :page-aliases: durability-replication-failure-considerations.adoc +:page-aliases: concept-docs:collections.adoc :description: Performance, availability, consistency -- balance your priorities, and model your data to achieve these goals. :page-toclevels: 2 :anyreplica-api: pass:q[https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/AsyncCollection.html#getAnyReplica(java.lang.String,com.couchbase.client.java.kv.GetAnyReplicaOptions)] diff --git a/modules/devguide/examples/java/KvOperations.java b/modules/devguide/examples/java/KvOperations.java index b1ae1bb2..352848b9 100644 --- a/modules/devguide/examples/java/KvOperations.java +++ b/modules/devguide/examples/java/KvOperations.java @@ -217,17 +217,6 @@ public static void main(String... args) { System.out.println("cas value: " + result.cas()); } - { - System.out.println("\nExample: [expiry-replace]"); - // tag::expiry-replace[] - GetResult found = collection.get("my-document3", getOptions().withExpiry(true)); - - MutationResult result = collection.replace("my-document3", json, - replaceOptions().expiry(found.expiryTime().get())); - // end::expiry-replace[] - - } - try { System.out.println("\nExample: [preserve-expiry]"); diff --git a/modules/devguide/examples/java/ManagingConnections.java b/modules/devguide/examples/java/ManagingConnections.java index 93b08804..d7eaf418 100644 --- a/modules/devguide/examples/java/ManagingConnections.java +++ b/modules/devguide/examples/java/ManagingConnections.java @@ -48,8 +48,7 @@ public static void main(String... args) { // You can access multiple buckets using the same Cluster object. Bucket anotherBucket = cluster.bucket("beer-sample"); - // You can access collections other than the default - // if your version of Couchbase Server supports this feature. + // You can access multiple collections, too Scope customerA = bucket.scope("customer-a"); Collection widgets = customerA.collection("widgets"); diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index 733f2cea..b59ca64f 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -17,7 +17,7 @@ = Couchbase {name-sdk} {sdk_dot_minor} -The Couchbase {name-sdk} allows {name_platform} applications to access a Couchbase cluster -- +The Couchbase {name-sdk} allows {name_platform} applications to access a Couchbase operational cluster -- Capella or self-managed. // -- other SDKs are available for Couchbase Lite (edge or mobile devices) and Capella Columnar (real-time analytics) @@ -27,7 +27,7 @@ xref:project-docs:sdk-release-notes.adoc[] | {sdk-gh-link}[{name-sdk} source code] -What's the point of a fast and scalable database if it's not easy to develop for? +A fast and scalable database is even better when it's easy to develop for. Couchbase gives you the {name_platform} APIs to work with Capella, our managed solution, or self-managed options in your private Cloud or datacenter. @@ -203,4 +203,22 @@ Useful resources to help support your development experience with Couchbase and ++++ + +{empty} + + + +{empty} + + + + +== icon:code[] Couchbase Operational Cluster Feature Compatibility + +include::project-docs:deployment.adoc[tag=feature-compat] + + + +{empty} + + + + include::{version-common}@sdk:shared:partial$columnar-available.adoc[tag=initial-availability-o] diff --git a/modules/hello-world/pages/platform-help.adoc b/modules/hello-world/pages/platform-help.adoc index 8c921ef6..623b975f 100644 --- a/modules/hello-world/pages/platform-help.adoc +++ b/modules/hello-world/pages/platform-help.adoc @@ -34,16 +34,16 @@ To install the JDK we are going to use a JVM-management tool called `sdkman`. === SDKMAN! -SDKMAN! -- the Software Development Kit Manager -- enables multiple Java versions and runtimes to be installed and managed, without intefering with your system's default JVM. +SDKMAN! -- the Software Development Kit Manager -- enables multiple Java versions and runtimes to be installed and managed, without interfering with your system's default JVM. This third party tool is unnecessary in most production environments, but ideal for development machines. Installation instructions can be found on the https://sdkman.io/install[SDKMAN! website]. -Once SDKMAN! is installed, use it to install the latest version of Java: +Once SDKMAN! is installed, use it to install the latest stable version of Java: [source,console] ---- -$ sdk install java 23.0.2-oracle +$ sdk install java ---- You may be prompted to set that version as a default -- say yes (by pressing **). diff --git a/modules/hello-world/pages/sample-application.adoc b/modules/hello-world/pages/sample-application.adoc index d89af96c..04e8016f 100644 --- a/modules/hello-world/pages/sample-application.adoc +++ b/modules/hello-world/pages/sample-application.adoc @@ -2,70 +2,39 @@ :page-toclevels: 2 :description: Quickstart app to build a REST API using Couchbase Capella in Java using Spring Boot. :page-aliases: ROOT:sample-application.adoc,ROOT:tutorial4.adoc,ROOT:sample-app-backend.adoc +:dev-portal-link: https://github.com/couchbase-examples/java-springboot-quickstart +:this-platform: (in Java using Spring Boot) +:dir-name: java-springboot-quickstart +// abstract +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=abstract] -[abstract] -{description} -Discover how to program interactions with Couchbase via the Data, Query, and Search services. - - -After you have navigated through https://cloud.couchbase.com/sign-up[signing up to Capella], -if {name_platform} is entered as your chosen language, you will be pointed to a clonable quickstart app on GitHub. -If you were not, you can still find it https://github.com/couchbase-examples/java-springboot-quickstart[here]. - - -Often, the first step developers take after creating their database is to create a REST API that can perform Create, Read, Update, and Delete (CRUD) operations for that database. -The https://github.com/couchbase-examples/java-springboot-quickstart[quickstart project] is designed to teach you and give you a starter project (in Java using Spring Boot) to generate such a REST API. -After you have loaded the travel-sample bucket in your database, you can run this application which is a REST API with Swagger documentation so that you can learn: -. How to create, read, update, and delete documents using xref:howto:kv-operations[Key-Value operations]. -KV operations are unique to Couchbase and provide super fast (under millisecond) operations. -. How to write simple parametrized xref:howtos:n1ql-queries-with-sdk.html[{sqlpp} queries] using the built-in travel-sample bucket. -This documentation -- and a number of other useful developer tutorials -- -can be found on the https://developer.couchbase.com/tutorial-quickstart-java-springboot/[Couchbase Developer Portal]. +// intro +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=intro] == Prerequisites -To run this prebuilt project, you will need: +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=prereq] -* A https://www.couchbase.com/products/capella/[Couchbase Capella] cluster with the xref:ref:travel-app-data-model.adoc[travel-sample] bucket loaded. -+ -To run this tutorial using a self-managed Couchbase cluster, please refer to the <<#running-self-managed-couchbase-cluster>> section. - -* Java SDK 17+ -- see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility guide]. +* Java JDK 17+ -- see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility guide]. + [NOTE] ==== The application is tested with Java 17 and 21. If you are using a different version of Java, please update the `pom.xml` file accordingly. ==== -* The Travel Sample Bucket -- pre-loaded in Capella Free Tier, or see xref:cloud:clusters:data-service/import-data-documents.adoc#import-sample-data[]. - * https://maven.apache.org/install.html[Maven 3.6.3+]. -== App Setup -We will walk through the different steps required to get the application running: -. Cloning Repo -+ -[source,console] ----- -$ git clone https://github.com/couchbase-examples/java-springboot-quickstart.git ----- - -. Navigate to the Project Directory -+ -[source,console] ----- -$ cd java-springboot-quickstart ----- +== App Setup -. Install Dependencies +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=setup] + The dependencies for the application are specified in the `pom.xml` file in the root folder. Dependencies can be installed through `mvn` the default package manager for Java. @@ -78,13 +47,13 @@ $ mvn clean install -DskipTests=true Note, the `-DskipTests=true` option is used to skip the tests. The tests require the application to be running. -=== Setup Database Configuration -To learn more about connecting to your Capella cluster, please follow the https://docs.couchbase.com/cloud/get-started/connect.html[instructions]. -Specifically, you need to do the following: -. Create the xref:cloud:clusters:manage-database-users.adoc[database credentials] to access the travel-sample bucket (Read and Write) used in the application. -. https://docs.couchbase.com/cloud/clusters/allow-ip-address.html[Allow access] to the Cluster from the IP on which the application is running. + + +=== Setup Database Configuration + +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=db-config] All configuration for communication with the database is read from the application properties. We have provided a convenience feature in this quickstart to read the properties from a local file, @@ -105,18 +74,17 @@ You can also use your system environment variables to set the properties.The pro The properties are read from the `application.properties` file if the environment variables are not set. + + + == Running The Application You can add environment variables `DB_CONN_STR`, `DB_USERNAME`, and `DB_PASSWORD` to your system environment variables or you can update the `application.properties` file in the `src/main/resources` folder. -.Running from a Development Machine -[TIP] -==== -Couchbase -- including Capella -- is designed to run in a LAN-like environment. -For development, connecting to a remote cloud instance from a local laptop instead of an application server in the same region, -may require you to adjust some timeouts. -If you have problems, refer to the xref:ref:client-settings.adoc#constrained-network-environments[constrained network environments] section of the docs. -==== + +// constrained network environment +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=dev-pc] + === Directly on Your Local Machine @@ -208,9 +176,8 @@ $ mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.RouteIntegrati === Data Model -For this quickstart, we use three collections, `airport`, `airline` and `routes` that contain sample airports, airlines and airline routes respectively. The routes collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections. +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=data-model] -image::travel_sample_data_model.png[travel-sample data model] === Extending API by Adding New Entity @@ -223,158 +190,24 @@ If you would like to add another entity to the APIs, these are the steps to foll === Running Self-Managed Couchbase Cluster -If you are running this quickstart with a self-managed Couchbase cluster, you need to [load](https://docs.couchbase.com/server/current/manage/manage-settings/install-sample-buckets.html) the travel-sample data bucket in your cluster and generate the credentials for the bucket. +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=self-managed] -You need to update the connection string and the credentials in the `application.properties` file in the `src/main/resources` folder. -Note: Couchbase Server version 7 or higher must be installed and running before running the Spring Boot Java app. === Swagger Documentation -Swagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects. +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=swagger] + -Click on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts. ==== Trying Out the API -You can try out an API by clicking on the "Try it out" button next to the endpoints. -- Parameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request. +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=try] -- Execution: Once you've inputted all the necessary parameters, you can click the "Execute" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body. ==== Models -Swagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect. - - - - - - - - - - - - - - - - - - - - -//// -= Sample Application -:description: Discover how to program interactions with Couchbase via the Data, Query, and Search services. -:content-type: tutorial -:page-topic-type: tutorial -:page-aliases: ROOT:sample-application,ROOT:tutorial4,ROOT:sample-app-backend -:page-pagination: full - -:travel-sample-git-project: try-cb-java - -include::project-docs:partial$attributes.adoc[] - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=abstract] - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=quick-start] - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=bring-your-own] - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=using] - - - -== Sample App Backend - -The backend code shows Couchbase Java SDK in action with Query and Search, -but also how to plug together all of the elements and build an application with Couchbase Server and the Java SDK. -Look at `TenantUser.java` to see some of the pieces necessary in most applications, such as the TenantUser `@Service`: - -[source,java] ----- -@Service -public class TenantUser { - - private final TokenService jwtService; - - @Autowired - public TenantUser(TokenService jwtService) { - this.jwtService = jwtService; - } - - static final String USERS_COLLECTION_NAME = "users"; - static final String BOOKINGS_COLLECTION_NAME = "bookings"; ----- - -Creating a user shows the typical security concerns, with salted password hashes, as well as the mundane but essential business of using the KV interface to `insert` the username into the database: - -[source,java] ----- -public Result> createLogin(final Bucket bucket, final String tenant, final String username, - final String password, DurabilityLevel expiry) { - String passHash = BCrypt.hashpw(password, BCrypt.gensalt()); - JsonObject doc = JsonObject.create() - .put("type", "user") - .put("name", username) - .put("password", passHash); - InsertOptions options = insertOptions(); - if (expiry.ordinal() > 0) { - options.durability(expiry); - } - - Scope scope = bucket.scope(tenant); - Collection collection = scope.collection(USERS_COLLECTION_NAME); - String queryType = String.format("KV insert - scoped to %s.users: document %s", scope.name(), username); - try { - collection.insert(username, doc, options); - Map data = JsonObject.create().put("token", jwtService.buildToken(username)).toMap(); - return Result.of(data, queryType); - } catch (Exception e) { - e.printStackTrace(); - throw new AuthenticationServiceException("There was an error creating account"); - } -} ----- - -Here, the _flights_ array, containing the flight IDs, is converted to actual objects: - -[source,java] ----- - List> results = new ArrayList>(); - for (int i = 0; i < flights.size(); i++) { - String flightId = flights.getString(i); - GetResult res; - try { - res = bookingsCollection.get(flightId); - } catch (DocumentNotFoundException ex) { - throw new RuntimeException("Unable to retrieve flight id " + flightId); - } - Map flight = res.contentAsObject().toMap(); - results.add(flight); - } - - String queryType = String.format("KV get - scoped to %s.user: for %d bookings in document %s", scope.name(), - results.size(), username); - return Result.of(results, queryType); -} ----- - - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=data-model] - -include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=rest-api] - - -// TODO: we don't use the partial here, because of the location of swagger.json -// in try-cb-dotnet/wwwroot/ -== REST API +include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=models] -You can explore the REST API here in read-only mode, or once you are running the application, at the `/apidocs` endpoint. -// swagger_ui::https://raw.githubusercontent.com/couchbaselabs/{travel-sample-git-project}/HEAD/try-cb-dotnet/wwwroot/swagger.json[] -swagger_ui::https://raw.githubusercontent.com/couchbaselabs/try-cb-java/7.0/swagger.json[] -//// diff --git a/modules/hello-world/pages/sdk-authentication.adoc b/modules/hello-world/pages/sdk-authentication.adoc deleted file mode 100644 index b1bfb6e2..00000000 --- a/modules/hello-world/pages/sdk-authentication.adoc +++ /dev/null @@ -1,5 +0,0 @@ - - - - -:page-aliases: sdk-authentication-overview diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 6a0b776f..14173f3e 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -3,133 +3,71 @@ :page-toclevels: 3 :description: Install, connect, try. A quick start guide to get you up and running with Couchbase and the {name-sdk}. :forum-link: https://www.couchbase.com/forums/c/java-sdk/5 +:complete-code-include: include::devguide:example$java/StartUsingCapella.java[] +// implementation 'com.couchbase.client:java-client:{sdk_current_version}' :page-partial: // Note to editors // // This page pulls in content from -// https://github.com/couchbase/docs-sdk-common/blob/release/7.6/modules/shared/partials/start-using-sdk.adoc +// https://github.com/couchbase/docs-sdk-common/blob/api/3.10/modules/shared/partials/start-using-sdk.adoc // // and code samples from -// https://github.com/couchbase/docs-sdk-java/tree/release/3.8/modules/devguide/examples/java +// https://github.com/couchbase/docs-sdk-java/tree/release/3.12/modules/devguide/examples/java // // It can be seen built at -// https://docs.couchbase.com/java-sdk/3.8/hello-world/start-using-sdk.html +// https://docs.couchbase.com/java-sdk/3.12/hello-world/start-using-sdk.html + [abstract] {description} +// intro +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=intro] -Couchbase has a simple interface for creating and modifying records in a document, -based upon the *collection* into which the documents are organized. -You can read more about data modeling <>, -but first let's look at those data operations, and installing the {name-sdk}. - -// remember to add a nomenclature note to the next version of this page for LCB. +// upsert snippet .Upsert with Replication set to xref:concept-docs:data-durability-acid-transactions.adoc#durable-writes[Majority Durablity]: - [source,java] ---- collection.upsert("my-document", JsonObject.create().put("doc", true), upsertOptions().durability(DurabilityLevel.MAJORITY)); ---- -`upsert` inserts (creates) the document if it does not exist, or replaces it if it does. -We'll explore creating and retrieving data records in more detail <> -(and touch lightly upon a little of Java's functional programming approach as we go), -after walking through a quick installation. -TIP: This page walks you through a quick installation, and CRUD examples against the Data Service. -Elsewhere in this section you can find a fully worked-through xref:hello-world:sample-application.adoc[] and, -for those new to document (NoSQL) databases, our xref:hello-world:student-record-developer-tutorial.adoc[Student Record Tutorial]. +// intro-upsert +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=intro-upsert] -== Before You Start +// TIP - DEE tutoral & Student record tutorial +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=other-tutorials] -Couchbase Capella, our Database-as-a-Service, lets you get on with what matters, while we take care of the administration for you. -Alternately, if you need to control every aspect of deployment -- -or just want to run the Server in a VM on your laptop -- -there are several self-managed options available: -[tabs] -==== -Couchbase Capella:: -+ --- -If you haven't already got a cluster set up, the easiest route is to https://cloud.couchbase.com/sign-up[sign up to Couchbase Capella and deploy a free tier cluster^], -then come back to this page. -Make a note of the xref:cloud:get-started:connect.adoc[endpoint] to connect to, -and remember the credentials for the user that you set up. --- -Self-Managed Couchbase Server:: -+ --- -Install Couchbase Server locally, or in your private Cloud: - -* xref:{version-server}@server:install:get-started.adoc[Deployment overview] -* xref:{version-server}@server:install:getting-started-docker.adoc[Docker Install] -* xref:operator::overview.adoc[Couchbase Autonomous Operator] -** xref:operator::install-kubernetes.adoc[Kubernetes] -** xref:operator::install-openshift.adoc[Openshift] -* xref:{version-server}server:cloud:couchbase-cloud-deployment.adoc[Cloud Marketplace]: -** xref:{version-server}@server:cloud:couchbase-aws-marketplace.adoc[AWS Marketplace] -** xref:{version-server}@server:cloud:couchbase-azure-marketplace.adoc[Azure Marketplace] -** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace] - -For the example code below to run, you'll need the username and password of the Administrator user that you create, and the IP address of at least one of the nodes of the cluster. --- -==== +== Before You Start + +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=before] + // Script the docs! // Can any of the SDK installations be scripted? + + === Prerequisites -* The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- +* The Java SDK is tested against LTS versions of OpenJDK -- see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. + https://adoptium.net/[OpenJDK {java_latest_lts_version} with HotSpot JVM] is recommended. -The code examples also assume: -[tabs] -==== -Couchbase Capella:: -+ --- -* You have signed up to https://cloud.couchbase.com/sign-up[Couchbase Capella]. - -* You have created your own bucket, or loaded the Travel Sample dataset. -Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster. +// self-managed + Capella pre-reqs +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=prereq] -* A user is created with permissions to access the cluster (at least Application Access permissions). -See the xref:cloud:get-started:cluster-and-data.adoc#credentials[Capella connection page] for more details. - -IMPORTANT: Couchbase Capella uses xref:cloud:organizations:organization-projects-overview.adoc[Roles] to control user access to cluster resources. -For the purposes of this guide, you can use the *Organization Owner* role automatically assigned to your account during installation of the Capella cluster. -In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. --- - -Self-Managed Couchbase Server:: -+ --- -* xref:{version-server}@server:getting-started/do-a-quick-install.adoc[Couchbase Server] is installed and accessible locally. - -* You have created your own bucket, or loaded the Travel Sample dataset using the xref:{version-server}@server:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Web interface]. - -* A user is created with permissions to access your cluster (at least Application Access permissions). -See xref:{version-server}@server:manage:manage-security/manage-users-and-roles.adoc[Manage Users, Groups and Roles] for more details. - -IMPORTANT: Couchbase Server uses xref:{version-server}@server:learn:security/roles.adoc[Role-Based Access Control (RBAC)] to control access to cluster resources. -In this guide we suggest using the *Full Admin* role created during setup of your local Couchbase Server cluster. -In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. --- -==== == Installation @@ -173,28 +111,15 @@ implementation 'com.couchbase.client:java-client:{sdk_current_version}' ==== // end::quick-install[] + === IDE Plugins -To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors. -For links and more information on these and other integrations across the {name_platform} ecosystem, -check out the xref:project-docs:third-party-integrations.adoc[] page. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=ide] === Grab the Code -If you're all set up and in a real hurry, just grab this code sample and add in your Capella details. - -.Complete Hello World code sample [*Click to open or collapse the listing*] -[%collapsible] -==== -.... -include::devguide:example$java/StartUsingCapella.java[] -.... -==== - -Otherwise, read on as we introduce the CRUD API and connection to Capella or self-managed Couchbase Server. - -TIP: There's a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages, and a *Copy* icon to grab just the snippet shown. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=complete-code] == Connect to your Database @@ -233,7 +158,7 @@ Cloud Native Gateway (CNG):: Couchbase's large number of ports across the URLs of many services can be proxied by using a `couchbase2://` endpoint as the connection string -- currently only compatible with recent versions of xref:operator:ROOT:concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator]: -[source,scala] +[source,java] ---- Cluster cluster = Cluster.connect( "couchbase2://10.12.14.16", @@ -262,12 +187,7 @@ quarkus.couchbase.password=password -- ==== - -For a deeper look at connection options, read xref:howtos:managing-connections.adoc[]. - -TIP: The connection code for getting started uses the Administrator password that you were given during set up. -In any production app you should create a role restricted to the permissions needed for your app -- -more on this in xref:concept-docs:best-practices.adoc#roles-and-rbac[the Security documentation]. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=deeper-conn] The `ClusterEnvironment.Builder` is covered more fully on the xref:ref:client-settings.adoc#the-environment-builder[Client Settings] page. @@ -318,13 +238,13 @@ include::devguide:example$java/StartUsingCapella.java[tag=collection,indent=0] == Create, Read, Update, Delete -Couchbase documents are organized into buckets, scopes, and collections. -https://en.wikipedia.org/wiki/CRUD[CRUD operations^] -- Create, Read, Update, Delete -- can be performed upon documents in a collection. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=crud] + === JSON We'll create a snippet of JSON to work with, using the client's own JSON library, -but you can read about the Scala SDK's support for other JSON libraries on the +but you can read about the {name-sdk}'s support for other JSON libraries on the xref:howtos:json.adoc[] page. [source,java] @@ -352,7 +272,7 @@ include::devguide:example$java/StartUsingCapella.java[tag=upsert,indent=0] The `get` method reads a document from a collection. // If the collection does not have a document with this ID, the `get` method also throws `DocumentNotFoundException`. -Wrapping the method in a `Try` / `Catch` is a good way to handle exceptions: +Wrapping the method in a `try` / `catch` is a good way to handle exceptions: [source,java] ---- @@ -433,29 +353,13 @@ try { } ---- -Like `replace`, `remove` also optionally takes the CAS value if you want to make sure you are only removing the document if it hasn’t changed since you last fetched it. +Like `replace`, `remove` also optionally takes the xref:howtos:kv-operations.adoc#what-is-cas[CAS value] if you want to make sure you are only removing the document if it hasn’t changed since you last fetched it. == Data Modeling -Documents are organized into collections -- collections of documents that belong together. -You get to decide what it means to "belong." -Developers usually put documents of the same type in the same collection. - -For example, imagine you have two types of documents: customers and invoices. -You could put the customer documents in a collection called `customers`, and the invoice documents in a collection called `invoices`. - -Each document belongs to exactly one collection. -A document's ID is unique _within_ the collection. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=data-model] -Different scopes can hold collections with different names. -There is no relationship between collections in different scopes. -Each collection belongs to just one scope and -a collection's name is unique within the scope. - - -More details can be found on the xref:concept-docs:data-model.adoc[Data Model page]. -// The xref:student-record-developer-tutorial.adoc[Student Records Tutorial] gives an introduction to data modeling in a document database alongside using the {name-sdk}. == What Next? @@ -467,18 +371,4 @@ both //// - -=== Help and Troubleshooting - -* xref:howtos:troubleshooting-cloud-connections.adoc[Troubleshooting common network problems]. -* {forum-link}[Help forum]. -* https://discord.com/channels/915294689681362954/1217642561645318194[Discord channel]. -* Read the xref:howtos:error-handling.adoc[error handling page]. -* xref:cloud:get-started:capella-iq/get-started-with-iq.adoc#generate-sdk-code-preview[Get help from Couchbase iQ]. - -=== Next Steps - -// * Take a look at the xref:hello-world:sample-application.adoc[]. -* xref:concept-docs:data-durability-acid-transactions.adoc[Learn more about the Data Service]. -* xref:concept-docs:querying-your-data.adoc[Discover SQL++] -- our SQL-family querying language. -* Explore some of the xref:project-docs:third-party-integrations.adoc[third party integrations] with Couchbase and the {name_platform} SDK, across the {name_platform} ecosystem. +include::{version-common}@sdk:shared:partial$start-using-sdk.adoc[tag=what-next] diff --git a/modules/hello-world/partials/alpha-warning.adoc b/modules/hello-world/partials/alpha-warning.adoc deleted file mode 100644 index a0b5844e..00000000 --- a/modules/hello-world/partials/alpha-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Alpha_ of the Couchbase Java SDK. -As such they are likely to change without notice. -This alpha code _should not_ be used in production. - -Documentation is incomplete, subject to change, and likely to contain broken links. -==== diff --git a/modules/hello-world/partials/beta-warning.adoc b/modules/hello-world/partials/beta-warning.adoc deleted file mode 100644 index 7bd1139e..00000000 --- a/modules/hello-world/partials/beta-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Beta_ release of the Couchbase Java SDK. -The API interface is stable, but could change for bug fixes during the Beta process. -New features are likely to be added. - -Documentation is incomplete, subject to change, and could contain broken links. -==== diff --git a/modules/howtos/pages/advanced-analytics-querying.adoc b/modules/howtos/pages/advanced-analytics-querying.adoc deleted file mode 100644 index 0616006f..00000000 --- a/modules/howtos/pages/advanced-analytics-querying.adoc +++ /dev/null @@ -1,2 +0,0 @@ -= Advanced Analytics Querying - diff --git a/modules/howtos/pages/analytics-using-sdk.adoc b/modules/howtos/pages/analytics-using-sdk.adoc index 7a7128b8..236250c2 100644 --- a/modules/howtos/pages/analytics-using-sdk.adoc +++ b/modules/howtos/pages/analytics-using-sdk.adoc @@ -1,6 +1,6 @@ = Analytics :description: Parallel data management for complex queries over many records, using a familiar SQL-like syntax. -:page-aliases: analytics-query.adoc +:page-aliases: analytics-query.adoc,concept-docs:analytics-for-sdk-users.adoc :page-edition: Enterprise Edition [abstract] diff --git a/modules/howtos/pages/collecting-information-and-logging.adoc b/modules/howtos/pages/collecting-information-and-logging.adoc index 6f55726d..117a386c 100644 --- a/modules/howtos/pages/collecting-information-and-logging.adoc +++ b/modules/howtos/pages/collecting-information-and-logging.adoc @@ -258,28 +258,5 @@ Once the SDK writes the logs with the tags to a file, you can then use the xref: == SDK Telemetry from the Server -In addition to Tracing and other metrics, and client logging, SDK telemetry is also sent to the Server -- available from 8.0, and in new Capella Operational clusters -- for ingestion with other Prometheus metrics. -Capella Operatioal exposes these metrics through the UI. - -For self-managed Server, collection can be disabled and enabled through the REST API: - -[source,console] ----- -curl --user Administrator:password http://172.17.0.2:8091/settings/appTelemetry -d enabled=true ----- - -And the Prometheus-format metrics fetched with: - -[source,console] ----- -curl --user Administrator:password http://172.17.0.2:8091/metrics ----- - -Further details can be found in the xref:{version-server}@server:rest-api:application-telemetry.adoc[] page. - -There may be advantages to collecting information this way, -but note that metrics are collected per node, -and a central Prometheus instance should be set to collect all metrics so that information is not lost in case of a sudden failover. - -Also note that if the cluster is behind a load balancer, the collected metrics may not accurately record the actual correct node with which the SDK interacts. +include::{version-common}@sdk:shared:partial$logging.adoc[tag=telemetry] diff --git a/modules/howtos/pages/concurrent-async-apis.adoc b/modules/howtos/pages/concurrent-async-apis.adoc index 4da916ee..aef18db7 100644 --- a/modules/howtos/pages/concurrent-async-apis.adoc +++ b/modules/howtos/pages/concurrent-async-apis.adoc @@ -85,6 +85,9 @@ In all other cases, the blocking API (for simplicity) or the reactive API (for r == Batching +include::{version-common}@sdk:shared:partial$best-practices.adoc[tag=bulk-get-sidebar] + + The SDK itself does not provide explicit APIs for batching, because using the reactive mechanisms it allows you to build batching code applied to your use case much better than a generic implementation could in the first place. While it can be done with the async API as well, we recommend using the reactive API so you can use async retry and fallback mechanisms that are supplied out of the box. @@ -134,7 +137,7 @@ include::devguide:example$java/AsyncOperations.java[tag=retry-bulk] It is recommended to check out the `retry` and `retryBackoff` methods for their configuration options and overloads. Of course, all the operators shown here can be combined to achieve exactly the semantics you need. -Finally, for even advanced retry policies you can utilize the retry functionality in the https://projectreactor.io/docs/extra/release/api/reactor/retry/Retry.html[reactor-extra^] package. +Finally, for even more advanced retry policies you can utilize the retry functionality in the https://projectreactor.io/docs/extra/release/api/reactor/retry/Retry.html[reactor-extra^] package. == Reactive Streams Integration diff --git a/modules/howtos/pages/concurrent-document-mutations.adoc b/modules/howtos/pages/concurrent-document-mutations.adoc index a49dc622..294edf6e 100644 --- a/modules/howtos/pages/concurrent-document-mutations.adoc +++ b/modules/howtos/pages/concurrent-document-mutations.adoc @@ -1,8 +1,8 @@ = Concurrent Document Mutations :page-topic-type: howto -include::project-docs:partial$attributes.adoc[] +:description: You can use the CAS value to control how concurrent document modifications are handled :page-aliases: ROOT:concurrent-document-mutations.adoc -// ,7.6@server:developer-guide:cas-concurrency.adoc +// ,8.0@server:developer-guide:cas-concurrency.adoc include::{version-common}@sdk:shared:partial$cas.adoc[tag=intro] diff --git a/modules/howtos/pages/error-handling.adoc b/modules/howtos/pages/error-handling.adoc index a376f205..a14067e1 100644 --- a/modules/howtos/pages/error-handling.adoc +++ b/modules/howtos/pages/error-handling.adoc @@ -2,11 +2,13 @@ :description: Errors are inevitable. That's why the SDK has very extensive error handling and retry capabilties :navtitle: Handling Errors :page-aliases: ROOT:handling-error-conditions.adoc,handling-error-conditions.adoc,errors.adoc,handling-errors.adoc +:page-toclevels: 2 [abstract] {description} which are focussed on one goal: keeping your application available as best as possible even in the face of (transient) failures. + Unfortunately, the SDK alone can't make all the decisions needed since it lacks the understanding of your application domain. In most cases transparent retry is the best choice, but maybe sometimes you need to fail quickly and switch over to an alternate data source. On this page you will learn about basic and advanced error handling mechanisms, as well as the fundamentals that hold them all together. @@ -35,7 +37,7 @@ All the specifics are discussed below, but a broad categorization of exceptions For example, if you perform an `insert` operation and the document already exists, the SDK will fail the operation with a `DocumentExistsException`. 2. Failures in all other cases, especially during pre-dispatch and dispatch, will result in either a `TimeoutException` or a `RequestCanceledException`. -=== The Ubiquitous TimeoutException +=== TimeoutException -- Ambiguous or Unambiguous The one exception that you are inevitably going to hit is the `TimeoutException`, or more specifically its child implementations the `UnambiguousTimeoutException` and the `AmbiguousTimeoutException`. diff --git a/modules/howtos/pages/full-text-searching-with-sdk.adoc b/modules/howtos/pages/full-text-searching-with-sdk.adoc index 4c7173b5..70266211 100644 --- a/modules/howtos/pages/full-text-searching-with-sdk.adoc +++ b/modules/howtos/pages/full-text-searching-with-sdk.adoc @@ -21,7 +21,6 @@ There are two APIs for querying search: `cluster.searchQuery()`, and `cluster.se Both are also available at the Scope level. The former API supports Search queries (`SearchQuery`), while the latter additionally supports the `VectorSearch` added in 7.6. -Most of this documentation will focus on the former API, as the latter is in @Stability.Volatile status. We will perform a Search query here -- see the xref:vector-searching-with-sdk.adoc[Vector Search] docs for examples of Vector and xref:vector-searching-with-sdk.adoc#combining-fts-and-vector-queries[combining Vector and Search queries]. diff --git a/modules/howtos/pages/health-check.adoc b/modules/howtos/pages/health-check.adoc index 96a4f915..db933eb1 100644 --- a/modules/howtos/pages/health-check.adoc +++ b/modules/howtos/pages/health-check.adoc @@ -10,19 +10,14 @@ {description} +// intro +include::{version-common}@sdk:shared:partial$health-check.adoc[tag="intro"] -In today's distributed and virtual environments, users will often not have full administrative control over their whole network. -Working in distributed environments is hard. Latencies come and go, so do connections in their entirety. -Is it a network glitch, or is the remote cluster down? -Sometimes just knowing the likely cause is enough to get a good start on a workaround, or at least avoid hours wasted on an inappropriate solution. - -Health Check features _Ping_ to check nodes are still healthy, and to force idle connections to be kept alive in environments with eager shutdowns of unused resources. -_Diagnostics_ requests a report from a node, giving instant health check information. // Uses -include::{version-common}@sdk:pages:partial$health-check.adoc[tag="uses"] +include::{version-common}@sdk:shared:partial$health-check.adoc[tag="uses"] @@ -36,7 +31,7 @@ At its simplest, `ping` provides information about the current state of the conn [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-basic] +include::devguide:example$java/HealthCheck.java[tag=ping-basic,indent=0] ---- This will print the latency for each socket (endpoint) connected per service. More information is available on the classes. @@ -45,7 +40,7 @@ This is made easy by the `exportToJson` method: [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-json-export] +include::devguide:example$java/HealthCheck.java[tag=ping-json-export,indent=0] ---- By default the SDK will ping all services available on the target cluster. @@ -53,7 +48,7 @@ You can customize the type of services to ping through the `PingOptions`: [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=ping-options] +include::devguide:example$java/HealthCheck.java[tag=ping-options,indent=0] ---- In this example, only the Query service is included in the ping report. @@ -72,13 +67,13 @@ This makes it much cheaper to call on a regular basis, but does not provide any [source,java] ---- -include::devguide:example$java/HealthCheck.java[tag=diagnostics-basic] +include::devguide:example$java/HealthCheck.java[tag=diagnostics-basic,indent=0] ---- Because it is passive, diagnostics are only available at the `Cluster` level and cover everything in the current SDK state. Also, because it is not doing any I/O you cannot proactively filter the list of services that are returned, all you need to do is look only at the ones that are interesting to you. A `DiagnosticsResult` has one interesting property over a ping result -- it provides a cumulative `ClusterState` through the `state()` method. -The state can be `ONLINE`, `DEGRADED` or `OFFLINE`. +The state can be `ONLINE`, `DEGRADED`, or `OFFLINE`. This allows to give a single, although simplistic, view on how your cluster is doing from a client point of view. The state is determined as follows: diff --git a/modules/howtos/pages/json.adoc b/modules/howtos/pages/json.adoc index dcaa0fe8..a421bc6f 100644 --- a/modules/howtos/pages/json.adoc +++ b/modules/howtos/pages/json.adoc @@ -3,7 +3,9 @@ :navtitle: JSON Modelling :page-toclevels: 2 -include::project-docs:partial$attributes.adoc[] + +[abstract] +{description} == Philosophy diff --git a/modules/howtos/pages/kv-operations.adoc b/modules/howtos/pages/kv-operations.adoc index 59bcfae9..205f535a 100644 --- a/modules/howtos/pages/kv-operations.adoc +++ b/modules/howtos/pages/kv-operations.adoc @@ -1,9 +1,8 @@ = Data Operations -:description: Data service offers the simplest way to retrieve or mutate data where the key is known. +:description: The Data Service offers the simplest way to retrieve or mutate data where the key is known. :page-aliases: ROOT:document-operations.adoc,ROOT:documents-creating.adoc,ROOT:documents-updating.adoc,ROOT:documents-retrieving.adoc,ROOT:documents-deleting.adoc -// :example-source: 3.8@java-sdk:devguide:example$java/Queries.java +// :example-source: 3.13@java-sdk:devguide:example$java/Queries.java :page-toclevels: 3 -:page-pagination: full @@ -16,27 +15,23 @@ as well as KV Range scan, for querying without an index. The complete code sample used on this page can be downloaded from https://github.com/couchbase/docs-sdk-java/blob/release/{sdk_dot_minor}/modules/devguide/examples/java/KvOperations.java[here]. -At its heart Couchbase Server is a high-performance key-value store, and the key-value interface outlined below is the fastest and best method to perform operations involving single documents. -A _document_ refers to an entry in the database (other databases may refer to the same concept as a _row_). -A document has an ID (_primary key_ in other databases), which is unique to the document and by which it can be located. -The document also has a value which contains the actual application data. -See xref:concept-docs:documents.adoc[the concept guide to _Documents_] for a deeper dive into documents in the Couchbase Data Platform. +// intro +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=intro] -Before proceeding, make sure you're familiar with the basics of authorization and connecting to a Cluster from the xref:hello-world:start-using-sdk.adoc[Start Using the SDK] section. +//// The code samples below will use these imports: [source,java] ---- include::devguide:example$java/KvOperations.java[tag=imports] ---- +//// -[TIP] -.{sqlpp} vs. Key-Value -==== -{sqlpp_url}[{sqlpp} (formerly N1QL)] can also be used to perform many single-document operations but we very strongly recommend using the key-value API for this instead, as it can be much more efficient. The request can go directly to the correct node, there's no query parsing overhead, and it's over the highly optimized memcached binary protocol. -==== + +//{sqlpp} vs. Key-Value +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=sql-vs-kv] == JSON @@ -52,13 +47,10 @@ The SDK also supports custom transcoders and serializers which are covered separ == CRUD -[TIP] -.Sub-Document Operations -==== -All of these operations involve fetching the complete document from the Cluster. -Where the number of operations or other circumstances make bandwidth a significant issue, -the SDK can work on just a specific _path_ of the document with xref:subdocument-operations.adoc[Sub-Document Operations]. -==== +// Sub-Document Operations +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=subdoc] + + === Upsert @@ -128,15 +120,13 @@ Then we `get` it back into `doc` and pull out the document's content as a `JsonO Afterwards, we update a field in the `JsonObject` with `put`. `JsonObject` is mutable, we don't need to store the result of the `put`. Finally, we `replace` the document with the updated content, and a CAS value, storing the final result as `result`. + + ==== What is CAS? -CAS, or Compare And Swap, is a form of optimistic locking. Every document in Couchbase has a CAS value, and it's changed on every mutation. -When you `get` a document you also get the document's CAS, and then when it's time to write the document, you send the same CAS back. -If another thread or program has modified that document in the meantime, the Couchbase Server can detect you've provided a now-outdated CAS, and return an error. -This provides cheap, safe concurrency. -See xref:concurrent-document-mutations.adoc[this detailed description of CAS] for further details. +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=cas] + -In general, you'll want to provide a CAS value whenever you `replace` a document, to prevent overwriting another agent's mutations. === Retrying on CAS failures @@ -168,6 +158,7 @@ include::devguide:example$java/KvOperations.java[tag=remove,indent=0] Like `replace`, `remove` also optionally takes the CAS value if you want to make sure you are only removing the document if it hasn't changed since you last fetched it. + == Durability Writes in Couchbase are written to a single node, and from there the Couchbase Server will take care of sending that mutation to any configured replicas. @@ -185,9 +176,9 @@ If no argument is provided the application will report success back as soon as t However, we recognize that there are times when the application needs that extra certainty that especially vital mutations have been successfully replicated, and the other durability options provide the means to achieve this. -The options differ depend on what Couchbase Server version is in use. -If 6.5 or above is being used, you can take advantage of the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[Durable Write] feature, -in which Couchbase Server will only return success to the SDK after the requested replication level has been achieved. +If you need stronger durability guarantees, +you can take advantage of the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[Durable Write] feature, +in which Couchbase Server (self-managed or Capella) will only return success to the SDK after the requested replication level has been achieved. The three replication levels are: * `Majority` -- The server will ensure that the change is available in memory on the majority of configured replicas. @@ -198,16 +189,16 @@ The options are in increasing levels of safety. Note that nothing comes for free -- for a given node, waiting for writes to storage is considerably slower than waiting for it to be available in-memory. These tradeoffs, as well as which settings may be tuned, are discussed in the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[durability page]. -// remove 6.5 stuff once 8.0 is released? -If a version of Couchbase Server lower than 6.5 is being used then the application can fall-back to xref:concept-docs:durability-replication-failure-considerations.adoc#older-server-versions['client verified' durability]. -Here the SDK will do a simple poll of the replicas and only return once the requested durability level is achieved. -This can be achieved like this: -[source,java] ----- -include::devguide:example$java/KvOperations.java[tag=durability-observed,indent=0] ----- + +This durability is enforced by the cluster. +A client verified durability API was necessary with older, no longer supported version of Couchbase Server. +This API is still avaialable, but there are few cases where you would want to use this less performant option. +Details can be found +https://docs-archive.couchbase.com/java-sdk/3.3/concept-docs/durability-replication-failure-considerations.html#older-server-versions[in our archived docs]. + + To stress, durability is a useful feature but should not be the default for most applications, as there is a performance consideration, and the default level of safety provided by Couchbase will be reasonable for the majority of situations. @@ -243,20 +234,13 @@ include::devguide:example$java/KvOperations.java[tag=expiry-get,indent=0] ---- Note that when updating the document, special care must be taken to avoid resetting the expiry to zero. -If you are using Couchbase Server 7.0 or later, set the `preserveExpiry` option when updating the document: +Set the `preserveExpiry` option when updating the document: [source,java] ---- include::devguide:example$java/KvOperations.java[tag=preserve-expiry,indent=0] ---- -Prior to Couchbase 7.0, it's necessary to fetch the previous expiry and set it again: - -[source,java] ----- -include::devguide:example$java/KvOperations.java[tag=expiry-replace,indent=0] ----- - Some applications may find `getAndTouch` useful, which fetches a document while updating its expiry field. It can be used like this: @@ -269,6 +253,7 @@ include::devguide:example$java/KvOperations.java[tag=expiry-touch,indent=0] == Atomic Counters The value of a document can be increased or decreased atomically using `collecion.binary().increment()` and `collection.binary().decrement()`. + //// .Increment [source,csharp] @@ -294,7 +279,8 @@ include::example$KvOperations.cs[tag=binarydecrement,indent=0] include::example$KvOperations.cs[tag=binarydecrementwithoptions,indent=0] ---- //// -NOTE: Increment & Decrement are considered part of the ‘binary’ API and as such may still be subject to change + +NOTE: Increment & Decrement are considered part of the "binary" API and as such may still be subject to change See the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/kv/Increment.html[API Reference] for full details. @@ -309,7 +295,7 @@ include::{version-common}@sdk:shared:partial$atomic.adoc[tag=xdcr] == Scoped KV Operations -It is possible to perform scoped key-value operations on named xref:{version-server}@server:learn:data/scopes-and-collections.adoc[`Collections`] _with Couchbase Server release 7.x_. +It is possible to perform scoped key-value operations on named xref:{version-server}@server:learn:data/scopes-and-collections.adoc[`Collections`]. See the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/Collection.html[API docs] for more information. Here is an example showing an upsert in the `users` collection, which lives in the `travel-sample.tenant_agent_00` keyspace: @@ -392,12 +378,4 @@ Setting `idsOnly` to true also works with the other scan types described above. == Additional resources -Working on just a specific path within a JSON document will reduce network bandwidth requirements -- see the xref:subdocument-operations.adoc[Sub-Document] pages. - -For a significant performance speed up with large volumes of data, reference our xref:concurrent-async-apis.adoc[asynchronous programming options]. - -Another way of increasing network performance is to _pipeline_ operations with xref:concurrent-async-apis.adoc#batching[Batching Operations]. - -As well as various xref:concept-docs:data-model.adoc[Formats] of JSON, Couchbase can work directly with xref:concept-docs:nonjson.adoc[arbitrary bytes, or binary format]. - -Our xref:sqlpp-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of {sqlpp}. +include::{version-common}@sdk:shared:partial$data-service.adoc[tag=resources] diff --git a/modules/howtos/pages/managing-connections.adoc b/modules/howtos/pages/managing-connections.adoc index dfe78854..ff5c0e36 100644 --- a/modules/howtos/pages/managing-connections.adoc +++ b/modules/howtos/pages/managing-connections.adoc @@ -4,7 +4,7 @@ :page-aliases: ROOT:managing-connections.adoc,howtos:multi-network.adoc,ROOT:connecting.adoc,ROOT:connection-advanced.adoc :page-toclevels: 2 -include::project-docs:partial$attributes.adoc[] + [abstract] {description} @@ -21,8 +21,6 @@ The simplest way to create a `Cluster` object is to call `Cluster.connect()` wit include::devguide:example$java/ManagingConnections.java[tag=simpleconnect,indent=0] ---- -NOTE: If you are connecting to a version of Couchbase Server older than 6.5, it will be more efficient if the addresses are those of data (KV) nodes. -You will in any case, with 7.0 and earlier, need to open a `Bucket` instance before connecting to any other HTTP services (such as _Query_ or _Search_). In a production environment, your connection string should include the addresses of multiple server nodes in case some are currently unavailable. Multiple addresses may be specified in a connection string by delimiting them with commas: @@ -121,9 +119,9 @@ If your Couchbase Server cluster is running in a containerized, port mapped, or Both the client and server require special configuration in this case. On the server side, each server node must be configured to advertise its external address as well as any custom port mapping. -This is done with the `setting-alternate-address` CLI command introduced in Couchbase Server 6.5. +This is done with the `setting-alternate-address` CLI command -- +see the xref:server:cli:cbcli/couchbase-cli-setting-alternate-address.adoc[reference] for further information. A node configured in this way will advertise two addresses: one for connecting from the same network, and another for connecting from an external network. -// todo link to https://docs.couchbase.com/server/7.0/cli/cbcli/couchbase-cli-setting-alternate-address.html On the client side, the externally visible ports must be used when connecting. If the external ports are not the default, you can specify custom ports in the connection string when calling `Cluster.connect()`. @@ -286,10 +284,7 @@ quarkus.couchbase.password=password == Cloud Native Gateway -Couchbase's next generation connection protocol, introduced in Java SDK 3.5 and xref:operator::concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator 2.6.1], can be enabled simply by changing the connection string to `couchbase2://` but there are a few differences to be aware of, described <<#limitations,below>>. - -The protocol implements a gRPC-style interface between the SDK and Couchbase Server (in this case, only available in the Server running on Kubernetes or OpenShift, with a recent version of xref:operator::overview.adoc[Couchbase Autonomous Operator]). - +include::{version-common}@sdk:shared:partial$managing-connections.adoc[tag=cng] === Limitations @@ -373,9 +368,17 @@ _plus_ it waits for the K-V (data) sockets to be ready. Other timeout issues may occur when using the SDK located geographically separately from the Couchbase Server cluster -- this is xref:project-docs:compatibility#network-requirements[not recommended]. See the xref:#working-in-the-cloud[Cloud section] below for some suggestions of settings adjustments. + + + + +== Working in the Cloud + include::{version-common}@sdk:shared:partial$managing-connections.adoc[tag=cloud] + + == Async and Reactive APIs The Couchbase Java SDK provides first-class support for asynchronous and reactive programming. @@ -415,5 +418,4 @@ Here's the same example, but using the Reactive API instead of the Async API: include::devguide:example$java/ManagingConnections.java[tag=reactivecluster,indent=0] ---- - -// == Working in the Cloud +See the xref:concurrent-async-apis.adoc[] page for more information. diff --git a/modules/howtos/pages/provisioning-cluster-resources.adoc b/modules/howtos/pages/provisioning-cluster-resources.adoc index 98d20609..103d9365 100644 --- a/modules/howtos/pages/provisioning-cluster-resources.adoc +++ b/modules/howtos/pages/provisioning-cluster-resources.adoc @@ -1,7 +1,7 @@ = Provisioning Cluster Resources :description: Provisioning cluster resources is managed at the collection or bucket level, depending upon the service affected. :navtitle: Provisioning Cluster Resources -:page-aliases: ROOT:managing-clusters.adoc +:page-aliases: ROOT:managing-clusters.adoc,concept-docs:buckets-and-clusters.adoc :page-toclevels: 2 // API refs diff --git a/modules/howtos/pages/sdk-authentication.adoc b/modules/howtos/pages/sdk-authentication.adoc index f854bdcb..387c5dbe 100644 --- a/modules/howtos/pages/sdk-authentication.adoc +++ b/modules/howtos/pages/sdk-authentication.adoc @@ -12,7 +12,7 @@ include::project-docs:partial$attributes.adoc[] Our xref:hello-world:start-using-sdk.adoc[Getting Started] guide covered the basics for authorizing against a Couchbase cluster, but you may need to use alternative authentication methods such as Certification. -== RBAC +== Basic Authentication Our xref:hello-world:start-using-sdk.adoc[Getting Started] guide introduced basic authentication against a Couchbase cluster: @@ -37,6 +37,9 @@ include::devguide:example$java/Auth.java[tag=rbac-pwd,indent=0] In this example, the `PLAIN` authentication mechanism is enabled as well, which is needed if LDAP is enabled on the server side and no TLS encrypted connection is used. + +== RBAC + include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=rbac] include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=cert-auth] diff --git a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc index 3bdada2c..8f1eb14a 100644 --- a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc +++ b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc @@ -242,7 +242,7 @@ This query will stream all rows as they become available from the server, automa == Querying at Scope Level It is possible to query off the xref:concept-docs:n1ql-query.adoc#collections-and-scopes-and-the-query-context[`Scope` level], -_with Couchbase Server release 7.x_, using the `scope.query()` method. +using the `scope.query()` method. It takes the statement as a required argument, and then allows additional options if needed. A complete list of `QueryOptions` can be found in the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/AsyncScope.html#query-java.lang.String-[API docs]. diff --git a/modules/howtos/pages/view-queries-with-sdk.adoc b/modules/howtos/pages/view-queries-with-sdk.adoc index 3f19b4f5..a9c42374 100644 --- a/modules/howtos/pages/view-queries-with-sdk.adoc +++ b/modules/howtos/pages/view-queries-with-sdk.adoc @@ -31,7 +31,7 @@ CAUTION: If you are provisioning Views on Couchbase Server for a legacy applicat xref:{version-server}@server:learn:buckets-memory-and-storage/storage-engines.adoc#couchstore[couchstore] bucket_. -We will maintain support for Views in the SDKs for so long as it can be used with a supported version of Couchbase Server. +Use of Views in the {name-sdk} is now deprecated. Information on using MapReduce Views with the SDK can still be accessed in our https://docs-archive.couchbase.com/java-sdk/3.1/howtos/view-queries-with-sdk.html[documentation archive]. diff --git a/modules/howtos/partials/alpha-warning.adoc b/modules/howtos/partials/alpha-warning.adoc deleted file mode 100644 index 1bb83349..00000000 --- a/modules/howtos/partials/alpha-warning.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Required attributes: -// :lang: Java -// :version: 3.0.0 alpha -[WARNING] -==== -These pages cover the _Alpha_ of the Couchbase Java SDK. -As such they are likely to change without notice. -This alpha code _should not_ be used in production. - -Documentation is incomplete, subject to change, and likely to contain broken links. -==== diff --git a/modules/howtos/partials/beta-warning.adoc b/modules/howtos/partials/beta-warning.adoc deleted file mode 100644 index 7bd1139e..00000000 --- a/modules/howtos/partials/beta-warning.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Required attributes: -[WARNING] -==== -These pages cover the _Beta_ release of the Couchbase Java SDK. -The API interface is stable, but could change for bug fixes during the Beta process. -New features are likely to be added. - -Documentation is incomplete, subject to change, and could contain broken links. -==== diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index 7ad6e23b..b8bc2e25 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -10,7 +10,7 @@ Plus notes on Cloud, networks, and AWS Lambda. {description} -The {sdk_dot_minor} SDK requires Java 8 or later to be installed. +The {sdk_dot_minor} SDK requires Java 8 or later _Java {java_latest_lts_version} is recommended_. @@ -20,22 +20,7 @@ _Java {java_latest_lts_version} is recommended_. === JDK Version Compatibility -The {name-sdk} is tested with Oracle JDK and OpenJDK. -Other JDK implementations might work but are not tested and are unsupported. -We recommend running the latest LTS version (i.e. at the time of writing JDK {java_latest_lts_version}) with the highest patch version available. - -The following JDK releases are supported: - -* https://adoptium.net/[OpenJDK 25 with HotSpot JVM] (recommended) -* https://adoptium.net/[OpenJDK 21 with HotSpot JVM] -* https://adoptium.net/[OpenJDK 17 with HotSpot JVM] -* https://www.oracle.com/java/technologies/downloads/#jdk17[Oracle JDK 17] -* https://adoptium.net/[OpenJDK 11] (Hotspot recommended) or https://www.oracle.com/java/technologies/downloads/#jdk11[Oracle JDK 11] -* https://adoptium.net/[OpenJDK 1.8 with HotSpot JVM] -* https://www.oracle.com/java/technologies/downloads/#java8[Oracle JDK 1.8] - -Please make sure you run on one of the latest patch releases, since they provide stability improvements and security fixes in general. - +include::{version-common}@sdk:shared:partial$compat.adoc[tag=jdk-compat] === OS Compatibility @@ -44,33 +29,8 @@ In general, the JVM eliminates concerns about underlying OS compatibility, and Couchbase JVM SDKs can be expected to run on all of the Operating Systems supported by xref:{version-server}@server:install:install-platforms.adoc[Couchbase Server]. -The {name-sdk} will run on, and is supported on, the following OSs and platforms. -The SDK has been tested on a representative subset of the platforms listed below. - -**** -[discrete] -=== GNU/Linux +include::{version-common}@sdk:shared:partial$compat.adoc[tag=os-compat] -* Amazon Linux 2 & AL2023. -* Red Hat Enterprise Linux 8, 9, & 10. -* Oracle Linux 8, 9, & 10. -* Ubuntu (LTS) 22.04 (_Jammy_) & 24.04 (_Noble_). -* Debian 11 (_Bullseye_), Debian 12 (_Bookworm_), & Debian 13 (_Trixie_). -* SUSE Enterprise Linux 12 & 15. -* Alpine Linux 3.21 - 3.23. - -[discrete] -=== Microsoft Windows - -* Microsoft Windows 10 & 11; -* Windows Server 2019, 2022, & 2025. - -[discrete] -=== Mac OS X - -The current and previous two releases of OS X. -At time of writing (February 2026): 26 (Tahoe), 15 (Sequoia), and 14 (Sonoma). -**** The JVM SDKs should also be expected to run on other commonly-available GNU/Linux distributions which support an appropriate JDK, but not all combinations can be tested -- notable exceptions are listed below. @@ -113,14 +73,19 @@ The downside of these workarounds is potentially reduced performance, which can // Platforms, Chipsets, and Virtual Environments. -include::{version-common}@sdk:shared:partial$platform.adoc[tag=virtual] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=virtual] // Network Requirements -include::{version-common}@sdk:shared:partial$network-requirements.adoc[] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=network-requirements] + + + +// Serverless Environments +include::{version-common}@sdk:shared:partial$compat.adoc[tag=serverless] @@ -134,18 +99,15 @@ Couchbase SDKs are tested against a variety of different environments to ensure === Couchbase Version/SDK Version Matrix -The matrix below denotes the version of Couchbase Server, the version of the {name-sdk} and whether the SDK is: -* ✖ *Unsupported*: This combination is not tested, and is not within the scope of technical support if you have purchased a support agreement. -* ◎ *Compatible*: This combination has been tested previously, and should be compatible. -evertheless, this combination is not recommended by our technical support organization, as not all of the latest features are supported by it. -It is best to upgrade either the SDK or the Couchbase version you are using. -* ✔ *Supported*: This combination is subject to ongoing quality assurance, and is fully supported by our technical support organization. +include::{version-common}@sdk:shared:partial$compat.adoc[tag=matrix-notes1] + + .Recommended SDK per Server Version Matrix [#table_sdk_versions] |=== -| | 3.4, 3.5 | 3.6, 3.7 | 3.8 | 3.9-3.11 +| | 3.4, 3.5 | 3.6, 3.7 | 3.8 | 3.9-3.13 | *Server 8.0* ① | *✔* @@ -159,7 +121,7 @@ It is best to upgrade either the SDK or the Couchbase version you are using. | *✔* | *✔* -| *Server 7.2* +| *Server 7.2* ② | *◎* | *◎* | *✔* @@ -167,18 +129,16 @@ It is best to upgrade either the SDK or the Couchbase version you are using. |=== -① Server 7.6 & 8.0 are compatible with all supported (not yet End-of-Life) versions of the {name-sdk}, but for full support of the latest features you need to upgrade to a recent version of the SDK. -See the <<#couchbase-new-feature-availability-matrix,Feature Availablity matrix below>> and the xref:sdk-release-notes.adoc[Release Notes page]. -Note the https://www.couchbase.com/support-policy/EOL/[End of Life dates^] for Couchbase Server and SDK versions. -See the notes there for Support details. +include::{version-common}@sdk:shared:partial$compat.adoc[tag=matrix-notes2] + + + === Capella Compatibility -The Couchbase {name-sdk} is fully compatible with Couchbase Capella, our fully-hosted database-as-a-service. -To make development easier, the SDK includes the Capella client certificate ready installed. -include::{version-common}@sdk:shared:partial$capella.adoc[tag=cloud] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=cloud] === Couchbase New Feature Availability Matrix @@ -206,10 +166,9 @@ include::{version-common}@sdk:shared:partial$capella.adoc[tag=cloud] | From SDK 3.9.0 ① |=== -① As part of the standard SDK {sqlpp} API, it should be compatible with all earlier versions of the SDK -- but it has not been tested. -This table is not an exhaustive list -- just a few highlights -- provided to help assess compatibility of older versions in particular. -For alignment of SDKs and new Server features, scroll down to the information below the <>. +include::{version-common}@sdk:shared:partial$compat.adoc[tag=feature-notes] + === Spring Data Couchbase Compatibility @@ -220,7 +179,7 @@ The following table provides an overview at the time of Java SDK {sdk_dot_minor} .Recommended Spring Data Couchbase per Server Version Matrix [#table_spring_versions] |=== -| | SDC 5.4 - 5.5 | SDC 6.0 +| | SDC 5.4 - 5.5 | SDC 6.0 - 6.1 | _Status ->_ | _Maintenance Support_ @@ -238,14 +197,14 @@ Using the latest Spring Data Couchbase should ensure that this is so. === Quarkus Java Compatibility -Couchbase Quarkus requires Java SDK 3.7.7 or newer. +include::1.4@quarkus-extension::compatibility.adoc[tag=compat-table] See the xref:quarkus-extension:ROOT:overview.adoc[Couchbase Quarkus Java Extension docs] for details of using Quarkus, and the compatibility with Quarkus, GraalVM, and the Couchbase Java SDK. === API Version -include::{version-common}@sdk:shared:partial$api-version.adoc[tag=api-version] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=api-version] @@ -255,9 +214,11 @@ include::{version-common}@sdk:shared:partial$api-version.adoc[tag=api-version] === Interface Stability -include::{version-common}@sdk:shared:partial$interface-stability-pars.adoc[tag=interface-stability-section] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=interface-stability-section] === Older SDK Versions -include::{version-common}@sdk:shared:partial$archive.adoc[tag=link] + +include::{version-common}@sdk:shared:partial$compat.adoc[tag=archive-link] + diff --git a/modules/project-docs/pages/deployment.adoc b/modules/project-docs/pages/deployment.adoc index 05a16ecc..d6af4595 100644 --- a/modules/project-docs/pages/deployment.adoc +++ b/modules/project-docs/pages/deployment.adoc @@ -15,19 +15,7 @@ - - - - -One of Couchbase's strengths is speedy response, so deployment of apps should be in the same region as the Server -- whether Capella, or your own self-managed cluster. - -We always recommend the xref::sdk-release-notes.adoc#latest-release[latest version] of the SDK. -This not only contains the latest security updates and bug fixes, but will be compatible with the latest Couchbase Server release -(note, Capella always runs a recent version of Couchbase Server). - -Before deploying, take note of any xref:compatibility.adoc[compatibility] issues for the language platform and underlying OS. -The xref:sdk-full-installation.adoc[full installation guide] should cover any special cases for all supported environments. - +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=intro] @@ -37,18 +25,10 @@ include::{version-common}@sdk:shared:partial$deployment.adoc[tag=load-balancer] - == Development & Testing Environments -During development, some shortcuts are taken to get up and running which would not be acceptable during deployment. -These include use of administrator permissions, connecting from your laptop instead of a secure app server, and even disabling certificate verification for TLS. -Testing environments may also differ from deployment. -The {name-sdk} docs note whenever a shortcut is being taken, but here is a non-exhaustive list of those development practices which should not be carried over to production deployments: - -* Over-priveleged access -* Geographical separation of app server and database -* Skipping certificate verification +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=testing] // * more The best way to accommodate developing an application that is to be deployed to production is to use the platform's default approach for configuration files. @@ -65,22 +45,69 @@ This section also contains information on xref:migrating-sdk-code-to-3.n.adoc[mi // :migration-link: for 4.x pages?? -== Further Reading -* Integrate Couchbase with your data ecosystem: -** xref:project-docs:third-party-integrations.adoc[SDK Integrations] -** xref:server:develop:integrations.adoc[Integrations across Couchbase] -* xref:project-docs:get-involved.adoc[Contribute to the SDK] -=== Deploying Couchbase Server -* xref:cloud::index.adoc[Capella] -- Database as a Service -* xref:{version-server}@server:install:get-started.adoc[Self-managed Couchbase Server]: -** xref:{version-server}@server:install:getting-started-docker.adoc[Docker Install] -** xref:operator::overview.adoc[Couchbase Autonomous Operator] -*** xref:operator::install-kubernetes.adoc[Kubernetes] -*** xref:operator::install-openshift.adoc[Openshift] -** xref:{version-server}server:cloud:couchbase-cloud-deployment.adoc[Cloud Marketplace]: -*** xref:{version-server}@server:cloud:couchbase-aws-marketplace.adoc[AWS Marketplace] -*** xref:{version-server}@server:cloud:couchbase-azure-marketplace.adoc[Azure Marketplace] -*** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace] +== Couchbase Operational Cluster Feature Compatibility + +// tag::feature-compat[] +All of the SDKs have API compatibility with most of the features in Couchbase Operational Clusters -- +whether self-managed, or Capella. +The following table covers possible exceptions, and gives the version of the {name-sdk} and Couchbase Server with which some features were introduced. + + +.Couchbase Server and SDK Supported Version Matrix +[.table-merge-cells] +[cols="8,5,5,5"] +|=== +| | Server 7.2 | Server 7.6.x | Server 8.0 + +| KV Range Scan +| N/A +2+| From 3.4.1 + +| Zone aware replica reads +| N/A +2+| From 3.6.0 + +| Vector Search with Search Vector Index +| N/A +2+| From 3.6.0 + +| Vector Query using Hyperscale Vector Index +2+| N/A +| From SDK 3.9.0 ① + +| Vector Query using Composite (GSI & vector) index +2+| N/A +| From SDK 3.9.0 ① + +| Distributed ACID Transactions +3+| From 3.0.0 + +| DNS SRV refresh for serverless environments (AWS Lambda, Azure Functions, and GCP Functions) +3+| From 3.4.0 + +| Circuit Breakers +3+| From 3.0.0 + +| Response Time Observability with OTel +3+| From 3.0.7 + +| Field Level Encryption +3+| From 2.6.0 + +| Cloud Native Gateway +3+| From 3.5.0 +|=== + +<1> As part of the standard SDK {sqlpp} API, it should be compatible with all earlier versions of the SDK -- but it has not been tested. +// end::feature-compat[] + + + +// == Further Reading +include::{version-common}@sdk:shared:partial$deployment.adoc[tag=further-reading] + + + diff --git a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc index f0395f5b..b1b6cc1a 100644 --- a/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc +++ b/modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc @@ -617,6 +617,10 @@ include::devguide:example$java/Migrating.java[tag=searchcheck,indent=0] === Views +// deprecation admonition +include::{version-common}@sdk:shared:partial$views.adoc[tag=deprecate-sdk] + + Views have stayed at the `Bucket` level, because it does not have the concept of CollectionsExample and is scoped at the bucket level on the server as well. The API has stayed mostly the same, the most important change is that `staleness` is unified under the `ViewConsistency` enum. @@ -751,8 +755,9 @@ Note that some options have been removed, and others have different ways to conf |`sslKeystoreFile` | on `CertificateAuthenticator` |`sslKeystorePassword` | on `CertificateAuthenticator` |`sslKeystore` | on `CertificateAuthenticator` -|`sslTruststoreFile` | `SecurityConfig.trustCertificate` -|`sslTruststorePassword` | `SecurityConfig.trustCertificate` +a|`sslTruststoreFile` + +`sslTruststorePassword` .^| `SecurityConfig.trustStore` |`sslTruststore` | `SecurityConfig.trustManagerFactory` |`bootstrapCarrierEnabled` | removed |`bootstrapHttpDirectPort` | via custom `SeedNode` @@ -829,4 +834,4 @@ Note that some options have been removed, and others have different ways to conf |`propagateParentSpan` | removed |==== -include::{version-common}@sdk:shared:partial$archive.adoc[tag=migration] +include::{version-common}@sdk:shared:partial$compat.adoc[tag=migration] diff --git a/modules/project-docs/pages/sdk-full-installation.adoc b/modules/project-docs/pages/sdk-full-installation.adoc index 0a937a01..cc30aff8 100644 --- a/modules/project-docs/pages/sdk-full-installation.adoc +++ b/modules/project-docs/pages/sdk-full-installation.adoc @@ -14,12 +14,12 @@ It offers synchronous APIs as well as reactive and asynchronous equivalents to m The Couchbase Java SDK 3._x_ is a complete rewrite of the 2.x API, providing a simpler surface area and adding support for Couchbase Server features like xref:concept-docs:collections.adoc[Collections and Scopes] (available in Couchbase Server 7.0+). The (reactive) API also migrated from `RxJava` to `Reactor`, along with other improvements to performance, logging, debugging and timeout troubleshooting. -If you're upgrading your application from Java SDK 2.x, please read our xref:project-docs:migrating-sdk-code-to-3.n.adoc[Migrating 2.x code to SDK 3.0 Guide]. +If you're upgrading your application from Java SDK 2.x, please read our xref:project-docs:migrating-sdk-code-to-3.n.adoc[Migrating 2.x code to SDK 3.x Guide]. == Prerequisites -The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- see our xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. +The Java SDK is tested against LTS versions of OpenJDK -- see our xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. The underlying OS normally makes no difference, but library incompatibilities in Alpine Linux makes a xref:project-docs:compatibility.adoc#alpine-linux-compatibility[workaround] necessary for this OS. diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc index 5ff6b197..54b7a8d7 100644 --- a/modules/project-docs/pages/sdk-release-notes.adoc +++ b/modules/project-docs/pages/sdk-release-notes.adoc @@ -3,33 +3,33 @@ :navtitle: Release Notes :page-toclevels: 2 :page-partial: -:page-aliases: relnotes-java-sdk.adoc,ROOT:sdk-release-notes.adoc,ROOT:relnotes-java-sdk.adoc,ROOT:release-notes.adoc,ROOT:download-links.adoc,server:sdks:java-2.2/download-links.adoc +// :page-aliases: relnotes-java-sdk.adoc,ROOT:sdk-release-notes.adoc,ROOT:relnotes-java-sdk.adoc,ROOT:release-notes.adoc,ROOT:download-links.adoc,server:sdks:java-2.2/download-links.adoc [abstract] {description} -These pages cover the 3._x_ versions of the Couchbase Java SDK. -For release notes, download links, and installation methods for 2.7 and earlier releases of the Couchbase Java Client, please see the https://docs-archive.couchbase.com/java-sdk/2.7/sdk-release-notes.html[2.x Java Release Notes & Download Archive]. +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=intro] -=== Installation -See the xref:project-docs:sdk-full-installation.adoc[Full Installation] guide for details. +=== Installation +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=installation-moved] -include::{version-common}@sdk:pages:partial$signed.adoc[tag=signed] +// JVM signed +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=signed] // tag::all[] [#latest-release] -== Java SDK 3.11 Releases +== Java SDK 3.13 Releases We always recommend using the latest version of the SDK -- it contains all of the latest security patches and support for new and upcoming features. All patch releases for each dot minor release should be API compatible, and safe to upgrade; any changes to expected behavior are noted in the release notes that follow. -Version 3.11 of the Java SDK implements the 3.9 xref:compatibility.adoc#api-version[SDK API]. +Version {sdk_dot_minor} of the Java SDK implements the {sdk_api} xref:compatibility.adoc#api-version[SDK API]. See the xref:compatibility.adoc#couchbase-feature-availability-matrix[compatibility pages] for more information on feature compatibility with different versions of Couchbase Server. @@ -45,6 +45,332 @@ echo metrics-micrometer ; grep '' $src/metrics-micrometer/pom.xml | hea //// + +// before GA +// uncomment aliases +// and comment out in 3.11 + + + + + +[v3.13.0] +=== Version 3.13.0 (13 October 2026) + +https://packages.couchbase.com/clients/java/3.13.0/Couchbase-Java-Client-3.13.0.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.13.0/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.13.0/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== New Features + +* https://jira.issues.couchbase.com/browse/JCBC-2224[JCBC-2224]: +Added an option for Hybrid Search Score Fusion, for future releasese of Couchbase Server. +// Added an option for Hybrid Search Score Fusion when using Couchbase Server 8.5 or later. + +* https://jira.issues.couchbase.com/browse/JCBC-2226[JCBC-2226]: +Added `collection.getReplica()`, which allows reading from a specific replica. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1767[JVMCBC-1767], https://jira.issues.couchbase.com/browse/JVMCBC-1768[JVMCBC-1768]: +Added versions of `EncryptionModule` and `JsonValueModule` that are compatible with Jackson 3. + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1773[JVMCBC-1773]: +Added handling for a new query error code introduced in Couchbase Server 7.6, mapped to `AuthenticationFailureException`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1756[JVMCBC-1756]: +The executor for blocking transaction operations is now backed by virtual threads for improved scalability when running on Java 21 or later. +This change only affects the reactive Java and Scala transaction APIs, as well as all transactions in Kotlin. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1765[JVMCBC-1765]: +Upgraded Netty to `4.2.19`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1766[JVMCBC-1766]: +Upgraded Jackson to `2.21.7` / `3.1.7`. + +==== Deprecations + +* https://jira.issues.couchbase.com/browse/JVMCBC-1741[JVMCBC-1741]: +`SaslMechanism.SCRAM_SHA1` is now deprecated, and is no longer used unless your application builds a custom `PasswordAuthenticator` that explicitly allows it. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1751[JVMCBC-1751]: +The overload of `Cluster.connect()` that takes a `SeedNode` set is now deprecated in favor of the overload that takes a connection string, which is more versatile. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1772[JVMCBC-1772]: +Deprecated the `IoEnvironment` methods that accept a Netty `EventLoopGroup`, since a future SDK version might not use Netty. +Users who need to tune I/O threading should use `eventLoopThreadCount` instead. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1771[JVMCBC-1771]: +Fixed a rare deadlock during bucket bootstrap that could cause the SDK to hang while fetching the bucket topology. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1769[JVMCBC-1769]: +Fixed a rare race condition that could cause problems with topology updates. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1764[JVMCBC-1764]: +Fixed a `NullPointerException` related to executing a prepared statement (a query with `adhoc=false`) in a transaction. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1754[JVMCBC-1754]: +Reduced the occurrence of false positive `WatchdogInvalidStateIdentifiedEvent` log messages in deployments using private endpoints, and other environments where node hostnames are not unique. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1763[JVMCBC-1763]: +Tracing spans for KV range scan are now completed correctly. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1743[JVMCBC-1743]: +Fixed a bug that caused the SDK to ignore the "field" parameter of a regexp search query when using the `couchbase2://` protocol. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1446[JVMCBC-1446]: +Fixed an otherwise harmless race condition that caused "Could not locate a single global configuration" warnings in the log. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1745[JVMCBC-1745], https://jira.issues.couchbase.com/browse/JVMCBC-1747[JVMCBC-1747]: +The `META-INF/io.netty.versions.properties` and `META-INF/native-image` resources from the SDK's repackaged version of Netty are now relocated to avoid conflicts with vanilla Netty. + + +== Java SDK 3.12 Releases + + +[v3.12.3] +=== Version 3.12.3 (10 September 2026) + +https://packages.couchbase.com/clients/java/3.12.3/Couchbase-Java-Client-3.12.3.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.3/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.3/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1762[JVMCBC-1762]: +Returning a failed future from `RetryStrategy.shouldRetry()` now causes the request to fail immediately instead of timing out, and propagates the exception from the failed future. ++ +Thank you to community member https://github.com/1fanwang[Stefan Wang]. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1760[JVMCBC-1760]: +Upgraded to Netty `4.2.18`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1761[JVMCBC-1761]: +Upgraded to Jackson `2.21.6`. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1759[JVMCBC-1759]: +The `couchbase2://` protocol now correctly throws `NumberTooBigException` when a subdocument operation fails for that reason. + + +[v3.12.2] +=== Version 3.12.2 (28 July 2026) + +https://packages.couchbase.com/clients/java/3.12.2/Couchbase-Java-Client-3.12.2.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.2/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.2/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1755[JVMCBC-1755]: +`bucket.waitUntilReady()` no longer times out during rebalance when some nodes are not yet hosting the bucket. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1752[JVMCBC-1752]: +The `couchbase2://` protocol was returning incorrect mutation tokens, with `partitionUUID` erroneously set to the same value as `partitionID`. +This is low-impact, and only affects developers who use the `couchbase2://` protocol and specify the "consistent with" option when querying or searching. + + + + +[v3.12.1] +=== Version 3.12.1 (08 July 2026) + +https://packages.couchbase.com/clients/java/3.12.1/Couchbase-Java-Client-3.12.1.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.1/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.1/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1739[JVMCBC-1739]: +Low-information topology changes are now logged at `DEBUG` level instead of `INFO`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1746[JVMCBC-1746]: +Upgraded to Netty `4.2.16`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1750[JVMCBC-1750]: +Upgraded to Jackson `2.21.5`. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1740[JVMCBC-1740]: +Fixed a regression in `3.11.0` that could cause an uneven distribution of network channels to event loops. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1749[JVMCBC-1749]: +Fixed a regression in `3.12.0` that prevented Spring Data Couchbase from executing transactions. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1744[JVMCBC-1744]: +Fixed a bug in the `couchbase2` protocol that caused the SDK to throw a generic `CouchbaseException` instead of `DocumentNotLockedException`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1748[JVMCBC-1748]: +Fixed an issue where in some cases the SDK would continue trying to connect to a node that was removed from the cluster. + + + +[v3.12.0] +=== Version 3.12.0 (02 June 2026) + +https://packages.couchbase.com/clients/java/3.12.0/Couchbase-Java-Client-3.12.0.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.12.0/index.html[API Reference] | +https://docs.couchbase.com/sdk-api/couchbase-core-io-3.12.0/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.9** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Built Against | API Stability +| `tracing-opentelemetry` | OpenTelemetry 1.57.0 | Committed +| `tracing-opentracing` | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | OpenTelemetry 1.57.0 | Volatile +| `metrics-micrometer` | Micrometer 1.12.9 | Volatile +|======================= + + +==== New features + +* https://jira.issues.couchbase.com/browse/JCBC-2214[JCBC-2214]: +Adds a new API to `Collection`, `getOrNull`. +This behaves identically to the regular Key-Value get call except that if the document does not exist then null is returned rather than an exception being raised, +avoiding the slight overhead of exception creation on JVM platforms. +In addition, when `OpenTelemetry` is being used an exception is not attached to the span in that case. + +==== Improvements + +* https://jira.issues.couchbase.com/browse/JVMCBC-1722[JVMCBC-1722]: +Simplified the transaction protocol implementation, and changed the threading model to make it easier to reason about thread safety. As a happy side effect, internal performance testing shows improved transaction throughput and latency for some workloads. ++ +TIP: Developers using the SDK's reactive transaction API may see an increase in the number of threads spawned by the SDK, because each operation is now executed on its own dedicated thread. For high-concurrency transactions running on Java 21 and later, we recommend using the blocking API and virtual threads. + +* https://jira.issues.couchbase.com/browse/JCBC-1739[JCBC-1739]: +When inserting or replacing a document inside a transaction, it is now possible to specify an expiration time for the document. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1732[JVMCBC-1732]: +Improved the error message when a Full-Text Search request fails due to insufficient user permissions. The message now indicates the cause of the failure, instead of "Request failed, but no more information available". + +* https://jira.issues.couchbase.com/browse/JVMCBC-1725[JVMCBC-1725]: +Added the `db.system.name` attribute to `OpenTelemetry` spans. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1735[JVMCBC-1735], https://jira.issues.couchbase.com/browse/JVMCBC-1736[JVMCBC-1736]: +Hardened the code that handles cluster topology changes. +Improved the diagnostics in this critical area by adding a limited number of new `INFO` log messages that describe topology changes. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1731[JVMCBC-1731]: +Added a new `DEBUG` log message that shows the options used for socket connections. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1733[JVMCBC-1733]: +Upgraded to `Netty` `4.2.14`. + +* https://jira.issues.couchbase.com/browse/JVMCBC-1734[JVMCBC-1734]: +Upgraded to `Jackson `2.21.4`. + +==== Bug Fixes + +* https://jira.issues.couchbase.com/browse/JVMCBC-1738[JVMCBC-1738]: +Ignoring the result rows of a reactive query no longer causes future queries to time out. + +* https://jira.issues.couchbase.com/browse/JCBC-2216[JCBC-2216]: +`EventingFunctionManager.functionsStatus()` no longer throws an exception if a function is in the `"resuming"` state. +The `EventingFunctionStatus` enum has two new values: `RESUMING` and `UNKNOWN` (a special value indicating the SDK did not recognize the status code returned by the server). + +* https://jira.issues.couchbase.com/browse/JVMCBC-1728[JVMCBC-1728]: +The durations reported by some transaction diagnostic messages are no longer inflated by a factor of 1,000,000. +This bug had no effect on the SDK’s behavior, but could mislead developers reading the logs. + + + + +== Java SDK 3.11 Releases + + === Version 3.11.1 (16 February 2026) https://packages.couchbase.com/clients/java/3.11.1/Couchbase-Java-Client-3.11.1.zip[Download] | @@ -1006,6 +1332,51 @@ Adds support for base64-encoded vectors in `VectorQuery`. == Java SDK 3.6 Releases +=== Version 3.6.4 (26 April 2026) + +This is a maintenance release. + +https://packages.couchbase.com/clients/java/3.6.4/Couchbase-Java-Client-3.6.4.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.6.4/index.html[API Reference] | +http://docs.couchbase.com/sdk-api/couchbase-core-io-2.6.4/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.6.3** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Couchbase Version | Built Against | API Stability +| `tracing-opentelemetry` | 1.4.4 | OpenTelemetry 1.31.0 | Committed +| `tracing-opentracing` | 1.4.4 | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | 0.6.4 | OpenTelemetry 1.31.0 | Volatile +| `metrics-micrometer` | 0.6.4 | Micrometer 1.10.10 | Volatile +|======================= + + +==== Improvements + +* https://issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. ++ +NOTE: This is a backport of a feature from version 3.12.0. +It is not present in SDK versions before 3.12.0 unless mentioned in the release notes. + + === Version 3.6.3 (19 August 2024) This is a regular maintenance release. @@ -1195,6 +1566,50 @@ Previously, the SDK assumed `1` was the default value, and omitted the parameter == Java SDK 3.5 Releases +=== Version 3.5.4 (27 April 2026) + +This is a maintenance release. + +https://packages.couchbase.com/clients/java/3.5.4/Couchbase-Java-Client-3.5.4.zip[Download] | +https://docs.couchbase.com/sdk-api/couchbase-java-client-3.5.4/index.html[API Reference] | +http://docs.couchbase.com/sdk-api/couchbase-core-io-2.5.4/[Core API Reference] + +The supported and tested dependencies for this release are: + +* io.projectreactor:**reactor-core:3.5.8** +* org.reactivestreams:**reactive-streams:1.0.4** + +Optional artifacts on top of this SDK version are tested for the following compatibilities: + +.Optional Artifact Version Compatibility +[options="header"] +|======================= +| Artifact | Couchbase Version | Built Against | API Stability +| `tracing-opentelemetry` | 1.3.4 | OpenTelemetry 1.31.0 | Committed +| `tracing-opentracing` | 1.3.4 | OpenTracing 0.33.0 | Committed +| `metrics-opentelemetry` | 0.5.4 | OpenTelemetry 1.31.0 | Volatile +| `metrics-micrometer` | 0.5.4 | Micrometer 1.10.9 | Volatile +|======================= + +==== Improvements + +* https://issues.couchbase.com/browse/JVMCBC-1729[JVMCBC-1729]: +When running on Linux, the SDK now sets the `TCP_USER_TIMEOUT` socket option so it can detect dead connections more quickly. +By default, the SDK sets the timeout to 20 seconds. +You can override the default by configuring the new `io.tcpUserTimeout` client setting. +For example, to set the timeout to 30 seconds you would configure the `ClusterEnvironment.Builder` like this: ++ +[source,java] +---- +env.ioConfig(io -> io.tcpUserTimeout(Duration.ofSeconds(30))) +---- ++ +Thank you to community member Omer Cilingir for this contribution. ++ +NOTE: This is a backport of a feature from version 3.12.0. +It is not present in SDK versions before 3.12.0 unless mentioned in the release notes. + + === Version 3.5.3 (6 February 2024) This is a regular maintenance release. @@ -3641,5 +4056,5 @@ Numerous _Alpha_ and _Beta_ releases were made in the run-up to the 3.0 release, == Older Releases -Although https://www.couchbase.com/support-policy/EOL/[no longer supported], documentation for older releases continues to be available in our https://docs-archive.couchbase.com/home/index.html[docs archive]. +include::{version-common}@sdk:shared:partial$relnotes.adoc[tag=older] // end::all[] diff --git a/modules/project-docs/pages/third-party-integrations.adoc b/modules/project-docs/pages/third-party-integrations.adoc index 76f121c6..7fdd09da 100644 --- a/modules/project-docs/pages/third-party-integrations.adoc +++ b/modules/project-docs/pages/third-party-integrations.adoc @@ -35,3 +35,6 @@ The philosophy of the project claims to "strongly favor simplicity and conventio In CouchMove you write your migrations in {sqlpp_url}[{sqlpp} (formerly N1QL)], while in https://github.com/couchbaselabs/CouchVersion[CouchVersion] you can write them using the Java SDK, which essentially allow you to create more complex migrations. CouchVersion provides a new approach for adding changes (change sets) based on Java classes and methods with appropriate annotations. + +Liquibase manages schema changes, storing changes in text files as XML, YAML, JSON, or SQL. +It is often used as a migration tool, and Liquibase have made available a https://github.com/liquibase/liquibase-couchbase[Couchbase extension for Liquibase] for Couchbase Server 7.0+. diff --git a/modules/ref/pages/error-codes.adoc b/modules/ref/pages/error-codes.adoc index a0cd3ac7..23d94cac 100644 --- a/modules/ref/pages/error-codes.adoc +++ b/modules/ref/pages/error-codes.adoc @@ -66,5 +66,5 @@ WARNING: [com.couchbase.core][DnsSrvLookupFailedEvent][86ms] DNS SRV lookup fail * Our practical look at xref:howtos:error-handling.adoc[error handling with the SDK]. * xref:howtos:health-check.adoc#diagnostics[Diagnostics] with Health Check. -* xref:concept-docs:errors.adoc[Discussion document] on handling exceptions. +// * xref:concept-docs:errors.adoc[Discussion document] on handling exceptions. * Further reference material in the https://docs.couchbase.com/sdk-api/couchbase-java-client/index.html[API Guide]. diff --git a/modules/ref/pages/index.adoc b/modules/ref/pages/index.adoc index dfe12ca1..002c3b43 100644 --- a/modules/ref/pages/index.adoc +++ b/modules/ref/pages/index.adoc @@ -36,8 +36,6 @@ but the complete set of discussion docs for the SDK is listed and linked below: // TODO - put this in a better order. -* xref:concept-docs:buckets-and-clusters.adoc[Buckets & Clusters] -* xref:concept-docs:collections.adoc[Collections & Scope] * xref:concept-docs:compression.adoc[Compression] * xref:concept-docs:data-model.adoc[Data Model] ** xref:concept-docs:documents.adoc[Documents] @@ -50,26 +48,26 @@ but the complete set of discussion docs for the SDK is listed and linked below: * xref:concept-docs:durability-replication-failure-considerations.adoc[Failure Considerations] * xref:concept-docs:encryption.adoc[Field Level Encryption] * xref:concept-docs:data-services.adoc[Service Selection / Querying your Data] -** xref:concept-docs:analytics-for-sdk-users.adoc[Analytics] -** xref:concept-docs:understanding-views.adoc[Map Reduce Views] +** xref:concept-docs:understanding-views.adoc[Map Reduce Views] [Deprecated] ** xref:concept-docs:n1ql-query.adoc[Query] ** xref:concept-docs:full-text-search-overview.adoc[Search] * xref:concept-docs:sdk-user-management-overview.adoc[User Management] ** xref:concept-docs:certificate-based-authentication.adoc[Cert Auth] -** xref:concept-docs:rbac.adoc[RBAC] // + -* xref:concept-docs:data-durability-acid-transactions.adoc[Data Modelling, Durability, and Consistency] -* xref:concept-docs:querying-your-data.adoc[] - -* xref:concept-docs:durability-replication-failure-considerations.adoc[] +=== Key Discussion Documents * xref:concept-docs:best-practices.adoc[] +* xref:concept-docs:data-durability-acid-transactions.adoc[Data Modelling, Durability, and Consistency] + +* xref:concept-docs:durability-replication-failure-considerations.adoc[] + * xref:concept-docs:management-api.adoc[Managing Couchbase] +* xref:concept-docs:querying-your-data.adoc[] * xref:project-docs:deployment.adoc[SDK Deployment] diff --git a/pom.xml b/pom.xml index 8f7e960a..f81b7d7d 100644 --- a/pom.xml +++ b/pom.xml @@ -8,6 +8,13 @@ + + com.couchbase.client + couchbase-client-bom + 3.13.0 + pom + import + io.opentelemetry opentelemetry-bom @@ -85,7 +92,7 @@ io.grpc grpc-netty-shaded - 1.28.0 + 1.75.0