Update Spring Boot and Spring Data Developer Portal Readmes (#24)

teetangh · web-flow · commit 14a89fd78de8 · 2024-05-07T06:48:22.000+05:30
* added spring boot readme

* added spring data readme and updated springboot readme

* fixed the readmes based on the feedback + added images

* fixed the sring boot and spring data readmes based on feedback

* updated spring boot and spring data docs based on feedback

* moved the spring bott and spring data files into seperate folders

* updated the docs based on feedback

* changed to invalid capella string

* Updated Spring Boot and Spring Data documentation

* resolved comments based on feedback

* updated boot and data readmes
diff --git a/tutorial/markdown/java/spring-boot/spring-boot.md b/tutorial/markdown/java/spring-boot/spring-boot.md
@@ -2,12 +2,12 @@
 # frontmatter
 path: "/tutorial-quickstart-java-springboot"
 # title and description do not need to be added to markdown, start with H2 (##)
-title: Start with Java and Spring Boot
+title: Quickstart in Couchbase with Java and Spring Boot
 short_title: Java and Spring Boot
 description:
-  - Learn how to configure Spring Data with Couchbase
+  - Learn to build a REST API in Java using Spring Boot and Couchbase
   - Explore key-based operations and SQL++ querying using Spring Data Couchbase repositories
-  - Build a simple REST APIs that stores user profiles on a Couchbase cluster
+  - Explore CRUD operations in action with Couchbase
 content_type: quickstart
 filter: sdk
 technology:
@@ -27,42 +27,6 @@ length: 30 Mins
 
 <!-- TODO:  Figure out how to add width to image size in try it now links -->
 
-## Table of Contents
-
-- [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [Source Code](#source-code)
-  - [Install Dependencies](#install-dependencies)
-  - [Database Server Configuration](#database-server-configuration)
-  - [Application Properties](#application-properties)
-- [Running The Application](#running-the-application)
-  - [Directly on the machine](#directly-on-the-machine)
-  - [Docker](#docker)
-- [Data Model](#data-model)
-- [Airline Document Structure](#airline-document-structure)
-- [Let's Review the Code](#lets-review-the-code)
-  - [Code Organization](#code-organization)
-  - [Model](#model)
-  - [Controller](#controller)
-  - [Service](#service)
-  - [Repository](#repository)
-- [Mapping Workflow](#mapping-workflow)
-  - [GET Mapping Workflow](#get-mapping-workflow)
-  - [POST Mapping Workflow](#post-mapping-workflow)
-  - [PUT Mapping Workflow](#put-mapping-workflow)
-  - [DELETE Mapping Workflow](#delete-mapping-workflow)
-- [Custom SQL++ Queries](#custom-sql-queries)
-  - [Get all airlines by country](#get-all-airlines-by-country)
-  - [Get all airlines by destination airport](#get-all-airlines-by-destination-airport)
-- [Running The Tests](#running-the-tests)
-  - [Run Individual Tests](#run-individual-tests)
-- [Project Setup Notes](#project-setup-notes)
-- [Contributing](#contributing)
-- [Appendix](#appendix)
-  - [Extending API by Adding New Entity](#extending-api-by-adding-new-entity)
-  - [Running Self Managed Couchbase Cluster](#running-self-managed-couchbase-cluster)
-  - [Swagger Documentation](#swagger-documentation)
-
 ## Getting Started
 
 ### Prerequisites
@@ -87,19 +51,19 @@ git clone https://github.com/couchbase-examples/java-springboot-quickstart.git
 mvn package
 ```
 
-> Note: Maven packages auto restore when building the project in IntelliJ IDEA or Eclipse depending on IDE configuration.
+> Note: Maven automatically restores packages when building the project. in IntelliJ IDEA or Eclipse depending on IDE configuration.
 
 ### Database Server Configuration
 
 - The `CouchbaseConfig` class is a Spring configuration class responsible for setting up the connection to a Couchbase database in a Spring Boot application. It defines two beans:
 
   - `getCouchbaseCluster()`: This bean creates and configures a connection to the Couchbase cluster using the provided hostname, username, and password.
 
-  - `getCouchbaseBucket(Cluster cluster)`: This bean creates a Couchbase bucket within the cluster if it doesn't already exist and returns the Bucket object associated with the specified bucket name.
+  - `getCouchbaseBucket(Cluster cluster)`: This bean retrieves a Couchbase bucket from a cluster, ensuring it exists and is ready within a timeout, throwing exceptions if not found or if connection times out.
 
 ### Application Properties
 
-You need to configure the connection details to your Couchbase Server in the application.properties file located in the src/main/resources directory.
+You need to configure the connection details to your Couchbase Server in the `application.properties` file located in the `src/main/resources` directory.
 
 In the connection string, replace `DB_CONN_STR` with the connection string of your Couchbase cluster. Replace `DB_USERNAME` and `DB_PASSWORD` with the username and password of a Couchbase user with access to the bucket.
 
@@ -144,7 +108,7 @@ docker build -t java-springboot-quickstart .
 Run the Docker image
 
 ```sh
-docker run -d --name springboot-container -p 9440:8080 java-springboot-quickstart -e DB_CONN_STR=<connection_string> -e DB_USERNAME=<username> -e DB_PASSWORD=<password>
+docker run -d --name springboot-container -p 8080:8080 java-springboot-quickstart -e DB_CONN_STR=<connection_string> -e DB_USERNAME=<username> -e DB_PASSWORD=<password>
 ```
 
 Note: The `application.properties` file has the connection information to connect to your Capella cluster. You can also pass the connection information as environment variables to the Docker container.
@@ -166,7 +130,7 @@ For this tutorial, we use three collections, `airport`, `airline` and `route` th
 
 ## Airline Document Structure
 
-We will be setting up a REST API to manage some airline documents. The `name` field is the name of the airline. The `callsign` field is the callsign of the airline. The `iata` field is the IATA code of the airline. The `icao` field is the ICAO code of the airline. The `country` field is the country of the airline. 
+We will be setting up a REST API to manage some airline documents. The `name` field is the name of the airline. The `callsign` field is the callsign of the airline. The `iata` field is the IATA code of the airline. The `icao` field is the ICAO code of the airline. The `country` field is the country of the airline.
 
 Our airline document will have a structure similar to the following example:
 
@@ -176,7 +140,7 @@ Our airline document will have a structure similar to the following example:
   "callsign": "Couchbase",
   "iata": "CB",
   "icao": "CBA",
-  "country": "United States",
+  "country": "United States"
 }
 ```
 
@@ -387,7 +351,7 @@ These workflows illustrate how each HTTP method interacts with the `AirlineServi
 
 ## Custom SQL++ Queries
 
-1. Get all airlines by country
+### 1. Get all airlines by country
 
 ```java
 
@@ -411,7 +375,7 @@ In the query, we are using the `country` parameter to filter the results by coun
 
 Once the query is executed, the `AirlineController` constructs an HTTP response with a status code of 200 OK and includes the list of airlines in the response body as a list of JSON objects.
 
-2. Get all airlines by destination airport
+### 2. Get all airlines by destination airport
 
 ```java
  @Override
@@ -437,12 +401,12 @@ Once the query is executed, the `AirlineController` constructs an HTTP response
 
 ## Running The Tests
 
+This command will execute all the test cases in your project.
+
 ```sh
 mvn test
 ```
 
-This command will execute all the test cases in your project.
-
 ### Run Individual Tests:
 
 Additionally, you can run individual test classes or methods using the following commands:
@@ -467,9 +431,9 @@ mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.RouteIntegration
 
 ## Project Setup Notes
 
-This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/). The HealthCheckController is provided as a santity check and is used in unit tests.
+This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/).
 
-A full list of packages are referenced in the pom.xml file.
+A full list of packages are referenced in the `pom.xml` file.
 
 ## Contributing
 
diff --git a/tutorial/markdown/java/spring-data/spring-data.md b/tutorial/markdown/java/spring-data/spring-data.md
@@ -1,56 +1,25 @@
 ---
 # frontmatter
 path: "/tutorial-quickstart-java-springdata"
-title: Couchbase With Spring-Boot and Spring Data
-short_title: Spring Data
+title: Quickstart in Couchbase with Java and Spring Data
+short_title: Java and Spring Data
 description:
-  - Build a REST API with Couchbase and Spring Data
-  - Learn how to configure the Couchbase SDK
-content_type: tutorial
+  - Learn to build a REST API in Java using Spring Data and Couchbase
+  - Explore key-based operations and SQL++ querying using Spring Data Couchbase repositories
+  - Explore CRUD operations in action with Couchbase
+content_type: quickstart
 filter: sdk
 technology:
   - kv
   - query
 tags:
+  - REST API
   - Spring Data
 sdk_language:
   - java
 length: 30 Mins
 ---
 
-## Table of Contents
-
-- [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [Source Code](#source-code)
-  - [Install Dependencies](#install-dependencies)
-  - [Database Server Configuration](#database-server-configuration)
-  - [Application Properties](#application-properties)
-- [Running the Application](#running-the-application)
-  - [Directly on Machine](#directly-on-machine)
-  - [Using Docker](#using-docker)
-- [Data Model](#data-model)
-- [Airline Document Structure](#airline-document-structure)
-- [Let's Review the Code](#lets-review-the-code)
-  - [Code Organization](#code-organization)
-  - [Repository](#repository)
-  - [Model](#model)
-  - [Controller](#controller)
-  - [Service](#service)
-- [Mapping Workflow](#mapping-workflow)
-  - [GET Mapping Workflow](#get-mapping-workflow)
-  - [POST Mapping Workflow](#post-mapping-workflow)
-  - [PUT Mapping Workflow](#put-mapping-workflow)
-  - [DELETE Mapping Workflow](#delete-mapping-workflow)
-- [Custom SQL++ Queries](#custom-sql-queries)
-- [Running The Tests](#running-the-tests)
-- [Project Setup Notes](#project-setup-notes)
-- [Contributing](#contributing)
-- [Appendix](#appendix)
-  - [Extending API by Adding New Entity](#extending-api-by-adding-new-entity)
-  - [Running Self Managed Couchbase Cluster](#running-self-managed-couchbase-cluster)
-  - [Swagger Documentation](#swagger-documentation)
-
 ## Getting Started
 
 ### Prerequisites
@@ -77,32 +46,14 @@ git clone https://github.com/couchbase-examples/java-springdata-quickstart.git
 
 Gradle dependencies:
 
-```groovy
+```gradle
 implementation 'org.springframework.boot:spring-boot-starter-web'
 // spring data couchbase connector
 implementation 'org.springframework.boot:spring-boot-starter-data-couchbase'
 // swagger ui
 implementation 'org.springdoc:springdoc-openapi-ui:1.6.6'
 ```
 
-Maven dependencies:
-
-```xml
-<dependency>
-  <groupId>org.springframework.boot</groupId>
-  <artifactId>spring-boot-starter-data-couchbase</artifactId>
-</dependency>
-<dependency>
-  <groupId>org.springframework.boot</groupId>
-  <artifactId>spring-boot-starter-web</artifactId>
-</dependency>
-<dependency>
-  <groupId>org.springdoc</groupId>
-  <artifactId>springdoc-openapi-ui</artifactId>
-  <version>1.6.6</version>
-</dependency>
-```
-
 #### Useful Links
 
 - [Spring Data Couchbase - Reference Documentation](https://docs.spring.io/spring-data/couchbase/docs/current/reference/html/)
@@ -114,38 +65,85 @@ Spring Data couchbase connector can be configured by providing a `@Configuration
 The sample application provides a configuration bean that uses default couchbase login and password:
 
 ```java
+@Slf4j
 @Configuration
+@EnableCouchbaseRepositories
 public class CouchbaseConfiguration extends AbstractCouchbaseConfiguration {
 
+  @Value("#{systemEnvironment['DB_CONN_STR'] ?: '${spring.couchbase.bootstrap-hosts:localhost}'}")
+  private String host;
+
+  @Value("#{systemEnvironment['DB_USERNAME'] ?: '${spring.couchbase.bucket.user:Administrator}'}")
+  private String username;
+
+  @Value("#{systemEnvironment['DB_PASSWORD'] ?: '${spring.couchbase.bucket.password:password}'}")
+  private String password;
+
+  @Value("${spring.couchbase.bucket.name:travel-sample}")
+  private String bucketName;
+
   @Override
   public String getConnectionString() {
-    // capella
-    // return "couchbases://cb.xyz.cloud.couchbase.com";
-
-    // localhost
-    return "127.0.0.1"
+    return host;
   }
 
   @Override
   public String getUserName() {
-    return "Administrator";
+    return username;
   }
 
   @Override
   public String getPassword() {
-    return "password";
+    return password;
   }
 
   @Override
   public String getBucketName() {
-    return "springdata_quickstart";
+    return bucketName;
+  }
+
+  @Override
+  public String typeKey() {
+    return "type";
+  }
+
+  @Override
+  @Bean(destroyMethod = "disconnect")
+  public Cluster couchbaseCluster(ClusterEnvironment couchbaseClusterEnvironment) {
+    try {
+      log.debug("Connecting to Couchbase cluster at " + host);
+      return Cluster.connect(getConnectionString(), getUserName(), getPassword());
+    } catch (Exception e) {
+      log.error("Error connecting to Couchbase cluster", e);
+      throw e;
+    }
+  }
+
+  @Bean
+  public Bucket getCouchbaseBucket(Cluster cluster) {
+    try {
+      if (!cluster.buckets().getAllBuckets().containsKey(getBucketName())) {
+        log.error("Bucket with name {} does not exist. Creating it now", getBucketName());
+        throw new BucketNotFoundException(bucketName);
+      }
+      return cluster.bucket(getBucketName());
+    } catch (Exception e) {
+      log.error("Error getting bucket", e);
+      throw e;
+    }
   }
 
-  ...
+}
 ```
 
 > _from config/CouchbaseConfiguration.java_
 
+These methods are used to configure and retrieve a Couchbase Cluster and a specific Bucket within that cluster in a Spring application.
+
+- `couchbaseCluster(ClusterEnvironment couchbaseClusterEnvironment)`: This method configures and returns a Cluster instance using the provided ClusterEnvironment. It logs a debug message indicating the connection attempt to the Couchbase cluster. If an error occurs during the connection attempt, it logs an error message and rethrows the exception.
+
+- `getCouchbaseBucket(Cluster cluster)`: This method retrieves a specific Bucket from the given Cluster. It first checks if the bucket exists in the cluster by calling cluster.buckets().getAllBuckets().containsKey(getBucketName()). If the bucket does not exist, it logs an error message, throws a BucketNotFoundException, and stops the application startup. Otherwise, it returns the Bucket instance.
+
 This default configuration assumes that you have a locally running Couchbae server and uses standard administrative login and password for demonstration purpose.
 Applications deployed to production or staging environments should use less privileged credentials created using [Role-Based Access Control](https://docs.couchbase.com/go-sdk/current/concept-docs/rbac.html).
 Please refer to [Managing Connections using the Java SDK with Couchbase Server](https://docs.couchbase.com/java-sdk/current/howtos/managing-connections.html) for more information on Capella and local cluster connections.
@@ -229,11 +227,11 @@ We will be setting up a REST API to manage some airline documents. Our airline d
   "callsign": "Couchbase",
   "iata": "CB",
   "icao": "CBA",
-  "country": "United States",
+  "country": "United States"
 }
 ```
 
- The `name` field is the name of the airline. The `callsign` field is the callsign of the airline. The `iata` field is the IATA code of the airline. The `icao` field is the ICAO code of the airline. The `country` field is the country of the airline. 
+The `name` field is the name of the airline. The `callsign` field is the callsign of the airline. The `iata` field is the IATA code of the airline. The `icao` field is the ICAO code of the airline. The `country` field is the country of the airline.
 
 ## Let's Review the Code
 
@@ -250,12 +248,20 @@ To begin clone the repo and open it up in the IDE of your choice to learn about
 ### Repository
 
 `AirlineRepository.java`
-This interface extends the `CouchbaseRepository` interface and provides methods for CRUD operations. The `@N1qlPrimaryIndexed` annotation creates a primary index on the `airline` collection. The `@ViewIndexed` annotation creates a view index on the `airline` collection. The `@Query` annotation allows us to create custom N1QL queries. The `@ScanConsistency` annotation allows us to specify the scan consistency for the query. The `@Param` annotation allows us to specify parameters for the query.
+This interface extends the `CouchbaseRepository` interface and provides methods for CRUD operations.
+
+- `@Scope("..."):` Specifies the scope of the repository, which helps organize and manage documents within a Couchbase bucket.
+
+- `@Collection("..."):` Specifies the collection within the bucket where the documents are stored.
+
+- `@Repository:` Marks the interface as a repository component in the Spring application context.
+
+- `@ScanConsistency(query = QueryScanConsistency.REQUEST_PLUS)`: Specifies the scan consistency level for queries executed by methods in this repository, ensuring strong consistency for read operations.
 
 ### Model
 
 `Airline.java`
-This class represents an airline document. The `@Document` annotation indicates that this class is a Couchbase document. The `@Field` annotation indicates that the following fields are Couchbase document fields:  `name`, `callsign`, `iata`, `icao`, `country`.
+This class represents an airline document. The `@Document` annotation indicates that this class is a Couchbase document. The `@Field` annotation indicates that the following fields are Couchbase document fields: `name`, `callsign`, `iata`, `icao`, `country`.
 
 ### Controller
 
