DEV Community: İbrahim Gündüz

Spring Boot: A Practical Guide to Building Review Environments for Feature Branches

İbrahim Gündüz — Sat, 17 Jan 2026 18:42:38 +0000

Testing is one of the most crucial steps in the software development lifecycle. To ensure that the features we develop work correctly before integration, a review environment provides a dedicated space where application features can be tested using automated or manual tests.

In this article, we will focus on building a review environment on a dedicated PC or virtual machine.

Externalizing Application Configuration with Environment Variables

To ensure that each feature works correctly, the application must be fully isolated from other instances, including its external dependencies such as databases, caches, and message queues. Since we will run a separate instance of the application for each feature branch, configuration must be externalized using environment variables. This allows the application to dynamically determine which external resources it should connect to at runtime.

As we have already covered this topic in previous posts, I will not dive into the details of externalizing application configuration or providing deployment isolation for external resources such as Redis or RabbitMQ. However, if you haven’t read them yet, I strongly recommend taking a look at the following articles before continuing:

For our example project, the application will connect to PostgreSQL, Redis, and RabbitMQ, with isolation achieved through a dedicated database name, cache key prefix, and broker virtual host for each feature branch.

# application.yaml

spring:
  rabbitmq:
    host: ${RABBITMQ_HOST:localhost}
    port: ${RABBITMQ_PORT:5672}
    virtualHost: ${RABBITMQ_VHOST:dev}
    username: ${RABBITMQ_USER:guest}
    password: ${RABBITMQ_PASSWORD:guest}
  datasource:
    url: jdbc:postgresql://${POSTGRESQL_HOST:localhost}:${POSTGRESQL_PORT:5432}/${POSTGRESQL_DBNAME:dev}
    driver-class-name: org.postgresql.Driver
    username: ${POSTGRESQL_USER:postgres}
    password: ${POSTGRESQL_PASSWORD:postgres}
  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      password: ${REDIS_PASSWORD}
      database: 0
  cache:
    type: redis
    redis:
      key-prefix: ${CACHE_KEY_PREFIX:default}
      use-key-prefix: true

Containerizing The Application

In this step, we will create a Dockerfile that packages the application into a container image, enabling it to run in an isolated and reproducible environment.

The following example demonstrates a multi-stage Dockerfile, where the application is built in the first stage and then copied into a lightweight runtime image in the second stage.

ARG MAVEN_VERSION=3.9-eclipse-temurin-21
ARG JRE_VERSION=21-jre

FROM maven:${MAVEN_VERSION} AS build

ARG CI_COMMIT_REF_NAME=dev

WORKDIR /build
COPY pom.xml .
RUN mvn -B -q dependency:go-offline

COPY src ./src
RUN mvn -B -q package -DskipTests -Drevision=${CI_COMMIT_REF_NAME}

FROM eclipse-temurin:${JRE_VERSION}

WORKDIR /app
COPY --from=build /build/target/*.jar app.jar
EXPOSE 8080

ENTRYPOINT ["java","-jar","/app/app.jar"]

In the example above, the Maven project is built using the -Drevision=${CI_COMMIT_REF_NAME} parameter. This value is captured at build time and exposed through the application using the build-info feature of the spring-boot-maven-plugin, allowing the build version to be displayed in a controller response.

Since the required application configurations have already been externalized, this versioning approach is optional and can be omitted in your own project if build metadata is not required at runtime.

Provision the Review Environment Infrastructure

With the application packaged as a container image, the next step is to provision an environment capable of running these containers. Given the operational overhead of deploying Kubernetes on a dedicated system, Docker Swarm provides a simpler and more suitable alternative for hosting isolated review environments.

The first step in provisioning the environment is installing Docker on the target machine. Since this process is well documented in the official Docker documentation, we won’t cover the installation steps here. Instead, you can refer to the official guide at the following link:

Install Docker Engine

Once Docker is installed, you can initialize Docker Swarm as shown below:

$ docker swarm init

Swarm initialized: current node (pzfpqsijpyuypd4xmluzlv3u7) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-2rci0c2v4bs7hh8bfpkenvmow78hcdcufs6411m2qaz90avlrt-0drqyzyeg8pghhu0tc4zjepq2 192.168.1.106:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

As shown above, Docker outputs the required commands for forming a Swarm cluster and scaling it across multiple nodes. You can add additional machines to the swarm using the docker swarm join --token ... command provided during initialization.

Provisioning Shared Infrastructure Services

In real-world environments, stateful services such as databases and message brokers are typically provisioned once and shared across deployments. These services are not recreated as part of the CI/CD pipeline, as doing so would introduce unnecessary risk and complexity. Instead, only application services are managed dynamically through CI/CD.

The following example demonstrate deployment configuration of the shared services.

# infra.yaml

services:
  pgsql:
    image: postgres:18.1
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
      interval: 2s
      timeout: 120s
      retries: 15
      start_period: 30s
    volumes:
      - postgresql_data:/var/lib/postgresql:Z
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 240s
    networks:
      - backend_net

  redis:
    image: redis:8.2
    ports:
      - 6379:6379
    healthcheck:
      test: [ "CMD", "redis-cli", "ping" ]
      interval: 2s
      timeout: 120s
      retries: 15
      start_period: 30s
    volumes:
      - redis_data:/data
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 240s
    networks:
      - backend_net

  rabbitmq:
    image: rabbitmq:4.2.2-management-alpine
    ports:
      - 15672:15672
    healthcheck:
      test: [ "CMD", "rabbitmq-diagnostics", "-q", "ping" ]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks:
      - backend_net
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq

  traefik:
    image: traefik:v3.6.7
    command:
      - "--providers.swarm=true"
      - "--providers.swarm.exposedByDefault=false"
      - "--entrypoints.web.address=:80"
      - "--ping=true"
      - "--ping.entrypoint=web"
      - "--log.level=INFO"
    ports:
      - "80:80"
    healthcheck:
      test: [ "CMD", "wget", "--spider", "-q", "http://localhost/ping" ]
      interval: 5s
      timeout: 2s
      retries: 5
      start_period: 10s
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - ingress_net

volumes:
  postgresql_data:
    driver: local

  redis_data:
    driver: local

  rabbitmq_data:
    driver: local

networks:
  ingress_net:
    external: true
  backend_net:
    external: true

There are a few important points worth mentioning about this configuration. Since shared infrastructure services and feature-branch applications are deployed as separate stacks, Docker Swarm would normally create isolated default networks for each deployment. However, in this setup, application services must be able to access the shared infrastructure, and Traefik must be able to route incoming requests to feature-branch deployments.

To enable this, we define two shared overlay networks:

ingress_net for routing external traffic from Traefik to application services
backend_net for communication between application services and shared backend services

Because these networks are marked as external, they must be created manually before deploying any stacks.

$ docker network create --driver overlay ingress_net && \
  docker network create --driver overlay backend_net

ac6il04xh6p5fct8kg6h5k4dv
nxbqa4tl9urpcc94b8xm53eyv

Once the networks are created, you can deploy the shared infrastructure stack as shown below:

$ docker stack deploy -c infra.yaml infra --detach

Creating service infra_traefik
Creating service infra_pgsql
Creating service infra_redis
Creating service infra_rabbitmq

Deploying Feature-Branch Application Services

With the shared infrastructure in place, we can now deploy the application itself as isolated review environments. In this section, we deploy a feature-branch instance of the application and expose it through Traefik using hostname-based routing.

The following stack definition describes how a single feature branch is deployed as an isolated application service. Branch-specific values, such as the branch name (CI_COMMIT_REF_NAME), are injected at deployment time by the CI tool.

# app.yaml

services:
  app:
    image: my-app:${CI_COMMIT_REF_NAME}
    environment:
      RABBITMQ_HOST: rabbitmq
      RABBITMQ_PORT: 5672
      RABBITMQ_VHOST: ${CI_COMMIT_REF_NAME}
      RABBITMQ_USER: ${CI_COMMIT_REF_NAME}_user
      RABBITMQ_PASSWORD: YourStrongPassword
      POSTGRESQL_HOST: pgsql
      POSTGRESQL_PORT: 5432
      POSTGRESQL_DBNAME: app_${CI_COMMIT_REF_NAME}
      POSTGRESQL_USER: postgres
      POSTGRESQL_PASSWORD: postgres
      REDIS_HOST: redis
      REDIS_PORT: 6379
      CACHE_KEY_PREFIX: "${CI_COMMIT_REF_NAME}:"
    networks:
      - backend_net
      - ingress_net
    deploy:
      labels:
        - "traefik.enable=true"
        - "traefik.swarm.network=ingress_net"
        - "traefik.http.routers.app-${CI_COMMIT_REF_NAME}.rule=Host(`${CI_COMMIT_REF_NAME}.example.com`)"
        - "traefik.http.routers.app-${CI_COMMIT_REF_NAME}.entrypoints=web"
        - "traefik.http.services.app-${CI_COMMIT_REF_NAME}.loadbalancer.server.port=8080"

networks:
  ingress_net:
    external: true
  backend_net:
    external: true

CI/CD Integration

Connecting the CI Environment to Docker Swarm

To deploy services into Docker Swarm, the CI environment must be able to interact with the Swarm manager. This is typically achieved by running a CI agent, such as a GitLab Runner, on a Swarm manager node or in an environment with access to the Docker API. Once configured, the CI pipeline can build images and deploy stacks directly into the cluster using standard Docker commands.

Adding Packaging Step To CI/CD Pipeline

To build the application image, the CI pipeline runs the docker build command and pushes the resulting image to a container registry. Make sure to consult your CI tool’s documentation to determine which environment variable is provided to represent the current branch name.

$ docker build \                                     
  --build-arg CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME} \                                            
  -t my-app:$CI_COMMIT_REF_NAME .
...
$ docker push my-app:$CI_COMMIT_REF_NAME

Adding Provisioning Step TO CI/CD Pipeline

Since each feature branch is deployed with isolated resources—such as a dedicated PostgreSQL database and a RabbitMQ virtual host—the CI/CD pipeline must perform a provisioning step before deploying the application service. This step prepares the required backend resources so the application can start successfully.

Creating the PostgreSQL Database

The following script retrieves the running PostgreSQL container backing the infra_pgsql service and creates a branch-specific database:

export SERVICE_ID=$(docker service ps -q --filter "desired-state=running" infra_pgsql)
export CONTAINER_ID=$(docker inspect ${SERVICE_ID} --format '{{.Status.ContainerStatus.ContainerID}}') 
docker exec -it ${CONTAINER_ID} createdb -U postgres app_${CI_COMMIT_REF_NAME} || true

This command is intentionally idempotent: if the database already exists, the pipeline continues without failing.

After the database is created, the CI pipeline executes database migrations against the newly created database before deploying the application. This ensures that each feature branch starts with a clean and predictable schema.

Creating the RabbitMQ Virtual Host and User

Similarly, RabbitMQ resources must be created inside the running RabbitMQ container. The following commands create a virtual host and a dedicated user for the feature branch:

export SERVICE_ID=$(docker service ps -q --filter "desired-state=running" infra_rabbitmq)
export CONTAINER_ID=$(docker inspect ${SERVICE_ID} --format '{{.Status.ContainerStatus.ContainerID}}') 
docker exec -it ${CONTAINER_ID} rabbitmqctl add_vhost ${CI_COMMIT_REF_NAME}
docker exec -it ${CONTAINER_ID} rabbitmqctl add_user ${CI_COMMIT_REF_NAME}_user YourStrongPassword
docker exec -it ${CONTAINER_ID} rabbitmqctl set_user_tags ${CI_COMMIT_REF_NAME}_user
docker exec -it ${CONTAINER_ID} rabbitmqctl set_permissions -p ${CI_COMMIT_REF_NAME} \
  ${CI_COMMIT_REF_NAME}_user \
  ".*" ".*" ".*"

This setup ensures that each feature branch has its own isolated messaging context without interfering with other deployments.

By provisioning branch-specific resources as part of the CI/CD pipeline, the application remains environment-agnostic, shared infrastructure services remain long-lived, and feature-branch deployments become fully automated and reproducible.

This approach closely mirrors how review environments are implemented in real-world systems.

Deploying the Feature-Branch Stack from CI

Once the application image is built and the required backend resources are provisioned, the final step in the pipeline is deploying the feature-branch stack into Docker Swarm. This is done by reusing the same stack definition and injecting branch-specific values at deployment time.

The following command deploys the application stack for the current feature branch:

$ docker stack deploy \
  -c app.yaml \
  app-${CI_COMMIT_REF_NAME} \
  --detach

Cleanup Step

Most CI tools provide a mechanism to define cleanup tasks that run when a feature branch is merged or removed. For example, GitLab CI supports this through features such as auto_stop and on_stop jobs. Refer to the official documentation of your CI solution to identify the appropriate mechanism and configure it to execute the required cleanup commands, such as dropping the previously created database and removing branch-specific RabbitMQ resources.

Configuring Wildcard DNS for Review Environments

To make feature-branch review environments accessible via unique hostnames, a wildcard DNS record is required. Instead of creating individual DNS records for each branch, a single wildcard record is configured to route all subdomains to the Docker Swarm instance.

For example, the following DNS record maps all subdomains of example.com to the Swarm manager node:

A *.example.com → <swarm-manager-ip>

With this configuration in place, requests to ${CI_COMMIT_REF_NAME}.example.com are forwarded to Traefik, which then routes the request to the corresponding application service based on hostname rules defined in the deployment labels.

Demo Time!

The example application included in this post exposes a simple endpoint that returns the currently deployed application version. Let’s call the root endpoint to verify that the request is correctly routed to the feature-branch deployment.

$ curl MF-443.example.com

Current version is: MF-443

If you are testing locally, you can achieve the same result by explicitly setting the Host header in the request:

$ curl -H "Host: MF-443.example.com" http://127.0.0.1

Current version is: MF-443

Conclusion

By combining containerization, externalized configuration, and declarative deployments, feature branches can be promoted to fully isolated review environments with minimal overhead. This approach enables fast feedback cycles while keeping shared infrastructure stable and manageable. Although the examples in this article use Docker Swarm, the same principles apply to other orchestration platforms and can be adapted to fit different team sizes and operational constraints.

As always, you can find the code example in the following repository.

Review Environment Code Example

Thanks for reading!

Credits:

Docker Official Documents | Swarm Mode
Baeldung | Add Build Properties to a Spring Boot Application
Cover photo by Homa Appliances on Unsplash

Circuit Breaker in Inter-Service Communication

İbrahim Gündüz — Sat, 10 Jan 2026 15:29:20 +0000

Compared to in-memory calls, network-based communication introduces additional complexity. Remote calls may fail due to timeouts, network instability, or errors in downstream services. In high-traffic, internet-facing systems, such failures can escalate into catastrophic issues and potentially render the system unresponsive. For this reason, the circuit breaker pattern is used to prevent such scenarios.

In practice, the circuit breaker pattern is implemented by wrapping a remote call with a component that monitors failures. When the failure rate exceeds a configured threshold, the circuit breaker transitions to the open state, preventing calls from reaching the protected service.

In this article, we’ll explore some Java-based solutions related to this topic.

Resilience4j

Resilience4j is a lightweight Java library providing fault-tolerance patterns such as circuit breaker, retry, rate limiter, and bulkhead with several modules. (You can find the modules here: Maven Repositories)

Since we are focusing on the circuit breaker pattern, let’s walk through the steps required to use the circuit breaker module from Resilience4j.

To start, we need to add the resilience4j-circuitbreaker dependency to our pom.xml file.

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-circuitbreaker</artifactId>
    <version>2.3.0</version>
</dependency>

Creating a CircuitBreaker Configuration

Next, we need to create an instance of circuit breaker registry. For the example code, we've created circuit breaker registry with a minimal configuration.

CircuitBreakerConfig config = CircuitBreakerConfig.custom()
                .slidingWindowSize(10)
                .minimumNumberOfCalls(5)
                .failureRateThreshold(50)
                .build();

CircuitBreakerRegistry circuitBreakerRegistry = CircuitBreakerRegistry.of(config);

This configuration means:

The circuit breaker evaluates the last 10 calls
At least 5 calls must be recorded before calculating the failure rate
If 50% or more of the calls fail, the circuit breaker transitions to OPEN

You can find all available configuration options here: https://resilience4j.readme.io/docs/circuitbreaker#create-and-configure-a-circuitbreaker

Executing The Remote Call

You can create an instance of CircuitBreaker from the registry and execute a remote call using the executeSupplier() method:

CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("circuitBreaker");
String result = circuitBreaker.executeSupplier(() -> paymentGateway.getStatus("TRID00001"));

To better understand how the circuit breaker behaves, let’s examine a test scenario.

Scenario 1: The remote service is unreachable from the beginning

CircuitBreakerConfig config = CircuitBreakerConfig.custom()
        .slidingWindowSize(10)
        .minimumNumberOfCalls(5)
        .failureRateThreshold(50)
        .build();

CircuitBreakerRegistry circuitBreakerRegistry = CircuitBreakerRegistry.of(config);
CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("circuitBreaker");

PaymentGateway paymentGateway = mock(PaymentGateway.class);
when(paymentGateway.getStatus(anyString())).thenThrow(new RuntimeException("Failed"));

for (int i = 1; i <= 10; i++) {
    try {
        String result = circuitBreaker.executeSupplier(
            () -> paymentGateway.getStatus("TRID00001")
        );
    } catch (RuntimeException exception) {
        System.out.printf(
            "%d) %s:%s%n", 
            i, 
            exception.getClass().getSimpleName(), 
            exception.getMessage()
        );
    }
}

verify(paymentGateway, times(5)).getStatus(anyString());
Assertions.assertThat(circuitBreaker.getState())
    .isEqualTo(CircuitBreaker.State.OPEN);

We'll see the following output:

1) RuntimeException:Failed
2) RuntimeException:Failed
3) RuntimeException:Failed
4) RuntimeException:Failed
5) RuntimeException:Failed
6) CallNotPermittedException:CircuitBreaker 'circuitBreaker' is OPEN and does not permit further calls
7) CallNotPermittedException:CircuitBreaker 'circuitBreaker' is OPEN and does not permit further calls
8) CallNotPermittedException:CircuitBreaker 'circuitBreaker' is OPEN and does not permit further calls
9) CallNotPermittedException:CircuitBreaker 'circuitBreaker' is OPEN and does not permit further calls
10) CallNotPermittedException:CircuitBreaker 'circuitBreaker' is OPEN and does not permit further calls

In this test, the circuit breaker is configured with minimumNumberOfCalls(5).
This means the circuit breaker will not make any state transition decisions until at least 5 calls have been recorded.

Because all recorded calls fail and the configured failure rate threshold is 50%, the circuit breaker transitions to the OPEN state immediately after the fifth call. Once open, it prevents further calls from reaching the remote service and throws a CallNotPermittedException instead.

Scenario 2: Failed Calls Exceeds The Failure Rate Threshold And The Remote Service Recover Later

CircuitBreakerConfig config = CircuitBreakerConfig.custom()
        .slidingWindowSize(10)
        .minimumNumberOfCalls(5)
        .failureRateThreshold(50)
        .waitDurationInOpenState(Duration.ofMillis(500))
        .permittedNumberOfCallsInHalfOpenState(2)
        .build();

CircuitBreakerRegistry circuitBreakerRegistry = CircuitBreakerRegistry.of(config);
CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("circuitBreaker");

PaymentGateway paymentGateway = mock(PaymentGateway.class);

when(paymentGateway.getStatus(anyString()))
        .thenReturn("SUCCESS", "SUCCESS", "SUCCESS", "SUCCESS", "SUCCESS")
        .thenThrow(
                new RuntimeException("Downstream failure"),
                new RuntimeException("Downstream failure"),
                new RuntimeException("Downstream failure"),
                new RuntimeException("Downstream failure"),
                new RuntimeException("Downstream failure")
        )
        .thenReturn("SUCCESS", "SUCCESS");

// 1) First 5 calls succeed
for (int i = 1; i <= 5; i++) {
    final String txId = "TX-" + i;
    circuitBreaker.executeSupplier(() -> paymentGateway.getStatus(txId));
}
assertThat(circuitBreaker.getState()).isEqualTo(CircuitBreaker.State.CLOSED);

// 2) Next 5 calls fail -> OPEN
for (int i = 6; i <= 10; i++) {
    final String txId = "TX-" + i;
    try {
        circuitBreaker.executeSupplier(() -> paymentGateway.getStatus(txId));
    } catch (Exception ignored) {}
}

assertThat(circuitBreaker.getState()).isEqualTo(CircuitBreaker.State.OPEN);

// 3) Wait duration expires
Thread.sleep(600);

// Trigger HALF_OPEN (first permitted call)
circuitBreaker.executeSupplier(() -> paymentGateway.getStatus("TX-11"));
assertThat(circuitBreaker.getState()).isEqualTo(CircuitBreaker.State.HALF_OPEN);

// 4) Second permitted call -> CLOSED
circuitBreaker.executeSupplier(() -> paymentGateway.getStatus("TX-12"));
assertThat(circuitBreaker.getState()).isEqualTo(CircuitBreaker.State.CLOSED);

verify(paymentGateway, times(12)).getStatus(anyString());

This example clearly demonstrates how the circuit breaker operates. Let’s review it step by step:

The mock is configured to return a successful response for the first five calls, throw exceptions for the next five calls, and return successful responses for the final two calls.
Since the first five calls complete successfully, the circuit breaker remains in the CLOSED state.
The circuit breaker is configured with a minimum number of 5 calls, a sliding window size of 10, and a failure rate threshold of 50%. Because calls #6 through #10 fail, the failure rate exceeds the threshold and the circuit breaker transitions to the OPEN state.
The waitDurationInOpenState is configured as 500 ms, so the test waits slightly longer (600 ms) before making another call.
The first call after the wait duration transitions the circuit breaker from OPEN to HALF_OPEN.
Since permittedNumberOfCallsInHalfOpenState is set to 2, the second successful call transitions the circuit breaker from HALF_OPEN back to CLOSED.

Decorating the Remote Call

Resilience4j allows us to reuse protected remote service calls by creating decorated functions with a circuit breaker.

Function<String, String> decoratedGetStatus =
                CircuitBreaker.decorateFunction(
                        circuitBreaker,
                        paymentGateway::getStatus
                );

// Call the decorated function
decoratedGetStatus.apply("TRID00001");

If the method to be wrapped accepts multiple arguments:

public interface PaymentGateway {
    AuthorizationResult authorize(String token, Integer amount);
}

you can decorate the remote call as shown below:

BiFunction<String, Integer, AuthorizationResult> decoratedAuthorize = (token, amount) -> CircuitBreaker.decorateSupplier(
                circuitBreaker,
                () -> paymentGateway.authorize(token, amount)
        )
        .get();

// Call the decorated function
decoratedAuthorize.apply("7cf267eb-21d8-4802-9703-d4309bd3eddc", 100);

Adding Fallback

So far, we have seen how to cut off communication between the application and a remote service under certain circumstances. When the circuit breaker is in the OPEN state, it throws an exception instead of allowing the remote call to proceed. Handling both remote service exceptions and circuit breaker exceptions at every call site can quickly become inconvenient and error-prone.

Function<String, String> safeDecoratedGetStatus = transactionId -> {
    try {
        return decoratedGetStatus.apply(transactionId); }
    catch (Exception exception) {
        return  "UNKNOWN";
    }
};

Instead, we can provide a fallback response when a failure occurs. This approach allows the application to degrade gracefully by returning a predefined or computed fallback value whenever the remote call fails or the circuit breaker is open.

For cleaner and more expressive handling, you can consider using io.vavr:vavr:

Function<String, String> safeDecoratedGetStatus = transactionId ->
        Try.of(() -> decoratedGetStatus.apply(transactionId))
                .recover(throwable -> "UNKNOWN").get();

Resilience4j offers many useful components in addition to the circuit breaker, and these components can be combined to build more resilient systems. I strongly recommend reviewing the official documentation for more examples and advanced usage: https://resilience4j.readme.io/docs/examples

Spring Cloud Circuit Breaker

Spring Cloud Circuit Breaker is an abstraction layer over multiple circuit breaker libraries, similar to how Spring’s RestClient abstracts HTTP clients.

To start using Spring Cloud Circuit Breaker with Spring Boot, add the following dependency to your pom.xml

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
    <version>5.0.0</version>
</dependency>

Configuring Spring Cloud Circuit Breaker

To define a default configuration that applies to all circuit breakers, you can register a Customizer bean as shown below:

@Bean
public Customizer<Resilience4JCircuitBreakerFactory> circuitBreakerCustomizer(CircuitBreakerConfig defaultCircuitBreakerConfig) {
    return factory -> factory.configureDefault(id ->
            new Resilience4JConfigBuilder(id)
                    .circuitBreakerConfig(defaultCircuitBreakerConfig)
                    .build());
}

@Bean
public CircuitBreakerConfig defaultCircuitBreakerConfig() {
    return CircuitBreakerConfig.custom()
            .slidingWindowSize(10)
            .minimumNumberOfCalls(5)
            .failureRateThreshold(50)
            .waitDurationInOpenState(Duration.ofSeconds(60))
            .build();
}

Alternatively, you can configure circuit breakers declaratively using application configuration:

resilience4j.circuitbreaker:
  configs:
    default:
      slidingWindowSize: 10
      minimumNumberOfCalls: 5
      failureRateThreshold: 50
      waitDurationInOpenState: 60s
  instances:
    OrderService:
      baseConfig: default

Protecting Services With Circuit Breaker

You can protect service calls by using a CircuitBreakerFactory, which is injected into your service class.

@Service
public class OrderService {
    private final CircuitBreakerFactory<?, ?> circuitBreakerFactory;

    public OrderService(CircuitBreakerFactory<?, ?> circuitBreakerFactory) {
        this.circuitBreakerFactory = circuitBreakerFactory;
    }

    public OrderStatus getOrderStatus(String orderId) {
        return circuitBreakerFactory.create("OrderService")
                .run(
                        () -> callGetStatusApi(orderId),
                        throwable -> fallbackGetStatus(orderId, throwable)
                );
    }

    private OrderStatus callGetStatusApi(String orderId) {
        // TODO: Call the api
        return new OrderStatus();
    }

    private OrderStatus fallbackGetStatus(String orderId, Throwable throwable) {
        // TODO: Return fallback result and log the failure
        return new OrderStatus();
    }
}

In this example, the circuit breaker named OrderService monitors calls to the downstream service. When the breaker is OPEN, calls are short-circuited and the fallback method is executed instead.

The spring-cloud-starter-circuitbreaker integrates multiple Resilience4j resilience patterns, including CircuitBreaker, Retry, and TimeLimiter under the Spring Cloud Circuit Breaker abstraction. This allows applications to address additional edge cases such as retries for transient failures and timeouts for slow responses using a single starter dependency and consistent configuration model.

For more advanced use cases and configuration options, refer to the official documentation linked in the Credits section.

Hope you find it helpful. As always, you can find code example in the following repository.

Circuit Breaker Code Examples

Thanks for reading!

Credits:

Message Schema Evolution in RabbitMQ: Using Virtual Hosts as Deployment Boundaries

İbrahim Gündüz — Tue, 06 Jan 2026 20:52:21 +0000

This article is a continuation of a previous post in which we focused on deployment safety through cache key versioning. If you haven’t read it yet, we recommend starting there:

Versioning Redis Cache Keys to Prevent Stale Data During Spring Boot Application Deployments

Message schema evolution is another critical factor that can threaten deployment safety if it is not handled correctly. Changes to message structures, such as adding, removing, or renaming fields, can easily lead to incompatibilities between producers and consumers during rolling deployments. Without clear deployment boundaries, these incompatibilities may cause message processing failures, data loss, or subtle runtime bugs that are difficult to detect.

Let’s look at the following example to better understand the risks involved.

Example Case:

v1: Delayed Capture After Authorization

The backend performs the authorization synchronously during the checkout flow and immediately informs the user of the result.
After a successful authorization, the backend publishes an event indicating that the payment has been authorized. (PaymentAuthorized)

{
  "paymentId": "p-123",
  "authorizedAmount": 100.00,
  "currency": "EUR"
}

The consumer processes this event and performs a full capture of the authorized amount.

capture(authorizedAmount)

v2: Partial capture based on stock availability

As the system evolves, some products may be out of stock at fulfillment time.

The backend still performs the authorization synchronously and returns the result to the user.
Before capturing the payment, the system checks stock availability via the inventory service.
The backend now publishes an event that includes the actual amount to be captured, which may be lower than the authorized amount. (PaymentCaptureRequested)

{
  "paymentId": "p-123",
  "authorizedAmount": 100.00,
  "captureAmount": 80.00,
  "currency": "EUR"
}

The consumer captures only the specified amount.

capture(captureAmount)

What Really Happens During a Rolling Deployment?

Scenario 1: v2 consumer processing v1 messages

Because the message does not contain captureAmount field, the consumer may fail to process the message.

Result: Capture fails or the consumer behaves unpredictably

Scenario 2: v1 consumer processing v2 messages

The v1 consumer does not recognize the captureAmount field or may ignore it entirely.
Since authorizedAmount is an expected field, the v1 consumer proceeds to capture the full authorized amount.

Result: The customer is charged more than the value of the fulfilled items.

The root cause of these failures is not incorrect business logic, but the fact that multiple, incompatible versions of producers and consumers are allowed to process the same messages during a deployment. To prevent this, RabbitMQ virtual hosts can be used to ensure that only compatible versions are able to communicate with each other.

Using RabbitMQ Virtual Hosts as Deployment Boundaries

To achieve clean isolation and a risk-free cutover, the following steps can be applied to your applications and deployment pipeline.

1. Externalize RabbitMQ Configuration

Update both producer and consumer applications to inject the RabbitMQ virtual host and credentials via external configuration.

spring.rabbitmq.virtualHost=${RABBITMQ_VHOST}
spring.rabbitmq.username=${RABBITMQ_USER}
spring.rabbitmq.password=${RABBITMQ_PASSWORD}

2. Provision Version-Scoped RabbitMQ Resources

Add a step to your deployment pipeline that provisions a version-scoped RabbitMQ virtual host, user, and permissions before deploying the application.

$ rabbitmqctl add_vhost payments-v1.0
$ rabbitmqctl add_user payments-v1.0-app YourStrongPassword
$ rabbitmqctl set_user_tags payments-v1.0-app
$ rabbitmqctl set_permissions -p payments-v1.0 \
  payments-v1.0-app \
  ".*" ".*" ".*"

3. Inject Configuration via Environment Variables

Provide the required configuration values through the application environment.

...
  environment:
    RABBITMQ_VHOST: ${RABBITMQ_VHOST}
    RABBITMQ_USER: ${RABBITMQ_USER}
    RABBITMQ_PASSWORD: ${RABBITMQ_PASSWORD}
...
  command: java -jar ...

4. Deploy and Verify

Deploy the new version of the application.
Perform health checks to ensure all nodes are running correctly.
Verify that messages from the previous version have been fully consumed.

5. Clean Up Old Resources

Once the deployment is complete and the previous version is no longer needed:

Remove the old virtual host.
Delete the associated user.

This ensures the broker remains clean and prevents obsolete deployment boundaries from accumulating over time.

Credits:

Spring AMQP RabbitAutoConfiguration Reference Doc
Spring AMQP Reference Doc
Cover Photo by Ivan N on Unsplash

Versioning Redis Cache Keys to Prevent Stale Data During Spring Boot Application Deployments

İbrahim Gündüz — Fri, 02 Jan 2026 21:56:36 +0000

Applications often generate content that needs to be consumed later at runtime. This content may be stored in the file system, written to a database table, shared through a message broker, or placed in a shared cache. Since software systems evolve over time, the consumers of previously generated content are expected to handle these changes. However, this is not always possible.

Let's take a real world example:

Example: Structure Changes On Cached Objects

The class shown below retrieves data for a specific user from the users table, constructs a UserProfile object, and caches the result in Redis.

@Service
public class UserProfileService {
    private final UserRepository userRepository;

    public UserProfileService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Cacheable("userProfile")
    public UserProfile getProfile(Long userId) {
        User user = userRepository.findById(userId).orElseThrow();
        return new UserProfile(
                user.getId(),
                user.getFirstName(),
                user.getLastName()
        );
    }
}

At a later point, we decided to extend the UserProfile object by adding an email field and populating it from the database.

         return new UserProfile(
                 user.getId(),
                 user.getFirstName(),
-                user.getLastName()
+                user.getLastName(),
+                user.getEmail()
         );
     }
 }

Because Spring had already populated the cache with instances of the previous object structure, subsequent calls to the getProfile() method would fail due to a deserialization error when reading the outdated cached values.

org.springframework.data.redis.serializer.SerializationException: Cannot serialize

Or something similar depending on your serializer configuration.

How To Solve

Although both the problem and its solution are conceptually simple, the impact can be severe in production environments. Such errors may cause extended downtime, failed deployments, or forced rollbacks — especially when cache entries have long TTL values.

To enable safe deployments and rollbacks, cache entries must be versioned. A common and effective approach is to include a version identifier—optionally combined with the application name when using a shared cache—in the cache key. This ensures that newer application versions do not attempt to read incompatible cached data created by older versions.

@Configuration
public class CacheConfiguration {
    @Bean
    public RedisCacheConfiguration redisCacheConfiguration(ObjectProvider<BuildProperties> buildPropertiesProvider) {
        BuildProperties buildProperties = buildPropertiesProvider.getIfAvailable();

        String name = buildProperties != null ? buildProperties.getName() : "application";
        String version = buildProperties != null ? buildProperties.getVersion() : "dev";

        return RedisCacheConfiguration.defaultCacheConfig()
                .prefixCacheNameWith(String.format("%s:%s:", name, version));
    }
}

The cache key can be constructed using build information from Maven (via Maven resource filtering or the spring-boot-maven-plugin with the build-info goal), a Git commit hash (for example, using the git-commit-id-plugin), or any other metadata injected by the CI/CD pipeline.

When Redis is configured with a global key prefix as shown above, cached entries are stored with versioned keys, for example:

127.0.0.1:6379> keys *
1) "payment-gateway:1.1.0:userProfile::1"
2) "payment-gateway:1.1.1:userProfile::1"

Because each application instance accesses only cache keys matching its own version, deployments and rollbacks can be performed safely without encountering deserialization errors caused by incompatible cached data.

Hope you find it helpful. As always, you can find code example in the following repository.

Cache Key Versioning Code Example

Thanks for reading!

Credits

Protecting Sensitive Data Using Envelope Encryption

İbrahim Gündüz — Tue, 30 Dec 2025 13:39:02 +0000

Envelope encryption is a technique that uses two layers of encryption to protect sensitive data. The first layer encrypts the data using a symmetric encryption algorithm with a randomly generated Data Encryption Key (DEK), which secures the actual plaintext. The second layer then encrypts, or wraps, the DEK using a Key Encryption Key (KEK). The KEK is typically a long-lived key stored and protected inside a KMS or HSM, and it may be either symmetric or asymmetric depending on the system. This two-tiered approach ensures the security of both the DEK and the encrypted data. Envelope encryption is widely used as part of centralized key management systems (KMS) provided by major cloud platforms.

In this article, we will explore how this technique works through a simple example implementation.

What Are The Benefits Of Envelope Encryption?

Stronger security: Security is the primary benefit of this technique. In most production environments, the Key Encryption Key (KEK) is stored and protected inside a KMS backed by HSMs, ensuring that it never leaves the secure hardware boundary. Because the KEK is required to unwrap the Data Encryption Key (DEK), an attacker cannot decrypt the ciphertext even if they obtain the encrypted data—the DEK itself cannot be recovered without the KEK.
Simplified key management: Simplified key management is another major advantage. Envelope encryption allows an organization to manage many Data Encryption Keys (DEKs) under one or more Key Encryption Keys (KEKs), greatly reducing operational complexity. KEKs can be rotated without re-encrypting all the data, since existing encrypted DEKs continue to work with older KEK versions. This makes large-scale key rotation feasible and minimizes impact on the underlying data storage.

Encryption Flow

Now that we’ve covered the fundamentals of envelope encryption, let’s walk through a simple implementation to demonstrate how to encrypt sensitive data — such as a credit card number—using this technique.

// Fake card number
String plainText = "5105105105105100";

The first step is to generate a random key (the Data Encryption Key, or DEK), which will be used to encrypt the plaintext using a symmetric algorithm such as AES-GCM.

private static final String KEY_ALGORITHM = "AES";
private static final int AES_KEY_LENGTH = 256;

//...
KeyGenerator keyGenerator = KeyGenerator.getInstance(KEY_ALGORITHM);
keyGenerator.init(AES_KEY_LENGTH);
SecretKey dataEncryptionKey = keyGenerator.generateKey();

Next, encrypt the input data using the AES-GCM algorithm with the generated DEK.

//...
private static final String ENC_ALGORITHM = "AES/GCM/NoPadding";
//...

byte[] bPlainText = plainText.getBytes(StandardCharsets.UTF_8);
Cipher cipher = Cipher.getInstance(ENC_ALGORITHM);
cipher.init(Cipher.ENCRYPT_MODE, dataEncryptionKey);

byte[] iv = cipher.getIV();
byte[] cipherText = cipher.doFinal(bPlainText);

To safely store the IV and the ciphertext, encode them using Base64:

String encodedIv = Base64.getEncoder().encodeToString(iv);
String encodedCipherText = Base64.getEncoder().encodeToString(cipherText);

Now we have the encrypted data and the IV used during encryption. Here is what the output looks like:

Base64 Encoded IV: g4xPa5FCgkw+KzmT
Base64 Encoded Cipher: fWegEZo4dlmm1YHvAe+njcZrcz10r5W9ntEEpQK5OgA=

Wrapping the Data Encryption Key (DEK)

Up to this point, we’ve covered the first layer of envelope encryption, which encrypts the input data. Now we’re ready for the second layer—wrapping the Data Encryption Key itself.

In production, KEKs are generated and stored inside KMS services backed by HSMs. Since the KEK never leaves secure hardware, the application cannot directly access it.

For illustration, we’ll use a simplified in-memory KMS shown below for the example implementation.

package com.example;

import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.KeyGenerator;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.SecretKey;
import java.security.GeneralSecurityException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;

public class InMemoryKMS {
    private static final String KEY_ALGORITHM = "AES";
    private static final int AES_KEY_LENGTH = 256;
    private static final String WRAP_TRANSFORMATION = "AESWrap";
    private final Map<String, List<SecretKey>> keyStore = new HashMap<>();

    public String createKEK() {
        SecretKey key = generateKey();
        String keyId = UUID.randomUUID().toString();
        keyStore.computeIfAbsent(keyId, k -> new ArrayList<>()).add(key);
        return keyId;
    }

    public void rotateKEK(String keyId) {
        List<SecretKey> versions = keyStore.get(keyId);
        if (versions == null) {
            throw new IllegalArgumentException("Unknown keyId: " + keyId);
        }

        SecretKey newKek = generateKey();
        versions.add(newKek);
    }

    public byte[] wrapDEK(String keyId, SecretKey dataEncryptionKey) {
        try {
            SecretKey activeKek = getLatestKey(keyId);
            Cipher cipher = Cipher.getInstance(WRAP_TRANSFORMATION);
            cipher.init(Cipher.WRAP_MODE, activeKek);

            return cipher.wrap(dataEncryptionKey);
        } catch (NoSuchPaddingException | IllegalBlockSizeException | NoSuchAlgorithmException |
                 InvalidKeyException e) {
            throw new RuntimeException(e);
        }
    }

    public SecretKey unwrapDEK(String keyId, byte[] wrappedDataEncryptionKey) {
        try {
            List<SecretKey> versions = keyStore.get(keyId);
            if (versions == null) {
                throw new IllegalArgumentException("Unknown keyId: " + keyId);
            }

            // Try each KEK version (newest first), just like cloud KMS
            for (int i = versions.size() - 1; i >= 0; i--) {
                SecretKey kek = versions.get(i);

                try {
                    Cipher cipher = Cipher.getInstance(WRAP_TRANSFORMATION);
                    cipher.init(Cipher.UNWRAP_MODE, kek);

                    return (SecretKey) cipher.unwrap(wrappedDataEncryptionKey, KEY_ALGORITHM, Cipher.SECRET_KEY);

                } catch (GeneralSecurityException ignored) {
                    // Try next version
                }
            }

            throw new IllegalStateException("Unable to unwrap DEK with any KEK version");
        } catch (Exception e) {
            throw new IllegalStateException("Failed to unwrap DEK", e);
        }
    }

    private SecretKey generateKey() {
        try {
            KeyGenerator generator = KeyGenerator.getInstance(KEY_ALGORITHM);
            generator.init(AES_KEY_LENGTH);
            return generator.generateKey();
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException(e);
        }
    }

    private SecretKey getLatestKey(String keyId) {
        List<SecretKey> versions = keyStore.get(keyId);
        if (versions == null || versions.isEmpty()) {
            throw new IllegalArgumentException("Unknown keyId: " + keyId);
        }
        return versions.getLast();
    }
}

Now we are ready to wrap the Data Encryption Key previously generated using our in memory KMS.

InMemoryKMS kms = new InMemoryKMS();
String keyId = kms.createKEK();

byte[] wrappedDEK = kms.wrapDEK(keyId, dataEncryptionKey);

To store the wrapped DEK later safely, encode it with Base64.

String encodedWrappedDEK = Base64.getEncoder().encodeToString(wrappedDEK);

As we completed the encryption process, we should have the following output which we can safely transfer or store, and use for description later.

Base64 Encoded IV: +W1d4YVNBBJFDuaB
Base64 Encoded Cipher: Wib4Hx96rSBn7dTXrrdKEb3BTxbUdDm7PPCxybc20/I=
KEK ID: eeeb0c35-b166-4680-a800-3a28641fb03c
Base64 Encoded WrappedDEK: dzQCY+x+JsDdHpscjf1qiWgm2utGEwNFIBIX6QiWqW/mjIRP42jFgw==

Decryption Flow

During encryption, we stored the randomly generated initialization vector (IV), the ciphertext, the wrapped Data Encryption Key (DEK), and the identifier of the Key Encryption Key (KEK) managed by the in-memory KMS. Because the KEK never leaves the KMS, the application cannot directly decrypt the DEK or the ciphertext on its own. To recover the original data, we must first ask the KMS to unwrap the DEK.

byte[] wrappedDek = Base64.getDecoder().decode(encodedWrappedDEK);
SecretKey dataEncryptionKey = kms.unwrapDEK(kekId, wrappedDek);

At this point, we have reconstructed the original DEK. Keep in mind that the DEK should never be stored or persisted after it is unwrapped; it should exist only in memory for as short a time as possible.

We can decrypt the ciphertext using the unwrapped DEK.

byte[] iv = Base64.getDecoder().decode(encodedIv);
byte[] cipherText = Base64.getDecoder().decode(encodedCipherText);

Cipher cipher = Cipher.getInstance(ENC_ALGORITHM);

GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(GCM_TAG_LENGTH, iv);
cipher.init(Cipher.DECRYPT_MODE, dataEncryptionKey, gcmParameterSpec);
byte[] decrypted = cipher.doFinal(cipherText);

String decryptedText = new String(decrypted, StandardCharsets.UTF_8);

System.out.println("Decrypted Text: " + decryptedText);

And finally, we can see the original data as shown below:

Decrypted Text: 5105105105105100

A Note on Key Rotation:

Since key rotation is a broader topic within KMS systems, we won’t cover it in depth in this article. However, briefly put: when the KMS rotates a key, it creates a new KEK version and designates it as the active key for future wrapping operations. Older KEK versions remain available for unwrapping, ensuring that previously wrapped DEKs can still be decrypted. This design allows key rotation without requiring re-encryption of existing data.

Final Thoughts:

Envelope encryption provides a strong and scalable way to protect sensitive data while simplifying key management. It is the foundation of most modern cloud KMS systems.

As always, you can find complete code example in the following repository.

Envelope Encryption Code Example

Thanks for reading!

Credits

AES/GCM encryption in java
Envelope encryption
Hybrid cryptosystem
Cover Photo by Mauro Sbicego on Unsplash
Special thanks to Alexandru Pătrănescu

A Practical Guide to Google Guice

İbrahim Gündüz — Sun, 28 Dec 2025 18:10:32 +0000

Google Guice is a lightweight dependency injection (DI) framework that simplifies development by letting you manage object creation without pulling in large, unnecessary framework dependencies.

The framework focuses on object creation and wiring, but it can do much more through its extensions—such as servlet integration (guice-servlet), JPA persistence support (guice-persist or guice-persist-jpa), and even Spring integration (guice-spring).

In this article, we'll focus on the core features of the framework that enable us to accomplish common development tasks.

Setup

To start using Google Guice, add the following Maven dependency to your project

<dependency>
    <groupId>com.google.inject</groupId>
    <artifactId>guice</artifactId>
    <version>7.0.0</version>
</dependency>

Constructor Injection

Google Guice allows you to inject dependencies using constructors or setter methods without changing your implementation logic. You can inject a dependency simply by adding the @Inject annotation to the class constructor and defining the appropriate bindings in your module class.

Let's take a look at the following example:

package com.example;

import com.google.inject.Inject;
import java.math.BigDecimal;

public class CardPaymentProcessor implements PaymentProcessor {
    private final CardVault cardVault;
    private final PaymentProvider paymentProvider;
    private final TransactionStorage transactionStorage;

    @Inject
    public CardPaymentProcessor(CardVault cardVault, PaymentProvider paymentProvider, TransactionStorage transactionStorage) {
        this.cardVault = cardVault;
        this.paymentProvider = paymentProvider;
        this.transactionStorage = transactionStorage;
    }

    public PaymentReceipt processPayment(String cardToken, BigDecimal paymentAmount) {
        try {
            CardData cardData = cardVault.getCardData(cardToken);
            PaymentResult paymentResult = paymentProvider.charge(cardData, paymentAmount);
            transactionStorage.savePaymentResult(paymentResult);

            return paymentResult.isSuccessful() ?
                    PaymentReceipt.forSuccess(paymentResult, paymentAmount) :
                    PaymentReceipt.forFailure(paymentResult, paymentAmount);
        } catch (PaymentProcessingException exception) {
            return PaymentReceipt.forException(exception, paymentAmount);
        }
    }
}

As you can see in the example above, the CardPaymentProcessor class depends on several other components through their interfaces. Since Google Guice resolves dependencies based on interface bindings, it provides greater flexibility and makes it easy to replace these implementations with mocks during testing—just like other modern dependency injection frameworks.

As a next step, we need to define the bindings as shown below:

package com.example;

import com.google.inject.AbstractModule;

public class MainModule extends AbstractModule {
    @Override
    protected void configure() {
        bind(PaymentProvider.class).to(HsbcPaymentProvider.class);
        bind(TransactionStorage.class).to(DatabaseTransactionStorage.class);
        bind(CardVault.class).to(ExternalCardVault.class);
        bind(PaymentProcessor.class).to(CardPaymentProcessor.class);
    }
}

And finally, we can get an instance of PaymentProcessor implementation as shown below

public static void main(String[] args) {
    Injector injector = Guice.createInjector(new MainModule());

    PaymentProcessor paymentProcessor = injector.getInstance(PaymentProcessor.class);

    // ...
}

Setter Injection

You can inject a dependency by creating a setter method annotated with @Inject.

Continuing with the same example from above:

public class CardPaymentProcessor implements PaymentProcessor {
  // ...
  private PaymentProvider paymentProvider;
  // ...

  @Inject
  public void setPaymentProvider(PaymentProvider paymentProvider) {
    this.paymentProvider = paymentProvider;
  }
}

Because Guice injects the paymentProvider dependency after the object is instantiated, the PaymentProvider field cannot be declared as final.

You can create the module class in the same way as shown in the Constructor Injection section.

Service Factory

Factories are used for objects that require a special creation process. Guice provides a similar mechanism called Provider to help you create and inject such objects while still maintaining clean dependency management.

Providers can either be separate classes that implement Guice’s Provider interface or methods annotated with @Provides that create and return the desired object.

Let's start by creating the provider class.

package com.example;

import com.google.inject.Provider;

import java.net.http.HttpClient;
import java.time.Duration;

public class HttpClientProvider implements Provider<HttpClient> {
    private final static int CONNECTION_TIMEOUT_IN_MS = 10_000;
    @Override
    public HttpClient get() {
        return HttpClient.newBuilder()
                .connectTimeout(Duration.ofMillis(CONNECTION_TIMEOUT_IN_MS))
                .followRedirects(HttpClient.Redirect.ALWAYS)
                .build();
    }
}

As you can see, it's a well-known factory class. In order tell Guice how to create this dependency, we need to define a binding as shown below.

@Override
protected void configure() {
    bind(HttpClient.class)
        .toProvider(HttpClientProvider.class)
        .in(Scopes.SINGLETON);
}

And you can inject it either through constructor or setter methods.

package com.example;

import com.google.inject.Inject;

import java.net.http.HttpClient;

public class LoggingService {
    private final HttpClient httpClient;

    @Inject
    public LoggingService(HttpClient httpClient) {
        this.httpClient = httpClient;
    }

    public void info(String message) {
        // ...
    }
}

You can access the LogginService instance in the same way as shown the examples above. But I want to touch on something here:

public static void main(String[] args) {
        Injector injector = Guice.createInjector(new MainModule());
        LoggingService loggingService = injector.getInstance(LoggingService.class);
        loggingService.info("Test message");
    }

Normally, we don’t create interfaces for every single class. For example, I didn’t create an interface for LoggingService. When we request an instance of a concrete class by its type, Guice can construct it automatically, without requiring any additional bindings to determine which implementation to use.

Another topic worth mentioning is the use of scopes. In our example, we defined a binding with a specific scope using .in(Scopes.SINGLETON). This is necessary because Guice creates a new instance of a dependency every time it is requested when no scope is specified. In other words, bindings are in prototype (no-scope) mode by default.

Working In Multi-Module Projects

As your project grows, maintaining all bindings in a single module can become difficult. Guice supports working with multiple modules, allowing you to organize your bindings across separate module classes.

public static void main(String[] args) {
    Injector injector = Guice.createInjector(
            new PaymentModule(),
            new BillingModule()
    );

    BillingService billingService = injector.getInstance(BillingService.class);
    billingService.charge("afafc9a3-346a-4dce-9909-ca65dc45fadc", BigDecimal.valueOf(100));
}

The order in which modules are provided does not matter. Guice merges all bindings into a single injector regardless of the order.

Named Bindings

Sometimes, we may need multiple instances of the same class with different configurations. To tell Guice which version of the class should be injected, we can assign names to the bindings. Guice allows us to create distinct versions of a binding using named bindings

You can define bindings with a name as shown below:

package com.example;

import com.google.inject.AbstractModule;
import com.google.inject.name.Names;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MainModule extends AbstractModule {
    @Override
    protected void configure() {
        bind(Logger.class)
                .annotatedWith(Names.named("appLogger"))
                .toInstance(LoggerFactory.getLogger("application"));

        bind(Logger.class)
                .annotatedWith(Names.named("auditLogger"))
                .toInstance(LoggerFactory.getLogger("audit"));
    }
}

And you can inject the desired instance by annotating the parameter with @Named annotation.

public class HsbcPaymentProvider implements PaymentProvider {
    private final Logger logger;

    @Inject
    public HsbcPaymentProvider(@Named("appLogger") Logger logger) {
        this.logger = logger;
    }
    // ...
}

Loading Configurations From `.properties` Files

Guice enables you to bind and use configuration values stored in a .properties file, as shown below.

First, create an application.properties file under the resources/ directory:

datasource.url=jdbc:mysql://localhost:3306/app-database-dev
datasource.user=appuser
datasource.password=password

Next, create a module that loads and binds these properties:

package com.example;

import com.google.inject.AbstractModule;
import com.google.inject.name.Names;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class ConfigurationModule extends AbstractModule {
    private static final String CONFIG_FILE = "application.properties";

    @Override
    protected void configure() {
        ClassLoader classLoader = getClass().getClassLoader();
        InputStream configFileStream = classLoader.getResourceAsStream(CONFIG_FILE);

        if (configFileStream == null) {
            throw new RuntimeException("Could not find " + CONFIG_FILE + " on the classpath");
        }

        try {
            Properties properties = new Properties();
            properties.load(configFileStream);
            Names.bindProperties(binder(), properties);
        } catch (IOException e) {
            throw new RuntimeException("Failed to load properties from " + CONFIG_FILE, e);
        }
    }
}

Now you can inject configuration values into your classes using the @Named annotation:

// ...
public class DatabaseTransactionStorage implements TransactionStorage {
    private final String datasourceUrl;
    private final String dbUser;
    private final String dbPassword;

    @Inject
    public DatabaseTransactionStorage(
            @Named("datasource.url") String datasourceUrl,
            @Named("datasource.username") String dbUser,
            @Named("datasource.password") String dbPassword) {
        this.datasourceUrl = datasourceUrl;
        this.dbUser = dbUser;
        this.dbPassword = dbPassword;
    }

    // ...
}

You can also retrieve configuration values directly from the DI container:

public static void main(String[] args) {
    Injector injector = Guice.createInjector(new ConfigurationModule());
    String datasourceUrl = injector.getInstance(Key.get(String.class, Names.named("datasource.url")));
    System.out.println(datasourceUrl);
}

Hope you enjoyed reading. As always, you can find the complete example in the following GitHub repository:

Google Guice Code Example

Thanks!

Credits:

How to Align Spring Boot Validation Errors with Your JSON Property Naming Strategy

İbrahim Gündüz — Tue, 25 Nov 2025 21:00:18 +0000

Problem

Our API uses a snake_case naming strategy for DTO deserialization and serialization. However, when validation fails, the error messages still use the original object property names, ignoring the configured naming strategy, which leads to inconsistent API responses.

Solution

This issue occurs because bean validation happens after the incoming request has been deserialized into the DTO, but before the response is serialized. As a result, validation errors report the Java field names rather than the JSON property names defined by the configured naming strategy.

First, make sure that the property naming strategy is configured as shown below:

# application.properties

spring.jackson.property-naming-strategy=SNAKE_CASE

Override the default error generation with creating a custom error handler.

@RestControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<?> handleMethodArgumentNotValidException(MethodArgumentNotValidException exception) {
       // TODO: To be implemented
    }
}

To access the mapped field names, inject an ObjectMapper and resolve the JSON property names by iterating over the list of field errors.

private final ObjectMapper objectMapper;

//...

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<?> handleMethodArgumentNotValidException(MethodArgumentNotValidException exception) {
  List<String> errors = exception.getBindingResult()
          .getFieldErrors()
          .stream()
          .map(this::formatErrorMessage)
          .toList();

  return ResponseEntity.badRequest().body(Map.of("errors", errors));
}

private String formatErrorMessage(FieldError fieldError) {
  PropertyNamingStrategy mapping = objectMapper.getPropertyNamingStrategy();
  String mappedFieldName = mapping.nameForField(null, null, fieldError.getField());

  return String.format("%s.%s: %s", fieldError.getObjectName(), mappedFieldName, fieldError.getDefaultMessage());
}

Let’s test it!

$ curl -XPOST "http://api.yourdomain.com/v1/merchants" \
-H "Content-Type: application/json" \
-d "{}"

{
  "errors" : [ 
    "merchantCreateRequest.partner_id: must not be null", 
    "merchantCreateRequest.merchant_name: must not be null" 
  ]
}%

You can find all code examples in the following repository:
https://github.com/ibrahimgunduz34/blog-code-examples/tree/master/spring-boot-validation-error

Thanks for reading!

How to Configure Global Settings for Spring RestClient

İbrahim Gündüz — Thu, 30 Oct 2025 07:16:34 +0000

RestClient is an HTTP client that offers a modern API built on top of underlying HTTP client libraries such as the native HTTP client from JDK 11 and Apache HttpComponents. As the existing RestTemplate client is planned for deprecation, RestClient can be considered its modern replacement. (See more details: The state of HTTP clients in Spring)

In this article, we'll see how to configure the client for some common use cases.

Creating Client Bean with Common Parameters:

In some cases, we may need a client instance configured for a specific API, and in such cases, we don’t want to send common request parameters with every single request. In the following example, the client bean is configured with a base URL and a default header that will be included in every request. It sends a dynamic variable in the URL also.

@Bean
public RestClient restClient() {
    return RestClient.builder()
            .baseUrl("https://example.com/{vendor}")
            .defaultUriVariables(Map.of("vendor", "MyVendor"))
            .defaultHeaders(headers -> {
                headers.add("X-Platform", "Company");
            })
            .build();
}

Exception Handling

By default, RestClient throws a subclass of RestClientException when retrieving a response with HTTP/4xx or HTTP/5xx status code. You can override the behavior as shown below.

You can log the error, and throw a custom exception for any HTTP errors using HttpStatusCode::isError, or for server-side errors using HttpStatusCode::is5xxServerError, as shown below. :

@Bean
public RestClient restClient() {
    return RestClient.builder()
            .defaultStatusHandler(HttpStatusCode::is5xxServerError, ((request, response) -> {
                logger.error(
                        "Api request was failed. Response status: {}, body: {}",
                        response.getStatusCode(),
                        new String(response.getBody().readAllBytes())
                );

                throw new ApiError("Something went wrong");
            }))
            .build();
}

Or you can simply make the client silent in case any HTTP errors occur.

@Bean
public RestClient restClient() {
    return RestClient.builder()
            .defaultStatusHandler((response) -> true)
            .build();
}

Setting Up Client Connection and Read Timeouts

If you're a Spring Boot user, you can simply configure the client using properties or configuration beans.

In order to configure the timeouts, you can use the following properties

spring.http.client.connect-timeout=30s
spring.http.client.read-timeout=5s

Or you can define a bean in your configuration classes as shown below:

@Bean
public RestClient restClient(RestClient.Builder builder) {
    ClientHttpRequestFactorySettings settings = ClientHttpRequestFactorySettings
            .defaults()
            .withConnectTimeout(Duration.ofMillis(30000))
            .withReadTimeout(Duration.ofMillis(5000));

    ClientHttpRequestFactory requestFactory = ClientHttpRequestFactoryBuilder.detect().build(settings);

    return builder.requestFactory(requestFactory)
            .build();
}

If you're not using Spring Boot...

Because RestClient executes HTTP calls through underlying HTTP client libraries, you can setup connection and read timeouts using ClientHttpRequestFactory implementations provided by Spring Framework.

Spring Framework provides the following ClientHttpRequestFactory implementations:

SimpleClientHttpRequestFactory as a simple default
JdkClientHttpRequestFactory for Java’s HttpClient (JDK11+)
HttpComponentsClientHttpRequestFactory for use with Apache HTTP Components HttpClient
JettyClientHttpRequestFactory for Jetty’s HttpClient
ReactorNettyClientRequestFactory for Reactor Netty’s HttpClient

If you haven’t specified a request factory while building the RestClient bean, it will use the Apache or Jetty HttpClient if they are available on the classpath. Otherwise, if the java.net.http module is loaded, it will use Java’s HttpClient. Finally, it will fall back to the simple default implementation.

You can change the client connection and read timeouts for the default as shown below:

@Bean
public RestClient restClient() {
    SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
    requestFactory.setConnectTimeout(Duration.ofMillis(30000));
    requestFactory.setReadTimeout(Duration.ofMillis(5000));

    return RestClient.builder()
            .requestFactory(requestFactory)
            .build();
}

Because SimpleClientHttpRequestFactory executes HTTP calls using java.net.HttpURLConnection, you may prefer to use JdkClientHttpRequestFactory or another implementation due to protocol- or performance-related limitations. You can setup the timeouts as shown below in such cases:

@Bean
public RestClient restClient() {
    HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofMillis(30000))
            .build();

    JdkClientHttpRequestFactory requestFactory = new JdkClientHttpRequestFactory(client);
    requestFactory.setReadTimeout(Duration.ofMillis(5000));

    return RestClient.builder()
            .requestFactory(requestFactory)
            .build();
}

Changing Underlying HTTP Client Library

If you're a Spring Boot user and the auto-detected HTTP client does not meet your needs, you can simply change it through spring.http.client.factory property.

# available options: http-components, jetty, reactor, jdk, and simple.
spring.http.client.factory=jdk

Or you can create a bean like shown below in your configuration class for more complex customizations

@Bean
public RestClient restClient(RestClient.Builder builder) {
    ClientHttpRequestFactorySettings settings = ClientHttpRequestFactorySettings
            .defaults()
            .withConnectTimeout(Duration.ofMillis(30000))
            .withReadTimeout(Duration.ofMillis(5000));

    ClientHttpRequestFactory requestFactory = ClientHttpRequestFactoryBuilder
            .jdk()
            .build(settings);

    return builder.requestFactory(requestFactory)
            .defaultStatusHandler((response) -> true)
            .build();
}

Client Request/Response Logging

While you can log request and response transactions by changing log level of the underlying HTTP client package, you can create a ClientHttpRequestInterceptor implementation as shown below.

@Component
public class RequestLoggerInterceptor implements ClientHttpRequestInterceptor {
    private static final Logger logger = LoggerFactory.getLogger(RequestLoggerInterceptor.class);

    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException {
        logRequest(request, body);
        ClientHttpResponse response = execution.execute(request, body);
        logResponse(request, response);
        return response;
    }

    private void logRequest(HttpRequest request, byte[] body) {
        logger.info("Request: {} {}", request.getMethod(), request.getURI());
        if (body != null && body.length > 0) {
            logger.info("Request body: {}", new String(body, StandardCharsets.UTF_8));
        }
    }

    private void logResponse(HttpRequest request, ClientHttpResponse response) throws IOException {
        logger.info("Response status: {}", response.getStatusCode());
        byte[] responseBody = response.getBody().readAllBytes();
        if (responseBody.length > 0) {
            logger.info("Response body: {}", new String(responseBody, StandardCharsets.UTF_8));
        }
    }
}

And register the interceptor to the client while building the RestClient bean.

@Bean
public RestClient restClient1(RestClient.Builder builder, RequestLoggerInterceptor loggerInterceptor) {
    return builder
            .requestInterceptor(loggerInterceptor)
            .build();
}

Although the client throws an exception when it receives a response with an HTTP 4xx or 5xx status code, it will still execute the interceptor and continue logging.

2025-10-30T09:11:28.932+02:00  INFO 101069 --- [           main] org.example.RequestLoggerInterceptor     : Request: GET http://localhost:8080/
2025-10-30T09:11:28.971+02:00  INFO 101069 --- [           main] org.example.RequestLoggerInterceptor     : Response status: 400 BAD_REQUEST
2025-10-30T09:11:28.971+02:00  INFO 101069 --- [           main] org.example.RequestLoggerInterceptor     : Response body: Invalid request
Exception in thread "main" org.springframework.web.client.HttpClientErrorException$BadRequest: 400 Bad Request: [no body]
    at org.springframework.web.client.HttpClientErrorException.create(HttpClientErrorException.java:103)
    at org.springframework.web.client.StatusHandler.lambda$defaultHandler$3(StatusHandler.java:86)
    at org.springframework.web.client.StatusHandler.handle(StatusHandler.java:146)
...

Thanks for reading!

Credits:

Generics as a Design Tool, Not Just a Language Feature

İbrahim Gündüz — Sun, 19 Oct 2025 17:29:09 +0000

Programming languages offer many useful features that make our lives easier. Some of them may seem like tools for better code organization, but it’s worth remembering that they can also shape the way we design software — like generics in Java.

Since you’re reading this article online, you can easily find many Java resources explaining generics. Here, however, we’ll focus on how to use this feature as a practical design tool through real-world use cases.

Let's get started!

Example:

I tried to find a really bad example that you can see almost every day in a legacy project. :)

We have a platform that allows our clients to pay using credit cards or stored card tokens. Each payment method is handled by a different payment provider.

public class CardPaymentStrategyImpl implements CardPaymentStrategy {
    private final BobPayImpl client;

    public CardPaymentStrategyImpl(BobPayImpl client) {
        this.client = client;
    }

    @Override
    public TransactionResult authorize(CardPaymentDetails paymentDetails, BigDecimal amount) {
        BobPayCardPaymentAuthorizationResponse cardPaymentResult = client.authorizeCardPayment(paymentDetails, amount);
        // TODO: Map cardPaymentResult to TransactionResult
        return new TransactionResult();
    }
}

public class TokenPaymentStrategyImpl implements TokenPaymentStrategy {
    private final AlicePayImpl client;

    public TokenPaymentStrategyImpl(AlicePayImpl client) {
        this.client = client;
    }

    @Override
    public TransactionResult authorize(TokenPaymentDetails paymentDetails, BigDecimal amount) {
        AlicePayTokenPaymentAuthorizationResponse tokenPaymentResult = client.authorizeTokenPayment(paymentDetails, amount);
        // TODO: Map tokenPaymentResult to TransactionResult
        return new TransactionResult();
    }
}

public class PaymentProcessor {
    public TransactionResult authorize(CardPaymentStrategy strategy, CardPaymentDetails paymentDetails, BigDecimal amount) {
        return strategy.authorize(paymentDetails, amount);
    }

    public TransactionResult authorize(TokenPaymentStrategy strategy, TokenPaymentDetails paymentDetails, BigDecimal amount) {
        return strategy.authorize(paymentDetails, amount);
    }
}

As you can see, we have two low-level client libraries that provide payment methods with different method names and response models. The classes implementing CardPaymentStrategy and TokenPaymentStrategy help us standardize the types and method names by encapsulating the low-level clients. This allows the PaymentProcessor class to interact with the strategy classes using internal types. The solution works, but let’s take it a step further and improve it using the tools we have.

At first glance, the PaymentProcessor class doesn’t really care which strategy you call and takes advantage of Java’s method overloading. However, there are some code smells coming from this class. Ideally, it should be payment-method agnostic — we shouldn’t need to add another method every time we implement a new payment method.

Let's start by replacing the CardPaymentStrategy and TokenPaymentStrategy interfaces with PaymentStrategy<T> generic interface.

public interface PaymentStrategy<T> {
    TransactionResult authorize(T paymentDetails, BigDecimal amount);
}

public class CardPaymentStrategyImpl implements PaymentStrategy<CardPaymentDetails> {
 //...
}

public class TokenPaymentStrategyImpl implements PaymentStrategy<TokenPaymentDetails> {
    //...
}

And finally, our PaymentProcessor class would look like this:

public class PaymentProcessor {
    public <T> TransactionResult authorize(PaymentStrategy<T> strategy, T paymentDetails, BigDecimal amount) {
        return strategy.authorize(paymentDetails, amount);
    }
}

Generics are one of the most powerful features in Java. They help us write cleaner, safer, and more reusable code — all while catching type errors at compile time instead of at runtime.

But here’s something that often surprises developers: generics don’t actually exist at runtime in Java. So how does that work?

Let’s talk about Type Erasure.

Type erasure is the process by which the Java compiler (javac) removes all generic type information (such as or ) during compilation.

At compile time, the compiler uses generic type parameters (like T) to enforce type safety. For example, it ensures that your CardPaymentStrategyImpl can only receive a CardDetails object and reports an error if you attempt to pass a different type.

At runtime, however, all generic type information is erased and replaced with their unbounded type (usually Object) or with their upper bound if one was specified.

In the context of your PaymentStrategy<T> interface, the runtime sees the following:

Code Segment	Compile-Time View	Runtime View
Interface	`PaymentStrategy<T>`	`PaymentStrategy` (Raw Type)
Method	`TransactionResult authorize(T details, ...)`	`TransactionResult authorize(Object details, ...)`
Strategy	`CardPaymentStrategyImpl implements PaymentStrategy<CardDetails>`	`CardPaymentStrategyImpl implements PaymentStrategy`

For more information, I would strongly recommend checking the resources specified in the Credits section.

I tried to keep it as brief as possible, but there are many real-world cases in the libraries we use every day — for example, HTTP client libraries that map objects to requests or responses to objects.

Thanks for reading!

Credits:

Cover photo by Sigmund on Unsplash
Type Erasure in Java Explained

Spring AMQP: How to Convert Messages for Sending and Receiving Objects

İbrahim Gündüz — Tue, 14 Oct 2025 07:30:11 +0000

org.springframework.boot:spring-boot-starter-amqp uses SimpleMessageConverter as its default MessageConverter implementation. This means it handles text-based content, byte arrays, and serialized Java objects.

In this article, we'll see how to send and receive plain Java objects as RabbitMQ messages using Jackson2JsonMessageConverter.

Implementation

If your project doesn't use spring-boot-starter-web, add the following package to ensure you get the jackson libraries with the version managed by Spring boot.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-json</artifactId>
</dependency>

Create a new Jackson2JsonMessageConverter bean to use as the message converter for messages being sent and received.

@Bean
public Jackson2JsonMessageConverter messageConverter() {
    return new Jackson2JsonMessageConverter();
}

Create a new RestTemplate bean that uses the previously defined Jackson2JsonMessageConverter to convert messages being sent to objects.

@Bean
public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory, Jackson2JsonMessageConverter messageConverter) {
    RabbitTemplate rabbitTemplate = new RabbitTemplate(connectionFactory);
    rabbitTemplate.setMessageConverter(messageConverter);
    return rabbitTemplate;
}

And finally, create a new SimpleRabbitListenerContainerFactory that uses the message converter to enable Spring Boot to transform messages into plain Java objects in the listeners you create later.

@Bean
public SimpleRabbitListenerContainerFactory listenerContainerFactory(ConnectionFactory connectionFactory, Jackson2JsonMessageConverter messageConverter) {
    SimpleRabbitListenerContainerFactory factory = new SimpleRabbitListenerContainerFactory();
    factory.setConnectionFactory(connectionFactory);
    factory.setMessageConverter(messageConverter);
    return factory;
}

Now you can send and receive messages easily, as shown below.

PaymentEvent event = new PaymentEvent(
        "https://webhook.site/ecd3dc67-e32e-41d9-82ff-3505c0fd2ab9",
        "payment.completed",
        "8a7f70f6-912c-497e-802c-c7bde9e4bb33"
);

rabbitTemplate.convertAndSend(MessageBrokerBindingConfig.PAYMENT_EVENTS_EXCHANGE, "payment.events.completed", event);

@RabbitListener(queues = MessageBrokerBindingConfig.PAYMENT_EVENTS_QUEUE)
public void onMessage(PaymentEvent event) {
    //  TODO 
}

In this article, we briefly explained how to configure Spring AMQP to send and receive plain Java objects.

Thanks for reading.

Credits:

Interfacing 2.4" SSD1309 SPI OLED Display With ESP8266

İbrahim Gündüz — Fri, 10 Oct 2025 19:30:16 +0000

In this tutorial, we’ll learn how to connect 2.42" SSD13093 SPI OLED display with ESP8266. As a development board, we’ll use ESP8266 NodeMCU board.

SPI Pins in ESP8266 NodeMCU Board

ESP provides two SPI ports. However, the ones on the left side (SD1, CMD, SD0, CLK) cannot be used as it’s reserved for flash communication. So, we’ll connect the OLED display through Hardware SPI pins on the right side (D5, D6, D7, D8).

SSD1309 SPI OLED Display Pinouts

The OLED display requires some extra pin connections like DC, Reset, VCC, and GND pins besides the SPI communication pins. As the OLED screen requires 3.3V VCC voltage, the VCC pin should be connected ESP8266 NodeMCU board’s 3.3V pin and the GND pin to the board’s GND. RST and DC pins would be connected to ESP8266 NodeMCU board as it’s explained below.

SSD1309 SPI OLED Display ESP8266 NodeMCU Board Connection

Connect the OLED display to the ESP8266 NodeMCU board according to the connections described in the table below.

+----------------------------+---------------------------+
| ESP8266 NodeMCU Board Pins | SSD1309 OLED Display Pins |
+----------------------------+---------------------------+
| VCC                        | 3.3V                      |
| GND                        | GND                       |
| D5 (SCLK)                  | SCK                       |
| D7 (MOSI)                  | SDA                       |
| D8 (CS)                    | CS                        |
| D2                         | DC                        |
| D1                         | RES                       |
+----------------------------+---------------------------+

Sample Program Code

For the sample program code, I used u8g2 library to communicate the OLED display.

#include <U8g2lib.h>

U8G2_SSD1309_128X64_NONAME2_1_4W_HW_SPI u8g2(U8G2_R2, /* cs=*/ 15, /* dc=*/ 4, /* reset=*/ 5);  
void setup() {
  u8g2.begin();
  u8g2.setFont(u8g2_font_logisoso16_tf);

}

void loop() {
  u8g2.firstPage();
  do {
    u8g2.drawUTF8(30, 30, "Hello World!");
  } while (u8g2.nextPage());
}

Thanks for reading!

Credits

Configuring ESP8266 Wi-Fi Network Connection Through A Web Page

İbrahim Gündüz — Thu, 09 Oct 2025 09:03:07 +0000

ESP8266 is one of the popular Wi-Fi chips with microcontroller capability. In this article, we will touch on a couple of items that are possible to do with ESP8266 and finally, we will see how to configure a WI-FI network connection through a web page working on the chip by bringing all those together.

Creating A WI-FI Access Point

ESP8266 can operate in station and access point modes. As we need to access a web page to be running on ESP8266, we will see how to run the chip in access point mode first.

In order to configure the WI-FI, we import the ESP8266WiFi library.

#include <ESP8266WiFi.h>

Next, we define an SSID and a password for the Wi-Fi network we’re going to create.

const char *AP_SSID="MyDevice";
const char *AP_PASSWORD="123456789";

And finally, it’s time to start our mini access point.

void setup() {
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, AP_PASSWORD);
}

Let’s compile the code below and upload it to the development board (In my case, I used a NodeMCU board with an EP8266 chip)

#include <ESP8266WiFi.h>

const char *AP_SSID="MyDevice";
const char *AP_PASSWORD="123456789";

void setup() {
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, AP_PASSWORD);
}

void loop() {}

As you can see from the following picture, the access point name appears on the list.

Enter the password that we defined in the code to authenticate the network.

And, that’s it! ESP8266Wifi library handles the rest of the network configuration and allows assigning a dynamic IP to the connected client.

You can also manually configure the access point's network as follows

void setup() {
  IPAddress localIp(192, 168, 20, 1);
  IPAddress gatewayIp(0, 0, 0, 0);
  IPAddress netmask(255, 255, 255, 0);

  WiFi.mode(WIFI_AP);
  WiFi.softAPConfig(localIp, gatewayIp, netmask);
  WiFi.softAP(AP_SSID, AP_PASSWORD);
}

Connecting A Wi-Fi Network

We can connect to a Wi-Fi network by using the same library. Let’s start by defining the network credentials we’ll connect.

const char * WIFI_SSID = "YourRouterSsid";
const char * WIFI_PASSWORD = "YourWifiPassword";

Connect to the specified network.

WiFi.mode(WIFI_STA);
WiFi.begin(WIFI_SSID, WIFI_PASSWORD);

As it’s a process that is not immediately happening, we should keep it waiting until connected.

while (WiFi.status() != WL_CONNECTED) {
    delay(500);
}

And finally, maybe it’s good to print some information at the end.

 if (WiFi.status() == WL_CONNECTED) {
    Serial.println("Connected.");
    Serial.println(WiFi.localIP());
  } else {
    Serial.println("Not connected.");
  }

Let’s compile the code below and upload it to the development board.

#include <Arduino.h>
#include <ESP8266WiFi.h>

const char * WIFI_SSID = "YourRouterSsid";
const char * WIFI_PASSWORD = "YourWifiPassword";

void setup() {
  Serial.begin(9600);
  Serial.println("Connecting...");

  WiFi.mode(WIFI_STA);
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);

  // Wait until connected
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
  }

  if (WiFi.status() == WL_CONNECTED) {
    Serial.println("Connected.");
    Serial.println(WiFi.localIP());
  } else {
    Serial.println("Not connected.");
  }
}

void loop() {}

As you can see from the following picture, it connected to the network and obtained a new IP address from the DHCP service existing on the router.

Creating A Web Server

We can easily create a simple web server that handles just GET/POST requests by using ESP8266WebServer library.

Let’s take the following example:

// ...
#include <ESP8266WebServer.h>
// ...
ESP8266WebServer webServer(80);

void setup() {
  // ...
  webServer.on("/", handleRequest);
  webServer.begin();
}

void loop() {
  webServer.handleClient();
}

void handleRequest() {
  webServer.send(200, "text/html", "Hello World!");
}

As you can see from the code above, the web server starts listening to the port 80 defined while creating the class instance by calling the begin method. It handles the incoming requests by the handleClient() function called inside the loop method and, it calls the assigned request handler function accordingly with the request path.

The chip can operate the same logic for both access point and station modes.

Let’s compile the code below and upload it to the development board.

#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>

const char *AP_SSID="MyDevice";
const char *AP_PASSWORD="123456789";

void handleRequest();

ESP8266WebServer webServer(80);

void setup() {
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, AP_PASSWORD);

  webServer.on("/", handleRequest);
  webServer.begin();
}

void loop() {
  webServer.handleClient();
}

void handleRequest() {
  webServer.send(200, "text/html", "Hello World!");
}

After the uploading is complete, connect the access point named MyDevice and navigate http://192.168.4.1/ url from the browser.

Storing And Reading Data From The Flash Memory

Finally, we reached the last topic that we’re going to learn before putting everything together.

It’s possible to save some data on the chip although power cuts. You can use EEPROM library to write or read data from the flash memory. EEPROM emulates an EEPROM by using a part of the flash memory from the microcontroller.

Let's take a look at the code example below:

#include <Arduino.h>
#include <EEPROM.h>

struct WifiCredentials {
  char ssid[30];
  char password[30];
} 

wifiCredentials = {};

void setup() {
  Serial.begin(9600);
  delay(2000);

  strncpy(wifiCredentials.ssid, "MyDevice", sizeof(wifiCredentials.ssid));
  strncpy(wifiCredentials.password, "123456789", sizeof(wifiCredentials.password));

  // write the wifiCredentials variable content on the EPROM address 0.
  EEPROM.begin(sizeof(wifiCredentials));
  EEPROM.put(0, wifiCredentials);
  EEPROM.commit();

  // Read data from the EPROM address 0 into wifiCredentials variable.
  EEPROM.get(0, wifiCredentials);
  Serial.println(wifiCredentials.ssid);
}

void loop() {}

There are a few points to mention regarding the code above.

You need to call EEPROM.begin(n) before any reading or writing operation. (n) is the number of bytes to be used from the memory.

EEPROM does not store the data permanently before calling EEPROM.commit().

Setting Up Wi-Fi Network Through A Web Page on ESP8266

Although the code looks like a little bit large, simply it performs the following operations

Reads the stored credentials from EEPROM
Tries to connect to Wi-Fi if credentials exist
It starts the wifi in access point mode if the previously started connection has failed or no stored credentials exist.

Let’s compile the code below and upload it to the development board.

#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>
#include <EEPROM.h>
#include <Arduino.h>

#define AP_SSID "MyDevice"
#define AP_PASSWORD "123456789"
#define WEB_SERVER_PORT 80
#define MAX_CONNECTION_RETRY 30

struct WiFiCredentials
{
  char ssid[30];
  char password[30];
} wiFiCredentials = {};

void connectToWiFi(WiFiCredentials wiFiCredentials);
void setupAccessPoint();
void handleRequest();

ESP8266WebServer server(WEB_SERVER_PORT);

void setup()
{
  Serial.begin(9600);
  delay(2000);

  EEPROM.begin(sizeof(wiFiCredentials));

  EEPROM.get(0, wiFiCredentials);

  if (wiFiCredentials.ssid[0] != '\0')
  {
    connectToWiFi(wiFiCredentials);
  }

  if (WiFi.status() != WL_CONNECTED)
  {
    setupAccessPoint();
  }
}

void loop() {
  server.handleClient();
}

void connectToWiFi(WiFiCredentials wiFiCredentials)
{
  Serial.println("Connecting...");
  WiFi.mode(WIFI_STA);
  WiFi.begin(wiFiCredentials.ssid, wiFiCredentials.password);

  int unsigned retry = 0;

  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);

    if (retry++ > MAX_CONNECTION_RETRY) {
      break;
    }
  }

  if (WiFi.status()  == WL_CONNECTED) {
    Serial.println("Connected!");
    Serial.println(WiFi.localIP());
  } else {
    Serial.println("Failed to connect!");
  }
}

void setupAccessPoint()
{
  Serial.println("Starting Access Point");
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, AP_PASSWORD);

  server.on("/", handleRequest);
  server.begin();
}

void handleRequest() 
{
  if (server.method() == HTTP_POST) {
    strncpy(wiFiCredentials.ssid, server.arg("ssid").c_str(), sizeof(wiFiCredentials.ssid));
    strncpy(wiFiCredentials.password, server.arg("password").c_str(), sizeof(wiFiCredentials.password));

    wiFiCredentials.ssid[server.arg("ssid").length()] = wiFiCredentials.password[server.arg("password").length()] = 0;

    EEPROM.put(0, wiFiCredentials);
    EEPROM.commit();

    const char * content = "<html><head> <link rel=\"stylesheet\" href=\"https://netdna.bootstrapcdn.com/bootstrap/3.0.2/css/bootstrap.min.css\"> <style>body{background: #eee !important;}.wrapper{margin-top: 80px; margin-bottom: 80px;}.form-signin, .result-message{max-width: 380px; padding: 15px 35px 45px; margin: 0 auto; background-color: #fff; border: 1px solid rgba(0, 0, 0, 0.1);}.form-signin .form-signin-heading{margin-bottom: 30px;}.form-signin .form-control{position: relative; font-size: 16px; height: auto; padding: 10px; -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box;}.form-signin .form-control:focus{z-index: 2;}.form-signin input[type=text]{margin-bottom: -1px; border-bottom-left-radius: 0; border-bottom-right-radius: 0;}.form-signin input[type=password]{margin-bottom: 20px; border-top-left-radius: 0; border-top-right-radius: 0;}.result-message{text-align: center;}</style></head><body> <div class=\"wrapper\"> <div class=\"result-message\"> The Wi-Fi credentials have been stored. <br/> Please reboot the device! </div></div></body></html> ";
    server.send(200, "text/html", content);
  } else {
    const char * formHtml = "<html><head> <link rel=\"stylesheet\" href=\"https://netdna.bootstrapcdn.com/bootstrap/3.0.2/css/bootstrap.min.css\"> <style>body{background: #eee !important;}.wrapper{margin-top: 80px; margin-bottom: 80px;}.form-signin{max-width: 380px; padding: 15px 35px 45px; margin: 0 auto; background-color: #fff; border: 1px solid rgba(0, 0, 0, 0.1);}.form-signin .form-signin-heading{margin-bottom: 30px;}.form-signin .form-control{position: relative; font-size: 16px; height: auto; padding: 10px; -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box;}.form-signin .form-control:focus{z-index: 2;}.form-signin input[type=text]{margin-bottom: -1px; border-bottom-left-radius: 0; border-bottom-right-radius: 0;}.form-signin input[type=password]{margin-bottom: 20px; border-top-left-radius: 0; border-top-right-radius: 0;}</style></head><body> <div class=\"wrapper\"> <form class=\"form-signin\" method=\"POST\"> <h2 class=\"form-signin-heading\">Connect To Wi-Fi</h2> <input type=\"text\" class=\"form-control\" name=\"ssid\" placeholder=\"SSID\" required=\"\" autofocus=\"\"/> <input type=\"password\" class=\"form-control\" name=\"password\" placeholder=\"Password\" required=\"\"/> <button class=\"btn btn-lg btn-primary btn-block\" type=\"submit\">Save</button> </form> </div></body></html> ";
    server.send(200, "text/html", formHtml);
  }
}

Open the Wi-Fi network list from your computer, find the access point named MyDevice, and connect to it.

Navigate to http://192.168.4.1 from your browser and save your Wi-Fi network credentials.

After saving your credentials, your board will be ready to connect to the Wi-Fi network. All you have to do is reset the board after seeing the following page.

You can also check the debug information from the serial monitor to make sure the board is connected to the Wi-Fi network smoothly.

That’s it. You can see a short demo in the video below:

Thanks for reading!

DEV Community: İbrahim Gündüz

Spring Boot: A Practical Guide to Building Review Environments for Feature Branches

Externalizing Application Configuration with Environment Variables

Containerizing The Application

Provision the Review Environment Infrastructure

Provisioning Shared Infrastructure Services

Deploying Feature-Branch Application Services

CI/CD Integration

Connecting the CI Environment to Docker Swarm

Adding Packaging Step To CI/CD Pipeline

Adding Provisioning Step TO CI/CD Pipeline

Creating the PostgreSQL Database

Creating the RabbitMQ Virtual Host and User

Deploying the Feature-Branch Stack from CI

Cleanup Step

Configuring Wildcard DNS for Review Environments

Demo Time!

Conclusion

Credits:

Circuit Breaker in Inter-Service Communication

Resilience4j

Creating a CircuitBreaker Configuration

Executing The Remote Call

Scenario 1: The remote service is unreachable from the beginning

Scenario 2: Failed Calls Exceeds The Failure Rate Threshold And The Remote Service Recover Later

Decorating the Remote Call

Adding Fallback

Spring Cloud Circuit Breaker

Configuring Spring Cloud Circuit Breaker

Protecting Services With Circuit Breaker

Credits:

Message Schema Evolution in RabbitMQ: Using Virtual Hosts as Deployment Boundaries

Example Case:

v1: Delayed Capture After Authorization

v2: Partial capture based on stock availability

What Really Happens During a Rolling Deployment?

Scenario 1: v2 consumer processing v1 messages

Scenario 2: v1 consumer processing v2 messages

Using RabbitMQ Virtual Hosts as Deployment Boundaries

1. Externalize RabbitMQ Configuration

2. Provision Version-Scoped RabbitMQ Resources

3. Inject Configuration via Environment Variables

4. Deploy and Verify

5. Clean Up Old Resources

Credits:

Versioning Redis Cache Keys to Prevent Stale Data During Spring Boot Application Deployments

Example: Structure Changes On Cached Objects

How To Solve

Credits

Protecting Sensitive Data Using Envelope Encryption

What Are The Benefits Of Envelope Encryption?

Encryption Flow

Wrapping the Data Encryption Key (DEK)

Decryption Flow

A Note on Key Rotation:

Final Thoughts:

Credits

A Practical Guide to Google Guice

Setup

Constructor Injection

Setter Injection

Service Factory

Working In Multi-Module Projects

Named Bindings

Loading Configurations From .properties Files

Credits:

How to Align Spring Boot Validation Errors with Your JSON Property Naming Strategy

Problem

Solution

How to Configure Global Settings for Spring RestClient

Creating Client Bean with Common Parameters:

Exception Handling

Setting Up Client Connection and Read Timeouts

Changing Underlying HTTP Client Library

Client Request/Response Logging

Credits:

Generics as a Design Tool, Not Just a Language Feature

Example:

Credits:

Spring AMQP: How to Convert Messages for Sending and Receiving Objects

Loading Configurations From `.properties` Files