Merge branch 'release/3.5' of https://github.com/couchbase/docs-sdk-java into release/3.5

RichardSmedley · RichardSmedley · commit 13af6054a4a9 · 2023-10-23T16:50:56.000+01:00
diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc
@@ -62,7 +62,7 @@ We recommend running the latest Java LTS version (i.e. at the time of writing JD
 // Other supported Java versions will work, too.
 Couchbase publishes all stable artifacts to https://central.sonatype.com/namespace/com.couchbase.client[Maven Central].
 
-The latest version (as of September 2023) is https://central.sonatype.com/artifact/com.couchbase.client/java-client/3.4.10/jar[3.4.10].
+The latest version (as of October 2023) is https://central.sonatype.com/artifact/com.couchbase.client/java-client/3.4.11/jar[3.4.11].
 
 You can use your favorite dependency management tool to install the SDK.
 
@@ -77,7 +77,7 @@ Maven::
     <dependency>
         <groupId>com.couchbase.client</groupId>
         <artifactId>java-client</artifactId>
-        <version>3.4.10</version>
+        <version>3.4.11</version>
     </dependency>
 </dependencies>
 ----
@@ -88,7 +88,7 @@ Gradle::
 --
 [source,groovy]
 ----
-implementation 'com.couchbase.client:java-client:3.4.10'
+implementation 'com.couchbase.client:java-client:3.4.11'
 ----
 --
 ====
diff --git a/modules/howtos/examples/Auth.java b/modules/howtos/examples/Auth.java
@@ -14,15 +14,17 @@
  * limitations under the License.
  */
 
-import static com.couchbase.client.java.ClusterOptions.clusterOptions;
-
-import java.security.KeyStore;
-
+import com.couchbase.client.core.env.Authenticator;
 import com.couchbase.client.core.env.CertificateAuthenticator;
 import com.couchbase.client.core.env.PasswordAuthenticator;
 import com.couchbase.client.core.error.InvalidArgumentException;
 import com.couchbase.client.java.Cluster;
 
+import java.nio.file.Paths;
+import java.security.KeyStore;
+
+import static com.couchbase.client.java.ClusterOptions.clusterOptions;
+
 public class Auth {
 
   public static void main(String... args) {
@@ -53,11 +55,27 @@ public static void main(String... args) {
     {
       try {
         // tag::certauth[]
-        // should be replaced with your actual KeyStore
+        // Replace the following line with code that gets your actual key store.
+        // The key store contains the client's certificate and private key.
         KeyStore keyStore = loadKeyStore();
 
-        CertificateAuthenticator authenticator = CertificateAuthenticator.fromKeyStore(keyStore, "keyStorePassword");
-        Cluster cluster = Cluster.connect("127.0.0.1", clusterOptions(authenticator));
+        Authenticator authenticator = CertificateAuthenticator.fromKeyStore(
+            keyStore,
+            "keyStorePassword"
+        );
+
+        Cluster cluster = Cluster.connect(
+            "couchbases://127.0.0.1",
+            clusterOptions(authenticator)
+                .environment(env -> env
+                    .securityConfig(security -> security
+                        // Tell the client to trust the cluster's root certificate.
+                        // If your cluster's root certificate is from a well-known
+                        // Certificate Authority (CA), you can skip this.
+                        .trustCertificate(Paths.get("/path/to/ca-cert.pem"))
+                    )
+                )
+        );        
         // end::certauth[]
       } catch (InvalidArgumentException e) {
         // The code requires a valid keystore, catching the exception for
diff --git a/modules/howtos/pages/kv-operations.adoc b/modules/howtos/pages/kv-operations.adoc
@@ -285,6 +285,11 @@ 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
 
+TIP: Setting the document expiry time only works when a document is created, and it is not possible to update the expiry time of an existing counter document with the Increment method -- to do this during an increment, use with the `Touch()` method.
+
+
+
+// Atomicity Across Data Centers
 
 include::{version-common}@sdk:shared:partial$atomic.adoc[tag=xdcr]
 
diff --git a/modules/howtos/pages/n1ql-queries-with-sdk.adoc b/modules/howtos/pages/n1ql-queries-with-sdk.adoc
@@ -51,7 +51,11 @@ include::example$SimpleQuery.java[tag=class,indent=0]
 --
 ====
 
-Let's break it down. A query is always performed at the `Cluster` level, using the `query` method. It takes the statement as a required argument and then allows to provide additional options if needed (in the example above, no options are specified).
+Note that building indexes is covered in some detail on the xref:concept-docs:n1ql-query.adoc#index-building[Query concept page], which you should take a quick look at --
+and in the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/manager/query/package-summary.html[API Reference].
+
+Let's break down the above code snippet. 
+A query is always performed at the `Cluster` level, using the `query` method. It takes the statement as a required argument and then allows to provide additional options if needed (in the example above, no options are specified).
 
 Once a result returns you can iterate the returned rows and/or accessing the `QueryMetaData` associated with the query. If something goes wrong during the execution of the query, a derivate of the `CouchbaseException` will be thrown that also provides additional context on the operation:
 
diff --git a/modules/howtos/pages/sdk-authentication.adoc b/modules/howtos/pages/sdk-authentication.adoc
@@ -45,16 +45,26 @@ include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=cert-auth]
 
 == Authenticating the Java Client by Certificate
 
-For sample procedures whereby certificates can be generated and deployed, see xref:7.1@server:manage:manage-security/manage-certificates.adoc[Manage Certificates].
-The rest of this document assumes that the processes there, or something similar, have been followed.
-That is, a cluster certificate has been created and installed on the server, a client certificate has been created, and it is stored in a JVM keystore along with the cluster's certificate.
+To learn how to generate and deploy certificates, see xref:{server_version}@server:manage:manage-security/manage-certificates.adoc[Manage Certificates].
+The rest of this section assumes you followed those processes, or did something similar.
+
+For the following example, you will need a client certificate and the associated private key.
+These must be stored together in the same Java KeyStore file or pkcs12 bundle.
+
+If your cluster's root certificate does not come from a well-known Certificate Authority (CA), you must tell the client to trust the cluster's root certificate.
+This example assumes the cluster's root certificate is available in a file called `ca-cert.pem`.
+
+TIP: To trust multiple root certificates, put them all in the same `ca-certs.pem` file.
 
 [source,java]
 ----
 include::example$Auth.java[tag=certauth,indent=0]
 ----
 
-In addition to providing the initialized `KeyStore` directly, the `CertificateAuthenticator` can also be initialized from a key store path, a key directly or a `KeyManagerFactory` for maximum flexibility. Please see the API documentation for the `CertificateAuthenticator` for more details.
+`CertificateAuthenticator` has several static factory methods.
+If you prefer not to load your own `KeyStore` object, you can create a `CertificateAuthenticator` from a `Path` to a key store file, or from an in-memory certificate & key.
+For maximum flexibility, you can even provide your own `KeyManagerFactory`.
+Please see the https://docs.couchbase.com/sdk-api/couchbase-core-io/com/couchbase/client/core/env/CertificateAuthenticator.html[API documentation] for the `CertificateAuthenticator` for more details.
 
 include::{version-common}@sdk:shared:partial$auth-overview.adoc[tag=ldap]
 
diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc
@@ -10,7 +10,7 @@ include::project-docs:partial$attributes.adoc[]
 [abstract]
 {description}
 
-The 3.4 SDK requires Java 8 or later to be installed, earlier versions will not work.
+The 3.5 SDK requires Java 8 or later to be installed, earlier versions will not work.
 _Java 17 is recommended_, which has various enhancements like sealed classes, pattern matching for switch expressions (in preview), and further updates and improvements on core libraries.
 Most of the flavors available will do, although we may only provide support for OpenJDK and Oracle JDK going forward. 
 
@@ -29,11 +29,11 @@ It is best to upgrade either the SDK or the Couchbase version you are using.
 [#table_sdk_versions]
 [cols="40,20,25"]
 |===
-| | 3.1 | SDK 3.2-3.4
+| | 3.1 | SDK 3.2-3.5
 
 | *Server 6.6*
-| *✔*
-| *✔*
+| *◎*
+| *◎*
 
 | *Server 7.0-7.2*
 | *◎*
@@ -100,7 +100,7 @@ Microsoft Windows 10 / All LTS releases from Windows Server 2016.
 === Mac OS X
 
 The current and previous two releases of OS X.
-At time of writing (October 2022): 13 (Ventura), 12 (Monterey), and 11 (Big Sur).
+At time of writing (November 2023): 14 (Sonoma), 13 (Ventura), and 12 (Monterey).
 M1 ARM  architecture is fully supported in the Java SDK.
 
 [discrete]
@@ -151,39 +151,43 @@ The downside of these workarounds is potentially reduced performance, which can
 
 .Couchbase Server and SDK Supported Version Matrix
 [.table-merge-cells]
-[cols="7,5,7"]
+[cols="7,5,6.7"]
 |===
-| | Server 6.6 | Server 7.0 & 7.1
+| | Server 6.6 | Server 7.0 & 7.1 | Server 7.2
 
 | Enhanced Durability
-2+| All SDK versions
+3+| All SDK versions
 
 | Durable Writes
-2+| Since SDK 3.0
+3+| Since SDK 3.0
 
 | Analytics
-2+| Since SDK 2.7
+3+| Since SDK 2.7
 
 | Distributed ACID Transactions
-2+| Since SDK 3.3 included in SDK, or since SDK 3.0 with Java Transactions Libraryfootnote:[3.0.7 or more recent recommended; preferably, follow the transitive dependency for the transactions library in Maven.]
+3+| Since SDK 3.3 included in SDK, or since SDK 3.0 with Java Transactions Libraryfootnote:[3.0.7 or more recent recommended; preferably, follow the transitive dependency for the transactions library in Maven.]
 
 | {sqlpp} Queries inside the Transaction Lambda
 | Not Supported
-| Since SDK 3.1, or since 3.0.7 with Java Transactions Libraryfootnote:[1.2.1 or newer recommended.]
+2+| Since SDK 3.1, or since 3.0.7 with Java Transactions Libraryfootnote:[1.2.1 or newer recommended.]
 
 | Collections
 | Developer Preview in 6.6, SDK 3.0
-| Since SDK 3.0.6
+2+| Since SDK 3.0.6
 
 | Scope-Level {sqlpp} Queries & all Collections features
 | Not Supported
-| Since SDK 3.2.0
+2+| Since SDK 3.2.0
 
 | Field Level Encryption v2
-2+| Since SDK 3.0.5footnote:[Field Level Encryption distributed as separate library.]
+3+| Since SDK 3.0.5footnote:[Field Level Encryption distributed as separate library.]
 
 | Request Tracing
-2+| Since SDK 3.1.0
+3+| Since SDK 3.1.0
+
+| Cloud Native Gateway
+2+| Not Supported
+| From SDK 3.5.0 (with xref:operator::overview.adoc[Couchbase Autonomous Operator] 2.6+)
 |===
 
 
diff --git a/modules/project-docs/pages/sdk-full-installation.adoc b/modules/project-docs/pages/sdk-full-installation.adoc
@@ -33,7 +33,7 @@ We recommend running the latest Java LTS version (i.e. at the time of writing JD
 Java 17 has various enhancements like sealed classes, pattern matching for switch expressions (in preview), and further updates and improvements on core libraries.
 
 Couchbase publishes all stable artifacts to https://central.sonatype.com/namespace/com.couchbase.client[Maven Central].
-The latest version (as of September 2023) is https://central.sonatype.com/artifact/com.couchbase.client/java-client/3.4.10/jar[3.4.10].
+The latest version (as of October 2023) is https://central.sonatype.com/artifact/com.couchbase.client/java-client/3.4.11/jar[3.4.11].
 
 You can use your favorite dependency management tool to install the SDK.
 
@@ -50,7 +50,7 @@ For https://maven.apache.org[Maven], you can insert the following into the depen
     <dependency>
         <groupId>com.couchbase.client</groupId>
         <artifactId>java-client</artifactId>
-        <version>3.4.10</version>
+        <version>3.4.11</version>
     </dependency>
 ----
 Refer to the https://maven.apache.org/guides/introduction/introduction-to-the-pom.html/[Maven Documentation] for more information regarding the structure of the `pom.xml` file.
@@ -62,7 +62,7 @@ For https://gradle.org/[Gradle], you can use:
 
 [source,groovy]
 ----
-implementation 'com.couchbase.client:java-client:3.4.10'
+implementation 'com.couchbase.client:java-client:3.4.11'
 ----
 --
 ====
@@ -72,3 +72,43 @@ Refer to the xref:project-docs:sdk-release-notes.adoc[Release Notes] for further
 You can also find links to the hosted javadocs there.
 
 
+[snapshots]
+== Using a Snapshot Version
+
+Couchbase publishes pre-release snapshot artifacts to the Sonatype OSS Snapshot Repository.
+If you wish to use a snapshot version, you'll need to tell your build tool about this repository.
+
+[{tabs}]
+====
+Maven::
++
+--
+.`*pom.xml*`
+[source,xml]
+----
+<repositories>
+  <repository>
+    <id>sonatype-snapshots</id>
+    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
+    <releases><enabled>false</enabled></releases>
+    <snapshots><enabled>true</enabled></snapshots>
+  </repository>
+</repositories>
+----
+--
+Gradle (Groovy)::
++
+--
+.`*build.gradle*`
+[source,groovy]
+----
+repositories {
+    mavenCentral()
+    maven {
+        url "https://oss.sonatype.org/content/repositories/snapshots"
+        mavenContent { snapshotsOnly() }
+    }
+}
+----
+--
+====
diff --git a/modules/project-docs/pages/sdk-release-notes.adoc b/modules/project-docs/pages/sdk-release-notes.adoc
@@ -29,6 +29,42 @@ All patch releases for each dot minor release should be API compatible, and safe
 any changes to expected behavior are noted in the release notes that follow.
 
 
+=== Version 3.4.11 (4 October 2023)
+
+With thanks to our community for the contribution, support for Micrometer Observation has been added via the new `tracing-micrometer-observation` module.
+
+https://packages.couchbase.com/clients/java/3.4.11/Couchbase-Java-Client-3.4.11.zip[Download] |
+https://docs.couchbase.com/sdk-api/couchbase-java-client-3.4.11/index.html[API Reference] |
+http://docs.couchbase.com/sdk-api/couchbase-core-io-2.4.11/[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.2.11             | OpenTelemetry 1.19.0       | Committed
+| `tracing-opentracing`     | 1.2.11             | OpenTracing 0.33.0         | Committed
+| `metrics-opentelemetry`   | 0.4.11             | OpenTelemetry 1.19.0       | Volatile
+| `metrics-micrometer`      | 0.4.11             | Micrometer 1.10.0          | Volatile
+|=======================
+
+==== Improvements
+* https://issues.couchbase.com/browse/JCBC-2046[JCBC-2046]:
+With thanks to our community for the contribution, support for Micrometer Observation has been added via the new `tracing-micrometer-observation` module.
+* https://issues.couchbase.com/browse/JVMCBC-1327[JVMCBC-1327]:
+Internal improvements to support upcoming faster failover and config push features.
+
+==== Bugfixes
+* https://issues.couchbase.com/browse/JVMCBC-1364[JVMCBC-1364]:
+Fixed decoding of certain niche sub-document errors, so they no longer raise a `DecodingFailureException`.
+
+
 === Version 3.4.10 (6 September 2023)
 
 This is a standard maintenance release.
diff --git a/modules/ref/pages/client-settings.adoc b/modules/ref/pages/client-settings.adoc
@@ -377,6 +377,8 @@ System Property: `com.couchbase.env.timeout.kvDurableTimeout`
 +
 Key/Value operations with enhanced durability requirements may take longer to complete, so they have a separate default timeout.
 +
+*Do not* set this above 65s, which is the maximum possible `SyncWrite` timeout on the Server side.
++
 WARNING: The `kvDurableTimeout` property is not part of the stable API and may change or be removed at any time.
 
 // todo: is kvDurableTimeout a strictly client-side timeout?
diff --git a/pom.xml b/pom.xml
@@ -22,7 +22,7 @@
         <dependency>
             <groupId>com.couchbase.client</groupId>
             <artifactId>java-client</artifactId>
-            <version>3.4.10</version>
+            <version>3.4.11</version>
         </dependency>
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>

Original file line number	Diff line number	Diff line change
@@ -377,6 +377,8 @@ System Property: `com.couchbase.env.timeout.kvDurableTimeout`
`377`	`377`	`+`
`378`	`378`	`Key/Value operations with enhanced durability requirements may take longer to complete, so they have a separate default timeout.`
`379`	`379`	`+`
	`380`	+Do not set this above 65s, which is the maximum possible `SyncWrite` timeout on the Server side.
	`381`	`++`
`380`	`382`	WARNING: The `kvDurableTimeout` property is not part of the stable API and may change or be removed at any time.
`381`	`383`
`382`	`384`	`// todo: is kvDurableTimeout a strictly client-side timeout?`