Instead of relying solely on Resilience4j, we’ll walk through the internal mechanics so you understand how circuit breakers actually work.

What We’ll Cover

1. Prerequisites and Technical Context

2. What Is a Circuit Breaker in Distributed Systems

   • Why Circuit Breakers Matter in Spring Boot

   • Why Circuit Breakers Are Foundational

   • What Problem Circuit Breakers Solve That Timeouts and Retries Do Not

   • The Circuit Breaker State Model

   • Why Not Just Use Resilience4j?

3. Design Goals for a Custom Circuit Breaker

4. How to Build a Minimal Working CircuitBreaker Class

   • Concurrency and State Transition Guarantees

   • Explaining the State Model in the Class

   • Failure Tracking Inside the Class

   • How Closed State Transitions to Open

   • OPEN State Behavior in the Class

   • Scheduler‑Driven Recovery: Entering HALF_OPEN

5. Spring Boot Scheduler Example

   • How This Connects to Execution Flow

   • Scheduler Design and Thread Safety

   • Why We Avoid @Scheduled for This Design

   • Bringing It All Together

   • Observability: Making the Breaker Understandable

   • Handling Different Failure Types

6. Custom Breaker vs Resilience4j

7. When You Should Not Build Your Own

8. Extending the Design

9. Common Mistakes

10. Conclusion

Prerequisites and Technical Context

This article assumes you are comfortable with core Spring Boot and Java concepts. We won’t cover framework fundamentals or basic concurrency principles in depth. Here’s what you’ll need to know:

Spring Boot Basics

You should be comfortable with how dependency injection works in Spring, how to define @Configuration classes and @Bean definitions, and the basic service-layer structure of a Spring application. In this tutorial, we’ll treat the circuit breaker as a plain Java component and wire it into Spring through configuration classes rather than annotations.

Java Concurrency Fundamentals

You don’t need to be a concurrency expert, but you should be comfortable with Java’s basic concurrency tools. The implementation uses AtomicInteger, volatile fields, a ScheduledExecutorService, and simple synchronization, so you should understand why shared mutable state is dangerous, how atomic operations differ from synchronized blocks, and why state transitions in a shared state machine must be serialized.

Functional Interfaces

The circuit breaker exposes an execute(Supplier<T>) method, so you should be comfortable using Supplier<T>, writing simple lambda expressions, and wrapping outbound service calls inside a function you can pass to the breaker.

Resilience4j Basics

You don’t need hands-on Resilience4j experience, but you should know that it’s a lightweight Java fault-tolerance library that offers circuit breakers, retries, rate limiters, bulkheads, and is commonly used in Spring Boot via annotations or config. In this article we’ll only reference Resilience4j for comparison, not for actual configuration or usage.

What Is a Circuit Breaker in Distributed Systems?

A circuit breaker is a fault-tolerance pattern that stops a system from repeatedly attempting operations that are likely to fail.

The name comes from electrical engineering. In a physical circuit, a breaker “opens” when the current becomes unsafe, preventing damage. After a cooldown period, it allows current to flow again to test whether the issue has been resolved.

In software, the same principle applies. When Service A depends on Service B, and Service B becomes slow or unavailable, naïvely retrying every request can:

• Exhaust thread pools

• Saturate connection pools

• Increase latency across the system

• Trigger cascading failures

• Bring down otherwise healthy services

Instead of continuing to send requests to a failing dependency, a circuit breaker:

• Detects repeated failures

• Opens the circuit and blocks calls

• Fails fast without attempting the operation

• Periodically tests whether the dependency has recovered

This turns uncontrolled failure into controlled degradation.

Why Circuit Breakers Matter in Spring Boot

Because circuit breakers are a foundational resilience pattern in distributed systems, most Spring Boot teams reach immediately for Resilience4j or legacy Hystrix‑style abstractions – and for good reason. These libraries are mature, well-tested, and production-proven.​

However, treating circuit breakers as black boxes often leads to:​

• Misconfigured thresholds

• Incorrect assumptions about failure handling

• Difficulty extending behavior beyond library defaults

• Debugging issues where “the breaker opened, but we don’t know why”​

Building your own circuit breaker – even if you never ship it to production – forces you to understand the mechanics that actually protect your system. In some cases, a custom implementation also provides flexibility that general-purpose libraries cannot.

Why Circuit Breakers Are Foundational

Circuit breakers are a foundational resilience pattern because they protect your scarcest resources (like threads, network and database connections, and CPU time) from being exhausted by a failing dependency.

Without a breaker, a single slow service can gradually consume all of those resources and turn a local problem into a system-wide outage.

Circuit breakers enforce isolation boundaries between services and sit alongside timeouts, retries, bulkheads, and rate limiters, but they make one crucial strategic choice that simple retries do not: they stop trying for now. That decision is what prevents cascading collapse.

What Problem Circuit Breakers Solve That Timeouts and Retries Do Not

Timeouts and retries are reactive: timeouts cap how long you wait, and retries try the same operation again in the hope it succeeds.

A circuit breaker is proactive. It monitors failure patterns and, once a threshold is crossed, temporarily disables the failing integration point so new requests are rejected immediately instead of timing out.This dramatically reduces resource waste and stabilizes the system under stress.

The Circuit Breaker State Model

Any circuit breaker – library-based or custom – follows the same conceptual state machine.​

1. Closed: In the Closed state, all requests are allowed and failures are simply monitored.

2. Open: When failures cross a configured threshold, the breaker moves to Open, blocks new requests, and makes them fail immediately.

3. Half-Open: After a cooldown period, it enters Half-Open, where it lets a small number of trial requests through to test whether the dependency has recovered; based on those results, it either returns to Closed or goes back to Open.

The complexity lies not in the states themselves, but in how and when transitions occur.​

Why Not Just Use Resilience4j?

Resilience4j is excellent, but there are valid reasons to build your own:​

• You want non-standard failure logic (for example, domain-aware errors).

• You need custom recovery strategies.

• You want state persisted or shared differently.

• You need tight integration with business metrics.

• You want to understand the internals for tuning and debugging.​

More importantly, understanding the internals prevents misuse. Many production incidents stem from misconfigured circuit breakers rather than missing ones.​

Design Goals for a Custom Circuit Breaker

Before writing any code, we need to be clear about what “correct” behavior looks like. A circuit breaker seems simple in theory, but subtle design mistakes can introduce race conditions, false openings, or silent failures where it stops protecting the system.

The following goals shape a predictable and production-safe implementation.

Thread-Safe and Low Overhead

The breaker sits on the hot path of outbound calls, so every protected request passes through it. If it introduces lock contention or heavy synchronization, it quickly becomes a bottleneck.

The implementation needs to avoid coarse-grained locking, use atomic primitives carefully, and serialize state transitions without blocking execution more than necessary. Thread safety is non‑negotiable: a circuit breaker that misbehaves under concurrency is worse than having no breaker at all.

Predictable State Transitions

Circuit breakers are state machines. If their transitions are inconsistent or prone to races, you end up with split‑brain behavior – one thread believes the breaker is OPEN while another believes it is CLOSED – and your protection becomes undefined.

To avoid this, every transition (CLOSED → OPEN → HALF_OPEN → CLOSED) must be explicit, atomic, and deterministic, all guarded by a single transition mechanism. In this design, predictability matters far more than cleverness.

Explicit Failure Tracking

Not every failure should open the breaker. If you blindly count every exception, you risk opening the breaker on client validation errors, treating business rule violations as infrastructure failures, and hiding real domain bugs behind resilience logic.

Failure classification has to be deliberate: the breaker should react only to infrastructure‑level problems such as timeouts, connection errors, and 5xx responses, not to domain logic errors. Keeping that separation ensures your resilience layer stays aligned with actual failure modes.

Time-Based Recovery Using a Scheduler

Some implementations check timestamps on every request to decide when to move from OPEN to HALF_OPEN, adding extra branching to the hot path.

Instead, this design uses a scheduler: when the breaker opens, it schedules a recovery attempt, keeps the OPEN state purely fail‑fast, and avoids request‑driven polling. That approach reduces branching and contention under load. Recovery should be controlled and predictable – not opportunistic.

Framework-Agnostic Core Logic

The breaker itself should be plain Java – no Spring annotations, no AOP, and no direct framework coupling. That choice makes unit testing easier, keeps the component portable, and preserves a clean separation of concerns with less hidden magic. Spring should wrap the breaker, not define it, so your resilience strategy is not trapped inside any one framework’s abstractions.

Easy Integration into Spring Boot

Although the core logic is framework‑agnostic, it still needs to plug cleanly into a Spring application. That means wiring it via @Configuration, supporting dependency injection, and calling it from clear execution points in your service layer. Resilience behavior should be obvious in code reviews. Hiding it behind annotations often leads to confusion when you are debugging production issues.

How to Build a Minimal Working CircuitBreaker Class

Now let’s turn the conceptual components into a single cohesive class. This is still a minimal implementation, but it’s complete enough to demonstrate state, failure tracking, scheduling, and execution logic in one place.

A minimal circuit breaker consists of:​

1. State holder

2. Failure tracker

3. Transition rules

4. Scheduler for recovery

5. Execution guard

public final class CircuitBreaker {

    enum State {
        CLOSED,
        OPEN,
        HALF_OPEN
    }

    private final ScheduledExecutorService scheduler;
    private final int failureThreshold;
    private final int halfOpenTrialLimit;
    private final Duration openCooldown;

    private final AtomicInteger failureCount = new AtomicInteger(0);
    private final AtomicInteger halfOpenTrials = new AtomicInteger(0);

    // All transitions go through this field, guarded by `synchronized` blocks.
    private volatile State state = State.CLOSED;

    public CircuitBreaker(
            ScheduledExecutorService scheduler,
            int failureThreshold,
            int halfOpenTrialLimit,
            Duration openCooldown
    ) {
        this.scheduler = scheduler;
        this.failureThreshold = failureThreshold;
        this.halfOpenTrialLimit = halfOpenTrialLimit;
        this.openCooldown = openCooldown;
    }

    public <T> T execute(Supplier<T> action) {
        // 1. Guards the functionality based on its current state. 
        //We are using synchronized block for thread safety. 
        // Make sure another thread does not override our current state
        State current;
        synchronized (this) {
            current = state;

            if (current == State.OPEN) {
                throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
            }

            if (current == State.HALF_OPEN) {
                int trials = halfOpenTrials.incrementAndGet();
                if (trials > halfOpenTrialLimit) {
                    // Too many trial requests; fail fast.
                    halfOpenTrials.decrementAndGet();
                    throw new IllegalStateException("Circuit breaker is HALF_OPEN. Trial limit exceeded.");
                }
            }
        }

        // 2. Execute the business functionality here. For e.g API calls to other systems 
        try {
            T result = action.get();
            // 3. Record success
            onSuccess();
            return result;
        } catch (Throwable t) {
            // 3. Record failure
            onFailure(t);
            // 4. Propagate to caller
            if (t instanceof RuntimeException re) {
                throw re;
            }
            if (t instanceof Error e) {
                throw e;
            }
            throw new RuntimeException(t);
        }
    }

    private void onSuccess() {
        synchronized (this) {
            failureCount.set(0);

            if (state == State.HALF_OPEN) {
                // A successful trial closes the breaker.
                transitionToClosed();
            }
        }
    }

    private void onFailure(Throwable t) {
        // Example: only count "server-side" failures.
        boolean breakerRelevant = true; // placeholder for domain-specific checks

        if (!breakerRelevant) {
            return;
        }

        synchronized (this) {
            int failures = failureCount.incrementAndGet();
            if (state == State.CLOSED && failures >= failureThreshold) {
                transitionToOpen();
            } else if (state == State.HALF_OPEN) {
                // Any failure in HALF_OPEN sends us back to OPEN.
                transitionToOpen();
            }
        }
    }

    private void transitionToOpen() {
        state = State.OPEN;
        // Reset counters so the next CLOSED phase starts clean.
        failureCount.set(0);
        halfOpenTrials.set(0);
        scheduleHalfOpen();
    }

    private void transitionToHalfOpen() {
        synchronized (this) {
            state = State.HALF_OPEN;
            halfOpenTrials.set(0);
        }
    }

    private void transitionToClosed() {
        state = State.CLOSED;
        failureCount.set(0);
        halfOpenTrials.set(0);
    }

    private void scheduleHalfOpen() {
        scheduler.schedule(
                this::transitionToHalfOpen,
                openCooldown.toMillis(),
                TimeUnit.MILLISECONDS
        );
    }
}

Now we’ll walk through each responsibility in that class: why the fields exist, how state transitions work, where concurrency guarantees matter, how execution is guarded, and how the scheduler drives recovery.

Each subsection maps directly back to part of this class – we’re not introducing new concepts, just explaining the behavior implemented within the code above.

Concurrency and State Transition Guarantees

Although the breaker uses atomic primitives for counters and a volatile state field, this only works because all state transitions are guarded consistently.​

In practice, every transition – CLOSED → OPEN, OPEN → HALF_OPEN, HALF_OPEN → CLOSED – must be performed under the same synchronization mechanism as shown below: either a single lock or a CAS-based state machine. Mixing unsynchronized state writes with atomic counters can lead to split-brain behavior (for example, one thread reopening the breaker while another closes it).​

synchronized (this) {
            current = state;

            if (current == State.OPEN) {
                throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
            }

            if (current == State.HALF_OPEN) {
                int trials = halfOpenTrials.incrementAndGet();
                if (trials > halfOpenTrialLimit) {
                    // Too many trial requests; fail fast.
                    halfOpenTrials.decrementAndGet();
                    throw new IllegalStateException("Circuit breaker is HALF_OPEN. Trial limit exceeded.");
                }
            }
        }

The rule is simple: reads may be optimistic, but writes and transitions must be serialized.

Explaining the State Model in the Class

At the core of the implementation is a simple but strict state machine represented by the State enum: CLOSED, OPEN and HALF_OPEN

The state field is declared volatile so changes are immediately visible across threads. When one thread moves the breaker to a new state, other threads see that update without delay.

Alongside the state, the class maintains failureCount and halfOpenTrials counters using AtomicInteger (Refer to the code in the above section). These track how failures accumulate and how many recovery attempts we have made, without resorting to coarse‑grained locks.

The key design idea is separation of responsibilities: the enum captures the current mode of operation, while the atomic counters hold the metrics that influence state transitions. Atomic increments alone do not guarantee safe transitions, though, so all updates to the state still follow a consistent serialization strategy to avoid race conditions.

enum State {
        CLOSED,
        OPEN,
        HALF_OPEN
    }

This structure gives us a clear foundation: a small, explicit state machine with observable transition boundaries.

Failure Tracking Inside the Class

private void onFailure(Throwable t) {
        // Example: only count "server-side" failures.
        boolean breakerRelevant = true; // placeholder for domain-specific checks

        if (!breakerRelevant) {
            return;
        }

        synchronized (this) {
            int failures = failureCount.incrementAndGet();
            if (state == State.CLOSED && failures >= failureThreshold) {
                transitionToOpen();
            } else if (state == State.HALF_OPEN) {
                // Any failure in HALF_OPEN sends us back to OPEN.
                transitionToOpen();
            }
        }
    }

In this implementation, failure tracking is intentionally simple: we count consecutive failures. Each time a protected call throws an exception we classify as breaker‑relevant, failureCount is incremented. On a successful call, the counter resets.

I chose consecutive failures for clarity rather than sophistication. More advanced strategies, like sliding time windows or failure ratios, introduce extra state and timing complexity. When you’re learning how a breaker works, a simple counter makes the transition rules easy to reason about and easy to test.

Equally important, the breaker should not treat every exception the same. Domain validation errors, client misuse, and business rule violations shouldn’t affect the breaker’s state. Only infrastructure‑level problems (like timeouts, connection failures, or 5xx responses) should move the breaker toward OPEN. That separation keeps the breaker focused on dependency instability, not application bugs or bad inputs.

How Closed State Transitions to Open

When the breaker is in the CLOSED state, all requests flow through normally. In this phase the breaker is purely observational: it monitors outcomes and increments failureCount whenever a breaker‑relevant exception occurs.

Inside the onFailure method (shown in the above section), once the failureCount exceeds the configured threshold, the breaker transitions to OPEN. This transition must be atomic and serialized – otherwise, multiple threads could try to open the breaker at the same time, leading to inconsistent scheduling or duplicate recovery tasks.

private void transitionToOpen() {
        state = State.OPEN;
        // Reset counters so the next CLOSED phase starts clean.
        failureCount.set(0);
        halfOpenTrials.set(0);
        scheduleHalfOpen();
    }

Moving to OPEN immediately changes system behavior. From that point on, new requests are rejected without attempting the protected operation, which shields downstream services and preserves local resources such as threads and connection pools.

OPEN State Behavior in the Class

The OPEN state represents pure fail‑fast behavior. While the breaker is open, no protected calls are executed. The execute() method immediately throws an exception indicating that the circuit is open.

public <T> T execute(Supplier<T> action) {
        // 1. Guards the functionality based on its current state. 
        //We are using synchronized block for thread safety. 
        // Make sure another thread does not override our current state
        State current;
        synchronized (this) {
            current = state;

            if (current == State.OPEN) {
                throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
            }
....
}

This behavior is not about improving latency – it is about resource protection. Letting calls continue and simply “wait for timeouts” would still tie up threads and connections. The value of the OPEN state is that it refuses to participate in propagating failure at all.

In this state, the breaker has a single responsibility: wait for the scheduled recovery attempt. It doesn’t check timestamps on each request or poll in the hot path. Its behavior is deterministic: reject immediately and let the scheduler decide when to try again.

Scheduler‑Driven Recovery: Entering HALF_OPEN

When the breaker transitions to OPEN, it immediately schedules a delayed task using the injected ScheduledExecutorService. After the configured cooldown period elapses, that task transitions the breaker to HALF_OPEN.

// Refer below methods from the main code 

private void transitionToOpen() {
        state = State.OPEN;
        // Reset counters so the next CLOSED phase starts clean.
        failureCount.set(0);
        halfOpenTrials.set(0);
        scheduleHalfOpen(); // schedule a delayed task after changing the state to State.Open
    }

private void scheduleHalfOpen() {
        scheduler.schedule(
                this::transitionToHalfOpen,
                openCooldown.toMillis(),
                TimeUnit.MILLISECONDS
        );
    }

This design keeps time-based logic out of the request execution path. Rather than checking elapsed time on every call, the breaker delegates recovery timing to a dedicated scheduler thread. This reduces conditional logic under load and keeps the execute() method focused on guarding execution.

The scheduler must be reliable and isolated. A single-threaded executor is typically sufficient because transitions are rare and lightweight. More importantly, transitions should be idempotent so that unexpected rescheduling does not corrupt state.

Spring Boot Scheduler Example

In Spring Boot, you can wire a dedicated ScheduledExecutorService bean to drive state transitions instead of using plain Java threads.

@Configuration
class CircuitBreakerConfig {

    // First bean 
    @Bean
    ScheduledExecutorService circuitBreakerScheduler() {
        return Executors.newSingleThreadScheduledExecutor();
    }

    // Second bean 
    @Bean
    CircuitBreaker circuitBreaker(ScheduledExecutorService circuitBreakerScheduler) {
        return new CircuitBreaker(
                circuitBreakerScheduler,
                5,                     // failureThreshold
                2,                     // halfOpenTrialLimit
                Duration.ofSeconds(30) // openCooldown
        );
    }
}

The configuration class above wires the circuit breaker into the Spring container without introducing framework coupling into the breaker itself.

The first bean circuitBreakerScheduler() defines a dedicated ScheduledExecutorService. This executor is responsible exclusively for time-based state transitions. When the breaker moves to OPEN, it uses this scheduler to queue a delayed task that transitions the state to HALF_OPEN.

Using a single-threaded executor is intentional. Circuit breaker transitions are lightweight and infrequent, so parallel scheduling is unnecessary. A single thread guarantees serialized transition execution and avoids overlapping recovery attempts.

The second bean constructs the CircuitBreaker itself. Here we inject the scheduler and configure three things: a failure threshold of 5 consecutive errors, a half‑open trial limit of 2 test requests, and a 30‑second cooldown before we attempt recovery again. This configuration makes the breaker’s behavior explicit and easy to reason about – there are no hidden properties files or annotations, because everything that affects resilience is defined in one place.

At this point, the breaker is a fully managed Spring bean that you can inject into services and use programmatically.

How This Connects to Execution Flow

Once registered as a bean, the breaker becomes part of the application’s dependency graph. A typical service might inject it and wrap outbound calls:

@Service
class ExternalApiService {

    private final CircuitBreaker circuitBreaker;
    private final RestTemplate restTemplate;

    ExternalApiService(CircuitBreaker circuitBreaker, RestTemplate restTemplate) {
        this.circuitBreaker = circuitBreaker;
        this.restTemplate = restTemplate;
    }

    public String callExternal() {
        return circuitBreaker.execute(() ->
                restTemplate.getForObject("http://external/api", String.class)
        );
    }
}

Every outbound call to the external system flows through the breaker’s execute() method, which enforces the current state rules before allowing the call to proceed. That makes resilience behavior explicit at the integration boundary: anyone reviewing the service can immediately see that the call is protected. There is no hidden interception layer and no AOP proxy quietly changing behavior at runtime.

Scheduler Design and Thread Safety

The scheduler’s only responsibility is delayed state transition. It doesn’t execute business logic and it doesn’t evaluate request outcomes. Its purpose is narrowly scoped: move the breaker from OPEN to HALF_OPEN after a cooldown.

Because the executor is single-threaded, scheduled tasks cannot overlap. But this doesn’t eliminate concurrency concerns entirely. Request threads may still attempt transitions at the same time the scheduler fires. For this reason, transition methods such as transitionToHalfOpen() and transitionToOpen() must remain serialized and idempotent.

In other words, even though the scheduler simplifies time-based recovery, it doesn’t replace the need for careful state management.

The architectural separation looks like this:

• Request threads → enforce execution rules and record outcomes

• Scheduler thread → handle time-based recovery transitions

Keeping these responsibilities separate reduces complexity in the hot path and improves predictability under load.

Why We Avoid @Scheduled for This Design

Spring provides @Scheduled as an alternative mechanism for time-based tasks. While convenient, it introduces global scheduling behavior and reduces isolation.

By using a dedicated ScheduledExecutorService for the breaker, we avoid interference with other scheduled jobs, keep lifecycle control explicit, and tie scheduling logic directly to breaker transitions.

This design reinforces the principle that resilience components should be isolated and predictable.

Bringing It All Together

At this stage, the full interaction looks like this:

1. A service wraps its dependency call with circuitBreaker.execute().

2. If the breaker is CLOSED, the call proceeds and any relevant failures are counted.

3. When failures exceed the threshold, the breaker moves to OPEN and schedules a recovery attempt.

4. While OPEN, calls fail immediately without hitting the downstream system.

5. After the cooldown period, the scheduler transitions the breaker to HALF_OPEN.

6. A small number of trial calls then decide whether the breaker returns to CLOSED or goes back to OPEN.

Nothing is hidden: every transition is visible in code, every configuration value is explicit, and each thread involved has a single responsibility. That clarity is what makes a custom implementation useful for learning – and safe when it is designed correctly.

Observability: Making the Breaker Understandable

A circuit breaker without observability is risky. At a minimum you should expose the current state, the failure count, the time of the last transition, and how long the breaker has been open.

On the metrics side, track how often the breaker opens, how many calls are rejected per second, and the success rate of recovery attempts.

Your logs should record state transitions at INFO level and failure classification decisions at DEBUG. With that level of visibility, your custom breaker is often easier to understand and tune than what many libraries provide out of the box..

Handling Different Failure Types

Not all failures are equal.

• API Response Timeouts → breaker‑relevant

• API 5xx responses → breaker‑relevant

• API 4xx responses → usually not

• Any data or business validation errors → never

A custom breaker lets you apply this kind of business‑aware classification, which is often hard to express cleanly with generic libraries.

Custom Breaker vs Resilience4j

The choice is not binary. Many teams prototype with a custom breaker and later replace it with Resilience4j – now correctly configured.​

When You Should Not Build Your Own

Do not build a custom breaker if:​

• You lack observability.

• You do not understand concurrency.

• You need advanced features immediately.

• Your system is safety-critical.​

For example, if you are building a payments platform with strict SLAs and cannot afford to battle-test a custom breaker, stick with a mature library like Resilience4j. The risk of subtle concurrency bugs, misclassified failures, or scheduler misconfigurations is too high to experiment in production.​

Extending the Design

Once you understand the core, you can add:​

• Sliding window metrics.

• Adaptive thresholds.

• Persistent breaker state.

• Distributed breakers (per dependency).

• Integration with feature flags.​

These extensions are much easier when you control the internals.​

Common Mistakes

Common mistakes when working with circuit breakers include:​

• Opening the breaker on the first failure.

• Blocking threads while OPEN.

• Allowing unlimited HALF_OPEN requests.

• Treating all exceptions equally.

• Ignoring observability.​

Most of these happen when using libraries without understanding them.​

Conclusion

Resilience libraries are powerful, but they are not magic. A circuit breaker is fundamentally a state machine with failure tracking and time-based transitions. Building your own – even once – forces you to internalize this reality.​

In Spring Boot systems, a custom circuit breaker:​

• Clarifies failure semantics.

• Improves debugging.

• Enables domain-specific resilience.

• Makes you a better user of Resilience4j.​

You may never deploy your own breaker to production. But after building one, you will never configure a circuit breaker blindly again.​

Using DTOs is helpful when building applications that hold sensitive data like financial or health records. When used properly, DTOs can prevent sensitive fields from being exposed to the client side. In critical systems, they can further tighten security and reduce failure conditions by ensuring that only valid and required fields are accepted.

In this article, you’ll learn what DTOs are, why they’re important, and the best ways to create them for your Spring-based applications.

Prerequisites

This is a slightly more advanced tutorial. So to understand it better, you should have a sound knowledge of Java concepts like objects, getters and setters, and Spring/Spring Boot. You should also have a solid understanding of how software works in general.

Table of Contents

• What is a DTO?

• How to Create a DTO for a Spring-Based Application

• How to Create DTOs From Two or Multiple Objects

• Conclusion

What is a DTO?

DTOs stand for Data Transfer Objects. It is a software design pattern that ensures the transfer of tailored/streamlined data objects between different layers of a software system.

Image source | Fabio Ribeiro

The direction of data transfer with DTOs across the various layers of software is bi-directional. DTOs are either used to carry data in an inbound direction from an external client/user to the software or are constructed and used to carry data in an outbound direction from the software.

DTOs only hold field data, constructors, and necessary getter and setter methods. So they are Plain Old Java Objects (POJOs).

You can see the bi-directional flow in the image below:

Image source | Fabio Ribeiro

Why Use DTOs?

1. Data Privacy

In Spring Boot, entities serve as the blueprint for creating data objects. These entities are classes annotated with @Entity and map to a database table. An instance of the entity class represents a database row or record, while a field in the entity class represents a database column.

When registering for a software service or product, the user might be asked to provide both sensitive and non-sensitive data for the proper functioning of the application. These data are held as fields by the entity class and finally mapped and persisted to the database.

When we need to retrieve data from the database and expose it through an API endpoint based on the query provided – say, a query to retrieve a user record or entity, Jackson (the serializer dependency commonly used in Spring-based applications) serialises all the data fields contained in the retrieved user entity. Now, imagine you have a User entity that contains fields like password, credit card details, date of birth, home address, and other sensitive data you wouldn’t want to reveal when the User entity is being serialised. Well, this is where DTOs come in.

With DTOs, you can retrieve the complete entity (containing both sensitive and insensitive data) from the database, create a custom class (say UserDTO.java) that only holds the insensitive fields that you feel are safe to expose, and finally, map the database-retrieved entity to the safe-to-expose UserDTO object. This way, the UserDTO is what gets serialised and exposed through the API endpoint and not the complete entity – keeping the sensitive data confidential.

2. Improved Software Performance

DTOs can improve the performance of your software application by reducing the number of API calls for data retrieval. With DTOs, you can return serialized data from more than one entity in just one API call.

Let’s say that in your Spring Boot application, there are User and Follower entities, and you want to return user data as well as their followers. Typically, Jackson can only serialize one entity at a time, either User or Follower. But with a DTO, you can combine these two entities into one and eventually serialize and return all the data in a single request, instead of building two endpoints to return user and follower data.

In the next section, I’ll show you the various ways you can create DTOs for your Spring Boot project with code implementations.

How to Create a DTO for a Spring-Based Application

There are two main approaches to creating DTOs in Spring/Spring Boot:

1. Creating Custom Objects and Handling Mapping Manually

This approach requires you to handle the mapping/transforming of your existing entity to the custom object (DTO) by yourself – that is to say, you write the code that creates the DTO and sets the DTO fields to the values present in the existing entity. This is common for developers who prefer fine-grained control, but it can be tedious for large-scale projects.

Follow the steps below to create a UserDTO from a User entity:

Step 1: Create the DTO class

Create a new file named UserDTO.java and write the code below into it:

public class UserDTO {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;


    // No-args Constructor
    public UserDTO() {}

    // All-args constructor
    public UserDTO(Long id, String firstName, String lastName, String email) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }


    // Getters and Setters
    public Long getId() {
        return id;
    }


    public void setId(Long id) {
        this.id = id;
    }


    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }


    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

}

The defined UserDTO class can only hold four (4) fields: id, firstName, lastName, and email. It’s not capable of exposing or receiving more than this number of fields. The class also contains getter and setter methods for retrieving and assigning data to the fields.

Step 2: Create Mapper Methods Inside a Utility Class

Create a new file named UserMapper.java and put this piece of code into it:

public class UserMapper {

    // Convert Entity to DTO

    public static UserDTO toDTO(UserEntity user) {

        if (user == null) return null;

        UserDTO dto = new UserDTO();
        dto.setId(user.getId());
        dto.setFirstName(user.getFirstName());
        dto.setLastName(user.getLastName());
        dto.setEmail(user.getEmail());
        return dto;
    }


    // Convert DTO to Entity

    public static UserEntity toEntity(UserDTO dto) {

        if (dto == null) return null;
       UserEntity user = new UserEntity(); 
        user.setFirstName(dto.getFirstName());
        user.setLastName(dto.getLastName());
        user.setEmail(dto.getEmail());

        return user;
    }

The UserMapper class is a utility class that maps the UserEntity to a DTO and the DTO to an entity. This is where the bi-directional data transfer I talked about earlier comes into play. First, the UserEntity-DTO-direction involves retrieving the complete record from the database and transforming it into a streamlined object (void of unnecessary information) before it’s serialized and exposed to the client side through an API endpoint.

The DTO-UserEntity-direction involves taking the object from the client side as input into the system, but this time, to limit the client in terms of the number of data fields they can pass to the system. This object is received, mapped to an entity, and saved in the system. This is important when you don’t want the client to have access to certain critical fields (that would make your application vulnerable). That’s why software engineers always say, “Don’t trust the user”.

Let me give you a peek into what our UserEntity looks like:

import jakarta.persistence.*;

import java.time.LocalDate;


@Entity

@Table(name = "users")

public class UserEntity {


    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)

    private Long id;
    private String firstName;
    private String lastName;

    @Column(unique = true)
    private String email;
    private String password;
    private String phoneNumber;
    private String gender;
    private LocalDate dateOfBirth;
    private String address;
    private String city;
    private String state;
    private String country;
    private String profilePictureUrl;
    private boolean isVerified;
    private LocalDate createdAt;
    private LocalDate updatedAt;

    // Constructors
    public UserEntity() {}

    // Getters and Setters
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getPhoneNumber() {
        return phoneNumber;
    }

    public void setPhoneNumber(String phoneNumber) {
        this.phoneNumber = phoneNumber;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public LocalDate getDateOfBirth() {
        return dateOfBirth;
    }

    public void setDateOfBirth(LocalDate dateOfBirth) {
        this.dateOfBirth = dateOfBirth;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public String getState() {
        return state;
    }

    public void setState(String state) {
        this.state = state;
    }

    public String getCountry() {
       return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getProfilePictureUrl() {
        return profilePictureUrl;
    }

    public void setProfilePictureUrl(String profilePictureUrl) {
        this.profilePictureUrl = profilePictureUrl;
    }

    public boolean isVerified() {
        return isVerified;
    }

    public void setVerified(boolean verified) {
        isVerified = verified;
    }

    public LocalDate getCreatedAt() {
        return createdAt;
    }

    public void setCreatedAt(LocalDate createdAt) {
        this.createdAt = createdAt;
    }

    public LocalDate getUpdatedAt() {
        return updatedAt;
    }

    public void setUpdatedAt(LocalDate updatedAt) {
        this.updatedAt = updatedAt;
    }

}

In the code snippet above, you can see that the UserDTO holds just four (4) fields, which are insensitive and safe to expose upon serialization. These fields are id, firstName, lastName, and email – unlike the UserEntity, which contains both the sensitive and insensitive fields. So, the not-safe-to-expose UserEntity maps to the safe-to-expose UserDTO. With that being done, the UserDTO object can be serialized and returned through an endpoint. You can now see why DTOs help us prevent exposing confidential information.

2. Creating Custom Objects and Handling Mapping Through an External Library

Using an external library means adding a layer of abstraction to the mapping process. The library handles the stressful parts of the job for you, and it’s often a preferred choice for large-scale projects. In this article, we’re using MapStruct because it’s popular and easy to use. Maven will be our build tool.

Step 1: Add the dependency to your project

Since you are using Maven as your build tool, open your pom.xml file and add this code:

<dependencies>
    <!-- MapStruct API -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>
</dependencies>
<build>
    <plugins>
        <!-- Annotation processor plugin -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>1.5.5.Final</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

This will help download the dependency during the project build.

Step 2: Define your DTO

Use the UserDTO.java file given in step 1 of the first approach.

Step 3: Create the MapStruct Mapper Interface

Create a file and name it UserMapper.java, and add the code below to it:

import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    UserDTO toDTO(UserEntity user);
    UserEntity toEntity(UserDTO userDTO);
}

The UserMapper interface contains the INSTANCE field and two methods, namely toDTO and toEntity, that take in objects of types UserEntity and UserDTO, respectively, as arguments. The implementations of these methods are abstracted and handled by the library for us.

You can now use the mapper methods (toDTO and toEntity) in your Service or Controller.

How to Create DTOs From Two or Multiple Objects

This is one of the most important ways to use DTOs: creating DTOs from more than one entity and combining them as one, so that they can be returned in one API call or request.

There are many ways you can apply this technique and create complex response DTOs, based on the requirements of your project. The form or structure of your API response object might not be the same as the example given in this tutorial – but the same principle applies, which is simply creating individual DTOs and combining them into one DTO, which eventually serves as the response DTO.

The example below isn’t super complex, but it’s sufficient to help you understand how this works so you can leverage the technique in creating more complex API response objects. This example will combine DTOs of a doctor and their appointments.

Step 1: Create the DTO Classes

Create a file named DoctorDto.java and add this code to it:

public class DoctorProfileDTO {
    private String doctorId;
    private String fullName;
    private String email;
    private String specialization;

   // No-args constructor
   public DoctorProfileDTO(){
    }

    // Getter and Setter for doctorId
    public String getDoctorId() {
        return doctorId;
    }

    public void setDoctorId(String doctorId) {
        this.doctorId = doctorId;
    }

    // Getter and Setter for fullName
    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }

    // Getter and Setter for email
    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    // Getter and Setter for specialization
    public String getSpecialization() {
        return specialization;
    }

    public void setSpecialization(String specialization) {
        this.specialization = specialization;
    }
}

Create another one called AppointmentDto.java and include this code:

public class AppointmentDTO {
    private String appointmentId;
    private String appointmentDate;
    private String status;
    private String patientName;
    private String patientEmail;

   // No-args constructor
   public AppointmentDTO(){
    }

    // Getter and Setter for appointmentId
    public String getAppointmentId() {
        return appointmentId;
    }

    public void setAppointmentId(String appointmentId) {
        this.appointmentId = appointmentId;
    }

    // Getter and Setter for appointmentDate
    public String getAppointmentDate() {
        return appointmentDate;
    }

    public void setAppointmentDate(String appointmentDate) {
        this.appointmentDate = appointmentDate;
    }

    // Getter and Setter for status
    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    // Getter and Setter for patientName
    public String getPatientName() {
        return patientName;
    }

    public void setPatientName(String patientName) {
        this.patientName = patientName;
    }

    // Getter and Setter for patientEmail
    public String getPatientEmail() {
        return patientEmail;
    }

    public void setPatientEmail(String patientEmail) {
        this.patientEmail = patientEmail;
    }
}

Step 2: Create a Composite DTO Combining both Entities

Create a file named DoctorWithAppointmentsDTO.java:

import java.util.List;

public class DoctorWithAppointmentsDTO {
    private DoctorProfileDTO doctorProfile;
    private List<AppointmentDTO> appointments;

    // No-args constructor
    public DoctorWithAppointmentsDTO() {
    }

    // Getter and Setter for doctorProfile
    public DoctorProfileDTO getDoctorProfile() {
        return doctorProfile;
    }

    public void setDoctorProfile(DoctorProfileDTO doctorProfile) {
        this.doctorProfile = doctorProfile;
    }

    // Getter and Setter for appointments
    public List<AppointmentDTO> getAppointments() {
        return appointments;
    }

    public void setAppointments(List<AppointmentDTO> appointments) {
        this.appointments = appointments;
    }
}

Step 3: Create a Mapper Class

Create a mapper class DoctorMapper.java containing the logic to map to the DoctorWithAppointmentsDTO class:

public class MapperClass {

    public DoctorWithAppointmentsDTO toDTO(Doctor doctor, List<Appointment> appointments) {

        DoctorProfileDTO doctorProfile = new DoctorProfileDTO();
        doctorProfile.setDoctorId(doctor.getId());
        doctorProfile.setFullName(doctor.getFullName());
        doctorProfile.setEmail(doctor.getEmail());
        doctorProfile.setSpecialization(doctor.getSpecialization());

        List<AppointmentDTO> appointmentDTOs = appointments.stream().map(appt -> {
            AppointmentDTO dto = new AppointmentDTO();
            dto.setAppointmentId(appt.getId());
            dto.setAppointmentDate(appt.getDate().toString()); 
            dto.setStatus(appt.getStatus().name());
            dto.setPatientName(appt.getPatient().getName());
            dto.setPatientEmail(appt.getPatient().getEmail());
            return dto;
        }).toList();

        DoctorWithAppointmentsDTO doctorWithAppointment = new DoctorWithAppointmentsDTO();
        doctorWithAppointment.setDoctorProfile(doctorProfile);
        doctorWithAppointment.setAppointments(appointmentDTOs);

        return doctorWithAppointment;
    }
}

From the example above, you can see that two separate DTOs (AppointmentDTO and DoctorProfileDTO) were created before the composite DTO, DoctorWithAppointmentsDTO was created. The composite DTO class (DoctorWithAppointmentsDTO) contains fields that hold the instances of the Appointment and DoctorProfile DTOs. The mapper class takes in the Doctor and a list of Appointment entities as arguments, maps them to DoctorProfileDTO and AppointmentDTO, respectively. Finally, the fields for the composite DTO class are set using the DTO objects mapped from the entities.

The DoctorWithAppointmentsDTO, when serialised and returned through an endpoint, should give you an output like this:

{
  "doctorProfile": {
    "doctorId": "abc123",
    "fullName": "Dr. Susan Emeka",
    "email": "suzan.emeka@example.com",
    "specialisation": "Cardiology"
  },
  "appointments": [
    {
      "appointmentId": "appt001",
      "appointmentDate": "2025-07-10T09:00:00",
      "status": "CONFIRMED",
      "patientName": "James Agaji",
      "patientEmail": "james.agaji@example.com"
    },
 {
      "appointmentId": "appt002",
      "appointmentDate": "2025-08-12T07:05:08",
      "status": "CONFIRMED",
      "patientName": "Jane Augustine",
      "patientEmail": "jane.augustine@example.com"
    }
  ]
}

Conclusion

If you’re a software engineer who’s concerned with privacy and efficiency, using DTOs in your applications is a must.

In this article, you’ve learned what DTOs are as well as the main approaches for creating and using them. Take the time to go through the code snippets given in this article and practice with them until you’re comfortable implementing them yourself. Thanks for reading.

If you’re learning Java with the end goal of building applications, you’ll need to be able to choose a suitable Java framework (a collection of necessary pre-built tools and libraries) to make development easier once you know the fundamentals.

There are many Java frameworks out there that help you complete different tasks, such as Jakarta EE (formerly Java EE, an enterprise-level framework, used for large-scale applications), JSF (or JavaServer Faces, a UI framework for developing Java web interfaces), Spring, Spring Boot, and others.

You may have heard of Spring and Spring Boot by now, as they are very popular and commonly used by Java devs. In this article, you will learn:

• What the Spring and Spring Boot frameworks are.

• Their real-world use cases and how to get started building with them.

• The key differences between Spring and Spring Boot.

Prerequisites

To fully understand the content of this article, you should have a good working knowledge of the Java programming language, be familiar with the concept of APIs (Application Programming Interfaces), and know how to use Java project build tools – especially Maven, as it’s the build tool we’ll use for this article’s code examples.

Table of Contents

• What is the Spring Framework?

• What is the Spring Boot Framework?

• Core Differences Between Spring and Spring Boot

• Real World Example

• How to Choose Between Spring and Spring Boot

• Conclusion

What is the Spring Framework?

Spring is a framework used for building modern enterprise-grade applications. It’s primarily used for Java, but it’s also compatible with the Kotlin and Groovy programming languages, too. This means that you can use Kotlin and Groovy to develop applications in Spring.

Spring provides a clear paradigm you can follow for building and configuring applications for easy deployment on any platform you choose.

At the core of the Spring framework is its robust infrastructure support. It internally handles implementing key components that are required for the safety and overall functionality of enterprise applications. It does this using modules such as:

• Spring JDBC

• Spring MVC

• Spring Security

• Spring AOP

• Spring ORM and

• Spring Test

These let developers focus on the business logic of the application instead of worrying about implementing or writing the code for the components/modules from scratch. This saves significant development time.

Why use Spring?

Spring does a lot of heavy lifting in terms of reducing excessive infrastructure code through its modules compared to legacy Java frameworks. This is one of the reasons it’s so popular.

For instance, when it comes to handling dependencies in Spring, you just have to define the dependency using the @Bean annotation in a configuration class, replacing the older approach of adding the dependency in an XML file.

Spring then adds the bean to an IoC (Inversion of Control) container, and makes the bean available to be utilised during runtime, also handling the lifecycle and wiring automatically.

Here is a simple code illustration of the configuration class below:

@Configuration

public class AppConfig{

@Bean

public DataSource dataSource() {

    DriverManagerDataSource ds = new DriverManagerDataSource();

    ds.setUrl("jdbc:mysql://localhost:3306/mydb");

    ds.setUsername("user");

    ds.setPassword("pass");

    return ds;

  }


}

Here’s the class where the resource/dependency is utilised:

@Component

public class UserRepository {

private DataSource dataSource;

public UserRepository(DataSource dataSource){

      this.dataSource = dataSource;

}

    public void connectToDb() throws SQLException {

        Connection conn = dataSource.getConnection();

        System.out.println("Connected to DB via Spring!");

        conn.close();

    }

}

These code snippets demonstrate how dependency injection is implemented using Spring’s @Bean and @Component annotations. In the code is a configuration class and a second class where the DataSource is injected and used. This shows a simplistic approach to dependency management in Spring.

Key Components of the Spring Framework

Spring is made up of several components, each serving distinct roles (as shown in the image below):

Image source | Overview of the Spring Framework

These components collectively provide useful functionalities that make Spring a robust framework. Think of them as parts that make up a whole. Let me briefly explain each of the components and their various roles for easy understanding.

Data Access/Integration:

This component enables easy interaction with databases and other data sources. It contains several modules (JDBC, ORM, OXM, JMS and Transaction Management), each performing unique functions.

These modules provide fine-grained abstraction for tasks like executing SQL queries, integrating with ORM frameworks (for example, Hibernate), handling XML data binding, messaging, and managing transactions, while working in a Spring-based application.

Web:

The Web component makes interaction between the client side (through HTTP request) and the core business logic possible in a Spring application. It consists of four modules (Web, Web-Servlet, Web-Struts, and Web-Portlet), each serving a specific function:

• The Web module enables multipart file upload functionality and initialization of the IoC container.

• Web-Servlet module provides an MVC (Model View Controller) Implementation for web applications.

• The Web-Struts module integrates Struts into Spring by using support classes.

• The Web-Portlet module supports MVC implementation for use in a portlet environment.

AOP and Instrumentation:

AOP provides the implementation that makes it possible to ensure the separation of “cross-cutting concerns” in your application from the business logic, leading to cleaner and more organized code that’s free from clutter and repetition.

Instead of writing these concerns everywhere in your classes, you just define them in aspects and they are injected for you by Spring when the program needs them. These concerns could be logging, security, or transactions.

Instrumentation:

This enables class instrumentation support, which ensures class bytecode modification.

Core Container:

Core Container as the name implies, is a crucial part of Spring. It is responsible for some of the unique features that make the Spring Framework desired and popular: IoC (Inversion of Control) and dependency injection.

Core Container is made of Beans, Core, Context and Expression Language modules. These modules all have unique, yet complementary properties.

Test:

The Test component provides a suitable approach to testing Spring applications, and it integrates smoothly with JUnit or TestNG. It goes as far as providing mock objects that can be used to test different components of your application in either an isolated or Spring-managed environment, helping you achieve a robust and reliable software application.

What is the Spring Boot Framework?

Spring Boot is an open-source framework built on top of Spring for developing robust stand-alone applications that you can “easily run”. The major purpose for which Spring Boot was created was to further simplify the process of configuring and running Spring applications.

Spring Boot enforces an opinionated approach to development and provides extra useful features not contained in Spring. Let’s learn a bit more about how it works.

Key Features of the Spring Boot Framework

Spring Boot, being part of the Spring ecosystem, inherits most Spring functionalities, but contains additional features not included in Spring. Let me explain these unique features briefly:

Auto-configuration

Spring Boot automatically configures dependencies present in the classpath (location where the Java runtime looks for classes/resources during compilation) through the @SpringBootApplication annotation. This is a combination of @EnableAutoConfiguration, @Configuration, and @ComponentScan. This auto-configuration saves effort in writing boilerplate code for configuring dependencies/beans (as you have to do with Spring).

Here’s how you can use the @SpringBootApplication annotation for auto-configuration in Spring Boot applications:

      @SpringBootApplication

public class MyApp {

    public static void main(String[] args) {

        SpringApplication.run(MyApp.class, args);

    }

}

Starter dependencies

Starter dependencies provide a cleaner and less verbose way of managing dependencies in Spring Boot. Essentially, it bundles a set of complementary dependencies that perform a common task into one, meaning you don’t need to manually declare every single dependency that is part of the starter bundle.

Starter dependencies in Spring Boot follow the naming convention spring-boot-starter-*, where the asterisk represents the name of the particular dependency.

Some common starter dependencies in Spring Boot are:

• spring-boot-starter-web

• spring-boot-starter-aop

• spring-boot-starter-data-jdbc

• spring-boot-starter-data-jpa

• spring-boot-starter-data-rest

Actuator

Actuator is a module in the Spring Boot framework that lets you monitor Spring Boot applications after/during development. It provides both inbuilt and customizable endpoints you can use for application health checks, metrics, and diagnostics.

These are some of the commonly used endpoints:

• /actuator/health: Provides health status.

• /actuator/metrics: Displays various application metrics.

• /actuator/info: Shows general application information.

• /actuator/env: Exposes environment properties.

• /actuator/beans: Lists all Spring beans.

• /actuator/threaddump: Performs a thread dump.

• /actuator/shutdown: Allows graceful shutdown (disabled by default).

Command line tool

The Spring Boot command line tool is an interface that helps you rapidly develop and test your Spring Boot applications. It contains commands you can use to:

• Run Spring Boot applications from the terminal directly (spring run).

• Manage application dependencies and versions

• Initialize a new Spring Boot project

• Compile and test Java/Groovy scripts.

Additional configuration (through application.properties and application.yml files)

application.properties and application.yml files are two formats you can use to configure your Spring Boot application settings. They are in key-value and YAML formats, respectively. They let you configure ports, data source, logging, caching, and so on.

 server.port=8081
 spring.datasource.url=jdbc:mysql://localhost:3306/mydb

spring.datasource.username=root

spring.datasource.password=secret

logging.level.org.springframework=DEBUG

This is an example of an application.properties file for a Spring Boot project. You can see that the port, datasource and logging credentials have been configured.

Embedded Web Server

Spring Boot comes with embedded web servers (Tomcat, Jetty, and Undertow) that are used to easily serve compiled Spring Boot applications in the form of jar files without needing to deploy them to an external, dedicated web server. This simplifies deployment, especially in a microservice architecture and containerised environments, as applications can be easily run using the command:

java -jar my-springboot-app.jar

Note that Spring Boot cannot exist without Spring (but Spring can exist without Jakarta EE and other Java legacy frameworks created before it). Spring Boot is part of the Spring platform. It is like the extra icing on top of the cake that makes it sweeter.

Of course, you can still have your cake without the icing. Technically, you can say Spring Boot is an additional layer that still needs Spring to run as its underlying infrastructure.

Core Differences Between Spring and Spring Boot

You should now be familiar with the fundamentals of the Spring and Spring Boot frameworks. So let’s talk a bit more about how they differ, x-raying their strengths and areas of weakness.

Configuration

Configuration in Spring is more tedious when compared to Spring Boot, since you’ll need to manually add the configurations for your project in Spring. This requires more code for setting up the various components you need for a project.

Meanwhile, configuration in Spring Boot is easier as you can use the Spring Initializr website. There, you just have to select the dependencies for the project, add a little more setup, and then download the zip file that contains the configuration for the project. It requires minimal steps to do this, which improves your productivity and makes the learning curve easier.

External Server and Deployment

Spring requires that you deploy your applications to an external server like Tomcat in the form of a WAR (Web Application Archive or Web Application Resource) file.

Spring Boot, on the other hand, comes with an embedded server like Tomcat, which you can use for running/deploying stand-alone executable applications as JAR (or Java ARchive) files. This is why Spring Boot is highly preferred for developing microservices since it is relatively easy to build applications and run them.

Level of Control

Both Spring and Spring Boot utilise the Inversion of Control (or IoC) paradigm for managing dependencies. Spring gives you more control over the application because you have the flexibility to initiate configurations as needed. But Spring Boot handles more of the application management internally, giving you little room for control over the application configuration, as it auto-generates configurations that may not be needed for a particular project. This can lead to redundant code.

Suitability for Development

Spring, like Java EE, is preferred for large-scale enterprise applications due to its fine-grained configuration control that is invaluable, especially for complex and critical performance applications like banking, healthcare, and e-commerce. It provides great flexibility, which makes it suitable for integrating with Java EE components and other enterprise-grade technologies and legacy systems.

Spring Boot is not a common choice for large-scale monolithic applications, even though it can be used in these cases. It is more suitable for developing stand-alone applications or microservices where rapid development with embedded server support is prioritized over granular configuration and control.

Production-ready features

In Spring, extra effort is needed to manually set up health checks, metrics and monitoring of your application. Whereas, Spring Boot comes with the actuator, which is a built-in tool that is useful for metrics, application monitoring, and for carrying out health checks. You just need to add this dependency to your pom.xml file

<dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-actuator</artifactId>

</dependency>

After that, you can monitor your application by visiting the desired actuator endpoint that exposes the needed information. Find a list of the common actuator endpoints you can visit under the Actuator subsection of the What is Spring Boot section above.

Real World Example

Let’s look at an example of how to build a simple REST API endpoint in both Spring and Spring Boot frameworks:

Building with the Spring Framework

In this API example, the technologies/dependencies we’ll use are:

• Java (Programming Language)

• Maven (the build tool for the project)

• Tomcat (servlet container)

• Operating System (Mac/Linux/Windows)

• Core Spring framework with the Spring MVC module

• Jackson Databind: for JSON serialisation

Note that we’ll be using Maven here as our build tool (and for the Spring Boot example that follows, too) because of its simplicity and beginner friendliness.

Step 1: Create AppConfig.java file

This is the configuration class that sets on Spring MVC properties through the @EnableWebMvc annotation, scans for the controllers in their packages through the @ComponentScan annotation, and configures other needed defaults automatically.

@Configuration

@EnableWebMvc

@ComponentScan(basePackages = "com.example.controller")

public class AppConfig implements WebMvcConfigurer {

}

Step 2: Create WebAppInitializer.java

This is the class that replaces web.xml (That was used in older versions.) It creates the Spring application context and connects to the AppConfig file for configuration.

public class WebAppInitializer implements WebApplicationInitializer {  
  @Override
  public void onStartup(ServletContext servletContext) {

    // Create annotation-based web context

    AnnotationConfigWebApplicationContext context = 

      new AnnotationConfigWebApplicationContext();

    context.register(AppConfig.class);

    // Register DispatcherServlet

    DispatcherServlet servlet = new DispatcherServlet(context);

    ServletRegistration.Dynamic registration = 

      servletContext.addServlet("dispatcher", servlet);

    registration.setLoadOnStartup(1);

    registration.addMapping("/");

  }

}

Step 3: Add the controller logic

Create a HelloController.java file and add the controller logic. It receives a GET request and returns “Hello from Spring Framework!”

@RestController // Combines @Controller + @ResponseBody

public class HelloController {

  @GetMapping("/hello")

  public String hello() {

    return "Hello from Spring Framework!";

  }

}

Step 4: Add Dependencies

Include all the dependencies for the project in a pom.xml file, since we’re using Maven as the build tool.

<dependency>

  <groupId>org.springframework</groupId>

  <artifactId>spring-webmvc</artifactId>

  <version>6.1.6</version> <!-- Latest Spring 6.x -->

</dependency>

<dependency>

  <groupId>com.fasterxml.jackson.core</groupId>

  <artifactId>jackson-databind</artifactId>

  <version>2.17.0</version> <!-- For JSON support -->

</dependency>

Step 5: Build and Deploy the API

Lastly, you have to build the application into a WAR (Web Archive) file and deploy it to a servlet container (like Tomcat, Jetty, or whichever is suitable) before the application can be made accessible.

Follow the steps given below to deploy to a Tomcat server:

1. Package the app as a WAR file

If Maven is your build tool for the project, add this configuration code to your Pom.xml file:

<packaging>war</packaging>

Then, build using the command:

./mvnw clean package

After this, your WAR file will be created and stored in target/yourapp.war

2. Deploy your WAR file to a servlet container (in this case, Tomcat)

At this point, you can choose to either deploy your WAR file to a remote or local servlet container on your machine. Let’s deploy to a local servlet container since you can easily practice this on your own.

• Download and install Apache Tomcat from the official website https://tomcat.apache.org/

• Enter the webapps directory by entering the command cd path-to-tomcat/webapps/

• Copy your WAR file into the folder

cp /path-to-your/target/yourapp.war

• Start the Tomcat web server.

On Linux/Mac OS, run:

./bin/startup.sh

On Windows, do:

startup.bat.

You should see a link similar to this on your terminal window:

http://localhost:8080/yourapp

Go ahead and click on it. And there you go!

Building with the Spring Boot Framework

The different technologies from the Spring example that I will use are simply the Embedded Tomcat server over the Tomcat servlet container. And here, of course, we’ll be using Spring Boot as the development framework instead of Spring.

In Spring Boot, you can either go straight into your IDE and start creating the needed files and configurations for your project, or you can choose to use the Spring initializr to select dependencies and generate the base files and configurations for your project. The second option is preferred since it is less tedious.

Step 1: Choose Necessary Dependencies for Your Project and Download the Zip File

Open the Spring initializr website, choose the project as Maven, language as Java, and fill in the project metadata. For this project, fill in the Artifact as Hello.

Choose jar for packaging, and then select the dependencies for the project. For this article, we will use only the Spring Web. Then click on the generate button.

This downloads a zip file to your machine containing the boilerplate code with which you can build your application.

Step 2: Create the Controller (HelloController.java)

Unzip the downloaded file from step 1, and open it in your preferred IDE (or Integrated Development Environment). Navigate to the Hello/src/main/java/com/example/Hello directory, where you should already have the HelloApplication.java file, and add the HelloController.java file:

@RestController

public class HelloController {

  @GetMapping("/hello")

  public String hello() {

    return "Hello from Spring Boot!";

  }

}

Step 3: Build and run the application

On your terminal, run the following commands: mvn clean package && java -jar target/your-app.jar. You can then access the endpoint on http://localhost:8080/hello. When you click on the link, you should see Hello from Spring Boot! on your screen.

How to Choose Between Spring and Spring Boot

Spring and Spring Boot are both popular Java frameworks for building robust software solutions. And as you have learned from the earlier part of this tutorial, they have many common features (since Spring Boot is built atop Spring).

But there are a few key areas where they differ. First is the format of their packaged files: Spring is packaged to WAR, and Spring Boot to JAR. Also, Spring Boot comes with an embedded web server while Spring requires an external servlet container.

The embedded web server that comes with Spring Boot makes it easy to run Spring Boot applications during development and in production without needing an external servlet container. Meanwhile, traditional Spring requires developers to deploy to an external servlet container. This makes Spring Boot suitable for rapid development and deployment of stand-alone applications or microservices, as it not only saves time but also reduces setup complexity and infrastructure requirements.

Furthermore, Spring’s fine-grained configuration and ease of integration with legacy systems and tools make it the desired choice for developing highly customizable enterprise-grade applications. This is unlike Spring Boot, which relies on the convention-over-configuration philosophy, providing auto-configuration for reduced development time.

Conclusion

Building enterprise-grade and microservices applications with Java is much easier using the Spring and Spring Boot frameworks.

In this article, you’ve learned how these two frameworks work, along with their areas of strength and drawbacks.

This article doesn’t intend to favour one framework over the other, but rather to show in detail how they differ and their unique characteristics.

But to summarize:

• Use Spring when building highly customized legacy-integrated enterprise systems.

• Use Spring Boot for REST APIs, microservices, or cloud-native apps.

The next time you are faced with a project requiring you to choose a similar framework, it is imperative to carefully weigh your choices and select the framework that closely fits your task. Happy coding!

References

1. Spring Framework Official Documentation

2. Baeldung – Introduction to Spring Framework

3. Ellow. Spring vs Spring Boot: An In-depth Comparison

We just published a course on the freeCodeCamp.org YouTube channel that will teach you all about integrating AI capabilities into your Spring Boot applications using Spring AI. Developed by Faisal Memon, this hands-on course goes beyond theory, guiding you through practical projects that showcase the real-world potential of AI in application development. By the end of the course, you'll have built a variety of projects that combine AI creativity and productivity, giving you a solid foundation in leveraging AI technologies with Spring Boot.

What You'll Build

The course is structured around two key projects, designed to give you a comprehensive understanding of how to apply AI in different contexts:

1. Project 1: Stock Photo Generator, Q&A Bot, and Recipe Generator

   • This project blends creativity and utility by exploring three different AI-driven tools:

     • Stock Photo Generator: Generate high-quality images using AI.

     • Q&A Bot: Build a chatbot capable of answering questions based on user input.

     • Recipe Generator: Create a tool that suggests recipes based on ingredients, powered by machine learning.

2. Project 2: Audio Transcriber

   • Develop a transcription tool that converts spoken words into written text. This project demonstrates how to incorporate state-of-the-art speech recognition and processing technologies within a Spring Boot application.

Course Outline

This course is packed with detailed tutorials and step-by-step guidance. Here are the key topics and sections you’ll cover:

1. Introduction to Spring AI and understanding the core concepts.

2. Setting Up Projects with proper configurations and dependencies.

3. Integrating OpenAI APIs for NLP and image generation.

4. Building Services and Controllers for chat and image generation features.

5. Parameterizing and Customizing Outputs to enhance functionality.

6. Creating a React Frontend to interact with your Spring Boot backend.

7. Handling CORS Issues and other common development challenges.

8. Developing the Audio Transcriber Tool with end-to-end integration.

9. Styling Your Applications with CSS and frontend best practices.

Why Learn Spring AI?

Spring AI offers a streamlined way to integrate AI into your Java applications without reinventing the wheel. It provides standardized ways to access powerful AI models (like OpenAI’s GPT and image generation APIs) within familiar Spring Boot paradigms. This means you can leverage your existing Spring skills while unlocking new AI-driven possibilities. From chatbots to image generation and transcription tools, the potential applications are vast and relevant to modern software development needs.

If you’re ready to level up your Spring Boot applications with cutting-edge AI features, head over to the freeCodeCamp.org YouTube channel and watch this course (5-hour watch).

In this guide, we'll dive deep into some of the most popular design patterns and show you how to implement them in Spring Boot. By the end, you'll not only understand these patterns conceptually but also be able to apply them in your own projects with confidence.

Table of Contents

• Introduction to Design Patterns

• How to Set Up Your Spring Boot Project

• What is the Singleton Pattern?

• What is the Factory Pattern?

• What is the Strategy Pattern?

• What is the Observer Pattern?

• How to Use Spring Boot’s Dependency Injection

• Best Practices and Optimization Tips

• Conclusion and Key Takeaways

Introduction to Design Patterns

Design patterns are reusable solutions to common software design problems. Think of them as best practices distilled into templates that can be applied to solve specific challenges in your code. They are not specific to any language, but they can be particularly powerful in Java due to its object-oriented nature.

In this guide, we'll cover:

• Singleton Pattern: Ensuring a class has only one instance.

• Factory Pattern: Creating objects without specifying the exact class.

• Strategy Pattern: Allowing algorithms to be selected at runtime.

• Observer Pattern: Setting up a publish-subscribe relationship.

We'll not only cover how these patterns work but also explore how they can be applied in Spring Boot for real-world applications.

How to Set Up Your Spring Boot Project

Before we dive into the patterns, let’s set up a Spring Boot project:

Prerequisites

Make sure you have:

• Java 11+

• Maven

• Spring Boot CLI (optional)

• Postman or curl (for testing)

Project Initialization

You can quickly create a Spring Boot project using Spring Initializr:

curl https://start.spring.io/starter.zip \
-d dependencies=web \
-d name=DesignPatternsDemo \
-d javaVersion=11 -o design-patterns-demo.zip
unzip design-patterns-demo.zip
cd design-patterns-demo

What is the Singleton Pattern?

The Singleton pattern ensures that a class has only one instance and provides a global access point to it. This pattern is commonly used for services like logging, configuration management, or database connections.

How to Implement the Singleton Pattern in Spring Boot

Spring Boot beans are singletons by default, meaning that Spring automatically manages the lifecycle of these beans to ensure only one instance exists. However, it's important to understand how the Singleton pattern works under the hood, especially when you're not using Spring-managed beans or need more control over instance management.

Let’s walk through a manual implementation of the Singleton pattern to demonstrate how you can control the creation of a single instance within your application.

Step 1: Create a LoggerService Class

In this example, we’ll create a simple logging service using the Singleton pattern. The goal is to ensure that all parts of the application use the same logging instance.

public class LoggerService {
    // The static variable to hold the single instance
    private static LoggerService instance;

    // Private constructor to prevent instantiation from outside
    private LoggerService() {
        // This constructor is intentionally empty to prevent other classes from creating instances
    }

    // Public method to provide access to the single instance
    public static synchronized LoggerService getInstance() {
        if (instance == null) {
            instance = new LoggerService();
        }
        return instance;
    }

    // Example logging method
    public void log(String message) {
        System.out.println("[LOG] " + message);
    }
}

• Static Variable (instance): This holds the single instance of LoggerService.

• Private Constructor: The constructor is marked private to prevent other classes from creating new instances directly.

• Synchronized getInstance() Method: The method is synchronized to make it thread-safe, ensuring that only one instance is created even if multiple threads try to access it simultaneously.

• Lazy Initialization: The instance is created only when it's first requested (lazy initialization), which is efficient in terms of memory usage.

Real-World Usage: This pattern is commonly used for shared resources, such as logging, configuration settings, or managing database connections, where you want to control access and ensure that only one instance is used throughout your application.

Step 2: Use the Singleton in a Spring Boot Controller

Now, let's see how we can use our LoggerService Singleton within a Spring Boot controller. This controller will expose an endpoint that logs a message whenever it's accessed.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class LogController {

    @GetMapping("/log")
    public ResponseEntity<String> logMessage() {
        // Accessing the Singleton instance of LoggerService
        LoggerService logger = LoggerService.getInstance();
        logger.log("This is a log message!");
        return ResponseEntity.ok("Message logged successfully");
    }
}

• GET Endpoint: We’ve created a /log endpoint that, when accessed, logs a message using the LoggerService.

• Singleton Usage: Instead of creating a new instance of LoggerService, we call getInstance() to ensure we’re using the same instance every time.

• Response: After logging, the endpoint returns a response indicating success.

Step 3: Testing the Singleton Pattern

Now, let's test this endpoint using Postman or your browser:

GET http://localhost:8080/log

Expected Output:

• Console log: [LOG] This is a log message!

• HTTP Response: Message logged successfully

You can call the endpoint multiple times, and you'll see that the same instance of LoggerService is used, as indicated by the consistent log output.

Real-World Use Cases for the Singleton Pattern

Here’s when you might want to use the Singleton pattern in real-world applications:

1. Configuration Management: Ensure that your application uses a consistent set of configuration settings, especially when those settings are loaded from files or databases.

2. Database Connection Pools: Control access to a limited number of database connections, ensuring that the same pool is shared across the application.

3. Caching: Maintain a single cache instance to avoid inconsistent data.

4. Logging Services: As shown in this example, use a single logging service to centralize log outputs across different modules of your application.

Key Takeaways

• The Singleton pattern is an easy way to ensure that only one instance of a class is created.

• Thread safety is crucial if multiple threads are accessing the Singleton, which is why we used synchronized in our example.

• Spring Boot beans are already singletons by default, but understanding how to implement it manually helps you gain more control when needed.

This covers the implementation and usage of the Singleton pattern. Next, we’ll explore the Factory pattern to see how it can help streamline object creation.

What is the Factory Pattern?

The Factory pattern allows you to create objects without specifying the exact class. This pattern is useful when you have different types of objects that need to be instantiated based on some input.

How to Implementing a Factory in Spring Boot

The Factory pattern is incredibly useful when you need to create objects based on certain criteria but want to decouple the object creation process from your main application logic.

In this section, we’ll walk through building a NotificationFactory to send notifications via Email or SMS. This is especially useful if you anticipate adding more notification types in the future, such as push notifications or in-app alerts, without changing your existing code.

Step 1: Create the Notification Interface

The first step is to define a common interface that all notification types will implement. This ensures that each type of notification (Email, SMS, and so on) will have a consistent send() method.

public interface Notification {
    void send(String message);
}

• Purpose: The Notification interface defines the contract for sending notifications. Any class that implements this interface must provide an implementation for the send() method.

• Scalability: By using an interface, you can easily extend your application in the future to include other types of notifications without modifying existing code.

Step 2: Implement EmailNotification and SMSNotification

Now, let's implement two concrete classes, one for sending emails and another for sending SMS messages.

public class EmailNotification implements Notification {
    @Override
    public void send(String message) {
        System.out.println("Sending Email: " + message);
    }
}

public class SMSNotification implements Notification {
    @Override
    public void send(String message) {
        System.out.println("Sending SMS: " + message);
    }
}

Step 3: Create a NotificationFactory

The NotificationFactory class is responsible for creating instances of Notification based on the specified type. This design ensures that the NotificationController doesn’t need to know about the details of object creation.

public class NotificationFactory {
    public static Notification createNotification(String type) {
        switch (type.toUpperCase()) {
            case "EMAIL":
                return new EmailNotification();
            case "SMS":
                return new SMSNotification();
            default:
                throw new IllegalArgumentException("Unknown notification type: " + type);
        }
    }
}

Factory Method (createNotification()):

• The factory method takes a string (type) as input and returns an instance of the corresponding notification class.

• Switch Statement: The switch statement selects the appropriate notification type based on the input.

• Error Handling: If the provided type is not recognized, it throws an IllegalArgumentException. This ensures that invalid types are caught early.

Why Use a Factory?

• Decoupling: The factory pattern decouples object creation from the business logic. This makes your code more modular and easier to maintain.

• Extensibility: If you want to add a new notification type, you only need to update the factory without changing the controller logic.

Step 4: Use the Factory in a Spring Boot Controller

Now, let’s put everything together by creating a Spring Boot controller that uses the NotificationFactory to send notifications based on the user’s request.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class NotificationController {

    @GetMapping("/notify")
    public ResponseEntity<String> notify(@RequestParam String type, @RequestParam String message) {
        try {
            // Create the appropriate Notification object using the factory
            Notification notification = NotificationFactory.createNotification(type);
            notification.send(message);
            return ResponseEntity.ok("Notification sent successfully!");
        } catch (IllegalArgumentException e) {
            return ResponseEntity.badRequest().body(e.getMessage());
        }
    }
}

GET Endpoint (/notify):

• The controller exposes a /notify endpoint that accepts two query parameters: type (either "EMAIL" or "SMS") and message.

• It uses the NotificationFactory to create the appropriate notification type and sends the message.

• Error Handling: If an invalid notification type is provided, the controller catches the IllegalArgumentException and returns a 400 Bad Request response.

Step 5: Testing the Factory Pattern

Let’s test the endpoint using Postman or a browser:

1. Send an Email Notification:

    GET http://localhost:8080/notify?type=email&message=Hello%20Email
   

   Output:

    Sending Email: Hello Email
   

2. Send an SMS Notification:

    GET http://localhost:8080/notify?type=sms&message=Hello%20SMS
   

   Output:

    Sending SMS: Hello SMS
   

3. Test with an Invalid Type:

    GET http://localhost:8080/notify?type=unknown&message=Test
   

   Output:

    Bad Request: Unknown notification type: unknown
   

Real-World Use Cases for the Factory Pattern

The Factory pattern is particularly useful in scenarios where:

1. Dynamic Object Creation: When you need to create objects based on user input, like sending different types of notifications, generating reports in various formats, or handling different payment methods.

2. Decoupling Object Creation: By using a factory, you can keep your main business logic separate from object creation, making your code more maintainable.

3. Scalability: Easily extend your application to support new types of notifications without modifying existing code. Simply add a new class that implements the Notification interface and update the factory.

What is the Strategy Pattern?

The Strategy pattern is perfect when you need to switch between multiple algorithms or behaviors dynamically. It allows you to define a family of algorithms, encapsulate each one within separate classes, and make them easily interchangeable at runtime. This is especially useful for selecting an algorithm based on specific conditions, keeping your code clean, modular, and flexible.

Real-World Use Case: Imagine an e-commerce system that needs to support multiple payment options, like credit cards, PayPal, or bank transfers. By using the Strategy pattern, you can easily add or modify payment methods without altering existing code. This approach ensures that your application remains scalable and maintainable as you introduce new features or update existing ones.

We’ll demonstrate this pattern with a Spring Boot example that handles payments using either a credit card or PayPal strategy.

Step 1: Define a PaymentStrategy Interface

We start by creating a common interface that all payment strategies will implement:

public interface PaymentStrategy {
    void pay(double amount);
}

The interface defines a contract for all payment methods, ensuring consistency across implementations.

Step 2: Implement Payment Strategies

Create concrete classes for credit card and PayPal payments.

public class CreditCardPayment implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("Paid $" + amount + " with Credit Card");
    }
}

public class PayPalPayment implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("Paid $" + amount + " via PayPal");
    }
}

Each class implements the pay() method with its specific behavior.

Step 3: Use the Strategy in a Controller

Create a controller to dynamically select a payment strategy based on user input:

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PaymentController {

    @GetMapping("/pay")
    public ResponseEntity<String> processPayment(@RequestParam String method, @RequestParam double amount) {
        PaymentStrategy strategy = selectPaymentStrategy(method);
        if (strategy == null) {
            return ResponseEntity.badRequest().body("Invalid payment method");
        }
        strategy.pay(amount);
        return ResponseEntity.ok("Payment processed successfully!");
    }

    private PaymentStrategy selectPaymentStrategy(String method) {
        switch (method.toUpperCase()) {
            case "CREDIT": return new CreditCardPayment();
            case "PAYPAL": return new PayPalPayment();
            default: return null;
        }
    }
}

The endpoint accepts method and amount as query parameters and processes the payment using the appropriate strategy.

Step 4: Testing the Endpoint

1. Credit Card Payment:

    GET http://localhost:8080/pay?method=credit&amount=100
   

   Output: Paid $100.0 with Credit Card

2. PayPal Payment:

    GET http://localhost:8080/pay?method=paypal&amount=50
   

   Output: Paid $50.0 via PayPal

3. Invalid Method:

    GET http://localhost:8080/pay?method=bitcoin&amount=25
   

   Output: Invalid payment method

Use Cases for the Strategy Pattern

• Payment Processing: Dynamically switch between different payment gateways.

• Sorting Algorithms: Choose the best sorting method based on data size.

• File Exporting: Export reports in various formats (PDF, Excel, CSV).

Key Takeaways

• The Strategy pattern keeps your code modular and follows the Open/Closed principle.

• Adding new strategies is easy—just create a new class implementing the PaymentStrategy interface.

• It’s ideal for scenarios where you need flexible algorithm selection at runtime.

Next, we’ll explore the Observer pattern, perfect for handling event-driven architectures.

What is the Observer Pattern?

The Observer pattern is ideal when you have one object (the subject) that needs to notify multiple other objects (observers) about changes in its state. It’s perfect for event-driven systems where updates need to be pushed to various components without creating tight coupling between them. This pattern allows you to maintain a clean architecture, especially when different parts of your system need to react to changes independently.

Real-World Use Case: This pattern is commonly used in systems that send notifications or alerts, such as chat applications or stock price trackers, where updates need to be pushed to users in real-time. By using the Observer pattern, you can add or remove notification types easily without altering the core logic.

We’ll demonstrate how to implement this pattern in Spring Boot by building a simple notification system where both Email and SMS notifications are sent whenever a user registers.

Step 1: Create an Observer Interface

We begin by defining a common interface that all observers will implement:

public interface Observer {
    void update(String event);
}

The interface establishes a contract where all observers must implement the update() method, which will be triggered whenever the subject changes.

Step 2: Implement EmailObserver and SMSObserver

Next, we create two concrete implementations of the Observer interface to handle email and SMS notifications.

EmailObserver Class

public class EmailObserver implements Observer {
    @Override
    public void update(String event) {
        System.out.println("Email sent for event: " + event);
    }
}

The EmailObserver handles sending email notifications whenever it's notified of an event.

SMSObserver Class

public class SMSObserver implements Observer {
    @Override
    public void update(String event) {
        System.out.println("SMS sent for event: " + event);
    }
}

The SMSObserver handles sending SMS notifications whenever it's notified.

Step 3: Create a UserService Class (The Subject)

We’ll now create a UserService class that acts as the subject, notifying its registered observers whenever a user registers.

import org.springframework.stereotype.Service;
import java.util.ArrayList;
import java.util.List;

@Service
public class UserService {
    private List<Observer> observers = new ArrayList<>();

    // Method to register observers
    public void registerObserver(Observer observer) {
        observers.add(observer);
    }

    // Method to notify all registered observers of an event
    public void notifyObservers(String event) {
        for (Observer observer : observers) {
            observer.update(event);
        }
    }

    // Method to register a new user and notify observers
    public void registerUser(String username) {
        System.out.println("User registered: " + username);
        notifyObservers("User Registration");
    }
}

• Observers List: Keeps track of all registered observers.

• registerObserver() Method: Adds new observers to the list.

• notifyObservers() Method: Notifies all registered observers when an event occurs.

• registerUser() Method: Registers a new user and triggers notifications to all observers.

Step 4: Use the Observer Pattern in a Controller

Finally, we’ll create a Spring Boot controller to expose an endpoint for user registration. This controller will register both EmailObserver and SMSObserver with the UserService.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
public class UserController {
    private final UserService userService;

    public UserController() {
        this.userService = new UserService();
        // Register observers
        userService.registerObserver(new EmailObserver());
        userService.registerObserver(new SMSObserver());
    }

    @PostMapping("/register")
    public ResponseEntity<String> registerUser(@RequestParam String username) {
        userService.registerUser(username);
        return ResponseEntity.ok("User registered and notifications sent!");
    }
}

• Endpoint (/register): Accepts a username parameter and registers the user, triggering notifications to all observers.

• Observers: Both EmailObserver and SMSObserver are registered with UserService, so they are notified whenever a user registers.

Testing the Observer Pattern

Now, let’s test our implementation using Postman or a browser:

POST http://localhost:8080/api/register?username=JohnDoe

Expected Output in Console:

User registered: JohnDoe
Email sent for event: User Registration
SMS sent for event: User Registration

The system registers the user and notifies both the Email and SMS observers, showcasing the flexibility of the Observer pattern.

Real-World Applications of the Observer Pattern

1. Notification Systems: Sending updates to users via different channels (email, SMS, push notifications) when certain events occur.

2. Event-Driven Architectures: Notifying multiple subsystems when specific actions take place, such as user activities or system alerts.

3. Data Streaming: Broadcasting data changes to various consumers in real-time (for example, live stock prices or social media feeds).

How to Use Spring Boot’s Dependency Injection

So far, we’ve been manually creating objects to demonstrate design patterns. However, in real-world Spring Boot applications, Dependency Injection (DI) is the preferred way to manage object creation. DI allows Spring to automatically handle the instantiation and wiring of your classes, making your code more modular, testable, and maintainable.

Let’s refactor our Strategy pattern example to take advantage of Spring Boot's powerful DI capabilities. This will allow us to switch between payment strategies dynamically, using Spring’s annotations to manage dependencies.

Updated Strategy Pattern Using Spring Boot's DI

In our refactored example, we’ll leverage Spring’s annotations like @Component, @Service, and @Autowired to streamline the process of injecting dependencies.

Step 1: Annotate Payment Strategies with @Component

First, we’ll mark our strategy implementations with the @Component annotation so that Spring can detect and manage them automatically.

@Component("creditCardPayment")
public class CreditCardPayment implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("Paid $" + amount + " with Credit Card");
    }
}

@Component("payPalPayment")
public class PayPalPayment implements PaymentStrategy {
    @Override
    public void pay(double amount) {
        System.out.println("Paid $" + amount + " using PayPal");
    }
}

• @Component Annotation: By adding @Component, we tell Spring to treat these classes as Spring-managed beans. The string value ("creditCardPayment" and "payPalPayment") acts as the bean identifier.

• Flexibility: This setup allows us to switch between strategies by using the appropriate bean identifier.

Step 2: Refactor the PaymentService to Use Dependency Injection

Next, let’s modify the PaymentService to inject a specific payment strategy using @Autowired and @Qualifier.

@Service
public class PaymentService {
    private final PaymentStrategy paymentStrategy;

    @Autowired
    public PaymentService(@Qualifier("payPalPayment") PaymentStrategy paymentStrategy) {
        this.paymentStrategy = paymentStrategy;
    }

    public void processPayment(double amount) {
        paymentStrategy.pay(amount);
    }
}

• @Service Annotation: Marks PaymentService as a Spring-managed service bean.

• @Autowired: Spring injects the required dependency automatically.

• @Qualifier: Specifies which implementation of PaymentStrategy to inject. In this example, we’re using "payPalPayment".

• Ease of Configuration: By simply changing the @Qualifier value, you can switch the payment strategy without altering any business logic.

Step 3: Using the Refactored Service in a Controller

To see the benefits of this refactoring, let’s update the controller to use our PaymentService:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
public class PaymentController {
    private final PaymentService paymentService;

    @Autowired
    public PaymentController(PaymentService paymentService) {
        this.paymentService = paymentService;
    }

    @GetMapping("/pay")
    public String makePayment(@RequestParam double amount) {
        paymentService.processPayment(amount);
        return "Payment processed using the current strategy!";
    }
}

• @Autowired: The controller automatically receives the PaymentService with the injected payment strategy.

• GET Endpoint (/pay): When accessed, it processes a payment using the currently configured strategy (PayPal in this example).

Testing the Refactored Strategy Pattern with DI

Now, let’s test the new implementation using Postman or a browser:

GET http://localhost:8080/api/pay?amount=100

Expected Output:

Paid $100.0 using PayPal

If you change the qualifier in PaymentService to "creditCardPayment", the output will change accordingly:

Paid $100.0 with Credit Card

Benefits of Using Dependency Injection

• Loose Coupling: The service and controller don’t need to know the details of how a payment is processed. They simply rely on Spring to inject the correct implementation.

• Modularity: You can easily add new payment methods (for example, BankTransferPayment, CryptoPayment) by creating new classes annotated with @Component and adjusting the @Qualifier.

• Configurability: By leveraging Spring Profiles, you can switch strategies based on the environment (for example, development vs. production).

Example: You can use @Profile to automatically inject different strategies based on the active profile:

@Component
@Profile("dev")
public class DevPaymentStrategy implements PaymentStrategy { /* ... */ }

@Component
@Profile("prod")
public class ProdPaymentStrategy implements PaymentStrategy { /* ... */ }

Key Takeaways

• By using Spring Boot’s DI, you can simplify object creation and improve the flexibility of your code.

• The Strategy Pattern combined with DI allows you to easily switch between different strategies without changing your core business logic.

• Using @Qualifier and Spring Profiles gives you the flexibility to configure your application based on different environments or requirements.

This approach not only makes your code cleaner but also prepares it for more advanced configurations and scaling in the future. In the next section, we’ll explore Best Practices and Optimization Tips to take your Spring Boot applications to the next level.

Best Practices and Optimization Tips

General Best Practices

• Don’t overuse patterns: Use them only when necessary. Overengineering can make your code harder to maintain.

• Favor composition over inheritance: Patterns like Strategy and Observer are great examples of this principle.

• Keep your patterns flexible: Leverage interfaces to keep your code decoupled.

Performance Considerations

• Singleton Pattern: Ensure thread safety by using synchronized or the Bill Pugh Singleton Design.

• Factory Pattern: Cache objects if they are expensive to create.

• Observer Pattern: Use asynchronous processing if you have many observers to prevent blocking.

Advanced Topics

• Using Reflection with the Factory pattern for dynamic class loading.

• Leveraging Spring Profiles to switch strategies based on the environment.

• Adding Swagger Documentation for your API endpoints.

Conclusion and Key Takeaways

In this tutorial, we explored some of the most powerful design patterns—Singleton, Factory, Strategy, and Observer—and demonstrated how to implement them in Spring Boot. Let’s briefly summarize each pattern and highlight what it’s best suited for:

Singleton Pattern:

• Summary: Ensures that a class has only one instance and provides a global access point to it.

• Best For: Managing shared resources like configuration settings, database connections, or logging services. It’s ideal when you want to control access to a shared instance across your entire application.

Factory Pattern:

• Summary: Provides a way to create objects without specifying the exact class to be instantiated. This pattern decouples object creation from the business logic.

• Best For: Scenarios where you need to create different types of objects based on input conditions, such as sending notifications via email, SMS, or push notifications. It’s great for making your code more modular and extensible.

Strategy Pattern:

• Summary: Allows you to define a family of algorithms, encapsulate each one, and make them interchangeable. This pattern helps you choose an algorithm at runtime.

• Best For: When you need to switch between different behaviors or algorithms dynamically, such as processing various payment methods in an e-commerce application. It keeps your code flexible and adheres to the Open/Closed Principle.

Observer Pattern:

• Summary: Defines a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.

• Best For: Event-driven systems like notification services, real-time updates in chat apps, or systems that need to react to changes in data. It’s ideal for decoupling components and making your system more scalable.

What’s Next?

Now that you’ve learned these essential design patterns, try integrating them into your existing projects to see how they can improve your code structure and scalability. Here are a few suggestions for further exploration:

• Experiment: Try implementing other design patterns like Decorator, Proxy, and Builder to expand your toolkit.

• Practice: Use these patterns to refactor existing projects and enhance their maintainability.

• Share: If you have any questions or want to share your experience, feel free to reach out!

I hope this guide has helped you understand how to effectively use design patterns in Java. Keep experimenting, and happy coding!

FGA allows you to set up detailed access controls that specify who can do what and under which conditions.

In this tutorial, you will learn how to implement fine-grained authorization in Java and Spring Boot using Permit.io.

Here is the source code (remember to give it a star ⭐).

I hope you enjoyed my previous blog about building a custom video conferencing app with Stream and Next.js. These blogs reflect my journey in creating DevTools Academy, a platform designed to help developers discover amazing developer tools.

This tutorial is another effort to introduce you to a super helpful developer tool that I recently explored.

Table of Contents:

• What is Permit?

• Prerequisites

• What is Fine-Grained Authorization?

  • Role-Based Access Control (RBAC)

  • Attribute-Based Access Control (ABAC)

  • Relationship-Based Access Control (ReBAC)

• How to Implement Fine-Grained Authorization

  • Implementing Role-Based Access Control

  • Implementing Attribute-Based Access Control

  • Implementing Relationship-Based Access Control

• How to Implement FGA in Java and SpringBoot

  • Step 1: Setting Up the E-commerce Application

  • Step 2: Get your Environment API Key

  • Step 3: Deploy Policy Decision Point (PDP)

  • Step 4: Running the App

• Next Steps

  • Before We End...

What is Permit?

Permit.io is a full stack, plug-and-play application-level authorization solution that allows you to implement a secure, flexible, authorization layer within minutes, so you can focus on what matters most.

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of Java and Spring Boot. You’ll also need the following:

• Permit.io: A developer tool that simplifies the implementation of FGA.

• Spring Boot Starter Web: Provides essential components for building web applications, including RESTful APIs.

• Gradle: A build tool for managing dependencies.

• JDK 11 or later: The Java Development Kit version required to compile and run your Spring Boot app.

• Postman or cURL: Tools for testing your API endpoints.

What is Fine-Grained Authorization?

Fine-grained authorization offers access control to resources by determining who can access them, to what extent, and under specified conditions.

Contrary to coarse-grained authorization (that handles access based on categories like user roles such as "admin" or "user"), fine-grained authorization gives you the flexibility to define access at a granular level, for specific resources or actions and even attributes.

In Fine Grained Authorization there exist 3 types of policy models for managing authorization; Role Based Access Control (RBAC), Attribute Based Access Control (ABAC), and Relationship-Based Access Control (ReBAC).

Let's take a look, at each of these approaches and see how you can implement them in your application.

Role-Based Access Control (RBAC)

RBAC is a security approach that controls resource access based on the roles of users within an organization. This model streamlines permissions by organizing users into roles and managing access control according to these defined roles.

Key Concepts in RBAC:

Users: People who use the system such as employees or customers.

Roles: A set of permissions or access privileges assigned to a group of users based on their responsibilities or tasks such as admin, manager, or customer.

Permissions: The rights granted to users for interacting with resources, such as read, write, or delete.

Attribute-Based Access Control (ABAC)

ABAC is a versatile and adaptive access control model that decides who can or cannot access resources based on attributes, like user details. The ABAC model allows you to define fine-grained authorization based on user attributes.

Key Concepts in ABAC:

Attributes: Characteristics or properties used to make access control decisions. Attributes are typically categorized into:

• User Attributes: Information about the user (for example, role, department, job title, age, and so on).

• Resource Attributes: Characteristics of the resource (for example, file type, data classification level, creation date, owner).

• Action Attributes: The action the user is trying to perform (for example, read, write, delete, approve).

• Environmental Attributes: Contextual information about the access request (for example, time of day, location, device type, IP address).

Relationship-Based Access Control (ReBAC)

ReBAC is an access control system that grants permissions to access resources based on the relationship between entities within a system. The approach emphasizes defining and managing access control by mapping out how users relate to resources and other entities such as organizations or groups.

Key Concepts of ReBAC:

Entities: Users, resources (such as files and documents), and other entities, such as groups or organizational units.

Relationships: The connections that specify the relationship between two entities. A user might be the "owner" of a document or a "member" of a team, for instance.

Policies: Rules that use relationships to determine access rights. A user can access a resource or execute an action on it if they have a particular relationship with it.

How to Implement Fine-Grained Authorization

Now that you have a basic understanding of RBAC, ABAC, and ReBAC, let’s see how we can implement these models in an e-commerce app.

Implementing Role-Based Access Control

Step 1: Navigate to Permit.io, and then create an account and your workspace.

By default, you should see a project that includes two environments: Development and Production.

Step 2: Create a resource named Products. To create the resource, open the Policy tab on the left sidebar and then open the Resources tab at the top. After that, click the Create a Resource button and then create a resource called Products with actions read, create, update, and delete.

Step 3: Create another resource called Reviews with actions read, create, update, and delete.

Step 4: Open the Policy Editor tab. You’ll see that 3 roles named admin, editor, and viewer were created.

• Role admin has permission to create, delete, read, or update a product or a review.

• Role editor has permission to create, read, or update a product or a review but not delete any.

• Role viewer has permission to create and read a product or a review but not delete or update any.

Implementing Attribute-Based Access Control

Step 1: Open the Resources tab, then click the Add Attributes button.

• Add an attribute called vendor

• Add an attribute called the customer

Step 2: Open the ABAC Rules tab, then create a new ABAC Resource Set called Own Products that depends on the Products resource. After that, add a condition that gives permissions only to the user who created a product based on the vendor attribute.

Step 3: Create another ABAC Resource Set called Own Reviews that depends on the Reviews resource.

Implementing Relationship-Based Access Control

Step 1: Open the Resources tab and edit the Products resource. Add role vendor in the ReBAC options section. Then set products as parent of reviews in the relations section.

Step 2: Edit the Reviews resource by adding role customer in the ReBAC options section, as shown below:

Step 3: Go to Policy Editor tab and add:

• role vendor permission to update and delete own products.

• role customer permission to update and delete their own reviews on products.

How to Implement FGA in Java and SpringBoot

Now that we have defined RBAC, ABAC, and ReBAC policies in the Permit.io web interface, let’s learn how to enforce them in an E-Commerce Management System application using the Permit.io API.

There’s a lot of code coming up, so make sure you read through the extensive comments I’ve left throughout each code block. These will help you understand more fully what’s going on in this code.

Step 1: Setting Up the E-commerce Application

To set up the e-commerce application and git clone the source code.

git clone https://github.com/tyaga001/java-spring-fine-grained-auth.git

Installing Permit package SDK

To install the Permit package SDK, you add the SDK under the dependencies block in the build.graddle file.

## Dependencies

To set up the necessary dependencies for your Spring Boot project, include the following in your `build.gradle` file:

```groovy
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    // Add this line to install the Permit.io Java SDK in your project
    implementation 'io.permit:permit-sdk-java:2.0.0'
}

Initializing the Permit SDK

You can initialize the Permit SDK Client using the code below:

package com.boostmytool.store.config;

import io.permit.sdk.Permit;
import io.permit.sdk.PermitConfig;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration  // Marks this class as a configuration class for Spring IoC
public class PermitClientConfig {

    @Value("${permit.api-key}")  // Inject Permit API key from application properties
    private String apiKey;

    @Value("${permit.pdp-url}")  // Inject Permit PDP (Policy Decision Point) URL from application properties
    private String pdpUrl;

    /**
     * Creates a Permit client bean with custom configuration
     * @return Permit client instance
     */
    @Bean
    public Permit permit() {
        return new Permit(
                new PermitConfig.Builder(apiKey)  // Initialize PermitConfig with API key
                        .withPdpAddress(pdpUrl)   // Set the PDP address
                        .withDebugMode(true)      // Enable debug mode for detailed logging
                        .build()                  // Build the PermitConfig object
        );
    }
}

Syncing Users with SDK

To start enforcing permissions, you should first sync a user to Permit, and then assign them a role.

In the code below, the UserService class provides methods for user login, signup, role assignment, and authorization, with exception handling for possible errors when interacting with the Permit API.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ForbiddenAccessException;
import com.boostmytool.store.exception.UnauthorizedException;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import org.springframework.stereotype.Service;

import java.io.IOException;

@Service  // Marks this class as a Spring service, making it a candidate for component scanning
public class UserService {
    private final Permit permit;

    // Constructor injection for the Permit SDK
    public UserService(Permit permit) {
        this.permit = permit;
    }

    /**
     * Simulates user login by creating and returning a Permit User object.
     * 
     * @param key User's unique key
     * @return User object
     */
    public Object login(String key) {
        return new User.Builder(key).build();
    }

    /**
     * Handles user signup by creating and syncing a new Permit User.
     * 
     * @param key User's unique key
     * @return Created and synced User object
     */
    public User signup(String key) {
        var user = new User.Builder(key).build();
        try {
            permit.api.users.sync(user);  // Syncs the new user with the Permit service
        } catch (PermitContextError | PermitApiError | IOException e) {
            throw new RuntimeException("Failed to create user", e);  // Handles exceptions during user creation
        }
        return user;
    }

    /**
     * Assigns a role to the user within the "default" environment.
     * 
     * @param user User object to assign the role to
     * @param role Role to be assigned
     */
    public void assignRole(User user, String role) {
        try {
            permit.api.users.assignRole(user.getKey(), role, "default");  // Assigns role in the "default" environment
        } catch (PermitApiError | PermitContextError | IOException e) {
            throw new RuntimeException("Failed to assign role to user", e);  // Handles exceptions during role assignment
        }
    }

    /**
     * Checks if the user is authorized to perform a specific action on a resource.
     * 
     * @param user User object requesting authorization
     * @param action Action to be authorized
     * @param resource Resource on which the action will be performed
     * @throws UnauthorizedException if user is not logged in
     * @throws ForbiddenAccessException if user is denied access
     */
    public void authorize(User user, String action, Resource resource) {
        if (user == null) {
            throw new UnauthorizedException("Not logged in");  // Throws exception if user is not logged in
        }
        try {
            var permitted = permit.check(user, action, resource);  // Performs authorization check
            if (!permitted) {
                throw new ForbiddenAccessException("Access denied");  // Throws exception if access is denied
            }
        } catch (PermitApiError | IOException e) {
            throw new RuntimeException("Failed to authorize user", e);  // Handles exceptions during authorization
        }
    }
}

Then in the code below, the UserController class exposes REST API endpoints for user signup and role assignment. It interacts with the UserService class to handle user-related business logic and provides appropriate HTTP responses.

package com.boostmytool.store.controllers;

import com.boostmytool.store.exception.UnauthorizedException;
import com.boostmytool.store.service.UserService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController  // Indicates that this class handles HTTP requests and returns JSON responses
@RequestMapping("/api/users")  // Base URL path for all user-related operations
public class UserController {
    private final UserService userService;

    // Constructor injection of UserService, containing business logic for user operations
    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * Handles user signup requests.
     * Endpoint: POST /api/users/signup
     * 
     * @param key Unique key for the new user
     * @return Created User object
     */
    @PostMapping("/signup")
    public User signup(@RequestBody String key) {
        return userService.signup(key);  // Calls the signup method in UserService to create a new user
    }

    /**
     * Handles assigning a role to the logged-in user.
     * Endpoint: POST /api/users/assign-role
     * 
     * @param request HTTP request, used to retrieve the current user
     * @param role Role to be assigned to the current user
     */
    @PostMapping("/assign-role")
    public void assignRole(HttpServletRequest request, @RequestBody String role) {
        // Retrieves the current user from the request attributes
        User currentUser = (User) request.getAttribute("user");

        // Throws an exception if the user is not logged in
        if (currentUser == null) {
            throw new UnauthorizedException("Not logged in");
        }

        // Assigns the specified role to the current user
        userService.assignRole(currentUser, role);
    }
}

Creating RBAC, ABAC, and ReBAC Policy Enforcement Point

In the code below, the ProductService class manages CRUD operations for products and reviews, handling permissions and roles via the Permit API.

Each operation includes user authorization checks, with appropriate exception handling for Permit API errors and resource not found scenarios.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ResourceNotFoundException;
import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import io.permit.sdk.openapi.models.RelationshipTupleCreate;
import io.permit.sdk.openapi.models.ResourceInstanceCreate;
import io.permit.sdk.openapi.models.RoleAssignmentCreate;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;

@Service  // Marks this class as a Spring service
public class ProductService {

    private final List<Product> products = new ArrayList<>();  // In-memory list to store products
    private final AtomicInteger productIdCounter = new AtomicInteger();  // Counter to generate unique product IDs
    private final AtomicInteger reviewIdCounter = new AtomicInteger();   // Counter to generate unique review IDs

    // Builders for Permit resource instances (product and review)
    private final Resource.Builder productResourceBuilder = new Resource.Builder("product");
    private final Resource.Builder reviewResourceBuilder = new Resource.Builder("review");

    private final UserService userService;  // Service for handling user-related operations
    private final Permit permit;  // Permit SDK instance for handling authorization and resource management

    // Constructor for injecting dependencies
    public ProductService(UserService userService, Permit permit) {
        this.userService = userService;
        this.permit = permit;
    }

    // Method to authorize a user for a given action on a resource
    private void authorize(User user, String action, Resource resource) {
        userService.authorize(user, action, resource);
    }

    // Authorizes a user to perform an action on a specific product
    private void authorize(User user, String action, Product product) {
        var attributes = new HashMap<String, Object>();
        attributes.put("vendor", product.getVendor());  // Add vendor attribute to the product
        userService.authorize(user, action, productResourceBuilder.withKey(product.getId().toString()).withAttributes(attributes).build());
    }

    // Authorizes a user to perform an action on a specific review
    private void authorize(User user, String action, Review review) {
        var attributes = new HashMap<String, Object>();
        attributes.put("customer", review.getCustomer());  // Add customer attribute to the review
        userService.authorize(user, action, reviewResourceBuilder.withKey(review.getId().toString()).withAttributes(attributes).build());
    }

    // Retrieves a product by its ID, throws an exception if not found
    private Product getProductById(int id) {
        return products.stream().filter(product -> product.getId().equals(id))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Product with id " + id + " not found"));
    }

    // Retrieves all products, checks if the user is authorized to "read" products
    public List<Product> getAllProducts(User user) {
        authorize(user, "read", productResourceBuilder.build());  // User must have "read" permission
        return new ArrayList<>(products);  // Return a copy of the products list
    }

    // Retrieves a product by its ID, checks if the user is authorized to "read" the product
    public Product getProduct(User user, int id) {
        authorize(user, "read", productResourceBuilder.build());
        return getProductById(id);
    }

    // Adds a new product, authorizes the user and creates resource instances and role assignments in Permit
    public Product addProduct(User user, String content) {
        authorize(user, "create", productResourceBuilder.build());  // Check if user can create a product
        Product product = new Product(productIdCounter.incrementAndGet(), user.getKey(), content);  // Create new product

        try {
            // Create resource instance in Permit and assign "vendor" role to the user for this product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(product.getId().toString(), "product").withTenant("default"));
            permit.api.roleAssignments.assign(new RoleAssignmentCreate("vendor", user.getKey()).withResourceInstance("product:" + product.getId()).withTenant("default"));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException("Failed to create resource instance or role assignment: " + e.getMessage());
        }

        products.add(product);  // Add product to in-memory list
        return product;
    }

    // Updates a product's content, checks if the user is authorized to "update" the product
    public Product updateProduct(User user, int id, String content) {
        Product product = getProductById(id);  // Get the product by its ID
        authorize(user, "update", product);  // Check if user can update the product
        product.setContent(content);  // Update product content
        return product;
    }

    // Deletes a product, checks if the user is authorized to "delete" the product
    public void deleteProduct(User user, int id) {
        boolean isDeleted = products.removeIf(product -> {
            if (product.getId().equals(id)) {
                authorize(user, "delete", product);  // Check if user can delete the product
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Product with id " + id + " not found");
        }

        try {
            permit.api.resourceInstances.delete("product:" + id);  // Remove product resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }

    // Adds a review to a product, creates a resource instance and relationship in Permit
    public Review addReview(User user, int productId, String content) {
        authorize(user, "create", reviewResourceBuilder.build());  // Check if user can create a review
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = new Review(reviewIdCounter.incrementAndGet(), user.getKey(), content);  // Create new review

        try {
            // Create a resource instance for the review and set relationship with the product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(review.getId().toString(), "review").withTenant("default"));
            permit.api.relationshipTuples.create(new RelationshipTupleCreate("product:" + productId, "parent", "review:" + review.getId()));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }

        product.addReview(review);  // Add the review to the product
        return review;
    }

    // Updates a review's content, checks if the user is authorized to "update" the review
    public Review updateReview(User user, int productId, int reviewId, String content) {
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = product.getReviews().stream().filter(c -> c.getId().equals(reviewId))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Review with id " + reviewId + " not found"));

        authorize(user, "update", review);  // Check if user can update the review
        review.setContent(content);  // Update review content
        return review;
    }

    // Deletes a review, checks if the user is authorized to "delete" the review
    public void deleteReview(User user, int productId, int reviewId) {
        Product product = getProductById(productId);  // Get the product by its ID
        boolean isDeleted = product.getReviews().removeIf(review -> {
            if (review.getId().equals(reviewId)) {
                authorize(user, "delete", review);  // Check if user can delete the review
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Review with id " + reviewId + " not found");
        }

        try {
            permit.api.resourceInstances.delete("review:" + reviewId);  // Remove review resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }
}

Then in the code below, the ProductController class handles HTTP requests related to products and their reviews. It exposes endpoints for managing products (like creating, updating, deleting, and retrieving) and for managing product reviews.

package com.boostmytool.store.controllers;

import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import com.boostmytool.store.service.ProductService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController  // Indicates that this class is a Spring REST controller
@RequestMapping("/api/products")  // Base URL for all endpoints in this controller
public class ProductController {

    private final ProductService productService;  // ProductService instance to handle product-related operations

    @Autowired  // Autowires ProductService bean automatically
    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    // GET request to retrieve all products
    @GetMapping
    public List<Product> getAllProducts(HttpServletRequest request) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getAllProducts(currentUser);  // Calls ProductService to get all products for the user
    }

    // GET request to retrieve a product by its ID
    @GetMapping("/{id}")
    public Product getProductById(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getProduct(currentUser, id);  // Calls ProductService to get the product by ID for the user
    }

    // POST request to add a new product
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Sets the response status to 201 (Created)
    public Product addProduct(HttpServletRequest request, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addProduct(currentUser, content);  // Calls ProductService to add a new product
    }

    // PUT request to update an existing product by its ID
    @PutMapping("/{id}")
    public Product updateProduct(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateProduct(currentUser, id, content);  // Calls ProductService to update the product by ID
    }

    // DELETE request to delete a product by its ID
    @DeleteMapping("/{id}")
    public String deleteProduct(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteProduct(currentUser, id);  // Calls ProductService to delete the product by ID
        return "Deleted product with id " + id;  // Returns a success message after deletion
    }

    // POST request to add a new review to a product by product ID
    @PostMapping("/{id}/review")
    public Review addReview(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addReview(currentUser, id, content);  // Calls ProductService to add a review to the product
    }

    // PUT request to update an existing review by product and review ID
    @PutMapping("/{id}/review/{reviewId}")
    public Review updateReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateReview(currentUser, id, reviewId, content);  // Calls ProductService to update the review
    }

    // DELETE request to delete a review by product and review ID
    @DeleteMapping("/{id}/review/{reviewId}")
    public String deleteReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteReview(currentUser, id, reviewId);  // Calls ProductService to delete the review
        return "Deleted review with id " + reviewId + " from product " + id;  // Returns a success message after deletion
    }
}

Step 2: Get your Environment API Key

In the UI Dashboard, copy the Environment API Key of the active environment.

Then add the env API key and PDP URL in the application.yaml file.

permit:
  pdpUrl: 'http://localhost:7766'
  apiKey: "Your Permit environment API Key"

Step 3: Deploy Policy Decision Point (PDP)

The Policy Decision Point (PDP) is deployed in your VPC and is in charge of evaluating your authorization requests. The PDP will ensure zero latency, great performance, high availability, and improved security.

Use the command below to pull the Permit.io PDP container from Docker Hub.

docker pull permitio/pdp-v2:latest

Then run the container.

docker run -it -p 7766:7000 --env PDP_DEBUG=True --env PDP_API_KEY=<YOUR_API_KEY> permitio/pdp-v2:latest

Step 4: Running the App

You can run the application using the following Gradle command:

./gradlew bootRun

Viewing and Creating Products

Let’s now interact with the application endpoints using REQBIN.

First, create a new user using the /api/users/signup endpoint.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'johndoe'

You should be able to view the user in your Permit project, under Directory > All Tenants.

Initially, the user has no roles, so it cannot do much. For example, trying to list the products will result in a 403 Forbidden response, as shown below. The 403 error code means the user doesn’t have permissions to access the requested resource, which is products in this case. You can learn more about the difference between 401 and 403 error codes here.

For the user to view a list of products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer johndoe" \
-H "Content-Type: application/json" \
-d 'viewer'

You should see that user johndoe was assigned role viewer, as shown below:

Since a viewer can create a product, use the command below to create a product with user johndoe.

curl -X POST "http://localhost:8080/api/products" -H "Authorization: Bearer johndoe" -H "Content-Type: application/json" -d 'MacBook'

You should see that a new product is created with ID 1 and that the user johndoe has been added as the vendor.

Adding Reviews To Products

To add reviews to products, create another user called jane.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'jane'

For the user to add a review to products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer jane" \
-H "Content-Type: application/json" \
-d 'viewer'

Then you can add a review to the product added by johndoe using the command below:

curl -X POST "http://localhost:8080/api/products/1/review" -H "Authorization: Bearer jane" -H "Content-Type: application/json" -d 'The product was in good quality'

Congratulations! You’ve completed the project for this tutorial.

Next Steps

Now that you've learned how to implement fine-grained authorization in your Java and Spring Boot applications using Permit.io, you might want to explore further.

Here are some valuable resources:

• Permit.io docs

• RBAC VS ABAC: Choosing the Right Authorization Policy Model

Before We End

I hope you found this tutorial insightful.

Here are some of my other recent blog posts that you might enjoy:

• Learn React – A Guide to the Key Concepts

• Neon Postgres vs Supabase

• Full Stack Development with Next.js, Clerk, and Neon Postgres

For more tutorials on amazing developer tools, be sure to check out my blog DTA.

Follow me on Twitter to get live updates on my other projects.

Happy coding.

In this tutorial, we’ll build a chatbot application using Spring Boot, React, Docker, and OpenAI. This app will let users interact with an AI-powered chatbot, ask questions, and receive responses in real time.

The entire source code mentioned in this article is already available on the GitHub repository. Feel free to give it a star and fork it to play around.

To give you an idea of what we’ll be building here, this is how the final application will look:

Are you excited? Let’s build it from scratch!

Table of Contents

• Prerequisites

• Get Your OpenAI key

• Build the REST API in Spring Boot

• Build the ChatUI using Reactjs

• How to Dockerize the Application

• Run the Application

• Congratulations 🎉

Prerequisites

Before we dive into building the chatbot, here are a few things you’ll need to be familiar with:

1. Basic understanding of Java and Spring Boot.

2. Basic understanding of React and CSS.

3. Install JDK, Node Package Manager and Docker onto your machine.

Get Your OpenAI key

First, you’ll need to sign up for an OpenAI account if you don’t have one. Once signed in, you’ll be taken to the homepage.

In the top right corner, click the “Dashboard” menu. On the sidebar, click "API Keys," then click the "Create new secret key" button to generate your secret key:

Copy the secret key and save it somewhere safe, as you’ll need it later to connect your app to the OpenAI API.

You can go through the OpenAI API reference guide to learn more about how to call the APIs, what requests it accepts, and the responses it gives.

Build the REST API in Spring Boot

Let’s head over to the spring initializer to generate the boilerplate code:

You can give the group, artifact, name, description, and package you choose. We’ve used Maven as the built tool, Spring boot version 3.3.3, Jar as a packaging option, and Java version 17.

Hit the generate button and the zip will be downloaded. Unzip the files and import them as a Maven project into your favourite IDE (mine is Intellij).

Configure your OpenAI key in Spring

You can either use the existing application.properties file or create a application.yaml file. I love working with Yaml, so created a application.yaml file where I can place all my Spring Boot configurations.

Add the OpenAIKey, Model, and Temperature to your application.yaml file:

spring:
  ai:
    openai:
      chat:
        options:
          model: "gpt-3.5-turbo"
          temperature: "0.7"
      key: "PUT YOUR OPEN_API_KEY HERE"

A similar configuration in application.properties may look like as follows:

spring.ai.openai.chat.options.model=gpt-3.5-turbo
spring.ai.openai.chat.options.temperature=0.7
spring.ai.openai.key="PUT YOUR OPEN_API_KEY HERE"

Build the ChatController

Let’s create a GET API with the URL /ai/chat/string and a method to handle the logic:

@RestController
public class ChatController {

    @Autowired
    private final OpenAiChatModel chatModel;

    @GetMapping("/ai/chat/string")
    public Flux<String> generateString(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return chatModel.stream(message);
    }
}

• First, we’re adding @RestController to mark the ChatController class as our spring controller

• Then, we’re injecting the dependency for the OpenAiChatModel class. It comes out of the box as part of the Spring AI dependency we’ve used.

• The OpenAiChatModel comes with a method stream(message) which accepts the prompt as String and returns a String response (technically it’s a Flux of String as we’ve used a Reactive version of the same method).

• Internally, OpenAiChatModel.stream(message) will call the OpenAI API and fetch the response from there. The OpenAI call will use the configuration steps mentioned in your application.yaml file, so make sure to use a valid OpenAI key.

• We’ve created a method to handle the GET API call, which accepts the message and returns Flux<String> as the response.

Build, Run, and Test the REST API

Use the maven commands to build and run the Spring Boot application:

./mvnw clean install spring-boot:run

Ideally, it will run on a 8080 port unless you’ve customized the port. Make sure to keep that port free to successfully run the application.

You can either use Postman or the Curl command to test your REST API:

curl --location 'http://localhost:8080/ai/chat/string?message=How%20are%20you%3F'

Build the ChatUI using React.js

We will be making it super simple and easy for the sake of this tutorial, so pardon me if I don’t follow any React best practices.

Create App.js to Manage the ChatUI Form

We’ll be using useState to manage the state:

const [messages, setMessages] = useState([]);
const [input, setInput] = useState('');
const [loading, setLoading] = useState(false);

• messages: It will store all the messages in the chat. Each message has a text and a sender (either 'user' or 'ai').

• input: To hold what the user is typing in the text box.

• loading: This state is set to true while the chatbot is waiting for a response from the AI, and false when the response is received.

Let’s create a function handleSend and call it when the user sends a message by clicking a button or pressing Enter:

const handleSend = async () => {
    if (input.trim() === '') return;

    const newMessage = { text: input, sender: 'user' };
    setMessages([...messages, newMessage]);
    setInput('');
    setLoading(true);

    try {
        const response = await axios.get('http://localhost:8080/ai/chat/string?message=' + input);
        const aiMessage = { text: response.data, sender: 'ai' };
        setMessages([...messages, newMessage, aiMessage]);
    } catch (error) {
        console.error("Error fetching AI response", error);
    } finally {
        setLoading(false);
    }
};

Here’s what happens step by step:

• Check empty input: If the input field is empty, the function returns early (nothing is sent).

• New message from the user: A new message is added to the messages array. This message has the text (whatever the user typed) and is marked as being sent by the 'user'.

• Reset input: The input field is cleared after the message is sent.

• Start loading: While waiting for the AI to respond, loading is set to true to show a loading indicator.

• Make API request: The code is used axios to request the AI chatbot API, passing the user's message. When the response comes back, a new message from the AI is added to the chat.

• Error handling: If there is a problem getting the AI’s response, an error is logged to the console.

• Stop loading: Finally, the loading state is turned off.

Let’s write a function to update the input state whenever the user types something in the input field:

const handleInputChange = (e) => {
    setInput(e.target.value);
};

Next, let’s create a function to check if the user presses the Enter key. If they do, it calls handleSend() to send the message:

const handleKeyPress = (e) => {
    if (e.key === 'Enter') {
        handleSend();
    }
};

Now let’s create UI elements to render the chat messages:

{messages.map((message, index) => (
    <div key={index} className={`message-container ${message.sender}`}>
        <img
            src={message.sender === 'user' ? 'user-icon.png' : 'ai-assistant.png'}
            alt={`${message.sender} avatar`}
            className="avatar"
        />
        <div className={`message ${message.sender}`}>
            {message.text}
        </div>
    </div>
))}

This block renders all the messages in the chat:

• Mapping through messages: Each message is displayed as a div using .map().

• Message styling: The class name of the message changes based on who the sender is (user or ai), making it clear who sent the message.

• Avatar images: Each message shows a small avatar, with a different image for the user and the AI.

Let’s create some logic to show the loader based on a flag:

{loading && (
    <div className="message-container ai">
        <img src="ai-assistant.png" alt="AI avatar" className="avatar" />
        <div className="message ai">...</div>
    </div>
)}

While the AI is thinking (when loading is true), we show a loading message (...) so the user knows a response is coming soon.

At last, create a button to click the message send button:

<button onClick={handleSend}>
    <FaPaperPlane />
</button>

This button triggers the handleSend() function when clicked. The icon used here is a paper plane, which is common for "send" buttons.

The full Chatbot.js looks as below:

import React, { useState } from 'react';
import axios from 'axios';
import { FaPaperPlane } from 'react-icons/fa';
import './Chatbot.css';

const Chatbot = () => {
    const [messages, setMessages] = useState([]);
    const [input, setInput] = useState('');
    const [loading, setLoading] = useState(false);

    const handleSend = async () => {
        if (input.trim() === '') return;

        const newMessage = { text: input, sender: 'user' };
        setMessages([...messages, newMessage]);
        setInput('');
        setLoading(true);

        try {
            const response = await axios.get('http://localhost:8080/ai/chat/string?message=' + input);
            const aiMessage = { text: response.data, sender: 'ai' };
            setMessages([...messages, newMessage, aiMessage]);
        } catch (error) {
            console.error("Error fetching AI response", error);
        } finally {
            setLoading(false);
        }
    };

    const handleInputChange = (e) => {
        setInput(e.target.value);
    };

    const handleKeyPress = (e) => {
        if (e.key === 'Enter') {
            handleSend();
        }
    };

    return (
        <div className="chatbot-container">
            <div className="chat-header">
                <img src="ChatBot.png" alt="Chatbot Logo" className="chat-logo" />
                <div className="breadcrumb">Home &gt; Chat</div>
            </div>
            <div className="chatbox">
                {messages.map((message, index) => (
                    <div key={index} className={`message-container ${message.sender}`}>
                        <img
                            src={message.sender === 'user' ? 'user-icon.png' : 'ai-assistant.png'}
                            alt={`${message.sender} avatar`}
                            className="avatar"
                        />
                        <div className={`message ${message.sender}`}>
                            {message.text}
                        </div>
                    </div>
                ))}
                {loading && (
                    <div className="message-container ai">
                        <img src="ai-assistant.png" alt="AI avatar" className="avatar" />
                        <div className="message ai">...</div>
                    </div>
                )}
            </div>
            <div className="input-container">
                <input
                    type="text"
                    value={input}
                    onChange={handleInputChange}
                    onKeyPress={handleKeyPress}
                    placeholder="Type your message..."
                />
                <button onClick={handleSend}>
                    <FaPaperPlane />
                </button>
            </div>
        </div>
    );
};

export default Chatbot;

Use <Chatbot/> inside the App.js to load the Chatbot UI:

function App() {
  return (
    <div className="App">
            <Chatbot />
        </div>
  );
}

Along with this, we’re also using CSS to make our chatbot a little more beautiful. You can refer to App.css and Chatbot.css for that.

Run the Frontend

Use the npm command to run the application:

npm start

This should run the frontend on the URL http://localhost:3000. The application is good to be tested now.

But running the backend and frontend separately is a bit of a hassle. So let’s use Docker to make the entire build process easier.

How to Dockerize the Application

Let’s dockerize the entire application to help bundle and ship it anywhere hassle-free. You can install and configure Docker from the official Docker website.

Dockerize the Backend

The backend of our chatbot is built with Spring Boot, so we will create a Dockerfile that builds the Spring Boot app into an executable JAR file and runs it in a container.

Let’s write the Dockerfile for it:

# Start with an official image that has Java installed
FROM openjdk:17-jdk-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy the Maven/Gradle build file and source code into the container
COPY target/chatbot-backend.jar /app/chatbot-backend.jar

# Expose the application’s port
EXPOSE 8080

# Command to run the Spring Boot app
CMD ["java", "-jar", "chatbot-backend.jar"]

• FROM openjdk:17-jdk-alpine: This specifies that the container should be based on a lightweight Alpine Linux image that includes JDK 17, which is needed to run Spring Boot.

• WORKDIR /app: Sets the working directory inside the container to /app, where our application files will live.

• COPY target/chatbot-backend.jar /app/chatbot-backend.jar: Copies the built JAR file from your local machine (usually in the target folder after building the project with Maven or Gradle) into the container.

• EXPOSE 8080: This tells Docker that the application will listen for requests on port 8080.

• CMD ["java", "-jar", "chatbot-backend.jar"]: This specifies the command that will run when the container starts. It runs the JAR file that launches the Spring Boot app.

Dockerize the Frontend

The front end of our chatbot is built using React, and we can Dockerize it by creating a Dockerfile that installs the necessary dependencies, builds the app, and serves it using a lightweight web server like NGINX.

Let’s write the Dockerfile for the React frontend:

# Use a Node image to build the React app
FROM node:16-alpine AS build

# Set the working directory inside the container
WORKDIR /app

# Copy the package.json and install the dependencies
COPY package.json package-lock.json ./
RUN npm install

# Copy the rest of the application code and build it
COPY . .
RUN npm run build

# Use a lightweight NGINX server to serve the built app
FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html

# Expose port 80 for the web traffic
EXPOSE 80

# Start NGINX
CMD ["nginx", "-g", "daemon off;"]

• FROM node:16-alpine AS build: This uses a lightweight Node.js image to build the React app. We install all dependencies and build the app inside this container.

• WORKDIR /app: Sets the working directory inside the container to /app.

• COPY package.json package-lock.json ./: Copies package.json and package-lock.json to install dependencies.

• RUN npm install: Installs the dependencies listed in the package.json.

• COPY . .: Copies all the frontend source code into the container.

• RUN npm run build: Builds the React application. The built files will be in a build folder.

• FROM nginx:alpine: After building the app, this line starts a new container based on the nginx web server.

• COPY --from=build /app/build /usr/share/nginx/html: Copies the built React app from the first container into the nginx container, placing it in the default folder where NGINX serves files.

• EXPOSE 80: This exposes port 80, which NGINX uses to serve web traffic.

• CMD ["nginx", "-g", "daemon off;"]: This starts the NGINX server in the foreground to serve your React app.

Docker Compose to Run Both

Now that we have separate Dockerfiles for the frontend and backend, we’ll use docker-compose to orchestrate running both containers at once.

Let’s write the docker-compose.yml file inside the root directory of the project:

version: '3'
services:
  backend:
    build: ./backend
    ports:
      - "8080:8080"
    networks:
      - chatbot-network

  frontend:
    build: ./frontend
    ports:
      - "3000:80"
    depends_on:
      - backend
    networks:
      - chatbot-network

networks:
  chatbot-network:
    driver: bridge

• version: '3': This defines the version of Docker Compose being used.

• services:: This defines the services we want to run.

  • backend: This service builds the backend using the Dockerfile located in the ./backend directory and exposes port 8080.

  • frontend: This service builds the front end using the Dockerfile located in the ./frontend directory. It maps port 3000 on the host to port 80 inside the container.

• depends_on:: This makes sure the front end waits for the backend to be ready before it starts.

• networks:: This section defines a shared network so that both the backend and frontend can communicate with each other.

Run the Application

To run the entire application (both frontend and backend), you can use the following command:

docker-compose up --build

This command will:

• Build both the frontend and backend images.

• Start both containers (backend on port 8080, frontend on port 3000).

• Set up networking so that both services can communicate.

Now, you can head over to http://localhost:3000 load the Chatbot UI and start asking your questions to the AI.

Congratulations 🎉

You’ve successfully built a full-stack chatbot application using Spring Boot, React, Docker, and OpenAI.

The source code shown in the project is available on Github, if you found it helpful give it a star, and feel free to fork it and play around with it.

Course Overview

This course is perfect for developers looking to deepen their understanding of Spring Boot and Spring Security. You'll start from scratch, generating a new project, and progress through creating and mapping entity classes, implementing CRUD operations, and developing services and controllers for products, categories, and carts. By the end of the course, you'll have a robust backend application and a solid grasp of key Spring technologies.

Here are the key technologies featured int his coruse.

Spring Boot: Spring Boot is a powerful framework that simplifies the process of building production-ready applications. It provides a range of features, including auto-configuration and an embedded server, which help streamline the development process. In this course, you'll learn how to leverage Spring Boot to quickly set up and manage your shopping cart backend.

Spring Security: Security is a critical aspect of any application, and Spring Security is a comprehensive framework that addresses authentication and authorization concerns. You'll learn how to integrate Spring Security into your project, ensuring that your application is protected against common security threats.

JWT (JSON Web Tokens): JWT is a compact, URL-safe means of representing claims to be transferred between two parties. In this course, you'll discover how to use JWT for secure user authentication, allowing your application to verify user identities and manage sessions effectively.

Course Content Highlights

• Project Generation: Learn how to set up a new Spring Boot project and configure it for development.

• Entity Classes and CRUD Operations: Understand how to create and map entity classes, and implement CRUD operations for managing products, categories, and carts.

• Service and Controller Development: Develop robust services and controllers to handle business logic and API requests.

• Security Integration: Integrate Spring Security and JWT to secure your application, implementing user authentication and authorization.

• Testing and Debugging: Test your APIs and fix any errors to ensure your application runs smoothly.

• Project Wrap-Up: Clean up your project and conduct final security testing to ensure everything is in place.

Conclusion

By the end of this course, you'll have a comprehensive understanding of how to build a secure and efficient shopping cart backend using Spring Boot and Spring Security. Whether you're a beginner or an experienced developer, this course offers valuable insights and practical skills that you can apply to your projects.

Watch the full course on the freeCodeCamp.org YouTube channel (10-hour watch).