From 8c1f280a41b3844e57d18340478d5089ba0f7d16 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Fri, 11 Jul 2025 13:31:39 +0530 Subject: [PATCH 1/7] DOC-13358 Corrected a sentence by adding a trailing period. --- modules/hello-world/pages/overview.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index 120abb24..af80772e 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -97,8 +97,7 @@ But if you don't know exactly where you need to go, try one of the following: * Our xref:hello-world:start-using-sdk.adoc[Quickstart Guide] introduces the SDK with a quick install, and CRUD examples against the Data Service. * Couchbase's familiar SQL-family query language and fuzzy search options (including vector search) are introduced on the xref:concept-docs:querying-your-data.adoc[] page. * The {name-sdk} docs are, necessarily, just a sub-set {sdk-api-link}[{name-sdk} API Reference] -- and a complete listing of all APIs can be found in the reference. -* For a fuller orientation, there is a xref:project-docs:metadoc-about-these-sdk-docs.adoc[guide to the {name-sdk} docs] - +* For a fuller orientation, there is a xref:project-docs:metadoc-about-these-sdk-docs.adoc[guide to the {name-sdk} docs]. {empty} + From 23da810dc73336aeb69390249f93f3e674237a25 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 14 Jul 2025 14:12:55 +0530 Subject: [PATCH 2/7] fixing few syntax errors --- .../hello-world/pages/sample-application.adoc | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/modules/hello-world/pages/sample-application.adoc b/modules/hello-world/pages/sample-application.adoc index 56b580c5..870dfa17 100644 --- a/modules/hello-world/pages/sample-application.adoc +++ b/modules/hello-world/pages/sample-application.adoc @@ -51,21 +51,21 @@ The application is tested with Java 17 and 21. If you are using a different vers We will walk through the different steps required to get the application running: -. Cloning Repo +. Cloning Repo. + [source,console] ---- $ git clone https://github.com/couchbase-examples/java-springboot-quickstart.git ---- -. Navigate to the Project Directory +. Navigate to the Project Directory. + [source,console] ---- $ cd java-springboot-quickstart ---- -. Install Dependencies +. Install Dependencies. + 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. @@ -75,8 +75,11 @@ Dependencies can be installed through `mvn` the default package manager for Java $ mvn clean install -DskipTests=true ---- + -Note, the `-DskipTests=true` option is used to skip the tests. +[NOTE] +==== +The `-DskipTests=true` option is used to skip the tests. The tests require the application to be running. +==== === Setup Database Configuration @@ -131,14 +134,14 @@ $ mvn spring-boot:run === Using Docker -Build the Docker image +Build the Docker image. [source,console] ---- $ docker build -t java-springboot-quickstart . ---- -Run the Docker image +Run the Docker image. [source,console] ---- @@ -156,6 +159,7 @@ If you choose not to pass the environment variables, you can update the `applica === Verifying the Application Once the application starts, you can see the details of the application on the logs. + image::app-startup-spring-boot.png[] The application will run on port 8080 of your local machine -- `http://localhost:8080`. From 5614d7377f444fc6481563c5806dee7d8a95ff35 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Mon, 14 Jul 2025 23:32:27 +0530 Subject: [PATCH 3/7] fixing some voice and syntax errors --- .../hello-world/pages/start-using-sdk.adoc | 116 +++++++----------- 1 file changed, 42 insertions(+), 74 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 24fdee26..c0749e2d 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -59,10 +59,9 @@ there are several self-managed options available: 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. +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^]. +Once the set up is complete, 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:: @@ -80,7 +79,7 @@ Install Couchbase Server locally, or in your private Cloud: ** 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. +To run the example code below, you will need the username and password of the Administrator user that you create, and the IP address of a minimum of one node in the cluster. -- ==== @@ -90,12 +89,12 @@ For the example code below to run, you'll need the username and password of the === Prerequisites -* The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK -- +* The Java SDK is tested against the LTS versions of Oracle JDK and OpenJDK -- see the xref:project-docs:compatibility.adoc#jdk-compat[compatibility docs]. + https://adoptium.net/[OpenJDK 21 with HotSpot JVM] is recommended. -The code examples also assume: +It is also assumed that: [tabs] ==== @@ -105,14 +104,15 @@ 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. + +Note: The Travel Sample dataset is installed automatically when deploying a Capella free tier cluster. * 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. +Use the *Organization Owner* role automatically that is assigned to your account during installation of the Capella cluster. +In production, as a best practice and also for data security, it is strongly recommended to set up the users with more granular access roles. -- Self-Managed Couchbase Server:: @@ -122,20 +122,20 @@ Self-Managed Couchbase Server:: * 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). +* A user is created with permissions to access your cluster (with the required 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. +In production, as a best practice and also for data security, it is strongly recommended to set up the users with more granular access roles. -- ==== == Installation -We recommend running the latest Java LTS version (i.e. at the time of writing JDK 21) with the highest patch version available. -// Other supported Java versions will work, too. +At the time of writing JDK 21, it is recommended to run the latest Java LTS version with the highest patch version available. +// Other supported Java versions will also work. Couchbase publishes all stable artifacts to https://central.sonatype.com/namespace/com.couchbase.client[Maven Central]. The latest version of {sdk_dot_minor}.x is https://central.sonatype.com/artifact/com.couchbase.client/java-client/{sdk_current_version}/jar[{sdk_current_version}]. @@ -175,14 +175,14 @@ implementation 'com.couchbase.client:java-client:{sdk_current_version}' === IDE Plugins -To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors. +To make the 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. === 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. +If you're all set up and are in real hurry, take the below code sample and add in your Capella details. .Complete Hello World code sample [*Click to open or collapse the listing*] [%collapsible] @@ -194,8 +194,7 @@ 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. - +TIP: There is a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages. A *Copy* icon is also available that allows you to grab just the displayed snippet. == Connect to your Database @@ -230,8 +229,8 @@ include::devguide:example$java/StartUsing.java[tags="connect-env",indent=0] 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]: +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] ---- @@ -250,8 +249,8 @@ Quarkus:: + -- Our xref:quarkus-extension:ROOT:overview.adoc[Couchbase Quarkus Java Extension docs] cover installing and connecting with the Quarkus extension in detail, -but if you already have Quarkus installed and a project ready (with `quarkus-couchbase` in your `pom.xml` or `build.gradle`), -then your `src/main/resources/application.properties` file needs to contain: +but if you already installed Quarkus and have a project ready (with `quarkus-couchbase` in your `pom.xml` or `build.gradle`), +then your `src/main/resources/application.properties` file must contain: [source,properties] ---- @@ -335,11 +334,10 @@ include::devguide:example$java/StartUsingCapella.java[tag=json,indent=0] === Insert (Create) and Upsert `insert` and `upsert` will both create a new document. -The difference between the two is that if a document with that key already exists, the `insert` operation will fail, -// throwing `DocumentExistsException` -- -while the `upsert` operation will succeed, replacing the content. +The difference between the two is that if the document key already exists, the `insert` operation fails, +// throwing the `DocumentExistsException` error. However, the `upsert` operation succeeds, replacing the content. -We need to provide a unique ID as the key, and we'll use a UUID here: +Always provide a unique ID as the key, and use a UUID here: .Creating a new document [source,java] @@ -371,7 +369,7 @@ and then accessing the value of the *status* key as a String. ==== Better Error Handling All three of these operations could fail, so there's quite a lot of error handling code here to do something quite simple. -One way to improve on this is by using `flatMap`, like this: +One way to improve on this is by using `flatMap`, as below: [source,java] ---- @@ -417,8 +415,8 @@ include::devguide:example$java/StartUsingCapella.java[tag=replace-named,indent=0 ---- //// -CAUTION: When you replace a document, it's usually good practice to use xref:howtos:kv-operations.adoc#optimistic-locking[optimistic locking]. -Otherwise, changes might get lost if two people change the same document at the same time. +CAUTION: While replacing a document, it is a good practice to use xref:howtos:kv-operations.adoc#optimistic-locking[optimistic locking]. +Otherwise, changes could be lost if two people change the same document at the same time. === Remove (Delete) @@ -442,13 +440,13 @@ Documents are organized into collections -- collections of documents that belong 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. +For example, consider 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. +Each document belongs to one collection. A document's ID is unique _within_ the collection. -Different scopes can hold collections with different names. +Different scopes 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. @@ -489,22 +487,22 @@ both Now you're up and running, try one of the following: -* Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know; -* Explore xref:howtos:kv-operations.adoc[Key Value Operations] (CRUD) against a document database; -* Or xref:howtos:sqlpp-queries-with-sdk.adoc[Query] with our SQL-based {sqlpp} query language; -* Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service]; -* A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search]; -* Or read up on xref:concept-docs:data-services.adoc[which service fits your use case]. +* Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know. +* Explore xref:howtos:kv-operations.adoc[Key Value Operations] (CRUD) against a document database. +* xref:howtos:sqlpp-queries-with-sdk.adoc[Query] with our SQL-based {sqlpp} query language. +* Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service]. +* A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search]. +* Read about xref:concept-docs:data-services.adoc[which service fits your use case]. === Additional Resources //// The Scala SDK includes three APIs. -The examples above show the simple blocking API, for simplicity, but you can also perform all operations in an async style using Scala `Future`, and a reactive style using Project Reactor `SMono` and `SFlux`. -Please see xref:howtos:concurrent-async-apis.adoc[Choosing an API] for more details. +The examples above show the simple blocking API, for simplicity. However, you can also perform all operations in an async style using Scala `Future`, and a reactive style using Project Reactor `SMono` and `SFlux`. +For more information, see xref:howtos:concurrent-async-apis.adoc[Choosing an API]. //// -The API reference is generated for each release and the latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. +The API reference is generated for every release. The latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. Couchbase welcomes community contributions to the Java SDK. The SDK source code is available on https://github.com/couchbase/couchbase-jvm-clients[GitHub]. @@ -512,11 +510,11 @@ The SDK source code is available on https://github.com/couchbase/couchbase-jvm-c === Troubleshooting * Couchbase Server is designed to work in the same WAN or availability zone as the client application. -If you're running the SDK on your laptop against a Capella cluster, see further information on: +If you are running the SDK on your laptop against a Capella cluster, see further information on: ** Notes on xref:ref:client-settings.adoc#constrained-network-environments[Constrained Network Environments]. ** xref:project-docs:compatibility.adoc#network-requirements[Network Requirements]. -** If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. -* Our https://www.couchbase.com/forums/c/java-sdk/5[community forum] is a great source of help. +** If you have a consumer-grade router which has problems with the DNS-SRV records, review the xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. +* The https://www.couchbase.com/forums/c/java-sdk/5[community forum] is a great source of help. //// @@ -535,36 +533,6 @@ If you're running the SDK on your laptop against a Capella cluster, see further - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - = Start Using the Java SDK :description: A quick start guide to get you up and running with Couchbase and the Java SDK. :page-partial: From 1f2312f08190048720b34cb315a316cecdeb1c08 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 15 Jul 2025 09:35:16 +0530 Subject: [PATCH 4/7] fixing some sentences and voice --- modules/hello-world/pages/start-using-sdk.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index c0749e2d..bdc4c718 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -333,9 +333,9 @@ include::devguide:example$java/StartUsingCapella.java[tag=json,indent=0] === Insert (Create) and Upsert -`insert` and `upsert` will both create a new document. -The difference between the two is that if the document key already exists, the `insert` operation fails, -// throwing the `DocumentExistsException` error. However, the `upsert` operation succeeds, replacing the content. +`insert` and `upsert` both creates a new document. +The difference between the two is that if the document key already exists, the `insert` operation fails and displays the `DocumentExistsException` error. +However, the `upsert` operation succeeds and replaces the content. Always provide a unique ID as the key, and use a UUID here: From e5bae0d8aee1a15c07ee482a6a73df3984408411 Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Tue, 15 Jul 2025 13:54:16 +0530 Subject: [PATCH 5/7] Fixing some sentences for Active voice & trailing periods. --- modules/hello-world/pages/start-using-sdk.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index bdc4c718..9cea12e9 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -333,11 +333,11 @@ include::devguide:example$java/StartUsingCapella.java[tag=json,indent=0] === Insert (Create) and Upsert -`insert` and `upsert` both creates a new document. -The difference between the two is that if the document key already exists, the `insert` operation fails and displays the `DocumentExistsException` error. +`insert` and `upsert` both create a new document. +The difference is that if the document key already exists, the `insert` operation fails and displays the `DocumentExistsException` error. However, the `upsert` operation succeeds and replaces the content. -Always provide a unique ID as the key, and use a UUID here: +Always provide a unique ID as the key, and use a UUID as shown below. .Creating a new document [source,java] @@ -350,7 +350,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] ---- @@ -437,11 +437,11 @@ Like `replace`, `remove` also optionally takes the CAS value if you want to make == Data Modeling Documents are organized into collections -- collections of documents that belong together. -You get to decide what it means to "belong." +You get to decide what it means to "belong". Developers usually put documents of the same type in the same collection. For example, consider 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`. +You can put the customer documents in a collection named `customers`, and the invoice documents in a collection named `invoices`. Each document belongs to one collection. A document's ID is unique _within_ the collection. @@ -449,7 +449,7 @@ A document's ID is unique _within_ the collection. Different scopes 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. +the collection name is unique within the scope. More details can be found on the xref:concept-docs:data-model.adoc[Data Model page]. @@ -485,7 +485,7 @@ both == Next Steps -Now you're up and running, try one of the following: +Now that your setup is up and running, try one of the following: * Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know. * Explore xref:howtos:kv-operations.adoc[Key Value Operations] (CRUD) against a document database. @@ -498,7 +498,7 @@ Now you're up and running, try one of the following: //// The Scala SDK includes three APIs. -The examples above show the simple blocking API, for simplicity. However, you can also perform all operations in an async style using Scala `Future`, and a reactive style using Project Reactor `SMono` and `SFlux`. +The examples above show the simple blocking API, for simplicity. However, you can also perform all the operations in an async style using Scala `Future`, and a reactive style using Project Reactor `SMono` and `SFlux`. For more information, see xref:howtos:concurrent-async-apis.adoc[Choosing an API]. //// From ec1d641454c456fad823dd13df2b17796b1bb6fa Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 16 Jul 2025 14:48:58 +0530 Subject: [PATCH 6/7] Update modules/hello-world/pages/start-using-sdk.adoc Co-authored-by: Hakim --- modules/hello-world/pages/start-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 9cea12e9..21cca4de 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -111,7 +111,7 @@ Note: The Travel Sample dataset is installed automatically when deploying a Cape 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. -Use the *Organization Owner* role automatically that is assigned to your account during installation of the Capella cluster. +Use the *Organization Owner* role that is automatically assigned to your account during installation of the Capella cluster. In production, as a best practice and also for data security, it is strongly recommended to set up the users with more granular access roles. -- From c47ed8f2c77aeca266b86b5166424f273624dccf Mon Sep 17 00:00:00 2001 From: Pallavi-Janardhan Date: Wed, 16 Jul 2025 17:43:16 +0530 Subject: [PATCH 7/7] Update modules/hello-world/pages/start-using-sdk.adoc Co-authored-by: Hakim --- modules/hello-world/pages/start-using-sdk.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 21cca4de..dea8c33d 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -194,7 +194,8 @@ 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 is a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages. A *Copy* icon is also available that allows you to grab just the displayed snippet. +TIP: There's a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages. +A *Copy* icon is also available that allows you to grab just the displayed snippet. == Connect to your Database