Skip to content

DOC-13358 Corrected a sentence by adding a trailing period. #454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Pallavi-Janardhan wants to merge 5 commits into from
Closed

DOC-13358 Corrected a sentence by adding a trailing period. #454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8c1f280
DOC-13358 Corrected a sentence by adding a trailing period.
Pallavi-Janardhan Jul 11, 2025
23da810
fixing few syntax errors
Pallavi-Janardhan Jul 14, 2025
5614d73
fixing some voice and syntax errors
Pallavi-Janardhan Jul 14, 2025
1f2312f
fixing some sentences and voice
Pallavi-Janardhan Jul 15, 2025
e5bae0d
Fixing some sentences for Active voice & trailing periods.
Pallavi-Janardhan Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions modules/hello-world/pages/overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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} +

Expand Down
16 changes: 10 additions & 6 deletions modules/hello-world/pages/sample-application.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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]
----
Expand All @@ -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`.
Expand Down
128 changes: 48 additions & 80 deletions modules/hello-world/pages/start-using-sdk.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand All @@ -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.
--
====

Expand All @@ -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]
====
Expand All @@ -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::
Expand All @@ -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}].
Expand Down Expand Up @@ -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]
Expand All @@ -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

Expand Down Expand Up @@ -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]
----
Expand All @@ -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]
----
Expand Down Expand Up @@ -334,12 +333,11 @@ 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.
`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.

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 as shown below.

.Creating a new document
[source,java]
Expand All @@ -352,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]
----
Expand All @@ -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]
----
Expand Down Expand Up @@ -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)

Expand All @@ -439,19 +437,19 @@ 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, 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`.
For example, consider you have two types of documents: customers and 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 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.
the collection name is unique within the scope.


More details can be found on the xref:concept-docs:data-model.adoc[Data Model page].
Expand Down Expand Up @@ -487,36 +485,36 @@ 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;
* 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 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].
////

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].

=== 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.
////


Expand All @@ -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:
Expand Down
Loading