From ab7f2605df05783c43b7e380ffb3fcce37d3c209 Mon Sep 17 00:00:00 2001 From: teetangh Date: Sat, 6 Sep 2025 22:15:39 +0530 Subject: [PATCH] docs(spring-boot): modernize Couchbase configuration and enhance error handling - 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 --- .../markdown/java/spring-boot/spring-boot.md | 108 ++++++++++++++---- .../markdown/java/spring-data/spring-data.md | 106 +++++++++++++---- 2 files changed, 169 insertions(+), 45 deletions(-) diff --git a/tutorial/markdown/java/spring-boot/spring-boot.md b/tutorial/markdown/java/spring-boot/spring-boot.md index 2caa8f3..7a6dcb7 100644 --- a/tutorial/markdown/java/spring-boot/spring-boot.md +++ b/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= -e DB_USERNAME= -e DB_PASSWORD= +docker run -d --name springboot-container -p 8080:8080 \ + -e DB_CONN_STR= \ + -e DB_USERNAME= \ + -e DB_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 diff --git a/tutorial/markdown/java/spring-data/spring-data.md b/tutorial/markdown/java/spring-data/spring-data.md index d087f34..910febc 100644 --- a/tutorial/markdown/java/spring-data/spring-data.md +++ b/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.