docs(spring-boot): modernize Couchbase configuration and enhance error handling (#65)

- Updated Maven commands for building and running the application.
- Improved the `CouchbaseConfig` class with better error handling, connection timeout management, and enhanced logging.
- Revised application properties for Spring Boot 3.5+ compatibility, including new connection string formats and timeout settings.
- Added environment variable setup instructions for secure credential management.
- Enhanced integration test setup to ensure reliable execution and visibility into test results.
- Updated GitHub Actions workflow for multi-version testing and improved CI/CD reliability.

Files:
- tutorial/markdown/java/spring-boot/spring-boot.md
- tutorial/markdown/java/spring-data/spring-data.md

Author: teetangh

tutorial/markdown/java/spring-boot/spring-boot.md

@@ -48,41 +48,62 @@ git clone https://github.com/couchbase-examples/java-springboot-quickstart.git
 ### Install Dependencies
 
 ```shell
-mvn package
+mvn clean compile
 ```
 
-> Note: Maven automatically restores packages 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:
+The `CouchbaseConfig` class is a Spring configuration class responsible for setting up the connection to a Couchbase database in a Spring Boot application. It has been modernized with improved error handling and resilience:
 
-  - `getCouchbaseCluster()`: This bean creates and configures a connection to the Couchbase cluster using the provided hostname, username, and password.
+- `getCouchbaseCluster()`: Creates and configures a connection to the Couchbase cluster with:
+  - Proper variable scoping to handle connection timeouts gracefully  
+  - 30-second connection timeout with partial connectivity fallback
+  - Enhanced error logging and exception handling
 
-  - `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.
+- `getCouchbaseBucket(Cluster cluster)`: Retrieves a Couchbase bucket from the cluster with:
+  - Bucket existence validation before connection attempts
+  - 30-second ready timeout for improved reliability
+  - Comprehensive error handling for various failure scenarios
+
+**Key Improvements**: The configuration now handles connection timeouts more gracefully and provides better error diagnostics for troubleshooting connection issues.
 
 ### 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.
 
-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.
-
-The connection string should be in the following format:
+The modern Spring Boot 3.5+ configuration uses updated property names:
 
 ```properties
-spring.couchbase.bootstrap-hosts=couchbases://xyz.cloud.couchbase.com
-OR
-spring.couchbase.bootstrap-hosts=localhost
+# Modern Couchbase configuration (Spring Boot 3.5+)
+spring.couchbase.connection-string=${DB_CONN_STR}
+spring.couchbase.username=${DB_USERNAME}
+spring.couchbase.password=${DB_PASSWORD}
+spring.couchbase.bucket.name=travel-sample
+
+# Connection optimizations
+spring.couchbase.env.timeouts.query=30000ms
+spring.couchbase.env.timeouts.key-value=5000ms
+spring.couchbase.env.timeouts.connect=10000ms
 ```
 
-The couchbases protocol is used for secure connections.
+### Environment Variables Setup
+
+For security, use a `.env` file in your project root with your actual credentials:
 
 ```properties
-spring.couchbase.bootstrap-hosts=DB_CONN_STR
-spring.couchbase.bucket.user=DB_USERNAME
-spring.couchbase.bucket.password=DB_PASSWORD
+DB_CONN_STR=couchbases://xyz.cloud.couchbase.com
+DB_USERNAME=your_username
+DB_PASSWORD=your_password
 ```
 
+The connection string should be in the following format:
+- **Couchbase Capella**: `couchbases://xyz.cloud.couchbase.com` (secure)
+- **Local Couchbase**: `couchbase://localhost` (non-secure)
+
+The application uses the `dotenv-java` dependency to automatically load these environment variables.
+
 For more information on the spring boot connection string, see [Common Application Properties](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html).
 
 ## Running The Application
@@ -92,7 +113,7 @@ For more information on the spring boot connection string, see [Common Applicati
 At this point the application is ready, and you can run it via your IDE or from the terminal:
 
 ```shell
-mvn spring-boot:run -e -X
+mvn spring-boot:run
 ```
 
 > Note: Either the Couchbase Server must be installed and running on localhost or the connection string must be updated in the `application.properties` file.
@@ -108,7 +129,11 @@ docker build -t java-springboot-quickstart .
 Run the Docker image
 
 ```sh
-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>
+docker run -d --name springboot-container -p 8080:8080 \  
+  -e DB_CONN_STR=<connection_string> \  
+  -e DB_USERNAME=<username> \  
+  -e DB_PASSWORD=<password> \  
+  java-springboot-quickstart
 ```
 
 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.
@@ -401,12 +426,44 @@ 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.
+### Integration Tests
+
+This project uses Maven with proper integration test configuration. The tests connect to a real Couchbase instance and validate actual functionality:
 
 ```sh
 mvn test
 ```
 
+**Important**: This project was modernized to ensure integration tests actually execute (no false positives). The Maven surefire plugin configuration was updated to include integration tests that were previously excluded.
+
+### Test Validation
+
+To verify tests are actually running:
+1. Tests should show connection logs to Couchbase
+2. Test count should show actual execution (e.g., "Tests run: 18")
+3. Any test failures will show real assertion errors
+
+## Continuous Integration
+
+### GitHub Actions
+
+The project includes a modern GitHub Actions workflow (`.github/workflows/tests.yaml`) with:
+
+- **Multiple Java Versions**: Tests on Java 17 and 21
+- **Manual Triggering**: `workflow_dispatch` allows manual test runs
+- **Reliability Improvements**: 15-minute timeouts, fail-fast disabled for complete results
+- **Test Artifacts**: Automatic upload of test reports for debugging
+- **Simplified Commands**: Uses `./mvnw clean test` for focused testing
+
+### Running in CI/CD
+
+The workflow automatically:
+1. Sets up Java with Temurin distribution  
+2. Caches Maven dependencies for faster builds
+3. Executes integration tests against Couchbase
+4. Uploads test results as artifacts
+5. Sends failure notifications to Slack (if configured)
+
 ### Run Individual Tests:
 
 Additionally, you can run individual test classes or methods using the following commands:
@@ -431,9 +488,20 @@ 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/).
+This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/) with the following specifications:
+
+- **Spring Boot Version**: 3.5.5 (modernized from earlier versions)
+- **Java Version**: 17+ (updated from Java 8)  
+- **Build Tool**: Maven with wrapper (`mvnw`)
+- **Key Dependencies**: 
+  - Spring Boot Starter Web
+  - Couchbase Java SDK 3.7.9
+  - Spring Boot Validation
+  - SpringDoc OpenAPI (Swagger)
+  - Dotenv Java for environment variable management
+  - Project Lombok for reduced boilerplate
 
-A full list of packages are referenced in the `pom.xml` file.
+A full list of packages and versions are referenced in the `pom.xml` file.
 
 ## Contributing
 

tutorial/markdown/java/spring-data/spring-data.md

@@ -24,7 +24,7 @@ length: 30 Mins
 
 ### Prerequisites
 
-To run this prebuild project, you will need:
+To run this prebuilt project, you will need:
 
 - [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/dotnet-sdk/current/ref/travel-app-data-model.html) bucket loaded.
   - To run this tutorial using a self managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).
@@ -35,7 +35,7 @@ To run this prebuild project, you will need:
 
 ### Source Code
 
-The sample source code used in this tutorial is [published on GitHub](https://github.com/couchbase-examples/java-springboot-quickstart).
+The sample source code used in this tutorial is [published on GitHub](https://github.com/couchbase-examples/java-springdata-quickstart).
 To obtain it, clone the git repository with your IDE or execute the following command:
 
 ```shell
@@ -61,8 +61,9 @@ implementation 'org.springdoc:springdoc-openapi-ui:1.6.6'
 
 ### Database Server Configuration
 
-Spring Data couchbase connector can be configured by providing a `@Configuration` [bean](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition) that extends [`AbstractCouchbaseConfiguration`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.html).
-The sample application provides a configuration bean that uses default couchbase login and password:
+Spring Data Couchbase connector can be configured by providing a `@Configuration` [bean](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition) that extends [`AbstractCouchbaseConfiguration`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.html).
+
+The sample application provides a modernized configuration bean with improved error handling and environment variable support:
 
 ```java
 @Slf4j
@@ -152,23 +153,36 @@ Please refer to [Managing Connections using the Java SDK with Couchbase Server](
 
 You need to configure the connection details to your Couchbase Server in the application.properties file located in the src/main/resources directory.s
 
+**Modern Spring Boot 3.5+ Configuration:**
+
 ```properties
-spring.couchbase.bootstrap-hosts=DB_CONN_STR
-spring.couchbase.bucket.user=DB_USERNAME
-spring.couchbase.bucket.password=DB_PASSWORD
+# Modern Couchbase configuration 
+spring.couchbase.connection-string=${DB_CONN_STR}
+spring.couchbase.username=${DB_USERNAME}
+spring.couchbase.password=${DB_PASSWORD}
+spring.couchbase.bucket.name=travel-sample
+
+# Connection optimizations
+spring.couchbase.env.timeouts.query=30000ms
+spring.couchbase.env.timeouts.key-value=5000ms
+spring.couchbase.env.timeouts.connect=10000ms
 ```
 
-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.
+### Environment Variables Setup
 
-The connection string should be in the following format:
+For security, use a `.env` file in your project root:
 
 ```properties
-spring.couchbase.bootstrap-hosts=couchbases://xyz.cloud.couchbase.com
-OR
-spring.couchbase.bootstrap-hosts=localhost
+DB_CONN_STR=couchbases://xyz.cloud.couchbase.com
+DB_USERNAME=your_username
+DB_PASSWORD=your_password
 ```
 
-The couchbases protocol is used for secure connections. If you are using Couchbase Server 6.5 or earlier, you should use the couchbase protocol instead.
+The connection string formats:
+- **Couchbase Capella**: `couchbases://xyz.cloud.couchbase.com` (secure)
+- **Local Couchbase**: `couchbase://localhost` (non-secure)
+
+The `couchbases://` protocol is used for secure TLS connections (required for Couchbase Capella). The `couchbase://` protocol is for non-secure local connections.
 
 ## Running the Application
 
@@ -177,13 +191,13 @@ The couchbases protocol is used for secure connections. If you are using Couchba
 At this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.
 
 ```sh
-gradle bootRun
+./gradlew bootRun
 ```
 
-Note: If you're using Windows, you can run the application using the `gradle.bat` executable.
+Note: If you're using Windows, you can run the application using the Gradle wrapper batch file:
 
 ```sh
-./gradew.bat bootRun
+.\gradlew.bat bootRun
 ```
 
 ### Using Docker
@@ -362,22 +376,64 @@ For more information, see the [Couchbase Java SDK documentation](https://docs.co
 
 ## Running The Tests
 
-To run the tests, execute `./gradlew test` (`./gradlew.bat test` on Windows).
+### Integration Tests
+
+This project uses Gradle with comprehensive integration test setup. The tests connect to a real Couchbase instance:
 
 ```sh
 ./gradlew test
 ```
 
+**Windows users:**
+```sh
+.\gradlew.bat test
+```
+
+### Test Reliability
+
+This project was modernized to ensure reliable test execution:
+- Tests properly connect to Couchbase and validate real data
+- Integration tests are included in the standard test run
+- Test logging provides clear visibility into execution
+
+## Continuous Integration
+
+### GitHub Actions
+
+The project includes a modern GitHub Actions workflow with:
+
+- **Multi-Version Testing**: Java 17 and 21 support
+- **Manual Triggering**: `workflow_dispatch` for on-demand runs  
+- **Enhanced Reliability**: 15-minute timeouts, non-blocking failure handling
+- **Test Artifacts**: Automatic test report uploads
+- **Optimized Commands**: Uses `./gradlew clean test --stacktrace`
+
+### CI/CD Features
+
+The workflow provides:
+1. Temurin JDK setup with Gradle caching
+2. Real integration test execution against Couchbase
+3. Test result artifact collection for debugging
+4. Slack notification integration (configurable)
+
 ## Project Setup Notes
 
-This project was created using the [Spring Initializr](https://start.spring.io/) with the following options:
+This project was created using the [Spring Initializr](https://start.spring.io/) and modernized with:
+
+- **Project**: Gradle Project with Wrapper
+- **Language**: Java
+- **Spring Boot**: 3.5.5 (upgraded from 2.7.18)
+- **Packaging**: Jar
+- **Java Version**: 17+ (upgraded from Java 8)
+- **Key Dependencies**: 
+  - Spring Boot Starter Web
+  - Spring Boot Starter Data Couchbase  
+  - SpringDoc OpenAPI Starter WebMVC UI
+  - Spring Boot Starter Validation
+  - Project Lombok
+  - JUnit 5 (Jupiter)
 
-- Project: Gradle Project
-- Language: Java
-- Spring Boot: 2.7.18
-- Packaging: Jar
-- Java: 8
-- Dependencies: Spring Web, Spring Data Couchbase, Springdoc OpenAPI UI
+**Performance Optimizations**: The project uses `Slice` instead of `Page` for better memory efficiency and eliminates expensive `COUNT` queries in pagination scenarios.
 
 ## Contributing
 
@@ -399,7 +455,7 @@ If you would like to add another entity to the APIs, these are the steps to foll
 
 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.
 
-You need to update the connection string and the credentials in the [`src/main/resources/application.properties`](https://github.com/couchbase-examples/java-springboot-quickstart/blob/main/src/main/resources/application.properties) file.
+You need to update the connection string and the credentials in the [`src/main/resources/application.properties`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/resources/application.properties) file.
 
 > **NOTE:** Couchbase must be installed and running prior to running the Spring Boot app.