If you search for "install Java on Mac," you'll find a confusing number of vendors, version numbers, and installation methods. To make it easy, I'll cut through the confusion and show you a recommended Java installation path that takes about five minutes.

Here's my recommendation: Install Java 25 using Homebrew with the Eclipse Temurin distribution. Java 25 is the current LTS (Long-Term Support) release and your best choice unless your work team or university course uses an older version. With Homebrew, one terminal command accommodates the entire installation. The Temurin distribution is free, certified, and unencumbered by Oracle's licensing restrictions.

Now I’ll walk you through the process.

Table of Contents

1. What You Need Before You Begin

2. How to Check if Java Is Already Installed

3. Why Eclipse Temurin and Why Not Oracle

4. How to Install Java with Homebrew

5. How to Verify the Installation

6. How to Set JAVA_HOME for Build Tools

7. How to Troubleshoot Common Problems

8. Alternative Installation Methods

9. What's Next

What You Need Before You Begin

With this recommended path, you only need two things before you install Java: a terminal application and the Homebrew package manager.

Terminal

Terminal is the built-in Mac terminal application. If you don’t know, you can learn how to open Terminal here. You'll use it to run the installation commands.

Homebrew

Homebrew is a package manager you can use to install software programs for the command line. Check if you already have it like this:

$ brew --version
Homebrew 5.0.11

If you see a version number, you're ready. If you see zsh: command not found: brew you need to install Homebrew first. Follow the instructions at Install Homebrew.

How to Check if Java Is Already Installed

Run this command to check for an existing Java installation:

$ java -version

You'll see one of two results.

If Java is installed, you'll see output like this:

openjdk version "25.0.1" 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode)

If the version number shows 25, you already have the latest Java and you can stop here.

If Java is not installed, you'll see a message, "The operation couldn't be completed. Unable to locate a Java Runtime." You'll need to install Java as described below.

If you previously installed Java but see this dialog, something is wrong with your installation. See Unable to Locate a Java Runtime for troubleshooting. For detailed guidance on Java version output, see Check Java Version on Mac.

Why Eclipse Temurin and Why Not Oracle

If you search for Java downloads, you'll encounter several potentially confusing terms. Here's what they mean.

JDK stands for Java Development Kit. It contains the compiler, runtime, and developer tools you need to build and run Java applications. Vendors used to offer a JRE (Java Runtime Environment) for non-developers, but now the JDK does everything.

OpenJDK is the official open-source implementation of Java. All major Java vendors build from this same source code, so the core functionality is identical across vendors.

Eclipse Temurin is the distribution many developers recommend. It comes from the Adoptium project and is backed by IBM, Microsoft, Red Hat, and Google, among others. It's completely free for any use, including commercial production. Temurin is TCK-certified, meaning it passes Oracle's official compatibility tests (over 139,000 of them). You can trust that your Java code will run correctly.

Why not Oracle JDK? Oracle changed its licensing in January 2023. The new model charges per employee across the entire organization, not per Java user. A 500-person company would pay $90,000 per year. Oracle actively audits for compliance.

Temurin is functionally identical to Oracle JDK and is free to use under its open‑source license, avoiding Oracle’s Java subscription fees.

If you deploy to AWS, Amazon Corretto is another good free option. If you need Java 8 for legacy code, Azul Zulu provides well-supported builds. For a comparison of Java distributions, see Install JDK on Mac.

How to Install Java with Homebrew

Homebrew offers two ways to install Java: the cask method and the formula method. The cask method is easier because it installs the vendor's macOS package to the standard system location. Apple's macOS discovers it automatically with no extra configuration.

Run these two commands:

$ brew update
$ brew install --cask temurin@25

The first command refreshes Homebrew's package list. The second downloads and installs Eclipse Temurin JDK 25.

Homebrew places the JDK at /Library/Java/JavaVirtualMachines/temurin-25.jdk/. This is the standard macOS location for Java installations. Apple's macOS includes a Java launcher at /usr/bin/java that automatically searches this directory. You don't need to configure your PATH.

Homebrew also detects your Mac's chip architecture automatically. You'll get the correct native build whether you have an Apple Silicon or Intel Mac.

For more details about the Homebrew installation process, including the alternative formula method and troubleshooting, see Brew Install Java, Cask Method.

How to Verify the Installation

After installation, open a new Terminal window. Existing windows may not detect the new installation.

Check the Java version:

$ java -version
openjdk version "25.0.1" 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode)

This confirms three things: the version number (25.0.1), the distribution (Temurin), and that the 64-Bit Server VM is active.

Check the compiler:

$ javac -version
javac 25.0.1

List all installed JDKs:

$ /usr/libexec/java_home -V
Matching Java Virtual Machines (1):
    25.0.1 (arm64) "Eclipse Adoptium" - "OpenJDK 25.0.1" /Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home

If all three commands produce the expected output, Java is installed and working.

How to Set JAVA_HOME for Build Tools

For most users, Java works immediately after installation. The java and javac commands are available with no additional setup.

However, some build tools require the JAVA_HOME environment variable. Apache Maven, Gradle, and Android SDK all look for it. If you see errors mentioning "JAVA_HOME is not set," you need this step.

If you only run Java applications or use IntelliJ IDEA (which manages Java paths internally), you can skip this section.

Add this line to your ~/.zprofile file:

export JAVA_HOME=$(/usr/libexec/java_home)

This uses Apple's java_home utility to find the installed JDK automatically. After saving the file, you'll need to run source ~/.zprofile or close and reopen your terminal. Verify it works:

\( echo \)JAVA_HOME
/Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home

For complete configuration instructions, see Set JAVA_HOME on Mac.

How to Troubleshoot Common Problems

"Unable to locate a Java Runtime" message keeps appearing. Run java -version to verify Java is installed. If you just installed Java, see Unable to Locate a Java Runtime.

Wrong Java version appears. You have multiple JDKs installed and macOS selected a different one. Run /usr/libexec/java_home -V to list all installed versions. See Set JAVA_HOME on Mac to point to the version you want.

Alternative Installation Methods

Homebrew is the fastest path, but other options exist.

1. Manual download: You can download the .pkg installer directly from adoptium.net and double-click to install. This is a good choice if you don't use Homebrew. See Install Java on Mac for detailed instructions.

2. Homebrew formula. The command brew install openjdk@25 installs a Homebrew-managed build. This approach requires manual symlink configuration before macOS can discover it. See Brew Install Java, Formula Method for details.

3. Version managers. Tools like SDKMAN and mise can install and switch between multiple Java versions per project. If you work on codebases that require different Java versions, see Java Version Managers.

What's Next

You now have Java 25 installed on your Mac. You've verified it works and configured JAVA_HOME for build tools. You're ready to compile and run Java applications.

If your team or university course requires Java 21 instead, see Install Java 21 on Mac. If you need to remove Java, see Uninstall Java on Mac.

This article is based on my guides that offer additional details about how to install Java on Mac and choose the latest Java version.

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.​

SQLite powers more applications than you might think. It's in every smartphone, most web browsers, and countless desktop applications. Your phone probably has hundreds of SQLite databases on it right now. Despite handling billions of databases worldwide, many developers aren't familiar with all of the cool things that you can do with SQLite.

This tutorial introduces SQLite through practical examples in C/C++, Python, and Java. You can pick and choose the languages that suit your needs. No language wars here. You'll learn how to integrate SQLite into real applications. Whether you're building a desktop app, a web API, or just need local data storage without the drama of a full database server, SQLite has your back.

Code Playbacks

Code playbacks are a unique way to learn about programming. They are guided walkthroughs of code, allowing you to see not just the code itself but also the thought process behind it. This approach helps you understand not only what the code does, but why it was written that way. Here is a short video to show how to move through a code playback:

By registering on Playback Press, you'll gain access to an AI assistant that can answer your questions about the code. This makes learning even more interactive and personalized. Watch this video to see how to work with it:

A Brief Introduction to SQLite

You can find my entire collection of SQLite code playbacks in my free book, "Programming with SQLite".

Here's what you'll learn:

Chapter 1: Database Design and SQL

In this chapter, I cover the basics of relational database design and SQL. I keep it simple and practical. If you'd like more introductory SQL content like this go to my Intro SQL book. If you'd like some SQL problems to work through, check out 30 Worked SQL Examples. If you already dream in SELECT statements, skip ahead to the chapter that best suits your needs.

• 1.1 Database Design and Basic SQL

• 1.2 One-to-Many Relationships and More SQL

• 1.3 Many-to-Many Relationships and Even More SQL

Chapter 2: SQLite in C/C++

In this chapter, I discuss how to use the low level SQLite API from a C or C++ program. You have a lot of power when using the API and I cover ACID transactions. Yes, we're going to talk about pointers and memory management. Even if you're not a C/C++ programmer and haven't touched a pointer since college, I recommend looking at this chapter. Understanding what's happening under the hood will make the other chapters clearer. Plus, you can impress your friends at parties by casually mentioning you know how database transactions really work.

• 2.1 Using the SQLite C/C++ API

• 2.2 An Object Oriented Auction Program

• 2.3 SQLite Transactions

Chapter 3: SQLite in Python

Learn how to use SQLite in any Python program including Flask web apps. No ORMs hiding what's really happening. Just clean, direct database access. I cover how to query and create SQLite databases and then show how to build an API using Flask. By the end, you'll have a working web API that didn't require installing PostgreSQL, configuring connection pools, or sacrificing a weekend to database administration.

• 3.1 Using a SQLite Database in a Python Program

• 3.2 Creating SQLite Databases

• 3.3 Using SQLite in a Flask Web Application

• 3.4 Creating a Web API with Flask and SQLite

Chapter 4: SQLite in Java

In this final chapter I give an example in Java using JDBC. Because sometimes you need to write enterprise code, and SQLite works there too. Who says you need Oracle for everything?

• 4.1 Using a SQLite Database in a Java Program

Conclusion

Ready to explore SQLite? Start with the first playback and see how fun database programming can be. Each example builds on the previous one, giving you practical experience with real code. Real code solving real problems.

I'd love to hear your thoughts! Feel free to share your comments, questions, or feedback via email: mark@playbackpress.com. Your input helps me improve and create even better content.

If you've found this tutorial helpful, consider supporting my work through GitHub Sponsors. Your contributions help cover hosting costs and keep Playback Press free for everyone. Thank you for helping me continue creating educational resources for the developer community!

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.

A design pattern attempts to describe an effective solution to the problem in a generic way so that it can be applied to a specific set of circumstances.

I will use Java to build an example of each pattern. I’m assuming that you have some programming experience in Java. In particular, you should be (at least somewhat) familiar with the concepts of inheritance and polymorphism. These design patterns really show the power of inheritance and polymorphism, so if you are just learning about these topics this is a great opportunity to dig deeper.

What if you not a Java programmer? If you are familiar with any Object-Oriented language you will probably still get a lot out of the examples. Give it a shot!

Code Playbacks

To make design patterns more approachable, I developed an interactive tutorial that uses annotated code playbacks to walk through key design pattern features step-by-step.

Each design pattern is presented as a code playback that shows how a program changes over time along with my explanation about what's happening. This format helps you focus on the reasoning behind the code changes.

You can access the free 'book' of code playbacks here:

OO Design Patterns with Java, by Mark Mahoney (that’s me)

To view a code playback, click on the comments in the left panel. Each comment updates the code in the editor and highlights any changes. Read the explanation and study the code. If you get stuck, use the AI assistant like a tutor to help explain what is happening in the code.

For more information about code playbacks, you can watch a short demo here.

Key Design Patterns You Should Know

Strategy Pattern

The Strategy Pattern is used to define a 'family' of algorithms, encapsulate each one, and make them interchangeable. Software developers use the Strategy pattern when they know there are many different ways of accomplishing some behavior. Rather than include all the different ways in a single class, they separate them out into individual classes and plug them in when necessary.

This program creates some classes to hold student grades. Some instructors like to adjust the entire course’s grades to make them higher. Some instructors do this by dropping every student's lowest grade. Other instructors 'curve' each assignment. Since there are several different options, I will use the Strategy Pattern to isolate them and let the client choose which one they prefer.

Start by looking at the Assignment, Student, and Course classes. Once you are familiar with the core classes, watch as I change the code to implement two different approaches to curving the grades using the Strategy Pattern:

Strategy Pattern Adjusting Grades in a Course

Singleton Pattern

There are times when you need to make sure there is only one instance of a class and it is accessible everywhere in your code. This is the problem that the Singleton Pattern solves.

In this program, I will create a class that generates random numbers. I will rely on Java's built-in Random class but will be able to reproduce the exact same sequence of random numbers when in 'test mode'. I'll make sure that there is only one instance of this random number generator using the Singleton Pattern:

Singleton Pattern A Testable Random Number Class

Composite Pattern

Often, we’ll create whole/part containment tree structures. For example, in a file system there are simple files. I call these simple elements, primitives. We can group primitives together to form larger composites. Files can be grouped into directories. These composites (directories) can be grouped into still larger composites, and so on.

We could treat composites and primitives differently. But it often makes sense to treat them the same. Having to distinguish between the object types makes the application more complex.

The Composite Pattern describes how to use recursive composition so that clients don't need to make this distinction.

This program creates classes for printing a hierarchical collection of files and directories using the Composite Pattern:

Composite Pattern Displaying a Hierarchical File System

Decorator Pattern

Sometimes we want to add responsibilities to individual objects, not an entire class. The Decorator Pattern allows us to create decorators to provide a flexible alternative to inheritance for extending a class.

In this program, I create an interface for logging messages while a program is running. I use the interface to create a ConsoleLogger that prints the log messages to the screen. Then I start to add decorator objects that surround, or wrap, the ConsoleLogger. I add decorators to attach the date, author name, and time to the log messages using the Decorator Pattern:

Decorator Pattern Logging with Decorators

State Pattern

Sometimes there are systems that react differently based on the 'state' that they are in. A state is a period of time during which a system will react to events according to certain rules. This state-based behavior is implemented using the State Pattern.

I’ll show you how to move through the characters in a string and parse it to account for quotes within it. For example, the following string:

"hamburgers chips 'hot dogs' pickles 'french fries'"

can be split into a collection like this:

["hamburgers", "chips", "hot dogs", "pickles", "french fries"]

There are may ways to accomplish this in Java, but I’ll show a state-based approach. When a single quote is encountered within a string I will use that as an event and move between different states using the State Pattern:

State Pattern String Splitting for Search Bars

Observer Pattern

The Observer Pattern is used when the update of a single piece of data in one object needs to be propagated to a collection of other objects.

For example, when the value of a cell in a spreadsheet changes, several other cells may need to be notified of that change so that they can update themselves. Similarly, in a social network application when a user makes a post, all of their friends need to be notified so that their feeds can be updated. Both of these are essentially the same problem that the Observer Pattern solves.

This program creates a class to hold a time in a day called MyTime. Then I create two different types of Observers that will be notified when the time changes. The two observers will re-display the time every time it changes using the Observer Pattern:

Observer Pattern Observing the Time Change

Proxy Pattern

Sometimes we design a set of objects that have a client/server relationship but later decide that the two objects should not interact directly. This program shows how to use the Proxy Pattern to place some new functionality in between two previously cooperating classes.

I create a Card and Deck class for card games. The Deck starts out being hosted on the same machine as the Driver. Then I split the Driver and the Deck class so that they can be run on different machines using the Proxy Pattern:

Proxy Pattern Dealing Cards from a Remote Deck

Factory Pattern

The Factory Pattern provides a mechanism for creating 'families' of related objects without specifying their concrete classes. Instantiating concrete objects in an application makes it hard to change those objects later.

In this program, I will create two different families of classes for a help system for two different computing platforms using the Factory Pattern:

Factory Pattern Getting Help in Mac and Windows

Visitor Pattern

The Visitor Pattern lets you add functionality to a hierarchy of classes without changing its interface.

The reason why this is important is that there are times when we cannot change an existing hierarchy of classes. Perhaps I am using a hierarchy of classes that I am not in control of but I want to add some new functionality to it anyway. This is where the Visitor Pattern comes in.

In this program, I’ll add functionality to the File and Directory classes from the Composite program that I wrote earlier with minimal changes to those classes.

I create a visitor to count the number of files and directories in a topmost directory. Then I write a visitor to collect only the filenames in a directory including its sub-directories using the Visitor Pattern:

Visitor Pattern Adding Functionality to a Hierarchy of Classes (File and Directory)

Conclusion

I hope you enjoyed learning about object-oriented design patterns. If you are interested in other programming paradigms, you can check out some of my other 'books' here.

Questions and feedback are always welcome here: mark@playbackpress.com

If you'd like to support my work and help keep Playback Press free for all, consider donating using GitHub Sponsors. I use all of the donations for hosting costs. Your support helps me continue creating educational content like this. Thank you!

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

This is where constructors come into play. Constructors are special types of methods with no return type. They are basically used to initialise the object, to set up its internal state, or to assign default values to its attributes.

In this tutorial, we will go deep into the topic of constructors in Java. You’ll learn how they work and why they are essential in object creation and Java programming. By the end, I hope you’ll understand why they’re one of the core concepts of OOP.

Let’s start…

Prerequisites

You don’t need to know anything too advanced to start learning about constructors in Java. Just a basic understanding of Java syntax, classes, objects, methods, parameters, arguments, and access modifiers is enough to get started.

What we’ll cover:

• What are Constructors in Java?

  • Constructor syntax:

• Types of Constructors

  • Default Constructor

  • No Argument constructor

  • Parameterised Constructor

  • Copy Constructor

• What Happens Behind the Scenes When a Constructor Is Called in Java?

• How to Use the return Keyword in Constructors

  • Sample Code:

  • Example:

• Conclusion

• Frequently Asked Questions

What are Constructors in Java?

As mentioned above, constructors are special types of methods that:

1. do not have a return type (not even void),

2. have the same name as the class

3. are called automatically when an object is created using the new keyword.

A constructor’s main purpose is to initialise a newly created object, to set up its internal state, or to assign default values to its attributes.

Constructors can also be understood as a special block of code which is called when an object is created – either automatically or manually by hard-coding it – with the values we want to initialise the object with.

If we’re okay with the object using default values (like 0 for numbers or null for objects), Java will handle that for us automatically. But if we want to give the object specific values when it's created, we need to write a constructor that takes those values as parameters and uses them to set up the object.

Constructor syntax:

class ClassName {

    // Default constructor with access modifier
    [access_modifier] ClassName(parameters...) {
        // constructor body
    }

}

Examples

When the constructor is not defined explicitly

class Car {

    String brand;
    int year;

    // No constructor is defined, so Java provides a default one
}

public class Main {

    public static void main(String[] args) {

        Car car1 = new Car();  // Java calls the default constructor

        // Default values: brand = null, year = 0
        System.out.println("Brand: " + car1.brand);
        System.out.println("Year: " + car1.year);
    }
}

Output:

In the above code, we have a Car class with two variables:

1. brand of type String

2. year of type int

Since a class is just a blueprint, we need to create an object to actually use it. This is done in the Main class. When we create a Car object using new Car(), Java looks for a constructor. Because we didn’t define one, the compiler automatically provides a default constructor (one with no arguments).

This allows us to create the object and print its variables without any errors. The values printed will be the default ones — null for the String, and 0 for the int.

We'll dive deeper into how this works behind the scenes later, step by step, so it becomes easier to understand.

When we have defined a constructor

public class Car {

    String brand;
    int year;

    // Constructor with parameters to initialize custom values
    public Car(String brandName, int modelYear) {
        brand = brandName;
        year = modelYear;
    }
}

public class Main {

    public static void main(String[] args) {

        Car car2 = new Car("Toyota", 2022);  // Custom values

        System.out.println("Brand: " + car2.brand);
        System.out.println("Year: " + car2.year);
    }
}

Output

This is the same code as before, with one key difference: this time, we’ve explicitly defined a constructor. Because of this, the output we see isn’t the default values (null for String, 0 for int), but the custom values we provided.

How does that happen? Simple – we pass values as arguments when creating the object:

Car car2 = new Car("Toyota", 2022);

These values are received by the constructor as parameters and are then used to initialize the object’s variables. As a result, instead of default values, we get the brand and year we specified.

Types of Constructors

There are mainly four types of constructors:

1. Default Constructors

2. No-Arguments Constructor

3. Parameterised Constructor

4. Copy Constructor

Default Constructor

A type of no-argument constructor that is added by the compiler during the compilation process so that the values of the object can be initialised. It’s only added by the compiler if you don’t add one explicitly.

Syntax:

public class MyClass {

    public MyClass() {
        // Constructor body
    }

}

Example

public class Bike {

    // No constructor defined here
    // Compiler will automatically add a default constructor

    public static void main(String[] args) {
        Bike myBike = new Bike();  // Calls the compiler-provided default constructor
        System.out.println("Bike object created!");
    }

}

The code becomes the following after the compiler adds a default constructor during the compilation process:

public class Bike {

    // Compiler-added default constructor
    public Bike() {
        super();  // Calls Object class constructor
    }

    public static void main(String[] args) {
        Bike myBike = new Bike();  // Now calls this explicit default constructor
        System.out.println("Bike object created!");
    }

}

Output

Bike object created!

No Argument constructor

No-argument constructor is a type of constructor that you explicitly write in your code and that does not contain any parameters.

Now, you may be wondering…Isn't it the same as the default constructor? The answer is both yes and no.

There isn’t much difference between the default constructor and the no-argument constructor, as both do not take any parameters. But there is one key difference.

The default constructor, as we have already discussed, is a type of no-argument constructor that is automatically added by the compiler when it doesn’t find one in our code. In contrast, a no-argument constructor is a type of constructor that we write in our code.

In short, if the compiler is the one that is adding a constructor during the compilation process, it's called a default constructor. But if we are the ones adding the constructor, it’s called a no-argument constructor.

The main difference between a default constructor and a user-defined constructor is how they are created and what they do.

• A default constructor is automatically added by the compiler if we don’t add one ourselves. It doesn’t do much – it just calls the parent class (usually the Object class) and sets all variables to their default values. For example, int becomes 0and objects become null.

• A user-defined constructor is one that we write ourselves. We can add custom logic inside it, set custom values to variables, and use access modifiers like public, private, or protected. This means we can decide how the object should be set up when it is created.

Note that even if we don’t write super() in our constructor, Java still adds it automatically unless we call another constructor with this() or call a different super(...) with parameters.

We will understand this deeply in the next section.

Syntax:

class ClassName {

    public ClassName() {
        // Body (optional)
    }

}

Example

Let's use the same Bike example we used to explain the default constructor.

public class Bike {

    public Bike() {
        System.out.println("Bike object created!");
    }

    public static void main(String[] args) {
        Bike myBike = new Bike();
    }
}

Output:

Bike object created!

In the above code, we have defined a constructor in our code while writing it. This means that it is an example of a no-argument constructor.

We know that both types of constructors are defined without any parameters, but what about the body? We haven’t said anything about it. Let’s see what happens if we write code with a no-argument constructor without a body:

public class Bike {

    Bike() {
        // No body
    }

    public static void main(String[] args) {
        Bike myBike = new Bike(); // Calls the user-defined no-argument constructor
        System.out.println("Bike object created!");
    }
}

Output:

Bike object created!

The code still gets compiled because the compiler adds the super() keyword during the compilation process, which initialises the object using the object class.

Parameterised Constructor

A constructor that accepts parameters is called a parameterised constructor and is only used when we have to initialise an object’s attributes with custom values.

• Parameter refers to the variable listed in the constructor or method definition.

• Argument is the actual value passed when calling the constructor or method.

It gives us the flexibility of initiating our object with custom values given at the time of object creation.

Syntax

Below is the syntax for a parameterised constructor that takes one parameter:

class ClassName {

    // Data members (instance variables)
    DataType variable1;

    // Parameterized constructor
    ClassName(DataType param1) {
        variable1 = param1;
    }

    // Main method to create objects
    public static void main(String[] args) {
        // Creating object using parameterized constructor
        ClassName obj = new ClassName(value1);
    }
}

Example

We will again use the Bike example for this.

public class Bike {

    String modelName;  // instance variable

    // Parameterized constructor
    Bike(String model) {
        modelName = model;
    }

    public static void main(String[] args) {
        // Pass parameter while creating the Bike object
        Bike myBike = new Bike("Mountain Bike");
        System.out.println("Bike object created! Model: " + myBike.modelName);
    }
}

Output:

Bike object created! Model: Mountain Bike

In this example, we’re working with a Bike class that has an instance variable of String data type called modelName, and a constructor to set the value of that variable.

The constructor takes a parameter called model and assigns it to modelName. So, when we create a new Bike object and pass in the string "Mountain Bike", the constructor stores that value in the modelName variable.

Because of this, when we print out the model name, we see "Mountain Bike" instead of null, which is the default value of the String data type, as now the value of the modelName has been updated.

Copy Constructor

A copy constructor is used to create a new object as a copy of the existing object. Unlike C++, Java doesn’t have a default copy constructor. Instead, we have to create our own by creating a constructor that takes an object of the same class as a parameter and copies its fields.

Syntax

class ClassName {

    // Fields
    DataType1 field1;
    DataType2 field2;
    // ... other fields

    // Normal constructor
    ClassName(DataType1 f1, DataType2 f2) {
        field1 = f1;
        field2 = f2;
        // ... initialize other fields
    }

    // Copy constructor 
    ClassName(ClassName other) {
        field1 = other.field1;
        field2 = other.field2;
        // ... copy other fields
    }
}

Example

public class Bike {

    String modelName;  // instance variable

    // Parameterized constructor
    Bike(String model) {
        modelName = model;
    }

    // Copy constructor
    Bike(Bike otherBike) {
        modelName = otherBike.modelName;
    }

    public static void main(String[] args) {
        // Create a Bike object using the parameterized constructor
        Bike myBike = new Bike("Mountain Bike");
        System.out.println("Bike object created! Model: " + myBike.modelName);

        // Create a copy of the existing Bike object using the copy constructor
        Bike copiedBike = new Bike(myBike);
        System.out.println("Copied Bike object created! Model: " + copiedBike.modelName);
    }
}

Output:

Bike object created! Model: Mountain Bike

Copied Bike object created! Model: Mountain Bike

In the above code, we have created a copy constructor to copy the values of the object (myBike) into a new object (copiedBike), which we have defined in the main class.

But the way the new object is called is a little different. Instead of passing arguments for the constructor, we have passed the original object.

Why Copy Constructors?

A copy constructor is used to make a copy of the object, but you can also make a copy using the clone() method or the object.clone() method. So why do we use a copy constructor?

The copy constructor makes a deep copy, while the clone method makes a shallow copy of the object. There are various things that you should know before using cloning techniques, like CloneNotSupportedException.

On the other hand, copy constructors are clear and easy to understand, and work well with final fields. We can control how the copy happens (deep vs. shallow) and especially when we are dealing with mutable objects.

What Happens Behind the Scenes When a Constructor Is Called in Java?

So, just to recap: when we create an object using the new keyword, a constructor is automatically called. If we haven't defined any constructors in our class, Java automatically defines a constructor for us.

But while writing and running our code, we mostly focus on what’s visible in our editor, as in what we can see. Let’s dive a little deeper and explore what happens behind the scenes – at the compiler and JVM level – when an object is created and executed.

• Step 1: Memory Allocation – When we create an object using a new keyword, Java allocates memory for that object in the heap. This memory is where the object’s fields (also called attributes) will be placed.

• Step 2: Reference Creation – A reference to this object is stored on the stack, which lets our program interact with the object that lives in the heap.

• Step 3: Constructor Creation – Java then determines which constructor to call. If no constructor is explicitly defined in our class, the compiler automatically inserts a constructor with no parameters.

• Step 4: Superclass Constructor Call – Before executing the constructor’s body, Java first calls the constructor of the superclass using the super() keyword. This ensures that the fields inherited from the parent class are properly initialised. If you don’t explicitly write super(), the compiler adds it automatically in the first line of the code, but only if the superclass has a no-argument constructor, unless we're already calling another constructor via this().

But don’t use both the super() and this() keywords in the same constructor (you can use them in separate constructors.

Let’s say that it doesn’t have a super class – then what?

The answer is simple: Java has an in-built Object class that has a no-argument constructor by default. This is why our classes run smoothly even if we don’t write super() ourselves, as Java calls it in the background.

That means every class we create is a subclass of the object class:

Attribute Initialisation:

At this point, fields get initialised:

• First, with default values (for example, 0 for int, null for objects),

• Then, with any explicit initialisations we've written (for example, int x = 10), the default values will get replaced by them.

Constructor Execution:

And finally, the logic runs. This is where all or some of the attributes defined in the class for object creation are initialised by the parameters used during object creation, with the help of constructors.

But not every field may get initialised. Fields that are not updated by the constructor will keep the values they already have (either the default value or the explicitly initialised values).

In short, the constructor gives us the flexibility to customise our object at the time of creation, but it doesn't automatically set every field unless we explicitly write the logic for it.

Check the code below to understand better:

class Example {

    int a;           // default 0
    int b = 10;      // explicitly initialized to 10
    String name;     // default null

    Example(int x) {
        a = x;       // only 'a' is set through constructor
        // 'b' is not changed, stays 10
        // 'name' is not changed, stays null
    }

    void display() {
        System.out.println("a = " + a);
        System.out.println("b = " + b);
        System.out.println("name = " + name);
    }

    public static void main(String[] args) {
        Example obj = new Example(5);
        obj.display();
    }
}

Output:

In the above example, we have three data members – a, b, and name. We have already done the declaration and initialisation of the variable b at the beginning and given a value to a at the time of object creation.

So we can see that:

1. ‘a’, whose value has been updated by the constructor with the value given at the time of object creation, has the same value

2. ‘b’, which already had a value and does not get updated by the constructor, prints the same value

3. the string ‘name’ didn’t have a value, so null was printed instead, as it is the default value of the String data type.

How to Use the return Keyword in Constructors

We know that constructors are defined without a return type, but we can use the return keyword in the constructor only to exit the constructor early, not to return a value. Check out the code below.

Sample Code:

public class Bike {

    String modelName;  // instance variable
    int speed;

    // Parameterized constructor
    Bike(String model, int sp) {
        modelName = model;
        return;
        speed = sp;
    }

    public static void main(String[] args) {
        // Pass parameter while creating the Bike object
        Bike myBike = new Bike("Mountain Bike", 20);
        System.out.println("Bike object created! Model: " + myBike.modelName);
        System.out.println("Speed of the Bike is " + myBike.speed);
    }
}

Let’s try to understand the above code and the use of the return keyword along with it. We will start with what would happen if the return keyword wasn’t here. The code would have executed without any errors and would have received an output.

Now, what will happen if we add the return keyword? As we have discussed above, the return keyword will tell the compiler not to go beyond this point in the constructor.

So whatever we have written in the constructor after the return keyword will not be compiled, and if that had any value and was necessary for the proper execution of our code, the compiler will throw an error.

The error says it clearly ‘unreachable statement’, which means that the compiler was not allowed to go beyond the return keyword.

Now that you understand the return keyword, let’s see when you can use it.

Example:

public class Bike {

    // Constructor with a condition to exit early
    Bike(boolean skip) {
        if (skip) {
            System.out.println("Constructor exited early");
            return; // Ends constructor execution here
        }

        System.out.println("Constructor continues...");
        // More initialization logic can go here
        System.out.println("Bike object initialized successfully");
    }

    public static void main(String[] args) {
        System.out.println("Creating first bike (skip = true):");
        Bike bike1 = new Bike(true);  // Constructor will exit early

        System.out.println("\nCreating second bike (skip = false):");
        Bike bike2 = new Bike(false); // Constructor will continue
    }
}

We’ve defined a Bike class that has a constructor with one boolean parameter called skip. Inside the constructor, there's an if statement that checks if skip is true. If it is, the constructor prints a message and uses the return keyword to exit early. This means the rest of the constructor won’t run.

But there is no else block. So what happens when skip is false? In that case, the if condition is not true, then the code inside the if statement is not executed (including the return keyword) and the constructor simply continues to the next lines of code. That’s where we do the actual bike initialisation and print a success message.

In short:

1. If skip is true, the constructor exits early.

2. If skip is false, the constructor continues and finishes the setup.

This is a simple way to control how much of the constructor runs, based on a condition.

Conclusion

In this blog, we have understood many different topics, what a constructor is, its different types, like default constructor, no argument constructor, parameterised constructor and copy constructor, not only with theory but with code examples as well.

Understanding them will not only enhance our understanding but also help us write modular and well-maintained code in Java. While this concept is also important in OOP, as it is centred around the concept of objects and constructors are the ones that are used to initialise them.

Frequently Asked Questions

Q1. Why do we use constructors?

A: We use constructors because:

1. They are created automatically by the compiler and initialise the object with default values.

2. We can initialise all the attributes of the objects in one go.

3. They prevent incomplete or incorrect object initialisation by ensuring that important data is provided during object creation.

4. Code maintainability and modularity increase.

5. We can use objects as soon as they are created.

Q2. What is the basic difference between Method Overloading and Constructor Overloading?

A:

You can check out some of my other beginner-friendly articles on my blog:

1. Understanding abstraction in Java

2. How to build a Movie App in React using TMDB API?

3. How to merge two sorted arrays

Prior to the introduction of the Collections framework in JDK 1.2, you would’ve used Arrays and Vectors to store and manage a group of objects. But they had their own share of drawbacks.

The Java Collections Framework aims to overcome these issues by providing high-performance implementations of common data structures. These allow you to focus on writing the application logic instead of focusing on low-level operations.

Then, the introduction of Generics in JDK 1.5 significantly improved the Java Collections Framework. Generics let you enforce type safety for objects stored in a collection, which enhances the robustness of your applications. You can read more about Java Generics here.

In this article, I will guide you through how to use the Java Collections Framework. We’ll discuss the different types of collections, such as Lists, Sets, Queues, and Maps. I’ll also provide a brief explanation of their key characteristics such as:

• Internal mechanisms

• Handling of duplicates

• Support for null values

• Ordering

• Synchronization

• Performance

• Key methods

• Common implementations

We’ll also walk through some code examples for better understanding, and I’ll touch on the Collections utility class and its usage.

Table of Contents:

1. Understanding the Java Collections Framework

   • Collection Interfaces

   • Decoding the Java Collections Framework Hierarchy

   • A Closer Look at Collection Interfaces

2. Java Collection Interfaces

   • Lists

   • Sets

   • Queues

   • Maps

3. Collections Utility Class

4. Conclusion

Understanding the Java Collections Framework

According to the Java documentation, “A collection is an object that represents a group of objects. A collections framework is a unified architecture for representing and manipulating collections.”

In simple terms, the Java Collections Framework helps you manage a group of objects and perform operations on them efficiently and in an organized way. It makes it easier to develop applications by offering various methods to handle groups of objects. You can add, remove, search, and sort objects effectively using the Java Collections Framework.

Collection Interfaces

In Java, an interface specifies a contract that must be fulfilled by any class that implements it. This means the implementing class must provide concrete implementations for all the methods declared in the interface.

In the Java Collections Framework, various collection interfaces like Set, List, and Queue extend the Collection interface, and they must adhere to the contract defined by the Collection interface.

Decoding the Java Collections Framework Hierarchy

Check out this neat diagram from this article that illustrates the Java Collection Hierarchy:

We’ll start from the top and work down so you can understand what this diagram is showing:

1. At the root of the Java Collections Framework is the Iterable interface, which lets you iterate over the elements of a collection.

2. The Collection interface extends the Iterable interface. This means it inherits the properties and behavior of the Iterable interface and adds its own behavior for adding, removing, and retrieving elements.

3. Specific interfaces such as List, Set, and Queue further extend the Collection interface. Each of these interfaces has other classes implementing their methods. For example, ArrayList is a popular implementation of the List interface, HashSet implements the Set interface, and so on.

4. The Map interface is part of the Java Collections Framework, but it does not extend the Collection interface, unlike the others mentioned above.

5. All the interfaces and classes in this framework are part of the java.util package.

Note: A common source of confusion in the Java Collections Framework revolves around the difference between Collection and Collections. Collection is an interface in the framework, while Collections is a utility class. The Collections class provides static methods that perform operations on the elements of a collection.

Java Collection Interfaces

By now, you’re familiar with the different types of collections that form the foundation of the collections framework. Now we’ll take a closer look at the List, Set, Queue, and Map interfaces.

In this section, we'll discuss each of these interfaces while exploring their internal mechanisms. We'll examine how they handle duplicate elements and whether they support the insertion of null values. We'll also understand the ordering of elements during insertion and their support for synchronization, which deals with the concept of thread safety. Then we’ll walk through a few key methods of these interfaces and conclude by reviewing common implementations and their performance for various operations.

Before we begin, let's talk briefly about Synchronization and Performance.

• Synchronization controls access to shared objects by multiple threads, ensuring their integrity and preventing conflicts. This is crucial for maintaining thread safety.

• When choosing a collection type, one important factor is its performance during common operations like insertion, deletion, and retrieval. Performance is usually expressed using Big-O notation. You can learn more about it here.

Lists

A List is an ordered or sequential collection of elements. It follows zero-based indexing, allowing the elements to be inserted, removed, or accessed using their index position.

1. Internal mechanism: A List is internally supported by either an array or a linked list, depending on the type of implementation. For example, an ArrayList uses an array, while a LinkedList uses a linked list internally. You can read more about LinkedList here. A List dynamically resizes itself upon the addition or removal of elements. The indexing-based retrieval makes it a very efficient type of collection.

2. Duplicates: Duplicate elements are allowed in a List, which means there can be more than one element in a List with the same value. Any value can be retrieved based on the index at which it is stored.

3. Null: Null values are also allowed in a List. Since duplicates are permitted, you can also have multiple null elements.

4. Ordering: A List maintains insertion order, meaning the elements are stored in the same order they are added. This is helpful when you want to retrieve elements in the exact order they were inserted.

5. Synchronization: A List is not synchronized by default, which means it doesn't have a built-in way to handle access by multiple threads at the same time.

6. Key methods: Here are some key methods of a List interface: add(E element), get(int index), set(int index, E element), remove(int index), and size(). Let's look at how to use these methods with an example program.

    import java.util.ArrayList;
    import java.util.List;
   
    public class ListExample {
        public static void main(String[] args) {
            // Create a list
            List<String> list = new ArrayList<>();
   
            // add(E element)
            list.add("Apple");
            list.add("Banana");
            list.add("Cherry");
   
            // get(int index)
            String secondElement = list.get(1); // "Banana"
   
            // set(int index, E element)
            list.set(1, "Blueberry");
   
            // remove(int index)
            list.remove(0); // Removes "Apple"
   
            // size()
            int size = list.size(); // 2
   
            // Print the list
            System.out.println(list); // Output: [Blueberry, Cherry]
   
            // Print the size of the list
            System.out.println(size); // Output: 2
        }
    }
   

7. Common implementations: ArrayList, LinkedList, Vector, Stack

8. Performance: Typically, insert and delete operations are fast in both ArrayList and LinkedList. But fetching elements can be slow because you have to traverse through the nodes.

Sets

A Set is a type of collection that does not allow duplicate elements and represents the concept of a mathematical set.

1. Internal mechanism: A Set is internally backed by a HashMap. Depending on the implementation type, it is supported by either a HashMap, LinkedHashMap, or a TreeMap. I have written a detailed article about how HashMap works internally here. Be sure to check it out.

2. Duplicates: Since a Set represents the concept of a mathematical set, duplicate elements are not allowed. This ensures that all elements are unique, maintaining the integrity of the collection.

3. Null: A maximum of one null value is allowed in a Set because duplicates are not permitted. But this does not apply to the TreeSet implementation, where null values are not allowed at all.

4. Ordering: Ordering of elements in a Set depends on the type of implementation.

   • HashSet: Order is not guaranteed, and elements can be placed in any position.

   • LinkedHashSet: This implementation maintains the insertion order, so you can retrieve the elements in the same order they were inserted.

   • TreeSet: Elements are inserted based on their natural order. Alternatively, you can control the insertion order by specifying a custom comparator.

5. Synchronization: A Set is not synchronized, meaning you might encounter concurrency issues, like race conditions, which can affect data integrity if two or more threads try to access a Set object simultaneously

6. Key methods: Here are some key methods of a Set interface: add(E element), remove(Object o), contains(Object o), and size(). Let's look at how to use these methods with an example program.

    import java.util.HashSet;
    import java.util.Set;
   
    public class SetExample {
        public static void main(String[] args) {
            // Create a set
            Set<String> set = new HashSet<>();
   
            // Add elements to the set
            set.add("Apple");
            set.add("Banana");
            set.add("Cherry");
   
            // Remove an element from the set
            set.remove("Banana");
   
            // Check if the set contains an element
            boolean containsApple = set.contains("Apple");
            System.out.println("Contains Apple: " + containsApple);
   
            // Get the size of the set
            int size = set.size();
            System.out.println("Size of the set: " + size);
        }
    }
   

7. Common implementations: HashSet, LinkedHashSet, TreeSet

8. Performance: Set implementations offer fast performance for basic operations, except for a TreeSet, where the performance can be relatively slower because the internal data structure involves sorting the elements during these operations.

Queues

A Queue is a linear collection of elements used to hold multiple items before processing, usually following the FIFO (first-in-first-out) order. This means elements are added at one end and removed from the other, so the first element added to the queue is the first one removed.

1. Internal mechanism: The internal workings of a Queue can differ based on its specific implementation.

   • LinkedList – uses a doubly-linked list to store elements, which means you can traverse both forward and backward, allowing for flexible operations.

   • PriorityQueue – is internally backed by a binary heap, which is very efficient for retrieval operations.

   • ArrayDeque – is implemented using an array that expands or shrinks as elements are added or removed. Here, elements can be added or removed from both ends of the queue.

2. Duplicates: In a Queue, duplicate elements are permitted, allowing multiple instances of the same value to be inserted

3. Null: You cannot insert a null value into a Queue because, by design, some methods of a Queue return null to indicate that it is empty. To avoid confusion, null values are not allowed.

4. Ordering: Elements are inserted based on their natural order. Alternatively, you can control the insertion order by specifying a custom comparator.

5. Synchronization: A Queue is not synchronized by default. But, you can use a ConcurrentLinkedQueue or a BlockingQueue implementation for achieving thread safety.

6. Key methods: Here are some key methods of a Queue interface: add(E element), offer(E element), poll(), and peek(). Let's look at how to use these methods with an example program.

    import java.util.LinkedList;
    import java.util.Queue;
   
    public class QueueExample {
        public static void main(String[] args) {
            // Create a queue using LinkedList
            Queue<String> queue = new LinkedList<>();
   
            // Use add method to insert elements, throws exception if insertion fails
            queue.add("Element1");
            queue.add("Element2");
            queue.add("Element3");
   
            // Use offer method to insert elements, returns false if insertion fails
            queue.offer("Element4");
   
            // Display queue
            System.out.println("Queue: " + queue);
   
            // Peek at the first element (does not remove it)
            String firstElement = queue.peek();
            System.out.println("Peek: " + firstElement); // outputs "Element1"
   
            // Poll the first element (retrieves and removes it)
            String polledElement = queue.poll();
            System.out.println("Poll: " + polledElement); // outputs "Element1"
   
            // Display queue after poll
            System.out.println("Queue after poll: " + queue);
        }
    }
   

7. Common implementations: LinkedList, PriorityQueue, ArrayDeque

8. Performance: Implementations like LinkedList and ArrayDeque are usually quick for adding and removing items. The PriorityQueue is a bit slower because it inserts items based on the set priority order.

Maps

A Map represents a collection of key-value pairs, with each key mapping to a single value. Although Map is part of the Java Collection framework, it does not extend the java.util.Collection interface.

1. Internal mechanism: A Map works internally using a HashTable based on the concept of hashing. I have written a detailed article on this topic, so give it a read for a deeper understanding.

2. Duplicates: A Map stores data as key-value pairs. Here, each key is unique, so duplicate keys are not allowed. But duplicate values are permitted.

3. Null: Since duplicate keys are not allowed, a Map can have only one null key. As duplicate values are permitted, it can have multiple null values. In the TreeMap implementation, keys cannot be null because it sorts the elements based on the keys. However, null values are allowed.

4. Ordering: Insertion order of a Map varies on the implementation:

   • HashMap – the insertion order is not guaranteed as they are determined based on the concept of hashing.

   • LinkedHashMap – the insertion order is preserved and you can retrieve the elements back in the same order that they were added into the collection.

   • TreeMap – Elements are inserted based on their natural order. Alternatively, you can control the insertion order by specifying a custom comparator.

5. Synchronization: A Map is not synchronized by default. But you can use Collections.synchronizedMap() or ConcurrentHashMap implementations for achieving thread safety.

6. Key methods: Here are some key methods of a Map interface: put(K key, V value), get(Object key), remove(Object key), containsKey(Object key), and keySet(). Let's look at how to use these methods with an example program.

    import java.util.HashMap;
    import java.util.Map;
    import java.util.Set;
   
    public class MapMethodsExample {
        public static void main(String[] args) {
            // Create a new HashMap
            Map<String, Integer> map = new HashMap<>();
   
            // put(K key, V value) - Inserts key-value pairs into the map
            map.put("Apple", 1);
            map.put("Banana", 2);
            map.put("Orange", 3);
   
            // get(Object key) - Returns the value associated with the key
            Integer value = map.get("Banana");
            System.out.println("Value for 'Banana': " + value);
   
            // remove(Object key) - Removes the key-value pair for the specified key
            map.remove("Orange");
   
            // containsKey(Object key) - Checks if the map contains the specified key
            boolean hasApple = map.containsKey("Apple");
            System.out.println("Contains 'Apple': " + hasApple);
   
            // keySet() - Returns a set view of the keys contained in the map
            Set<String> keys = map.keySet();
            System.out.println("Keys in map: " + keys);
        }
    }
   

7. Common implementations: HashMap, LinkedHashMap, TreeMap, Hashtable, ConcurrentHashMap

8. Performance: HashMap implementation is widely used mainly due to its efficient performance characteristics depicted in the below table.

Collections Utility Class

As highlighted at the beginning of this article, the Collections utility class has several useful static methods that let you perform commonly used operations on the elements of a collection. These methods help you reduce the boilerplate code in your application and lets you focus on the business logic.

Here are some key features and methods, along with what they do, listed briefly:

1. Sorting: Collections.sort(List<T>) – this method is used to sort the elements of a list in ascending order.

2. Searching: Collections.binarySearch(List<T>, key) – this method is used to search for a specific element in a sorted list and return its index.

3. Reverse order: Collections.reverse(List<T>) – this method is used to reverse the order of elements in a list.

4. Min/Max Operations: Collections.min(Collection<T>) and Collections.max(Collection<T>) – these methods are used to find the minimum and maximum elements in a collection, respectively.

5. Synchronization: Collections.synchronizedList(List<T>) – this method is used to make a list thread-safe by synchronizing it.

6. Unmodifiable Collections: Collections.unmodifiableList(List<T>) – this method is used to create a read-only view of a list, preventing modifications.

Here's a sample Java program that demonstrates various functionalities of the Collections utility class:

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class CollectionsExample {
    public static void main(String[] args) {
        List<Integer> numbers = new ArrayList<>();
        numbers.add(5);
        numbers.add(3);
        numbers.add(8);
        numbers.add(1);

        // Sorting
        Collections.sort(numbers);
        System.out.println("Sorted List: " + numbers);

        // Searching
        int index = Collections.binarySearch(numbers, 3);
        System.out.println("Index of 3: " + index);

        // Reverse Order
        Collections.reverse(numbers);
        System.out.println("Reversed List: " + numbers);

        // Min/Max Operations
        int min = Collections.min(numbers);
        int max = Collections.max(numbers);
        System.out.println("Min: " + min + ", Max: " + max);

        // Synchronization
        List<Integer> synchronizedList = Collections.synchronizedList(numbers);
        System.out.println("Synchronized List: " + synchronizedList);

        // Unmodifiable Collections
        List<Integer> unmodifiableList = Collections.unmodifiableList(numbers);
        System.out.println("Unmodifiable List: " + unmodifiableList);
    }
}

This program demonstrates sorting, searching, reversing, finding minimum and maximum values, synchronizing, and creating an unmodifiable list using the Collections utility class.

Conclusion

In this article, you’ve learned about the Java Collections Framework and how it helps manage groups of objects in Java applications. We explored various collection types like Lists, Sets, Queues, and Maps and gained insight into some of the key characteristics and how each of these types supports them.

You learned about performance, synchronization, and key methods, gaining valuable insights into choosing the right data structures for your needs.

By understanding these concepts, you can fully utilize the Java Collections Framework, allowing you to write more efficient code and build robust applications.

If you found this article interesting, feel free to check out my other articles on freeCodeCamp and connect with me on LinkedIn.

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!

Spring Boot’s multi-module structure allows you to manage different parts of the application independently, which lets your team develop, test, and deploy components separately. This structure keeps code organized and modular, making it useful for both microservices and large monolithic systems.

In this tutorial, you’ll build a multi-module Spring Boot project, with each module dedicated to a specific responsibility. You’ll learn how to set up modules, configure inter-module communication, handle errors, implement JWT-based security, and deploy using Docker.

Prerequisites:

• Basic knowledge of Spring Boot and Maven.

• Familiarity with Docker and CI/CD concepts (optional but helpful).

Table of Contents

1. Why Multi-Module Projects?

2. Project Structure and Architecture

3. How to Set Up the Parent Project

4. How to Create the Modules

5. Inter-Module Communication

6. Common Pitfalls and Solutions

7. Testing Strategy

8. Error Handling and Logging

9. Security and JWT Integration

10. Deployment with Docker and CI/CD

11. Best Practices and Advanced Use Cases

12. Conclusion and Key Takeaways

1. Why Multi-Module Projects?

In single-module projects, components are often tightly coupled, making it difficult to scale and manage complex codebases. A multi-module structure offers several advantages:

• Modularity: Each module is dedicated to a specific task, such as User Management or Inventory, simplifying management and troubleshooting.

• Team Scalability: Teams can work independently on different modules, minimizing conflicts and enhancing productivity.

• Flexible Deployment: Modules can be deployed or updated independently, which is particularly beneficial for microservices or large applications with numerous features.

Real-World Example

Consider a large e-commerce application. Its architecture can be divided into distinct modules:

• Customer Management: Responsible for handling customer profiles, preferences, and authentication.

• Product Management: Focuses on managing product details, stock, and pricing.

• Order Processing: Manages orders, payments, and order tracking.

• Inventory Management: Oversees stock levels and supplier orders.

Case Study: Netflix

To illustrate these benefits, let's examine how Netflix employs a multi-module architecture.

Netflix is a leading example of a company that effectively uses this approach through its microservices architecture. Each microservice at Netflix is dedicated to a specific function, such as user authentication, content recommendations, or streaming services.

This modular structure enables Netflix to scale its operations efficiently, deploy updates independently, and maintain high availability and performance. By decoupling services, Netflix can manage millions of users and deliver content seamlessly worldwide, ensuring a robust and flexible system that supports its vast and dynamic platform.

This architecture not only enhances scalability but also improves fault isolation, allowing Netflix to innovate rapidly and respond effectively to user demands.

2. Project Structure and Architecture

Now let’s get back to our example project. Your multi-module Spring Boot project will use five key modules. Here’s the layout:

codespring-boot-multi-module/
 ├── common/               # Shared utilities and constants
 ├── domain/               # Domain entities
 ├── repository/           # Data access layer (DAL)
 ├── service/              # Business logic
 └── web/                  # Main Spring Boot application and controllers

Each module has a specific role:

• common: Stores shared utilities, constants, and configuration files used across other modules.

• domain: Contains data models for your application.

• repository: Manages database operations.

• service: Encapsulates business logic.

• web: Defines REST API endpoints and serves as the application’s entry point.

This structure aligns with separation of concerns principles, where each layer is independent and handles its own logic.

The diagram below illustrates the various modules:

3. How to Set Up the Parent Project

Step 1: Create the Root Project

Let’s run these commands to create the Maven parent project:

mvn archetype:generate -DgroupId=com.example -DartifactId=spring-boot-multi-module -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
cd spring-boot-multi-module

Step 2: Configure the Parent pom.xml

In the pom.xml, let’s define our dependencies and modules:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://www.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>spring-boot-multi-module</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <modules>
        <module>common</module>
        <module>domain</module>
        <module>repository</module>
        <module>service</module>
        <module>web</module>
    </modules>
    <properties>
        <java.version>11</java.version>
        <spring.boot.version>2.5.4</spring.boot.version>
    </properties>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring.boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

This pom.xml file centralizes dependencies and configurations, making it easier to manage shared settings across modules.

4. How to Create the Modules

Common Module

Let’s create a common module to define shared utilities like date formatters. Create this module and add a sample utility class:

mvn archetype:generate -DgroupId=com.example.common -DartifactId=common -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Date Formatter Utility:

package com.example.common;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class DateUtils {
    public static String formatDate(LocalDate date) {
        return date.format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
    }
}

Domain Module

In the domain module, you will define your data models.

package com.example.domain;

import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class User {
    @Id
    private Long id;
    private String name;

    // Getters and Setters
}

Repository Module

Let’s create the repository module to manage data access. Here’s a basic repository interface:

package com.example.repository;

import com.example.domain.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {}

Service Module

Let’s create the service module to hold your business logic. Here’s an example service class:

package com.example.service;

import com.example.domain.User;
import com.example.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public User getUserById(Long id) {
        return userRepository.findById(id).orElse(null);
    }
}

Web Module

The web module serves as the REST API layer.

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

5. Inter-Module Communication

To avoid direct dependencies, you can use REST APIs or message brokers (like Kafka) for inter-module communication. This ensures loose coupling and allows each module to communicate independently.

The diagram below demonstrates how modules communicate with each other:

The diagram illustrates how different system components communicate to handle requests efficiently.

The Web Module processes incoming API requests and forwards them to the Service Module, which contains the business logic. The Service Module then interacts with the Repository Module to fetch or update data in the Database. This layered approach ensures that each module operates independently, promoting flexibility and easier maintenance.

Example Using Feign Client:

In the context of inter-module communication, using tools like Feign Clients is a powerful way to achieve loose coupling between services.

The Feign client allows one module to seamlessly communicate with another through REST API calls, without requiring direct dependencies. This approach fits perfectly within the layered architecture described earlier, where the Service Module can fetch data from other services or microservices using Feign clients, rather than directly accessing databases or hard-coding HTTP requests.

This not only simplifies the code but also improves scalability and maintainability by isolating service dependencies.

@FeignClient(name = "userServiceClient", url = "http://localhost:8081")
public interface UserServiceClient {
    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);
}

6. Common Pitfalls and Solutions

When implementing a multi-module architecture, you may encounter several challenges. Here are some common pitfalls and their solutions:

• Circular Dependencies: Modules may inadvertently depend on each other, creating a circular dependency that complicates builds and deployments.

  • Solution: Carefully design module interfaces and use dependency management tools to detect and resolve circular dependencies early in the development process.

• Over-Engineering: There's a risk of creating too many modules, leading to unnecessary complexity.

  • Solution: Start with a minimal set of modules and only split further when there's a clear need, ensuring each module has a distinct responsibility.

• Inconsistent Configurations: Managing configurations across multiple modules can lead to inconsistencies.

  • Solution: Use centralized configuration management tools, such as Spring Cloud Config, to maintain consistency across modules.

• Communication Overhead: Inter-module communication can introduce latency and complexity.

  • Solution: Optimize communication by using efficient protocols and consider asynchronous messaging where appropriate to reduce latency.

• Testing Complexity: Testing a multi-module project can be more complex due to the interactions between modules.

  • Solution: Implement a robust testing strategy that includes unit tests for individual modules and integration tests for inter-module interactions.

By being aware of these pitfalls and applying these solutions, you can effectively manage the complexities of a multi-module architecture and ensure a smooth development process.

7. Testing Strategy and Configuration

Testing each module independently and as a unit is critical in multi-module setups.

Unit Tests

Here, we’ll use JUnit and Mockito for performing unit tests:

@RunWith(MockitoJUnitRunner.class)
public class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    public void testGetUserById() {
        User user = new User();
        user.setId(1L);
        user.setName("John");

        Mockito.when(userRepository.findById(1L)).thenReturn(Optional.of(user));

        User result = userService.getUserById(1L);
        assertEquals("John", result.getName());
    }
}

Integration Tests

And we’ll use Testcontainers with an in-memory database for integration tests:

@Testcontainers
@ExtendWith(SpringExtension.class)
@SpringBootTest
public class UserServiceIntegrationTest {

    @Container
    private static PostgreSQLContainer<?> postgresqlContainer = new PostgreSQLContainer<>("postgres:latest");

    @Autowired
    private UserService userService;

    @Test
    public void testFindById() {
        User user = userService.getUserById(1L);
        assertNotNull(user);
    }
}

8. Error Handling and Logging

Error handling and logging ensure a robust and debuggable application.

Error Handling

In this section, we'll explore how to handle errors gracefully in your Spring Boot application using a global exception handler. By using @ControllerAdvice, we'll set up a centralized way to catch and respond to errors, keeping our code clean and our responses consistent.

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException ex) {
        return new ResponseEntity<>("User not found", HttpStatus.NOT_FOUND);
    }
}

In the code example above, we define a GlobalExceptionHandler that catches any UserNotFoundException and returns a friendly message like "User not found" with a status of 404. This way, you don’t have to handle this exception in every controller—you’ve got it covered in one place!

Now, let’s take a look at the diagram. Here’s how it all flows: when a client sends a request to our Web Module, if everything goes smoothly, you'll get a successful response. But if something goes wrong, like a user not being found, the error will be caught by our Global Error Handler. This handler logs the issue and returns a clean, structured response to the client.

This approach ensures that users get clear error messages while keeping your app’s internals hidden and secure.

Logging

Structured logging in each module improves traceability and debugging. You can use a centralized logging system like Logback and include correlation IDs to trace requests.

9. Security and JWT Integration

In this section, we’re going to set up JSON Web Tokens (JWT) to secure our endpoints and control access based on user roles. We'll configure this in the SecurityConfig class, which will help us enforce who can access what parts of our application.

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/admin/**").hasRole("ADMIN")
            .antMatchers("/user/**").hasAnyRole("USER", "ADMIN")
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}

In the code example above, you can see how we’ve defined access rules:

• The /admin/** endpoints are restricted to users with the ADMIN role.

• The /user/** endpoints can be accessed by users with either the USER or ADMIN roles.

• Any other requests will require the user to be authenticated.

Next, we set up our application to validate incoming tokens using .oauth2ResourceServer().jwt();. This ensures that only requests with a valid token can access our secured endpoints.

Now, let’s walk through the diagram. When a client sends a request to access a resource, the Security Filter first checks if the provided JWT token is valid. If the token is valid, the request proceeds to the Service Module to fetch or process the data. If not, access is denied right away, and the client receives an error response.

This flow ensures that only authenticated users can access sensitive resources, keeping our application secure.

10. Deployment with Docker and CI/CD

In this section, we'll containerize each module using Docker to make our application easier to deploy and run consistently across different environments. We’ll also set up a CI/CD pipeline using GitHub Actions (but you can use Jenkins too if you prefer). Automating this process ensures that any changes you push are automatically built, tested, and deployed.

Step 1: Containerizing with Docker

We start by creating a Dockerfile for the Web Module:

FROM openjdk:11-jre-slim
COPY target/web-1.0-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

Here, we’re using a lightweight version of Java 11 to keep our image size small. We copy the compiled .jar file into the container and set it up to run when the container starts.

Step 2: Using Docker Compose for Multi-Module Deployment

Now, we'll use a Docker Compose file to orchestrate multiple modules together:

version: '3'
services:
  web:
    build: ./web
    ports:
      - "8080:8080"
  service:
    build: ./service
    ports:
      - "8081:8081"

With this setup, we can run both the Web Module and the Service Module at the same time, making it easy to spin up the entire application with a single command. Each service is built separately from its own directory, and we expose the necessary ports to access them.

CI/CD Example with GitHub Actions

name: CI Pipeline

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up JDK 11
      uses: actions/setup-java@v2
      with:
        java-version: '11'
    - name: Build with Maven
      run: mvn clean install

This pipeline automatically kicks in whenever you push new code or create a pull request. It checks out your code, sets up Java, and runs a Maven build to ensure everything is working correctly.

11. Best Practices and Advanced Use Cases

The following best practices ensure maintainability and scalability.

Best Practices

• Avoid Circular Dependencies: Ensure modules don’t have circular references to avoid build issues.

• Separate Concerns Clearly: Each module should focus on one responsibility.

• Centralized Configurations: Manage configurations centrally for consistent setups.

Advanced Use Cases

1. Asynchronous Messaging with Kafka: Use Kafka for decoupled communication between services. Modules can publish and subscribe to events asynchronously.

2. REST Client with Feign: Use Feign to call services within modules. Define a Feign client interface for communication.

3. Caching for Performance: Use Spring Cache in the service module for optimizing data retrieval.

Conclusion and Key Takeaways

A multi-module Spring Boot project provides modularity, scalability, and ease of maintenance.

In this tutorial, you learned to set up modules, manage inter-module communication, handle errors, add security, and deploy with Docker.

Following best practices and using advanced techniques like messaging and caching will further optimize your multi-module architecture for production use.

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.

We just published a comprehensive video course on the freeCodeCamp.org YouTube channel, designed to teach you how to use Selenium with Java using the Page Object Model. Created by Rex Jones II, this course is perfect for developers and testers who want to master the art of automated web testing and ensure the functionality of web applications with precision and efficiency.

Course Overview

This course is structured to guide you through the essentials of Selenium, a powerful tool for automating web browsers. Selenium allows you to simulate user interactions and verify the functionality of web applications, making it an indispensable tool for modern web testing. The course is divided into several parts, each focusing on different aspects of Selenium and Java, ensuring a thorough understanding of both the basics and advanced techniques.

Here are the core technologies and concepts in this course:

1. Selenium: At the heart of this course is Selenium, an open-source tool that automates web browsers. It supports various browsers and platforms, allowing testers to write test scripts in multiple programming languages, including Java. Selenium is widely used for functional testing, enabling testers to simulate user actions like clicking, typing, and navigating through web pages.

2. Java: As one of the most popular programming languages, Java is known for its portability, scalability, and robustness. In this course, you'll learn how to leverage Java to write efficient and maintainable test scripts for web applications.

3. Page Object Model (POM): This design pattern is crucial for creating scalable and maintainable test automation frameworks. POM encourages the separation of test scripts from the page-specific code, making it easier to manage and update tests as web applications evolve.

4. WebElements and JavaScriptExecutor: You'll explore how to interact with various web elements such as radio buttons, checkboxes, tables, links, drop-downs, and dates. Additionally, you'll learn how to use JavaScriptExecutor to perform actions like scrolling to elements, enhancing your ability to handle complex web pages.

5. Selenium Interfaces and Methods: The course delves into various Selenium interfaces and methods, teaching you how to take screenshots, handle modals, alerts, frames, and windows. You'll also learn about different wait strategies like explicit, fluent, and implicit waits, which are essential for synchronizing your tests with web application behavior.

6. Simulating User Interactions: Beyond basic interactions, the course covers how to simulate mouse movements and keyboard events, providing you with the skills to automate complex user scenarios.

Conclusion

This course is a valuable resource for anyone looking to deepen their understanding of automated web testing using Selenium and Java. Whether you're a beginner or an experienced tester, the structured approach and practical examples will equip you with the skills needed to create robust and efficient test automation frameworks. Watch the full course on the freeCodeCamp.org YouTube channel (8-hour watch).

In this article, I will introduce you to HashMaps in Java. We will explore the common operations of HashMap and then delve into how it operates internally. You will gain an understanding of the hash function and how index calculation takes place. Finally, we will look at the time complexities of the operations and touch upon the behavior in a concurrent environment.

What is a HashMap in Java?

A HashMap implements the Map interface, which is part of the Java collection framework. It's based on the concept of Hashing.

Hashing is a technique that transforms an input of arbitrary size into a fixed-size output using a hash function. The generated output is called the hash code and is represented by an integer value in Java. Hash codes are used for efficient lookup and storage operations in a HashMap.

Common Operations

Like we discussed above, data in a HashMap is stored in the form of key-value pairs. The key is a unique identifier, and each key is associated with a value.

Below are some common operations supported by a HashMap. Let's understand what these methods do with some simple code examples:

Insertion

• This method inserts a new key-value pair to the HashMap.

• The insertion order of the key-value pairs is not maintained.

• During insertion, if a key is already present, the existing value will be replaced with the new value that is passed.

• You can insert only one null key into the HashMap, but you can have multiple null values.

The method signature for this operation is given below, followed by an example:

public V put(K key, V value)

Map<String, Integer> map = new HashMap<>();
map.put("apple", 1);
map.put("banana", 2);

In the code above, we have a HashMap example where we add a key of type String and value of type Integer.

Retrieval:

• Fetches the value associated with a given key.

• Returns null if the key does not exist in the HashMap.

The method signature for this operation is given below, followed by an example:

public V get(Object key)

Integer value = map.get("apple"); // returns 1

In the code above, we're retrieving the value associated with the key apple.

Other common operations include:

• remove: Removes the key-value pair for the specified key. It returns null if the key is not found.

• containsKey: Checks if a specific key is present in the HashMap.

• containsValue: Checks if the specified value is present in the HashMap.

Internal Structure of a HashMap

Internally, a HashMap uses an array of buckets or bins. Each bucket is a linked list of type Node, which is used to represent the key-value pair of the HashMap.

static class Node<K, V> {
    final int hash;
    final K key;
    V value;
    Node<K, V> next;

    Node(int hash, K key, V value, Node<K, V> next) {
        this.hash = hash;
        this.key = key;
        this.value = value;
        this.next = next;
    }
}

Above, you can see the structure of the Node class which is used to store the key-value pairs of the HashMap.

The Node class has the following fields:

• hash: Refers to the hashCode of the key.

• key: Refers to the key of the key-value pair.

• value: Refers to the value associated with the key.

• next: Acts as a reference to the next node.

The HashMap is fundamentally based on a hash table implementation, and its performance depends on two key parameters: initial capacity and load factor. The original javadocs of the Hash table class define these two parameters as follows:

• The capacity is the number of buckets in the hash table, and the initial capacity is simply the capacity at the time the hash table is created.

• The load factor is a measure of how full the hash table is allowed to get before its capacity is automatically increased.

Let's now try and understand how the basic operations, put and get, work in a HashMap.

Hash Function

During the insertion (put) of a key-value pair, the HashMap first calculates the hash code of the key. The hash function then computes an integer for the key. Classes can use the hashCode method of the Object class or override this method and provide their own implementation. (Read about the hash code contract here). The hash code is then XORed (eXclusive OR) with its upper 16 bits (h >>> 16) to achieve a more uniform distribution.

XOR is a bitwise operation that compares two bits, resulting in 1 if the bits are different and 0 if they are the same. In this context, performing a bitwise XOR operation between the hash code and its upper 16 bits (obtained using the unsigned right shift >>> operator) helps to mix the bits, leading to a more evenly distributed hash code.

static final int hash(Object key) {
    int h;
    return (key == null) ? 0 : (h = key.hashCode()) ^ (h >>> 16);
}

Above, you can see the static hash method of the HashMap class.

The idea is to have a unique hash code for each key, but the hash function could produce the same hash code for different keys. This leads to a situation known as a collision. We will see how to handle collisions in the next section.

Index Calculation

Once the hash code for a key is generated, the HashMap calculates an index within the array of buckets to determine where the key-value pair will be stored. This is done using a bitwise AND operation, which is an efficient way to calculate the modulo when the array length is a power of two.

int index = (n - 1) & hash;

Here, we're calculating the index where n is the length of the bucket array.

Once the index is calculated, the key is then stored at that index in the bucket array. However, if multiple keys end up having the same index, it causes a collision. In such a scenario, the HashMap handles it in one of two ways:

• Chaining/Linking: Each bucket in the array is a linked list of nodes. If a key already exists at a particular index and another key gets hashed to the same index, it gets appended to the list.

• Treeify: If the number of nodes exceeds a certain threshold, the linked list is converted into a tree (This was introduced in Java 8).

static final int TREEIFY_THRESHOLD = 8;

This is the threshold that determines treeification.

Therefore, it is essential to have a good hash function that uniformly distributes the keys across the buckets and minimizes the chances of collisions.

The retrieval (get) and deletion (remove) operations work similarly to the insertion (put) operation. Here's how:

• Retrieval (get): Computes the hash code using the hash function -> calculates the index using the hash code -> traverses the linked list or tree to find the node with the matching key.

• Deletion (remove): Computes the hash code using the hash function -> calculates the index using the hash code -> removes the node from the linked list or tree.

Time Complexity

The basic operations of a HashMap, such as put, get, and remove, generally offer constant time performance of O(1), assuming that the keys are uniformly distributed. In cases where there is poor key distribution and many collisions occur, these operations might degrade to a linear time complexity of O(n).

Under treeification, where long chains of collisions are converted into balanced trees, lookup operations can improve to a more efficient logarithmic time complexity of O(log n).

Synchronization

The HashMap implementation is not synchronized. If multiple threads access a HashMap instance concurrently and iterate over the map, and if any one of the threads performs a structural modification (such as adding or removing a key-value mapping) on the map, it leads to a ConcurrentModificationException.

To prevent this, you can create a thread-safe instance using the Collections.synchronizedMap method.

Conclusion

In summary, understanding the internal workings of a HashMap is crucial for developers to make informed decisions. Knowing how a key is mapped, how collisions happen, and how they can be avoided helps you use the HashMap efficiently and effectively.

However, when it comes to sorting custom objects, such as instances of user-defined classes, the built-in sorting methods fall short. These methods don't know how to order objects based on custom criteria. This is where Java's Comparable and Comparator interfaces come into play, allowing developers to define and implement custom sorting logic tailored to specific requirements.

In this blog post, we'll explore how to use the Comparable and Comparator interfaces to sort custom objects in Java. I'll provide examples to illustrate the differences and use cases for each approach, helping you master custom sorting in your Java applications.

Table of Contents

• Sorting Methods for Primitive Types
• How to Use the Comparable Interface
• How to Use the Comparator Interface
• Comparable vs Comparator
• Wrapping Up

Sorting Methods for Primitive Types

Java provides a variety of built-in sorting methods that make it easy to sort primitive data types. These methods are highly optimized and efficient, allowing you to sort arrays and collections with minimal code. For primitive types, such as integers, floating-point numbers, and characters, the Arrays.sort() method is commonly used.

How to Use the Arrays.sort() Method

The Arrays.sort() method sorts the specified array into ascending numerical order. This method uses a dual-pivot quicksort algorithm, which is faster and more efficient for most data sets.

Let's look at an example of sorting an array of integers and characters using Arrays.sort():

package tutorial;

import java.util.Arrays;

public class PrimitiveSorting {
    public static void main(String[] args) {
        int[] numbers = { 5, 3, 8, 2, 1 };
        System.out.println("Original array: " + Arrays.toString(numbers));

        Arrays.sort(numbers);
        System.out.println("Sorted array: " + Arrays.toString(numbers));

        char[] characters = { 'o', 'i', 'e', 'u', 'a' };
        System.out.println("Original array: " + Arrays.toString(characters));

        Arrays.sort(characters);
        System.out.println("Sorted array: " + Arrays.toString(characters));
    }
}

Output:

Original array: [5, 3, 8, 2, 1]
Sorted array: [1, 2, 3, 5, 8]
Original array: [o, i, e, u, a]
Sorted array: [a, e, i, o, u]

How to Use the Collections.sort() Method

The Collections.sort() method is used to sort collections such as ArrayList. This method is also based on the natural ordering of the elements or a custom comparator.

package tutorial;

import java.util.ArrayList;
import java.util.Collections;

public class CollectionsSorting {
    public static void main(String[] args) {
        ArrayList<String> wordsList = new ArrayList<>();
        wordsList.add("banana");
        wordsList.add("apple");
        wordsList.add("cherry");
        wordsList.add("date");
        System.out.println("Original list: " + wordsList);

        Collections.sort(wordsList);
        System.out.println("Sorted list: " + wordsList);
    }
}

Output:

Original list: [banana, apple, cherry, date]
Sorted list: [apple, banana, cherry, date]

Limitations with Custom Classes

While Java's built-in sorting methods, such as Arrays.sort() and Collections.sort(), are powerful and efficient for sorting primitive types and objects with natural ordering (like String), they fall short when it comes to sorting custom objects. These methods do not inherently know how to order user-defined objects because there is no natural way for them to compare these objects.

For example, consider a simple Person class that has name, age, and weight attributes:

package tutorial;

public class Person {
    String name;
    int age;
    double weight;

    public Person(String name, int age, double weight) {
        this.name = name;
        this.age = age;
        this.weight = weight;
    }

    @Override
    public String toString() {
        return "Person [name=" + name + ", age=" + age + ", weight=" + weight + " kgs]";
    }
}

If we try to sort a list of Person objects using Arrays.sort() or Collections.sort(), we will encounter a compilation error because these methods do not know how to compare Person objects:

package tutorial;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class CustomClassSorting {
    public static void main(String[] args) {
        List<Person> people = new ArrayList<>(Arrays.asList(
                new Person("Alice", 30, 65.5),
                new Person("Bob", 25, 75.0),
                new Person("Charlie", 35, 80.0)
        ));
        System.out.println("Original people list: " + people);

        Collections.sort(people);
        System.out.println("Sorted people list: " + people);
    }
}

Compilation Error:

java: no suitable method found for sort(java.util.List<tutorial.Person>)
    method java.util.Collections.<T>sort(java.util.List<T>) is not applicable
      (inference variable T has incompatible bounds
        equality constraints: tutorial.Person
        lower bounds: java.lang.Comparable<? super T>)
    method java.util.Collections.<T>sort(java.util.List<T>,java.util.Comparator<? super T>) is not applicable
      (cannot infer type-variable(s) T
        (actual and formal argument lists differ in length))

The error occurs because the Person class does not implement the Comparable interface, and there is no way for the sorting method to know how to compare two Person objects.

To sort custom objects like Person, we need to provide a way to compare these objects. Java offers two main approaches to achieve this:

1. Implementing the Comparable Interface: This allows a class to define its natural ordering by implementing the compareTo method.
2. Using the Comparator Interface: This allows us to create separate classes or lambda expressions to define multiple ways of comparing objects.

We will explore both approaches in the upcoming sections, starting with the Comparable interface.

How to Use the Comparable Interface

Java provides a Comparable interface to define a natural ordering for objects of a user-defined class. By implementing the Comparable interface, a class can provide a single natural ordering that can be used to sort its instances. This is particularly useful when you need a default way to compare and sort objects.

Overview

The Comparable interface contains a single method, compareTo(), which compares the current object with the specified object for order. The method returns:

• A negative integer if the current object is less than the specified object.
• Zero if the current object is equal to the specified object.
• A positive integer if the current object is greater than the specified object.

How Comparable Allows for a Single Natural Ordering of Objects

By implementing the Comparable interface, a class can ensure that its objects have a natural ordering. This allows the objects to be sorted using methods like Arrays.sort() or Collections.sort() without the need for a separate comparator.

Let's implement the Comparable interface in a new PersonV2 class, comparing by age.

package tutorial;

public class PersonV2 implements Comparable<PersonV2> {
    String name;
    int age;
    double weight;

    public PersonV2(String name, int age, double weight) {
        this.name = name;
        this.age = age;
        this.weight = weight;
    }

    @Override
    public String toString() {
        return "PersonV2 [name=" + name + ", age=" + age + ", weight=" + weight + " kgs]";
    }

    @Override
    public int compareTo(PersonV2 other) {
        return this.age - other.age;
    }
}

In this implementation, the compareTo() method compares the age attribute of the current PersonV2 object with the age attribute of the specified PersonV2 object by subtracting one age from the other. By using the expression this.age - other.age, we’re effectively implementing this logic as follows:

• If this.age is less than other.age, the result will be negative.
• If this.age is equal to other.age, the result will be zero.
• If this.age is greater than other.age, the result will be positive.

Note: We can also use Integer.compare(this.age, other.age) instead of performing the arithmetic operation manually.

Now that the PersonV2 class implements the Comparable interface, we can sort a list of PersonV2 objects using Collections.sort():

package tutorial;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class CustomClassSortingV2 {
    public static void main(String[] args) {
        List<PersonV2> people = new ArrayList<>(Arrays.asList(
                new PersonV2("Alice", 30, 65.5),
                new PersonV2("Bob", 25, 75.0),
                new PersonV2("Charlie", 35, 80.0)
        ));
        System.out.println("Original people list: " + people);

        Collections.sort(people);
        System.out.println("Sorted people list: " + people);
    }
}

Output:

Original people list: [PersonV2 [name=Alice, age=30, weight=65.5 kgs], PersonV2 [name=Bob, age=25, weight=75.0 kgs], PersonV2 [name=Charlie, age=35, weight=80.0 kgs]]
Sorted people list: [PersonV2 [name=Bob, age=25, weight=75.0 kgs], PersonV2 [name=Alice, age=30, weight=65.5 kgs], PersonV2 [name=Charlie, age=35, weight=80.0 kgs]]

In this example, the PersonV2 objects are sorted in ascending order of age using the Collections.sort() method, which relies on the natural ordering defined by the compareTo() method in the PersonV2 class.

Limitations of Comparable

While the Comparable interface provides a way to define a natural ordering for objects, it has several limitations that can restrict its use in practical applications. Understanding these limitations can help us determine when to use other mechanisms, such as the Comparator interface, to achieve more flexible sorting.

• Single Natural Ordering: The primary limitation of Comparable is that it allows only one natural ordering for the objects of a class. When you implement Comparable, you define a single way to compare objects, which is used whenever the objects are sorted or compared. This can be restrictive if you need to sort objects in multiple ways.
• Inflexibility: If you need to sort objects by different attributes or in different orders, you will have to modify the class or create new implementations of Comparable. This inflexibility can lead to a proliferation of comparison methods and can make the code harder to maintain.
• Non-Adaptable: Once a class implements Comparable, the natural ordering is fixed and cannot be easily changed. For instance, if your PersonV2 class initially sorts by age but later you need to sort by weight or name, you have to either change the compareTo() method or create a new version of the class.

This is where the Comparator interface comes into play. To define multiple ways of comparing objects, we can use the Comparator interface, which we will explore in the next section.

How to Use the Comparator Interface

The Comparator interface in Java provides a way to define multiple ways of comparing and sorting objects. Unlike the Comparable interface, which allows only a single natural ordering, Comparator is designed to offer flexibility by allowing multiple sorting strategies. This makes it particularly useful for scenarios where objects need to be sorted in different ways.

Overview

The Comparator interface defines a single method, compare(), which compares two objects and returns:

• A negative integer if the first object is less than the second object.
• Zero if the first object is equal to the second object.
• A positive integer if the first object is greater than the second object.

This method provides a way to define custom ordering for objects without modifying the class itself.

How Comparator Allows for Multiple Ways of Ordering Objects

The Comparator interface allows you to create multiple Comparator instances, each defining a different ordering for objects. This flexibility means that you can sort objects by various attributes or in different orders without altering the object's class.

Let's implement multiple Comparator instances for the Person class. We'll define comparators for sorting by name, by age, and by weight. First, we need to update the Person class to include getters and ensure that attributes are accessible.

package tutorial;

public class Person {
    String name;
    int age;
    double weight;

    public Person(String name, int age, double weight) {
        this.name = name;
        this.age = age;
        this.weight = weight;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

    public double getWeight() {
        return weight;
    }

    @Override
    public String toString() {
        return "Person [name=" + name + ", age=" + age + ", weight=" + weight + " kgs]";
    }
}

Comparator by Name

This comparator sorts Person objects alphabetically by their name.

package tutorial.comparator;

import tutorial.Person;

import java.util.Comparator;

public class PersonNameComparator implements Comparator<Person> {

    @Override
    public int compare(Person p1, Person p2) {
        return p1.getName().compareTo(p2.getName());
    }
}

Comparator by Age

This comparator sorts Person objects by their age, in ascending order.

package tutorial.comparator;

import tutorial.Person;

import java.util.Comparator;

public class PersonAgeComparator implements Comparator<Person> {

    @Override
    public int compare(Person p1, Person p2) {
        return p1.getAge() - p2.getAge();
    }
}

Comparator by Weight

This comparator sorts Person objects by their weight, in ascending order.

package tutorial.comparator;

import tutorial.Person;

import java.util.Comparator;

public class PersonWeightComparator implements Comparator<Person> {

    @Override
    public int compare(Person p1, Person p2) {
        return (int) (p1.getWeight() - p2.getWeight());
    }
}