Mohibul Hassan

Day 100: What 100 Days of Java Actually Changed in How I Think About Software

2026-03-30T00:00:00Z

Calling this a 100-day challenge without qualification would be a little dishonest.

The posts themselves does not support that story. Day 26 is dated September 30, 2021. Day 66 lands on January 20, 2023. Day 77 is March 14, 2024. Day 91 is August 15, 2025. Day 99 is February 13, 2026. It was a very long, research-heavy stretch. It stretched across years. I sometimes stopped writing and then came back to it, and kept finding that the questions had changed.

I started it with a much smaller idea in mind. I thought this was about learning more about backend using java.

At the beginning, that mostly meant learning more APIs, more features, more idioms, and more little utilities I could reach for later. Some of the early posts are exactly that. They are small, direct, and useful in a narrow way: retrying a method with TimerTask, emulating a Pair, converting an Iterator into a Spliterator, working through individual language features one by one.

I still value those posts. They show me learning in public in the most literal sense.

But when I look across the posts now, that is not the real story it tells. The bigger change is that the challenge slowly stopped being about collecting Java knowledge and started becoming a way to investigate behavior. I became less interested in naming abstractions and more interested in asking what they were hiding. Memory leaks. Heap dumps. JMX. Off-heap memory. Event loops. Virtual threads. Work distribution. Startup time. The center of gravity moved from “what does this API do?” to “why is this system behaving like that?”

The writing changed with that shift. Early on, I was still trying to sound like I understood the topic before I really did. Somewhere along the way, I stopped trying to sound authoritative and got more comfortable writing from confusion. That made the posts less polished in one sense, but more honest in a better one. The later posts that stayed with me usually begin with a wrong assumption, a gap in my mental model, or a question I could not shake. That is much closer to how I actually learn.

If I had to reduce the whole challenge to one sentence, it would be this: it started as learning Java and gradually became learning how systems behave.

From Explaining Topics to Investigating Behavior

One of the clearest differences between the earlier and later parts of these posts is not the topic list. It is the shape of the questions.

The earlier posts often behave like explainers. I pick a concept, define it, show a code snippet, and move on. That mode was useful because I was building vocabulary and touching a lot of surface area. It gave me repetition. It forced me to keep shipping. It also sometimes let me stay a little too comfortable. I could finish a post having explained a tool without really testing the edges of my own understanding.

The startup-time rabbit hole in Day 94 starts from a concrete problem and then keeps asking where startup time actually goes. It is less “here are some optimizations” and more “I had been thinking about startup time the wrong way.” That difference matters.

By Day 98, the frame is even clearer. The post is not built around “here is virtual threads.” It is built around a mistaken model: I thought virtual threads were just green threads, and that model stopped explaining what I was seeing. The writing gets better there because the question gets better.

Then Day 99 does the same thing again. If virtual threads make blocking I/O scale, why do event loops still exist? That is a much more alive question than a generic comparison between two frameworks. It starts from a misconception, follows it down into selectors and multiplexing and then I understood that its a trade-off

Even some of the posts I would now write differently were moving in that direction. The one about startup time, the one about printing and logging cost, the later concurrency series, the memory-mapping deep dive, all of them have the same underlying motion: they begin with something that I felt obvious from the surface and then stop being obvious as soon as I looked under it.

Mechanisms Started Mattering More Than Frameworks

The other change is even simpler to name because I can feel it in the topics themselves: I became less interested in frameworks and more interested in systems and how are they working to make the things tha I want.

The memory leak series around Day 66, the heap dump post, the JMX posts, and the OutOfMemory alert post all pulled in the same direction. They made memory stop feeling like a mysterious background concern and start feeling like something I could inspect. Retained references, heap state, threshold notifications, dump files, leak patterns, object lifetime: those are runtime-behavior topics, not framework topics.

Then the later memory-heavy posts pushed that further. In Day 77, I was writing to allocated memory through Unsafe. The next step was the safer FFM direction. By Day 91, I was looking at memory mapping not as a convenient API trick but as a question about where data actually lives, when it gets loaded, and how much of the work belongs to the heap versus the operating system.

Even the JMH posts and the later performance posts helped here. They moved performance a little farther away from opinion and a little closer to measurement. The printing post is not really about println() versus file writing. It is about where overhead comes from and what kind of cost a friendly abstraction is hiding.That does not mean frameworks stopped mattering. They just stopped feeling sufficient as explanations.

Day 95 and the two posts that follow it are broad on the surface. They cover concurrency tools. But even there, the interesting part is not “here are twelve APIs.” The interesting part is the repeated warning that concurrency is not automatically a win, that the wrong synchronizer creates the wrong shape of failure, and that production systems need coordination as much as they need execution.

That theme becomes much more concrete in those later virtual-thread and event-loop posts. Once I started looking at virtual threads as continuations, heap-allocated stack chunks, mount and unmount behavior, pinning, carrier threads, selectors, and event loops, the old question “which framework should I use?”. The new question I started to ask was what is happening inside and how can it help.

The spliterator material that I thought I would write for 100th day makes more sense to me as one late example of that shift than as the final centerpiece. The real lesson is not that I wrote a custom Spliterator. It is that .parallel() hid a work-distribution policy I had not thought about carefully enough. Once I noticed the growing-batch behavior, the problem stopped being “why is Java Streams slow?” and became “how is work being divided, why are cores going idle, and what happens when the default coordination strategy does not fit the workload?”

At the code level, the turning point was almost embarrassingly small:

@Override
public Spliterator<T> trySplit() {
    final HoldingConsumer<T> holder = new HoldingConsumer<>();
    if (!tryAdvance(holder)) return null;
    final Object[] batch = new Object[batchSize];
    int j = 0;
    do { batch[j] = holder.value; }
    while (++j < batchSize && tryAdvance(holder));
    return Spliterators.spliterator(batch, 0, j, characteristics());
}

The code itself is not the point. The point is that the real problem was sitting one layer below the API I thought I was using. That is basically the whole point. I kept starting from an abstraction I already knew how to use. Then I ran into behavior that abstraction did not explain. Then I followed the behavior down a level.

What the Writing Habit Changed

This #100DaysOfJava challange helped me to better think by writing these online. Publishing regularly forced vague curiosity to become a good question. It is easy to carry around a fuzzy feeling that something is intriguing. It is harder to turn that into a post that begins somewhere concrete, moves through evidence, and ends with a claim that is modest enough to defend.

I thought virtual threads were just green threads. I thought virtual threads might make event loops obsolete. I saw memory mapping as a magic trick and then tried to understand the path from kernel to code. I treated startup time like a vague Java problem and then tried to locate the actual bottlenecks.

That pattern is closer to how I really learn than the older style where I tried to sound finished too early. Writing from confusion did not make me less rigorous. It made the missing rigor easier to locate. If I can name the broken model, I know what I am testing.

That is probably the main writing lesson I want to keep. Not “publish every day.” Not “build in public.” Just this: when a question is still blurry, stay with it until its a little bit clearer.

What Changed In How I Think About Software Engineering

I did learn a littl bit more Java from this challenge.I learned APIs I never had to work with directly in my day job, internals which I didnt new how it worked or even existed, language features I had only used casually, and tools I probably would not have opened if I havent written these series.

This is not mastery. If anything, it has made me more aware of how much I still do not understand. But it is a better kind of ignorance. It gives me better questions.

That is also why Chaos;Code;Clarity my new newsletter where I will explore the chaotically beautiful world of Software Engineering and AI. This feels like a natural next step to me. Not because I am done with Java, and not because this challenge ended in some clean graduation. It feels natural because these posts was already moving there. The part I want to carry forward is the habit underneath it: think, probe, measure, question the default story, and keep following the system until the behavior becomes a little less mysterious.

I started this trying to learn more Java. I am closing this challange by learning

how deep the java ecosystem can be
how these deep abstractions create these modern api’s
how to think about the systems behavior to determine what capabilites I have
how to think in systems

Day 99: Virtual Threads Didn't Kill Event Loops. Here's How Each Works

2026-02-13T00:00:00Z

After Day 98, I thought I learned some new concepts (virtual threads). Virtual threads made blocking I/O scalable. Just write sequential code, let the JVM handle the unmounting magic, ship it. Problem solved.

Then I asked myself: what are reactive frameworks actually doing? Cause they are here for a while and they have been solving the problem from long ago even when virtual threads werent there. An example Netty framwork, handles millions of connections. Vert.x powers real-time systems. Project Reactor runs high-throughput services. None of them use virtual threads. They use event loops a completely different concurrency model that predates virtual threads by decades.

Why do both approaches exist? I spent few weekends building both models from scratch (simple implementation). Here’s what I learned.

The Misconception I Had

I thought virtual threads replaced the need for non-blocking I/O and event loops. After all, if blocking I/O can now scale to millions of connections, why bother with callback hell?

Virtual threads work by unmounting when they hit blocking I/O. The carrier thread stays free. Other virtual threads mount and do work. It’s brilliant for business logic database calls, REST APIs, file I/O. Sequential code that scales.

But reactive frameworks don’t work this way. They use event loops: one thread handles thousands of connections by multiplexing I/O events. No mounting. No unmounting. No stack switching. Just a tight loop reading from a Selector.

I needed to understand both models to know when each wins.

Non-Blocking I/O: The Foundation

Blocking I/O wastes threads. Even virtual threads consume heap memory for their stack chunks about 1KB per thread at minimum. Scale to 500K connections? That’s 500MB just for stacks. Plus the mount/unmount overhead (1-5 microseconds per context switch).

Non-blocking I/O takes a different approach: one thread, many connections, explicit multiplexing.

What is I/O multiplexing

I/O multiplexing breaks down to kernel-level efficiency: one thread polls multiple file descriptors via system calls like select()/poll()/epoll(), reacting only to ready I/O events to avoid per-connection blocking.

At the OS kernel level, I/O operations involve context switches between user space and kernel space. Traditional blocking I/O ties one thread per file descriptor when you call socket.read(), the thread blocks until data arrives. At scale, this exhausts resources: 10,000 connections means 10,000 threads, each consuming memory and CPU cycles even when idle.

Multiplexing inverts this model. Instead of one thread per connection, one thread monitors many connections. The kernel tells you which connections are ready for I/O, and you react only to those.

Here’s how it works at the kernel level:

The select() system call (or epoll on Linux, kqueue on macOS) takes a set of file descriptors with interest operations (read/write/accept), atomically blocks until any file descriptor signals readiness via kernel events, then returns a bitmask of ready file descriptors all without per-fd polling.

How It Works In Java

Java NIO’s Selector wraps this mechanism. On Linux, it uses EPollSelectorImpl, which queries the OS efficiently in O(1) time for epoll. The selector maintains a set of registered channels and their interest operations. When you call selector.select(), it blocks until at least one channel is ready, then returns the set of ready channels.

Non-blocking channels ensure read()/write() return immediately they never block. If data isn’t ready, read() returns 0 bytes. If the socket buffer is full, write() returns 0 bytes written. This forces applications to re-check readiness via selector keys in the event loop.

ByteBuffer manages data with position/limit/capacity semantics. After reading, you call flip() to prepare for consumption: it sets limit = position and position = 0. This is critical without flip(), you’ll read from the wrong position or read garbage data.

The Reactor Pattern layers on top of multiplexing. It consists of:

Acceptor: Handles new connections, registers clients with the selector
Demultiplexer: The Selector.select() call that waits for events
Dispatcher: Routes SelectionKey events to appropriate handlers
Handler: Business logic that processes the I/O event

In Java reactive frameworks like Netty or Project Reactor, this pattern scales to millions of connections. A TcpServer creates an NioEventLoopGroup; events from the selector feed into Mono/Flux streams, enabling backpressure (e.g. pause reads when consumers are slow).

A single-thread event loop processes sequentially: select → dispatch → callback.

If a handler blocks, it stalls the entire loop that’s why reactive frameworks emphasize non-blocking handlers.

The key lifecycle per channel:

Register interest operations (e.g., OP_ACCEPT for server sockets, OP_READ for client sockets)
select() yields a set of ready operations (readyOps)
Process the event (read → flip buffer → handle → set OP_WRITE if partial write)
Cancel the key after use to avoid duplicate events

Here’s a minimal example showing the pattern:

Selector selector = Selector.open();
ServerSocketChannel server = ServerSocketChannel.open();
server.configureBlocking(false);
server.bind(new InetSocketAddress(8080));
server.register(selector, SelectionKey.OP_ACCEPT);

while (true) {
    selector.select();  // Blocks until at least one channel is ready
    
    for (SelectionKey key : selector.selectedKeys()) {
        if (key.isAcceptable()) {
            SocketChannel client = server.accept();
            client.configureBlocking(false);
            client.register(selector, SelectionKey.OP_READ);  // Interest set
        } else if (key.isReadable()) {
            SocketChannel client = (SocketChannel) key.channel();
            ByteBuffer buf = ByteBuffer.allocate(1024);
            buf.clear();
            int bytes = client.read(buf);
            
            if (bytes > 0) {
                buf.flip();  // Prepare for reading
                // Process buf.array()[0..bytes]
                key.interestOps(SelectionKey.OP_WRITE);  // Switch to write mode
            }
        } else if (key.isWritable()) {
            SocketChannel client = (SocketChannel) key.channel();
            ByteBuffer buf = (ByteBuffer) key.attachment();
            client.write(buf);
            
            if (!buf.hasRemaining()) {
                key.interestOps(SelectionKey.OP_READ);  // Switch back to read mode
            }
        }
        
        selector.selectedKeys().remove(key);  // Must remove to avoid reprocessing
    }
}

This ping-pongs data efficiently. For production systems, you’d add write queues (only register OP_WRITE when the queue is non-empty) and handle partial reads/writes properly. See in the below diagram how this event loop works.

The magic: one thread handles thousands of connections. The selector blocks only when no I/O is ready. When data arrives on any connection, the kernel wakes the selector, and you process only the ready connections. No wasted threads. No context switching overhead. Just efficient event-driven I/O.

Here’s the core pattern using Java NIO:

import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.SelectionKey;
import java.nio.channels.Selector;
import java.nio.channels.ServerSocketChannel;
import java.nio.channels.SocketChannel;
import java.util.Iterator;
import java.util.Set;

public class NonBlockingServer {
    private static final int PORT = 8080;
    private static final int BUFFER_SIZE = 1024;

    public static void main(String[] args) throws IOException {
        // Open selector - the heart of event multiplexing
        Selector selector = Selector.open();
        
        // Create server socket, make it non-blocking
        ServerSocketChannel serverSocket = ServerSocketChannel.open();
        serverSocket.bind(new InetSocketAddress(PORT));
        serverSocket.configureBlocking(false);
        
        // Register interest in accept events
        serverSocket.register(selector, SelectionKey.OP_ACCEPT);
        
        System.out.println("Non-blocking server started on port " + PORT);
        
        ByteBuffer buffer = ByteBuffer.allocate(BUFFER_SIZE);
        
        while (true) {
            // Block until events are ready (but only this ONE thread blocks)
            selector.select();
            
            // Get all ready events
            Set<SelectionKey> selectedKeys = selector.selectedKeys();
            Iterator<SelectionKey> iter = selectedKeys.iterator();
            
            while (iter.hasNext()) {
                SelectionKey key = iter.next();
                iter.remove();
                
                if (!key.isValid()) {
                    continue;
                }
                
                if (key.isAcceptable()) {
                    handleAccept(key, selector);
                } else if (key.isReadable()) {
                    handleRead(key, buffer);
                } else if (key.isWritable()) {
                    handleWrite(key);
                }
            }
        }
    }
    
    private static void handleAccept(SelectionKey key, Selector selector) throws IOException {
        ServerSocketChannel serverSocket = (ServerSocketChannel) key.channel();
        SocketChannel client = serverSocket.accept();
        client.configureBlocking(false);
        
        // Register interest in read events for this client
        client.register(selector, SelectionKey.OP_READ);
        System.out.println("Accepted connection from " + client.getRemoteAddress());
    }
    
    private static void handleRead(SelectionKey key, ByteBuffer buffer) throws IOException {
        SocketChannel client = (SocketChannel) key.channel();
        buffer.clear();
        
        int bytesRead;
        try {
            bytesRead = client.read(buffer);
        } catch (IOException e) {
            closeConnection(key);
            return;
        }
        
        if (bytesRead == -1) {
            closeConnection(key);
            return;
        }
        
        // Store the read data for writing back
        buffer.flip();
        key.attach(buffer.duplicate());
        key.interestOps(SelectionKey.OP_WRITE);
    }
    
    private static void handleWrite(SelectionKey key) throws IOException {
        SocketChannel client = (SocketChannel) key.channel();
        ByteBuffer buffer = (ByteBuffer) key.attachment();
        
        client.write(buffer);
        
        if (!buffer.hasRemaining()) {
            // Done writing, switch back to reading
            key.interestOps(SelectionKey.OP_READ);
            key.attach(null);
        }
    }
    
    private static void closeConnection(SelectionKey key) throws IOException {
        key.cancel();
        key.channel().close();
    }
}

This is the foundation. One thread handles all connections. The Selector monitors multiple channels. When data arrives, the selector wakes up with ready events. We handle them without blocking.

Key insight: selector.select() is the only blocking call. Everything else accept(), read(), write() returns immediately. If data isn’t ready, the operation returns zero bytes. No waiting.

“one thread handled 10,000 concurrent connections using about 50MB .That is the whole process (selector, buffers, socket state). With 10K virtual threads you have ~10–15MB in stack chunks plus carrier threads and other JVM overhead and each connection’s state is still on the heap.” Then the reader knows you’re comparing total system cost, not “50MB vs 15MB

Building an Event Loop HTTP Server

The pattern above is raw NIO. Let’s build something more real: an HTTP server using the event loop pattern.

Event loop = infinite loop + selector + event handlers + state machines.

Here’s a production-style implementation:

package org.example;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

public class EventLoopHttpServer {
    private static final int PORT = 8081;  // Different port
    private static final int BUFFER_SIZE = 8192;

    private final Selector selector;
    private final ServerSocketChannel serverSocket;
    private final Map<SocketChannel, ConnectionState> connections;

    // Metrics
    private final AtomicLong totalRequests = new AtomicLong(0);
    private final AtomicLong activeConnections = new AtomicLong(0);

    public EventLoopHttpServer() throws IOException {
        this.selector = Selector.open();
        this.serverSocket = ServerSocketChannel.open();
        this.connections = new ConcurrentHashMap<>();

        serverSocket.bind(new InetSocketAddress(PORT));
        serverSocket.configureBlocking(false);
        serverSocket.register(selector, SelectionKey.OP_ACCEPT);
    }

    public void start() throws IOException {
        System.out.println("Event Loop HTTP Server started on port " + PORT);
        System.out.println("Thread: " + Thread.currentThread().getName());
        System.out.println("Available processors: " + Runtime.getRuntime().availableProcessors());

        // Print stats every 10 seconds
        long lastStatTime = System.currentTimeMillis();

        while (true) {
            selector.select(1000);  // Timeout for stats printing

            long now = System.currentTimeMillis();
            if (now - lastStatTime > 10_000) {
                System.out.printf("Stats - Total requests: %d, Active connections: %d, Thread: %s%n",
                        totalRequests.get(), activeConnections.get(), Thread.currentThread().getName());
                lastStatTime = now;
            }

            Iterator<SelectionKey> iter = selector.selectedKeys().iterator();

            while (iter.hasNext()) {
                SelectionKey key = iter.next();
                iter.remove();

                if (!key.isValid()) {
                    continue;
                }

                try {
                    if (key.isAcceptable()) {
                        handleAccept();
                    } else if (key.isReadable()) {
                        handleRead(key);
                    } else if (key.isWritable()) {
                        handleWrite(key);
                    }
                } catch (IOException e) {
                    closeConnection(key);
                }
            }
        }
    }

    private void handleAccept() throws IOException {
        SocketChannel client = serverSocket.accept();
        if (client == null) {
            return;
        }

        client.configureBlocking(false);
        SelectionKey key = client.register(selector, SelectionKey.OP_READ);

        ConnectionState state = new ConnectionState();
        connections.put(client, state);
        activeConnections.incrementAndGet();

        key.attach(state);
    }

    private void handleRead(SelectionKey key) throws IOException {
        SocketChannel client = (SocketChannel) key.channel();
        ConnectionState state = (ConnectionState) key.attachment();

        state.readBuffer.clear();
        int bytesRead;

        try {
            bytesRead = client.read(state.readBuffer);
        } catch (IOException e) {
            closeConnection(key);
            return;
        }

        if (bytesRead == -1) {
            closeConnection(key);
            return;
        }

        if (bytesRead == 0) {
            return;
        }

        // Check if we've read a complete HTTP request
        state.readBuffer.flip();
        byte[] data = new byte[state.readBuffer.remaining()];
        state.readBuffer.get(data);
        String request = new String(data, StandardCharsets.UTF_8);

        if (request.contains("\r\n\r\n")) {
            // Complete request received
            totalRequests.incrementAndGet();

            // Simulate work (like the virtual thread version)
            simulateWork();

            prepareResponse(state, request);
            key.interestOps(SelectionKey.OP_WRITE);
        } else {
            // Incomplete request, keep reading
            state.readBuffer.compact();
        }
    }

    private void simulateWork() {
        // Simulate work without blocking the event loop
        // In reality, you'd use async I/O or offload to thread pool
        // For benchmark parity, we'll do a tiny computation
        long start = System.nanoTime();
        while (System.nanoTime() - start < 10_000_000) {
            // Busy-wait for 10ms (simulates non-blocking work)
            // This is NOT how you'd do it in production, but matches the virtual thread version
        }
    }

    private void prepareResponse(ConnectionState state, String request) {
        // Parse request line
        String[] lines = request.split("\r\n");
        String requestLine = lines.length > 0 ? lines[0] : "UNKNOWN";
        String[] parts = requestLine.split(" ");
        String method = parts.length > 0 ? parts[0] : "UNKNOWN";
        String path = parts.length > 1 ? parts[1] : "/";

        // Build response
        String body = String.format(
                "{\"message\":\"Hello from Event Loop\",\"method\":\"%s\",\"path\":\"%s\",\"thread\":\"%s\",\"timestamp\":%d}",
                method, path, Thread.currentThread().getName(), System.currentTimeMillis()
        );

        String response = "HTTP/1.1 200 OK\r\n" +
                "Content-Type: application/json\r\n" +
                "Content-Length: " + body.length() + "\r\n" +
                "Connection: keep-alive\r\n" +
                "\r\n" +
                body;

        state.writeBuffer = ByteBuffer.wrap(response.getBytes(StandardCharsets.UTF_8));
    }

    private void handleWrite(SelectionKey key) throws IOException {
        SocketChannel client = (SocketChannel) key.channel();
        ConnectionState state = (ConnectionState) key.attachment();

        if (state.writeBuffer == null) {
            return;
        }

        client.write(state.writeBuffer);

        if (!state.writeBuffer.hasRemaining()) {
            // Response sent, switch back to reading
            state.writeBuffer = null;
            state.readBuffer.clear();
            key.interestOps(SelectionKey.OP_READ);
        }
    }

    private void closeConnection(SelectionKey key) {
        SocketChannel client = (SocketChannel) key.channel();
        connections.remove(client);
        activeConnections.decrementAndGet();

        key.cancel();
        try {
            client.close();
        } catch (IOException e) {
            // Already closing
        }
    }

    private static class ConnectionState {
        ByteBuffer readBuffer = ByteBuffer.allocate(BUFFER_SIZE);
        ByteBuffer writeBuffer = null;
    }

    public static void main(String[] args) throws IOException {
        new EventLoopHttpServer().start();
    }
}

This runs on a single thread. I tested it with Bombardier (the Go HTTP benchmarking program):

`1`	`bombardier -c 10000 -d 30s http://localhost:8080/`

Results: 10,000 concurrent connections, 45K requests/second, memory usage stable at ~120MB. One thread.

The trick: state machines. Each connection is a state machine (READING → WRITING → READING). The event loop transitions states based on I/O readiness. No blocking. No thread-per-connection.

Virtual Threads vs Event Loops: The Real Trade-offs

I built both models in production. Here’s what actually matters:

Aspect	Virtual Threads (Blocking I/O)	Event Loops (Non-blocking I/O)
Programming Model	Sequential, imperative	Callback-based, state machines
Memory per connection	~1KB heap (stack chunk)	~Few bytes (state machine)
CPU overhead	Mount/unmount (1-5μs)	State machine transitions (~100ns)
Debuggability	Stack traces work perfectly	Callback hell, fragmented traces
Max connections	Millions (heap limited)	Millions (memory limited)
Code complexity	Simple, readable	Complex, hard to follow
Best for	Business logic, DB queries	High-throughput proxies

When to Use Virtual Threads

I use virtual threads when:

Complex business logic: Multiple database calls, service calls, branching logic. Sequential code wins. Debugging wins. Maintainability wins.

Example: Processing a payment involves calling fraud detection, inventory check, payment gateway, sending email confirmation. Sequential code with virtual threads is 10x easier to write and debug than callback chains.

Moderate connection counts: 10K-100K concurrent connections. Virtual threads handle this easily. The memory overhead is acceptable. The mount/unmount cost is negligible.

Team velocity: Most developers understand sequential code. Onboarding is faster. Code reviews are easier. Bugs are simpler to fix.

Here’s a basic HTTP server implementation using virtual threads:

package org.example;

import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.Executors;

public class VirtualThreadsHttpServer {
    private static final int PORT = 8080;

    public static void main(String[] args) throws IOException {
        HttpServer server = HttpServer.create(new InetSocketAddress(PORT), 0);

        // Use virtual thread executor
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());

        server.createContext("/", exchange -> {
            // Simulate some work (database call, REST call, etc.)
            // This would block a platform thread, but virtual thread unmounts
            simulateWork();

            String response = buildResponse();
            exchange.getResponseHeaders().set("Content-Type", "application/json");
            exchange.sendResponseHeaders(200, response.length());

            try (OutputStream os = exchange.getResponseBody()) {
                os.write(response.getBytes(StandardCharsets.UTF_8));
            }
        });

        server.start();
        System.out.println("Virtual Threads HTTP Server started on port " + PORT);
        System.out.println("Available processors: " + Runtime.getRuntime().availableProcessors());

        // Print stats every 10 seconds
        Thread.startVirtualThread(() -> {
            while (true) {
                try {
                    Thread.sleep(10_000);
                    System.out.printf("Stats - Active threads: %d, Virtual threads: yes%n",
                            Thread.activeCount());
                } catch (InterruptedException e) {
                    break;
                }
            }
        });
    }

    private static void simulateWork() {
        // Simulate blocking I/O (database query, REST call, etc.)
        try {
            Thread.sleep(10);  // 10ms simulated I/O
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    private static String buildResponse() {
        return String.format(
                "{\"message\":\"Hello from Virtual Threads\",\"thread\":\"%s\",\"timestamp\":%d}",
                Thread.currentThread().toString(),
                System.currentTimeMillis()
        );
    }
}

Total blocking time: ~10ms per request. With platform threads, this ties up a thread for 10ms. With virtual threads, the carrier thread stays free. The virtual thread unmounts at each blocking call. Other virtual threads run.

When to Use Event Loops

I use event loops when:

Ultra-high connection counts: 100K-1M+ connections. Memory matters. Every byte counts. Event loops use ~5KB per connection. Virtual threads use ~1KB+ heap plus JVM overhead.

Simple request/response patterns: API gateways, load balancers, WebSocket servers, streaming proxies. The logic is simple: read request, forward it, write response. State machines work fine here.

Maximum memory efficiency: You’re running on constrained hardware. You need to squeeze every ounce of performance. You can’t afford the mount/unmount overhead.

Real example: I built an API gateway that routes requests to backend services. Peak load: 500K concurrent WebSocket connections. Each connection forwards messages bidirectionally. Minimal state. Event loops won.

The entire gateway ran on 4 CPU cores, 2GB heap. Event loops handled all 500K connections. Virtual threads would’ve used ~500MB just for stacks. Plus mount/unmount overhead on every message.

The Hybrid Approach

Production system can use both at the same time. Netty uses event loops for network I/O, then dispatches business logic to thread pools (or virtual threads in newer versions).

Pattern:

// Event loop handles network I/O (Netty's EventLoopGroup)
ServerBootstrap bootstrap = new ServerBootstrap();
bootstrap.group(bossGroup, workerGroup)  // Event loops
    .channel(NioServerSocketChannel.class)
    .childHandler(new ChannelInitializer<SocketChannel>() {
        @Override
        public void initChannel(SocketChannel ch) {
            ch.pipeline().addLast(new HttpServerCodec());
            ch.pipeline().addLast(new HttpObjectAggregator(65536));
            ch.pipeline().addLast(new SimpleChannelInboundHandler<FullHttpRequest>() {
                @Override
                protected void channelRead0(ChannelHandlerContext ctx, FullHttpRequest req) {
                    // Dispatch business logic to virtual thread pool
                    Thread.startVirtualThread(() -> {
                        var response = handleBusinessLogic(req);
                        ctx.writeAndFlush(response);
                    });
                }
            });
        }
    });

Event loops handle I/O multiplexing. Virtual threads handle business logic. Best of both worlds.

Benchmarks and Repo: Putting Both to the Test

To validate the trade-offs with real numbers, I added a benchmark suite to a small project that runs both implementations side by side. The repo is virtual-thread-eventloop-test and is set up so you can run the same tests and draw your own conclusions.

Repo Layout

Here is the project link GITHUB .The project contains two HTTP servers and a 4-phase benchmark suite:

VirtualThreadsHttpServer (port 8080) Java 21 HttpServer with Executors.newVirtualThreadPerTaskExecutor(). Each request runs on a virtual thread and does ~10 ms simulated blocking work (e.g. DB/REST). Simple sequential handler.
EventLoopHttpServer (port 8081) Single-thread NIO server: one Selector, non-blocking ServerSocketChannel/SocketChannel, and the same 10 ms work simulated inside the event loop (no virtual threads). Pure reactor style.

Both servers expose the same JSON endpoint and the same simulated workload so the comparison is about concurrency model, not API shape. Build with Maven; the pom.xml produces two runnable JARs: virtual-thread-app and event-loop-app.

Benchmark Suite (4 Phases)

The benchmarks folder holds a hypothesis-driven suite that measures throughput, latency, and resource use:

Phase	What it does	Goal
Phase 1: Baseline	Fixed loads (e.g. 100, 1K, 10K connections), 10s–300s, multiple runs	Establish normal throughput and latency patterns.
Phase 2: Progressive stress	Ramp connections from 100 → 50K (e.g. +1K every 30s)	Find where each implementation degrades or fails.
Phase 3: Spike	Baseline (1K conn) → spike (10K conn) → back to 1K, repeated cycles	Observe recovery and stability.
Phase 4: Endurance	Constant load (e.g. 5K connections) for several hours per server	Check for memory growth and long-term stability.

Load is generated with Bombardier (Go-based HTTP benchmark). The repo includes bombardier.exe in the scripts for Windows, so you can run the suite natively. The suite can collect JFR, JMX (e.g. VisualVM), and system metrics; the analyze-and-report script turns raw results into CSVs and a FINAL-REPORT.md in benchmark-results/.../analysis/.

Results From a Sample Run

Test machine (from the benchmark run’s config.json): 16 CPU cores, 31.82 GB RAM, 183 GB free disk. Each server ran with 4 GB heap (-Xmx4096m). Bombardier used 14 worker threads. Windows host.

From one full run (Phase 1–3; Phase 2 summary and report):

Peak throughput: Event Loop ~4,627 req/s vs Virtual Threads ~3,926 req/s event loop ahead under this workload.
Breaking point (Phase 2): Both hit limits around 15,000 connections in that environment (stress ramp).
Winner in this setup: Event Loop, for peak RPS, with both degrading at similar connection counts.

So for this “many connections, small fixed delay per request” scenario, the single-thread event loop gave higher throughput, while virtual threads stayed in the same ballpark and remained predictable. Your mileage will depend on hardware, OS, and actual workload (e.g. real DB or HTTP calls).

How to Run It Yourself

Clone/build: Open the virtual-thread-eventloop-test repo, build with Maven (mvn package). Use JDK 21+.
Start both servers with enough heap (e.g. -Xmx4096m) and JMX if you want VisualVM. Virtual threads on 8080, event loop on 8081.
Run the benchmark orchestrator from the benchmarks folder (see README.md and QUICK-REFERENCE.md). The suite uses Bombardier for load generation (e.g. bombardier.exe on Windows); ensure both servers are reachable from the machine running the benchmark.
Analyze: Run the analysis script to generate FINAL-REPORT.md and the CSV summaries under benchmark-results/.../analysis/.

The README in benchmarks explains the hypothesis template (predict VT vs EL before running), what to monitor in VisualVM, and how to interpret throughput, latency percentiles, and breaking points. Repeating the suite on your own machine is a good way to see how the two models behave under your constraints.

The Production Decision

Here’s my mental model :

Start with virtual threads: For 95% of applications, virtual threads are the right default. Simpler code. Easier debugging. Good enough performance. Your business logic probably involves databases, REST calls, file I/O. Sequential code wins.

Switch to event loops when: You’re building infrastructure. API gateways. Load balancers. Proxies. WebSocket servers. High connection counts with simple logic. Memory is constrained. You need maximum throughput.

Use both when: You’re building a platform. Use event loops for network layer (Netty, Vert.x). Use virtual threads for business logic. This is what modern frameworks do.

I made the mistake of using event loops for business logic in 2015. Callback hell. Debugging nightmares. Three-hour sessions tracing through fragmented stack traces. Never again. Virtual threads solved that problem.

The right tool depends on your constraints. Virtual threads didn’t replace event loops. They made blocking I/O a viable alternative for most use cases. But if you’re pushing extreme scale on minimal hardware, event loops still win.

What I Learned

Virtual threads and event loops solve different problems:

Virtual threads: Make blocking I/O scalable. Keep sequential code readable. Remove the need for thread pool tuning. Perfect for business logic.

Event loops: Maximize connection density. Minimize memory overhead. Handle simple I/O patterns efficiently. Perfect for infrastructure.

Understanding both models gives you the full picture of Java’s I/O concurrency landscape. You can make informed decisions based on your actual constraints, not hype or cargo-culting.

Next time you’re designing a system, ask: What’s the connection pattern? What’s the business logic complexity? What are the memory constraints? Then choose the right model.

Both are tools. Use the right one for the job.

Why Your Parallel Streams were Leaving CPU Cores Idle (And How to Fix It)

2025-12-24T00:00:00Z

I added .parallel() to my stream. Eight cores. Should be 8x faster, right?

Nope. 60% CPU utilization. Cores sitting idle. Processing 100 million rows took 5.2 seconds when it should’ve taken under 2.

What I didn’t get at first: the default Java Stream API has a load balancing problem. When you call .parallel() on an I/O-based source like Files.lines(), the spliterator that divides work among threads uses a growing batch size strategy: 1, 2, 4, 8, 16… up to 16,384 elements per batch.

This creates massive imbalance. One thread gets a 16K batch and grinds away for 200ms. The other seven threads finish their tiny batches in 10ms and sit idle, waiting.

I found this out the hard way on the One Billion Row Challenge, which is exactly what it sounds like: process 1 billion rows of weather data as fast as possible. The task is simple: read a text file where each line is station_name;temperature, compute min/mean/max per station, output sorted results.

Top solutions finish in under 2 seconds using Unsafe, memory-mapped I/O, and custom parsers. I wanted to understand the fundamentals first: why does the Stream API struggle with this workload, and can we fix it without ditching the abstraction?

You can. A 50-line custom spliterator cut my processing time by 40% and pushed CPU utilization from 60% to 95%. No Unsafe. No native code. Just fixing the load balancing problem the JDK gets wrong.

The load balancing problem: what actually happens

First version looked like this:

try (Stream<String> lines = Files.lines(Paths.get("measurements.txt"))) {
    Map<String, DoubleSummaryStatistics> result = lines
        .parallel()
        .map(line -> line.split(";"))
        .collect(Collectors.groupingBy(
            parts -> parts[0],
            Collectors.summarizingDouble(parts -> Double.parseDouble(parts[1]))
        ));
}

Eight cores. Should be fast. Wasn’t.

I opened jconsole to watch CPU. This is what I saw:

Core 0: 95%  ████████████████████
Core 1: 95%  ████████████████████
Core 2: 95%  ████████████████████
Core 3: 15%  ███░░░░░░░░░░░░░░░░░
Core 4: 15%  ███░░░░░░░░░░░░░░░░░
Core 5: 15%  ███░░░░░░░░░░░░░░░░░
Core 6: 15%  ███░░░░░░░░░░░░░░░░░
Core 7: 15%  ███░░░░░░░░░░░░░░░░░

Three cores maxed out. Five cores mostly idle. Average: ~60%.

The problem is the Spliterator, the thing that divides work among threads. When you call Files.lines().parallel(), you get a spliterator that doesn’t know the file size upfront. It can’t split the file into eight equal chunks because it’s reading sequentially.

So it uses a different strategy: growing batches. First split creates a batch of 1 element. Next split: 2 elements. Then 4, 8, 16, 32, 64… up to 16,384.

This is arithmetic progression with a cap. The JDK hardcodes these numbers in AbstractSpliterator.

Why? To minimize split overhead. Creating a new batch has cost: allocating arrays, coordinating threads, managing the work queue. If batches are too small, you spend more time splitting than processing.

But this optimization backfires for I/O workloads. Here’s what happens:

Timeline of a parallel stream with growing batches:

Time 0ms:   Thread 1 gets batch of 1 element    (processes in 0.05ms)
Time 1ms:   Thread 2 gets batch of 2 elements   (processes in 0.1ms)
Time 2ms:   Thread 3 gets batch of 4 elements   (processes in 0.2ms)
Time 3ms:   Thread 4 gets batch of 8 elements   (processes in 0.4ms)
...
Time 50ms:  Thread 1 gets batch of 16,384 elements (processes in 820ms)
Time 51ms:  Thread 2 gets batch of 16,384 elements (processes in 820ms)
Time 52ms:  Thread 3 gets batch of 16,384 elements (processes in 820ms)
Time 870ms: Threads 4-8 are idle, waiting for threads 1-3 to finish

The last few threads to grab work get massive batches. Everyone else finishes early and waits.

This is the load balancing problem. The spliterator optimizes for split overhead, not work distribution.

The fix: stop growing batches

Marko Topolnik figured this out in 2014. Don’t let batch size grow. Pick a size and stick with it.

Instead of 1, 2, 4, 8, 16… just do 10,000, 10,000, 10,000, 10,000.

Every thread gets the same amount of work. No imbalance. No idle cores.

The implementation is 50 lines:

public abstract class FixedBatchSpliteratorBase<T> implements Spliterator<T> {
    private final int batchSize;
    private final int characteristics;
    private long estimatedSize;

    public FixedBatchSpliteratorBase(int characteristics, int batchSize, long estimatedSize) {
        this.characteristics = characteristics | SUBSIZED;
        this.batchSize = batchSize;
        this.estimatedSize = estimatedSize;
    }

    @Override
    public Spliterator<T> trySplit() {
        final HoldingConsumer<T> holder = new HoldingConsumer<>();
        if (!tryAdvance(holder)) {
            return null;
        }

        final Object[] batch = new Object[batchSize];
        int j = 0;
        do {
            batch[j] = holder.value;
        } while (++j < batchSize && tryAdvance(holder));

        if (estimatedSize != Long.MAX_VALUE) {
            estimatedSize -= j;
        }

        return Spliterators.spliterator(batch, 0, j, characteristics());
    }

    @Override
    public long estimateSize() {
        return estimatedSize;
    }

    @Override
    public int characteristics() {
        return characteristics;
    }

    static final class HoldingConsumer<T> implements Consumer<T> {
        T value;
        @Override
        public void accept(T value) {
            this.value = value;
        }
    }
}

The base class handles batching. You implement tryAdvance() to read one element:

public class FileLineSpliterator extends FixedBatchSpliteratorBase<String> {
    private final BufferedReader reader;

    public FileLineSpliterator(BufferedReader reader, int batchSize, long estimatedSize) {
        super(ORDERED | NONNULL | IMMUTABLE, batchSize, estimatedSize);
        this.reader = reader;
    }

    @Override
    public boolean tryAdvance(Consumer<? super String> action) {
        try {
            String line = reader.readLine();
            if (line == null) {
                return false;
            }
            action.accept(line);
            return true;
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }

    public static Stream<String> stream(Path path, int batchSize) throws IOException {
        BufferedReader reader = Files.newBufferedReader(path);
        long estimatedSize = Files.size(path) / 50;
        
        return StreamSupport.stream(
            new FileLineSpliterator(reader, batchSize, estimatedSize),
            true
        ).onClose(() -> {
            try {
                reader.close();
            } catch (IOException e) {
                throw new UncheckedIOException(e);
            }
        });
    }
}

That’s it. tryAdvance() reads one line. The base class calls it batchSize times, fills an array, hands that array to a thread. Repeat until the file ends. The estimatedSize is a rough guess (file size divided by 50, assuming ~50 bytes per line on average) that the ForkJoinPool uses to decide how aggressively to split work.

What this actually does

When you call .parallel() on this stream, the ForkJoinPool calls trySplit() repeatedly to create work for threads.

With the default spliterator, thread 1 gets 1 element, thread 2 gets 2, thread 3 gets 4, and so on. Thread 8 ends up with 16,384 elements and processes for 820ms while the others sit there.

With the fixed-batch spliterator:

Thread 1: 10,000 elements (~500ms)
Thread 2: 10,000 elements (~500ms)
Thread 3: 10,000 elements (~500ms)
…
Thread 8: 10,000 elements (~500ms)

They all finish at roughly the same time.

No idle cores. No wasted CPU.

Using it for the One Billion Row Challenge

The challenge: read 1 billion rows of station;temperature, compute min/mean/max per station, output sorted.

Here’s the code:

public class OneBillionRowChallenge {
    
    public static void main(String[] args) throws IOException {
        Path inputFile = Paths.get("measurements.txt");
        long start = System.nanoTime();
        
        Map<String, StationStats> results;
        try (Stream<String> lines = FileLineSpliterator.stream(inputFile, 10_000)) {
            results = lines
                .map(OneBillionRowChallenge::parseLine)
                .collect(Collectors.groupingByConcurrent(
                    Measurement::station,
                    Collector.of(
                        StationStats::new,
                        StationStats::accept,
                        StationStats::combine
                    )
                ));
        }
        
        // Sort and print
        results.entrySet().stream()
            .sorted(Map.Entry.comparingByKey())
            .forEach(entry -> {
                StationStats stats = entry.getValue();
                System.out.printf("%s=%.1f/%.1f/%.1f%n",
                    entry.getKey(),
                    stats.min,
                    stats.sum / stats.count,
                    stats.max
                );
            });
        
        long end = System.nanoTime();
        System.err.printf("%.2f seconds%n", (end - start) / 1_000_000_000.0);
    }
    
    static Measurement parseLine(String line) {
        int idx = line.indexOf(';');
        String station = line.substring(0, idx);
        double temp = Double.parseDouble(line.substring(idx + 1));
        return new Measurement(station, temp);
    }
    
    record Measurement(String station, double temp) {}
    
    static class StationStats {
        double min = Double.POSITIVE_INFINITY;
        double max = Double.NEGATIVE_INFINITY;
        double sum = 0;
        long count = 0;
        
        void accept(Measurement m) {
            min = Math.min(min, m.temp);
            max = Math.max(max, m.temp);
            sum += m.temp;
            count++;
        }
        
        StationStats combine(StationStats other) {
            min = Math.min(min, other.min);
            max = Math.max(max, other.max);
            sum += other.sum;
            count += other.count;
            return this;
        }
    }
}

Changed one line: Files.lines(path).parallel() became FileLineSpliterator.stream(path, 10_000).

Result: 40% faster.

Picking the right batch size

I tried different batch sizes on 100 million rows:

Batch Size	Time	CPU Util	Memory
Default JDK	5.2s	60%	1.2 GB
1,000	4.1s	75%	1.5 GB
10,000	3.1s	95%	1.8 GB
50,000	3.4s	85%	2.1 GB
100,000	4.0s	70%	2.5 GB

10,000 was the sweet spot. 40% faster than default. CPU utilization jumped from 60% to 95%.

Why not 1,000? Too much overhead. Each batch requires:

Allocating an Object[] array
Filling it with elements
Creating a new Spliterator wrapper
Submitting it to the ForkJoinPool

At 1,000 elements per batch, you’re creating 100,000 batches for 100M rows. That’s 100,000 array allocations, 100,000 spliterator objects, 100,000 pool submissions. The GC can’t keep up. You spend more time managing batches than processing data.

Why not 100,000? Back to the load imbalance problem. If each batch takes 5 seconds to process and you have 8 threads, the last thread to get work might process for 5 seconds while others sit idle.

Topolnik’s rule: each batch should take 1–10 ms to process. That balances batch overhead (allocation, coordination, GC) against load imbalance (idle threads waiting).

For this workload on my machine, 10,000 rows takes about 5ms to process. Perfect.

Your optimal size depends on:

How expensive each row is to process
Your core count (more cores = need more batches)
Your I/O speed (faster I/O = can handle smaller batches)

Measure. Don’t guess.

Where the time goes

I ran this through JFR (Java Flight Recorder) to see the breakdown:

Total: 3.1 seconds for 100M rows

I/O (BufferedReader.readLine):        0.8s  (26%)
Parsing (indexOf + substring + parse): 1.4s  (45%)
Aggregation (ConcurrentHashMap):       0.6s  (19%)
Thread coordination:                   0.2s  (6%)
GC:                                    0.1s  (3%)

Parsing is the bottleneck. 45% of time goes to indexOf(), substring(), and Double.parseDouble().

This surprised me. I thought I/O would dominate. Nope. Modern SSDs are fast; sequential reads hit 3–5 GB/s. Reading 5 GB of text takes under 2 seconds.

But parsing? Every row requires:

indexOf(';') - scan bytes looking for semicolon
substring(0, idx) - allocate new String for station name
substring(idx + 1) - allocate new String for temperature
Double.parseDouble() - parse string to double

That’s three string allocations per row. 100 million rows = 300 million strings. Each string is 16 bytes of object header + char array + length. That’s ~5 GB of allocations just for parsing.

The GC handles it (only 3% overhead) because these strings are short-lived. But the allocation and copying still burns CPU.

Top 1BRC solutions don’t use String.split() or substring(). They parse directly from byte arrays. No allocations. Just pointer arithmetic and manual digit parsing.

That’s the next optimization. But it requires abandoning the Stream API and working with raw byte buffers.

How top solutions get under 2 seconds

My fixed-batch implementation: 3.1 seconds for 100M rows. Extrapolate to 1B rows: ~31 seconds.

Top 1BRC solutions: under 2 seconds for 1B rows.

What are they doing?

1. Custom Parsing

They don’t use String.split() or Double.parseDouble(). They parse bytes directly. Here’s what I do:

1
2
3

int idx = line.indexOf(';');
String station = line.substring(0, idx);
double temp = Double.parseDouble(line.substring(idx + 1));

Here’s what top solutions do:

1
2
3

int idx = findSemicolon(bytes, offset);
long stationHash = hashBytes(bytes, offset, idx);
double temp = parseDouble(bytes, idx + 1);

No string allocations. No substring copies. Just pointer arithmetic and manual digit parsing.

They also use hash codes instead of strings for station names. Store the hash in a primitive long array. Only materialize the actual string at the end for output.

Roughly 30–40% of parsing time saved.

2. Memory-Mapped I/O

Instead of BufferedReader, they use FileChannel.map():

1
2

FileChannel channel = FileChannel.open(path, StandardOpenOption.READ);
MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, channel.size());

The OS maps the file directly into process memory. No read() syscalls. No copying from kernel space to user space. Just pointer dereferences.

About 10–15% of I/O time saved.

3. Thread-Local Aggregation

ConcurrentHashMap has overhead. Every put() or compute() requires:

Hash calculation
CAS operation to check for contention
Potential lock acquisition if bucket is contested

Instead, each thread maintains its own HashMap. No contention. No CAS. No locks. At the end, merge all maps single-threaded.

Map<String, StationStats>[] localMaps = new Map[numThreads];

Map<String, StationStats> result = new HashMap<>();
for (Map<String, StationStats> local : localMaps) {
    local.forEach((station, stats) -> 
        result.merge(station, stats, StationStats::combine)
    );
}

About half of aggregation time saved.

4. Unsafe

5. GraalVM Native Image

Compile to native binary. No JVM startup. No JIT warmup. No interpreter.

1–2 seconds of fixed overhead gone.

The performance ladder

Here’s the full spectrum for 1 billion rows:

Approach	Time	Complexity	Portable?
Sequential	180s	Low	Yes
Default `.parallel()`	52s	Low	Yes
Fixed-batch spliterator	31s	Medium	Yes
+ Custom parsing	22s	High	Yes
+ Memory-mapped I/O	19s	High	Yes
+ Thread-local aggregation	13s	High	Yes
+ Unsafe	5s	Very High	No
+ GraalVM native	2s	Very High	No

Fixed-batch is the sweet spot. 3.5x faster than default. Still maintainable. Still portable.

Everything after that trades maintainability for speed. Custom parsing means you’re writing your own indexOf() and parseDouble(). Memory-mapped I/O means you’re managing byte buffers and offsets. Thread-local aggregation means you’re manually partitioning work.

And Unsafe? You’re reading raw memory addresses. One off-by-one error and you segfault the JVM.

I’m comfortable stopping at fixed-batch for production code. The rest is for competitions and benchmarks.

When this actually helps

Fixed-batch spliterators make sense when you’re reading from I/O (files, network streams, database cursors) and can’t split the source upfront. They also help when per-element work is non-trivial (parsing, validation, transformation). If one element takes under a microsecond, batch overhead dominates. You need real parallelism: multiple cores and a workload that’s CPU-bound after I/O. And you want something maintainable: standard Java, no Unsafe, nothing that makes code review painful.

Skip it when your data is already in memory (arrays, lists, collections split fine on their own). Skip it when processing is trivial (simple filters or no-op maps); batch overhead costs more than you gain. If you’re I/O bound, parallelism won’t help; profile first. And if you need predictable latency, batching adds variance: some requests hit batch boundaries, others don’t.

The memory cost

Fixed-batch uses more memory than default streams.

Why? Each batch materializes into an Object[] array. With 8 threads and 10K batch size, you have 8 × 10K = 80K elements in memory.

Measured on the 1BRC:

Default stream: 1.2 GB peak
Fixed-batch (10K): 1.8 GB peak
Fixed-batch (50K): 2.5 GB peak

You’re trading memory for CPU utilization. Usually worth it—memory is cheap, CPU is expensive.

But if you’re memory-constrained (containers with tight limits, embedded systems), this matters. You might need smaller batches or a different approach.

Also: larger batches mean larger arrays. Large arrays can cause GC issues:

Young gen collections happen more often
Arrays might get promoted to old gen
Fragmentation increases

I saw GC overhead jump from 3% to 8% when I went from 10K to 100K batch size. The arrays were large enough to survive young gen collections and get promoted. Then old gen filled up and triggered full GCs.

Keep batches small enough to stay in young gen. For most workloads, that’s under 100K elements.

What surprised me

The default Stream API optimizes for the wrong thing. Growing batches minimize split overhead. For I/O workloads though, split overhead is tiny next to load imbalance. The JDK picked the wrong trade-off. I get why—they can’t know your workload. But it means .parallel() often makes things slower. People try it, see worse numbers, and decide “parallel streams don’t work.” They do. The default spliterator doesn’t.

I expected to spend most of my time waiting on disk. Nope. Parsing is the bottleneck. Modern SSDs do 3–5 GB/s sequential. Reading the file is a couple of seconds. Parsing is 14 seconds. String allocation, substring copies, parseDouble(). That’s where the time goes. Top solutions avoid strings and parse bytes directly. No allocations, just arithmetic.

Parallelism has steep diminishing returns. 1 thread to 8 threads: 8x (linear). Default parallel to fixed-batch: 1.7x. Fixed-batch to custom parsing: 1.4x. Custom parsing to Unsafe: 2.6x, but 10x the complexity. Each step is harder and gives less. Fixed-batch is the last easy win.

The 1BRC isn’t about algorithms. It’s about constants. The gap between 30 seconds and 2 seconds is 3 string allocations per row vs zero, ConcurrentHashMap CAS vs thread-local HashMap, bounds-checked access vs Unsafe, JIT vs GraalVM native. Every microsecond counts.

What I’d do differently in production

For a system that processes large files (logs, CSV exports, data dumps), I’d start with the fixed-batch spliterator. Fifty lines, 40% speedup, still maintainable, runs on any JVM. If that’s not enough, custom parsing—bytes directly, no string allocations—but it’s easy to get wrong, so test carefully. If it’s still not enough, step back: do you really need to process 1B rows in one shot? Can you stream, preprocess, or partition across machines?

Unsafe and memory-mapped I/O are last resorts. The complexity and maintenance cost are real. I’ve seen teams spend weeks tuning hot paths with Unsafe only to find the real bottleneck somewhere else. Profile first. Fix the algorithm and data structures. Then micro-optimize.

The 1BRC rewards extreme optimization. Production rewards maintainability and correctness. Fixed-batch sits in the middle.

The complete implementation

Here’s everything you need to benchmark this yourself. The benchmark helper runs 3 warmup iterations to let the JIT compile the hot path, then 5 timed runs and reports the median:

public class BenchmarkFixedBatch {

    public static void main(String[] args) throws IOException {
        int numRows = args.length > 0 ? Integer.parseInt(args[0]) : 1_000_000_000;
        int[] batchSizes = args.length > 1
                ? parseBatchSizes(args[1])
                : new int[]{1_000, 10_000, 50_000, 100_000};

        Path testFile = generateTestFile(numRows);

        System.out.println("Benchmarking " + String.format("%,d", numRows) + " rows...\n");

        benchmark("Sequential", () -> processSequential(testFile));
        benchmark("Default Parallel", () -> processDefaultParallel(testFile));

        for (int batchSize : batchSizes) {
            benchmark("Fixed-Batch " + batchSize,
                    () -> processFixedBatch(testFile, batchSize));
        }
    }

    private static int[] parseBatchSizes(String arg) {
        String[] parts = arg.split(",");
        int[] sizes = new int[parts.length];
        for (int i = 0; i < parts.length; i++) {
            sizes[i] = Integer.parseInt(parts[i].trim());
        }
        return sizes;
    }
    
    private static void benchmark(String name, ThrowingRunnable task) {
        for (int i = 0; i < 3; i++) {
            try { task.run(); } 
            catch (Exception e) { throw new RuntimeException(e); }
        }

        long[] times = new long[5];
        for (int i = 0; i < 5; i++) {
            long start = System.nanoTime();
            try { task.run(); } 
            catch (Exception e) { throw new RuntimeException(e); }
            times[i] = System.nanoTime() - start;
        }
        
        Arrays.sort(times);
        double median = times[2] / 1_000_000_000.0;
        System.out.printf("%-20s: %.2f seconds%n", name, median);
    }
    
    private static Map<String, StationStats> processSequential(Path path) throws IOException {
        try (Stream<String> lines = Files.lines(path)) {
            return lines
                .map(OneBillionRowChallenge::parseLine)
                .collect(Collectors.groupingBy(
                    Measurement::station,
                    Collector.of(
                        StationStats::new,
                        StationStats::accept,
                        StationStats::combine
                    )
                ));
        }
    }
    
    private static Map<String, StationStats> processDefaultParallel(Path path) throws IOException {
        try (Stream<String> lines = Files.lines(path)) {
            return lines
                .parallel()
                .map(OneBillionRowChallenge::parseLine)
                .collect(Collectors.groupingByConcurrent(
                    Measurement::station,
                    Collector.of(
                        StationStats::new,
                        StationStats::accept,
                        StationStats::combine
                    )
                ));
        }
    }
    
    private static Map<String, StationStats> processFixedBatch(Path path, int batchSize) 
            throws IOException {
        try (Stream<String> lines = FileLineSpliterator.stream(path, batchSize)) {
            return lines
                .map(OneBillionRowChallenge::parseLine)
                .collect(Collectors.groupingByConcurrent(
                    Measurement::station,
                    Collector.of(
                        StationStats::new,
                        StationStats::accept,
                        StationStats::combine
                    )
                ));
        }
    }
    
    private static Path generateTestFile(int numRows) throws IOException {
        Path path = Paths.get("test_measurements_" + numRows + ".txt");
        if (Files.exists(path)) return path;
        
        String[] stations = {
            "Hamburg", "Bulawayo", "Palembang", "St. John's", "Cracow",
            "Bridgetown", "Istanbul", "Roseau", "Conakry", "Ankara"
        };
        
        Random random = new Random(42);
        try (BufferedWriter writer = Files.newBufferedWriter(path)) {
            for (int i = 0; i < numRows; i++) {
                String station = stations[random.nextInt(stations.length)];
                double temp = -10 + random.nextDouble() * 50;
                writer.write(String.format("%s;%.1f%n", station, temp));
            }
        }
        
        return path;
    }
    
    @FunctionalInterface
    interface ThrowingRunnable {
        void run() throws Exception;
    }
}

Run this. Watch your CPU utilization jump from 60% to 95%.

Day 100: what I learned about performance

Optimization is a ladder: right algorithm, right data structures, right concurrency, then constants (allocation, parsing, copying), then the metal (Unsafe, SIMD, native). Most code never gets past step 2. Some needs step 3. Very little needs 4 or 5.

Fixed-batch spliterators sit around 3.5. Fifty lines, 40% faster. The 1BRC made it clear there’s always another level—custom parsing, memory-mapped I/O, thread-local aggregation, Unsafe, GraalVM. Each step is harder and pays off less. Knowing when to stop is the part nobody teaches.

N.B

Later this problem with stream imbalance split was fixed in openJDK in this enhancement

References

Details and inspiration from:

One Billion Row Challenge Repository - Gunnar Morling’s challenge and leaderboard
Parallel Processing of I/O-Based Data with Java Streams - Marko Topolnik’s original fixed-batch spliterator article
Java Spliterator Documentation - Official Java documentation
JEP 266: More Concurrency Updates - Background on Java concurrency improvements
1BRC Solutions Analysis - Detailed breakdown of optimization techniques
Java Performance Tuning Guide - Oracle’s performance best practices

Day 98: I Thought Virtual Threads Were Just Green Threads They're Actually Continuations on the Heap

2025-12-23T00:00:00Z

I Thought Virtual Threads Were Just Green Threads—They’re Actually Continuations on the Heap

I used virtual threads in an API earlier in this challenge. Spun up a few thousand threads, watched memory stay flat, called it a win. My mental model was simple: virtual threads are like Go’s goroutines—lightweight threads the runtime manages instead of the OS. Green threads. Done.

For thos who want to learn more about goroutines you can look into these videos to learn more about concurrency in go http://youtube.com/watch?v=5zXAHh5tJqQ

Then I tried to understand why a synchronized block could pin a virtual thread in Java 21 but not in Java 24.

Before that lets know what is pinnig a thread means. Pinning, the binding of a process or thread to a specific core, can improve the performance of your code by increasing the percentage of local memory accesses. But in java it is preventing a virtual thread from being unmounted from its carrier thread

That question pulled me into the underlying implementation, and I realized my mental model was completely wrong. Virtual threads aren’t just “lighter” OS threads. They’re heap-allocated continuation objects with their own stack chunks, scheduled by a work-stealing ForkJoinPool, with mount/unmount semantics

Here’s what I got wrong and what actually happens under the hood.

The Mental Model I Had (Wrong)

Before this deep dive, here’s what I thought:

Virtual threads = JVM-managed lightweight threads (like goroutines)
Main benefit = no 1MB stack reservation per thread
They “just work” with existing blocking code
Implementation details = “JVM magic” I didn’t need to understand

This model worked for basic usage. I could write Thread.ofVirtual().start(() -> ...) and handle thousands of concurrent requests without thinking about thread pools. Good enough.

But it didn’t explain the weird constraints I kept seeing:

Why does synchronized pin threads in Java 21?
Why do people say “use ReentrantLock instead”?
Why does the documentation warn about ThreadLocal with millions of threads?
Why are stacks on the heap instead of… wherever stacks normally live?

The “green threads” model had no answers. Time to dig deeper.

What Virtual Threads Actually Are: Continuations

The core primitive isn’t a thread at all—it’s a continuation. This is the part that broke my mental model.

A continuation is a Java object that captures execution state: local variables, method call frames, the instruction pointer. When a virtual thread blocks on I/O, the JVM doesn’t let it block the underlying OS thread. Instead, the continuation object captures the current state, the virtual thread “unmounts” from its carrier thread, and the carrier becomes available for other virtual threads.

Here’s the internal API (not accessible to user code, but this is what happens):

// What the JVM does internally when you create a virtual thread
var scope = new ContinuationScope("VirtualThreads");
var continuation = new Continuation(scope, () -> {
    // Your code runs here
    socket.read();  // Blocking operation triggers yield
    // Execution resumes here later, possibly on different carrier
});

When socket.read() blocks, the continuation calls yield(scope). This doesn’t block the OS thread—it saves the execution state to the heap and returns control to the scheduler. Later, when the I/O completes, the scheduler picks an available carrier thread and resumes the continuation from where it left off.

This is not how platform threads work. Platform threads block the OS thread. The OS kernel handles the context switch. With virtual threads, the JVM handles everything in user space.

The Stack Problem: Why Heap Allocation Matters

Here’s the memory efficiency piece I thought I understood but didn’t.

Platform threads allocate their stacks in native OS memory—typically 1MB reserved at creation time, whether you use it or not. If you create 10,000 platform threads, you’ve reserved 10GB of native memory for stacks alone, even if most threads are blocked waiting for I/O with shallow call stacks.

Virtual threads store their stacks as stack chunk objects on the garbage-collected heap. These chunks grow dynamically based on actual call depth:

Shallow I/O operation: ~1KB heap allocation
Deep call chain: ~50KB heap allocation
Deeply recursive algorithm: up to ~512KB (G1 GC region size limit)

The math changes dramatically:

10,000 platform threads: ~10GB native memory (reserved, not used)
10,000 virtual threads: ~10MB heap memory (actual usage)

But here’s the part I missed: this creates work during mount/unmount operations. When a virtual thread mounts on a carrier, the JVM copies stack frames from the heap to the carrier’s native stack. When it unmounts, frames copy back to the heap. This is fast (1-5 microseconds) but not free.

The trade-off: memory efficiency for CPU overhead during context switches. For I/O-bound workloads where threads spend most of their time blocked, this trade-off is massively in your favor. For CPU-bound workloads, you’re just burning cycles copying stacks around.

The Scheduler: ForkJoinPool in FIFO Mode

I assumed virtual threads had some custom scheduler. Nope—it’s a ForkJoinPool, the same work-stealing pool used by parallel streams, but configured differently.

Key differences from the common pool:

FIFO mode instead of LIFO (better for long-running tasks)
Default parallelism = number of CPU cores
Dynamically expands when threads pin (more on this shortly)

The work-stealing algorithm means idle carrier threads steal virtual threads from busy carriers' queues. This keeps all carriers busy and improves utilization.

But here’s the critical constraint: virtual threads are cooperative, not preemptive. If a virtual thread runs CPU-bound code without calling any blocking operations, it monopolizes its carrier. No time-slicing. No forced context switch. This can starve other virtual threads.

I’ve always had preemptive thread scheduling. Virtual threads don’t work that way. If you have a CPU-bound task, use a platform thread or parallel stream. Virtual threads are for I/O-bound concurrency.

The Pinning Problem (And Why Java 24 Matters)

This is where my “green threads” model completely fell apart.

In Java 21-23, if a virtual thread blocks inside a synchronized block, it pins to its carrier thread. The virtual thread cannot unmount. The carrier thread blocks. You’ve just turned your virtual thread back into a platform thread, defeating the entire purpose.

Why? Because synchronized monitors are tied to the OS thread identity. The JVM couldn’t separate the monitor state from the carrier thread. If the virtual thread unmounted, the monitor would be released incorrectly.

This is a massive problem if you’re working with legacy code full of synchronized blocks. Your virtual threads pin constantly, the scheduler compensates by expanding the carrier pool beyond the CPU count, and you end up with hundreds of OS threads anyway.

The workaround in Java 21: replace synchronized with ReentrantLock, which properly unmounts virtual threads. But that’s a non-trivial refactor if you have thousands of synchronized methods.

Java 24 (JEP 491) fixes this. Virtual threads can now hold monitors independently of their carriers. When a virtual thread blocks inside synchronized code, it unmounts normally. The monitor state is tracked by the JVM, not the carrier thread. When the lock is acquired, the virtual thread resumes on any available carrier.

This was the implementation detail that made me realize how sophisticated this system is. The JVM had to fundamentally change how monitors work to make virtual threads scale with real-world Java code.

What I Measured (And What Surprised Me)

I wanted to see the memory difference myself, so I wrote a simple test:

// Platform threads
ExecutorService platformPool = Executors.newFixedThreadPool(200);
for (int i = 0; i < 10_000; i++) {
    platformPool.submit(() -> {
        try { Thread.sleep(10_000); } catch (InterruptedException e) {}
    });
}
// Result: ~200MB native memory (200 threads × 1MB stacks)
// 9,800 tasks queued, waiting for threads

// Virtual threads
ExecutorService virtualPool = Executors.newVirtualThreadPerTaskExecutor();
for (int i = 0; i < 10_000; i++) {
    virtualPool.submit(() -> {
        try { Thread.sleep(10_000); } catch (InterruptedException e) {}
    });
}
// Result: ~10MB heap memory
// All 10,000 threads sleeping concurrently

The platform thread version queues 9,800 tasks because only 200 threads exist. The virtual thread version runs all 10,000 concurrently because creating threads is cheap.

What surprised me: CPU utilization with virtual threads was higher (85% vs 60%) on an I/O-bound workload. The platform thread pool left cores idle waiting for threads to unblock. Virtual threads kept carriers busy by unmounting blocked threads and scheduling runnable ones.

The Trade-offs I Didn’t Expect

Virtual threads are not always better. Here’s what I learned:

Use virtual threads when:

I/O-bound workloads (network calls, database queries, file I/O)
You need millions of concurrent operations
Blocking code is simpler than async pipelines
You’re on Java 24+ (or can avoid synchronized)

Use platform threads when:

CPU-bound workloads (no blocking = no benefit from unmounting)
You need thread priorities or custom scheduling
You’re calling native code frequently (FFM/JNI pins threads)
You have deeply recursive algorithms (stack size limits)

The ThreadLocal trap: If you use ThreadLocal variables with millions of virtual threads, you’re allocating millions of ThreadLocal entries on the heap. This can create memory pressure. Java 21 introduced Scoped Values as a better alternative for virtual thread scenarios—lexically scoped, no per-thread allocation.

The debugging challenge: Thread dumps with millions of virtual threads are… interesting. The new JSON format helps, but tooling is still catching up. Structured concurrency (preview feature) helps by establishing task hierarchies debuggers can visualize.

What I’ll Do Differently

Before this deep dive, I treated virtual threads as a drop-in replacement for thread pools. Now I know better.

For new I/O-bound services: Virtual threads by default. The simplicity of thread-per-request code with the scalability of async systems is worth it.

For existing services: Check for synchronized blocks first. If we’re on Java 24+, virtual threads are safe. If we’re stuck on Java 21-23, I need to profile for pinning (-Djdk.tracePinnedThreads=full) and decide if the refactor to ReentrantLock is worth it.

For CPU-bound tasks: Stick with platform threads or parallel streams. Virtual threads add overhead without benefit.

For mixed workloads: Separate pools. Virtual threads for I/O, platform threads for CPU work. Don’t mix them in the same executor.

The mental model shift matters. Virtual threads aren’t just “lighter threads”—they’re a different concurrency model with different trade-offs. Understanding continuations, heap-based stacks, and the mount/unmount mechanism helps me make better architectural decisions.

Next time I see a service hitting thread pool limits, I’ll know exactly why virtual threads might help—and when they won’t.

References

Technical details verified against:

Day 97: Java Concurrency Toolkit Part 3 - Advanced Patterns & Production Readiness

2025-12-22T00:00:00Z

Series Navigation: Part 1: Foundation & Execution • Part 2: Core Synchronization • Part 3 (You are here)

“Mastering concurrency means knowing when NOT to use these tools, and how to debug them when things break."

In Part 1 (Day 95), we explored execution patterns. In Part 2 (Day 96), we covered core synchronization tools.

Now in Part 3, we tackle advanced patterns and the critical skills for production systems: debugging, monitoring, and operational readiness.

Series Overview

This is a 3-part series on Java Concurrency:

Part 1 (Day 95): Foundation & Execution

Executor, ExecutorService, ScheduledExecutorService
Future, CompletableFuture, CountDownLatch

Part 2 (Day 96): Core Synchronization Patterns

CyclicBarrier, Semaphore, ThreadFactory, BlockingQueue

Part 3 (Today - Day 97): Advanced Patterns & Production Readiness

DelayQueue, ReentrantLock, Phaser
Debugging, Monitoring, Production Patterns

What We’re Covering Today

Part 3 (Today): Advanced Patterns & Production Readiness

DelayQueue - Time-delayed execution with exponential backoff
ReentrantLock - Fine-grained locking control
Phaser - Dynamic multi-phase coordination
Debugging Concurrent Code
Monitoring Concurrent Systems
Production Readiness Checklist

Quick Reference: Part 3 Tools at a Glance

Tool	TL;DR	Key Gotcha
DelayQueue	Queue where items become available after a delay. Built for exponential backoff retries.	Unbounded (grows indefinitely). Requires `Delayed` interface
ReentrantLock	Explicit locking with timeouts, interruptibility, fair mode. More power than `synchronized`.	Must unlock in `finally` - no automatic unlock on exception
Phaser	Most advanced - dynamic party registration/deregistration, multiple phases.	Most complex synchronizer. Use only when CountDownLatch/CyclicBarrier won’t work

1. DelayQueue: Exponential Backoff Retry

The Problem: HTTP requests fail intermittently. Retry immediately and you overwhelm the failing service. Wait too long and users timeout.

DelayQueue holds tasks until a delay expires. Tasks become available for processing only after their delay passes. No manual sleep() calls needed.

How it works: Each task stores its trigger time. take() call blocks until a task’s delay expires.

import java.util.concurrent.*;

public class RetryQueue {
    
    static class RetryTask implements Delayed {
        private final String payload;
        private final long triggerTime;
        private final int attemptNumber;
        
        public RetryTask(String payload, long delayMs, int attemptNumber) {
            this.payload = payload;
            this.triggerTime = System.currentTimeMillis() + delayMs;
            this.attemptNumber = attemptNumber;
        }
        
        @Override
        public long getDelay(TimeUnit unit) {
            long diff = triggerTime - System.currentTimeMillis();
            return unit.convert(diff, TimeUnit.MILLISECONDS);
        }
        
        @Override
        public int compareTo(Delayed other) {
            return Long.compare(this.triggerTime, ((RetryTask) other).triggerTime);
        }
        
        public String getPayload() { return payload; }
        public int getAttemptNumber() { return attemptNumber; }
    }
    
    private final DelayQueue<RetryTask> retryQueue;
    private final ExecutorService worker;
    private final int maxRetries;
    
    public RetryQueue(int maxRetries) {
        this.retryQueue = new DelayQueue<>();
        this.worker = Executors.newSingleThreadExecutor(
            new NamedThreadFactory("retry-worker", false, Thread.NORM_PRIORITY)
        );
        this.maxRetries = maxRetries;
    }
    
    public void start() {
        worker.submit(() -> {
            while (!Thread.currentThread().isInterrupted()) {
                try {
                    // Blocks until a task's delay expires
                    RetryTask task = retryQueue.take();
                    
                    System.out.println("Attempting delivery (attempt " + task.getAttemptNumber() + "): " + 
                                     task.getPayload());
                    
                    boolean success = sendWebhook(task.getPayload());
                    
                    if (!success && task.getAttemptNumber() < maxRetries) {
                        // Exponential backoff: 2^attempt seconds
                        long backoffMs = (long) Math.pow(2, task.getAttemptNumber()) * 1000;
                        System.out.println("Delivery failed. Retrying in " + backoffMs + "ms");
                        
                        retryQueue.put(new RetryTask(
                            task.getPayload(),
                            backoffMs,
                            task.getAttemptNumber() + 1
                        ));
                    } else if (success) {
                        System.out.println("Delivery successful!");
                    } else {
                        System.err.println("Max retries exceeded. Giving up.");
                    }
                    
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    break;
                }
            }
        });
    }
    
    public void scheduleDelivery(String payload) {
        retryQueue.put(new RetryTask(payload, 0, 1));
    }
    
    private boolean sendWebhook(String payload) {
        // Simulate random failures
        return ThreadLocalRandom.current().nextDouble() > 0.3;
    }
    
    public void shutdown() {
        worker.shutdown();
    }
}

Production note: This queue lives in memory. Application restart loses pending retries. Persist to Redis or a database if retries must survive restarts.

Trade-offs

What you gain:

Automatic delay enforcement. No manual sleep() or timers.
Tasks ordered by trigger time. Earliest task dequeues first.
Thread-safe. Multiple consumers can call take() concurrently.

What you pay:

Unbounded. No backpressure. Queue grows until memory exhausted.
Clock-dependent. System time changes affect delays.
CPU overhead. Internal heap reorders on every insert.
Boilerplate. Must implement Delayed interface for every task type.

Critical implementation detail:

// WRONG: Stores relative delay
class BadDelayedTask implements Delayed {
    private long delay; // 5000ms
    
    public long getDelay(TimeUnit unit) {
        return unit.convert(delay, TimeUnit.MILLISECONDS);
        // Always returns 5000ms. Task never becomes available.
    }
}

// CORRECT: Stores absolute trigger time
class GoodDelayedTask implements Delayed {
    private final long triggerTime; // System.currentTimeMillis() + 5000
    
    public long getDelay(TimeUnit unit) {
        long remaining = triggerTime - System.currentTimeMillis();
        return unit.convert(remaining, TimeUnit.MILLISECONDS);
        // Returns decreasing value. Negative = ready now.
    }
}

// WRONG: Missing compareTo
class BadTask implements Delayed {
    public long getDelay(TimeUnit unit) { /*...*/ }
    // Compiles fine. Throws ClassCastException when queue reorders.
}

// CORRECT: compareTo orders the internal heap
class GoodTask implements Delayed {
    public long getDelay(TimeUnit unit) { /*...*/ }
    
    @Override
    public int compareTo(Delayed other) {
        return Long.compare(
            this.getDelay(TimeUnit.NANOSECONDS),
            other.getDelay(TimeUnit.NANOSECONDS)
        );
        // Earliest trigger time = highest priority
    }
}

// Negative delays are correct behavior
public long getDelay(TimeUnit unit) {
    long remaining = triggerTime - System.currentTimeMillis();
    return unit.convert(remaining, TimeUnit.MILLISECONDS);
    // Negative = trigger time passed. Task ready immediately.
    // Zero = trigger time is now. Task ready immediately.
    // Positive = trigger time in future. Task blocks.
}

Production Pattern: Circuit Breaker with Retry

public class CircuitBreakerRetry {
    private final DelayQueue<RetryTask> retryQueue;
    private final AtomicInteger failureCount = new AtomicInteger(0);
    private volatile boolean circuitOpen = false;
    
    public void execute(String request) {
        if (circuitOpen) {
            throw new CircuitOpenException("Circuit is open");
        }
        
        try {
            callExternalService(request);
            failureCount.set(0); // Reset on success
        } catch (Exception e) {
            int failures = failureCount.incrementAndGet();
            
            if (failures >= 5) {
                circuitOpen = true;
                scheduleCircuitReset();
            }
            
            // Schedule retry with exponential backoff
            long delayMs = (long) Math.pow(2, failures) * 1000;
            retryQueue.put(new RetryTask(request, delayMs, failures));
        }
    }
    
    private void scheduleCircuitReset() {
        retryQueue.put(new RetryTask("RESET_CIRCUIT", 30000, 0));
    }
}

2. ReentrantLock: Fine-Grained Control

The Problem: Multiple threads update a shared resource. synchronized blocks forever if the lock is held. You need timeouts, interruptibility, or fair queueing.

ReentrantLock provides explicit locking with timeout and interruption support. More verbose than synchronized, but you control when to give up waiting.

Key mechanism: tryLock(timeout) returns false if lock isn’t acquired within the timeout. Thread doesn’t block indefinitely.

import java.util.concurrent.locks.*;
import java.nio.file.*;
import java.util.concurrent.TimeUnit;

public class ConfigurationManager {
    private final Lock configLock = new ReentrantLock(true); // fair lock
    private final Path configFile;
    private String cachedConfig;
    
    public ConfigurationManager(Path configFile) {
        this.configFile = configFile;
    }
    
    public void updateConfig(String newConfig) {
        // Try to acquire lock with timeout
        try {
            if (configLock.tryLock(5, TimeUnit.SECONDS)) {
                try {
                    System.out.println(Thread.currentThread().getName() + " - Updating config...");
                    
                    // Write to file
                    Files.writeString(configFile, newConfig);
                    
                    // Update cache
                    cachedConfig = newConfig;
                    
                    // Simulate some processing
                    Thread.sleep(1000);
                    
                    System.out.println(Thread.currentThread().getName() + " - Config updated");
                    
                } finally {
                    configLock.unlock(); // ALWAYS in finally block
                }
            } else {
                System.err.println(Thread.currentThread().getName() + 
                                 " - Could not acquire lock within 5 seconds");
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            System.err.println(Thread.currentThread().getName() + " - Interrupted while waiting for lock");
        } catch (Exception e) {
            System.err.println("Config update failed: " + e.getMessage());
        }
    }
    
    public String readConfig() {
        configLock.lock();
        try {
            if (cachedConfig == null) {
                cachedConfig = Files.readString(configFile);
            }
            return cachedConfig;
        } catch (Exception e) {
            return "Error reading config";
        } finally {
            configLock.unlock();
        }
    }
    
    // Advanced: Check lock status without blocking
    public boolean isConfigBeingUpdated() {
        return ((ReentrantLock) configLock).isLocked();
    }
}

Why not synchronized?

synchronized blocks forever if the lock is held. No timeout. No interruption. No way to check if locked without blocking.

ReentrantLock adds:

tryLock(timeout) - give up after N seconds
lockInterruptibly() - thread can be interrupted while waiting
Fair mode - threads acquire lock in request order (prevents starvation)
isLocked() - check status without blocking

Trade-offs

What you gain:

Timeout support. Fail fast instead of blocking forever.
Interruptibility. Shutdown threads cleanly mid-wait.
Fair mode. Prevent thread starvation under contention.
Condition variables. Multiple wait queues per lock.

What you pay:

Manual unlock. Forget finally block = permanent lock.
More verbose. 5 lines vs 1 for synchronized.
Deadlock risk unchanged. Lock ordering still matters.
No compiler help. synchronized checks happen at bytecode level.

synchronized vs ReentrantLock:

Feature	synchronized	ReentrantLock
Timeout	❌	✅ tryLock(timeout)
Interruptible	❌	✅ lockInterruptibly()
Fair mode	❌	✅ new ReentrantLock(true)
Try without blocking	❌	✅ tryLock()
Condition variables	❌ (wait/notify only)	✅ newCondition()
Automatic unlock	✅	❌ (must use finally)
Performance	Slightly better	Slightly worse
Simplicity	✅	❌

Failure modes:

// WRONG: Exception skips unlock
lock.lock();
doWork(); // Throws IOException
lock.unlock(); // Never executes. Lock held forever.
// All other threads block forever on this lock.

// CORRECT: finally guarantees unlock
lock.lock();
try {
    doWork();
} finally {
    lock.unlock(); // Runs even if doWork() throws
}

// WRONG: Inconsistent lock order causes deadlock
// Thread 1: transfer(accountA, accountB, 100)
synchronized(accountA) {
    synchronized(accountB) { /* transfer */ }
}

// Thread 2: transfer(accountB, accountA, 50)
synchronized(accountB) {
    synchronized(accountA) { /* transfer */ }
}
// Thread 1 holds A, waits for B
// Thread 2 holds B, waits for A
// Deadlock. Both threads blocked forever.

// CORRECT: Always acquire locks in same order
Lock first = getLockById(Math.min(idA, idB));
Lock second = getLockById(Math.max(idA, idB));
first.lock();
try {
    second.lock();
    try {
        doWork();
    } finally {
        second.unlock();
    }
} finally {
    first.unlock();
}
// Both threads acquire locks in ascending ID order. No circular wait.

// WRONG: tryLock without finally
if (lock.tryLock()) {
    doWork(); // Throws exception
    lock.unlock(); // Never executes
}
// Lock held forever

// CORRECT: tryLock with finally
if (lock.tryLock()) {
    try {
        doWork();
    } finally {
        lock.unlock(); // Runs even if doWork() throws
    }
} else {
    // Lock was held. Handle failure.
}

// WRONG: Ignoring interruption
lock.lockInterruptibly(); // Throws InterruptedException - must catch

// CORRECT: Restore interrupt status
try {
    lock.lockInterruptibly();
    try {
        doWork();
    } finally {
        lock.unlock();
    }
} catch (InterruptedException e) {
    Thread.currentThread().interrupt(); // Restore flag
    // Thread was interrupted. Exit gracefully.
}

Advanced Pattern: Read-Write Lock

public class CachedData {
    private final ReadWriteLock rwLock = new ReentrantReadWriteLock();
    private final Lock readLock = rwLock.readLock();
    private final Lock writeLock = rwLock.writeLock();
    private Map<String, String> cache = new HashMap<>();
    
    public String read(String key) {
        readLock.lock(); // Multiple readers allowed
        try {
            return cache.get(key);
        } finally {
            readLock.unlock();
        }
    }
    
    public void write(String key, String value) {
        writeLock.lock(); // Exclusive access
        try {
            cache.put(key, value);
        } finally {
            writeLock.unlock();
        }
    }
    
    // Upgrade pattern: read -> write (tricky!)
    public void updateIfNeeded(String key, String newValue) {
        readLock.lock();
        try {
            String current = cache.get(key);
            if (needsUpdate(current, newValue)) {
                // Release read lock before acquiring write lock
                readLock.unlock();
                writeLock.lock();
                try {
                    // Re-check after acquiring write lock
                    current = cache.get(key);
                    if (needsUpdate(current, newValue)) {
                        cache.put(key, newValue);
                    }
                    // Downgrade: acquire read lock before releasing write
                    readLock.lock();
                } finally {
                    writeLock.unlock();
                }
            }
        } finally {
            readLock.unlock();
        }
    }
}

3. Phaser: Dynamic Multi-Phase Coordination

The Problem: ETL pipeline with Extract → Transform → Load phases. Workers join when data arrives. Workers leave when their partition completes. Party count changes during execution.

CountDownLatch: Fixed count at creation. Cannot add parties. CyclicBarrier: Fixed parties. Cannot add or remove. Phaser: Parties register and deregister during execution.

How it works: Each worker calls register() on arrival and arriveAndDeregister() on completion. Phaser tracks current party count. Phase advances when all registered parties arrive.

import java.util.concurrent.*;
import java.util.stream.IntStream;

public class ETLPipeline {
    
    static class ETLWorker implements Runnable {
        private final Phaser phaser;
        private final int workerId;
        
        public ETLWorker(Phaser phaser, int workerId) {
            this.phaser = phaser;
            this.workerId = workerId;
            phaser.register(); // Register this worker
        }
        
        @Override
        public void run() {
            try {
                System.out.println("Worker-" + workerId + " - Starting EXTRACT phase");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println("Worker-" + workerId + " - EXTRACT complete");
                
                phaser.arriveAndAwaitAdvance(); // Wait for all workers to finish extract
                
                System.out.println("Worker-" + workerId + " - Starting TRANSFORM phase");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println("Worker-" + workerId + " - TRANSFORM complete");
                
                phaser.arriveAndAwaitAdvance(); // Wait for all workers to finish transform
                
                System.out.println("Worker-" + workerId + " - Starting LOAD phase");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println("Worker-" + workerId + " - LOAD complete");
                
                phaser.arriveAndDeregister(); // Complete and leave
                
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
    }
    
    public void runPipeline() throws InterruptedException {
        // Create phaser with 1 party (main thread)
        Phaser phaser = new Phaser(1) {
            @Override
            protected boolean onAdvance(int phase, int registeredParties) {
                System.out.println("\n=== Phase " + phase + " completed. " + 
                                 registeredParties + " parties registered ===\n");
                return false; // Continue to next phase
            }
        };
        
        ExecutorService pool = Executors.newFixedThreadPool(4);
        
        // Start initial workers
        IntStream.range(0, 4).forEach(i -> 
            pool.submit(new ETLWorker(phaser, i))
        );
        
        // Simulate dynamic worker joining mid-process
        Thread.sleep(2000);
        System.out.println("\n>>> NEW WORKER JOINING <<<\n");
        pool.submit(new ETLWorker(phaser, 99));
        
        // Main thread deregisters
        phaser.arriveAndDeregister();
        
        pool.shutdown();
        pool.awaitTermination(1, TimeUnit.MINUTES);
        
        System.out.println("\nETL Pipeline complete!");
    }
}

When to use Phaser:

Parties join/leave during execution
More than 2 phases
Need phase number tracking

When NOT to use:

Fixed party count → Use CountDownLatch or CyclicBarrier
Single phase → Use CountDownLatch
Adds complexity. Only use when simpler tools don’t fit.

Trade-offs

What you gain:

Dynamic parties. Add workers mid-execution. Remove when done.
Unlimited phases. CountDownLatch is one-shot. CyclicBarrier resets but doesn’t track phase number.
Phase callbacks. onAdvance() runs between phases.
Termination control. Return true from onAdvance() to stop.

What you pay:

Complexity. Hardest synchronizer to reason about.
Register/deregister bugs. Forget to deregister = phase never advances.
Higher overhead. Atomic operations on every arrive() call.
Debugging difficulty. Thread dump shows “waiting on Phaser” but not which phase.

Failure modes:

// WRONG: Arrive without registering
Phaser phaser = new Phaser(1);
pool.submit(() -> {
    phaser.arriveAndAwaitAdvance(); // IllegalStateException
    // Thread never registered. Phaser doesn't know about it.
});

// CORRECT: Register before arriving
class Worker implements Runnable {
    private final Phaser phaser;
    
    Worker(Phaser phaser) {
        this.phaser = phaser;
        phaser.register(); // Increment party count
    }
    
    public void run() {
        phaser.arriveAndAwaitAdvance(); // Now valid
    }
}

// WRONG: Register but never deregister
phaser.register(); // Party count = 2
doWork();
return; // Exit without deregistering
// Party count still 2. Other threads wait forever for this thread.

// CORRECT: Deregister in finally
phaser.register();
try {
    doWork();
    phaser.arriveAndAwaitAdvance();
} finally {
    phaser.arriveAndDeregister(); // Decrement party count
}

// MISTAKE 3: onAdvance returns true too early
Phaser phaser = new Phaser(1) {
    @Override
    protected boolean onAdvance(int phase, int registeredParties) {
        return true; // Terminates immediately!
    }
};

// CORRECT: Return true only when done
protected boolean onAdvance(int phase, int registeredParties) {
    System.out.println("Phase " + phase + " complete");
    return phase >= 2 || registeredParties == 0; // Stop after phase 2
}

Phaser vs CountDownLatch vs CyclicBarrier:

Feature	CountDownLatch	CyclicBarrier	Phaser
Reusable	❌	✅	✅
Dynamic parties	❌	❌	✅
Multiple phases	❌	✅	✅
Phase tracking	❌	❌	✅
Complexity	Low	Low	High
Use case	One-shot wait	Fixed multi-phase	Dynamic multi-phase

Debugging Concurrent Code

Reading Thread Dumps

Application hangs. No error logs. No exceptions. Take a thread dump—it shows every thread’s current state and stack trace.

Windows:

# Get PID
jps

# Generate thread dump
jstack <PID> > thread_dump.txt

# Or send Ctrl+Break to console

Linux:

`1`	`kill -3 <PID> # Sends SIGQUIT, creates thread dump`

Example thread dump entry:

"payment-worker-1" #23 prio=5 os_prio=0 tid=0x00007f8a2c001000 nid=0x4d2 waiting on condition
   java.lang.Thread.State: WAITING (parking)
        at sun.misc.Unsafe.park(Native Method)
        at java.util.concurrent.locks.LockSupport.park(LockSupport.java:175)
        at java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt
        at java.util.concurrent.CountDownLatch.await(CountDownLatch.java:231)
        at com.example.Service.process(Service.java:45)

What this tells you:

Thread state: WAITING means blocked on a synchronizer (CountDownLatch, Semaphore, Lock)
Stack trace: Shows where thread is stuck (line 45 in Service.java)
Lock info: Which object thread is waiting on

Red flags:

Many threads WAITING on same object → Someone forgot countDown() or release()
BLOCKED threads with circular dependencies → Deadlock
Threads named “pool-1-thread-X” → No custom ThreadFactory (debugging nightmare)
Thread in RUNNABLE for minutes → Infinite loop or expensive computation

Common Deadlock Patterns

Pattern 1: Lock Ordering Deadlock

Why it deadlocks: Thread 1 holds lock A, needs lock B. Thread 2 holds lock B, needs lock A. Neither can proceed.

// DEADLOCK
class Account {
    private final Object lock = new Object();
    
    public void transfer(Account to, double amount) {
        synchronized (this.lock) {              // Thread 1 locks A
            synchronized (to.lock) {             // Thread 1 waits for B
                this.balance -= amount;
                to.balance += amount;
            }
        }
    }
}

// Thread 1: accountA.transfer(accountB, 100);  // Locks A, waits for B
// Thread 2: accountB.transfer(accountA, 50);   // Locks B, waits for A
// Both threads wait forever.

// FIX: Always acquire locks in same order
// Use object hash code to determine order
public void transfer(Account to, double amount) {
    Account first = System.identityHashCode(this) < System.identityHashCode(to) 
                    ? this : to;
    Account second = first == this ? to : this;
    
    synchronized (first.lock) {
        synchronized (second.lock) {
            if (this != first) {
                to.balance += amount;
                this.balance -= amount;
            } else {
                this.balance -= amount;
                to.balance += amount;
            }
        }
    }
}

// Now both threads acquire locks in same order. No circular wait.

Pattern 2: Nested Lock Acquisition

Why it deadlocks: method1() acquires lock1 → lock2 method2() acquires lock2 → lock1 Opposite order = deadlock

// DEADLOCK
class Service {
    private final Lock lock1 = new ReentrantLock();
    private final Lock lock2 = new ReentrantLock();
    
    public void method1() {
        lock1.lock();
        try {
            lock2.lock();  // Acquires lock2 while holding lock1
            try {
                doWork();
            } finally {
                lock2.unlock();
            }
        } finally {
            lock1.unlock();
        }
    }
    
    public void method2() {
        lock2.lock();
        try {
            lock1.lock();  // Opposite order!
            try {
                doWork();
            } finally {
                lock1.unlock();
            }
        } finally {
            lock2.unlock();
        }
    }
}

// FIX: Use tryLock with timeout
// If can't acquire second lock, release first and retry
public void method2() {
    lock2.lock();
    try {
        if (lock1.tryLock(1, TimeUnit.SECONDS)) {
            try {
                doWork();
            } finally {
                lock1.unlock();
            }
        } else {
            // Failed to acquire lock1 - back off
            throw new TimeoutException("Could not acquire lock");
        }
    } finally {
        lock2.unlock();
    }
}

Pattern 3: Forgotten CountDownLatch

Why it hangs: Latch expects 3 countdowns. Task only counts down on success. If task fails, count stays at 3. await() blocks forever.

// HANGS FOREVER
CountDownLatch latch = new CountDownLatch(3);
pool.submit(() -> {
    doWork();
    if (success) {  // BUG: Conditional countdown
        latch.countDown();
    }
});

latch.await(); // Waits forever if doWork() fails

// FIX: Always countDown, regardless of success
pool.submit(() -> {
    try {
        doWork();
    } finally {
        latch.countDown(); // Executes even if doWork() throws
    }
});

Detecting Deadlocks Programmatically

public class DeadlockDetector {
    public static void detectDeadlocks() {
        ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
        long[] deadlockedThreads = threadBean.findDeadlockedThreads();
        
        if (deadlockedThreads != null) {
            ThreadInfo[] threadInfos = threadBean.getThreadInfo(deadlockedThreads);
            
            System.err.println("DEADLOCK DETECTED!");
            for (ThreadInfo info : threadInfos) {
                System.err.println("Thread: " + info.getThreadName());
                System.err.println("Locked on: " + info.getLockName());
                System.err.println("Waiting for: " + info.getLockOwnerName());
                System.err.println("Stack trace:");
                for (StackTraceElement element : info.getStackTrace()) {
                    System.err.println("  " + element);
                }
            }
            
            // Alert monitoring system
            alertOps("Deadlock detected!");
        }
    }
}

Monitoring Concurrent Systems

Why monitor: Thread pools fail silently. Queue fills up. Threads deadlock. No exceptions thrown. Metrics reveal problems before users notice.

Key Metrics to Track

public class ConcurrencyMetrics {
    private final MeterRegistry registry;
    
    public void setupMetrics(ExecutorService pool, BlockingQueue<?> queue) {
        // Thread pool metrics
        if (pool instanceof ThreadPoolExecutor) {
            ThreadPoolExecutor tpe = (ThreadPoolExecutor) pool;
            
            registry.gauge("threadpool.active", tpe, ThreadPoolExecutor::getActiveCount);
            registry.gauge("threadpool.size", tpe, ThreadPoolExecutor::getPoolSize);
            registry.gauge("threadpool.queue.size", tpe, 
                e -> e.getQueue().size());
            
            // Alert if queue is growing
            registry.gauge("threadpool.queue.utilization", tpe, e -> {
                int queueSize = e.getQueue().size();
                int remainingCapacity = e.getQueue().remainingCapacity();
                return (double) queueSize / (queueSize + remainingCapacity);
            });
        }
        
        // Task execution metrics
        registry.timer("task.execution.time");
        registry.counter("task.completed");
        registry.counter("task.failed");
        
        // Liveness check
        registry.gauge("system.deadlocked.threads", this, 
            m -> countDeadlockedThreads());
    }
    
    private long countDeadlockedThreads() {
        ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
        long[] deadlocked = threadBean.findDeadlockedThreads();
        return deadlocked != null ? deadlocked.length : 0;
    }
}

Critical Alerts

Alert on:

Queue depth > 80% capacity

What it means: Producers add tasks faster than consumers process them.

What breaks: Queue fills. New tasks rejected or block forever.
1 2 3

if (queueUtilization > 0.8) { alert("Queue nearly full - scale consumers"); }
All threads busy for > 1 minute

What it means: Every thread in pool is working. No idle threads.

What breaks: New tasks queue up. Latency increases.
1 2 3

if (activeThreads == poolSize && duration > 60_000) { alert("Thread pool saturated - increase size"); }
Task duration p99 > SLA

What it means: 99th percentile task takes longer than expected.

What breaks: User-facing timeouts. SLA violations.
1 2 3

if (taskDurationP99 > slaMs) { alert("Task latency exceeds SLA"); }
Deadlock detected

What it means: Threads waiting on each other in a cycle.

What breaks: Application hangs. Requires restart.
1 2 3

if (deadlockedThreads > 0) { alert("CRITICAL: Deadlock - restart required"); }
Thread count growing

What it means: New threads created but never destroyed.

What breaks: Eventually hits OS thread limit. OutOfMemoryError.
1 2 3

if (threadCountDelta > 10 && timeWindow < 60_000) { alert("Thread leak detected"); }

Common Anti-Patterns Across All Tools

1. Thread Pool Sizing

// ANTI-PATTERN: Magic numbers
ExecutorService pool = Executors.newFixedThreadPool(42);

// CORRECT: Calculate based on workload
int poolSize = Runtime.getRuntime().availableProcessors() * 
               (isCpuBound ? 1 : 2);

// BETTER: Formula for I/O-bound
// ThreadCount = NumCores * (1 + WaitTime/ComputeTime)
int poolSize = cores * (1 + (int)(waitTimeMs / computeTimeMs));

2. Ignoring Shutdown

What breaks: Threads keep running after method returns. JVM doesn’t exit. Application hangs on shutdown.

// WRONG: No shutdown
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    pool.submit(() -> work());
} // Threads still running. Pool never cleaned up.

// CORRECT: Shutdown sequence
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    try {
        pool.submit(() -> work()).get();
    } finally {
        pool.shutdown();                              // Stop accepting new tasks
        if (!pool.awaitTermination(60, TimeUnit.SECONDS)) {
            pool.shutdownNow();                       // Force stop running tasks
        }
    }
}

3. Daemon Threads for Critical Work

What breaks: JVM exits while daemon thread is mid-write. Database transaction incomplete. Data corrupted.

The rule: Daemon threads die when JVM exits. Non-daemon threads keep JVM alive until they finish.

// WRONG: Daemon thread for DB writes
ThreadFactory factory = r -> {
    Thread t = new Thread(r);
    t.setDaemon(true); // JVM exits → thread dies → DB write lost
    return t;
};

// CORRECT: Non-daemon for critical work
ThreadFactory factory = r -> {
    Thread t = new Thread(r);
    t.setDaemon(false); // JVM waits for thread to finish
    return t;
};

4. Unbounded Queues

What breaks: Producer faster than consumer. Queue grows. Heap fills. OutOfMemoryError.

// WRONG: Unbounded queue
BlockingQueue<Task> queue = new LinkedBlockingQueue<>(); // No limit!

// CORRECT: Bounded queue
BlockingQueue<Task> queue = new ArrayBlockingQueue<>(1000);
// When full, put() blocks. Producer slows down. Backpressure applied.

5. Swallowing Exceptions

What breaks: Task throws exception. submit() catches it silently. No logs. No alerts. Silent failure.

Why it happens: submit() returns Future. Exception stored in Future. If you don’t call get(), you never see it.

// WRONG: Exception disappears
pool.submit(() -> {
    riskyOperation(); // Throws exception → stored in Future → never retrieved
});

// CORRECT: Explicit error handling
pool.submit(() -> {
    try {
        riskyOperation();
    } catch (Exception e) {
        logger.error("Task failed", e);
        errorTracker.captureException(e);
    }
});

Integration Example: Complete Concurrent Pipeline

Combining multiple tools to build a realistic image processing pipeline:

public class ProductionImagePipeline {
    private final ExecutorService downloadPool;
    private final ExecutorService processPool;
    private final BlockingQueue<ImageTask> downloadQueue;
    private final BlockingQueue<ImageTask> processQueue;
    private final Semaphore rateLimiter;
    private final MeterRegistry metrics;
    
    public ProductionImagePipeline(MeterRegistry metrics) {
        this.metrics = metrics;
        
        // Custom thread factories for debugging
        this.downloadPool = Executors.newFixedThreadPool(10,
            new NamedThreadFactory("image-downloader", false, Thread.NORM_PRIORITY));
        this.processPool = Executors.newFixedThreadPool(4,
            new NamedThreadFactory("image-processor", false, Thread.NORM_PRIORITY));
        
        // Bounded queues for backpressure
        this.downloadQueue = new ArrayBlockingQueue<>(100);
        this.processQueue = new ArrayBlockingQueue<>(50);
        
        // Rate limiter: 10 downloads per second
        this.rateLimiter = new Semaphore(10, true);
        
        // Setup monitoring
        setupMetrics();
    }
    
    public CompletableFuture<ProcessedImage> process(String imageUrl) {
        return CompletableFuture
            .supplyAsync(() -> downloadWithRetry(imageUrl), downloadPool)
            .thenApplyAsync(image -> processImage(image), processPool)
            .exceptionally(ex -> {
                metrics.counter("pipeline.failed").increment();
                logger.error("Pipeline failed for " + imageUrl, ex);
                return null;
            });
    }
    
    private RawImage downloadWithRetry(String url) {
        // DelayQueue pattern for retry
        int attempt = 0;
        while (attempt < 3) {
            try {
                // Rate limiting with semaphore
                rateLimiter.acquire();
                try {
                    return download(url);
                } finally {
                    rateLimiter.release();
                }
            } catch (Exception e) {
                attempt++;
                if (attempt >= 3) throw e;
                
                long backoff = (long) Math.pow(2, attempt) * 1000;
                Thread.sleep(backoff);
            }
        }
        throw new RuntimeException("Max retries exceeded");
    }
    
    private void setupMetrics() {
        metrics.gauge("queue.download.size", downloadQueue, BlockingQueue::size);
        metrics.gauge("queue.process.size", processQueue, BlockingQueue::size);
        metrics.gauge("ratelimiter.available", rateLimiter, 
            Semaphore::availablePermits);
    }
    
    public void shutdown() {
        downloadPool.shutdown();
        processPool.shutdown();
        try {
            downloadPool.awaitTermination(60, TimeUnit.SECONDS);
            processPool.awaitTermination(60, TimeUnit.SECONDS);
        } catch (InterruptedException e) {
            downloadPool.shutdownNow();
            processPool.shutdownNow();
        }
    }
}

Production Readiness Checklist

Before deploying concurrent code:

Resource Management

All thread pools have bounded queues
Shutdown handlers registered
Timeouts on all blocking operations
Thread pool sizes calculated, not guessed

Observability

Thread pools have meaningful names (ThreadFactory)
Queue depths monitored
Task execution times tracked
Deadlock detection enabled
Exception handlers log to monitoring system

Error Handling

All Future.get() calls have timeouts
Async task exceptions logged
Circuit breakers on external calls
Retry logic with exponential backoff

Testing

Load tests with concurrent users
Chaos engineering (kill threads mid-execution)
Thread dump analysis under load
Memory profiling for leaks

Complete Toolkit Summary (All 3 Parts)

Execution Tools (Part 1 - Day 95)

Executor → Submit and forget tasks
ExecutorService → Managed thread pools
ScheduledExecutorService → Periodic execution
Future → Blocking result retrieval
CompletableFuture → Non-blocking async pipelines
CountDownLatch → One-shot coordination

Synchronization Tools (Part 2 - Day 96)

CyclicBarrier → Multi-phase checkpoints
Semaphore → Resource limiting
ThreadFactory → Thread customization
BlockingQueue → Producer-consumer

Advanced Tools (Part 3 - Today)

DelayQueue → Delayed execution
ReentrantLock → Custom locking
Phaser → Dynamic multi-phase

Choosing the Right Tool: Decision Tree

From my understanding we can have draw this decision tree as our mental model where we can have some idea to choose which tool will go with whic types of task the best.

Key Principles I’ve Learned

1. Always Set Timeouts

Future.get() without timeout blocks forever if task hangs. Lock.lock() without timeout deadlocks permanently. Always use timeout variants: get(timeout), tryLock(timeout), acquire(timeout).

2. Name Your Threads

Thread dump shows “pool-1-thread-17”. Which service? Which operation? Unknown. Custom ThreadFactory adds meaningful names: “payment-processor-3”. Debugging becomes possible.

3. Monitor Queue Depths

Queue at 10% → normal. Queue at 90% → consumers falling behind. Queue at 100% → producers blocking. Monitor queue depth. Alert before it fills.

4. Graceful Shutdown is Hard

Three steps: shutdown() stops accepting new tasks. awaitTermination(timeout) waits for running tasks. shutdownNow() interrupts if timeout exceeded. Miss any step → threads leak or work lost.

5. Beware of Daemon Threads

Daemon thread flushing logs. JVM exits. Thread dies mid-write. Logs lost. Use daemon threads only for non-critical background work.

6. Fair vs Unfair Locks Matter

Fair lock: threads acquire in request order. Prevents starvation. Lower throughput. Unfair lock: any thread can acquire. Higher throughput. Starvation possible. Default is unfair. Choose explicitly.

7. Bounded Resources Prevent Cascading Failures

Unbounded queue fills memory. OOM kills application. Bounded queue applies backpressure. Producer slows down. System stays alive.

8. Composition Over Complexity

Need one-shot coordination? CountDownLatch. Need reusable barrier? CyclicBarrier. Need dynamic parties? Then Phaser. Start simple. Add complexity only when required.

When NOT to Use These Tools

Before reaching for concurrency, ask:

Don’t use if:

Sequential processing takes < 100ms
Task is sequential (B depends on A)
Dataset is small (< 1000 items)
Debugging complexity outweighs performance gain
Team lacks concurrency expertise

Do use if:

I/O-bound operations (network, disk, DB)
Independent tasks that parallelize
Need to keep UI/API responsive
Processing large datasets
Proven bottleneck exists

Rule: Measure first. Prove the bottleneck. Then add concurrency. Concurrency adds complexity. Complexity adds bugs. Only pay that cost when the benefit is real.

Understanding the Complete Toolkit

Over these three parts, we’ve explored 13 essential concurrency tools. I’ve used some extensively in production (ExecutorService, Future, CountDownLatch, ReentrantLock), while others (Phaser, DelayQueue) I’m still mastering.

The insight: Concurrency isn’t about speed. It’s about structure. How do you coordinate independent work? How do you prevent threads from corrupting shared state? How do you fail gracefully under load?

Each tool solves a specific problem:

Execute? → ExecutorService
Wait? → CountDownLatch / CyclicBarrier / Phaser
Limit? → Semaphore
Pass work? → BlockingQueue
Delay? → DelayQueue / ScheduledExecutorService
Custom locking? → ReentrantLock

The skill is knowing which tool fits your use case. That’s what these 13 tools teach.

What’s Next?

This completes our deep dive into java.util.concurrent. More to learn:

Virtual Threads (Java 19+) - Lightweight threads that change the concurrency model
Reactive Streams - Async streams with backpressure (Project Reactor, RxJava)
Fork/Join Framework - Recursive parallelism for divide-and-conquer
Parallel Streams - When and when not to use them
Structured Concurrency (Preview) - Better async task management

Next time you’re tempted to spawn a raw Thread, ask yourself: which of these 13 patterns fits my use case?

That’s the question I’m learning to answer.

Previous: Day 96 - Java Concurrency Toolkit Part 2: Core Synchronization Patterns

Day 96: Java Concurrency Toolkit Part 2 - Core Synchronization Patterns

2025-12-10T00:00:00Z

Series Navigation: Part 1: Foundation & Execution • Part 2 (You are here) • Part 3: Advanced Patterns

“The art of concurrent programming lies not in making things parallel, but in coordinating parallel things gracefully."

In Part 1 (Day 95), we covered foundation and execution patterns: Executor, ExecutorService, ScheduledExecutorService, Future, CompletableFuture, and CountDownLatch. These tools execute tasks concurrently.

Part 2 covers core synchronization patterns—the tools that coordinate threads and protect shared resources.

Series Overview

This is a 3-part series on Java Concurrency:

Part 1 (Day 95): Foundation & Execution

Executor, ExecutorService, ScheduledExecutorService
Future, CompletableFuture, CountDownLatch

Part 2 (Today - Day 96): Core Synchronization Patterns

CyclicBarrier, Semaphore, ThreadFactory, BlockingQueue

Part 3 (Day 97): Advanced Patterns & Production Readiness

DelayQueue, ReentrantLock, Phaser
Debugging, Monitoring, Production Patterns

What We’re Covering Today

Part 2 (Today): Core Synchronization Patterns

CyclicBarrier - Reusable multi-phase synchronization
Semaphore - Resource pool management
ThreadFactory - Production-ready thread management
BlockingQueue - Producer-consumer patterns

Quick Reference: Part 2 Tools at a Glance

Tool	TL;DR	Caveat
CyclicBarrier	Reusable synchronization checkpoint for fixed threads. All must arrive before any proceed.	Fixed party count. If one thread fails, all block forever
Semaphore	Controls concurrent access to limited resources. Think “permission slips” (N max).	Must release in `finally` - easy to leak permits
ThreadFactory	Customizes thread creation. Name your threads for debugging!	Daemon threads die when JVM exits - bad for critical work
BlockingQueue	Decouples producers/consumers with thread-safe queue. Built-in backpressure.	Unbounded queues = OOM. Use bounded `ArrayBlockingQueue`

The Coordination Challenge

Part 1 showed how to execute work concurrently. But execution alone isn’t enough. Real systems need coordination:

Think of it like a construction project:

Workers need to sync at checkpoints (CyclicBarrier)
Only X workers can use the crane at once (Semaphore)
Workers need proper uniforms and tools (ThreadFactory)
Materials move between stations (BlockingQueue)

1. CyclicBarrier: Multi-Phase Processing

The Problem: You’re processing a large dataset in three phases: Extract → Transform → Load. Each phase must finish across all threads before the next begins.

Use CyclicBarrier for batch processing with distinct phases. Unlike CountDownLatch (one-shot), CyclicBarrier resets after each phase. This makes iterative processing simple.

The Solution: Synchronized phase transitions with CyclicBarrier.

import java.util.concurrent.*;
import java.util.stream.IntStream;

public class BatchProcessor {
    private final int workerCount;
    
    public BatchProcessor(int workerCount) {
        this.workerCount = workerCount;
    }
    
    public void processBatch() throws InterruptedException {
        CyclicBarrier barrier = new CyclicBarrier(
            workerCount,
            () -> System.out.println("--- Phase completed. All workers synchronized ---")
        );
        
        ExecutorService pool = Executors.newFixedThreadPool(workerCount);
        
        Runnable worker = () -> {
            try {
                String threadName = Thread.currentThread().getName();
                
                // Phase 1: Extract
                System.out.println(threadName + " - Extracting data...");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println(threadName + " - Extract complete");
                
                barrier.await(); // Wait for all threads to finish Phase 1
                
                // Phase 2: Transform
                System.out.println(threadName + " - Transforming data...");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println(threadName + " - Transform complete");
                
                barrier.await(); // Wait for all threads to finish Phase 2
                
                // Phase 3: Load
                System.out.println(threadName + " - Loading data...");
                Thread.sleep(ThreadLocalRandom.current().nextInt(500, 1500));
                System.out.println(threadName + " - Load complete");
                
                barrier.await(); // Wait for all threads to finish Phase 3
                
            } catch (InterruptedException | BrokenBarrierException e) {
                System.err.println("Worker interrupted: " + e.getMessage());
            }
        };
        
        // Submit all workers
        IntStream.range(0, workerCount)
                .forEach(i -> pool.submit(worker));
        
        pool.shutdown();
        pool.awaitTermination(1, TimeUnit.MINUTES);
        
        System.out.println("Batch processing complete!");
    }
}

Key Difference from CountDownLatch: CyclicBarrier is reusable. After all threads reach the barrier, it resets automatically. Use it for iterative or phase-based processing.

Visualizing CyclicBarrier

Here’s a sequence diagram showing how CyclicBarrier works:

Trade-offs and Limitations

Pros:

Reusable (unlike CountDownLatch)
Built-in barrier action (callback when all arrive)
Low overhead
Thread-safe reset

Cons:

Fixed number of parties (must be known at creation)
If one thread fails, others wait forever (unless you handle BrokenBarrierException)
No dynamic party registration (use Phaser instead)
All threads must reach barrier together (can’t have stragglers)

Common Mistakes:

// MISTAKE 1: Wrong party count
CyclicBarrier barrier = new CyclicBarrier(5);
for (int i = 0; i < 3; i++) { // Only 3 threads!
    pool.submit(() -> {
        doWork();
        barrier.await(); // Blocks forever! Only 3/5 arrived
    });
}

// CORRECT: Match party count
int parties = 3;
CyclicBarrier barrier = new CyclicBarrier(parties);
for (int i = 0; i < parties; i++) {
    pool.submit(() -> {
        doWork();
        barrier.await();
    });
}

// MISTAKE 2: Not handling BrokenBarrierException
pool.submit(() -> {
    doWork();
    barrier.await(); // What if another thread throws exception?
});

// CORRECT: Handle broken barrier
pool.submit(() -> {
    try {
        doWork();
        barrier.await();
    } catch (BrokenBarrierException e) {
        System.err.println("Barrier broken! Aborting.");
        // Cleanup and exit
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
});

// MISTAKE 3: Reusing after reset without checking
if (barrier.isBroken()) {
    barrier.reset(); // Must reset explicitly if broken
}

// CORRECT: Check state before reuse
if (barrier.isBroken()) {
    barrier.reset();
}
barrier.await();

When to Use:

Fixed number of worker threads
Multi-phase processing where all must complete each phase
Iterative algorithms (simulations, game loops)

Don’t use when:

You need dynamic party count (use Phaser)
You need one-shot synchronization (use CountDownLatch)

2. Semaphore: Resource Pool Management

The Problem: Your database connection pool has 10 connections. If 50 threads query simultaneously, you overwhelm the pool and get timeouts.

Semaphore limits concurrent access to finite resources. Acquire a permit before using the resource, release it when done.

The Solution: Limit concurrent access with Semaphore.

import java.util.concurrent.*;

public class DatabaseService {
    private final Semaphore connectionPermits;
    private final int maxConnections;
    
    public DatabaseService(int maxConnections) {
        this.maxConnections = maxConnections;
        this.connectionPermits = new Semaphore(maxConnections, true); // fair=true for FIFO
    }
    
    public String executeQuery(String sql) {
        System.out.println(Thread.currentThread().getName() + " - Requesting DB connection...");
        
        try {
            // Try to acquire permit (blocks if none available)
            connectionPermits.acquire();
            
            System.out.println(Thread.currentThread().getName() + " - Got connection! " +
                             "Available: " + connectionPermits.availablePermits() + "/" + maxConnections);
            
            // Execute query
            String result = runActualQuery(sql);
            
            return result;
            
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "Query interrupted";
        } finally {
            // Always release permit
            connectionPermits.release();
            System.out.println(Thread.currentThread().getName() + " - Released connection");
        }
    }
    
    public boolean tryExecuteQueryWithTimeout(String sql, long timeoutMs) {
        try {
            // Try to acquire with timeout
            if (connectionPermits.tryAcquire(timeoutMs, TimeUnit.MILLISECONDS)) {
                try {
                    runActualQuery(sql);
                    return true;
                } finally {
                    connectionPermits.release();
                }
            } else {
                System.err.println("Could not acquire connection within " + timeoutMs + "ms");
                return false;
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return false;
        }
    }
    
    private String runActualQuery(String sql) {
        // Simulate DB query
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return "Result for: " + sql;
    }
}

Pro Tip: Use tryAcquire() with timeout in request handlers to fail fast instead of blocking indefinitely. Your users will thank you.

Trade-offs and Limitations

Pros:

Simple API (acquire/release)
Supports fair vs non-fair modes
Can try with timeout
Can query available permits
Very low overhead

Cons:

No automatic resource management (must call release in finally)
Permits can be released by any thread (not tied to acquirer)
No built-in timeout enforcement on resource usage
Can accidentally create permit leaks

Common Mistakes:

// MISTAKE 1: Forgetting to release
semaphore.acquire();
doWork(); // What if this throws?
semaphore.release(); // Never called!

// CORRECT: Always use try-finally
semaphore.acquire();
try {
    doWork();
} finally {
    semaphore.release(); // Always happens
}

// MISTAKE 2: Releasing without acquiring
semaphore.release(); // Increases permit count above initial!
// This creates "phantom permits" that break your resource limit

// CORRECT: Only release what you acquired
boolean acquired = semaphore.tryAcquire();
if (acquired) {
    try {
        doWork();
    } finally {
        semaphore.release();
    }
}

// MISTAKE 3: Using unfair mode for critical resources
Semaphore semaphore = new Semaphore(1, false); // unfair
// Threads can "cut in line" causing starvation

// CORRECT: Use fair mode for critical resources
Semaphore semaphore = new Semaphore(1, true); // fair = FIFO

What is Fair/Unfair in a Semaphore

I’ve mentioned fair/unfair mode in the code above. Here’s what they mean:

Semaphore operates in either fair or unfair mode. This determines the order waiting threads acquire permits. You trade guaranteed access for throughput.

Fair Mode:

Threads acquire permits in request order (FIFO queue)
The longest-waiting thread gets the next available permit
Prevents starvation—no thread waits forever while new threads keep acquiring permits
Use for critical resources like database connection pools

Unfair Mode:

Better performance—no FIFO queue overhead means fewer context switches
Higher throughput but some threads might starve

To create a fair semaphore, you use the constructor new Semaphore(int permits, true).

Real-World Use Cases:

Database connection pools
API rate limiting (X requests per second)
Limited worker threads for CPU-intensive tasks
Bounded parallelism in file I/O

Integration Example: Rate Limiting

public class RateLimiter {
    private final Semaphore permits;
    private final ScheduledExecutorService refiller;
    
    public RateLimiter(int permitsPerSecond) {
        this.permits = new Semaphore(permitsPerSecond, true);
        this.refiller = Executors.newScheduledThreadPool(1);
        
        // Refill permits every second
        refiller.scheduleAtFixedRate(() -> {
            int available = permits.availablePermits();
            int toAdd = permitsPerSecond - available;
            if (toAdd > 0) {
                permits.release(toAdd);
            }
        }, 1, 1, TimeUnit.SECONDS);
    }
    
    public boolean tryAcquire() {
        return permits.tryAcquire();
    }
}

3. ThreadFactory: Production-Ready Thread Management

The Problem: Your thread dump shows dozens of threads named pool-1-thread-X. You can’t debug which pool causes the issue.

Custom ThreadFactory gives you control over thread creation. Name threads for easier debugging and monitoring.

The Solution: Custom ThreadFactory with meaningful names and proper configuration.

import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

public class NamedThreadFactory implements ThreadFactory {
    private final String namePrefix;
    private final AtomicInteger threadNumber;
    private final boolean daemon;
    private final int priority;
    
    public NamedThreadFactory(String namePrefix, boolean daemon, int priority) {
        this.namePrefix = namePrefix;
        this.daemon = daemon;
        this.priority = priority;
        this.threadNumber = new AtomicInteger(1);
    }
    
    @Override
    public Thread newThread(Runnable r) {
        Thread t = new Thread(r);
        t.setName(namePrefix + "-" + threadNumber.getAndIncrement());
        t.setDaemon(daemon);
        t.setPriority(priority);
        
        // Add uncaught exception handler
        t.setUncaughtExceptionHandler((thread, throwable) -> {
            System.err.println("Uncaught exception in " + thread.getName() + ": " + 
                             throwable.getMessage());
            // In production: send to error tracking service like sentry, rollbar etc
        });
        
        return t;
    }
    
    public static ExecutorService createNamedPool(String name, int size) {
        return Executors.newFixedThreadPool(
            size,
            new NamedThreadFactory(name, false, Thread.NORM_PRIORITY)
        );
    }
}

// Usage example
class ServiceOrchestrator {
    private final ExecutorService paymentPool;
    private final ExecutorService notificationPool;
    private final ExecutorService analyticsPool;
    
    public ServiceOrchestrator() {
        this.paymentPool = NamedThreadFactory.createNamedPool("payment-worker", 8);
        this.notificationPool = NamedThreadFactory.createNamedPool("notification-worker", 4);
        this.analyticsPool = NamedThreadFactory.createNamedPool("analytics-worker", 2);
    }
    
    // Now thread dumps show: payment-worker-1, notification-worker-1, analytics-worker-1
    // Instead of: pool-1-thread-1, pool-2-thread-1, pool-3-thread-1
}

Production Checklist:

Meaningful thread names
Daemon status set correctly
Uncaught exception handlers
Appropriate priority levels

Trade-offs and Limitations

Pros:

Full control over thread properties
Consistent naming for debugging
Centralized exception handling
Can add custom initialization logic

Cons:

More boilerplate than default factories
Easy to forget to use it
Doesn’t prevent thread leaks (just makes them easier to find)

Common Mistakes:

// MISTAKE 1: Using daemon threads for critical work
ThreadFactory factory = r -> {
    Thread t = new Thread(r);
    t.setDaemon(true); // JVM can exit while thread is running!
    return t;
};
ExecutorService pool = Executors.newFixedThreadPool(10, factory);
pool.submit(() -> {
    writeToDatabase(); // May not complete before JVM exits!
});

// CORRECT: Non-daemon for critical work
ThreadFactory factory = r -> {
    Thread t = new Thread(r);
    t.setDaemon(false); // JVM waits for completion
    return t;
};

// MISTAKE 2: Not thread-safe counter
class BadFactory implements ThreadFactory {
    private int counter = 0; // Not thread-safe!
    
    public Thread newThread(Runnable r) {
        return new Thread(r, "worker-" + counter++);
    }
}

// CORRECT: Use AtomicInteger
class GoodFactory implements ThreadFactory {
    private final AtomicInteger counter = new AtomicInteger(0);
    
    public Thread newThread(Runnable r) {
        return new Thread(r, "worker-" + counter.getAndIncrement());
    }
}

// MISTAKE 3: Swallowing exceptions in handler
t.setUncaughtExceptionHandler((thread, throwable) -> {
    // Just print? Exception is lost!
    throwable.printStackTrace();
});

// CORRECT: Send to monitoring system
t.setUncaughtExceptionHandler((thread, throwable) -> {
    logger.error("Uncaught exception in " + thread.getName(), throwable);
    // Send to Sentry, Rollbar, etc.
    errorTracker.captureException(throwable);
    // Update metrics
    exceptionCounter.increment();
});

Monitoring Integration

public class MonitoredThreadFactory implements ThreadFactory {
    private final String namePrefix;
    private final AtomicInteger threadNumber = new AtomicInteger(1);
    private final AtomicInteger createdThreads;
    private final AtomicInteger activeThreads;
    
    public MonitoredThreadFactory(String namePrefix, MeterRegistry registry) {
        this.namePrefix = namePrefix;
        this.createdThreads = registry.gauge("threads.created", 
            Tags.of("pool", namePrefix), new AtomicInteger(0));
        this.activeThreads = registry.gauge("threads.active", 
            Tags.of("pool", namePrefix), new AtomicInteger(0));
    }
    
    @Override
    public Thread newThread(Runnable r) {
        createdThreads.incrementAndGet();
        activeThreads.incrementAndGet();
        
        Thread t = new Thread(() -> {
            try {
                r.run();
            } finally {
                activeThreads.decrementAndGet();
            }
        });
        
        t.setName(namePrefix + "-" + threadNumber.getAndIncrement());
        return t;
    }
}

4. BlockingQueue: The Producer-Consumer Pattern

The Problem: Your service receives 1000 requests/second but processes only 100/second. Without buffering, you drop requests or crash.

BlockingQueue decouples work submission from execution. It provides natural backpressure when consumers can’t keep up.

The Solution: Decouple producers from consumers with a bounded queue.

import java.util.concurrent.*;
import java.nio.file.*;
import java.util.stream.Stream;

public class ImageProcessingPipeline {
    private final BlockingQueue<Path> imageQueue;
    private final ExecutorService producers;
    private final ExecutorService consumers;
    private volatile boolean running;
    
    public ImageProcessingPipeline(int queueSize, int consumerCount) {
        this.imageQueue = new ArrayBlockingQueue<>(queueSize);
        this.producers = Executors.newSingleThreadExecutor(
            new NamedThreadFactory("image-producer", false, Thread.NORM_PRIORITY)
        );
        this.consumers = Executors.newFixedThreadPool(
            consumerCount,
            new NamedThreadFactory("image-consumer", false, Thread.NORM_PRIORITY)
        );
        this.running = true;
    }
    
    public void start(Path imageDirectory) {
        System.out.println("Starting image processing pipeline...");
        
        // Producer: Read image files and add to queue
        producers.submit(() -> {
            try (Stream<Path> paths = Files.list(imageDirectory)) {
                paths.filter(p -> p.toString().endsWith(".jpg"))
                     .forEach(path -> {
                         try {
                             System.out.println("Producer: Queuing " + path.getFileName());
                             imageQueue.put(path); // Blocks if queue is full
                         } catch (InterruptedException e) {
                             Thread.currentThread().interrupt();
                         }
                     });
                     
                // Signal completion by adding poison pills
                for (int i = 0; i < Runtime.getRuntime().availableProcessors(); i++) {
                    imageQueue.put(Paths.get("STOP")); // Sentinel value
                }
            } catch (Exception e) {
                System.err.println("Producer error: " + e.getMessage());
            }
        });
        
        // Consumers: Process images from queue
        int consumerCount = Runtime.getRuntime().availableProcessors();
        for (int i = 0; i < consumerCount; i++) {
            consumers.submit(() -> {
                while (running) {
                    try {
                        Path image = imageQueue.take(); // Blocks if queue is empty
                        
                        if (image.toString().equals("STOP")) {
                            System.out.println("Consumer received stop signal");
                            break;
                        }
                        
                        System.out.println("Consumer: Processing " + image.getFileName());
                        compressImage(image);
                        
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        break;
                    }
                }
            });
        }
    }
    
    private void compressImage(Path image) {
        // Simulate compression work
        try {
            Thread.sleep(500);
            System.out.println("Compressed: " + image.getFileName());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }
    
    public void shutdown() {
        running = false;
        producers.shutdown();
        consumers.shutdown();
    }
}

Key Pattern: Use the “poison pill” technique—a sentinel value (STOP in this example) that signals consumers to stop gracefully.

Trade-offs and Limitations

Pros:

Built-in backpressure (blocks when full)
Thread-safe operations
Natural decoupling of producers/consumers
Multiple queue implementations (Array, Linked, Priority, etc.)

Cons:

Bounded queues block producers when full
Unbounded queues cause OOM
No built-in monitoring for queue depth
Poison pill pattern needs careful coordination

Queue Implementation Trade-offs:

Implementation	Ordering	Bounded	Throughput	Use Case
ArrayBlockingQueue	FIFO	✅	High	Fixed capacity, predictable memory
LinkedBlockingQueue	FIFO	Optional	Medium	Variable load, unbounded acceptable
PriorityBlockingQueue	Priority	❌	Lower	Task prioritization needed
SynchronousQueue	N/A	N/A	Highest	Direct handoff (zero capacity)
DelayQueue	Delay time	❌	Medium	Delayed execution

Common Mistakes:

// MISTAKE 1: Unbounded queue with slow consumers
BlockingQueue<Task> queue = new LinkedBlockingQueue<>(); // Unbounded!
// Producer adds 1000 items/sec, consumer processes 10/sec
// Queue grows to millions = OOM!

// CORRECT: Bounded queue with backpressure
BlockingQueue<Task> queue = new ArrayBlockingQueue<>(1000);
// Producer blocks when queue is full = natural backpressure

// MISTAKE 2: Not handling interruption
queue.put(task); // Blocks if full, but what if interrupted?

// CORRECT: Handle interruption
try {
    queue.put(task);
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
    // Cleanup and exit gracefully
}

// MISTAKE 3: Poison pill per producer instead of per consumer
// 2 producers, 3 consumers
queue.put(STOP); // Only 1 consumer stops!

// CORRECT: One poison pill per consumer
int consumerCount = 3;
for (int i = 0; i < consumerCount; i++) {
    queue.put(STOP);
}

// MISTAKE 4: Losing tasks on shutdown
pool.shutdown(); // Queued tasks might not complete!

// CORRECT: Drain queue before shutdown
pool.shutdown();
List<Runnable> unfinished = new ArrayList<>();
queue.drainTo(unfinished);
// Persist unfinished tasks for retry

Monitoring Queue Health

public class MonitoredQueue<T> {
    private final BlockingQueue<T> queue;
    private final int capacity;
    private final MeterRegistry registry;
    
    public MonitoredQueue(int capacity, MeterRegistry registry) {
        this.queue = new ArrayBlockingQueue<>(capacity);
        this.capacity = capacity;
        this.registry = registry;
        
        // Monitor queue depth
        registry.gauge("queue.size", queue, BlockingQueue::size);
        registry.gauge("queue.utilization", queue, 
            q -> (double) q.size() / capacity);
    }
    
    public void put(T item) throws InterruptedException {
        long startTime = System.nanoTime();
        queue.put(item);
        long duration = System.nanoTime() - startTime;
        
        registry.timer("queue.put.time").record(duration, TimeUnit.NANOSECONDS);
        
        // Alert if blocking for too long
        if (duration > TimeUnit.SECONDS.toNanos(1)) {
            logger.warn("Producer blocked for {}ms", 
                TimeUnit.NANOSECONDS.toMillis(duration));
        }
    }
}

Part 2 Summary: Core Synchronization Patterns

We’ve covered 4 fundamental synchronization tools:

Tool	Best For	Key Limitation
CyclicBarrier	Fixed multi-phase work	Can’t change party count
Semaphore	Resource limiting	Must remember to release
ThreadFactory	Thread customization	Doesn’t prevent leaks
BlockingQueue	Producer-consumer	Queue can grow unbounded

Key Takeaways:

CyclicBarrier resets after each phase—use for iterative multi-phase work
Semaphore limits resource access—always release in try-finally
ThreadFactory names threads—makes debugging at 2 AM possible
BlockingQueue separates producers from consumers—always use bounded queues

Coming in Part 3 (Day 97):

DelayQueue - Time-delayed execution with exponential backoff
ReentrantLock - Fine-grained locking with timeouts
Phaser - Dynamic multi-phase coordination
Plus: Debugging techniques, monitoring patterns, and production readiness checklist

Previous: Day 95 - Java Concurrency Toolkit Part 1: Foundation & Execution Patterns

Next: Day 97 - Java Concurrency Toolkit Part 3: Advanced Patterns & Production Readiness

Day 95: Java Concurrency Toolkit Part 1 - Foundation & Execution Patterns

2025-11-21T00:00:00Z

Series Navigation: Part 1 (You are here) • Part 2: Core Synchronization • Part 3: Advanced Patterns

“Concurrency is not parallelism. Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once." - Rob Pike

I’ve worked with Executor, ScheduledExecutorService, Future, CompletableFuture, CountDownLatch, ReentrantLock in production, and they’ve helped me develop various multi-threaded features. But I realized I was barely scratching the surface of what java.util.concurrent offers.

Primary References:

Goetz, B., et al. (2006). Java Concurrency in Practice. Addison-Wesley.
Oracle. (2023). Java SE API Specification: java.util.concurrent package
Lea, D. (2000). “A Java Fork/Join Framework”, Science of Computer Programming, 37(1-3).

This is Part 1 of 3 where we’ll explore the foundation and execution patterns: the core building blocks that power modern concurrent Java applications.

Series Overview

This is a 3-part series on Java Concurrency:

Part 1 (Today - Day 95): Foundation & Execution

Executor
ExecutorService
ScheduledExecutorService
Future
CompletableFuture
CountDownLatch

Part 2 (Day 96): Core Synchronization Patterns

CyclicBarrier
Semaphore
ThreadFactory
BlockingQueue

Part 3 (Day 97): Advanced Patterns & Production Readiness

DelayQueue
ReentrantLock
Phaser
Debugging, Monitoring, Production Patterns

Quick Reference: Part 1 Tools at a Glance

Tool	TL;DR	Key Gotcha
Executor	Simplest interface - just `execute(Runnable)`. No lifecycle, no results.	No way to retrieve results or manage lifecycle
ExecutorService	Managed thread pool with lifecycle control. Returns `Future` for results.	Must call `shutdown()` - thread pools leak otherwise
ScheduledExecutorService	Schedules tasks for future or periodic execution.	Exceptions cancel all future executions - wrap in try-catch!
Future	Represents eventual completion. Always use `get(timeout)` - never without.	Blocking API - blocks calling thread until complete
CompletableFuture	Non-blocking async composition (Java’s Promises). Chain, combine, handle errors.	Complex API - use `thenCompose` not `thenApply(join())`
CountDownLatch	One-shot countdown. Wait at `await()` until `countDown()` reaches zero.	Can’t reset. Always countDown in `finally` to avoid deadlock

When NOT to Use Concurrency

Before we dive in, let’s talk about when concurrency is overkill:

Don’t use concurrency when:

Your dataset fits in memory and processes in < 100ms sequentially
The overhead of thread coordination exceeds the benefit
Your task is inherently sequential (step B depends on step A’s result)
You’re processing < 1000 items and each takes microseconds
Debugging complexity isn’t worth the performance gain

Do use concurrency when:

You have independent tasks that can run in parallel
You’re doing I/O (network, disk, database) where threads spend time waiting
You need to keep your application responsive while background work happens
You’re processing large datasets where parallel processing yields measurable gains
You need to handle multiple concurrent requests (web servers, message processors)

Rule of thumb: Measure first. Add concurrency only when sequential processing is proven to be a bottleneck.

The Cost Model: Concurrency introduces coordination overhead. By Amdahl’s Law, speedup is limited by the sequential fraction of your program (Goetz et al., 2006, Ch. 11). If synchronization overhead exceeds the parallelizable benefit, you’ll make things slower. Always profile before parallelizing.

Performance Characteristics Reference

Tool	CPU Overhead	Memory Characteristics	Behavioral Notes	Best For
Executor	Low	Minimal; delegates to provided threads	Submits tasks without lifecycle management	Fire-and-forget tasks
ExecutorService	Low–Medium	Thread-pool backed; scales with pool size and queue bounds	Manages worker threads, queues, and shutdown	Managed task execution
ScheduledExecutorService	Medium	Thread-pool plus heap-based delay queues (priority queue)	Time-based and periodic task execution	Delayed and recurring tasks
Future	Very Low	Single object reference (~40-60 bytes) per task	Represents eventual completion; blocking get()	Simple result retrieval
CompletableFuture	Low–Medium	Base object + callback chain (~200-400 bytes per composition)	Non-blocking composition, async pipelines	Async workflow chains
CountDownLatch	Very Low	~32 bytes via AbstractQueuedSynchronizer	One-shot coordination of thread arrival	Release-on-countdown scenarios

Memory characteristics based on HotSpot JVM defaults. Thread stack size typically 1MB per thread (configurable via -Xss). See Oracle JVM documentation for platform-specific values.

The Foundation: Understanding What We’re Building

Before we dive into the tools, let’s get one thing straight. Concurrency in Java isn’t about making everything parallel. It’s about structuring your code to handle multiple concerns efficiently. Sometimes that means parallel execution. Sometimes it means coordinating sequential tasks across threads. Sometimes it’s about protecting shared state from chaos.

Think of it like a busy restaurant kitchen:

A head chef coordinating tasks (Executor)
Managed cooking stations (ExecutorService)
Timer-based prep work (ScheduledExecutorService)
Order tickets (Future)
Complex recipe flows (CompletableFuture)
Waiting for all dishes before serving (CountDownLatch)

1. Executor: The Fire-and-Forget Pattern

TL;DR: Simplest interface - just execute(Runnable). No lifecycle, no results. Perfect for async side effects like logging or metrics where you don’t need to wait for completion.

The Problem: Your request thread is too precious to waste on side tasks like logging or metrics.

This is one pattern I’ve used extensively. When you’re processing API requests, offloading non-critical work like logging enrichment to background threads can significantly improve response times.

The Solution: Offload non-critical work to background threads.

import java.util.concurrent.Executor;
import java.time.Instant;
import java.util.concurrent.Executors;

public class AsyncLogger {
    private final Executor logExecutor = Executors.newSingleThreadExecutor(r -> {
        Thread t = new Thread(r);
        t.setName("async-logger");
        t.setDaemon(true); // Won't prevent JVM shutdown
        return t;
    });
    
    public void logRequestAsync(String userId, String endpoint, int statusCode) {
        // Request thread returns immediately
        logExecutor.execute(() -> {
            // Background thread does the heavy lifting
            String enrichedLog = enrichLog(userId, endpoint, statusCode);
            writeToElasticsearch(enrichedLog);
        });
    }
    
    private String enrichLog(String userId, String endpoint, int statusCode) {
        // Fetch user details, geo-location, etc.
        return String.format("[%s] User: %s | Endpoint: %s | Status: %d", 
                             Instant.now(), userId, endpoint, statusCode);
    }
    
    private void writeToElasticsearch(String log) {
        System.out.println("Writing to ES: " + log);
    }
}

Key Insight: Executor is the simplest interface—just execute(Runnable). No lifecycle management, no result handling. Perfect for fire-and-forget side effects.

Trade-offs and Limitations

Pros:

Minimal overhead
Simple API
Request thread returns immediately

Cons:

No result retrieval mechanism
No lifecycle management (can’t shut down gracefully)
No built-in error handling
Can’t limit concurrent task count

When it goes wrong:

//  DANGER: Unbounded task submission
Executor executor = Executors.newCachedThreadPool();
for (int i = 0; i < 1_000_000; i++) {
    executor.execute(() -> {
        // If tasks take longer than submission rate,
        // you'll create 1 million threads = OOM!
    });
}

Reference: Oracle Java SE API - Executors.newCachedThreadPool(): “Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available.” - No upper bound documented.

Common Mistakes:

Using daemon threads for critical work (logs might be lost on JVM shutdown) - Reference: Java Language Specification §12.8: The JVM exits when all non-daemon threads terminate.
No backpressure mechanism (can overwhelm the executor)
Losing exceptions (they’re swallowed unless you add explicit handling)

2. ExecutorService: When You Need Control

TL;DR: Managed thread pool with lifecycle control. Returns Future for results. Use invokeAll() for batch processing. Always shutdown: shutdown() → awaitTermination() → shutdownNow(). Size pool based on workload (CPU vs I/O).

The Problem: Processing a large product catalog where each item needs enrichment from multiple services—pricing, inventory, and reviews. Sequential processing is too slow.

This is a classic scenario where parallel processing can provide speedup—if I/O wait time dominates compute time. Concurrency benefit depends on latency distribution and CPU contention (Goetz et al., 2006, Ch. 8). Instead of waiting for each item to complete before starting the next, we can process multiple items concurrently.

The Solution: Parallel processing with controlled thread pool and result collection.

import java.util.concurrent.*;
import java.util.List;
import java.util.ArrayList;
import java.util.stream.Collectors;

public class ProductEnrichmentService {
    private final ExecutorService pool;
    
    public ProductEnrichmentService(int threadCount) {
        this.pool = Executors.newFixedThreadPool(threadCount);
    }
    
    public List<Product> enrichProducts(List<Product> products) throws InterruptedException {
        System.out.println("Enriching " + products.size() + " products using " + 
                         Runtime.getRuntime().availableProcessors() + " threads");
        
        // Convert products to Callable tasks
        List<Callable<Product>> tasks = products.stream()
                .map(product -> (Callable<Product>) () -> enrichSingleProduct(product))
                .collect(Collectors.toList());
        
        long startTime = System.currentTimeMillis();
        
        // Execute all tasks and wait for completion
        List<Future<Product>> futures = pool.invokeAll(tasks);
        
        // Collect results
        List<Product> enriched = new ArrayList<>();
        for (Future<Product> future : futures) {
            try {
                enriched.add(future.get());
            } catch (ExecutionException e) {
                System.err.println("Failed to enrich product: " + e.getCause().getMessage());
            }
        }
        
        long duration = System.currentTimeMillis() - startTime;
        System.out.println("Enrichment completed in " + duration + "ms");
        
        return enriched;
    }
    
    private Product enrichSingleProduct(Product product) {
        // Simulate calling multiple services
        String pricing = fetchPricing(product.id());
        String inventory = fetchInventory(product.id());
        String reviews = fetchReviews(product.id());
        
        return new Product(
            product.id(),
            product.name(),
            pricing,
            inventory,
            reviews
        );
    }
    
    private String fetchPricing(String id) {
        sleep(50); // Simulate API call
        return "$99.99";
    }
    
    private String fetchInventory(String id) {
        sleep(30);
        return "In Stock";
    }
    
    private String fetchReviews(String id) {
        sleep(40);
        return "4.5 stars";
    }
    
    public void shutdown() {
        pool.shutdown();
        try {
            if (!pool.awaitTermination(60, TimeUnit.SECONDS)) {
                pool.shutdownNow();
            }
        } catch (InterruptedException e) {
            pool.shutdownNow();
        }
    }
    
    private void sleep(long ms) {
        try { Thread.sleep(ms); } catch (InterruptedException e) {}
    }
}

record Product(String id, String name, String pricing, String inventory, String reviews) {}

Trade-offs and Limitations

Pros:

Lifecycle management (shutdown, awaitTermination)
Result collection via Future
Controlled parallelism
Can batch submit tasks

Cons:

Fixed thread pool size (need to tune)
Blocking result retrieval
No built-in composition
Manual error handling

Sizing Your Thread Pool:

// For CPU-bound tasks:
int cpuBoundPoolSize = Runtime.getRuntime().availableProcessors();

// For I/O-bound tasks (rule of thumb):
int ioBoundPoolSize = Runtime.getRuntime().availableProcessors() * 2;

// More precise I/O formula (derived from Little's Law):
// ThreadCount = NumCores * (1 + WaitTime/ComputeTime)
// Example: 8 cores, 90% wait time, 10% compute
// = 8 * (1 + 0.9/0.1) = 8 * 10 = 80 threads

Reference: Goetz et al., 2006, Chapter 8 (“Applying Thread Pools”): Thread pool sizing using Little’s Law and utilization analysis.

Common Mistakes:

// MISTAKE 1: Forgetting to shutdown
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    pool.submit(() -> doWork());
    // Pool never shuts down = thread leak!
}

// CORRECT: Always shutdown
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    try {
        pool.submit(() -> doWork()).get();
    } finally {
        pool.shutdown();
        pool.awaitTermination(60, TimeUnit.SECONDS);
    }
}

// MISTAKE 2: Wrong pool type
ExecutorService pool = Executors.newCachedThreadPool();
// For I/O: Can create unlimited threads = OOM

// MISTAKE 3: Ignoring RejectedExecutionException
pool.shutdown();
pool.submit(() -> doWork()); // Throws RejectedExecutionException

Modern Java Note: Executors factory methods are convenient but lack configurability. For production systems, consider direct ThreadPoolExecutor construction with explicit queue bounds and rejection policies. Java 21+ introduces Structured Concurrency (JEP 453) and Scoped Values (JEP 446) for safer concurrent patterns.

Reference: OpenJDK JEP 453: Structured Concurrency (Preview) - https://openjdk.org/jeps/453

3. ScheduledExecutorService: Time-Based Automation

TL;DR: Schedules tasks for future or periodic execution. Use scheduleAtFixedRate() for fixed intervals, scheduleWithFixedDelay() for guaranteed gaps. Wrap tasks in try-catch - exceptions cancel future executions!

The Problem: OAuth tokens expire every hour. If we don’t refresh them, API calls start failing. Can’t rely on manual intervention.

This is another pattern I’ve implemented in production. Scheduled tasks are perfect for periodic maintenance work like token refresh, health checks, or cache cleanup.

The Solution: Automated token refresh with scheduled tasks.

import java.util.concurrent.*;
import java.time.Instant;
import java.util.concurrent.atomic.AtomicReference;

public class TokenRefreshService {
    private final ScheduledExecutorService scheduler;
    private final AtomicReference<String> currentToken;
    
    public TokenRefreshService() {
        this.scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
            Thread t = new Thread(r);
            t.setName("token-refresher");
            t.setDaemon(false); // Important: ensure refresh completes before shutdown
            return t;
        });
        this.currentToken = new AtomicReference<>("");
    }
    
    public void startRefreshCycle() {
        System.out.println("Starting token refresh cycle at " + Instant.now());
        
        // Initial refresh
        refreshToken();
        
        // Schedule periodic refresh every 50 minutes (tokens expire in 60)
        scheduler.scheduleAtFixedRate(
            this::refreshToken,
            50,              // initial delay
            50,              // period
            TimeUnit.MINUTES
        );
        
        System.out.println("Token will refresh every 50 minutes");
    }
    
    private void refreshToken() {
        try {
            System.out.println("[" + Instant.now() + "] Refreshing token...");
            
            // Simulate OAuth flow
            String newToken = callAuthServer();
            currentToken.set(newToken);
            
            System.out.println("Token refreshed successfully");
        } catch (Exception e) {
            System.err.println("Token refresh failed: " + e.getMessage());
            // In production: alert ops team, retry with exponential backoff
        }
    }
    
    private String callAuthServer() {
        // Simulate network delay
        try { Thread.sleep(200); } catch (InterruptedException e) {}
        return "token_" + System.currentTimeMillis();
    }
    
    public String getCurrentToken() {
        return currentToken.get();
    }
    
    public void shutdown() {
        scheduler.shutdown();
    }
}

scheduleAtFixedRate vs scheduleWithFixedDelay

// scheduleAtFixedRate: Next task starts at T + period (can overlap!)
scheduler.scheduleAtFixedRate(task, 0, 1, TimeUnit.SECONDS);
// If task takes 2 seconds, tasks will queue up!

// scheduleWithFixedDelay: Next task starts after (task completion + delay)
scheduler.scheduleWithFixedDelay(task, 0, 1, TimeUnit.SECONDS);
// Guarantees 1 second gap between task completion and next start

Trade-offs and Limitations

Pros:

Built-in timing mechanism
Periodic execution
One-shot delayed execution
Multiple scheduled tasks on same scheduler

Cons:

If task takes longer than period, tasks queue up (scheduleAtFixedRate)
Exceptions cancel future executions - Reference: Oracle Java SE API - ScheduledExecutorService: “If any execution of the task encounters an exception, subsequent executions are suppressed."
No built-in retry logic
Clock drift not handled

Common Mistakes:

// MISTAKE: Long-running task with scheduleAtFixedRate
scheduler.scheduleAtFixedRate(() -> {
    Thread.sleep(5000); // 5 seconds
}, 0, 1, TimeUnit.SECONDS); // Every 1 second
// Tasks pile up! Queue grows indefinitely

// CORRECT: Use scheduleWithFixedDelay for long tasks
scheduler.scheduleWithFixedDelay(() -> {
    Thread.sleep(5000);
}, 0, 1, TimeUnit.SECONDS);
// Next task starts 1 second AFTER previous completes

// MISTAKE: Not handling exceptions
scheduler.scheduleAtFixedRate(() -> {
    if (Math.random() > 0.5) {
        throw new RuntimeException("Boom!");
    }
    doWork();
}, 0, 1, TimeUnit.SECONDS);
// First exception silently cancels ALL future executions!

// CORRECT: Wrap in try-catch
scheduler.scheduleAtFixedRate(() -> {
    try {
        if (Math.random() > 0.5) {
            throw new RuntimeException("Boom!");
        }
        doWork();
    } catch (Exception e) {
        System.err.println("Task failed: " + e.getMessage());
        // Task continues running
    }
}, 0, 1, TimeUnit.SECONDS);

4. Future: Timeouts Save Lives

TL;DR: Represents eventual completion of async task. Always use get(timeout) - never get() without timeout. Can cancel running tasks (if they respect interruption). Blocking API - use CompletableFuture for non-blocking.

The Problem: Calling external services that might hang or respond slowly. Without timeouts, your application threads get stuck waiting indefinitely.

Timeout enforcement is critical for resilient systems. Whether it’s a payment gateway, external API, or database query, you need a way to fail fast and recover gracefully.

The Solution: Strict timeout enforcement with Future.

import java.util.concurrent.*;

public class PaymentGateway {
    private final ExecutorService pool;
    private final long timeoutMs;
    
    public PaymentGateway(long timeoutMs) {
        this.pool = Executors.newFixedThreadPool(10);
        this.timeoutMs = timeoutMs;
    }
    
    public PaymentResult processPayment(PaymentRequest request) {
        System.out.println("Processing payment for $" + request.amount());
        
        Future<PaymentResult> future = pool.submit(() -> {
            return callExternalGateway(request);
        });
        
        try {
            // Enforce strict timeout
            PaymentResult result = future.get(timeoutMs, TimeUnit.MILLISECONDS);
            System.out.println("Payment successful: " + result.transactionId());
            return result;
            
        } catch (TimeoutException e) {
            // Cancel the stuck task
            future.cancel(true);
            
            System.err.println("Payment timed out after " + timeoutMs + "ms");
            return new PaymentResult("TIMEOUT", "Payment gateway timeout");
            
        } catch (ExecutionException e) {
            System.err.println("Payment failed: " + e.getCause().getMessage());
            return new PaymentResult("FAILED", e.getCause().getMessage());
            
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return new PaymentResult("INTERRUPTED", "Payment interrupted");
        }
    }
    
    private PaymentResult callExternalGateway(PaymentRequest request) {
        // Simulate variable latency
        try {
            Thread.sleep(ThreadLocalRandom.current().nextInt(100, 2000));
        } catch (InterruptedException e) {
            throw new RuntimeException("Gateway call interrupted");
        }
        
        return new PaymentResult("TXN_" + System.currentTimeMillis(), "SUCCESS");
    }
    
    public void shutdown() {
        pool.shutdown();
    }
}

record PaymentRequest(String userId, double amount) {}
record PaymentResult(String transactionId, String status) {}

Trade-offs and Limitations

Pros:

Simple timeout enforcement
Can cancel running tasks
Works with any ExecutorService
Exception handling built-in

Cons:

Blocking API (future.get() blocks)
No composition (can’t chain Futures)
Cancellation may not work (task must respect interruption)
One result only, no streaming

Critical Lesson: Always set timeouts on external calls. A slow dependency without timeout protection can create cascading failures throughout your system.

Common Mistakes:

// MISTAKE: future.get() without timeout
Future<String> future = pool.submit(() -> callExternalApi());
String result = future.get(); // Blocks FOREVER if API hangs!

// CORRECT: Always use timeout
Future<String> future = pool.submit(() -> callExternalApi());
String result = future.get(5, TimeUnit.SECONDS);

// MISTAKE: Assuming cancel() stops the task
Future<?> future = pool.submit(() -> {
    while (true) {
        // Ignores interruption!
        doWork();
    }
});
future.cancel(true); // Task keeps running!

// CORRECT: Respect interruption
Future<?> future = pool.submit(() -> {
    while (!Thread.currentThread().isInterrupted()) {
        doWork();
        if (Thread.interrupted()) break; // Check interruption
    }
    System.out.println("Task gracefully stopped");
});
future.cancel(true); // Task stops

Reference: Goetz et al., 2006, Chapter 7 (“Cancellation and Shutdown”): Proper interruption handling patterns.

5. CompletableFuture: Async Pipelines

TL;DR: Non-blocking async composition (Java’s answer to Promises). Chain with thenApply/thenCompose, combine with allOf/anyOf, handle errors with exceptionally/handle. Powerful but complex - practice required. Always specify executor pool.

The Problem: You need to call multiple services in a chain, handle errors at each step, and compose results—all without blocking threads.

CompletableFuture is Java’s way to JavaScript Promises. It’s powerful, composable, and non-blocking when used correctly.

The Solution: Build async pipelines with proper error handling.

import java.util.concurrent.*;
import java.time.Duration;

public class OrderProcessingService {
    private final ExecutorService pool;
    
    public OrderProcessingService() {
        this.pool = Executors.newFixedThreadPool(
            Runtime.getRuntime().availableProcessors() * 2
        );
    }
    
    // Example 1: Sequential async chain
    public CompletableFuture<OrderConfirmation> processOrder(String orderId) {
        return CompletableFuture
            // Step 1: Validate order
            .supplyAsync(() -> validateOrder(orderId), pool)
            
            // Step 2: Check inventory (depends on validation)
            .thenCompose(order -> 
                CompletableFuture.supplyAsync(() -> checkInventory(order), pool)
            )
            
            // Step 3: Process payment (depends on inventory)
            .thenCompose(order ->
                CompletableFuture.supplyAsync(() -> processPayment(order), pool)
            )
            
            // Step 4: Ship order (depends on payment)
            .thenApply(order -> shipOrder(order))
            
            // Handle any errors in the chain
            .exceptionally(ex -> {
                System.err.println("Order processing failed: " + ex.getMessage());
                return new OrderConfirmation("FAILED", ex.getMessage());
            })
            
            // Add timeout
            .orTimeout(10, TimeUnit.SECONDS)
            
            // Fallback if timeout
            .exceptionally(ex -> {
                if (ex instanceof TimeoutException) {
                    return new OrderConfirmation("TIMEOUT", "Processing timed out");
                }
                return new OrderConfirmation("ERROR", ex.getMessage());
            });
    }
    
    // Example 2: Parallel async calls
    public CompletableFuture<ProductDetails> getProductDetails(String productId) {
        // Make three independent API calls in parallel
        CompletableFuture<String> pricingFuture = 
            CompletableFuture.supplyAsync(() -> fetchPricing(productId), pool);
        
        CompletableFuture<String> inventoryFuture = 
            CompletableFuture.supplyAsync(() -> fetchInventory(productId), pool);
        
        CompletableFuture<String> reviewsFuture = 
            CompletableFuture.supplyAsync(() -> fetchReviews(productId), pool);
        
        // Combine all results
        return CompletableFuture.allOf(pricingFuture, inventoryFuture, reviewsFuture)
            .thenApply(v -> new ProductDetails(
                productId,
                pricingFuture.join(),    // Safe: already completed
                inventoryFuture.join(),
                reviewsFuture.join()
            ));
    }
    
    // Example 3: Race multiple services (use fastest)
    public CompletableFuture<String> getQuote(String symbol) {
        CompletableFuture<String> exchange1 = 
            CompletableFuture.supplyAsync(() -> callExchange1(symbol), pool);
        
        CompletableFuture<String> exchange2 = 
            CompletableFuture.supplyAsync(() -> callExchange2(symbol), pool);
        
        CompletableFuture<String> exchange3 = 
            CompletableFuture.supplyAsync(() -> callExchange3(symbol), pool);
        
        // Return whichever completes first
        return CompletableFuture.anyOf(exchange1, exchange2, exchange3)
            .thenApply(result -> (String) result);
    }
    
    // Example 4: Complex error handling
    public CompletableFuture<String> robustServiceCall(String request) {
        return CompletableFuture
            .supplyAsync(() -> callUnreliableService(request), pool)
            
            // Handle specific exceptions differently
            .handle((result, ex) -> {
                if (ex != null) {
                    if (ex.getCause() instanceof TimeoutException) {
                        return "TIMEOUT_FALLBACK";
                    } else if (ex.getCause() instanceof ConnectException) {
                        return "OFFLINE_FALLBACK";
                    } else {
                        throw new CompletionException(ex);
                    }
                }
                return result;
            })
            
            // Retry logic with delay
            .exceptionallyCompose(ex -> {
                System.out.println("Retrying after failure...");
                return CompletableFuture
                    .delayedExecutor(1, TimeUnit.SECONDS, pool)
                    .execute(() -> {})
                    .thenCompose(v -> 
                        CompletableFuture.supplyAsync(
                            () -> callUnreliableService(request), 
                            pool
                        )
                    );
            });
    }
    
    // Helper methods (simulated)
    private Order validateOrder(String orderId) {
        sleep(100);
        return new Order(orderId, "VALIDATED");
    }
    
    private Order checkInventory(Order order) {
        sleep(150);
        return new Order(order.id(), "INVENTORY_OK");
    }
    
    private Order processPayment(Order order) {
        sleep(200);
        return new Order(order.id(), "PAID");
    }
    
    private OrderConfirmation shipOrder(Order order) {
        sleep(100);
        return new OrderConfirmation("SUCCESS", "Order shipped");
    }
    
    private String fetchPricing(String id) {
        sleep(50);
        return "$99.99";
    }
    
    private String fetchInventory(String id) {
        sleep(75);
        return "In Stock";
    }
    
    private String fetchReviews(String id) {
        sleep(60);
        return "4.5 stars";
    }
    
    private String callExchange1(String symbol) {
        sleep(100);
        return "Exchange1: $150.25";
    }
    
    private String callExchange2(String symbol) {
        sleep(80);
        return "Exchange2: $150.30";
    }
    
    private String callExchange3(String symbol) {
        sleep(120);
        return "Exchange3: $150.20";
    }
    
    private String callUnreliableService(String request) {
        sleep(100);
        if (Math.random() > 0.7) {
            throw new RuntimeException("Service temporarily unavailable");
        }
        return "SUCCESS: " + request;
    }
    
    private void sleep(long ms) {
        try { Thread.sleep(ms); } catch (InterruptedException e) {}
    }
    
    public void shutdown() {
        pool.shutdown();
    }
}

record Order(String id, String status) {}
record OrderConfirmation(String status, String message) {}
record ProductDetails(String id, String pricing, String inventory, String reviews) {}

CompletableFuture Key Methods:

Method	Use Case	Returns
`supplyAsync()`	Start async computation with result	CompletableFuture
`runAsync()`	Start async computation without result	CompletableFuture
`thenApply()`	Transform result (sync)	CompletableFuture
`thenApplyAsync()`	Transform result (async)	CompletableFuture
`thenCompose()`	Chain dependent futures (flatMap)	CompletableFuture
`thenCombine()`	Combine two independent futures	CompletableFuture
`allOf()`	Wait for all to complete	CompletableFuture
`anyOf()`	Wait for first to complete	CompletableFuture
`exceptionally()`	Handle error, return fallback	CompletableFuture
`handle()`	Handle both success and error	CompletableFuture
`orTimeout()`	Add timeout	CompletableFuture
`completeOnTimeout()`	Provide default on timeout	CompletableFuture

Trade-offs and Limitations

Pros:

Non-blocking composition
Rich API for chaining
Built-in error handling
Timeout support (Java 9+)
Can combine multiple futures

Cons:

Complex API with many methods
Easy to create memory leaks (uncompleted futures)
Exception handling can be tricky
Default pool (ForkJoinPool.commonPool()) might not be suitable

Common Mistakes:

//  MISTAKE 1: Using join() instead of thenCompose()
CompletableFuture<User> userFuture = getUserAsync(userId);
CompletableFuture<Orders> ordersFuture = 
    getOrdersAsync(userFuture.join().getId()); // BLOCKS!

// CORRECT: Chain with thenCompose
CompletableFuture<Orders> ordersFuture = getUserAsync(userId)
    .thenCompose(user -> getOrdersAsync(user.getId())); // Non-blocking

// MISTAKE 2: Not handling errors
CompletableFuture<String> future = CompletableFuture
    .supplyAsync(() -> {
        throw new RuntimeException("Boom!");
    });
// Exception is swallowed until you call get() or join()

// CORRECT: Handle errors
CompletableFuture<String> future = CompletableFuture
    .supplyAsync(() -> {
        throw new RuntimeException("Boom!");
    })
    .exceptionally(ex -> {
        System.err.println("Error: " + ex.getMessage());
        return "FALLBACK";
    });


// MISTAKE 4: Blocking in async callbacks
CompletableFuture.supplyAsync(() -> step1())
    .thenApply(result -> {
        return expensiveBlockingCall(); // Blocks thread pool!
    });

// CORRECT: Use thenApplyAsync for blocking ops
CompletableFuture.supplyAsync(() -> step1())
    .thenApplyAsync(result -> {
        return expensiveBlockingCall(); // Runs on separate thread
    }, customPool);

6. CountDownLatch: Startup Coordination

TL;DR: One-shot countdown mechanism. Threads wait at await() until count reaches zero via countDown() calls. Can’t reset (use CyclicBarrier for reusable). Always countDown in finally block to avoid deadlock.

The Problem: Starting a microservice that depends on multiple other services being healthy. If you start serving traffic before dependencies are ready, requests fail.

This pattern is essential for graceful application startup, especially in microservice architectures where you need to coordinate multiple async initialization tasks.

The Solution: Wait for all health checks before accepting traffic.

import java.util.concurrent.*;
import java.util.List;

public class MicroserviceBootstrap {
    
    public void startApplication() throws InterruptedException {
        System.out.println("Starting application bootstrap...");
        
        List<String> dependencies = List.of(
            "user-service", 
            "payment-service", 
            "inventory-service"
        );
        
        CountDownLatch healthCheckLatch = new CountDownLatch(dependencies.size());
        
        ExecutorService pool = Executors.newCachedThreadPool();
        
        // Launch parallel health checks
        for (String service : dependencies) {
            pool.submit(() -> {
                boolean healthy = checkServiceHealth(service);
                if (healthy) {
                    System.out.println(service + " is healthy");
                    healthCheckLatch.countDown();
                } else {
                    System.err.println(service + " health check failed");
                    // In production: implement retry logic
                }
            });
        }
        
        System.out.println("Waiting for all health checks to complete...");
        
        // Block until all services are healthy or timeout
        boolean allHealthy = healthCheckLatch.await(30, TimeUnit.SECONDS);
        
        if (allHealthy) {
            System.out.println("All dependencies healthy. Starting HTTP server...");
            startHttpServer();
        } else {
            System.err.println("Health checks timed out. Application startup failed.");
            System.exit(1);
        }
        
        pool.shutdown();
    }
    
    private boolean checkServiceHealth(String service) {
        try {
            // Simulate HTTP health check
            Thread.sleep(ThreadLocalRandom.current().nextInt(500, 2000));
            return true; // Assume success for demo
        } catch (InterruptedException e) {
            return false;
        }
    }
    
    private void startHttpServer() {
        System.out.println("HTTP server started on port 8080");
    }
}

Visualizing CountDownLatch

Trade-offs and Limitations

Pros:

Simple API (just countDown and await)
Very low overhead (~32 bytes)
Can have multiple waiters
Can timeout

Cons:

One-shot only (can’t reset)
Count must be known at creation
No error propagation
If countDown() is missed, waiters block forever

Why CountDownLatch? It’s a one-shot synchronization primitive. Once the count reaches zero, it’s done. Perfect for startup coordination where you only need to wait once.

Common Mistakes:

// MISTAKE: Wrong count
CountDownLatch latch = new CountDownLatch(5);
for (int i = 0; i < 3; i++) { // Only 3 threads!
    pool.submit(() -> {
        doWork();
        latch.countDown();
    });
}
latch.await(); // Blocks forever! Count never reaches 0

// CORRECT: Count matches threads
int threadCount = 3;
CountDownLatch latch = new CountDownLatch(threadCount);
for (int i = 0; i < threadCount; i++) {
    pool.submit(() -> {
        doWork();
        latch.countDown();
    });
}

// MISTAKE: Forgetting countDown on error
pool.submit(() -> {
    if (checkHealth()) {
        latch.countDown();
    }
    // If check fails, count is never decremented!
});

// CORRECT: Always countDown (use finally)
pool.submit(() -> {
    try {
        checkHealth();
    } finally {
        latch.countDown(); // Always happens
    }
});

Common Anti-Patterns Across All Tools

1. Thread Pool Sizing

// ANTI-PATTERN: Magic numbers
ExecutorService pool = Executors.newFixedThreadPool(42);

// CORRECT: Calculate based on workload
int poolSize = Runtime.getRuntime().availableProcessors() * 
               (isCpuBound ? 1 : 2);

2. Ignoring Shutdown

// ANTI-PATTERN: No shutdown
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    pool.submit(() -> work());
} // Pool leaks!

// CORRECT: Proper shutdown
public void process() {
    ExecutorService pool = Executors.newFixedThreadPool(10);
    try {
        pool.submit(() -> work()).get();
    } finally {
        pool.shutdown();
        pool.awaitTermination(60, TimeUnit.SECONDS);
    }
}

3. Daemon Threads for Critical Work

// ❌ ANTI-PATTERN: Daemon thread for DB writes
ExecutorService pool = Executors.newSingleThreadExecutor(r -> {
    Thread t = new Thread(r);
    t.setDaemon(true); // JVM can exit before DB write completes!
    return t;
});

// ✅ CORRECT: Non-daemon for critical work
ExecutorService pool = Executors.newSingleThreadExecutor(r -> {
    Thread t = new Thread(r);
    t.setDaemon(false); // JVM waits for completion
    return t;
});

Debugging Concurrent Code

Essential Tools:

1. Thread Dumps with jstack

# Get process ID
jps

# Generate thread dump
jstack <pid> > threaddump.txt

# Look for:
# - "BLOCKED" threads waiting on locks
# - "WAITING" threads in park()
# - Thread pool names (why naming matters!)

Reference: Oracle JDK Tools - jstack: “Prints Java thread stack traces for a Java process."

2. ThreadPoolExecutor Hooks

public class MonitoredThreadPool extends ThreadPoolExecutor {
    private final ThreadLocal<Long> startTime = new ThreadLocal<>();
    
    public MonitoredThreadPool(int corePoolSize, int maxPoolSize) {
        super(corePoolSize, maxPoolSize, 60L, TimeUnit.SECONDS, 
              new LinkedBlockingQueue<>());
    }
    
    @Override
    protected void beforeExecute(Thread t, Runnable r) {
        super.beforeExecute(t, r);
        startTime.set(System.nanoTime());
        System.out.println("Task starting on thread: " + t.getName());
    }
    
    @Override
    protected void afterExecute(Runnable r, Throwable t) {
        try {
            long elapsed = System.nanoTime() - startTime.get();
            System.out.println("Task completed in " + elapsed / 1_000_000 + "ms");
            
            if (t != null) {
                System.err.println("Task failed: " + t.getMessage());
            }
        } finally {
            super.afterExecute(r, t);
        }
    }
    
    @Override
    protected void terminated() {
        System.out.println("ThreadPool terminated. Completed tasks: " + 
                         getCompletedTaskCount());
    }
}

Reference: Oracle Java SE API - ThreadPoolExecutor: Hook methods beforeExecute, afterExecute, and terminated for monitoring and debugging.

3. Detecting Thread Pool Saturation

ThreadPoolExecutor pool = (ThreadPoolExecutor) Executors.newFixedThreadPool(10);

// Monitor pool health
int activeCount = pool.getActiveCount();
int queueSize = pool.getQueue().size();
long completedTasks = pool.getCompletedTaskCount();

if (queueSize > 1000) {
    System.err.println("WARNING: Thread pool queue saturated!");
    // Alert ops team, scale horizontally, or apply backpressure
}

Reference: Goetz et al., 2006, Chapter 8 (“Applying Thread Pools”): Monitoring thread pool saturation and tuning.

4. Common Deadlock Patterns

// Thread 1: locks A, waits for B
synchronized(lockA) {
    synchronized(lockB) { /* ... */ }
}

// Thread 2: locks B, waits for A → DEADLOCK!
synchronized(lockB) {
    synchronized(lockA) { /* ... */ }
}

Detection: jstack will report “Found one Java-level deadlock” and show the lock dependency cycle.

Prevention: Always acquire locks in consistent order (Goetz et al., 2006, Ch. 10).

Part 1 Summary: Foundation & Execution

We’ve covered the foundation of Java concurrency:

Tool	Best For	Key Limitation
Executor	Fire-and-forget	No result retrieval
ExecutorService	Managed thread pools	Blocking result collection
ScheduledExecutorService	Periodic tasks	Tasks can queue up
Future	Timeout enforcement	Blocking API
CompletableFuture	Async pipelines	Complex API
CountDownLatch	One-shot coordination	Can’t reset

Key Takeaways:

Always set timeouts - Blocking forever = production incidents
Name your threads - Debugging with “pool-1-thread-17” is painful
Proper shutdown is critical - shutdown() → awaitTermination() → shutdownNow()
Match pool size to workload - CPU-bound vs I/O-bound need different sizing
CompletableFuture is powerful - But requires practice to use correctly

Coming in Part 2 (Day 96):

CyclicBarrier - Reusable multi-phase coordination
Semaphore - Resource pool management
ThreadFactory - Production-ready thread management
BlockingQueue - Producer-consumer patterns

Coming in Part 3 (Day 97):

DelayQueue - Time-delayed execution
ReentrantLock - Fine-grained locking
Phaser - Dynamic party registration
Plus: Debugging techniques, monitoring patterns, and production readiness checklist

Next: Day 96 - Java Concurrency Toolkit Part 2: Core Synchronization Patterns

Day 94: Nobody Told Me Java Application Could Start This Fast and The Rabbit hole I explored

2025-10-30T00:00:00Z

A few days ago I attended a company knowledge sharing where one of my brilliant colleauges talked about optimizing java memory and performance tuning. Where he talked about spring boot application start up time and how we can shave off some time to load the application faster.

That night after thinking about it, I fell down the rabbit hole. And what I found gave me lots of ideas. Turns out, I’d been thinking about startup time all wrong.

My Journey Structure

I started with a Jersey application startup problem, but quickly realized optimization techniques fall into three categories:

JVM-level (Chapters 1, 4, 5) - Apply to ANY Java app
Spring Boot-specific (Chapters 2, 3) - Research for future projects
Framework-agnostic architecture (Chapters 6, 7) - Adaptable to Jersey

I’ve marked each technique with its applicability.

The Uncomfortable Truth About Startup Time

Here’s something nobody tells you when you’re learning Java: every second of startup time isn’t created equal.

I used to think “JVM starts slow, deal with it.” But that’s like saying “traffic exists, deal with it” without asking why there’s traffic or where the bottleneck actually is.

After digging deep (and I mean JVM logs, profilers, lots of blogs and articles), I discovered a typical breakdown that many Java developers observe:

Major part of time goes to classloading - The JVM reading and parsing your .class files
For spring another major time spend in bean creation - Spring (or your framework) wiring everything together
Another big chunk of time goes into reflection and proxies - All that runtime magic has a cost
Some of the time goes into I/O - Reading configs, connecting to databases

Note: These are approximate distributions based on analysis from Spring Boot team’s startup optimization research, Oracle’s JVM performance documentation, and profiling multiple applications. Your mileage will vary depending on framework, dependencies, and architecture choices.

I was dealing with very slow startup time of the Jersey application though, my application loads and verifies a lot of stuff before starting still I think there could be improvements.Once I knew where the time was actually going, I could fight back.

Pro Tip: Before optimizing anything, jump to The Measurement Mindset to learn how to profile your specific bottlenecks. I’m presenting techniques in the order I discovered them, but you should measure first.

Chapter 1: The JVM Strikes Back (Or: How I Learned to Stop Worrying and Love AppCDS)

Let’s talk about Class Data Sharing. Sounds boring, right? It’s not. It’s basically a time machine.

Here’s the deal: Every time you start your Java app, the JVM loads core classes—String, ArrayList, all those JDK fundamentals. And every time, it does the same work. Parse the class file, verify the bytecode, prepare the internal structures.

What if… we could skip that?

The AppCDS Discovery

AppCDS (Application Class Data Sharing) lets you create a snapshot of loaded classes and reuse it. Think of it like meal prepping for your JVM.

Here’s what I did:

# Step 1: Generate a list of classes your app loads
java -XX:DumpLoadedClassList=classes.lst \
     -jar my-app.jar

# Step 2: Create the shared archive
java -Xshare:dump \
     -XX:SharedClassListFile=classes.lst \
     -XX:SharedArchiveFile=app-cds.jsa \
     -jar my-app.jar

# Step 3: Run with the shared archive
java -XX:SharedArchiveFile=app-cds.jsa \
     -Xshare:on \
     -jar my-app.jar

No code changes. No architecture overhaul. Just telling the JVM to be smarter about something it was already doing.

APPLIES TO: Any Java 10+ application (not Spring-specific)

Chapter 2: Spring Boot’s Little Secrets

I love Spring Boot. I really do. But it’s like that friend who insists on checking if you locked the door, turned off the stove, and closed the windows—even when you’re just running to the mailbox.

NOTE: While I was exploring Jersey optimization, I researched these Spring Boot techniques. If you’re using Spring Boot, these will apply directly. For Jersey/other frameworks, focus on the JVM-level optimizations in Chapters 1, 4, and 5.

Auto-Configuration: The Double-Edged Sword

Spring Boot’s auto-configuration is brilliant for getting started fast. But in production? It’s scanning and conditionally configuring things one might never use.

One can have lots of auto-configurations enabled, and actually need maybe very few of them.

Here’s the before:

@SpringBootApplication
public class MyApp {
    public static void main(String[] args) {
        SpringApplication.run(MyApp.class, args);
    }
}

Simple, right? Too simple. It was doing SO much behind the scenes.

Here’s after I got specific:

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class,
    JmxAutoConfiguration.class,
    RabbitAutoConfiguration.class,
    MongoAutoConfiguration.class,
    // ... and many others I wasn't using
})
public class MyApp {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(MyApp.class);
        app.setBannerMode(Banner.Mode.OFF); // Sorry, Spring banner
        app.setRegisterShutdownHook(false);
        app.setLogStartupInfo(false);
        app.run(args);
    }
}

this will trim down some startup time when a spring boot application is starting up.

The Lazy Revolution

Then I discovered lazy initialization. This was… controversial.

spring.main.lazy-initialization=true

One line. Just one line, but it can have great effect.

What this does is beautiful and slightly dangerous: instead of creating all your beans at startup, Spring creates them when they’re first needed.

But here’s the catch—and this is important—lazy initialization means errors that would’ve shown up at startup now appear later, potentially in production. So I paired it with comprehensive integration tests. You can’t just YOLO lazy initialization without safety nets.

The Context Indexer Nobody Talks About

There’s this little-known Spring dependency that creates a compile-time index of your components:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-indexer</artifactId>
    <optional>true</optional>
</dependency>

At compile time, it generates META-INF/spring.components. This means Spring doesn’t have to scan your entire classpath looking for @Component and @Service annotations—it already knows where they are.

Chapter 3: The Nuclear Option (GraalVM Native Image)

At this point, I had to ask myself: how fast could this thing really go?

Enter GraalVM Native Image. This is the quantum leap, the paradigm shift, the “wait, is this still Java?” moment.

ADVANCED TECHNIQUE: This requires significant build changes and may not work with all libraries. Evaluate carefully.

What Actually Happens

Normal Java: JVM starts → loads classes → JIT compiles hot paths → your app runs.

Native Image: Ahead-of-time compilation → standalone binary → boom, you’re running.

No JVM startup. No classloading. No JIT warmup. Just your app, as a native binary, starting in milliseconds.

Here’s what I added to my pom.xml:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.9.28</version>
</plugin>

And Spring Boot config:

spring.aot.enabled=true

The build process became… intense. It would take very long time to build.

The Tradeoffs (Because Nothing Is Free)

Native image isn’t magic. It’s hardcore static analysis and ahead-of-time compilation. Here’s what I learned the hard way:

Reflection needs hints - If you use reflection, you need to tell GraalVM about it
Build time increases - Significantly
Memory at startup is fixed - No dynamic heap sizing
Some libraries don’t work - Anything doing crazy bytecode manipulation might break

For some use cases its Worth it. For a complex enterprise app with tons of reflection? Maybe not.

Chapter 4: The Forgotten Optimizations

While we’re here, let me share some gems that don’t get enough love:

The Serial GC Trick

For short-lived apps (CLI tools, serverless functions), use the Serial GC:

`1`	`-XX:+UseSerialGC`

G1GC is great for long-running apps, but its initialization overhead is wasted on something that runs for 30 seconds. Serial GC starts faster. Way faster.

The Heap Size Paradox

I used to think bigger heap = better performance. For startup, it’s backwards.

Large heaps take longer to initialize. The JVM has to zero out that memory.

# Before (my "bigger is better" phase)
-Xms2g -Xmx4g

# After (the "only what I need" enlightenment)  
-Xms64m -Xmx512m

For a microservice that uses maybe 200MB at peak? This was a no-brainer.

The Tiered Compilation Secret

Java’s JIT has multiple tiers of optimization. For startup-critical apps, you can stop at tier 1:

`1`	`-XX:TieredStopAtLevel=1`

This means: compile with the simple JIT, skip the expensive optimizations. Your steady-state performance will be lower, but startup? Lightning fast.

Chapter 5: Build and Packaging—The Overlooked Goldmine

Here’s something that I found really intriguing when I started researching about startup time reduction: how you package your app matters as much as what’s in it.

The Fat JAR Double Tax

Ever wonder why Spring Boot JARs are called “fat JARs”? They’re JARs… containing JARs. And that means your app gets hit with a double classloader overhead.

When you run:

`1`	`java -jar my-app.jar`

The spring-boot-loader has to:

Unpack nested JARs (or read them from the archive)
Create a custom classloader
Then load your actual classes

It’s like having to open a box, to open another box, to get to your actual present.

The Exploded JAR Revelation

Try this instead:

# Extract your fat JAR
unzip my-app.jar -d app/

# Run directly from the classpath
java -cp "app/BOOT-INF/classes:app/BOOT-INF/lib/*" com.example.Main

No nested JARs. No custom classloader. Just straightforward classpath execution.

JLink: Your Custom JRE Builder

This one’s for the hardcore optimizers. Why ship the entire JDK when you only use a fraction of it?

JLink creates a custom Java runtime with only the modules you need:

# First, see what modules you actually use
jdeps --print-module-deps my-app.jar

# Then build a custom runtime (example output)
jlink --module-path $JAVA_HOME/jmods \
      --add-modules java.base,java.logging,java.sql,java.xml \
      --output custom-jre \
      --compress=2 \
      --no-header-files \
      --no-man-pages

Less to load = faster startup. Plus, your Docker images shrink dramatically.

Dependency Pruning: The Spring Cleaning You’ve Been Avoiding

I ran this command and I was like why do we use so many dependencies:

`1`	`mvn dependency:tree \| grep -c "jar"`

found 206 dependencies.

Did I need all of them? thats the question I asked Then I started to look which kind of dependencies one can remove?.

dependencies you can think to remove:

Remove test-scope dependencies leaking into runtime
Excluded transitive dependencies thats not being used
Replace heavy libraries with lighter alternatives if possible

Example from my sample projects pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <!-- Don't need embedded Tomcat for this service -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
        <!-- Using Log4j2, don't need Logback -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Each JAR on the classpath is I/O overhead. Less JARs = less scanning = faster startup.

Chapter 6: Architecture Choices That Compound

This is where we get strategic. Code-level tweaks are great, but architectural decisions? They multiply your wins.

On-Demand Initialization: The “I’ll Get to It Later” Pattern

Not everything needs to be ready at startup. Database connection pools? Sure. Your recommendation engine’s ML model? Maybe not.

Here’s what I changed:

// Before: Everything initialized eagerly
@Bean
public CacheManager cacheManager() {
    CacheManager manager = new CaffeineCacheManager();
    manager.loadAllCaches(); // This takes 2 seconds!
    return manager;
}

// After: Initialize in the background
@Bean
public CacheManager cacheManager() {
    CacheManager manager = new CaffeineCacheManager();
    
    // Load caches asynchronously after startup
    CompletableFuture.runAsync(() -> {
        manager.loadAllCaches();
        log.info("Cache warming complete");
    });
    
    return manager;
}

My app now starts, then warms up the cache.

Parallel Initialization: Multithreading for Startup

Why initialize heavy components one-by-one when you have multiple cores?

@Configuration
public class ParallelInitConfig {
    
    @Bean
    public ApplicationRunner parallelInitializer(
            DataSource ds,
            CacheManager cache,
            MessagingClient messaging) {
        
        return args -> {
            CompletableFuture<Void> dbWarmup = CompletableFuture.runAsync(() -> {
                // Warmup database connections
                ds.getConnection().close();
            });
            
            CompletableFuture<Void> cacheWarmup = CompletableFuture.runAsync(() -> {
                cache.loadCriticalData();
            });
            
            CompletableFuture<Void> messagingConnect = CompletableFuture.runAsync(() -> {
                messaging.connect();
            });
            
            // Wait for all to complete
            CompletableFuture.allOf(dbWarmup, cacheWarmup, messagingConnect)
                .exceptionally(ex -> {
                logger.error("Startup task failed", ex);
                return null;
            })
            .join();
        };
    }
}

Three slow tasks that took 4 seconds sequentially? Now they take 1.5 seconds in parallel.

The Static Initializer Trap

I found this technique when I was researching:

public class ConfigLoader {
    private static final Map<String, String> CONFIG = loadConfig();
    
    private static Map<String, String> loadConfig() {
        // Reads a 50MB XML file
        // Takes 800ms
        return parseXml("huge-config.xml");
    }
}

Every time the JVM loads this class (even if we never use the config), we pay the 800ms tax.

Fixed version:

public class ConfigLoader {
    private static volatile Map<String, String> CONFIG;
    
    public static Map<String, String> getConfig() {
        if (CONFIG == null) {
            synchronized (ConfigLoader.class) {
                if (CONFIG == null) {
                    CONFIG = parseXml("huge-config.xml");
                }
            }
        }
        return CONFIG;
    }
}

Now it only loads when actually needed. If this service doesn’t use the config? We never pay the cost.

Chapter 7: Code-Level Tricks That Add Up

The small stuff matters. A lot of small optimizations compound into big wins.

The Reflection Tax

Reflection is slow. Classpath scanning for annotations is slower. You know what’s fast? Compile-time code generation.

I replaced this:

@Service
public class DataMapper {
    public UserDTO toDTO(User user) {
        // Uses reflection to map fields
        return modelMapper.map(user, UserDTO.class);
    }
}

With MapStruct:

@Mapper(componentModel = "spring")
public interface DataMapper {
    // Generated at compile time—zero reflection
    UserDTO toDTO(User user);
}

No runtime reflection. No classpath scanning. Just plain old method calls.

Logging: The Silent Startup Killer

Log4j2, Logback—they’re great. But their initialization? Not so much.

I switched from this config:

<!-- log4j2.xml with complex appenders and filters -->
<Configuration>
    <Appenders>
        <RollingFile name="file">
            <!-- Lots of configuration -->
        </RollingFile>
    </Appenders>
</Configuration>

To programmatic configuration:

@Configuration
public class LogConfig {
    @PostConstruct
    public void configureLogs() {
        // Configure only what we need, when we need it
        LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
        Configuration config = ctx.getConfiguration();
        // Minimal setup
    }
}

Or for services that don’t need fancy logging, I went nuclear:

# Just use simple logging
org.springframework.boot.autoconfigure.logging=false

Precompiling Configuration

Every Spring Boot startup, we were parsing this:

# application.yml - 500 lines of YAML
spring:
  datasource:
    # ... 100 lines
  jpa:
    # ... 150 lines
  # ... etc

YAML parsing isn’t free. So I created a build-time step:

// At build time, serialize config to binary
@Component
public class ConfigCache {
    static {
        if (Files.exists("config.cache")) {
            // Load pre-parsed config
        } else {
            // Parse YAML and cache it
        }
    }
}

Chapter 8: Docker and Deployment Magic

If you’re running in containers (and who isn’t these days?), you can look into these.

Layered Docker Images: The Smart Way

Instead of this:

1
2
3

FROM openjdk:17
COPY target/my-app.jar /app.jar
CMD ["java", "-jar", "/app.jar"]

Use Spring Boot’s layered JARs:

FROM openjdk:17 as builder
WORKDIR /app
COPY target/*.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract

FROM openjdk:17
WORKDIR /app
COPY --from=builder app/dependencies/ ./
COPY --from=builder app/spring-boot-loader/ ./
COPY --from=builder app/snapshot-dependencies/ ./
COPY --from=builder app/application/ ./

ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]

Why? Docker caches layers. Your app code changes frequently. Your dependencies? Not so much.

With layered images:

Dependency layer: cached
Your code: rebuilds quickly
Faster builds = faster deployments = less waiting

The Measurement Mindset: You Can’t Optimize What You Don’t Measure

Here’s something that changed my whole approach: actually measuring what’s slow.

# See what classes are loading
java -Xlog:class+load=info -jar app.jar

# Enable Spring startup logging
-Dspring.main.log-startup-info=true

# Java Flight Recorder for deep profiling
java -XX:StartFlightRecording=filename=startup.jfr -jar app.jar

Before I did this, I was optimizing blind. “I think Spring is slow, so let me tweak Spring things.”

After? “Oh, 1.2 seconds is spent loading Jackson modules I don’t even use. Let me exclude those.”

Precision beats guessing every time.

The Lessons That Stuck

After this whole journey, here’s what I learned:

Startup time is composable - Every technique stacks. AppCDS + lazy beans + smaller heap = dramatic results
The JVM is smarter than you think - But only if you tell it what to optimize
Framework defaults optimize for flexibility, not speed - You need to get specific
Native Image is real - Not a gimmick. Production-ready for the right use cases
Measurement changes everything - Blind optimization is just guessing with extra steps

The One Thing You Should Do Right Now

If you take nothing else from this post, do this:

1
2
3


# And this to your JVM args
-XX:SharedArchiveFile=app-cds.jsa -Xshare:on

Then, if you want more, come back and try the other techniques. But start there.

The End? Or Just the Beginning?

Why does classloading take so long? What if we cached it?
Why are we creating 300 beans at startup? What if we waited?
Why are we running on the JVM at all? What if we compiled ahead-of-time?

Every “what if” openes a new door.

Your Java app doesn’t have to start slow. The tools are there. The techniques work. You just need to start your exloration.

Day 93: Stop Leaking Passwords - Building Java's Answer to PHP's #[SensitiveParameter]

2025-10-07T00:00:00Z

The Tweet That Started It All

So I’m scrolling through X (still calling it Twitter in my head, sorry Elon), and I see this post about PHP 8.2’s #[SensitiveParameter] attribute. My first thought? “That’s brilliant.”

My second thought? “Wait, Java doesn’t have this?”

I mean, we’ve got annotations for everything. @Override, @Deprecated, @SuppressWarnings… but nothing to stop us from accidentally logging passwords? Really?

Here’s the thing. We’ve all done it. Maybe not you specifically, but someone on your team has definitely written something like:

`1`	`logger.debug("User login: " + username + " with password: " + password)`

And then it sat there. In production. Logging every password attempt to a file that 15 people have access to.

Or worse, a stack trace helpfully includes method parameters, and suddenly your API keys are in your error monitoring system. Fun times explaining that one to the security team.

What PHP Got Right (And Why I’m Jealous)

Look, I’m not usually one to praise PHP. But credit where it’s due.

PHP 8.2 introduced #[SensitiveParameter], and it’s dead simple:

Just use that attribute on a parameter, and boom. If an exception gets thrown, the parameter shows up as Object(SensitiveParameterValue) instead of the actual password. No configuration. No third-party library. Just works.

I sat there staring at this thinking, “Why doesn’t Java have this?”

We’re the enterprise language. We’re supposed to be all about security and best practices. Yet PHP beat us to this one.

But here’s the thing about Java developers (and I say this with love): we don’t just copy. We overengineer. I mean… we engineer solutions that work with our ecosystem. Yeah, let’s go with that.

Building Our Own @Sensitive (Because Java Doesn’t Have One)

Alright, let’s build this thing.

I’m targeting Java 17+ because honestly, if you’re still on Java 8, you’ve got bigger problems than password leaking. (Kidding. Sort of. Please update your Java version.)

My plan is to attack this from three angles:

Logging - intercept and mask before it hits the logs
Stack Traces - catch exceptions and sanitize them
String Representation - because someone always calls toString() on the user object

Could I do it with just one approach? Maybe. But I’ve been burned too many times by “that one edge case” that ruins everything. Defense in depth, right?

Let’s build this step by step. And yeah, there’s gonna be some reflection. Sorry not sorry.

Step 1: Creating the @Sensitive Annotation

First things first. We need the annotation itself.

This is the easy part, which is nice because the next parts get… interesting.

package com.example.security;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Marks a parameter, field, or method as containing sensitive data
 * that should be masked in logs, stack traces, and string representations.
 * 
 * Inspired by PHP's #[SensitiveParameter] attribute.
 * 
 * Example usage:
 * <pre>
 * public void login(String username, @Sensitive String password) {
 *     // password will be masked in any logs or stack traces
 * }
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
public @interface Sensitive {
    /**
     * The mask pattern to use when hiding sensitive data.
     * Default is "****"
     */
    String mask() default "****";
    
    /**
     * Whether to show partial data (e.g., last 4 digits of credit card)
     * Default is false - completely mask the data
     */
    boolean showPartial() default false;
    
    /**
     * Number of characters to show if showPartial is true
     */
    int partialLength() default 4;
}

See what I did there? I didn’t just make a marker annotation (you know, the ones that are just @interface Sensitive {}).

I added options. Because in the real world, you don’t always want to completely hide everything. Sometimes you need to show the last 4 digits of a credit card for support purposes. Sometimes you want a custom mask (I once worked at a place that insisted on using [REDACTED] for everything because someone watched too many spy movies).

The showPartial option lets you do exactly that. Want to show the last 4 digits? Done. Want a custom mask instead of ****? Easy.

Is this over-engineering? Probably. Do I care? Not really. Future me will thank current me when the requirements change.

Step 2: The Data Masking Utility (The Workhorse)

Okay, annotations are cool and all, but they don’t actually do anything. They’re just metadata.

We need something to actually mask the data. Enter SensitiveDataMasker.

This is where the real work happens. Think of it as the bouncer at the club - checking IDs (annotations) and deciding who gets in (what gets logged).

package com.example.security;

import java.lang.reflect.Field;
import java.lang.reflect.Parameter;

/**
 * Utility class for masking sensitive data based on @Sensitive annotations.
 */
public class SensitiveDataMasker {
    
    private static final String DEFAULT_MASK = "****";
    
    /**
     * Masks a value based on Sensitive annotation configuration
     */
    public static String mask(Object value, Sensitive annotation) {
        if (value == null) {
            return null;
        }
        
        String stringValue = value.toString();
        
        if (annotation == null) {
            return stringValue;
        }
        
        if (!annotation.showPartial()) {
            return annotation.mask();
        }
        
        // Show partial data (e.g., last 4 digits)
        int length = stringValue.length();
        int showLength = annotation.partialLength();
        
        if (length <= showLength) {
            return annotation.mask();
        }
        
        String visiblePart = stringValue.substring(length - showLength);
        String maskedPart = annotation.mask();
        
        return maskedPart + visiblePart;
    }
    
    /**
     * Masks method parameters that have @Sensitive annotation
     */
    public static Object[] maskParameters(Parameter[] parameters, Object[] args) {
        if (parameters == null || args == null || parameters.length != args.length) {
            return args;
        }
        
        Object[] maskedArgs = new Object[args.length];
        
        for (int i = 0; i < parameters.length; i++) {
            Sensitive annotation = parameters[i].getAnnotation(Sensitive.class);
            maskedArgs[i] = mask(args[i], annotation);
        }
        
        return maskedArgs;
    }
    
    /**
     * Creates a masked string representation of an object by hiding
     * all fields marked with @Sensitive
     */
    public static String toMaskedString(Object obj) {
        if (obj == null) {
            return "null";
        }
        
        StringBuilder sb = new StringBuilder();
        sb.append(obj.getClass().getSimpleName()).append("{");
        
        Field[] fields = obj.getClass().getDeclaredFields();
        boolean first = true;
        
        for (Field field : fields) {
            if (!first) {
                sb.append(", ");
            }
            first = false;
            
            field.setAccessible(true);
            
            try {
                Object value = field.get(obj);
                Sensitive annotation = field.getAnnotation(Sensitive.class);
                
                sb.append(field.getName()).append("=");
                
                if (annotation != null) {
                    sb.append(mask(value, annotation));
                } else {
                    sb.append(value);
                }
            } catch (IllegalAccessException e) {
                sb.append("?");
            }
        }
        
        sb.append("}");
        return sb.toString();
    }
}

This utility is the workhorse of our system. It handles masking individual values, masking method parameters in bulk, and creating masked string representations of entire objects.

I know what you’re thinking. “Is that reflection I see?” Yes. Yes it is.

Look, I tried doing this without reflection. I really did. Spent like 2 hours going down the bytecode manipulation rabbit hole with ByteBuddy. Then I remembered the golden rule: solve the problem first, optimize later. Reflection works fine here because we’re only using it when something’s actually being logged, which isn’t exactly a hot path in your application.

Plus, the JVM’s gotten really good at optimizing reflection calls these days. We’re not in Java 5 anymore.

Step 3: Custom Exception Handler for Stack Traces

Here’s where things get interesting.

package com.example.security;

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.Arrays;

/**
 * Custom exception wrapper that masks sensitive parameters in stack traces
 */
public class SensitiveException extends RuntimeException {
    
    private final transient Object[] originalArgs;
    private final transient Object[] maskedArgs;
    
    public SensitiveException(String message, Throwable cause, 
                             Method method, Object[] args) {
        super(buildMessage(message, method, args), cause);
        this.originalArgs = args;
        this.maskedArgs = maskArguments(method, args);
    }
    
    public SensitiveException(String message, Method method, Object[] args) {
        this(message, null, method, args);
    }
    
    private static Object[] maskArguments(Method method, Object[] args) {
        if (method == null || args == null) {
            return args;
        }
        
        Parameter[] parameters = method.getParameters();
        return SensitiveDataMasker.maskParameters(parameters, args);
    }
    
    private static String buildMessage(String message, Method method, Object[] args) {
        if (method == null) {
            return message;
        }
        
        Parameter[] parameters = method.getParameters();
        Object[] masked = SensitiveDataMasker.maskParameters(parameters, args);
        
        return String.format("%s | Method: %s | Arguments: %s", 
            message, 
            method.getName(), 
            Arrays.toString(masked));
    }
    
    public Object[] getMaskedArgs() {
        return maskedArgs != null ? maskedArgs.clone() : null;
    }
}

So this is basically a wrapper exception. When something goes wrong and you need to throw an exception, you throw this instead. It takes the original exception, looks at the method that caused it, finds any @Sensitive parameters, and masks them before building the error message.

The transient keyword on those fields? That’s because we don’t want masked passwords accidentally getting serialized and sent over the network. Been there, done that, got the post-mortem writeup.

Here’s a fun story: I initially didn’t make these transient. Deployed to staging. Everything looked great. Then someone serialized an exception for remote logging, and the original args went over the wire. Whoops. Always test your security features end-to-end, folks.

Step 4: The AOP Interceptor (Where the Magic Happens)

Okay, this is where we get a bit fancy. AOP - Aspect-Oriented Programming. Sounds scary. It’s not.

Think of it as a spy that sits between your method calls and does stuff before, after, or around them. In our case, it’s gonna catch any method with @Sensitive parameters and mask them before they hit the logs.

package com.example.security;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.Arrays;

/**
 * Aspect that automatically masks sensitive parameters in method calls
 * and ensures they don't leak into logs or exceptions
 */
@Aspect
@Component
public class SensitiveDataAspect {
    
    private static final Logger logger = LoggerFactory.getLogger(SensitiveDataAspect.class);
    
    /**
     * Intercept any method that has @Sensitive parameters
     */
    @Around("execution(* *(..)) && args(.., @Sensitive (*))")
    public Object maskSensitiveParameters(ProceedingJoinPoint joinPoint) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        Object[] args = joinPoint.getArgs();
        Parameter[] parameters = method.getParameters();
        
        // Mask arguments for logging
        Object[] maskedArgs = SensitiveDataMasker.maskParameters(parameters, args);
        
        // Log method entry with masked parameters
        if (logger.isDebugEnabled()) {
            logger.debug("Entering method: {} with args: {}", 
                method.getName(), 
                Arrays.toString(maskedArgs));
        }
        
        try {
            // Proceed with the original call
            Object result = joinPoint.proceed(args);
            
            if (logger.isDebugEnabled()) {
                logger.debug("Exiting method: {} successfully", method.getName());
            }
            
            return result;
        } catch (Throwable ex) {
            // Wrap exception with masked parameters
            logger.error("Exception in method: {} with args: {}", 
                method.getName(), 
                Arrays.toString(maskedArgs), 
                ex);
            
            throw new SensitiveException(
                "Error in " + method.getName(), 
                ex, 
                method, 
                args
            );
        }
    }
}

The @Around annotation is doing the heavy lifting here. That pointcut expression execution(* *(..)) && args(.., @Sensitive (*)) looks like line noise, I know. But it’s saying “intercept any method that has at least one parameter with @Sensitive annotation.”

Then we mask the args, log them safely, and if anything blows up, we wrap it in our SensitiveException so the stack trace stays clean.

One gotcha I ran into: the pointcut has to match the exact signature. I spent 30 minutes wondering why my aspect wasn’t firing before I realized I had the wrong number of dots in (..). Classic.

Step 5: The Logback Safety Net

You know what’s wild? Even with all the above, I still didn’t trust it completely. Because developers are creative. Someone will find a way to log a password directly. I’ve seen it happen.

So let’s add one more layer - a Logback encoder that catches common patterns.

package com.example.security;

import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.filter.Filter;
import ch.qos.logback.core.spi.FilterReply;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Logback filter that masks sensitive data patterns in log messages
 */
public class SensitiveLogFilter extends Filter<ILoggingEvent> {
    
    private static final Pattern PASSWORD_PATTERN = 
        Pattern.compile("(password|pwd|pass|secret|token|key)\\s*[:=]\\s*([^\\s,}]+)", 
            Pattern.CASE_INSENSITIVE);
    
    private static final Pattern API_KEY_PATTERN = 
        Pattern.compile("([a-zA-Z0-9]{32,})");
    
    private String maskPattern = "****";
    
    @Override
    public FilterReply decide(ILoggingEvent event) {
        String message = event.getMessage();
        
        if (message != null && containsSensitiveData(message)) {
            // Unfortunately, Logback doesn't allow message modification in filters
            // This would need to be implemented via a custom Layout instead
            // For now, we can at least detect and log a warning
            return FilterReply.NEUTRAL;
        }
        
        return FilterReply.NEUTRAL;
    }
    
    private boolean containsSensitiveData(String message) {
        return PASSWORD_PATTERN.matcher(message).find() || 
               API_KEY_PATTERN.matcher(message).find();
    }
    
    public void setMaskPattern(String maskPattern) {
        this.maskPattern = maskPattern;
    }
}

And the corresponding custom layout for Logback (logback.xml):

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.example.security.SensitiveMaskingEncoder">
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

And the encoder implementation:

package com.example.security;

import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
import ch.qos.logback.classic.spi.ILoggingEvent;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Custom Logback encoder that masks sensitive data in log messages
 */
public class SensitiveMaskingEncoder extends PatternLayoutEncoder {
    
    private static final Pattern PASSWORD_PATTERN = 
        Pattern.compile("(password|pwd|pass|secret|token|key)\\s*[:=]\\s*([^\\s,}\\]]+)", 
            Pattern.CASE_INSENSITIVE);
    
    @Override
    public byte[] encode(ILoggingEvent event) {
        String message = layout.doLayout(event);
        String maskedMessage = maskSensitiveData(message);
        return maskedMessage.getBytes();
    }
    
    private String maskSensitiveData(String message) {
        Matcher matcher = PASSWORD_PATTERN.matcher(message);
        StringBuffer sb = new StringBuffer();
        
        while (matcher.find()) {
            matcher.appendReplacement(sb, matcher.group(1) + "=****");
        }
        matcher.appendTail(sb);
        
        return sb.toString();
    }
}

This encoder sits in your logging pipeline and uses regex to catch patterns like password=something or token: xyz. Not perfect, but it’s saved me more than once from my own stupidity.

The regex (password|pwd|pass|secret|token|key)\\s*[:=]\\s*([^\\s,}]+) is probably my favorite line of code in this whole project. It’s like a little security guard that never sleeps.

Step 6: Seeing It in Action

Okay, enough theory. Let’s write some actual code that uses this.

package com.example.service;

import com.example.security.Sensitive;
import com.example.security.SensitiveDataMasker;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

@Service
public class AuthenticationService {
    
    private static final Logger logger = LoggerFactory.getLogger(AuthenticationService.class);
    
    /**
     * Login method with sensitive parameter
     */
    public boolean login(String username, @Sensitive String password) {
        // Even if we accidentally log the password, it will be masked
        logger.info("Login attempt for user: {}", username);
        
        try {
            // Simulate authentication
            boolean authenticated = authenticateUser(username, password);
            
            if (authenticated) {
                logger.info("User {} successfully authenticated", username);
                return true;
            } else {
                logger.warn("Authentication failed for user {}", username);
                return false;
            }
        } catch (Exception e) {
            // The stack trace won't show the actual password!
            logger.error("Authentication error", e);
            throw e;
        }
    }
    
    /**
     * Process payment with sensitive credit card info
     */
    public void processPayment(
            String username,
            @Sensitive(showPartial = true, partialLength = 4) String creditCard,
            @Sensitive String cvv) {
        
        logger.info("Processing payment for user: {}", username);
        // creditCard will show as "****1234" if the card number is "1234567890121234"
        // cvv will show as "****"
        
        // Process payment logic here
    }
    
    private boolean authenticateUser(String username, String password) {
        // Actual authentication logic
        return "admin".equals(username) && "secret123".equals(password);
    }
}

And here’s a User entity with sensitive fields:

package com.example.model;

import com.example.security.Sensitive;
import com.example.security.SensitiveDataMasker;

public class User {
    
    private String username;
    
    @Sensitive
    private String password;
    
    @Sensitive
    private String apiKey;
    
    private String email;
    
    @Sensitive(showPartial = true, partialLength = 4)
    private String phoneNumber;
    
    public User(String username, String password, String apiKey, 
                String email, String phoneNumber) {
        this.username = username;
        this.password = password;
        this.apiKey = apiKey;
        this.email = email;
        this.phoneNumber = phoneNumber;
    }
    
    // Getters and setters...
    
    @Override
    public String toString() {
        // Use our masking utility instead of default toString
        return SensitiveDataMasker.toMaskedString(this);
    }
}

Here’s the thing about that User class - the toString() method is where most leaks happen in my experience. Someone logs a user object for debugging, and bam, all the sensitive data is right there in plain text.

By overriding it with our toMaskedString() utility, we’re making the safe thing the default thing. And that’s really the whole point of this exercise.

Does It Actually Work? (Testing Time)

I’m not gonna lie - I was nervous when I first ran these tests. Like, “please work, please work” nervous.

package com.example.security;
import com.example.model.User;
import com.example.service.AuthenticationService;
import org.junit.jupiter.api.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import static org.junit.jupiter.api.Assertions.*;

class SensitiveDataTest {
    
    private static final Logger logger = LoggerFactory.getLogger(SensitiveDataTest.class);
    
    @Test
    void testUserToString_shouldMaskSensitiveFields() {
        User user = new User(
            "johndoe",
            "superSecret123!",
            "api_key_1234567890abcdef",
            "john@example.com",
            "1234567890"
        );
        
        String userString = user.toString();
        
        // Verify password is masked
        assertFalse(userString.contains("superSecret123!"));
        assertTrue(userString.contains("****"));
        
        // Verify API key is masked
        assertFalse(userString.contains("api_key_1234567890abcdef"));
        
        // Verify phone shows last 4 digits
        assertTrue(userString.contains("7890"));
        
        // Verify non-sensitive fields are visible
        assertTrue(userString.contains("johndoe"));
        assertTrue(userString.contains("john@example.com"));
        
        logger.info("User details: {}", user);
        // Log output: User details: User{username=johndoe, password=****, 
        //             apiKey=****, email=john@example.com, phoneNumber=****7890}
    }
    
    @Test
    void testLogin_shouldMaskPasswordInLogs() {
        AuthenticationService authService = new AuthenticationService();
        
        // This will log without exposing the password
        boolean result = authService.login("admin", "secret123");
        
        assertTrue(result);
    }
    
    @Test
    void testParameterMasking() {
        String original = "myPassword123";
        Sensitive annotation = createAnnotation(false, "****", 4);
        
        String masked = SensitiveDataMasker.mask(original, annotation);
        
        assertEquals("****", masked);
        assertNotEquals(original, masked);
    }
    
    @Test
    void testPartialMasking() {
        String creditCard = "1234567890123456";
        Sensitive annotation = createAnnotation(true, "****", 4);
        
        String masked = SensitiveDataMasker.mask(creditCard, annotation);
        
        assertEquals("****3456", masked);
        assertTrue(masked.endsWith("3456"));
    }
    
    private Sensitive createAnnotation(boolean showPartial, String mask, int partialLength) {
        return new Sensitive() {
            @Override
            public Class<? extends java.lang.annotation.Annotation> annotationType() {
                return Sensitive.class;
            }
            
            @Override
            public String mask() {
                return mask;
            }
            
            @Override
            public boolean showPartial() {
                return showPartial;
            }
            
            @Override
            public int partialLength() {
                return partialLength;
            }
        };
    }
}

That createAnnotation() helper is a bit ugly, I’ll admit. You can’t just new an annotation in Java (trust me, I tried). So you have to create an anonymous class that implements the annotation interface. It works, but it feels like you’re fighting the language a bit.

Whatever. Tests pass. Green checkmarks. Dopamine hit.

What We Built (The Good Stuff)

So after all that code, what did we actually achieve? Here’s the rundown:

Automatic parameter masking in logs via AOP. Just add the annotation, and you’re protected.
Stack trace protection through custom exception handling. No more passwords in error reports.
Flexible masking options. Full mask or show partial data, your choice.
Framework integration with Spring and Logback. Works with what you’re probably already using.
ToString safety for sensitive entities. Override once, safe forever.
Zero-impact on business logic. Seriously, just add @Sensitive and you’re done.

Not bad for a day’s work, if I say so myself.

The Real-World Impact (Why This Matters)

Let me paint you a picture. It’s 3 AM. Production’s on fire. You’re digging through logs trying to figure out why authentication is failing.

Without @Sensitive:

ERROR - Authentication failed for user: admin with password: superSecret123!

Congrats, you just found the bug. Also congrats, you now have to file a security incident report because that password is logged in 47 different places and backed up to S3.

With @Sensitive:

ERROR - Authentication failed for user: admin with password: ****

You still found the bug (it’s in the authentication logic, not the password itself). But now you can sleep at night.

That’s the difference. Not between working code and broken code. Between a debugging session and a career-limiting move.

Performance (The Question Everyone Asks)

“This sounds expensive!” Yeah, I thought that too. Let’s talk numbers.

AOP Overhead? Minimal. We’re only intercepting methods with @Sensitive parameters, not every method in your app. And AspectJ is fast - like, really fast.

Reflection? Sure, we use it. But only when something’s actually being logged, which isn’t happening millions of times per second. If your app is logging that much, you’ve got bigger problems.

String Operations? Only happens during logging or exceptions. Again, not a hot path.

I ran benchmarks. The overhead is typically less than 1ms per intercepted method call. Your database query takes 50ms. Your HTTP request takes 200ms. This? Barely registers.

Is it free? No. Is it worth it? Absolutely.

The Honest Limitations (Because Nothing’s Perfect)

Look, I’m not gonna pretend this solves everything. It doesn’t. Here’s what it can’t do:

Heap dumps will still show your passwords sitting in memory. If someone gets a heap dump, you’re already having a bad day.

Debugger access means developers can still see raw values when debugging. Which is fine - they’re supposed to be able to debug. Just don’t debug in production. (You’re not debugging in production, right? Right?)

Serialization isn’t handled. Standard Java serialization will serialize the raw values. You’d need custom serializers for that.

JVM native methods and deep JVM internals bypass our aspects. We’re working at the application layer, not the JVM layer.

Could we fix these? Maybe. With a Java Agent, you could get deeper integration. With custom serializers, you could handle serialization. With memory encryption… okay, now we’re getting into tinfoil hat territory.

The point is: this isn’t a silver bullet. It’s a really good first line of defense. And sometimes, that’s exactly what you need.

What I Learned Building This

You know what’s funny? I started this thinking it’d be a quick afternoon project. “Just intercept some method calls, mask some strings, how hard could it be?”

Four hours later, I’m deep in the Logback source code trying to figure out why my encoder isn’t firing. Turns out I’d misconfigured the appender. Classic.

But here’s what I actually learned:

Security is messy. There’s no clean solution that handles everything. You layer defenses and hope you caught the important stuff.

Developer experience matters more than I thought. If the annotation is hard to use, people won’t use it. Simple as that. So we made it stupid simple - just add @Sensitive and it works.

Integration beats innovation. I could’ve built something totally custom that requires a special framework. Or I could make it work with Spring and Logback that everyone already uses. Guess which one people will actually adopt?

Wrapping Up (And What’s Next)

So here we are. We’ve got a working @Sensitive annotation that actually prevents password leaks. It’s not perfect, but it’s pretty damn good.

The code’s modular. The tests pass. You can drop it into your Spring Boot app right now and it’ll just work. No weird dependencies. No configuration hell. Just protection.

Is it as elegant as PHP’s native #[SensitiveParameter]? Maybe not. But it’s more flexible, and it works with the Java ecosystem we already have. I’ll take “works today” over “perfectly elegant” any day.

Tomorrow, we’ll explore how to extend this with custom annotation processors that validate sensitive data handling at compile time. But that’s a story for Day 94!

Try It Yourself

Copy the codes from here and start your own experiments:

Add @Sensitive to different parameter types
Test with various logging frameworks
Try the partial masking with credit cards
Create custom mask patterns

Remember: Security isn’t just about preventing attacks, it’s about protecting your users' trust. And sometimes, that starts with a simple annotation.

Happy (and secure) coding.

References and Further Reading

Day 92: Building AI Agents with Java 21 and Spring AI - My Learning from the Workshop

2025-09-10T00:00:00Z

Building Production-Ready AI Agents with Spring AI: My learning from the workshop

Hey fellow Java developers, Today marks day 92 of my #100DaysOfJava journey, I have an exciting story to share with you! I recently attended an incredible workshop on Building Java AI Agents with Spring AI hosted by AWS. In this workshop I learned about building an AI agent that can not only chat with you but also manage a fictional unicorn rental business as example application.

What you will learn

This article will demonstrate my learnings from the workshop, like how to construct a complete AI agent system using Spring AI, progressing from a simple chat interface to a sophisticated application featuring:

Persistent Memory Management
Retrieval-Augmented Generation (RAG)
External Tool Integration
ChatClient Interface
Vector Store Integration
AWS Bedrock Integration
Model Context Protocol (MCP)
Production Deployment
Security & Performance
Real-world Architecture

We’ll build a fictional unicorn rental system that showcases real-world AI integration patterns applicable to any business domain.

Picture this: You’re a Java developer who has been comfortable with Spring Boot for years, and suddenly someone tells you that you can now build AI-powered applications using the same familiar Spring concepts you already know and love. That’s exactly what Spring AI brings to the table!

Understanding Spring AI’s Core Architecture

Spring AI provides a unified abstraction layer over various AI model providers, including OpenAI, Azure OpenAI, and Amazon Bedrock. The framework’s central component is the ChatClient interface, which standardizes interactions with different AI models while maintaining Spring’s dependency injection and configuration principles.

To fully grasp Spring AI’s architecture, it’s essential to understand its foundational concepts. The Spring AI Core Concepts documentation provides comprehensive coverage of these fundamental principles.

The ChatClient Interface: Your Gateway to AI Magic

At the heart of Spring AI lies the ChatClient interface - think of it as your personal assistant that can talk to any AI model. Here’s what makes it so powerful:

@RestController
@RequestMapping("api")
public class ChatController {
    
    private static final String DEFAULT_SYSTEM_PROMPT = """
        You are a helpful AI assistant for Unicorn Rentals, a fictional company that rents unicorns.
        Be friendly, helpful, and concise in your responses.
        """;

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
            .defaultSystem(DEFAULT_SYSTEM_PROMPT)
            .build();
    }
}

It can use any model under the hood with system prompt and other configuration. This abstraction enables switching between AI providers without modifying application logic, similar to how Spring Data abstracts database interactions.

@PostMapping("/chat/stream")
public Flux<String> chatStream(@RequestBody PromptRequest promptRequest){
    var conversationId = "user1"; // This should be retrieved from the Auth context
    return chatClient.prompt().user(promptRequest.prompt())
        .advisors(advisor -> advisor.param(ChatMemory.CONVERSATION_ID, conversationId))
        .stream().content();
}

The streaming endpoint returns a Flux<String>, which means the frontend receives the AI response word by word, creating that magical typewriter effect!

Step 2: Giving Our Agent Memory

What good is a rental agent who forgets who you are the moment you ask a second question? This is where MessageChatMemoryAdvisor comes to the rescue. As LLM doesnt have persistent memory between each call, if we dont manage memory ourselves we wont remember important information in our chats. Furthermore, assistant wont be able to give accurate and helpful answers without memory

public ChatController(ChatClient.Builder chatClient, DataSource dataSource, 
                     VectorStore vectorStore, ToolCallbackProvider tools) {
    var chatMemoryRepository = JdbcChatMemoryRepository.builder()
        .dataSource(dataSource)
        .dialect(new PostgresChatMemoryRepositoryDialect())
        .build();

    var chatMemory = MessageWindowChatMemory.builder()
        .chatMemoryRepository(chatMemoryRepository)
        .maxMessages(20)
        .build();

    this.vectorStore = vectorStore;

    this.chatClient = chatClient
        .defaultSystem(DEFAULT_SYSTEM_PROMPT)
        .defaultAdvisors(
            MessageChatMemoryAdvisor.builder(chatMemory).build(),
            QuestionAnswerAdvisor.builder(vectorStore).build())
        .defaultTools(new DateTimeTools(), new WeatherTools())
        .defaultToolCallbacks(tools)
        .build();
}

The MessageWindowChatMemory maintains a sliding window of recent messages, while JdbcChatMemoryRepository provides persistence using standard database infrastructure.

Streaming Responses for Enhanced User Experience

Modern AI applications benefit from streaming responses that provide immediate feedback:

@PostMapping("/chat/stream")
public Flux<String> chatStream(@RequestBody PromptRequest promptRequest){
    var conversationId = "user1"; // Should be retrieved from authentication context
    return chatClient.prompt().user(promptRequest.prompt())
        .advisors(advisor -> advisor.param(ChatMemory.CONVERSATION_ID, conversationId))
        .stream().content();
}

record PromptRequest(String prompt) {}

The Flux<String> return type enables real-time streaming of AI responses, improving perceived performance and user engagement.

Web Interface

The web interface features:

Real-time streaming responses - Watch as the AI types responses in real-time!
Dark mode design - Perfect for developers who love dark themes
Responsive layout - Works beautifully on desktop and mobile
Chat history - See your entire conversation flow

Implementing Retrieval-Augmented Generation (RAG)

RAG enhances AI responses by incorporating domain-specific knowledge from external sources. This approach combines the general knowledge of pre-trained models with current, specific information from your organization’s data.

Vector Store Integration

Spring AI integrates seamlessly with PostgreSQL’s PGVector extension for vector similarity search:

@PostMapping("load")
public void loadDataToVectorStore(@RequestBody String content) {
    vectorStore.add(List.of(new Document(content)));
}

The RAG workflow operates as follows:

Documents are chunked and converted to vector embeddings using Amazon Titan
User queries are similarly embedded
Vector similarity search retrieves relevant document chunks
The AI model generates responses using both its training data and retrieved context

Configuration for RAG

The application properties configure the complete RAG pipeline:

# RAG Configuration
spring.ai.model.embedding=bedrock-titan
spring.ai.bedrock.titan.embedding.model=amazon.titan-embed-text-v2:0
spring.ai.bedrock.titan.embedding.input-type=text
spring.ai.vectorstore.pgvector.initialize-schema=true
spring.ai.vectorstore.pgvector.dimensions=1024

This configuration automatically initializes the vector database schema and configures Amazon Titan for generating embeddings.

Tool Calling: Extending AI Capabilities

Tool calling allows AI agents to interact with external systems and APIs, transforming them from simple chatbots into capable automation systems.

Implementing External Tools

Tools are defined using the @Tool annotation and standard Java methods:

public class WeatherTools {
    private final RestTemplate restTemplate = new RestTemplate();

    @Tool(description = "Get weather forecast for a city on a specific date (format: YYYY-MM-DD)")
    public String getWeather(String city, String date) {
        try {
            // Convert city to coordinates using Geocoding API
            var encodedCity = UriUtils.encode(city, StandardCharsets.UTF_8);
            var geocodingUrl = URI.create("https://geocoding-api.open-meteo.com/v1/search?name=" +
                                         encodedCity + "&count=1");

            var geocodingResponse = restTemplate.exchange(
                geocodingUrl,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<Map<String, Object>>() {}
            );

            var body = geocodingResponse.getBody();
            var results = (body != null) ? (List<?>) body.getOrDefault("results", Collections.emptyList()) : Collections.emptyList();
            if (results.isEmpty()) {
                return "City not found: " + city;
            }

            var location = (Map<?, ?>) results.get(0);
            var latitude = ((Number) location.get("latitude")).doubleValue();
            var longitude = ((Number) location.get("longitude")).doubleValue();
            var cityName = (String) location.get("name");

            // Get weather data from Open-Meteo API
            var weatherUrl = URI.create(
                "https://api.open-meteo.com/v1/forecast" +
                "?latitude=%s&longitude=%s".formatted(latitude, longitude) +
                "&daily=temperature_2m_max,temperature_2m_min" +
                "&timezone=auto" +
                "&start_date=%s&end_date=%s".formatted(date, date)
            );

            var weatherResponse = restTemplate.exchange(
                weatherUrl,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<Map<String, Object>>() {}
            );

            var weatherData = weatherResponse.getBody();
            if (weatherData == null) {
                return "Failed to retrieve weather data";
            }

            var dailyData = (Map<?, ?>) weatherData.get("daily");
            var dailyUnits = (Map<?, ?>) weatherData.get("daily_units");

            if (dailyData == null || dailyUnits == null) {
                return "Weather data format is invalid";
            }

            var maxTempList = (List<?>) dailyData.get("temperature_2m_max");
            var minTempList = (List<?>) dailyData.get("temperature_2m_min");

            if (maxTempList == null || minTempList == null || maxTempList.isEmpty() || minTempList.isEmpty()) {
                return "Temperature data not available for the specified date";
            }

            var maxTemp = ((Number) maxTempList.get(0)).doubleValue();
            var minTemp = ((Number) minTempList.get(0)).doubleValue();
            var unit = (String) dailyUnits.get("temperature_2m_max");

            return """
                   Weather for %s on %s:
                   Min: %.1f%s, Max: %.1f%s
                   """.formatted(cityName, date, minTemp, unit, maxTemp, unit);

        } catch (Exception e) {
            return "Error fetching weather data: " + e.getMessage();
        }
    }
}

DateTime Tool for Temporal Context

A simpler tool demonstrates basic temporal functionality:

class DateTimeTools {
    @Tool(description = "Get the current date and time")
    public String getCurrentDateTime(String timeZone) {
        return java.time.ZonedDateTime.now(java.time.ZoneId.of(timeZone))
                .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}

When users request weather information, the AI automatically determines it needs current time context and weather data, orchestrating multiple tool calls to provide comprehensive responses.

Model Context Protocol (MCP) Integration

MCP standardizes communication between AI agents and external services. This protocol enables AI agents to interact with existing business systems without custom integration code.

Converting Existing Services to MCP Servers

Existing Spring Boot services can be enhanced with MCP capabilities by adding the @Tool annotation to service methods:

@Service
public class UnicornService {
    private final UnicornRepository unicornRepository;
    private final UnicornPublisher unicornPublisher;
    private static final Logger logger = LoggerFactory.getLogger(UnicornService.class);

    @Tool(description = "Create a new unicorn in the unicorn store.")
    @Transactional
    public Unicorn createUnicorn(Unicorn unicorn) {
        logger.debug("Creating unicorn: {}", unicorn);
        if (unicorn.getId() == null) {
            unicorn.setId(UUID.randomUUID().toString());
        }
        validateUnicorn(unicorn);

        var savedUnicorn = unicornRepository.save(unicorn);
        publishUnicornEvent(savedUnicorn, UnicornEventType.UNICORN_CREATED);

        logger.debug("Created unicorn with ID: {}", savedUnicorn.getId());
        return savedUnicorn;
    }

    @Tool(description = "Get a list of all unicorns in the unicorn store")
    public List<Unicorn> getAllUnicorns(String... parameters) {
        logger.debug("Retrieving all unicorns");
        return StreamSupport
                .stream(unicornRepository.findAll().spliterator(), false)
                .collect(Collectors.toList());
    }
}

This approach allows AI agents to perform actual business operations, transforming them from conversational interfaces into functional business automation tools.

Configuration-Driven Development

Spring AI’s configuration-centric approach minimizes boilerplate code:

# Application basics
spring.application.name=agent
logging.level.org.springframework.ai=DEBUG

# Amazon Bedrock Configuration
spring.ai.bedrock.converse.chat.options.model=us.anthropic.claude-3-7-sonnet-20250219-v1:0

# UI Configuration
spring.thymeleaf.cache=false
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html

# JDBC Memory Configuration
spring.ai.chat.memory.repository.jdbc.initialize-schema=always
spring.datasource.username=postgres

# RAG Configuration
spring.ai.model.embedding=bedrock-titan
spring.ai.bedrock.titan.embedding.model=amazon.titan-embed-text-v2:0
spring.ai.bedrock.titan.embedding.input-type=text
spring.ai.vectorstore.pgvector.initialize-schema=true
spring.ai.vectorstore.pgvector.dimensions=1024

# MCP Client Configuration
spring.ai.mcp.client.toolcallback.enabled=true

This configuration automatically sets up:

Claude 3.5 Sonnet as our chat model
Amazon Titan for embeddings
PostgreSQL for memory and vector storage
Thymeleaf for web templates
MCP client for external tool integration

No manual beans, no complex configuration classes - just properties!

The Complete Architecture: A Symphony of Components

Our final unicorn rental agent was a masterpiece of modern software architecture:

ChatClient - The conductor orchestrating everything
Web Interface - Beautiful Thymeleaf + Tailwind CSS frontend with real-time streaming
Memory System - Both local and persistent, keeping track of conversations
Vector Store - RAG capabilities for domain knowledge
Tool Calling - Weather, datetime, and business operations
MCP Integration - Communication with external services
AWS Bedrock - Powerful Claude AI models and Titan embeddings
PostgreSQL + PGVector - Reliable data storage with vector capabilities

The beauty of this architecture is how all these components work together seamlessly, yet each can be developed and tested independently.

Deployment: Taking It to the Cloud

The workshop didn’t stop at development - we deployed our creation to AWS EKS (Elastic Kubernetes Service)! Using Jib for containerization and Kubernetes manifests, our unicorn rental agent went from local development to cloud-ready production.

# Building and pushing to Amazon ECR
mvn compile jib:build -Dimage=$ECR_URI:latest

# Deploying to Amazon EKS
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml

Key Takeaways for Fellow Java Developers

Familiar Territory: Spring AI uses the same patterns we know and love from Spring Framework
Progressive Enhancement: Start simple, add features incrementally
Real Business Value: AI agents can perform actual business operations, not just chat
Production Ready: With proper architecture, these agents can handle real-world loads
Ecosystem Integration: Seamlessly works with existing Spring/Java infrastructure

Performance and Scaling

Several factors impact production performance:

Memory Management: Configure appropriate message window sizes based on conversation length requirements
Vector Store Optimization: Regularly maintain vector indexes and consider partitioning strategies for large datasets
Connection Pooling: Configure database connection pools appropriately for concurrent AI interactions
Caching: Implement caching strategies for frequently accessed embeddings and tool responses

Security Considerations

Production deployments require attention to security:

Authentication: Integrate conversation IDs with proper user authentication systems
API Rate Limiting: Implement rate limiting to prevent abuse of AI endpoints
Data Privacy: Ensure conversation data handling complies with privacy regulations
Input Validation: Validate and sanitize all user inputs before processing

Common Pitfalls and Best Practices

When developing AI applications with Spring AI, several common pitfalls can impact performance, cost, and user experience. Here’s how to avoid them:

Memory Management

Unlimited conversation history can lead to context window overflow and increased costs. Implement sliding window memory with appropriate limits:

var chatMemory = MessageWindowChatMemory.builder()
    .chatMemoryRepository(chatMemoryRepository)
    .maxMessages(20) // Adjust based on use case
    .build();

Tool Design Principles

Effective tools should be:

Atomic: Each tool should perform a single, well-defined operation
Idempotent: Tools should produce consistent results for identical inputs
Error-Resilient: Implement comprehensive error handling and fallback mechanisms

Vector Store Maintenance

RAG systems require ongoing maintenance:

Regular reindexing of document embeddings
Monitoring for embedding drift as models evolve
Implementing document versioning and update strategies

Real-World Applications

The patterns demonstrated extend to various enterprise scenarios:

Customer Service Automation

AI agents can handle customer inquiries by accessing knowledge bases, order systems, and external APIs for real-time information retrieval and problem resolution.

Internal Tool Integration

Development teams can create AI assistants that interact with CI/CD systems, monitoring tools, and documentation platforms to streamline operational workflows.

Business Process Automation

AI agents can orchestrate complex business processes by integrating with ERP systems, approval workflows, and notification services.

Conclusion: The Future of Java AI Development

Spring AI represents a paradigm shift for Java developers entering the AI space. Instead of learning entirely new frameworks or switching to Python, you can leverage your existing Spring expertise to build sophisticated AI applications.

Key takeaways for your next Java AI project:

Leverage Familiar Patterns: Spring AI uses dependency injection, configuration properties, and annotations you already know
Start Simple, Scale Smart: Begin with basic chat functionality and progressively add memory, RAG, and tool calling
Production-Ready Architecture: The framework includes enterprise features like connection pooling, error handling, and monitoring out of the box
Provider Flexibility: Switch between OpenAI, Azure, AWS Bedrock, or other providers without changing your application code
Real Business Value: Move beyond chatbots to create AI agents that integrate with existing business systems

The combination of Spring AI’s familiar development model with powerful AI capabilities opens up endless possibilities for Java applications. Whether you’re building customer service automation, internal development tools, or complex business process orchestration, Spring AI provides the foundation you need.

As the AI landscape continues evolving, Spring AI ensures Java developers can innovate without abandoning their expertise. The future of enterprise AI is here, and it speaks Java.

Ready to start building? Check out the complete project repository and begin your own AI journey today.

This post is part of my #100DaysOfJava challenge. Follow along for daily insights into Java development, Spring Framework innovations, and cutting-edge software engineering practices.

Resources:

Day 91: The Art of Reading Massive Files Without Breaking a Sweat - Memory Mapping in Java 21

2025-08-15T00:00:00Z

Any sufficiently advanced technology is indistinguishable from magic" - Arthur C. Clark

Today I am exploring that looked to me like a magic trick when I first saw it in a PR for 1BRC challange by Gunnar Morling which is called Memory mapping a very large file.

1. Memory-Mapped Files: The Magician’s Trick

Let me talk about the first time I discovered memory-mapped files. I was looking into the pr where it was required to read a very large file with 1 billion rows of temperature data which was around a 12GB file, You will find all the details here.

Memory mapping to me felt like is having a magical book that automatically opens to exactly the page you’re thinking about. But here’s where it gets fascinating, I didnt understood the magic so like a scientific explorer I started to look in depth what is happening and now I am sharing the expedition as blog post.From the deepest kernel level all the way up to your Java code.

The Deep Dive: From Kernel to Code

Now we are going to deep dive together into the whole process, where it starts from kernel and ends with creating a memory mapped file for us.

Step 1: The OS Kernel’s Virtual Memory Magic

When you call channel.map() in Java, you’re actually asking the operating system to perform one of its coolest tricks. The OS kernel creates what’s called a virtual memory mapping. Think of it like this:

Your file on disk is sitting there, maybe 5GB of data. Instead of copying all that data into your program’s memory (which would blow up your heap memory), the kernel creates a clever illusion. It assigns a range of virtual memory addresses—let’s say from address 0x10000000 to 0x30000000—and says these addresses represent the file.

But here’s the kicker: no actual file data gets loaded yet. The kernel just creates a mapping table that says “if anyone asks for memory at address 0x10000000, that’s actually byte 0 of the file.”

Step 2: The Page Fault

Now comes the really clever part. When your Java code tries to read from the mapped buffer:

1
2

MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, fileSize);
byte firstByte = buffer.get(0); // This triggers the magic!

That buffer.get(0) call tries to access virtual memory address 0x10000000. But remember, there’s no actual data there yet! This causes what’s called a “page fault”—the CPU literally stops and says “hey OS, there’s nothing at this address!”

The kernel’s page fault handler springs into action:

It realizes this address is part of a file mapping
It calculates which part of the file needs to be loaded (usually 4KB or 8KB chunks called “pages”)
It reads that chunk from disk into physical RAM
It updates the memory mapping table to point that virtual address to the real RAM location
It tells the CPU “okay, try again”

Your CPU then successfully reads the byte, and your Java code continues happily, completely unaware of this elaborate mechanism that just happened.

Step 3: The Page Cache Optimization

Here’s where things get really intriguing. The OS doesn’t just load the data and forget about it. It keeps those file chunks in what’s called the page cache. This is shared memory that all processes on the system can use.

So if another program (or even another instance of your program) tries to read the same file, the OS says “I already have that in RAM!” and reuses the same physical memory pages. This is why memory-mapped files are incredibly efficient when multiple processes need to access the same large files.

Here you can get the whole idea how memory mapping is working behind the scene

The Java Layer: What’s Really Happening

Now let’s look at what Java is doing on top of this OS magic:

import java.io.RandomAccessFile;
import java.nio.MappedByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.charset.StandardCharsets;

public class MemoryMappedReader {
    public static void processLogFile(String path) {
        try (RandomAccessFile file = new RandomAccessFile(path, "r");
             FileChannel channel = file.getChannel()) {

            long fileSize = channel.size();
            System.out.println("File size: " + fileSize / (1024 * 1024) + "MB");

            // This is the critical moment - we're asking the OS to create the mapping
            MappedByteBuffer buffer = channel.map(
                FileChannel.MapMode.READ_ONLY, 
                0, 
                fileSize
            );

            // Let's demonstrate different access patterns to show the performance characteristics
            demonstrateRandomAccess(buffer);
            demonstrateSequentialAccess(buffer);
            demonstratePatternSearch(buffer);

        } catch (Exception e) {
            System.err.println("Something went wrong: " + e.getMessage());
        }
    }

    private static void demonstrateRandomAccess(MappedByteBuffer buffer) {
        System.out.println("\n=== Random Access Test ===");
        long startTime = System.nanoTime();
        
        // Jump around the file randomly - this shows the power of memory mapping
        long[] positions = {0, buffer.limit() / 4, buffer.limit() / 2, buffer.limit() * 3 / 4, buffer.limit() - 1};
        
        for (long pos : positions) {
            if (pos < buffer.limit()) {
                buffer.position((int)pos);
                byte b = buffer.get();
                System.out.println("Byte at position " + pos + ": " + (char)b);
            }
        }
        
        long endTime = System.nanoTime();
        System.out.println("Random access took: " + (endTime - startTime) / 1_000_000 + "ms");
        System.out.println("Notice how fast that was? No disk seeks needed after the first few page faults!");
    }

    private static void demonstrateSequentialAccess(MappedByteBuffer buffer) {
        System.out.println("\n=== Sequential Access Test ===");
        buffer.position(0); // Reset to beginning
        
        long startTime = System.nanoTime();
        int lineCount = 0;
        
        // This will trigger efficient sequential page loading
        while (buffer.hasRemaining() && lineCount < 1000) {
            byte b = buffer.get();
            if (b == '\n') {
                lineCount++;
            }
        }
        
        long endTime = System.nanoTime();
        System.out.println("Counted " + lineCount + " lines");
        System.out.println("Sequential access took: " + (endTime - startTime) / 1_000_000 + "ms");
        System.out.println("The OS optimized this by reading ahead!");
    }

    private static void demonstratePatternSearch(MappedByteBuffer buffer) {
        System.out.println("\n=== Pattern Search Test ===");
        buffer.position(0); // Reset to beginning
        
        byte[] errorPattern = "ERROR".getBytes(StandardCharsets.UTF_8);
        int errorCount = 0;
        long startTime = System.nanoTime();
        
        // This shows how we can treat the entire file like a giant array
        while (buffer.hasRemaining()) {
            if (matchesPattern(buffer, errorPattern)) {
                errorCount++;
                // Skip past the matched pattern to avoid double-counting
                buffer.position(Math.min(buffer.position() + errorPattern.length, buffer.limit()));
            } else {
                buffer.position(buffer.position() + 1);
            }
        }
        
        long endTime = System.nanoTime();
        System.out.println("Found " + errorCount + " errors");
        System.out.println("Pattern search took: " + (endTime - startTime) / 1_000_000 + "ms");
        System.out.println("We just searched through the entire file without loading it all into heap memory!");
    }

    private static boolean matchesPattern(MappedByteBuffer buffer, byte[] pattern) {
        if (buffer.remaining() < pattern.length) return false;
        
        int originalPosition = buffer.position();
        
        // Check if the pattern matches at current position
        for (int i = 0; i < pattern.length; i++) {
            if (buffer.get() != pattern[i]) {
                buffer.position(originalPosition); // Reset position
                return false;
            }
        }
        
        buffer.position(originalPosition); // Reset position for caller
        return true;
    }

    // Let's also show what happens with memory monitoring
    public static void demonstrateMemoryUsage(String path) {
        Runtime runtime = Runtime.getRuntime();
        
        long beforeMapping = runtime.totalMemory() - runtime.freeMemory();
        System.out.println("Heap memory before mapping: " + beforeMapping / (1024 * 1024) + "MB");

        try (RandomAccessFile file = new RandomAccessFile(path, "r");
             FileChannel channel = file.getChannel()) {

            long fileSize = channel.size();
            MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, fileSize);

            long afterMapping = runtime.totalMemory() - runtime.freeMemory();
            System.out.println("Heap memory after mapping " + fileSize / (1024 * 1024) + "MB file: " + afterMapping / (1024 * 1024) + "MB");
            System.out.println("Heap memory increase: " + (afterMapping - beforeMapping) / 1024 + "KB");
            System.out.println("See? The file data isn't in our heap - it's managed by the OS!");

            // Access some data to trigger page faults
            for (int i = 0; i < Math.min(1000000, buffer.limit()); i += 4096) {
                buffer.get(i); // Access one byte per page (4KB)
            }

            long afterAccess = runtime.totalMemory() - runtime.freeMemory();
            System.out.println("Heap memory after accessing data: " + afterAccess / (1024 * 1024) + "MB");
            System.out.println("Still barely any heap usage!");

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

The Real Magic: What Makes This So Fast?

1. No Data Copying

Traditional file reading copies data from disk → OS buffer → your application’s memory. Memory mapping eliminates that middle step. Your application directly accesses the OS’s file cache.

2. Lazy Loading

The file isn’t actually read until you access specific parts. If you have a 10GB file but only read the first 100MB, only that 100MB gets loaded into RAM.

3. Shared Memory

Multiple processes can map the same file and share the same physical RAM pages. If you have 5 Java processes all analyzing the same log file, they all share the same cached data.

4. OS Optimization

The operating system is incredibly smart about predicting what you’ll read next. If you’re reading sequentially, it starts loading the next few pages in advance. If you’re jumping around randomly, it keeps recently accessed pages in cache.

The Dark Side: When Memory Mapping Goes Wrong

As we know every magic trick have its costs or its dark side let us explore what are the core costs and limitations of Memory Mapping a file.

The 32-bit Limitation

On 32-bit systems, you can only map about 2-4GB total across your entire process. Try to map a 10GB file, and you’ll get an IOException. This is because virtual address space is limited to 4GB total, and your heap, stack, and other stuff need space too.

// This will fail on 32-bit systems with large files
try {
    MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, tenGigabyteFileSize);
} catch (IOException e) {
    System.err.println("Probably hit virtual address space limit: " + e.getMessage());
}

The File Locking Problem

While your file is mapped, the OS holds a lock on it. Other processes can’t delete or modify the file. I’ve seen production deployments fail because a mapped log file couldn’t be rotated.

The Platform Dependency

Memory mapping performance varies wildly between operating systems. Windows, Linux, and macOS all implement it differently, with different page sizes and caching strategies.

Performance Showdown: The Numbers Don’t Lie

I ran some benchmarks on a 200MB log file to show you the difference:

=== Files.readAllLines() Test ===
Heap memory before reading: 3MB
Lines read: 1673704
Reading took: 793ms
Heap memory after reading: 311MB
Heap memory increase: 308MB
Notice: The entire file is now loaded in heap memory!
Found 700 error lines

=== BufferedReader Test ===
Heap memory before reading: 313MB
Lines read: 1673704
Reading took: 836ms
Heap memory after reading: 498MB
Heap memory increase: 185MB
Notice: BufferedReader processes line by line without loading entire file!
Found 700 error lines
File size: 200MB

==== Memory Mapping Test ====

=== Random Access Test ===
Byte at position 0: 2
Byte at position 52428859: e
Byte at position 104857719: ]
Byte at position 157286578: 

Byte at position 209715437: 

Random access took: 4ms
Notice how fast that was? No disk seeks needed after the first few page faults!

=== Sequential Access Test ===
Counted 1000 lines
Sequential access took: 4ms
The OS optimized this by reading ahead!

=== Pattern Search Test ===
Found 700 errors
Pattern search took: 612ms
We just searched through the entire file without loading it all into heap memory!
Heap memory before mapping: 500MB
Heap memory after mapping 200MB file: 500MB
Heap memory increase: 0KB
See? The file data isn't in our heap - it's managed by the OS!
Heap memory after accessing data: 502MB
Still barely any heap usage!

Process finished with exit code 0

The memory-mapped version is really faster than traditional reading and used 100x less memory in pattern search.

When to Use Memory Mapping

Perfect scenarios:

Log analysis tools that need to jump around files
Database implementations (this is how most databases work internally)
Image processing where you need random pixel access
Any time you need to treat a file like a giant array

Avoid when:

You’re on a 32-bit system with large files
The file changes frequently while you’re reading it
You only need to read the file once, sequentially
You’re in a memory-constrained environment where you can’t trust the OS page cache

The beauty of memory mapping is that it turns file I/O into memory access, letting the operating system’s decades of optimization work for you. It’s like having a genius butler who anticipates your every need and fetches data before you even know you want it like Alfred. The full code is in my github

Day 90: How I Built a Secret Agent That Infiltrates Any Java Application

2025-07-18T00:00:00Z

Ever had that sinking feeling? A critical application slows to a crawl in production. Users are complaining. You’re staring at logs, but they tell you nothing. You wish you could just ask the application, “What’s taking you so long?” Debugging is out; you can’t just halt a live system. This is where commercial giants like New Relic or Datadog wave their magic wands and produce beautiful dashboards showing you exactly which methods are the culprits.

I’ve seen developers wrestle with these black boxes. But what if I told you that the “magic” isn’t magic at all? It’s a standard, if somewhat hidden, feature of the JVM. Today, on day 90 of your Java journey, we are going to explore the keys to this kingdom. We’re going to build our own Java Agent.

We’ll create a simple, powerful tool that can attach to any Java application and measure method execution times, all without touching a single line of the target application’s source code.

But before that let us understand what is an APM.

What is an APM

APM stands for Application Performance Monitoring. It’s a system that helps monitor, manage, and optimize the performance of software applications, ensuring they are available and performant for users

Now let us move on to making a very simple Agent which can monitor the timing of the method execution. But before that let us understand what is a java agent?

What is a Java Agent? Not AI but The Spy Inside

Think of a Java Agent as a spy you send into the JVM. It’s a special JAR file that the JVM gives special privileges to. Its primary mission, using the java.lang.instrument API, is to intercept classes as they are being loaded. Before a class even gets a chance to run, our agent can step in and rewrite its bytecode on the fly.

There are two ways to deploy your agent:

Static Attachment:

You specify the agent at startup with the -javaagent flag. This is like having your spy embedded from the very beginning.

Dynamic Attachment:

You attach the agent to an already running JVM. This is the “emergency extraction” of diagnostics, more complex but incredibly powerful.

We’ll focus on the static approach today. It’s the perfect way to learn what is a java agent.

The Agent’s Entry Point: The premain Method

Just as your application has a main method, our agent has a premain method. The name says it all: it runs before main. This is our beachhead. The JVM calls this method and hands us the most important tool in our arsenal: the Instrumentation object. This object is our license to modify code.

Let’s look at the skeleton of our agent.

// In our Agent project
package com.example.javaagent;

import java.lang.instrument.Instrumentation;

public class MyTimingAgent {

    public static void premain(String agentArgs, Instrumentation inst) {
        System.out.println("Starting our custom Java Agent...");
        // The magic will happen here!
    }
}

For the JVM to recognize this as an agent, we need to add a special entry to our JAR’s META-INF/MANIFEST.MF file. We’ll let Maven’s maven-jar-plugin handle this configuration for us. We have another full section about what should this manifest file do and how to write it, a little bit later.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
            <configuration>
                <archive>
                    <manifest>
                        <addClasspath>true</addClasspath>
                    </manifest>
                    <manifestEntries>
                        <Premain-Class>
                            com.example.javaagent.MyTimingAgent
                        </Premain-Class>
                    </manifestEntries>
                </archive>
            </configuration>
        </plugin>
    </plugins>
</build>

The Right Tool for the Job: Byte Buddy

Now for the fun part: rewriting bytecode. We could, in theory, do this manually with a low-level library like ASM. That’s like trying to assemble a watch from raw metal—incredibly difficult and error-prone. We’re going to work smarter. We’ll use Byte Buddy, a brilliant, modern library that makes bytecode manipulation feel less like arcane magic and more like writing a fluent, readable builder.

First, add the Byte Buddy dependency to your agent’s pom.xml.

<dependencies>
    <dependency>
        <groupId>net.bytebuddy</groupId>
        <artifactId>byte-buddy</artifactId>
        <version>1.14.16</version>
    </dependency>
    <dependency>
        <groupId>net.bytebuddy</groupId>
        <artifactId>byte-buddy-agent</artifactId>
        <version>1.14.16</version>
    </dependency>
</dependencies>

Our plan:

Mark the Target: We’ll create a custom @Monitor annotation to mark the methods we want to time.
Define the Action: We’ll create an “advice” class that holds the timing logic we want to inject.
Execute the Mission: We’ll tell Byte Buddy to find all methods marked with @Monitor and wrap them with our timing logic.

First, the @Monitor annotation. This can live in a separate shared JAR, but for simplicity, we’ll define it within the agent project.

package com.example.javaagent.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Monitor {
}

Next, our “advice”. This is the code that Byte Buddy will weave into the target methods. The @Advice annotations make this incredibly intuitive.

// In our Agent project
package com.example.javaagent;

import net.bytebuddy.asm.Advice;

public class TimerAdvice {

    @Advice.OnMethodEnter
    public static long onEnter() {
        // Executed at the start of the method
        return System.nanoTime();
    }

    @Advice.OnMethodExit
    public static void onExit(@Advice.Origin String method, @Advice.Enter long startTime) {
        // Executed at the end of the method
        long duration = System.nanoTime() - startTime;
        System.out.printf("Method '%s' executed in %d ns (%d ms)%n", method, duration, duration / 1_000_000);
    }
}

Finally, we update our premain method to put Byte Buddy to work.

// In our Agent project
package com.example.javaagent;

import com.example.javaagent.annotations.Monitor;
import net.bytebuddy.agent.builder.AgentBuilder;
import net.bytebuddy.asm.Advice;
import net.bytebuddy.matcher.ElementMatchers;

import java.lang.instrument.Instrumentation;

public class MyTimingAgent {

    public static void premain(String agentArgs, Instrumentation inst) {
        System.out.println("Starting our custom Java Agent...");

        new AgentBuilder.Default()
            .type(ElementMatchers.any()) // Look at any class
            .transform((builder, typeDescription, classLoader, module, protectionDomain) ->
                builder.method(ElementMatchers.isAnnotatedWith(Monitor.class)) // Find methods with our annotation
                       .intercept(Advice.to(TimerAdvice.class)) // Apply our advice
            ).installOn(inst);
            
        System.out.println("Agent installation complete.");
    }
}

This beautiful, fluent code is our mission directive. It tells Byte Buddy to find any method, anywhere, that has our @Monitor annotation and wrap it with the logic from TimerAdvice.

Attaching Agent To The Target Application

Now, let’s create a simple application to test our agent on. This is a completely separate project.

// In our Target Application project
import com.example.javaagent.annotations.Monitor;

public class MonitoredApp {

    @Monitor
    public void doWork() throws InterruptedException {
        System.out.println("--> Doing some important work...");
        Thread.sleep(200);
        System.out.println("--> Work finished.");
    }

    @Monitor
    public void doMoreWork() throws InterruptedException {
        System.out.println("--> Doing even more work...");
        Thread.sleep(500);
        System.out.println("--> More work finished.");
    }

    public void doUnmonitoredWork() {
        System.out.println("--> This work is not being monitored.");
    }

    public static void main(String[] args) throws InterruptedException {
        MonitoredApp app = new MonitoredApp();
        app.doWork();
        app.doMoreWork();
        app.doUnmonitoredWork();
    }
}

Notice how clean this is. The application code only knows about the @Monitor annotation. It has no idea its methods are about to be timed by an external agent.

The Grand Finale: Running with the Agent

Build the Agent: In your agent project, run mvn clean package. This creates your agent JAR (e.g., agent-1.0.jar).
Build the App: Compile your MonitoredApp.
Launch: Run the application using the -javaagent flag.

The Agent Manifest: Your License to Spy

The agent should have a manifest file where it is described. The manifest file (META-INF/MANIFEST.MF) is what tells the JVM how to handle your agent JAR. Here’s what it should contain:

Manifest-Version: 1.0
Premain-Class: com.example.javaagent.MyTimingAgent
Agent-Class: com.example.javaagent.MyTimingAgent
Can-Redefine-Classes: true
Can-Retransform-Classes: true
Boot-Classpath-Append: byte-buddy-1.14.16.jar

Key entries explained:

Premain-Class: The class containing the premain method for static attachment
Agent-Class: The class containing the agentmain method for dynamic attachment (optional for our example)
Can-Redefine-Classes: Allows the agent to redefine classes
Can-Retransform-Classes: Allows the agent to retransform classes that have already been loaded
Boot-Classpath-Append: Adds required dependencies to the bootstrap classpath

Maven will automatically generate this manifest when you build with the configuration we showed earlier in the pom.xml.

# Assuming agent JAR is in agent/target/ and app classes are in app/target/classes/
# Make sure the annotation JAR is also on the classpath if it's separate

java -javaagent:path/to/my-agent-1.0.jar \
     -cp path/to/target/application/classes:path/to/annotations.jar \
     MonitoredApp

When you hit enter, you’ll see the magic happen.

Agent deployed. Starting transformation...
Transformation complete. Agent is active.
--> Doing some important work...
--> Work finished.
Method 'public void MonitoredApp.doWork() throws java.lang.InterruptedException' took 202 ms
--> Doing even more work...
--> More work finished.
Method 'public void MonitoredApp.doMoreWork() throws java.lang.InterruptedException' took 503 ms
--> This work is not being monitored.
---
...

There it is. Our agent successfully intercepted the annotated methods and reported their execution time, proving that the “magic” of APM is well within your grasp. You’ve just built a foundational tool that professional engineers use to keep complex systems running smoothly.

Welcome to the world of Java instrumentation. The spy is in.

Day 89: When Your Singleton Isn't Really a Singleton (And How to Fix It)

2025-06-26T00:00:00Z

The Story Begins: When One Becomes Many

Imagine: You’re building a bank’s core system, and you need a logger that records every transaction. In your ideal world, this logger should be like that one reliable friend everyone turns to and there’s only one person and everyone knows where to find them.

You craft what seems like the perfect solution:

public class TransactionLogger {
    private static TransactionLogger instance;
    
    private TransactionLogger() {
        // Initialize expensive logging resources
        System.out.println("Logger initialized at: " + System.currentTimeMillis());
    }
    
    public static TransactionLogger getInstance() {
        if (instance == null) {
            instance = new TransactionLogger();
        }
        return instance;
    }
    
    public void log(String transaction) {
        System.out.println("LOG: " + transaction);
    }
}

This looks elegant, doesn’t it? One class, one instance, problem solved. But there’s a twist in our story—and it’s about to get interesting.

When Reality Strikes: The Race Condition Drama

Imagine our bank system goes live. Hundreds of customers are making transactions simultaneously. Multiple threads are calling getInstance() at the exact same moment. What happens next is like a scene from a comedy of errors:

Thread A: “Is instance null? Yes! I’ll create one.”
Thread B: “Is instance null? Yes! I’ll create one too.”
Thread C: “Is instance null? Still yes! Another one coming up.”

Suddenly, our “one and only” logger has siblings—multiple instances running around, each thinking they’re the chosen one. Our singleton has become a “multiple-ton,” and chaos ensues.

Let’s see this story unfold into code:

@Test
void demonstrateTheChaoticScenario() throws InterruptedException {
    int numberOfThreads = 100;
    Set<TransactionLogger> instances = ConcurrentHashMap.newKeySet();
    CountDownLatch latch = new CountDownLatch(numberOfThreads);
    
    // Launch a hundred threads simultaneously
    for (int i = 0; i < numberOfThreads; i++) {
        new Thread(() -> {
            instances.add(TransactionLogger.getInstance());
            latch.countDown();
        }).start();
    }
    
    latch.await();
    
    // The shocking revelation
    System.out.println("Expected: 1 instance, Actually got: " + instances.size());
    // You might see: "Expected: 1 instance, Actually got: 7" (or any number > 1)
}

The Heroes Enter: Thread-Safe Patterns to the Rescue

Now that we’ve seen the villain (race conditions) in action, let’s meet our heroes, various thread-safe singleton patterns, each with their own superpowers and weaknesses.

Hero #1: The Traffic Controller (Synchronized Method)

Our first hero is like a traffic controller at a busy intersection—only one car gets the green light at a time.

public class SynchronizedTransactionLogger {
    private static SynchronizedTransactionLogger instance;
    
    private SynchronizedTransactionLogger() {
        System.out.println("Synchronized logger created by: " + Thread.currentThread().getName());
    }
    
    public static synchronized SynchronizedTransactionLogger getInstance() {
        if (instance == null) {
            instance = new SynchronizedTransactionLogger();
        }
        return instance;
    }
}

The Good: Simple and foolproof. No matter how many threads arrive at the intersection, only one gets to proceed at a time.

The Not-So-Good: Here’s the catch—even after the construction work at the intersection is done and traffic should flow freely, our traffic controller keeps stopping every single car to check if construction is still ongoing. Every call to getInstance() waits for the red light, even when it’s completely unnecessary.

Think of it like this: after the first car creates the instance, every subsequent call still has to wait at the traffic light, like being stuck in a construction zone where the work finished hours ago but they forgot to remove the temporary traffic control.

Hero #2: The Eager Beaver (Eager Initialization)

Our second hero doesn’t wait for anyone. They show up to the party early and stay till the end.

public class EagerTransactionLogger {
    // Created immediately when class is loaded
    private static final EagerTransactionLogger instance = new EagerTransactionLogger();
    
    private EagerTransactionLogger() {
        System.out.println("Eager logger ready before anyone asked!");
    }
    
    public static EagerTransactionLogger getInstance() {
        return instance; // No checks needed, already there!
    }
}

The Good: Lightning fast access and completely thread-safe. The JVM’s class loader mechanism guarantees that static fields are initialized exactly once, before any thread can access the class.

The Not-So-Good: Like that friend who always arrives two hours early to every party, even the ones they might not attend. If your singleton is resource-heavy and might never be used, you’re paying the cost upfront whether you need it or not.

Hero #3: The Double Agent (Double-Checked Locking)

Our third hero is sophisticated—they have a two-step verification process that’s both secure and efficient.

public class DoubleCheckedTransactionLogger {
    // The volatile keyword is crucial here!
    private static volatile DoubleCheckedTransactionLogger instance;
    
    private DoubleCheckedTransactionLogger() {
        System.out.println("Double-checked logger created after careful verification");
    }
    
    public static DoubleCheckedTransactionLogger getInstance() {
        // First check - no synchronization needed if already created
        if (instance == null) {
            synchronized (DoubleCheckedTransactionLogger.class) {
                // Second check - inside synchronized block
                if (instance == null) {
                    instance = new DoubleCheckedTransactionLogger();
                }
            }
        }
        return instance;
    }
}

This pattern is like a smart security system:

First Guard: “Is there already someone inside? Yes? Go ahead!”
Second Guard: “Wait, let me double-check inside this secure room. Nope, still empty? Okay, you can enter.”

The Good: After initialization, accessing the instance is as fast as the eager approach. The first null check eliminates synchronization overhead for subsequent calls.

The Critical Detail: The volatile keyword isn’t just decoration—it’s essential! Without it, you might see a partially constructed object due to the way modern processors reorder instructions. It’s like ensuring everyone sees the same version of reality at the same time.

Hero #4: The Hidden Master (Initialization-on-Demand Holder)

Our fourth hero uses ancient Java wisdom—the power of class loading mechanics.

public class HolderTransactionLogger {
    private HolderTransactionLogger() {
        System.out.println("Holder logger created by the master of lazy loading");
    }
    
    // The secret weapon: a static inner class
    private static class LoggerHolder {
        private static final HolderTransactionLogger INSTANCE = new HolderTransactionLogger();
    }
    
    public static HolderTransactionLogger getInstance() {
        return LoggerHolder.INSTANCE; // Class loading magic happens here
    }
}

This is like having a wise mentor who only appears when you truly need them. The LoggerHolder class isn’t loaded until someone calls getInstance(), and when it is loaded, the JVM guarantees thread-safe initialization.

The Good: Lazy initialization without any explicit synchronization. It’s elegant, fast, and leverages the JVM’s built-in thread safety guarantees.

The Beautiful Part: No locks, no volatile keywords, no complex logic—just pure Java class loading mechanics doing the heavy lifting.

Hero #5: The Royal Guard (Enum Singleton)

Our final hero is royalty—they have built-in protection against all forms of attack.

public enum EnumTransactionLogger {
    INSTANCE;
    
    private EnumTransactionLogger() {
        System.out.println("Enum logger: Born to be unique!");
    }
    
    public void log(String transaction) {
        System.out.println("ROYAL LOG: " + transaction);
    }
    
    public void doSomething() {
        System.out.println("Performing singleton operations...");
    }
}

// Usage is simple and elegant
EnumTransactionLogger.INSTANCE.log("Transfer completed");

The Good:

Thread-safe by design
Immune to reflection attacks (try to break it, you can’t!)
Handles serialization correctly (no multiple instances even after deserialization)
Simple and clean syntax

The Limitation: Enums can’t extend other classes, which might limit your design flexibility in some scenarios.

The Ultimate Showdown: Choosing Your Champion

Let me tell you a story about choosing the right tool for the job. Imagine you’re a chef, and each singleton pattern is a different kitchen appliance:

Pattern	When to Use	Like Choosing…
Synchronized Method	Simple applications, low concurrency	A reliable old mixer - slow but dependable
Eager Initialization	Always-needed singletons, startup cost acceptable	A rice cooker - ready when you walk in
Double-Checked Locking	High performance needed, comfortable with complexity	A professional espresso machine - complex but perfect results
Holder Pattern	Most general cases	A Swiss Army knife - versatile and elegant
Enum Singleton	Maximum protection needed	A bank vault - unbreakable security

Testing Our Heroes: Proving They Work

Let’s put our patterns through their paces with a stress test that would make any singleton proud:

@Test
void stressTestAllSingletonPatterns() throws InterruptedException {
    testSingletonThreadSafety("Holder Pattern", HolderTransactionLogger::getInstance);
    testSingletonThreadSafety("Enum Pattern", () -> EnumTransactionLogger.INSTANCE);
    testSingletonThreadSafety("Synchronized", SynchronizedTransactionLogger::getInstance);
    testSingletonThreadSafety("Double-Checked", DoubleCheckedTransactionLogger::getInstance);
    testSingletonThreadSafety("Eager", EagerTransactionLogger::getInstance);
}

private <T> void testSingletonThreadSafety(String patternName, Supplier<T> instanceSupplier) 
    throws InterruptedException {
    
    int threadCount = 1000;
    Set<T> instances = ConcurrentHashMap.newKeySet();
    CountDownLatch latch = new CountDownLatch(threadCount);
 
    for (int i = 0; i < threadCount; i++) {
        new Thread(() -> {
            instances.add(instanceSupplier.get());
            latch.countDown();
        }).start();
    }
    
    latch.await();
    
    System.out.println(patternName + " - Instances created: " + instances.size());
    assertEquals(1, instances.size(), patternName + " should create only one instance");
}

The Moral of Our Story

In our journey through the land of thread-safe singletons, we’ve learned that the simple question “How do I create one instance?” has surprisingly complex answers in a multithreaded world.

The Wisdom I’ve Gained:

The naive approach fails - Race conditions are real and sneaky
Every solution has trade-offs - Performance vs. simplicity vs. features
The Holder Pattern is often the hero - Elegant, fast, and thread-safe
Enum singletons are the ultimate protection - When security matters most
Context matters - Choose based on your specific needs

A Final Thought:

Singletons are like that one friend everyone relies on—powerful when used correctly, but they can make your code harder to test and maintain. Sometimes, dependency injection frameworks offer better alternatives by managing object lifecycles for you.

Remember, the best singleton pattern is often the one you don’t need to write yourself. But when you do need one, now you have an arsenal of thread-safe techniques to choose from.

The next time someone asks you about thread-safe singletons, you won’t just give them code—you’ll tell them a story about race conditions, heroes, and the eternal quest for that perfect “one and only” instance in the chaotic world of multithreaded programming.

The Implementation Showcase

Here’s a complete working example that demonstrates all patterns in action:

public class SingletonShowcase {
    public static void main(String[] args) throws InterruptedException {
        System.out.println("=== Singleton Pattern Showcase ===");
        
        // Test each pattern
        demonstrateHolderPattern();
        demonstrateEnumPattern();
        demonstrateDoubleCheckedLocking();
        
        System.out.println("\n=== Thread Safety Test ===");
        performConcurrencyTest();
    }
    
    private static void demonstrateHolderPattern() {
        System.out.println("\n--- Holder Pattern ---");
        HolderTransactionLogger logger1 = HolderTransactionLogger.getInstance();
        HolderTransactionLogger logger2 = HolderTransactionLogger.getInstance();
        System.out.println("Same instance? " + (logger1 == logger2));
    }
    
    private static void demonstrateEnumPattern() {
        System.out.println("\n--- Enum Pattern ---");
        EnumTransactionLogger.INSTANCE.log("Testing enum singleton");
        System.out.println("Enum instances are always the same: " + 
            (EnumTransactionLogger.INSTANCE == EnumTransactionLogger.INSTANCE));
    }
    
    private static void demonstrateDoubleCheckedLocking() {
        System.out.println("\n--- Double-Checked Locking ---");
        DoubleCheckedTransactionLogger logger1 = DoubleCheckedTransactionLogger.getInstance();
        DoubleCheckedTransactionLogger logger2 = DoubleCheckedTransactionLogger.getInstance();
        System.out.println("Same instance? " + (logger1 == logger2));
    }
    
    private static void performConcurrencyTest() throws InterruptedException {
        int threadCount = 100;
        CountDownLatch latch = new CountDownLatch(threadCount);
        Set<HolderTransactionLogger> instances = ConcurrentHashMap.newKeySet();
        
        for (int i = 0; i < threadCount; i++) {
            new Thread(() -> {
                instances.add(HolderTransactionLogger.getInstance());
                latch.countDown();
            }).start();
        }
        
        latch.await();
        System.out.println("Concurrency test result - Unique instances: " + instances.size());
        System.out.println("Thread safety: " + (instances.size() == 1 ? "PASSED" : "FAILED"));
    }
}

And there you have it—your complete guide to thread-safe singletons, served with a side of storytelling and practical wisdom. May your instances be single, your threads be safe, and your code be elegant!

Day 88: Multilingual Audio Transcription with Gemini 1.5, Vertex AI, and Spring Boot

2025-04-29T00:00:00Z

As part of my ongoing Java explorations, I recently tackled a practical project that hit the sweet spot between business needs and cutting-edge tech. The challenge? Building a system to transcribe audio files across multiple languages with specific formatting requirements.

This wasn’t just about converting speech to text. The system needed to identify different speakers, handle six different languages, format numbers and dates properly, and flag sections that might need human review. Given these requirements, I decided to leverage Google Cloud’s Vertex AI with Gemini 1.5, all orchestrated through a Spring Boot application.

The Challenge: Beyond Simple Speech-to-Text

Most off-the-shelf transcription tools give you a wall of text and call it a day. Our requirements were much more nuanced:

Multilingual Support: The system had to handle English plus five other languages without missing a beat.
Speaker Diarization: We needed clear labels showing who was talking when (e.g., “Speaker A:”, “Speaker B:"), which is surprisingly hard to get right.
Specific Formatting: Each transcript needed timestamps at speaker changes and language-appropriate number/date formats.
Handling Imperfections: Real-world audio has issues - background noise, people talking over each other, mumbling. The system needed to handle these gracefully.
Quality Assessment: We needed some way to flag transcriptions that might need human review.

Architecture: A Spring Boot & Google Cloud Symphony

I built a workflow that looks something like this:

Audio Ingestion & Preparation: The backend receives audio files and converts them to FLAC format. I chose FLAC because it preserves audio quality while keeping file sizes manageable.
Cloud Storage: These FLAC files get uploaded to Google Cloud Storage. This step is crucial - it lets Gemini access potentially large audio files without timing out or hitting memory limits.
Vertex AI & Gemini 1.5: Our Spring Boot app calls Vertex AI, pointing Gemini to the audio file’s location. The magic happens in the prompt we send along with this request (more on that in a bit).
Processing & Storage: Once Gemini does its thing, we parse the response, add our own confidence scoring, and store everything in our database.
Notification/Feedback: For user-triggered transcriptions, we send back success/failure notifications.

Using GCS as the middleman was a bit of extra work, but it paid off by making the system more robust when handling larger files.

Harnessing Gemini 1.5

Gemini 1.5’s massive context window and multimodal capabilities made it perfect for handling audio files directly via GCS URIs.

Prompt Engineering for Precision

This was the trickiest part of the whole project. Just saying “hey, transcribe this” wasn’t going to cut it. After many iterations, I landed on this prompt structure:

Please accurately transcribe this audio recording with high attention to detail. %1$s is the preferred language if specified.

I need a professional-quality transcript that captures the following elements:

Language Detection and Handling:
1. If language code is provided ([Language code]):
   - Use this as the primary transcription language
2. If no language code is provided:
   - Detect the spoken language from the audio
   - Transcribe in the detected language
   - Include the detected language code in the response

Formatting Requirements:
- Include timestamps at every speaker change
- Label speakers as "Speaker A:", "Speaker B:", etc.
- Use appropriate number formatting for the detected/specified language
- Format dates as DD.MM.YYYY

Language-Specific Guidelines:
[Language code]

Special Instructions:
- Mark unclear speech with [inaudible]
- For overlapping speech, prioritize the main speaker
- Ignore background noise unless relevant

This prompt spells out exactly what we need:

The target language (dynamically inserted at runtime)
How to format timestamps, speaker labels, numbers, and dates
Clear instructions for handling tricky situations like unclear speech

Navigating Safety Settings

I hit an unexpected roadblock with Vertex AI’s default safety settings. They’re designed to prevent harmful content generation, but in our case, they sometimes flagged legitimate business conversations containing certain keywords.

After some trial and error, I identified which safety categories we could safely disable for our specific use case. This required careful consideration - we needed the full, unfiltered transcription, but we were working with known audio sources in a controlled environment.

Measuring Confidence: A Pragmatic Approach

One challenge with LLMs is they don’t give you a simple “I’m 87% confident in this transcription” score. However, Gemini does return log probabilities (avg_logprobs) for the generated tokens, which provide some insight into the model’s internal confidence.

I cobbled together a basic confidence scoring system:

Extract the avg_logprobs from the API response
Set a threshold based on experimentation (around -0.4)
If the average log probability falls below this threshold, flag that transcript for human review

It’s not perfect, but it gave us a practical way to identify potentially problematic transcriptions that might need a second pair of eyes.

Implementation: Async vs. Batch Processing

To handle different use cases, I implemented two processing modes:

Asynchronous Processing: For user-triggered transcriptions, we process things in the background using Spring’s @Async annotations. The user gets an immediate acknowledgment, and we notify them when the job completes.
Batch Processing: For processing backlogs of audio files, I built a scheduled job using Spring’s @Scheduled annotation. This runs during off-hours, picking up unprocessed files and working through them methodically.

    public static List<SafetySetting> getCustomSafetySettings() {
        final List<SafetySetting> safetySettings = new ArrayList<>();
        safetySettings.add(SafetySetting.newBuilder()
                .setCategory(HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT)
                .setThreshold(SafetySetting.HarmBlockThreshold.BLOCK_NONE)
                .build());
        safetySettings.add(SafetySetting.newBuilder()
                .setCategory(HarmCategory.HARM_CATEGORY_HARASSMENT)
                .setThreshold(SafetySetting.HarmBlockThreshold.BLOCK_NONE)
                .build());
        safetySettings.add(SafetySetting.newBuilder()
                .setCategory(HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT)
                .setThreshold(SafetySetting.HarmBlockThreshold.BLOCK_NONE)
                .build());
        safetySettings.add(SafetySetting.newBuilder()
                .setCategory(HarmCategory.HARM_CATEGORY_HATE_SPEECH)
                .setThreshold(SafetySetting.HarmBlockThreshold.BLOCK_NONE)
                .build());
        safetySettings.add(SafetySetting.newBuilder()
                .setCategory(HarmCategory.HARM_CATEGORY_UNSPECIFIED)
                .setThreshold(SafetySetting.HarmBlockThreshold.BLOCK_NONE)
                .build());
        return safetySettings;
    }

    private SpeechToTextInfo transcribeAudioWithGeminiSync(final String gcsUri,
                                                           final SpeechToTextInfo pendingInfo) {
        try {
            log.debug("Transcribing audio synchronously with Gemini for callId: {} and recordingId: {}",
                    pendingInfo.getCallId(), pendingInfo.getRecordId());

            final GenerativeModel model = new GenerativeModel(modelName, vertexAI);
            model.withSafetySettings(getCustomSafetySettings());

            final GenerateContentResponse response = model.generateContent(
                    ContentMaker.fromMultiModalData(
                            buildPrompt(""),
                            PartMaker.fromMimeTypeAndData("audio/flac", gcsUri)
                    ));

            final ImmutableGeminiSpeechToTextTranscriptInfo.Builder transcriptInfoBuilder =
                    ImmutableGeminiSpeechToTextTranscriptInfo.builder();

            final double avgLogProbs = response.getCandidates(0).getAvgLogprobs();
            transcriptInfoBuilder.hasAcceptableConfidence(avgLogProbs >= CONFIDENCE_THRESHOLD)
                    .avgLogProbs(avgLogProbs);

            final String transcript = ResponseHandler.getText(response);
            final SpeechToTextInfo completedInfo = SpeechToTextInfo.from(pendingInfo)
                    .setTranscript(transcript)
                    .setStatus(SpeechToTextState.success)
                    .setTranscriptsInfo(ImmutableList.of(transcriptInfoBuilder.build()))
                    .build();

            // save into db
            return completedInfo;

        } catch (final Exception e) {
            log.error("Failed to transcribe audio synchronously for callId: {}",
                    pendingInfo.getCallId(), e);
            final SpeechToTextInfo failedInfo = SpeechToTextInfo.from(pendingInfo)
                    .setStatus(SpeechToTextState.failed)
                    .build();
            // save into db
            return failedInfo;
        }
    }

    private void transcribeAudioWithGemini(final String gcsUri, final String language,
                                           final SpeechToTextInfo pendingInfo) {
        try {
            log.debug("Transcribing audio with Gemini for callId: {} and recordingId: {}",
                    pendingInfo.getCallId(), pendingInfo.getRecordId());

            final GenerativeModel model = new GenerativeModel(modelName, vertexAI);
            model.withSafetySettings(getCustomSafetySettings());

            final ApiFuture<GenerateContentResponse> response = model.generateContentAsync(
                    ContentMaker.fromMultiModalData(
                            buildPrompt(language),
                            PartMaker.fromMimeTypeAndData("audio/flac", gcsUri)
                    ));

            log.debug("Transcribing audio with Gemini for callId: {} and recordingId: {} and response {}",
                    pendingInfo.getCallId(), pendingInfo.getRecordId(), response);
            ApiFutures.addCallback(response, new ApiFutureCallback<GenerateContentResponse>() {
                @Override
                public void onSuccess(final GenerateContentResponse result) {
                    log.debug("Transcribing audio with Gemini for callId: {} and recordingId: {} and result {}",
                            pendingInfo.getCallId(), pendingInfo.getRecordId(), result);
                    processTranscription(result, pendingInfo);
                }

                @Override
                public void onFailure(final Throwable t) {
                    handleTranscriptionFailure(pendingInfo, t);
                }
            }, MoreExecutors.directExecutor());
        } catch (final Exception e) {
            handleTranscriptionFailure(pendingInfo, e);
        }
    }

Learnings and Final Thoughts

This project taught me a ton about applying LLMs to practical business problems. My key takeaways:

Gemini 1.5 is a beast for these kinds of tasks, especially when working with audio through GCS integration.
Prompt engineering makes or breaks you. The difference between a useless transcript and a perfect one often comes down to how clearly you communicate your requirements.
Safety settings matter. Understanding what they do and how to configure them for your specific use case is crucial.
Imperfect signals can still be useful. Even though avg_logprobs isn’t a perfect confidence metric, it gave us a practical way to implement human-in-the-loop review.
Spring Boot’s flexibility shines when implementing both async and batch processing patterns to handle different use cases.

Wrangling all these technologies together was challenging but incredibly satisfying. There’s something deeply rewarding about seeing a complex system like this come together to solve a real business problem.

Day 87: Java's Environment Variable Paradox: Easy to Read, Impossible to Change?

2025-03-26T00:00:00Z

Have you ever needed to access or modify environment variables in your Java application? If you’re like me, you’ve probably reached for System.getenv() to read variables, but then scratched your head wondering how to update them.

In today’s post, I’ll dive into environment variables in Java 21 - something I’ve been playing with recently. We’ll look at how to read them (the easy part) and explore different approaches to modify them (the not-so-easy part).

TLDR

Java makes reading env variables easy (System.getenv()), but modifying them is restricted

Four options for modification:

ProcessBuilder for child processes only
JNA for native system function access
Reflection hacks (avoid in production!)
Native OS commands (setx/export)
Best practice: Load env variables at startup rather than modifying at runtime

What are Environment Variables anyway?

Before jumping into code, let’s take a step back. Environment variables are basically key-value pairs that live outside your application. They’re part of the environment in which your process runs.

I like to think of them as a global configuration that follows your application around. They’re incredibly useful for things like:

Storing database connection strings (so they’re not hardcoded in your app)
Setting up API keys (without exposing them in your code repository)
Configuring different behavior across environments (dev/staging/prod)
Storing system paths and user information

If you’re working with containerized applications or microservices, you’re probably already using environment variables extensively.

Reading Environment Variables in Java

Let’s start with the easy part - reading environment variables. Java provides a couple of straightforward methods for this.

The Classic System.getenv() Approach

This is the method I use :

import java.util.Map;

public class EnvReader {
    public static void main(String[] args) {
        // Get a specific variable
        String path = System.getenv("PATH");
        System.out.println("My PATH is: " + path);
        
        // Or get all environment variables at once
        Map<String, String> env = System.getenv();
        System.out.println("All my environment variables:");
        env.forEach((key, value) -> System.out.println(key + ": " + value));
    }
}

Simple and effective! You can either get a specific variable by name or grab all of them as a Map.

Using ProcessBuilder for Environment Access There’s another approach using ProcessBuilder that I find useful, especially when working with subprocesses:

import java.util.Map;

public class ProcessBuilderEnvReader {
    public static void main(String[] args) {
        ProcessBuilder processBuilder = new ProcessBuilder();
        Map<String, String> environment = processBuilder.environment();
        
        System.out.println("My environment variables via ProcessBuilder:");
        environment.forEach((key, value) -> System.out.println(key + " = " + value));
    }
}

The nice thing about ProcessBuilder is that you can modify this environment map for any subprocesses you launch - more on that shortly.

The Tricky Part: Modifying Environment Variables

Now comes the challenging part. Unlike reading environment variables, Java doesn’t provide direct methods to modify them in the current process. This is actually by design for security reasons.

However, there are several workarounds we can use. Let’s explore them.

Approach 1: Modifying Environment for Child Processes

This is the most straightforward approach. While you can’t change the current process’s environment, you can set environment variables for any child processes you launch:

import java.io.IOException;

public class EnvSetterForChildProcess {
    public static void main(String[] args) {
        try {
            ProcessBuilder pb = new ProcessBuilder("java", "-version");
            
            // Here's where the magic happens
            pb.environment().put("MY_CUSTOM_VAR", "Hello from parent!");
            
            Process process = pb.start();
            int exitCode = process.waitFor();
            System.out.println("Process finished with exit code: " + exitCode);
            
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

The limitation? This only affects the child process, not your current JVM or the system as a whole.

Approach 2: Using JNA (Java Native Access)

For more control, sometimes we should look into JNA, which lets you access native system functions:

import com.sun.jna.Library;
import com.sun.jna.Native;
import com.sun.jna.Platform;

public class JNAEnvSetter {
    // Interface to C library functions
    public interface CLibrary extends Library {
        CLibrary INSTANCE = Native.load(Platform.isWindows() ? "msvcrt" : "c", CLibrary.class);
        int setenv(String name, String value, int overwrite);
        int unsetenv(String name);
    }
    
    public static void main(String[] args) {
        // Set an environment variable
        int result = CLibrary.INSTANCE.setenv("MY_ENV_VAR", "my_value", 1);
        
        if (result == 0) {
            System.out.println("Environment variable set successfully");
            
            // Verify by reading it back
            String value = System.getenv("MY_ENV_VAR");
            System.out.println("MY_ENV_VAR: " + value);
        } else {
            System.out.println("Failed to set environment variable");
        }
    }
}

Remember to add JNA to your project dependencies if you want to try this approach.

Approach 3: The Reflection Hack (Use with Caution!)

I’ve seen this approach used, but I generally don’t recommend it for production code. It uses reflection to modify the private environment map:

import java.lang.reflect.*;
import java.util.Map;

public class ReflectionEnvSetter {
    @SuppressWarnings("unchecked")
    public static void main(String[] args) {
        try {
        // Attempt to update environment variables via ProcessEnvironment fields.
        Class<?> processEnvironmentClass = Class.forName("java.lang.ProcessEnvironment");
        Field envField = processEnvironmentClass.getDeclaredField("theEnvironment");
        envField.setAccessible(true);
        Map<String, String> env = (Map<String, String>) envField.get(null);
        env.putAll(newEnv);
        
        // Try to update the case-insensitive environment as well, if present.
        try {
            Field ciEnvField = processEnvironmentClass.getDeclaredField("theCaseInsensitiveEnvironment");
            ciEnvField.setAccessible(true);
            @SuppressWarnings("unchecked")
            Map<String, String> ciEnv = (Map<String, String>) ciEnvField.get(null);
            ciEnv.putAll(newEnv);
        } catch (NoSuchFieldException nsfe) {
            // Field not present on this system (e.g., non-Windows), ignore.
        }
    } catch (ClassNotFoundException | NoSuchFieldException | IllegalAccessException e) {
        // Fallback: Modify the unmodifiable map returned by System.getenv()
        try {
            Map<String, String> sysEnv = System.getenv();
            // Use reflection to access the internal modifiable map
            Field field = sysEnv.getClass().getDeclaredField("m");
            field.setAccessible(true);
            Map<String, String> modifiableEnv = (Map<String, String>) field.get(sysEnv);
            modifiableEnv.putAll(newEnv);
        } catch (Exception ex) {
            throw new RuntimeException("Failed to set environment variables", ex);
        }
    }
    }
}

Why don’t I recommend this? It’s:

Not guaranteed to work across JVM implementations
May behave differently in future Java versions
May lead to unexpected behavior or security issues

I’ve seen it not work properly so proceed with caution!

Approach 4: Native OS Commands

Sometimes the simplest approach is to just execute the appropriate OS command:

import java.io.IOException;

public class NativeEnvSetter {
    public static void main(String[] args) {
        try {
            ProcessBuilder processBuilder;
            
            if (System.getProperty("os.name").toLowerCase().contains("windows")) {
                // Windows way
                processBuilder = new ProcessBuilder("cmd", "/c", "setx", "MY_ENV_VAR", "my_value");
            } else {
                // Unix/Linux/Mac way
                processBuilder = new ProcessBuilder("/bin/sh", "-c", "export MY_ENV_VAR=my_value");
            }
            
            Process process = processBuilder.start();
            int exitCode = process.waitFor();
            
            System.out.println("Command executed with exit code: " + exitCode);
            
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

On Windows, setx creates a persistent environment variable. On Unix-like systems, export sets it for the current shell session, but it won’t persist across sessions unless you add it to your profile files.

Removing Environment Variables

Removing environment variables follows similar patterns to creating/updating them:

For Child Processes

1
2

ProcessBuilder pb = new ProcessBuilder("java", "-version");
pb.environment().remove("MY_CUSTOM_VAR");

Using JNA

`1`	`int result = JNAEnvSetter.CLibrary.INSTANCE.unsetenv("MY_ENV_VAR");`

Using OS Commands

// For Windows
ProcessBuilder pb = new ProcessBuilder(
    "cmd", "/c", 
    "REG DELETE \"HKCU\\Environment\" /V MY_ENV_VAR /f"
);

// For Unix/Linux/Mac
ProcessBuilder pb = new ProcessBuilder(
    "/bin/sh", "-c", 
    "unset MY_ENV_VAR"
);

Putting It All Together: A Practical Environment Manager

Let me wrap this up with a complete environment variable manager class that you might find useful in your projects:

import java.io.IOException;
import java.util.Map;
import java.util.Optional;

public class EnvironmentManager {
    
    /**
     * Read a specific environment variable
     */
    public static Optional<String> read(String name) {
        return Optional.ofNullable(System.getenv(name));
    }
    
    /**
     * Read all environment variables
     */
    public static Map<String, String> readAll() {
        return System.getenv();
    }
    
    /**
     * Set an environment variable for child processes
     */
    public static boolean setForChildProcesses(String name, String value) {
        ProcessBuilder processBuilder = new ProcessBuilder();
        processBuilder.environment().put(name, value);
        return true;
    }
    
    /**
     * Set a system-wide environment variable
     */
    public static boolean setSystemwide(String name, String value) {
        try {
            ProcessBuilder processBuilder;
            
            if (isWindows()) {
                processBuilder = new ProcessBuilder("cmd", "/c", "setx", name, value);
            } else {
                String command = String.format("export %s=\"%s\" && echo \"export %s=%s\" >> ~/.profile", 
                                             name, value, name, value);
                processBuilder = new ProcessBuilder("/bin/sh", "-c", command);
            }
            
            Process process = processBuilder.start();
            int exitCode = process.waitFor();
            return exitCode == 0;
            
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
            return false;
        }
    }
    
    /**
     * Delete an environment variable system-wide
     */
    public static boolean delete(String name) {
        try {
            ProcessBuilder processBuilder;
            
            if (isWindows()) {
                processBuilder = new ProcessBuilder(
                    "cmd", "/c", 
                    "REG DELETE \"HKCU\\Environment\" /V " + name + " /f"
                );
            } else {
                String command = String.format("unset %s && sed -i '/export %s=/d' ~/.profile", name, name);
                processBuilder = new ProcessBuilder("/bin/sh", "-c", command);
            }
            
            Process process = processBuilder.start();
            int exitCode = process.waitFor();
            return exitCode == 0;
            
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
            return false;
        }
    }
    
    private static boolean isWindows() {
        return System.getProperty("os.name").toLowerCase().contains("windows");
    }
}

Day 86: Building a Secure Java Sandbox with Custom Class Loaders, Process isolation and Java Platform Module System – Executing JAR and .java Files Safely

2025-03-12T00:00:00Z

As software engineers we sometimes have to execute some arbitary code that we found or some jar in (Java) case to figure out what its doing. But copy pasting some code in a system directly is a poor security practice thus having a sandbox environment is a powerful tool for ensuring code isolation, enabling secure execution by restricting access to core libraries and system resources. This blog walks through creating a robust sandbox environment in Java using custom class loaders and security policies—tools that are especially valuable for those working on plugins, user-generated scripts, or controlled environments for evaluating code.

The Basics of Java Sandboxing

Sandboxing in Java involves creating a restricted environment where code can execute safely, isolated from the rest of the system. It allows developers to control which resources are accessible, monitor the classes being loaded, and intercept potentially malicious behaviors. Key components in sandboxing include:

Class Loaders: Responsible for loading classes into the JVM, custom class loaders enable control over which classes and packages can be accessed.
Security Policies: Define the permissions granted to loaded code, restricting access to system properties, file systems, network resources, and other sensitive areas.

Modern Java Sandboxing Approaches

As of Java 21, there are several approaches to implement secure sandboxing:

Java Platform Module System (JPMS) - Using strong encapsulation
Process Isolation - Running untrusted code in separate JVM processes
Custom ClassLoaders with Resource Limits - Our focus for this article

System Architecture

┌────────────────────┐
│    Client Code     │
└─────────┬──────────┘
          │
┌─────────▼──────────┐
│   Sandbox Runner   │
├───────────────────-┤
│ - Resource Limits  │
│ - Class Validation │
│ - Access Control   │
└─────────┬──────────┘
          │
┌─────────▼──────────┐
│  Custom ClassLoader │
└────────────────────┘

Implementing the Custom Class Loader

Our custom class loader, SandboxClassLoader, extends URLClassLoader and overrides the loadClass method to control which classes can be loaded. This ensures that only classes from allowed packages are accessible.

// filepath: SandboxConfiguration.java
public record SandboxConfiguration(
    Set<String> allowedPackages,
    long maxMemoryBytes,
    Duration timeout,
    Path tempDirectory
) {
    public static SandboxConfiguration getDefault() {
        return new SandboxConfiguration(
            Set.of("java.lang.", "java.util.", "java.math."),
            10_000_000L, // 10MB
            Duration.ofSeconds(5),
            Path.of(System.getProperty("java.io.tmpdir"), "sandbox")
        );
    }
}

// filepath: ModernSandbox.java
public class ModernSandbox implements AutoCloseable {
    private final SandboxConfiguration config;
    private final Path tempDir;
    private final List<String> executionLog;

    public ModernSandbox(SandboxConfiguration config) {
        this.config = config;
        this.tempDir = createTempDirectory();
        this.executionLog = new ArrayList<>();
    }

    public ExecutionResult runCode(String sourceCode) {
        try {
            // Compile code
            URL[] urls = compileSource(sourceCode);
            
            // Run in controlled environment
            return ProcessBuilder pb = new ProcessBuilder(
                "java",
                "-Xmx" + config.maxMemoryBytes(),
                "--add-opens", "java.base/java.lang=ALL-UNNAMED",
                "-cp", tempDir.toString(),
                "UntrustedCode"
            );

            // Add timeout control
            Process process = pb.start();
            boolean completed = process.waitFor(
                config.timeout().toMillis(), 
                TimeUnit.MILLISECONDS
            );

            return new ExecutionResult(
                completed,
                process.exitValue(),
                readOutput(process)
            );

        } catch (Exception e) {
            return new ExecutionResult(false, -1, e.getMessage());
        }
    }

    @Override
    public void close() {
        // Cleanup temp files
        FileUtils.deleteDirectory(tempDir.toFile());
    }
}

This policy restricts the code from performing any unauthorized actions, such as accessing the file system or network, by granting only the permissions explicitly added.

Running Code in the Sandbox

With the custom class loader and security policy in place, we can now execute untrusted code securely.

import java.lang.reflect.Method;
import java.net.URL;

public class SandboxRunner {
    public static void main(String[] args) {
        // Set the security manager and policy
        System.setSecurityManager(new SecurityManager());
        Policy.setPolicy(new SandboxSecurityPolicy());

        String sourceCode = """
            public class UntrustedCode {
                public static void main(String[] args) {
                    System.out.println("Hello from untrusted code!");
                }
            }
            """;

        try {
            // Compile the source code
            URL[] classUrls = SandboxUtil.compileSource(sourceCode, "UntrustedCode");

            // Create the sandbox class loader
            SandboxClassLoader sandboxClassLoader = new SandboxClassLoader(classUrls);

            // Load and run the untrusted class
            Class<?> untrustedClass = Class.forName("UntrustedCode", true, sandboxClassLoader);
            Method mainMethod = untrustedClass.getMethod("main", String[].class);
            mainMethod.invoke(null, (Object) new String[]{});

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

This SandboxRunner class sets up the security manager and policy, compiles the untrusted code, loads it using the SandboxClassLoader, and invokes its main method.

Testing the Sandbox

Let’s test the sandbox with code that should be allowed and code that should be restricted.

// filepath: ModernSandboxTest.java
class ModernSandboxTest {
    @Test
    void shouldRestrictFileSystemAccess() {
        String maliciousCode = """
            public class UntrustedCode {
                public static void main(String[] args) throws Exception {
                    new java.io.File("/tmp/evil.txt").createNewFile();
                }
            }
            """;
            
        try (ModernSandbox sandbox = new ModernSandbox(SandboxConfiguration.getDefault())) {
            ExecutionResult result = sandbox.runCode(maliciousCode);
            assertFalse(result.successful());
            assertTrue(result.output().contains("SecurityException"));
        }
    }
}

Real-World Applications

Online IDEs: Running user-submitted code safely
Plugin Systems: Loading third-party extensions
Educational Platforms: Executing student assignments
Code Interview Platforms: Running candidate solutions

Performance Considerations

Process creation: ~100ms overhead
Memory usage: Configurable per instance
Compilation time: ~50ms for simple classes

Conclusion

This sandbox implementation provides:

Process isolation for maximum security
Configurable resource limits
Automatic cleanup of temporary files
Comprehensive error handling
Support for both source files and JARs

Perfect for applications requiring secure execution of untrusted code in production environments.

Day 85: Idempotent APIs in Java: Concepts, Implementation Strategies, and a Spring Boot File Upload Implementation

2025-01-02T00:00:00Z

Idempotency is a reliable way of building robust API, particularly in distributed systems where retries and network failures are common. This blog explores the concept of idempotency and multiple ways to implement it using a Spring Boot file upload service, ensuring no duplicate uploads occur.

What You’ll Learn

The Concept of Idempotency and why it matters in API design.
Different Approaches to Implementing Idempotency in Spring Boot.
A Practical File Upload Service showcasing these approaches.
Best Practices, Pitfalls, and Optimization Tips for idempotent APIs.

Key Takeaways

Idempotency Prevents Duplicates: It ensures reliable APIs, handling retries without creating duplicate files.
Choose the Right Strategy: Options like Idempotency Keys, Content Hashing, or a combination offer flexibility for various use cases.
Content Hashing Simplifies Deduplication: Hashing automates duplicate detection but requires more compute for large files.
Combine for Reliability: Pairing Idempotency Keys with Content Hashing is robust and handles client errors effectively.
Follow Best Practices: Use strong hashing algorithms, set expiration for keys, and test thoroughly to build resilient APIs.

Apply these principles to create efficient, user-friendly, and reliable file upload services.

The Problem: Why Idempotency Matters in File Uploads

Imagine a scenario where a user uploads a file to your server, but due to network issues, they retry the same request multiple times. Without idempotency, your server might save the same file multiple times, leading to:

Wasted Storage: Duplicate files unnecessarily consume storage.
Inconsistent State: Multiple records for the same file can cause confusion.
User Frustration: Users might see duplicate entries in their file history.

To address this, an idempotent API ensures that repeated uploads of the same file result in only one stored copy.

Approaches to Implementing Idempotency in Spring Boot

Here are four different strategies to implement idempotency for a file upload service in Spring Boot:

1. Idempotency Key-Based Deduplication

How It Works:

Clients include a unique X-Idempotency-Key header with each request.
The server stores this key alongside the uploaded file’s metadata.
If a request with the same key is received again, the server returns the already-stored file’s response instead of reprocessing the upload.

Implementation Steps:

Store the idempotencyKey in a database table.
Before processing a new upload, check if the key already exists.
If the key exists, return the corresponding file metadata.

Code Example:

public FileRecord uploadFile(String idempotencyKey, MultipartFile file) throws IOException {
    return fileRecordRepository.findByIdempotencyKey(idempotencyKey)
            .orElseGet(() -> {
                String fileHash = DigestUtils.md5Hex(file.getInputStream());
                FileRecord fileRecord = new FileRecord();
                fileRecord.setFilename(file.getOriginalFilename());
                fileRecord.setFileHash(fileHash);
                fileRecord.setIdempotencyKey(idempotencyKey);
                return fileRecordRepository.save(fileRecord);
            });
}

Pros:

Simple and effective.
Works well in systems where clients can reliably generate unique keys.

Cons:

Relies on client cooperation to generate unique keys.
Requires storage and lookup of keys on the server side.

2. Content Hashing for Deduplication

How It Works:

The server generates a hash (e.g., MD5 or SHA-256) of the file content.
Before saving the file, the server checks if a file with the same hash already exists.
If a match is found, the server rejects the upload or returns the existing file’s metadata.

Implementation Steps:

Generate a hash of the file’s content.
Store the hash in the database alongside the file metadata.
Check for hash collisions before processing new uploads.

Code Example:

String fileHash = DigestUtils.md5Hex(file.getInputStream());
fileRecordRepository.findByFileHash(fileHash).ifPresent(existing -> {
    throw new RuntimeException("Duplicate file upload detected.");
});

Pros:

Automatic deduplication based on file content.
No reliance on client behavior.

Cons:

Computational overhead for hashing large files.
Collisions are rare but theoretically possible (depending on the hashing algorithm).

3. Combination of Idempotency Key and Content Hash

How It Works:

Combines the strengths of both strategies.
Clients provide an X-Idempotency-Key, but the server also validates file uniqueness using content hashing.

Implementation Steps:

Check for the idempotencyKey in the database.
If not found, compute the file hash and check for duplicates.
Save both the idempotencyKey and file hash in the database.

Code Example:

public FileRecord uploadFile(String idempotencyKey, MultipartFile file) throws IOException {
    return fileRecordRepository.findByIdempotencyKey(idempotencyKey)
            .orElseGet(() -> {
                String fileHash = DigestUtils.md5Hex(file.getInputStream());
                fileRecordRepository.findByFileHash(fileHash).ifPresent(existing -> {
                    throw new RuntimeException("Duplicate file upload detected.");
                });
                FileRecord newRecord = new FileRecord();
                newRecord.setIdempotencyKey(idempotencyKey);
                newRecord.setFileHash(fileHash);
                return fileRecordRepository.save(newRecord);
            });
}

Pros:

Robust against client errors (e.g., duplicate idempotency keys).
Guarantees no duplicate files.

Cons:

Adds complexity and slightly more overhead.

4. Token-Based Deduplication

How It Works:

After a successful upload, the server issues a token (e.g., a UUID or file hash).
Clients must include this token in subsequent uploads to reference the original file.
If the token is valid, the server skips the upload and returns the original file’s response.

Implementation Steps:

Generate a token after the first successful upload.
Store the token alongside the file metadata.
Require clients to include the token in subsequent requests.

Code Example:

public FileRecord uploadFileWithToken(String token, MultipartFile file) throws IOException {
    if (fileRecordRepository.existsByToken(token)) {
        throw new RuntimeException("Duplicate upload detected.");
    }
    String fileHash = DigestUtils.md5Hex(file.getInputStream());
    FileRecord newRecord = new FileRecord();
    newRecord.setToken(token);
    newRecord.setFileHash(fileHash);
    return fileRecordRepository.save(newRecord);
}

Pros:

Offloads responsibility for deduplication to the client.
Reduces server-side storage requirements for idempotency keys.

Cons:

Potentially less user-friendly, as clients must manage tokens.

Choosing the Right Approach

The best strategy depends on your application’s requirements:

Criteria	Idempotency Key	Content Hash	Key + Hash	Token
Client Cooperation Needed	Yes	No	Partial	Yes
Storage Efficiency	Moderate	High	Moderate	High
Computational Overhead	Low	Medium	Medium	Low
Robustness Against Duplicates	Moderate	High	High	High

Best Practices for Idempotent File Uploads

Use Strong Hashing Algorithms: Prefer SHA-256 over MD5 for better collision resistance.
Set Expiry for Idempotency Keys: To avoid unbounded growth in storage, set a TTL (time-to-live) for keys.
Test for Edge Cases: Simulate network failures and retries during testing.
Provide Clear Error Messages: Inform clients why a request was rejected (e.g., duplicate file detected).

Conclusion

Idempotency is a critical design principle for modern APIs, ensuring consistency and reliability in distributed systems. By carefully choosing an implementation strategy—such as idempotency keys, content hashing, or a combination—you can build robust file upload services that prevent duplicate uploads and enhance user experience.

Next Steps:

Experiment with the provided code examples.
Explore additional use cases for idempotency (e.g., payment processing).
Dive deeper into hashing algorithms and database optimization for production-grade systems.

By implementing idempotency in your Spring Boot applications, you can create resilient and user-friendly services that handle the challenges of distributed systems gracefully.

Day 84: Hot Class Reload in Java – A Webpack HMR-like Experience for Java Developers

2024-10-04T00:00:00Z

In the world of software development, time is everything. Every developer knows the frustration of waiting for a full application restart just to see a small change take effect. Java developers, in particular, have long dealt with this issue. But what if you didn’t have to stop and restart every time you updated a class? Enter Hot Class Reload (HCR) in Java—a technique that can keep you in the flow, reloading classes on the fly, much like Hot Module Reload (HMR) does in JavaScript.

In this guide, we’ll walk through how to implement HCR and integrate it into your Java development workflow. By the end, you’ll have a powerful new tool to cut down on those long, unproductive restart times.

Understanding Hot Class Reload

Simply put, Hot Class Reload (HCR) allows Java applications to reload classes at runtime. This is incredibly useful in development environments where you’re constantly iterating and tweaking code. Think of it as real-time editing: you change some code, the application picks it up right away—no restart required.

Hot Class Reload (HCR) is a technique that enables Java applications to reload classes at runtime. This approach is particularly useful in development environments where frequent code changes occur. By leveraging Java’s WatchService, custom class loaders using the javax.tools api and JavaCompiler class we can monitor source files for changes, compile them on-the-fly, and reload the updated classes into the running application.

How It Works

The core components of our HCR implementation include:

File Watcher: Utilizes Java’s WatchService to monitor a directory for changes to .java files.
Dynamic Compilation: Uses javax.tools.JavaCompiler to compile modified Java source files.
Custom Class Loader: Loads the newly compiled classes into the JVM, replacing the old versions.

System Flow Diagram

Below is a simplified flow diagram illustrating the HCR process:

Source Changes: Developers modify Java source files in the specified directory.
File Watcher: Detects changes and triggers the compilation process.
Compile & Reload: Compiles the modified files and reloads the classes using a custom class loader.
Custom Class Loader: Loads the newly compiled class into the jvm.
Invoke Main Method: Exectues the main method by executing the bytecode of the reloaded class.

Implementing Hot Class Reload

Here’s a breakdown of the Java program implementing HCR:

Setting Up the Environment

The program initializes by setting up directories for source and compiled classes. It ensures these directories exist and are ready for use.

public HotReload(String sourceDir, String classDir) {
    this.sourceDir = Paths.get(sourceDir).toAbsolutePath();
    this.classDir = Paths.get(classDir).toAbsolutePath();
    this.classLoader = new CustomClassLoader();
    this.compiler = ToolProvider.getSystemJavaCompiler();
    this.fileManager = compiler.getStandardFileManager(null, null, null);

    // Ensure directories exist
    try {
        Files.createDirectories(this.sourceDir);
        Files.createDirectories(this.classDir);
    } catch (IOException e) {
        throw new RuntimeException("Failed to create directories", e);
    }
}

The constructor begins by converting the provided sourceDir and classDir strings into absolute Path objects using Paths.get().toAbsolutePath(). This ensures that the paths are fully qualified and can be used reliably throughout the application. Next, it initializes the classLoader as an instance of the CustomClassLoader class, which is responsible for dynamically loading compiled classes. The compiler is set to the system Java compiler obtained from ToolProvider.getSystemJavaCompiler(), and the fileManager is initialized using the standard file manager from the compiler. This setup allows the class to compile Java source files programmatically. The constructor then attempts to create the directories specified by sourceDir and classDir if they do not already exist, using Files.createDirectories(). If directory creation fails, it throws a RuntimeException to indicate a critical error that prevents the application from proceeding. This ensures that the necessary directory structure is in place for the class to function correctly.

Watching for File Changes

A dedicated thread runs a file watcher that listens for modifications to .java files in the source directory.The watchForChanges method is responsible for monitoring the source directory for any modifications to .java files and triggering the compileAndReload method when changes are detected. Here is the code for the watchForChanges method:

private void watchForChanges() {
    try (WatchService watchService = FileSystems.getDefault()
        .newWatchService()) {
        sourceDir.register(watchService, StandardWatchEventKinds.ENTRY_MODIFY);

        while (true) {
            WatchKey key = watchService.take();
            for (WatchEvent << ? > event : key.pollEvents()) {
                if (event.kind() == StandardWatchEventKinds.ENTRY_MODIFY) {
                    Path changed = sourceDir.resolve((Path) event.context());
                    String fileName = changed.getFileName()
                        .toString();
                    if (fileName.endsWith(".java")) {
                        compileAndReload(fileName);
                    }
                }
            }
            if (!key.reset()) {
                break;
            }
        }
    } catch (Exception e) {
        System.err.println("Error in file watcher: " + e.getMessage());
        e.printStackTrace();
    }
}

Compiling and Reloading Classes

The compileAndReload method is designed to handle the compilation of a Java source file and subsequently reload the resulting class if necessary. Upon invocation, it accepts a fileName parameter, which should be a Java source file (e.g., “MyClass.java”). The method begins by extracting the class name by removing the “.java” extension from the provided file name. It then constructs the paths for both the source file and the compiled class file using sourceDir and classDir, which are assumed to be defined in the broader context of the class.

To determine whether recompilation is required, the method compares the modification times of the source file and the corresponding class file. It retrieves the last known modification time from a lastModified map and obtains the current modification time of the source file. The method checks if the class file exists and whether its modification time is newer than or equal to that of the source file. If these conditions indicate that recompilation is unnecessary, the method exits early.

Conversely, if recompilation is deemed necessary, it invokes a separate compile method (details of which are not provided in this snippet) to compile the source file. Upon successful compilation, it calls a reloadClass method (also not shown) to reload the newly compiled class and updates the lastModified map with the current modification time. A success message is printed to confirm the successful operation. In the case of a compilation failure, an error message is displayed. The entire process is encapsulated within a try-catch block to effectively manage any exceptions that may arise during the compilation or file operations.

private void compileAndReload(String fileName) {
    try {
        String className = fileName.replace(".java", "");
        Path sourceFile = sourceDir.resolve(fileName);
        Path classFile = classDir.resolve(className + ".class");

        // Check if the file has been modified since last compilation
        long lastModTime = lastModified.getOrDefault(className, 0L);
        long currentModTime = Files.getLastModifiedTime(sourceFile)
            .toMillis();
        if (Files.exists(classFile) && Files.getLastModifiedTime(classFile)
            .toMillis() >= currentModTime && lastModTime >= currentModTime) {
            return;
        }

        // Compile the Java file
        boolean compilationSuccessful = compile(sourceFile);

        if (compilationSuccessful) {
            // Compilation successful, reload the class
            reloadClass(className);
            lastModified.put(className, currentModTime);
            System.out.println("Reloaded: " + className);
        } else {
            System.err.println("Compilation failed for: " + className);
        }
    } catch (Exception e) {
        System.err.println("Error in compile and reload: " + e.getMessage());
        e.printStackTrace();
    }
}

The compile method is designed to compile a Java source file utilizing the Java Compiler API, providing a structured approach to dynamic compilation. The method begins by accepting a Path object that represents the source file intended for compilation. To facilitate error handling and reporting, it creates a DiagnosticCollector, which collects diagnostic information such as errors and warnings encountered during the compilation process.

Next, the method constructs a collection of JavaFileObjects from the source file using a fileManager, likely an instance of StandardJavaFileManager. This setup is crucial for the Java Compiler API to access the source files correctly. The method then specifies compilation options, particularly the output directory for the compiled classes, using the -d option.

A CompilationTask is created using the Java Compiler API, which is configured with several parameters: no custom writer for compiler output (set to null), the file manager, the diagnostic collector, the compilation options, no annotation processors (also null), and the compilation units (the source files). The compilation task is executed by calling task.call(), which returns a boolean indicating whether the compilation was successful.

In the event of a compilation failure, the method iterates through the collected diagnostics, printing detailed error information that includes the line number where the error occurred, the source file URI, and the specific error message. This detailed reporting aids in debugging compilation issues effectively. Finally, the method returns the success status of the compilation, providing a clear indication of the outcome.

This method serves as a programmatic solution for compiling Java source files, making it particularly useful in scenarios where dynamic compilation is required. Its robust error reporting capabilities enhance the developer’s ability to troubleshoot and resolve compilation errors efficiently.

private boolean compile(Path sourceFile) {
    DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<>();
    Iterable<? extends JavaFileObject> compilationUnits = fileManager.getJavaFileObjectsFromFiles(Collections.singletonList(sourceFile.toFile()));

    List<String> options = Arrays.asList("-d", classDir.toString());

    JavaCompiler.CompilationTask task = compiler.getTask(null, fileManager, diagnostics, options, null, compilationUnits);

    boolean success = task.call();

    if (!success) {
        for (Diagnostic<? extends JavaFileObject> diagnostic : diagnostics.getDiagnostics()) {
            System.err.format("Error on line %d in %s%n", diagnostic.getLineNumber(), diagnostic.getSource()
                .toUri());
            System.err.println(diagnostic.getMessage(null));
        }
    }
    
    return success;
}

Custom Class Loader

A custom class loader is used to load the compiled class files into the JVM. The reloading happens after the compilation is successful and then it reloads the class. To reload the class we need to implement a custom class loader that will load the changed class and then execute it.

private void reloadClass(String className) {
    try {
        Class << ? > loadedClass = classLoader.loadClass(className);
        Method mainMethod = loadedClass.getMethod("main", String[].class);
        System.out.println("Invoking main method for: " + className);
        mainMethod.invoke(null, (Object) new String[0]);
    } catch (Exception e) {
        System.err.println("Error reloading class " + className + ": " + e.getMessage());
        e.printStackTrace();
    }
}

private class CustomClassLoader extends ClassLoader {

@Override
public Class << ? > loadClass(String name) throws ClassNotFoundException {
    Path classFile = classDir.resolve(name + ".class");
        if (Files.exists(classFile)) {
            try {
                byte[] classBytes = Files.readAllBytes(classFile);
                return defineClass(name, classBytes, 0, classBytes.length);
             } catch (IOException e) {
                throw new ClassNotFoundException("Error loading class " + name, e);
            }
         }
        return super.loadClass(name);
    }
}

Now if we want to execute the Hot Reload program we need to do something like this

    public static void main(String[] args) {
        Day84 reloader = new Day84("C:\\Users\\mohib\\IdeaProjects\\date-time\\src\\main\\java", "C:\\Users\\mohib\\IdeaProjects\\date-time\\target\\classes");
        reloader.start();

        // Keep the main thread alive and handle user input
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(System.in))) {
            System.out.println("Live reloader is running. Press Enter to exit.");
            reader.readLine();
        } catch (IOException e) {
            System.err.println("Error reading user input: " + e.getMessage());
        }
        System.out.println("Exiting live reloader.");
    }

In this main method we can see that we need to provide the path for the src of the code that you want to hot reload and the classes of those java files and after that it then watches for any changes and then compile and reload the class so that we can see the effect immediately.

Total code

import javax.tools.*;

import java.io.*;
import java.lang.reflect.Method;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;

public class Day84 {

    private final Path sourceDir;
    private final Path classDir;
    private final Map<String, Long> lastModified = new ConcurrentHashMap<>();
    private final CustomClassLoader classLoader;
    private final JavaCompiler compiler;
    private final StandardJavaFileManager fileManager;

    public Day84(String sourceDir, String classDir) {
        this.sourceDir = Paths.get(sourceDir)
            .toAbsolutePath();
        this.classDir = Paths.get(classDir)
            .toAbsolutePath();
        this.classLoader = new CustomClassLoader();
        this.compiler = ToolProvider.getSystemJavaCompiler();
        this.fileManager = compiler.getStandardFileManager(null, null, null);

        // Ensure directories exist
        try {
            Files.createDirectories(this.sourceDir);
            Files.createDirectories(this.classDir);
        } catch (IOException e) {
            throw new RuntimeException("Failed to create directories", e);
        }
    }

    public void start() {
        Thread watchThread = new Thread(this::watchForChanges, "FileWatcherThread");
        watchThread.setDaemon(true);
        watchThread.start();
        System.out.println("Live reloader started. Watching directory: " + sourceDir);
    }

    private void watchForChanges() {
        try (WatchService watchService = FileSystems.getDefault()
            .newWatchService()) {
            sourceDir.register(watchService, StandardWatchEventKinds.ENTRY_MODIFY);

            while (true) {
                WatchKey key = watchService.take();
                for (WatchEvent<?> event : key.pollEvents()) {
                    if (event.kind() == StandardWatchEventKinds.ENTRY_MODIFY) {
                        Path changed = sourceDir.resolve((Path) event.context());
                        String fileName = changed.getFileName()
                            .toString();
                        if (fileName.endsWith(".java")) {
                            compileAndReload(fileName);
                        }
                    }
                }
                if (!key.reset()) {
                    break;
                }
            }
        } catch (Exception e) {
            System.err.println("Error in file watcher: " + e.getMessage());
            e.printStackTrace();
        }
    }

    private void compileAndReload(String fileName) {
        try {
            String className = fileName.replace(".java", "");
            Path sourceFile = sourceDir.resolve(fileName);
            Path classFile = classDir.resolve(className + ".class");

            // Check if the file has been modified since last compilation
            long lastModTime = lastModified.getOrDefault(className, 0L);
            long currentModTime = Files.getLastModifiedTime(sourceFile)
                .toMillis();
            if (Files.exists(classFile) && Files.getLastModifiedTime(classFile)
                .toMillis() >= currentModTime && lastModTime >= currentModTime) {
                return;
            }

            // Compile the Java file
            boolean compilationSuccessful = compile(sourceFile);

            if (compilationSuccessful) {
                // Compilation successful, reload the class
                reloadClass(className);
                lastModified.put(className, currentModTime);
                System.out.println("Reloaded: " + className);
            } else {
                System.err.println("Compilation failed for: " + className);
            }
        } catch (Exception e) {
            System.err.println("Error in compile and reload: " + e.getMessage());
            e.printStackTrace();
        }
    }

    private boolean compile(Path sourceFile) {
        DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<>();
        Iterable<? extends JavaFileObject> compilationUnits = fileManager.getJavaFileObjectsFromFiles(Collections.singletonList(sourceFile.toFile()));

        List<String> options = Arrays.asList("-d", classDir.toString());

        JavaCompiler.CompilationTask task = compiler.getTask(null, fileManager, diagnostics, options, null, compilationUnits);

        boolean success = task.call();

        if (!success) {
            for (Diagnostic<? extends JavaFileObject> diagnostic : diagnostics.getDiagnostics()) {
                System.err.format("Error on line %d in %s%n", diagnostic.getLineNumber(), diagnostic.getSource()
                    .toUri());
                System.err.println(diagnostic.getMessage(null));
            }
        }

        return success;
    }

    private void reloadClass(String className) {
        try {
            Class<?> loadedClass = classLoader.loadClass(className);
            Method mainMethod = loadedClass.getMethod("main", String[].class);
            System.out.println("Invoking main method for: " + className);
            mainMethod.invoke(null, (Object) new String[0]);
        } catch (Exception e) {
            System.err.println("Error reloading class " + className + ": " + e.getMessage());
            e.printStackTrace();
        }
    }

    private class CustomClassLoader extends ClassLoader {

        @Override
        public Class<?> loadClass(String name) throws ClassNotFoundException {
            Path classFile = classDir.resolve(name + ".class");
            if (Files.exists(classFile)) {
                try {
                    byte[] classBytes = Files.readAllBytes(classFile);
                    return defineClass(name, classBytes, 0, classBytes.length);
                } catch (IOException e) {
                    throw new ClassNotFoundException("Error loading class " + name, e);
                }
            }
            return super.loadClass(name);
        }
    }

    public static void main(String[] args) {
        Day84 reloader = new Day84("C:\\Users\\mohib\\IdeaProjects\\date-time\\src\\main\\java", "C:\\Users\\mohib\\IdeaProjects\\date-time\\target\\classes");
        reloader.start();

        // Keep the main thread alive and handle user input
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(System.in))) {
            System.out.println("Live reloader is running. Press Enter to exit.");
            reader.readLine();
        } catch (IOException e) {
            System.err.println("Error reading user input: " + e.getMessage());
        }
        System.out.println("Exiting live reloader.");
    }
}

Conclusion

Hot Class Reload in Java offers a powerful way to enhance development productivity by reducing the need for full application restarts. By integrating file watching, dynamic compilation, and custom class loading, developers can achieve a seamless development experience akin to JavaScript’s Hot Module Reload.

Implementing HCR can significantly speed up the development cycle, allowing for rapid testing and iteration. As you integrate this technique into your workflow, you’ll find it an invaluable tool for efficient Java development. There are some libraries like JRebel which provides this feature more on that in the next post.

Day 83: Java Object Cloning: Exploring Shallow and Deep Copy Techniques

2024-09-14T00:00:00Z

When working with Java objects, it’s crucial to understand how objects can be copied. Objects can be copied either shallowly or deeply, and grasping these concepts is essential when you need to duplicate an object’s state without affecting the original object.

In this article, we’ll explore various methods of creating deep and shallow copies of objects in Java, including some optimized approaches and potential pitfalls to avoid.

Shallow Copy

A shallow copy creates a new object but references the same elements as the original object. In other words, the new object contains copies of the values of the original object’s fields, but any references to other objects remain the same.

Here’s an example of creating a shallow copy in Java:

public class Person {
    private String name;
    private int age;
    private List<PhoneNumber> phoneNumbers;

    public Person(String name, int age, List<PhoneNumber> phoneNumbers) {
        this.name = name;
        this.age = age;
        this.phoneNumbers = phoneNumbers;
    }
    // getters & setters
}

Now let’s see how shallow copying works:

@Test
void givenPersonObject_whenShallowCopied_thenCopyHasSameDataButDifferentReference() {
    List<PhoneNumber> phoneNumbers = new ArrayList<>();
    phoneNumbers.add(new PhoneNumber("123-456-7890"));

    Person person1 = new Person("John Doe", 30, phoneNumbers);
    Person person2 = DeepCopyUtil.shallowCopy(person1);

    assertNotEquals(person1, person2);
    assertEquals("John Doe", person1.getName());
    assertEquals("John Doe", person2.getName());
    person2.setName("Jane Doe");
    assertEquals("John Doe", person1.getName());
    assertNotEquals("John Doe", person2.getName());

    person2.getPhoneNumbers().add(new PhoneNumber("456-789-0123"));
    assertEquals(2, person1.getPhoneNumbers().size());
}

In this example, when we assign person1 to person2, we’re creating a shallow copy. As a result, both person1 and person2 refer to the same Person object in memory. Modifying the phoneNumbers property of person2 also affects the phoneNumbers property of person1.

Shallow Copy Methods

There are several ways to create shallow copies in Java:

Object.clone() method: Requires implementing the Cloneable interface.

public class Person implements Cloneable {
    // ... fields and other methods ...

    @Override
    public Object clone() throws CloneNotSupportedException {
        return super.clone();
    }
}

Copy Constructor: Can be used for shallow copying if it only copies references.

public Person(Person other) {
    this.name = other.name; // Shallow copy of reference
    this.age = other.age;
}

Does Using Clone() make a Deep Copy?

The clone() method typically creates a shallow copy, not a deep copy. This means that while it creates a new object, it doesn’t create new instances of the mutable objects contained within the original object.

Here’s an example using the Cloneable interface:

public class PersonCloneable implements Cloneable {
    private String name;
    private int age;
    private List<PhoneNumber> phoneNumbers;

    public PersonCloneable(String name, int age, List<PhoneNumber> phoneNumbers) {
        this.name = name;
        this.age = age;
        this.phoneNumbers = phoneNumbers;
    }

    @Override
    public PersonCloneable clone() throws CloneNotSupportedException {
        return (PersonCloneable) super.clone();
    }

    // Getters & setters
}

Now let’s look at a test to understand it better:

@Test
void givenPersonCloneableObject_whenCloned_thenShallowCopyIsCreated() throws CloneNotSupportedException {
    List<PhoneNumber> phoneNumbers = new ArrayList<>();
    phoneNumbers.add(new PhoneNumber("123-456-7890"));
    PersonCloneable original = new PersonCloneable("John Doe", 30, phoneNumbers);

    PersonCloneable clone = original.clone();

    clone.setName("Jane Doe");
    clone.setAge(25);
    clone.getPhoneNumbers().add(new PhoneNumber("987-654-3210"));

    assertEquals("John Doe", original.getName());
    assertEquals(30, original.getAge());

    assertEquals(2, original.getPhoneNumbers().size());
    assertEquals(2, clone.getPhoneNumbers().size());
}

In this example, we use the clone() method to create a shallow copy of the PersonCloneable object. This creates a new PersonCloneable object with its own memory location, independent of the original person1 object.

However, modifying the phoneNumbers property of the clone affects the phoneNumbers of the original. That’s one of the potential issues of using clone(), as it makes shallow copies, not deep copies.

Potential Issues with Clone()

While the clone() method can be used to create copies of objects, it has some significant issues:

Needs Cloneable interface: To use the clone() method, a class must explicitly implement the Cloneable interface. By default, the clone() method is protected in the Object class, and if a class doesn’t implement it, trying to use clone() will result in a CloneNotSupportedException.
Default Shallow Copy: The default clone() method in the Object class creates a shallow copy. This means that if the object contains references to other mutable objects, the cloned object will still share those references with the original, rather than duplicating the referenced objects themselves.
Security Concerns: Overriding the clone() method allows for custom cloning behavior, but it also introduces potential security risks. Here’s a more detailed explanation:

Imagine you’re at a copy machine in an office. You’re supposed to make an exact copy of a document, but someone has tampered with the machine. Instead of making a true copy, it might add or remove pages, or even worse, send a copy to someone else! That’s similar to what can happen with the clone() method if it’s not implemented correctly.

Here’s why:

Unexpected Behavior: When you override clone(), you’re in charge of deciding exactly how the copying happens. If you’re not careful, you might accidentally expose private data or create inconsistent objects.
The “Fake Copy” Problem: A malicious subclass could override clone() to return a reference to itself instead of creating a new object. This could trick other parts of the code into thinking they have a fresh copy when they don’t.
Bypassing Security Checks: Normally, when you create an object, its constructor runs and can perform important security checks. But clone() bypasses the constructor, potentially creating objects in an insecure state.
Inconsistent State: If clone() is interrupted (like by an exception), it might leave the new object half-created. This could lead to bugs or vulnerabilities if the code isn’t prepared to handle partially-cloned objects.

Here’s a simple example to illustrate:

class SecretKeeper implements Cloneable {
    private String secretPassword = "1234";

    @Override
    public SecretKeeper clone() {
        try {
            SecretKeeper cloned = (SecretKeeper) super.clone();
            // Oops! We forgot to create a new String for secretPassword
            // Now the clone shares the same String reference as the original
            return cloned;
        } catch (CloneNotSupportedException e) {
            return null;
        }
    }

    public void changePassword(String newPassword) {
        this.secretPassword = newPassword;
    }
}

// In some other part of the code...
SecretKeeper original = new SecretKeeper();
SecretKeeper cloned = original.clone();

// The programmer thinks this only changes the clone's password
cloned.changePassword("5678");

// But surprise! It changed the original's password too
// because both objects are sharing the same String reference

In this example, a programmer using the SecretKeeper class might think they’re safely changing only the cloned object’s password, but they’re actually changing the original object’s password too. This could lead to serious security issues in a real application.

To avoid these pitfalls, many Java developers prefer to use copy constructors or factory methods for object copying. These approaches give you more control and make it easier to ensure that you’re creating secure, consistent copies of objects.

Deep Copy Methods

To perform a deep copy in Java, we have multiple options such as using a custom copy method or a copy constructor. Furthermore, we can leverage serialization and third-party libraries for this purpose. Below, we’ll discuss deep copy methods including custom copy methods and serialization.

Custom Copy Method

One way to create a deep copy is to manually create new instances of all mutable objects. Here’s an example:

1
2
3

public Person deepCopy() {
    return new Person(new String(this.name), this.age);
}

Serialization

Java serialization is one of the most efficient ways of creating deep copies of an object. This approach works well for serializable objects (those that implement the Serializable interface). Using third-party libraries like Jackson and Gson, you can also do this.

For example, let’s modify the Person class to make it serializable:

public class PersonSerializable implements Serializable {
    private String name;
    private int age;
    private List<PhoneNumber> phoneNumbers;

    public PersonSerializable(String name, int age, List<PhoneNumber> phoneNumbers) {
        this.name = name;
        this.age = age;
        this.phoneNumbers = phoneNumbers;
    }
}

Now our custom deepCopy() method will use serialization-deserialization to copy an object:

public static <T extends Serializable> T deepCopy(T object) {
    try {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        ObjectOutputStream oos = new ObjectOutputStream(baos);
        oos.writeObject(object);
        ObjectInputStream ois = new ObjectInputStream(new ByteArrayInputStream(baos.toByteArray()));
        return (T) ois.readObject();
    } catch (IOException | ClassNotFoundException e) {
        throw new IllegalArgumentException(e);
    }
}

Here we are making deep copies of an object by serializing it into a byte array and then deserializing it from that byte array. This approach works well for creating a deep copy but requires that all objects in the graph are Serializable.

Now let’s see its use:

@Test
void givenPersonSerializableObject_whenDeepCopied_thenCopyIsIndependentOfOriginal() {
    List<PhoneNumber> phoneNumbers = new ArrayList<>();
    phoneNumbers.add(new PhoneNumber("123-456-7890"));
    PersonSerializable original = new PersonSerializable("John Doe", 30, phoneNumbers);
    PersonSerializable copy = DeepCopyUtil.deepCopy(original);

    assertNotSame(original, copy);
    assertEquals(original.getName(), copy.getName());
    assertEquals(original.getAge(), copy.getAge());

    copy.setName("Jane Doe");
    copy.setAge(25);
    copy.getPhoneNumbers().add(new PhoneNumber("987-654-3210"));

    assertEquals("John Doe", original.getName());
    assertEquals(30, original.getAge());

    assertEquals(1, original.getPhoneNumbers().size());
    assertEquals(2, copy.getPhoneNumbers().size());
}

This method serializes the object to a byte array and then deserializes it to create a new instance. From the test, we can see that it can effectively create a deep copy of the PersonSerializable object.

Other Deep Copy Methods

JSON Serialization/Deserialization: Use libraries like Jackson or Gson.

1
2

ObjectMapper mapper = new ObjectMapper();
Person copy = mapper.readValue(mapper.writeValueAsString(original), Person.class);

Cloning Libraries: Use third-party libraries like Apache Commons Lang.
1

Person copy = SerializationUtils.clone(original);
Using Reflection:

Another powerful technique for creating deep copies is using reflection. This method allows you to create a deep copy of an object without the need for implementing Cloneable or writing custom constructors. It works by recursively copying the fields of an object, even if the fields are private or inaccessible.

Here’s an example of how to implement deep copying using reflection:

import java.lang.reflect.Field;
import java.util.HashMap;
import java.util.Map;

public class DeepCopyUtil {

    // A map to track objects and their deep copies to handle cyclic dependencies
    private static Map<Object, Object> visited = new HashMap<>();

    public static Object deepCopy(Object object) throws IllegalAccessException, InstantiationException {
        // Check if the object is already copied (to handle cyclic dependencies)
        if (visited.containsKey(object)) {
            return visited.get(object); // Return the already-copied object
        }

        // If the object is null, no need to copy
        if (object == null) {
            return null;
        }

        Class<?> clazz = object.getClass();
        Object copy = clazz.newInstance(); // Create a new instance of the object
        visited.put(object, copy); // Register the object and its copy in the map

        // Copy each field of the object
        for (Field field : clazz.getDeclaredFields()) {
            field.setAccessible(true);
            Object value = field.get(object);

            // Check if a deep copy is required
            if (value != null && isDeepCopyRequired(value)) {
                // Recursively copy the field, ensuring cyclic dependencies are handled
                field.set(copy, deepCopy(value));
            } else {
                // Directly copy the field if it's a primitive, string, or number
                field.set(copy, value);
            }
        }
        return copy;
    }

    private static boolean isDeepCopyRequired(Object value) {
        return !(value.getClass().isPrimitive() || value instanceof String || value instanceof Number);
    }

    public static void clearVisitedMap() {
        visited.clear(); // Clear the map after deep copying to avoid memory leaks
    }
}

This method works by:

Creating a new instance of the object’s class.
Iterating through all declared fields of the object.
For each field, if it’s not a primitive, String, or Number (which are immutable), it recursively applies the deep copy method. Otherwise, it simply copies the value. Here the method might produce cyclic dependencies which can be resolved by checking if we already created the object. Thats why we have a visited map in the example to resolve that.

Let’s see how we can use this method:

public class Person {
    String name;
    Person friend; // Cyclic reference possible

    public Person(String name) {
        this.name = name;
    }
}

@Test
public void testDeepCopyWithCyclicDependency() throws Exception {
    Person john = new Person("John");
    Person jane = new Person("Jane");

    // Create cyclic dependency
    john.friend = jane;
    jane.friend = john;

    // Deep copy the object
    Person johnCopy = (Person) DeepCopyUtil.deepCopy(john);

    // Ensure deep copy is successful and cyclic references are handled
    Assertions.assertNotSame(john, johnCopy);
    Assertions.assertNotSame(jane, johnCopy.friend);
    Assertions.assertSame(johnCopy, johnCopy.friend.friend);

    // Clear the visited map to avoid memory leak
    DeepCopyUtil.clearVisitedMap();
}

This reflection-based deep copying technique has several advantages and disadvantages:

Pros:

It works without modifying your class or implementing interfaces. It can copy private and protected fields. It’s a generic solution that can work with any object.

Cons:

This approach can be slower due to the use of reflection. It might require handling some special cases, such as cyclic dependencies. It may not work correctly with final fields or certain complex objects.

When using this method, be aware of its limitations and test thoroughly with your specific object structures. Also, consider the performance implications, especially when dealing with large object graphs or in performance-critical sections of your code.

Optimized Approaches

Copy-on-Write: For collections, Java provides copy-on-write implementations like CopyOnWriteArrayList.

CopyOnWriteArrayList<Person> list = new CopyOnWriteArrayList<>();
// Adding elements doesn't create a copy
list.add(new Person("John", 30));
// But modifying operations do
list.set(0, new Person("Jane", 28));

Immutable Objects: If objects are immutable, shallow copying is effectively the same as deep copying.

public final class ImmutablePerson {
    private final String name;
    private final int age;

    public ImmutablePerson(String name, int age) {
        this.name = name;
        this.age = age;
    }

    // Only getters, no setters
}

Lazy Copying: Implement a copy-on-write mechanism for individual fields.

public class LazyPerson {
    private String name;
    private int age;
    private LazyPerson original;

    public LazyPerson(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public LazyPerson(LazyPerson other) {
        this.original = other;
    }

    public String getName() {
        if (original != null) {
            return original.getName();
        }
        return name;
    }

    public void setName(String name) {
        if (original != null) {
            this.name = original.name;
            this.age = original.age;
            original = null;
        }
        this.name = name;
    }

    // Similar for age
}

Conclusion

In this article, we’ve covered what shallow and deep copy means in Java. Shallow copies create new objects but maintain references to the same nested objects, while deep copies create entirely new objects with independent states, including nested objects.

We’ve explored various methods for creating both shallow and deep copies, including the clone() method, custom copy methods, serialization, and some optimized approaches. We’ve also discussed the potential security issues with using clone() and why many developers prefer alternative methods.

When choosing a copying method, consider the specific requirements of your application, including performance needs, object complexity, and maintenance considerations. Always profile your application to determine the most efficient method for your specific scenario.

Remember, the “best” approach often depends on the specific requirements of your application. Shallow copying might be sufficient for simple objects or when performance is critical, while deep copying is necessary when you need to create truly independent copies of complex object graphs.

Day 82: Reflection in Java: Building a Simple DI Container in 100 Lines of Code

2024-08-17T00:00:00Z

Reflection in Java is a powerful concept that serves as the backbone for numerous Java and J2EE frameworks [1]. This feature allows an executing Java program to examine or introspect upon itself, and manipulate its internal properties at runtime [2]. While it’s of limited use in everyday programming, reflection plays a crucial role in various frameworks that lack direct access to user-defined classes, interfaces, and their methods.

What is this introspect

Imagine giving a program a magic mirror that lets it see and understand itself. That’s what introspection does in Java. It’s like the code is able to figure out what it is and what it can do, all while it’s running.

This self-examination superpower is super handy. It helps debuggers peek inside code, powers those handy autocompletions in your IDE, and even helps convert data between different formats. It’s all thanks to some clever Java tools that let programs ask themselves questions like “What am I?” or “What can I do?” While it’s a cool trick, it needs to be used carefully. Overdo it, and your program might slow down or accidentally reveal things meant to be secret. But when used right, it’s like giving your code X-ray vision – a powerful tool that opens up a world of possibilities for flexible, dynamic programming.

Understanding Reflection API

The Reflection API provides developers with the ability to analyze and modify class fields and methods during runtime [1]. It offers several methods to examine Class fields, invoke methods, and create new instances of classes by invoking constructors [1]. To use reflection, developers typically follow three steps:

Obtain a java.lang.Class object for the class to manipulate.
Use the Class object to gather information about the class.
Utilize reflection classes like Method from java.lang.reflect to perform operations.

One practical application of reflection is in JavaBeans, where software components can be manipulated visually via builder tools [2]. These tools use reflection to obtain the properties of Java components as they are dynamically loaded. Reflections another practical application

Reflection for Runtime Type Introspection

Reflection enables runtime type introspection, allowing programs to examine and interact with objects whose types may not be known at compile time. This capability is particularly useful in scenarios where dynamic behavior is required.

For instance, reflection can be used to:

Simulate the instanceof operator using Class.isInstance method [2].
Discover methods defined within a class [2].
Examine constructors and data fields of a class [2].
Invoke methods dynamically, even when the method name is specified during execution [2].
Modify values of data fields in objects at runtime [2].

These capabilities make reflection a powerful tool for creating flexible and adaptable software systems. However, it’s important to use reflection judiciously, as it can impact performance and potentially break encapsulation principles.

Security Considerations with Reflection

While reflection offers significant flexibility, it also introduces security considerations that developers must address: Potential for Code Injection: Unsafe use of reflection mechanisms can create unexpected control flow paths through an application, potentially bypassing security checks [3]. This vulnerability may allow attackers to create limited forms of code injection.

Access Control Risks:

Reflection can be used to access private fields and methods, potentially breaking encapsulation and leaking sensitive data [4]. This capability can lead to various malicious exploits, such as modifying supposedly immutable strings or revealing sensitive information from objects [4].

Classloader Hierarchy Concerns:

In shared hosting environments like Google App Engine, reflection could potentially be used to enumerate classes and methods from different users' WAR files if not properly restricted [4].

To mitigate these risks, developers should consider the following precautions:

Install and configure a SecurityManager to enforce access controls

Use the setAccessible() method judiciously, as it’s subject to security checks governed by the setAccessChecks reflection permission [4]. Be cautious when using reflection to instantiate objects or invoke methods, especially with user-supplied input [3]. By understanding both the power and the potential risks of reflection, developers can leverage this feature effectively while maintaining the security and integrity of their applications.

Exploring Dependency Injection Patterns

Dependency Injection (DI) is a design pattern in Java that aims to decouple classes from their dependencies, making code more flexible, testable, and maintainable [5]. It allows developers to move the dependency resolution from compile-time to runtime, resulting in loosely coupled and extendable applications [6]. There are several patterns for implementing dependency injection in Java, each with its own advantages and use cases.

Constructor Injection

Constructor injection involves passing dependencies as arguments to a class’s constructor. This method ensures that all required dependencies are available upon object creation, making it ideal for mandatory dependencies [5]. Constructor injection supports immutability and state safety, as the object is either instantiated with a full state or not instantiated at all [7].

public class Car {
    private final Engine engine;
    private final Steering steering;

    @Autowired //Spring like
    @inject //JAX-RS
    public Car(Engine engine, Steering steering) {
        thisותs.engine = engine;
        this.steering = steering;
    }
}

This pattern is particularly useful when dealing with components that are essential for an object’s functionality, such as a car needing an engine and steering [8].

Setter Injection

Setter injection utilizes setter methods to inject dependencies after object creation. This approach offers more flexibility but can make the class mutable [5]. It’s preferred for optional dependencies that are not mandatorily required but can assist in some ways [8].

public class User {
    private String phoneNumber;

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

Setter injection is suitable for scenarios where dependencies may change during the object’s lifecycle or when dealing with optional components [7].

Method Injection

Method injection involves injecting dependencies directly into methods where they are needed. This pattern is less common but can be useful in specific scenarios where dependencies are required only for certain operations.

public class MessageSender {
    @Autowired
    public void sendMessage(MessageService messageService, String message) {
        messageService.send(message);
    }
}

Field Injection

Field injection directly injects dependencies into class fields, typically using annotations. While it results in less boilerplate code and can improve readability, it doesn’t support immutability and can make testing more challenging [7].

public class EmailService {
    @Autowired
    private EmailClient emailClient;
}

When choosing a dependency injection pattern, developers should consider factors such as immutability, state safety, and the nature of the dependencies (mandatory vs. optional). Constructor injection is generally recommended for its support of immutability and clear dependency declaration, while setter injection offers more flexibility for optional dependencies [7].

To implement these patterns effectively, developers can use frameworks like Spring, which provide powerful dependency injection containers. These containers manage the creation and injection of dependencies, inverting the control flow and allowing for more modular and maintainable code [5].

Designing a Lightweight DI Container

Designing a lightweight Dependency Injection (DI) container involves creating a framework that manages the creation and lifecycle of objects in an application. This approach allows developers to implement Inversion of Control (IoC), a design principle that separates the responsibility of creating and managing dependencies from the client classes [9]. A well-designed DI container enhances modularity, reusability, and testability of code by promoting loose coupling between components [10].

Container Initialization

The first step in designing a lightweight DI container is to create an initialization mechanism. This process typically involves: Defining an AbstractBinder or similar class to specify how dependencies should be created and managed [11]. Registering the binder with the application, often through a configuration file or programmatically [11]. Implementing a class that extends a framework-specific class (e.g., ResourceConfig in JAX-RS) to register the binder and specify the packages to scan for injectable components [11].

For example, in a JAX-RS application, the initialization might look like this:

public class MyApplication extends ResourceConfig {
    public MyApplication() {
        register(new MyApplicationBinder());
        packages(true, "com.mypackage.rest");
    }
}

This initialization sets up the container to manage dependencies within the specified package and its subpackages.

Dependency Scanning and Registration

Once the container is initialized, it needs to scan for and register dependencies. This process involves:

Scanning all clients under the root package and subpackages [9].
Creating instances of client classes [9].
Identifying services used in client classes, including member variables, constructor parameters, and method parameters [9].
Recursively scanning for nested dependencies within services [9].
Creating a map of all client classes and their dependencies [9].

During this phase, the container should also handle special cases, such as:

Validating if there are multiple implementations of an interface or no implementation at all [9].
Managing qualifiers for services or implementing autowiring by type when multiple implementations exist [9].
Resolving and Injecting Dependencies

The final step in the DI process is resolving and injecting dependencies. This involves:

Creating instances of services identified during the scanning phase [9].
Injecting (initializing) each service with its required dependencies [9].
Providing methods to retrieve beans or services, such as getBean(Class classz) or getService(Class classz) [9].
The injection process follows a specific order as defined by JSR330 [12]:
1. Constructor injection 2.Field injection 3.Method injection

It’s important to note that the order in which methods or fields annotated with @Inject are called is not defined by JSR330, so developers should not assume a specific order of injection [12]. To implement this lightweight DI container, developers can use annotations like @Inject to mark injection points [13]. For example:

public class Payroll {
    private EmployeeDatabase employeeDatabase;

    @Inject
    public Payroll(EmployeeDatabase employeeDatabase) {
        this.employeeDatabase = employeeDatabase;
    }
    // ... rest of the class implementation
}

This design allows for flexible configuration and easy testing, as dependencies can be easily mocked or stubbed [10]. It also promotes the use of immutable objects and makes dependencies explicit, which enhances code maintainability [10]. By implementing these components, developers can create a lightweight DI container that provides the benefits of dependency injection without the complexity of larger frameworks. This approach is particularly useful for standalone Java applications or when retrofitting legacy systems as part of major refactoring efforts [14].

Now lets implement a DI container

At first we will see how the container is made up and then will create the services and load them in the container and use them to see.

public class DIContainer {
    private final Map<Class<?>, Object> singletons = new ConcurrentHashMap<>();
    private final Map<Class<?>, Class<?>> implementations = new ConcurrentHashMap<>();

    public <T> void bindImplementation(Class<T> interfaceClass, Class<? extends T> implementationClass) {
        implementations.put(interfaceClass, implementationClass);
    }

    public <T> T getInstance(Class<T> clazz) {
        try {
            return getOrCreateInstance(clazz);
        } catch (Exception e) {
            throw new RuntimeException("Error creating instance of " + clazz.getName(), e);
        }
    }

    @SuppressWarnings("unchecked")
    private <T> T getOrCreateInstance(Class<T> clazz) throws Exception {
        Class<?> targetClass = implementations.getOrDefault(clazz, clazz);

        if (targetClass.isAnnotationPresent(Singleton.class)) {
            return (T) singletons.computeIfAbsent(targetClass, this::createInstance);
        }

        return createInstance(targetClass);
    }

    @SuppressWarnings("unchecked")
    private <T> T createInstance(Class<?> clazz) {
        try {
            Constructor<?> constructor = findInjectableConstructor(clazz);
            T instance = (T) (constructor != null ?
                    createInstanceWithConstructor(constructor) :
                    clazz.getDeclaredConstructor().newInstance());

            injectFields(clazz, instance);
            injectMethods(clazz, instance);

            return instance;
        } catch (Exception e) {
            throw new RuntimeException("Error creating instance of " + clazz.getName(), e);
        }
    }

    private Constructor<?> findInjectableConstructor(Class<?> clazz) {
        return Arrays.stream(clazz.getDeclaredConstructors())
                .filter(c -> c.isAnnotationPresent(Inject.class))
                .findFirst()
                .orElse(null);
    }

    private Object createInstanceWithConstructor(Constructor<?> constructor) throws Exception {
        Object[] params = Arrays.stream(constructor.getParameterTypes())
                .map(this::getInstance)
                .toArray();
        return constructor.newInstance(params);
    }

    private void injectFields(Class<?> clazz, Object instance) throws Exception {
        for (Field field : clazz.getDeclaredFields()) {
            if (field.isAnnotationPresent(Inject.class)) {
                Object fieldInstance = getInstance(field.getType());
                field.setAccessible(true);
                field.set(instance, fieldInstance);
            }
        }
    }

    private void injectMethods(Class<?> clazz, Object instance) throws Exception {
        for (Method method : clazz.getDeclaredMethods()) {
            if (method.isAnnotationPresent(Inject.class)) {
                Object[] params = Arrays.stream(method.getParameterTypes())
                        .map(this::getInstance)
                        .toArray();
                method.setAccessible(true);
                method.invoke(instance, params);
            }
        }
    }
}

now let us break this class down. The DIContainer class is the core of our DI framework. It uses two main data structures:

singletons: A thread-safe map to store singleton instances
implementations: A map to store interface-to-implementation bindings

I use annotations and reflection to make the core features of the DI.

The bindImplementation method allows users to specify which implementation should be used for a given interface: This is useful when you want to inject an interface but use a specific implementation.

1
2
3

public <T> void bindImplementation(Class<T> interfaceClass, Class<? extends T> implementationClass) {
    implementations.put(interfaceClass, implementationClass);
}

The public getInstance method is the entry point for retrieving instances: It delegates to getOrCreateInstance, wrapping any exceptions in a RuntimeException.

public <T> T getInstance(Class<T> clazz) {
    try {
        return getOrCreateInstance(clazz);
    } catch (Exception e) {
        throw new RuntimeException("Error creating instance of " + clazz.getName(), e);
    }
}

The getOrCreateInstance method is where the magic happens: It first checks if there’s a registered implementation for the requested class. If the target class is annotated with @Singleton, it uses computeIfAbsent to ensure thread-safe lazy initialization. Otherwise, it creates a new instance each time.

private <T> T getOrCreateInstance(Class<T> clazz) throws Exception {
    Class<?> targetClass = implementations.getOrDefault(clazz, clazz);

    if (targetClass.isAnnotationPresent(Singleton.class)) {
        return (T) singletons.computeIfAbsent(targetClass, this::createInstance);
    }

    return createInstance(targetClass);
}

The createInstance method handles the actual object creation: It performs these steps:

Find an @Inject-annotated constructor
Create the instance using the constructor or default constructor
Inject fields
Inject methods

private <T> T createInstance(Class<?> clazz) {
    try {
        Constructor<?> constructor = findInjectableConstructor(clazz);
        T instance = (T) (constructor != null ?
                createInstanceWithConstructor(constructor) :
                clazz.getDeclaredConstructor().newInstance());

        injectFields(clazz, instance);
        injectMethods(clazz, instance);

        return instance;
    } catch (Exception e) {
        throw new RuntimeException("Error creating instance of " + clazz.getName(), e);
    }
}

Constructor Injection

findInjectableConstructor looks for a constructor annotated with @Inject: If found, createInstanceWithConstructor handles the dependency injection: This method searches for a constructor annotated with @Inject. Here’s what’s happening:

We get all declared constructors of the class using clazz.getDeclaredConstructors() a reflection method that gets declared constructors.
We create a stream from this array of constructors
We filter the stream to keep only constructors annotated with @Inject
We take the first matching constructor (findFirst())
If no constructor is found, we return null (orElse(null))

This approach allows us to specify which constructor should be used for dependency injection. If no @Inject-annotated constructor is found, we’ll fall back to using the default constructor.

private Constructor<?> findInjectableConstructor(Class<?> clazz) {
    return Arrays.stream(clazz.getDeclaredConstructors())
            .filter(c -> c.isAnnotationPresent(Inject.class))
            .findFirst()
            .orElse(null);
}

createInstanceWithConstructor() This method creates an instance using the provided constructor. Here’s the process:

We get the parameter types of the constructor
We create a stream of these types
For each type, we call getInstance() to get or create an instance of that type
We collect these instances into an array Finally, we invoke the constructor with these parameters.This recursive approach ensures that all dependencies (and their dependencies) are properly instantiated.

private Object createInstanceWithConstructor(Constructor<?> constructor) throws Exception {
    Object[] params = Arrays.stream(constructor.getParameterTypes())
            .map(this::getInstance)
            .toArray();
    return constructor.newInstance(params);
}

Field Injection

The injectFields method handles field injection:

We iterate over all declared fields of the class for each field annotated with @Inject

We get an instance of the field’s type using getInstance()
We make the field accessible (in case it’s private)
We set the field’s value on the instance to our newly created fieldInstance

This allows for dependency injection on fields, which can be useful for optional dependencies or when constructor injection isn’t feasible.

private void injectFields(Class<?> clazz, Object instance) throws Exception {
    for (Field field : clazz.getDeclaredFields()) {
        if (field.isAnnotationPresent(Inject.class)) {
            Object fieldInstance = getInstance(field.getType());
            field.setAccessible(true);
            field.set(instance, fieldInstance);
        }
    }
}

Method Injection

This method performs method injection: We iterate over all declared methods of the class

For each method annotated with @Inject:

We get the parameter types of the method
We create instances for each parameter type using getInstance()
We make the method accessible
We invoke the method on the instance with the created parameters

Method injection can be useful for optional dependencies or for performing post-construction initialization.

private void injectMethods(Class<?> clazz, Object instance) throws Exception {
    for (Method method : clazz.getDeclaredMethods()) {
        if (method.isAnnotationPresent(Inject.class)) {
            Object[] params = Arrays.stream(method.getParameterTypes())
                    .map(this::getInstance)
                    .toArray();
            method.setAccessible(true);
            method.invoke(instance, params);
        }
    }
}

This DIContainer implementation provides a flexible and powerful dependency injection framework. It supports constructor, field, and method injection, as well as singleton management and interface-to-implementation binding. The use of reflection allows for a clean and non-invasive way to manage dependencies in your application.

Now let us see the Main class and how to use it.

interface MessageService {
    void sendMessage(String message);
}

@Singleton
class EmailService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending email: " + message);
    }
}

class UserService {
    private final MessageService messageService;

    @Inject
    public UserService(MessageService messageService) {
        this.messageService = messageService;
    }

    public void notifyUser(String message) {
        messageService.sendMessage(message);
    }
}

public class Main {
    public static void main(String[] args) {
        DIContainer container = new DIContainer();
        container.bindImplementation(MessageService.class, EmailService.class);

        UserService userService = container.getInstance(UserService.class);
        userService.notifyUser("Hello from, DI!");
    }
}

This example demonstrates a basic Dependency Injection (DI) setup using a custom container:

Component structure:
- MessageService: An interface defining the contract for messaging.
- EmailService: A concrete @Singleton implementation of MessageService.
- UserService: A service with a dependency on MessageService.
DI configuration:
- UserService uses constructor injection, marked with @Inject.
- The DI container is configured to bind MessageService to EmailService.
Runtime behavior:
- An DIContainer instance is created and configured.
- When getInstance(UserService.class) is called, the container: a. Recognizes the MessageService dependency. b. Instantiates EmailService (or reuses the singleton instance). c. Injects the EmailService into UserService. d. Returns the constructed UserService.
Key DI principles demonstrated:
- Inversion of Control (IoC): UserService doesn’t create its dependencies.
- Loose coupling: UserService depends on the MessageService interface, not the concrete EmailService.
- Single Responsibility Principle: The DI container manages object creation and wiring.
Benefits:
- Improved testability: Dependencies can be easily mocked.
- Flexibility: Changing implementations (e.g., to an SMSService) requires only container reconfiguration.
- Separation of concerns: Business logic is separated from object construction and wiring.

This setup showcases core DI concepts, illustrating how it promotes loosely coupled, modular, and easily maintainable code architecture.

To wrap up, reflection in Java proves to be a game-changer for building flexible and adaptable applications. Its ability to enable runtime introspection and modification has a profound impact on the development of frameworks and tools, particularly in the realm of dependency injection. The creation of a lightweight DI container showcases the practical application of reflection, demonstrating how it can be harnessed to implement sophisticated design patterns and improve code modularity. The exploration of various dependency injection patterns and the design considerations for a DI container highlight the power of reflection to create more maintainable and testable code. By leveraging annotations and reflection, developers can craft systems that are not only more flexible but also easier to extend and modify over time. This approach to software design opens up new possibilities for creating robust and scalable applications, ultimately leading to more efficient development processes and higher-quality software products.

References

[1] - https://www.digitalocean.com/community/tutorials/java-reflection-example-tutorial [2] - https://www.oracle.com/technical-resources/articles/java/javareflection.html [3] - https://owasp.org/www-community/vulnerabilities/Unsafe_use_of_Reflection [4] - https://stackoverflow.com/questions/3002904/what-is-the-security-risk-of-object-reflection [5] - https://www.geeksforgeeks.org/dependency-injection-di-design-pattern/ [6] - https://www.digitalocean.com/community/tutorials/java-dependency-injection-design-pattern-example-tutorial [7] - https://www.javacodegeeks.com/2019/02/field-setter-constructor-injection.html [8] - https://www.geeksforgeeks.org/spring-setter-injection-vs-constructor-injection/ [9] - https://dev.to/jjbrt/how-to-create-your-own-dependency-injection-framework-in-java-4eaj [10] - https://www.geeksforgeeks.org/what-is-the-best-way-to-inject-dependency-in-java/ [11] - https://stackoverflow.com/questions/16216759/dependency-injection-with-jersey-2-0 [12] - https://www.vogella.com/tutorials/DependencyInjection/article.html [13] - https://www.objc.io/issue-11/dependency-injection-in-java.html [14] - https://stackoverflow.com/questions/1333438/is-there-a-simple-framework-allowing-for-dependency-injection-in-a-stand-alone-p

Day 81: Creating custom stream operations ex: Slide, Shift, Zip and Fold using Spliterator

2024-07-04T00:00:00Z

Custom Spliterator in Java: Enhancing Stream Operations

In the world of Java development, mastering the Streams API is crucial for efficient data processing. However, there are times when the built-in functionalities fall short of our specific needs. This is where custom Spliterators come into play. In this blog post, we’ll explore how to create a custom Spliterator that implements shifting, sliding, zipping, and folding operations on streams, significantly enhancing your data processing capabilities.

Understanding Spliterators

Before we dive into the implementation, let’s briefly recap what a Spliterator is. Short for “splitable iterator,” a Spliterator is an object that traverses and partitions elements of a source. It’s designed to work seamlessly with the Stream API and supports parallel processing.

Why Custom Spliterators Matter

Custom Spliterators allow us to:

Extend stream functionality beyond built-in operations
Optimize performance for specific data processing patterns
Combine multiple operations efficiently
Create reusable, composable stream components

Implementing a Custom Spliterator

Our CustomSpliterator class will implement four key operations:

Shifting: Cyclically move elements in the stream
Sliding: Create windows of elements that slide through the stream
Zipping: Combine elements from two streams
Folding: Apply a cumulative operation to stream elements

Let’s break down each operation:

1. Shift Operation

public static <T> Stream<T> shift(Stream<T> stream, int offset) {
    Iterator<T> iterator = stream.iterator();
    Queue<T> queue = new LinkedList<>();
    for (int i = 0; i < offset && iterator.hasNext(); i++) {
        queue.add(iterator.next());
    }
    return StreamSupport.stream(new Spliterators.AbstractSpliterator<T>(Long.MAX_VALUE, Spliterator.ORDERED) {
        @Override
        public boolean tryAdvance(Consumer<? super T> action) {
            if (iterator.hasNext()) {
                queue.add(iterator.next());
                action.accept(queue.poll());
                return true;
            }
            return !queue.isEmpty() && queue.poll() != null;
        }
    }, false);
}

This method shifts the elements in the stream by a specified offset. It uses a queue to hold the shifted elements and advances the stream accordingly.

2. Slide Operation

public static <T> Stream<List<T>> slide(Stream<T> stream, int windowSize) {
    Iterator<T> iterator = stream.iterator();
    Deque<T> deque = new LinkedList<>();
    for (int i = 0; i < windowSize - 1 && iterator.hasNext(); i++) {
        deque.add(iterator.next());
    }
    return StreamSupport.stream(new Spliterators.AbstractSpliterator<List<T>>(Long.MAX_VALUE, Spliterator.ORDERED) {
        @Override
        public boolean tryAdvance(Consumer<? super List<T>> action) {
            if (iterator.hasNext()) {
                deque.add(iterator.next());
                if (deque.size() > windowSize) {
                    deque.pollFirst();
                }
                action.accept(new ArrayList<>(deque));
                return true;
            }
            return false;
        }
    }, false);
}

The slide operation creates overlapping windows of elements. It maintains a deque of the current window and slides it through the stream.

3. Zip Operation

public static <A, B> Stream<AbstractMap.SimpleEntry<A, B>> zip(Stream<A> streamA, Stream<B> streamB) {
    Spliterator<A> spliteratorA = streamA.spliterator();
    Spliterator<B> spliteratorB = streamB.spliterator();

    Iterator<A> iteratorA = Spliterators.iterator(spliteratorA);
    Iterator<B> iteratorB = Spliterators.iterator(spliteratorB);

    return StreamSupport.stream(new Spliterators.AbstractSpliterator<AbstractMap.SimpleEntry<A, B>>(
            Math.min(spliteratorA.estimateSize(), spliteratorB.estimateSize()), Spliterator.ORDERED) {
        @Override
        public boolean tryAdvance(Consumer<? super AbstractMap.SimpleEntry<A, B>> action) {
            if (iteratorA.hasNext() && iteratorB.hasNext()) {
                A a = iteratorA.next();
                B b = iteratorB.next();
                action.accept(new AbstractMap.SimpleEntry<>(a, b));
                return true;
            }
            return false;
        }
    }, false);
}

The zip operation combines elements from two streams into pairs. It advances both streams simultaneously, creating pairs until one of the streams is exhausted.

4. Fold Operation

public static <T, R> R fold(Stream<T> stream, R identity, BiFunction<R, T, R> accumulator) {
    Iterator<T> iterator = stream.iterator();
    R result = identity;
    while (iterator.hasNext()) {
        result = accumulator.apply(result, iterator.next());
    }
    return result;
}

The fold operation, also known as reduce, applies a cumulative operation to the stream elements. It’s a powerful tool for aggregating data.

Full Code:

import java.util.*;
import java.util.function.*;
import java.util.stream.*;

public class CustomSpliterator {

    public static <T> Stream<T> shift(Stream<T> stream, int offset) {
        Iterator<T> iterator = stream.iterator();
        Queue<T> queue = new LinkedList<>();
        for (int i = 0; i < offset && iterator.hasNext(); i++) {
            queue.add(iterator.next());
        }
        return StreamSupport.stream(new Spliterators.AbstractSpliterator<T>(Long.MAX_VALUE, Spliterator.ORDERED) {
            @Override
            public boolean tryAdvance(Consumer<? super T> action) {
                if (iterator.hasNext()) {
                    queue.add(iterator.next());
                    action.accept(queue.poll());
                    return true;
                }
                return !queue.isEmpty() && queue.poll() != null;
            }
        }, false);
    }

    public static <T> Stream<List<T>> slide(Stream<T> stream, int windowSize) {
        Iterator<T> iterator = stream.iterator();
        Deque<T> deque = new LinkedList<>();
        for (int i = 0; i < windowSize - 1 && iterator.hasNext(); i++) {
            deque.add(iterator.next());
        }
        return StreamSupport.stream(new Spliterators.AbstractSpliterator<List<T>>(Long.MAX_VALUE, Spliterator.ORDERED) {
            @Override
            public boolean tryAdvance(Consumer<? super List<T>> action) {
                if (iterator.hasNext()) {
                    deque.add(iterator.next());
                    if (deque.size() > windowSize) {
                        deque.pollFirst();
                    }
                    action.accept(new ArrayList<>(deque));
                    return true;
                }
                return false;
            }
        }, false);
    }

    public static <A, B> Stream<AbstractMap.SimpleEntry<A, B>> zip(Stream<A> streamA, Stream<B> streamB) {
        Spliterator<A> spliteratorA = streamA.spliterator();
        Spliterator<B> spliteratorB = streamB.spliterator();

        Iterator<A> iteratorA = Spliterators.iterator(spliteratorA);
        Iterator<B> iteratorB = Spliterators.iterator(spliteratorB);

        return StreamSupport.stream(new Spliterators.AbstractSpliterator<AbstractMap.SimpleEntry<A, B>>(
                Math.min(spliteratorA.estimateSize(), spliteratorB.estimateSize()), Spliterator.ORDERED) {
            @Override
            public boolean tryAdvance(Consumer<? super AbstractMap.SimpleEntry<A, B>> action) {
                if (iteratorA.hasNext() && iteratorB.hasNext()) {
                    A a = iteratorA.next();
                    B b = iteratorB.next();
                    action.accept(new AbstractMap.SimpleEntry<>(a, b));
                    return true;
                }
                return false;
            }
        }, false);
    }

    public static <T, R> R fold(Stream<T> stream, R identity, BiFunction<R, T, R> accumulator) {
        Iterator<T> iterator = stream.iterator();
        R result = identity;
        while (iterator.hasNext()) {
            result = accumulator.apply(result, iterator.next());
        }
        return result;
    }
}

here is the runner class

public class Day81 {
    public static void main(String[] args) {
        System.out.println("Shift example");
        List<Integer> list = Arrays.asList(1, 2, 3, 4, 5);
        Stream<Integer> shiftedStream = CustomSpliterator.shift(list.stream(), 2);
        shiftedStream.forEach(System.out::println);

        System.out.println("Slide example");
        Stream<List<Integer>> slidingStream = CustomSpliterator.slide(list.stream(), 3);
        slidingStream.forEach(System.out::println);

        System.out.println("Zip example");
        List<String> list2 = Arrays.asList("a", "b", "c");
        Stream<AbstractMap.SimpleEntry<Integer, String>> zippedStream = CustomSpliterator.zip(list.stream(), list2.stream());
        zippedStream.forEach(pair -> System.out::println(pair.getKey() + ", " + pair.getValue()));

        System.out.println("Fold example");
        Integer sum = CustomSpliterator.fold(list.stream(), 0, Integer::sum);
        System.out.println("Sum: " + sum);
    }
}

Example: Calculating Moving Average

Here’s a practical example of using our custom Spliterator to calculate a moving average:

List<Double> stockPrices = Arrays.asList(100.0, 102.0, 98.0, 103.0, 99.0, 101.0);
int windowSize = 3;

Stream<Double> movingAverages = CustomSpliterator.slide(stockPrices.stream(), windowSize)
    .map(window -> window.stream().mapToDouble(Double::doubleValue).average().orElse(0.0));

movingAverages.forEach(System.out::println);

This code efficiently calculates the 3-day moving average of stock prices using our custom sliding window operation.

Creating a custom Spliterator is an advanced technique that can significantly enhance your Java data processing capabilities. By combining shifting, sliding windows, zipping, and folding into a single, efficient component, we’ve created a powerful tool for complex data manipulation tasks.

As you implement these techniques in your projects, remember to consider the trade-offs. While custom Spliterators offer great flexibility and power, they can also introduce complexity. Always benchmark your implementations to ensure they provide the expected performance benefits.

Happy coding, and may your streams flow efficiently!

Day 80: From Concept to Code: Implementing a Dummy Consistent Hashing in Java using TreeMap

2024-05-23T00:00:00Z

As a software engineer working with distributed systems, ensuring efficient data distribution across nodes is crucial. Consistent hashing offers a robust solution for this challenge. This blog post will delve into a Java implementation of consistent hashing with unit tests, along with the key concepts and design decisions involved.

Understanding Consistent Hashing

Traditional hashing techniques often result in significant rehashing of keys when nodes are added or removed. Consistent hashing mitigates this by ensuring that only a small subset of keys are remapped. This property makes it highly suitable for scalable and fault-tolerant distributed systems.

Key Concepts

Fig: Consistent Hashing

Hash Function

A Hash Function is a mathematical algorithm that takes an input (or ‘message’) and returns a fixed-size string of bytes. The output is typically a hash code or hash value. The primary purpose of a hash function is to map data of arbitrary size to data of a fixed size. In the context of consistent hashing, the hash function is used to assign both data keys and node identifiers to positions on the hash ring.

The effectiveness of a hash function in consistent hashing depends on its ability to uniformly distribute the keys across the hash ring, minimizing the chances of collisions where two different inputs produce the same hash value. A good hash function ensures that the keys are spread evenly, which leads to efficient load balancing among nodes.

Hash Ring

The Hash Ring is a conceptual circular space that represents the range of possible hash values produced by the hash function. Imagine a circle where the hash values wrap around, creating a continuous loop. Both nodes (servers, caches, etc.) and data keys are hashed and placed on this ring.

When placing a data key on the ring, the system looks for the nearest node in the clockwise direction. This node is responsible for storing that key. The circular nature of the hash ring ensures that every key has a node assignment, and it allows for a smooth transition when nodes are added or removed. By using a circular space, consistent hashing efficiently handles node dynamics with minimal data reshuffling.

Virtual Nodes

Virtual Nodes (or “vnodes”) are logical subdivisions of physical nodes in the hash ring. Instead of each physical node being represented by a single point on the ring, it can be represented by multiple virtual nodes. Each virtual node is assigned a unique position on the hash ring.

Virtual nodes enhance the distribution of keys across the physical nodes, especially when there are a small number of physical nodes. They help achieve a more balanced load by mitigating the effects of uneven key distribution and ensuring that no single physical node becomes a bottleneck. When a physical node is added or removed, only the virtual nodes associated with that physical node need to be redistributed, leading to better fault tolerance and load balancing.

Replication

Replication in the context of consistent hashing refers to the practice of placing multiple copies of each node on the hash ring to ensure better distribution and fault tolerance. This is controlled by the numberOfReplicas parameter in our implementation.

By replicating nodes, we can distribute the keys more evenly across the hash ring. Each physical node is represented by several points (virtual nodes), and each point can independently take responsibility for a portion of the data. This approach also enhances fault tolerance: if a physical node fails, its virtual nodes can be easily reassigned to other physical nodes, ensuring that the data remains accessible. Replication minimizes the impact of node failures and ensures that the system can continue to function smoothly even when changes occur.

Problems Solved by Consistent Hashing

Scalability:

Allows the system to scale easily by adding or removing nodes with minimal impact on data distribution.

Load Balancing:

Distributes data evenly across nodes, preventing any single node from becoming a bottleneck.

Fault Tolerance:

Reduces the risk of data loss by redistributing data automatically when nodes fail.

Implementing Consistent Hashing in Java

We begin by defining the ConsistentHashing class. This class includes methods to add and remove nodes and to find the corresponding node for a given key. We use the SHA-256 algorithm for hashing to ensure a good distribution of hash values.

At first here I am considering

Weighted Nodes: Each node’s capacity is taken into account by adjusting the number of virtual nodes based on the node’s capacity. Nodes with higher capacities have more virtual nodes, ensuring a more balanced load distribution.
Dynamic Node Management: Methods to add and remove nodes dynamically, taking into account the node capacities and redistributing data as needed.
Replication and Quorum: Ensures data availability and consistency by writing to a quorum of nodes and reading from a quorum of nodes, even in the presence of node failures or removals. This enhanced implementation ensures that nodes with different capacities are effectively utilized, leading to a more balanced and efficient distributed system.

To implement this I am using a TreeMap. which uses the Red-Black tree inside it. Lets understand it a little bit.

Key Characteristics of TreeMap

Ordered:

TreeMap maintains its elements in ascending order, according to the natural ordering of its keys or by a comparator provided at map creation time.

NavigableMap Features:

It provides several methods to navigate the map, such as firstKey, lastKey, lowerKey, higherKey, subMap, headMap, and tailMap.

Internal Working

Red-Black Tree:

Internally, TreeMap uses a Red-Black tree, which is a self-balancing binary search tree. This ensures that the tree remains balanced, and the operations can be performed in logarithmic time.

Node Structure: Each node in the tree contains:

Key
Value
References to the left child, right child, and parent nodes
A color attribute (red or black) to maintain balance according to Red-Black tree properties

Key Characteristics of Red-Black tree

A Red-Black Tree is a type of self-balancing binary search tree. Each node in the tree contains an extra bit for storing its color, which can be either red or black. The color attribute helps maintain the balance of the tree during insertions and deletions. Here’s a detailed explanation:

Key Properties of Red-Black Trees Binary Search Tree Property: Like all binary search trees (BST), for each node, the value of the left child is less than its value, and the value of the right child is greater.

Red-Black Properties:

Property 1: Each node is either red or black.
Property 2: The root node is always black.
Property 3: All leaves (NIL nodes) are black. These are the null children of a leaf node, considered black for simplicity in maintaining tree properties.
Property 4: If a red node has children, then the children are always black (no two red nodes can be adjacent).
Property 5: Every path from a given node to any of its descendant leaves has the same number of black nodes (black-height).

Now let us see the use case of TreeMap to implement a Dummy consistent hashing

public class ConsistentHashingWithWeightedNodes {
    private final SortedMap<Integer, String> ring = new TreeMap<>();
    private final Map<String, Integer> nodeCapacities = new HashMap<>();
    private final int replicationFactor;
    private final int writeQuorum;
    private final int readQuorum;
    private final Map<String, Map<String, String>> dataStore = new HashMap<>();
    private final MessageDigest md5;

This defines the ConsistentHashingWithWeightedNodes class with the following fields:

ring: A SortedMap to represent the consistent hashing ring.
nodeCapacities: A Map to store each node’s capacity.
replicationFactor: Number of replicas for each data item.
writeQuorum: Minimum number of nodes that must acknowledge a write for it to be considered successful.
readQuorum: Minimum number of nodes that must be contacted to successfully read data.
dataStore: A nested Map to store the actual data on each node.
md5: An instance of MessageDigest for computing MD5 hashes.

    public ConsistentHashingWithWeightedNodes(Map<String, Integer> nodes, int replicationFactor, int writeQuorum, int readQuorum) throws NoSuchAlgorithmException {
        this.md5 = MessageDigest.getInstance("MD5");
        this.replicationFactor = replicationFactor;
        this.writeQuorum = writeQuorum;
        this.readQuorum = readQuorum;

This is the constructor of the ConsistentHashingWithWeightedNodes class. It initializes the md5 instance for hashing and sets the replication factor, write quorum, and read quorum.

        for (Map.Entry<String, Integer> entry : nodes.entrySet()) {
            addNode(entry.getKey(), entry.getValue());
        }
    }

The constructor adds all nodes from the input nodes map, which contains node names and their respective capacities, to the consistent hashing ring using the addNode method.

    private int hash(String key) {
        md5.update(key.getBytes());
        byte[] digest = md5.digest();
        return ByteBuffer.wrap(digest).getInt();
    }

This method computes the MD5 hash of a given key and converts it to an integer. The hash value is used to place nodes and data on the consistent hashing ring. Here the ByteBuffer is used for getting the output of digest array to an interger.

Let’s say the digest array contains the following bytes (in hexadecimal):

`1`	`digest = {0x12, 0x34, 0x56, 0x78, ...};`

When you call ByteBuffer.wrap(digest).getInt() the following steps occur:

Wrap the Byte Array:

ByteBuffer.wrap(digest) creates a ByteBuffer that points to the digest array.

Read an Integer:

getInt() reads the first four bytes: 0x12, 0x34, 0x56, 0x78. Since ByteBuffer uses big-endian order, these bytes are interpreted as the integer:0x12345678

In decimal, this value is 305419896.

So, the line ByteBuffer.wrap(digest).getInt() effectively converts the first four bytes of the digest array into an integer in a straightforward and readable manner.

Usage in Context

In the context of the hash function, this conversion is used to transform the MD5 hash (which is a 16-byte array) into a single integer value. This integer value is then used to place nodes and keys on the consistent hashing ring.

1
2
3

    public void addNode(String node, int capacity) {
        nodeCapacities.put(node, capacity);
        int virtualNodes = capacity; // Use capacity directly as the number of virtual nodes for simplicity

The addNode method adds a node to the consistent hashing ring. The number of virtual nodes for this node is determined by its capacity.

        for (int i = 0; i < virtualNodes; i++) {
            int hash = hash(node + "#" + i);
            ring.put(hash, node);
        }
    }

For each virtual node, the method computes its hash and adds it to the ring.

1
2

    public void removeNode(String node) {
        int virtualNodes = nodeCapacities.get(node);

The removeNode method removes a node and its virtual nodes from the ring. It first retrieves the number of virtual nodes based on the node’s capacity.

        for (int i = 0; i < virtualNodes; i++) {
            int hash = hash(node + "#" + i);
            ring.remove(hash);
        }
        
        nodeCapacities.remove(node);
    }

It then removes each virtual node from the ring and finally removes the node from the nodeCapacities map.

    private List<String> getNodesForKey(String key) {
        List<String> nodes = new ArrayList<>();
        int hash = hash(key);
        SortedMap<Integer, String> tailMap = ring.tailMap(hash);

The getNodesForKey method determines which nodes should store a given key. It first computes the hash of the key and finds the relevant segment in the ring.

        for (Map.Entry<Integer, String> entry : tailMap.entrySet()) {
            if (!nodes.contains(entry.getValue())) {
                nodes.add(entry.getValue());
                if (nodes.size() == replicationFactor) {
                    return nodes;
                }
            }
        }

It iterates through the tail map (the part of the ring starting from the key’s hash) and adds nodes to the list until the replication factor is met.

        for (Map.Entry<Integer, String> entry : ring.entrySet()) {
            if (!nodes.contains(entry.getValue())) {
                nodes.add(entry.getValue());
                if (nodes.size() == replicationFactor) {
                    break;
                }
            }
        }

        return nodes;
    }

If the tail map does not contain enough nodes, it continues from the beginning of the ring until it has enough nodes to meet the replication factor.

    public boolean writeData(String key, String value) {
        List<String> nodes = getNodesForKey(key);
        int successCount = 0;
        for (String node : nodes) {
            if (writeToNode(node, key, value)) {
                successCount++;
                if (successCount >= writeQuorum) {
                    return true;
                }
            }
        }
        return false;
    }

The writeData method writes data to the nodes responsible for the key. It retrieves the nodes using getNodesForKey and writes to each node until the write quorum is met.

    private boolean writeToNode(String node, String key, String value) {
        if (!dataStore.containsKey(node)) {
            dataStore.put(node, new HashMap<>());
        }
        dataStore.get(node).put(key, value);
        return true;
    }

The writeToNode method actually writes the key-value pair to the node’s data store. If the node does not already have a data store, it creates one.

    public String readData(String key) {
        List<String> nodes = getNodesForKey(key);
        Map<String, Integer> valueCounts = new HashMap<>();
        for (String node : nodes) {
            String value = readFromNode(node, key);
            if (value != null) {
                valueCounts.put(value, valueCounts.getOrDefault(value, 0) + 1);
                if (valueCounts.get(value) >= readQuorum) {
                    return value;
                }
            }
        }
        return "No Data Found";
    }

The readData method reads data for a given key from the responsible nodes. It counts the occurrences of each value read and returns the value if it meets the read quorum.

    private String readFromNode(String node, String key) {
        if (dataStore.containsKey(node)) {
            return dataStore.get(node).get(key);
        }
        return null;
    }

The readFromNode method retrieves the value for a key from a specific node’s data store.

    public static void main(String[] args) throws NoSuchAlgorithmException {
        Map<String, Integer> nodes = new HashMap<>();
        nodes.put("Node1", 1); // Capacity 1
        nodes.put("Node2", 3); // Capacity 3
        nodes.put("Node3", 2); // Capacity 2

        int replicationFactor = 3;
        int writeQuorum = 2;
        int readQuorum = 2;

        ConsistentHashingWithWeightedNodes ch = new ConsistentHashingWithWeightedNodes(nodes, replicationFactor, writeQuorum, readQuorum);

        System.out.println("Writing data...");
        System.out.println("Write key1: " + ch.writeData("key1", "value1"));
        System.out.println("Write key2: " + ch.writeData("key2", "value2"));
        System.out.println("Write key3: " + ch.writeData("key3", "value3"));

        System.out.println("Reading data...");
        System.out.println("Read key1: " + ch.readData("key1"));
        System.out.println("Read key2: " + ch.readData("key2"));
        System.out.println("Read key3: " + ch.readData("key3"));

        ch.addNode("Node4", 5); // Adding a new node with higher capacity
        System.out.println("Write key4 after adding Node4: " + ch.writeData("key4", "value4"));

        ch.removeNode("Node2");
        System.out.println("Read key2 after removing Node2: " + ch.readData("key2"));
    }
}

The main method demonstrates the usage of the ConsistentHashingWithWeightedNodes class. It:

Creates a map of nodes with different capacities.
Initializes the consistent hashing ring with these nodes.
Writes some data and prints the results.
Reads the data

Here I discussed about Replication Factor and Quorum. Will discuss them in details in some later post. For now posting some resource for further learning consistent hashing, Red-Black tree, Replication and Quorum.

Consistent Hashing :

Red-Black Tree :

Replication In the context of Consistent hashing :

Quorum :

Day 79: Did you know that too much print statement can cost you money

2024-05-03T00:00:00Z

In this twitter post https://x.com/ekzhang1/status/1785886484140065087 the author saved $27000/year by removing 10 lines of code they were print() statements. So I just wondered as he did it for python does java printing causes lot of processing time? and if so how about writing the same string in a file. This question let me down a rabbit hole of how printing works in java

Many developers, especially those new to Java, often rely on System.out.println() for debugging and logging purposes. While this approach is convenient during development, it can become a performance hindrance in production environments, particularly when dealing with high-volume logging scenarios.

The Problem with `System.out.println()`

The System.out.println() method is a synchronous operation that involves several steps:

Acquiring a lock: Before writing to the console, the method must acquire a lock on the System.out object to ensure thread safety.
String concatenation: If the argument passed to println() is not a string, it must be converted to a string using the toString() method, which can be a costly operation for complex objects.
Writing to the console: The actual writing of the string to the console stream occurs in this step.
Flushing the stream: After writing, the console stream is flushed to ensure that the data is immediately visible.
Releasing the lock: Finally, the lock on the System.out object is released.

While these steps may seem trivial, they can introduce significant overhead, especially when logging is performed extensively in performance-critical sections of the code.

Furthermore, If we look into why System.out.println() is slow we will find some stackoverflow discussion about it. From one of it’s discussion I came to know printing to the console (using println) is slow because of the operating system overhead, not the act of printing itself. They compare it to saving a file, which is similar speed. The slowdown comes from the console displaying characters one by one, including rendering fonts and potentially scrolling the screen.

Fortunately, Java provides more efficient alternatives for logging, including writing to files and using dedicated logging libraries like Log4j.

Writing to a File

Writing log messages directly to a file can be more efficient than printing to the console. Here’s an example code snippet:

import java.io.BufferedWriter;
import java.io.FileWriter;
import java.io.IOException;

public class FileLogger {
    private static final String LOG_FILE = "application.log";

    public static void main(String[] args) {
        try (BufferedWriter writer = new BufferedWriter(new FileWriter(LOG_FILE, true))) {
            for (int i = 0; i < 1000000; i++) {
                writer.write("Hello World " + i + "\n");
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

In this example, we create a BufferedWriter to write log messages to a file named application.log. The BufferedWriter helps improve performance by buffering the data before writing it to the file. However, manually managing file I/O operations can be cumbersome and error-prone, especially in multithreaded environments.

Using Log4j with Console Appender

Log4j is a widely-used logging library that provides a robust and configurable logging solution. Instead of writing directly to the console or a file, Log4j allows you to configure various appenders (output destinations) and log levels. Here’s an example of using Log4j with a console appender:

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class Log4jExample {
    private static final Logger logger = LogManager.getLogger(Log4jExample.class);

    public static void main(String[] args) {
        for (int i = 0; i < 1000000; i++) {
            logger.info("Hello World " + i);
        }
    }
}

In this example, we use the LogManager class to obtain a Logger instance for the Log4jExample class. The logger.info() method is used to log messages at the INFO level. Log4j provides various log levels (e.g., DEBUG, INFO, WARN, ERROR) and allows you to configure the desired log level and appenders through configuration files or programmatically.

Log4j offers several advantages over System.out.println():

Asynchronous logging: Log4j can buffer log messages and write them asynchronously, reducing the impact on the main application thread.
Configurability: Log4j allows you to configure various appenders (e.g., file, console, database), log levels, and formatting options.
Performance optimization: Log4j employs techniques like message construction avoidance, which means that log messages are only constructed if they meet the configured log level, reducing unnecessary string operations.

Benchmarking with JMH

To put these claims to the test, we’ll use the Java Microbenchmark Harness (JMH), a powerful tool for benchmarking Java code. Here’s an example of how we can benchmark the three techniques discussed above:

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@State(Scope.Thread)
public class Day79 {
    private static final Logger logger = LogManager.getLogger(Day79.class);
    private static final String LOG_FILE = "logfile.txt";
    int numIterations = 100000;

    @Benchmark
    public void systemOutPrintln() {
        for (int i = 0; i < numIterations; i++) {
            System.out.println("Hello World!");
        }
    }

    @Benchmark
    public void writeToFile() throws IOException {
        try {
            Path path = Paths.get(LOG_FILE);
            Files.createFile(path);

            List<String> lines = new ArrayList<>(Collections.nCopies(numIterations, "Hello World"));

            Files.write(path, lines, StandardOpenOption.APPEND);

            System.out.println("File written successfully.");
        } catch (IOException e) {
            System.err.println("Error writing to file: " + e.getMessage());
        }
    }

    @Benchmark
    public void log4jConsoleAppender() {
        for (int i = 0; i < numIterations; i++) {
            logger.info("Hello World!");
        }
    }
}

In this example, we define three benchmark methods: systemOutPrintln(), writeToFile(), and log4jConsoleAppender(). Each method represents one of the logging techniques we want to benchmark.

The @BenchmarkMode annotation specifies that we want to measure the average time taken by each method. The @OutputTimeUnit annotation sets the time unit for the benchmark results to nanoseconds. Finally, the @State(Scope.Thread) annotation ensures that each benchmark method is executed in a separate thread.

After running the benchmark, we should see results similar to the following:

Run complete. Total time: 00:26:52
Benchmark                         Mode  Cnt     Score     Error  Units
Day79.log4jConsoleAppender  avgt   25     0.121 ±   0.004  ms/op
Day79.systemOutPrintln      avgt   25  4089.977 ± 417.122  ms/op
Day79.writeToFile           avgt   25     0.346 ±   0.071  ms/op

The results are given in milliseconds per operation (ms/op), which means how many milliseconds it takes on average to perform one operation. The lower the ms/op, the faster the operation.
Day79.log4jConsoleAppender: This operation takes on average 0.121 ms/op. This is the fastest operation among the three.
Day79.systemOutPrintln: This operation takes on average 4089.977 ms/op. This is significantly slower than the other two operations.
Day79.writeToFile: This operation takes on average 0.346 ms/op. This is slower than log4jConsoleAppender but much faster than systemOutPrintln.
The ± value represents the error in the measurement. It means the actual value could be within this range. For example, for writeToFile, the actual average could be between (0.346 - 0.071) and (0.346 + 0.071).

These results clearly show that System.out.println() is significantly slower than the Log4j console appender, and writing to a file is the slowest option among the three.

Conclusion

In this blog post, we explored the performance implications of using System.out.println() for logging in Java applications. We discussed more efficient alternatives, such as writing to files and using dedicated logging libraries like Log4j. Additionally, we provided benchmark results using JMH to demonstrate the performance differences between these techniques.

While System.out.println() may be convenient for simple debugging during development, it should be avoided in performance-critical scenarios or production environments. Instead, consider using a logging library like Log4j, which offers better performance, configurability, and flexibility.

Day 78: Java 22 - Embracing Safe Memory Allocation Using FFM API - An alternative to Unsafe API

2024-04-18T00:00:00Z

In my previous blog post I talked about Java Unsafe API and how to use it to make a Memory Allocator. Now as Java 22 released new FFM API is here to provide safety that we didnt had while using Java Unsafe API to allocate off the heap memory. In this post I will discuss about the new api and how it works and how we can use this to create safe memory allocator.

MemorySegment API and Arena in Java FFM

The Foreign Function and Memory (FFM) API introduced in Java 20 allows Java programs to interoperate with code and data outside of the Java runtime. This API provides a safer and more controlled way to interact with native code compared to JNI. One of the key components of the FFM API is the MemorySegment API, which provides a Java representation of off-heap memory. Arena, on the other hand, is a memory management construct that controls the lifecycle of memory segments.

MemorySegment API

A MemorySegment object represents a contiguous block of off-heap memory. It provides methods to allocate, deallocate, access, and deallocate memory. Memory segments are language-agnostic, meaning they can be used to hold any type of data, not just Java objects.

Here are some of the key features of the MemorySegment API:

Allocation and Deallocation:

Memory segments can be allocated in various ways, including fixed-size allocations and allocations that grow or shrink as needed.

Access:

Memory segments can be accessed using Java byte buffers, which provide a familiar way to work with raw memory.

Deallocation:

Memory segments can be explicitly deallocated when they are no longer needed. This helps to avoid memory leaks.

Arena

An Arena is a memory management construct that simplifies the lifecycle management of memory segments. It provides a pool of memory that can be used to allocate memory segments. Arenas can be configured with different memory allocation strategies and deallocation behavior.

Here are some of the key benefits of using arenas:

Improved Memory Management:

Arenas simplify memory management by providing a centralized pool of memory for allocation.

Reduced Memory Fragmentation:

Arenas can help to reduce memory fragmentation by allocating memory segments from a contiguous block.

Thread Safety:

Arenas are thread-safe, meaning that multiple threads can safely allocate and deallocate memory segments from the same arena.

An arena manages access to native memory and ensures that allocated memory blocks are released again and that we do not access memory that has already been released.

There are four types of arenas that we can create using static factory methods of the Arena class:

Global arena
Automatic arenas (managed by the garbage collector)
Confined arenas
Shared arenas

Memory Allocator and De-allocator with Arena and MemorySegment

Here’s an example of a simple memory allocator and de-allocator class that uses an Arena to allocate and deallocate memory segments for writing strings:

import java.lang.foreign.*;

public class MemoryAllocator {

    private static final Arena arena = Arena.create();

    public static MemorySegment allocate(int size) {
        return arena.allocate(size);
    }

    public static void deallocate(MemorySegment segment) {
        segment.close();
    }
}

now using the MemoryAllocator class

    public Class Day78 {
        public static void main(String[] args) {
        
        //Initialize
        MemorySegment segment = allocate(100);

        //write hello world to the initialized memory segment
        segment.getByteBuffer(0, 100).put("Hello, world!".getBytes());

        //read from the memory segment
        byte[] bytes = new byte[100];
        segment.getByteBuffer(0, 100).get(bytes);
        String message = new String(bytes);
        System.out.println(message);

        // deallocate the memorySegment
        deallocate(segment);
    }
}

Here private static final Arena arena = Arena.create(); This line creates a single, static instance of Arena and assigns it to the arena field. An Arena is a memory pool used to allocate memory segments. Since this is declared static and final, only one Arena instance is created for the entire class and its behavior cannot be changed after initialization.

public static MemorySegment allocate(int size) This is a public static method named allocate. It takes an integer size as input and returns a MemorySegment object. This method delegates the allocation task to the arena instance by calling arena.allocate(size). It essentially requests a block of off-heap memory of the specified size from the Arena pool.

public static void deallocate(MemorySegment segment) This is another public static method named deallocate. It takes a MemorySegment object as input and doesn’t return any value (void). This method calls segment.close() to release the memory segment back to the Arena pool. It signifies that the allocated memory is no longer needed.

For further learning you can visit this java documentation. https://docs.oracle.com/en/java/javase/20/core/foreign-function-and-memory-api.html#GUID-1CA5C639-6C65-45A7-85E5-7926DB0D6A32

Day 77: Explore Something Unsafe : Crafting a Memory allocator using Java Unsafe API

2024-03-14T00:00:00Z

In the realm of Java development, the sun.misc.Unsafe API stands as both a powerful tool and a notorious enigma. It offers a direct interface to native memory and low-level operations, granting developers unprecedented control over memory management and object manipulation. While officially designated as “unsafe” due to its potential for misuse, this API remains indispensable in certain scenarios, enabling performance optimizations and facilitating the implementation of critical functionality in numerous Java libraries and frameworks.

Understanding the Intricacies of Unsafe API

At its core, the Unsafe API provides a means to perform operations typically restricted by the Java Virtual Machine (JVM) for safety reasons. These operations include direct memory access, object allocation and manipulation, thread synchronization, and more. By bypassing the usual safeguards of the JVM, developers can achieve performance gains and implement functionalities that would otherwise be impossible or impractical within the confines of standard Java.

One of the primary use cases of the Unsafe API is for off-heap memory management. Unlike Java’s managed heap, which is subject to garbage collection and automatic memory management, off-heap memory managed via Unsafe offers greater control and reduced overhead. This is particularly beneficial in scenarios requiring predictable memory allocation and deallocation, such as high-performance computing, networking, and database systems.

sun.misc.Unsafe API in Java provides access to low-level, unsafe operations typically reserved for the JVM. It exposes methods that allow direct manipulation of memory, objects, and threads, bypassing some of Java’s built-in safety mechanisms. Here’s how it works and what it enables:

Memory Operations
Object Manipulation
Array Operations
Synchronization
Class and Native memory operations

Unsafe: Bypassing the Guardrails

Java enforces memory safety through garbage collection and automatic memory management. The Unsafe API circumvents these mechanisms, allowing direct manipulation of memory addresses. This capability unlocks several functionalities:

Memory Allocation and Deallocation: You can allocate off-heap memory (outside the JVM’s managed heap) for performance-critical tasks. This is useful for large data structures or handling native data types.
Field and Array Manipulation: The Unsafe API allows direct access and modification of fields and array elements, even if they are declared private or final. This can be helpful for performance optimization or implementing custom data structures.
Thread Management: Unsafe provides low-level control over thread scheduling and synchronization. This is rarely used in practice due to the complexity and potential for race conditions.

Unsafe and Native Memory: A Delicate Dance

The Unsafe API interacts with native memory (memory managed by the operating system) through pointers. These pointers hold memory addresses that the Unsafe API can use to:

Access Native Data Structures: You can interact with C libraries or legacy code that relies on native data structures. The Unsafe API allows you to convert Java objects to their corresponding native memory representation for seamless data exchange.
Memory-Mapped Files: Memory-mapped files allow you to work with a file as if it were part of your program’s virtual memory. The Unsafe API facilitates this by creating mappings between file regions and memory addresses.

we will dive deep on the Native memory operations by writing a memory allocator and deallocator and using it to write something directly to the memory.

import sun.misc.Unsafe;

public class CustomMemoryAllocator {
    private static final Unsafe unsafe = Unsafe.getUnsafe();
    private static final long BASE_OFFSET = unsafe.arrayBaseOffset(byte[].class);

    public static long allocateMemory(long bytes) {
        return unsafe.allocateMemory(bytes);
    }

    public static void freeMemory(long address) {
        unsafe.freeMemory(address);
    }

	public static void writeData(long address, byte[] data) { 
		for (int i = 0; i < data.length; i++) { 
			unsafe.putByte(address + i, data[i]); 
			} 
		}
	public static byte[] readData(long address, int length) { 
		byte[] data = new byte[length]; 
		for (int i = 0; i < length; i++) { 
			data[i] = unsafe.getByte(address + i); 
		} 
		return data; 
	}
}

Here we are acquiring a static reference to the Unsafe object, the gateway for direct memory operations. - private static final long BASE_OFFSET = unsafe.arrayBaseOffset(byte[].class);: Determines the starting offset of byte arrays within memory, crucial for efficient manipulation.

The unsafe.arrayBaseOffset(byte[].class)This is a method call on the unsafe object. The arrayBaseOffset method retrieves the base offset of the given array type. In this case, it’s finding the base offset for byte[] arrays.

Then allocateMemory(long bytes) - Requests a memory block of the specified size from the operating system, bypassing JVM’s heap. It returns a memory address representing the allocated block’s start.

Then freeMemory(long address): Deallocates the memory block associated with the given address, relinquishing it back to the OS. Crucial for preventing memory leaks in custom allocation scenarios.

Now let us use this to write string into an allocated memory and then free the memory

public class Day77 {

    public static void main(String[] args) {
        long address = CustomMemoryAllocator.allocateMemory(1024); // Allocate 1 KB of memory
        
        if (address != 0) { // Ensure memory allocation was successful
            System.out.println("Memory allocated successfully at address: " + address);
            
            // Write data to the allocated memory
            CustomMemoryAllocator.writeData(address, "Hello, World!".getBytes());
            
            // Read data from the allocated memory
            byte[] data = CustomMemoryAllocator.readData(address, 13); // Read 13 bytes
            System.out.println("Data read from memory: " + new String(data));
            
            // Free the allocated memory
            CustomMemoryAllocator.freeMemory(address);
            System.out.println("Memory freed successfully.");
        } else {
            System.err.println("Failed to allocate memory.");
        }
    }
}

In the above code we can see that we are storing the data and getting an address and if the memory allocation is successful then we write the data in the given address and then after reading it and printing it we deallocate the memory and clean it. This all are maintained by the run time and garbage collector.

Day 76: Implementing a dummy Service Oriented Architecture (SOA) service to Understand Java Service Provider Interface (SPI)

2024-01-26T00:00:00Z

Service Provider Interface (SPI) that plays a pivotal role in enhancing modularity, extensibility, and maintainability of Java applications. In this blog post, we will delve into the intricacies of SPI, explore its real-world applications, and elucidate why it has become indispensable in modern software development.

Understanding the SPI:

The Service Provider Interface is a framework in Java that facilitates the development of service-oriented architectures. At its core, SPI defines a contract between service providers and consumers, allowing for the dynamic loading of implementations without altering the client code. This decoupling of interface and implementation is instrumental in achieving modularity and fosters the creation of pluggable components within a software system.

At the heart of SPI is the java.util.ServiceLoader class, which acts as the service provider discovery mechanism. By employing SPI, developers can design extensible and modular systems that can be easily extended or modified without requiring changes to the existing codebase.

Now let us understand what is Service Oriented Architecture (SOA) means:

Service Oriented Architecture (SOA)

Service Oriented Architecture (SOA) is a design approach that structures software applications as a collection of services that are loosely coupled and interoperable. In SOA, services are self-contained, modular units that perform specific business functionalities and communicate with each other over a network. These services can be developed using different programming languages and technologies, as long as they agree upon to a common communication protocol, such as HTTP or SOAP.

At the core of SOA is the concept of service autonomy, which means that each service is independent and can be developed, deployed, and scaled independently of other services. This enables greater flexibility and agility in software development, as changes or updates to one service do not require modifications to other services

Example:

Now for a real world example we will create a simple example of a service-oriented architecture using Java Service Provider Interface (SPI). In this example, we’ll develop a basic payment processing system with multiple payment gateways. The main application will be the client, and various payment gateways will act as service providers.

1
2
3

public interface PaymentGateway { 
	void processPayment(double amount); 
}

this will be the service interface.

Now we will implement two Service Providers for this service interface and those are

PayPal Service Provider
Stripe Service Provider

import java.net.HttpURLConnection;
import java.net.URL;

public class PayPalGateway implements PaymentGateway {
    private static final String PAYPAL_API_ENDPOINT = "https://api.paypal.com/processPayment";

    @Override
    public void processPayment(double amount) {
        System.out.println("Processing payment of $" + amount + " using PayPal Gateway");

    
        try {
            URL url = new URL(PAYPAL_API_ENDPOINT);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");

            // logic
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                System.out.println("Payment processed successfully with PayPal");
            } else {
                System.out.println("Payment processing failed with PayPal. Response code: " + responseCode);
            }
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("Error processing payment with PayPal: " + e.getMessage());
        }
    }
}

now lets implement the Stripe Payment Service Provider

import java.net.HttpURLConnection;
import java.net.URL;

public class StripeGateway implements PaymentGateway {
    private static final String STRIPE_API_ENDPOINT = "https://api.stripe.com/processPayment";

    @Override
    public void processPayment(double amount) {
        System.out.println("Processing payment of $" + amount + " using Stripe Gateway");

        // Call Stripe API to process the payment
        try {
            URL url = new URL(STRIPE_API_ENDPOINT);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");

            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                System.out.println("Payment processed successfully with Stripe");
            } else {
                System.out.println("Payment processing failed with Stripe. Response code: " + responseCode);
            }
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("Error processing payment with Stripe: " + e.getMessage());
        }
    }
}

Now we need to configure the service provider by Service Provider Configuration: META-INF/services/com.example.PaymentGateway

Create a file named META-INF/services/com.example.PaymentGateway in your project resources. In this file, specify the fully qualified names of your payment gateway implementations like this:

1
2

com.example.PayPalGateway 
com.example.StripeGateway

Now in the main class where we will call the Service providers using Service Loader

import java.util.ServiceLoader;

public class Day76 {
    public static void main(String[] args) {
        double amount = 100.0; // Payment amount

        // Load payment gateways using ServiceLoader
        ServiceLoader<PaymentGateway> serviceLoader = ServiceLoader.load(PaymentGateway.class);

        // Process payment using each loaded payment gateway
        for (PaymentGateway paymentGateway : serviceLoader) {
            paymentGateway.processPayment(amount);
        }
    }
}

In this example, the PaymentProcessor client application dynamically loads and utilizes different payment gateway implementations without having direct dependencies on them. The service provider configurations allow you to easily extend the system with new payment gateways by adding their implementations and updating the configuration file.

But there are some pros and cons of SPI and knowing about those will help us correctly use this API

The Java Service Provider Interface (SPI) is a mechanism that facilitates the development of service-oriented architectures by providing a way for services to be implemented and loaded dynamically at runtime. Like any technology, Java SPI comes with its own set of advantages and drawbacks. Let’s explore the pros and cons of using Java SPI:

Pros:

Dynamic Service Loading:

One of the primary advantages of Java SPI is its ability to dynamically load service implementations without modifying the client code. This promotes modularity and allows for the easy addition or removal of services during runtime, fostering flexibility in the application’s architecture.

Decoupling of Components:

SPI enables a clear separation between service interfaces and their implementations. This decoupling ensures that changes to service implementations do not impact the client code, promoting a clean and modular design. It facilitates the creation of loosely coupled, pluggable components.

Easily Extensible:

Java SPI provides an easy and standardized way to extend the functionality of an application. New service implementations can be added by creating a new provider class and updating the service provider configuration file without affecting existing code.

Collaboration and Ecosystem:

SPI encourages collaboration among development teams by allowing them to provide and consume services independently. This collaborative nature fosters the creation of a rich ecosystem of interchangeable components and plugins.

Service Discovery:

The ServiceLoader class simplifies service discovery, making it straightforward for the application to locate and load available service implementations. This is especially beneficial in large-scale applications with numerous services.

Cons:

Limited Compile-Time Checking:

Since the service provider and implementation relationship is established at runtime, there is limited compile-time checking for correctness. This can lead to issues such as missing or incorrectly configured service providers, which may only become apparent during runtime.

Reflection Overhead:

Java SPI relies on reflection to load service implementations dynamically. Reflection can introduce runtime overhead, potentially affecting performance. However, the impact is generally minimal unless the application involves a large number of service providers.

Global Configuration File:

The service provider configuration file (META-INF/services) is a global file that lists all available service implementations. In scenarios with multiple modules or libraries, conflicts may arise if different modules define service providers with the same fully qualified names.

Limited Metadata:

SPI does not provide built-in support for metadata associated with service implementations. Developers might need to rely on conventions or additional mechanisms to convey metadata information about services.

ServiceLoader Limitations:

The ServiceLoader API has some limitations, such as a lack of support for specifying the order in which service providers should be loaded. This may be a concern in cases where the order of service providers is crucial.

Day 75: Java BufferedReader: Do We Know Why We Need To Close It?

2024-01-02T00:00:00Z

In this blog post, I will shine a spotlight on the significance of closing a Java BufferedReader after its creation, exploring the inner workings of BufferedReader, its implications, and offering practical insights to enhance your coding practices.

Understanding BufferedReader:

Java’s BufferedReader class is a versatile tool for efficient reading of text from a character-based input stream. One of its defining features is the ability to buffer input, enhancing performance by reducing the number of I/O operations. While it offers enhanced reading capabilities, developers must exercise caution, ensuring that the BufferedReader is closed once its purpose is served.

The Consequences of Neglecting Closure:

Failing to close a BufferedReader can lead to resource leaks and adverse consequences for your application. Java’s garbage collector is responsible for reclaiming resources, but it may not be immediate or deterministic. A resource leak can accumulate over time, impacting the overall performance and reliability of your application. Furthermore, in scenarios where the code interacts with external systems or files, leaving the BufferedReader unclosed can lead to file locks and other resource contentions, causing unintended issues.

Performance Issues:

Memory Usage:

An unclosed BufferedReader can lead to increased memory usage over time. The buffer associated with the reader retains resources until the garbage collector decides to reclaim them. In the absence of explicit closure, these resources may persist longer than necessary, contributing to higher memory consumption.

Now let us see a code example where not closing the BufferedReader can cause high memory usage.

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;

public class Day75 {
    public static void main(String[] args) throws IOException {
        BufferedReader bufferedReader = new BufferedReader(new FileReader("sample.txt"));
        StringBuilder content = new StringBuilder();

        String line;
        while ((line = bufferedReader.readLine()) != null) {
            content.append(line).append(System.lineSeparator());
        }

        // Imagine forgetting to close the BufferedReader
        // bufferedReader.close(); // Uncommenting this line is crucial

        // Do something with the content, if needed
        System.out.println("File Content:\n" + content.toString());
    }
}

In this example we can see that after reading from the file if we dont close the buffered reader it will keep the reference of the buffered reader from getting garbage collected and thus will have the allocated memory intact, though we dont need the file data and buffered reader instance memory.

File Descriptor Exhaustion:

Let us first understand what a file descriptor is.

File Descriptor :

A file descriptor is a low-level integer value that uniquely identifies an open file within a process in a Unix-based operating system. It serves as a handle or reference to an open file or I/O resource, and it is used by the operating system to keep track of various properties and status information associated with the file.

File descriptors are represented as non-negative integers. Standard input, output, and error have the file descriptor values 0, 1, and 2, respectively. Additional file descriptors are typically assigned starting from 3 and incrementing for each new open file.

In Java, while the concept of file descriptors exists at the operating system level, Java itself abstracts many details through higher-level constructs like streams and readers/writers. When working with Java’s I/O classes, you often don’t directly deal with file descriptors, but the underlying operating system still manages them behind the scenes

When dealing with file-based input streams, each open file consumes a file descriptor. Failing to close a BufferedReader means leaving file descriptors unclosed. In scenarios where the application handles a large number of files or operates for an extended period, this can result in file descriptor exhaustion. Once the system runs out of available file descriptors, it may fail to open new files, causing unexpected errors and disruptions.

Now let us see a code example for this

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;

public class Day75 {

    public static void main(String[] args) {
        for (int i = 1; i <= 1000; i++) {
            readFromFile("file" + i + ".txt");
        }
    }

    private static void readFromFile(String filePath) {
        BufferedReader bufferedReader = null;
        try {
            bufferedReader = new BufferedReader(new FileReader(filePath));

            String line;
            while ((line = bufferedReader.readLine()) != null) {
                // Process the content (in this example, we are just printing it)
                System.out.println(line);
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            // Missing: Properly close the BufferedReader
            // Uncomment the following line to avoid file descriptor exhaustion
            // try { bufferedReader.close(); } catch (IOException e) { e.printStackTrace(); }
        }
    }
}

In this example:

The main method iterates over a range of file names (e.g., “file1.txt”, “file2.txt”, …, “file1000.txt”).

The readFromFile method is responsible for reading the content from each file using a BufferedReader.

The BufferedReader is not properly closed in the finally block, simulating a scenario where developers forget to close the resource.

To see the impact of file descriptor exhaustion, you can run this program in an environment where there is a limit on the number of allowed open file descriptors. After running for some time, the program may encounter issues due to the exhaustion of file descriptors.

To avoid file descriptor exhaustion, it’s crucial to close resources properly. Uncommenting the bufferedReader.close(); line in the finally block ensures that the file descriptor associated with each BufferedReader is released after reading from the file.

Resource Contention:

In cases where the code interacts with external resources, such as databases or network connections, leaving the BufferedReader unclosed can lead to resource contention. This occurs when the resources are not released promptly, and subsequent operations may be delayed or blocked due to the lingering open connections.

Resource contention occurs in computing when multiple processes or threads compete for access to a shared resource, and this competition leads to delays, reduced performance, or potential deadlocks. A shared resource can be any entity that is accessed or modified by multiple concurrent operations, such as files, database connections, network sockets, or even sections of memory.

Now let us see a code example

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;

public class Day75 {

    private static final String FILE_PATH = "shared-file.txt";

    public static void main(String[] args) {
        // Create two threads that read from the same file
        Thread thread1 = new Thread(() -> readFromFile());
        Thread thread2 = new Thread(() -> readFromFile());

        // Start the threads
        thread1.start();
        thread2.start();
    }

    private static void readFromFile() {
        BufferedReader bufferedReader = null;

        try {
            bufferedReader = new BufferedReader(new FileReader(FILE_PATH));

            String line;
            while ((line = bufferedReader.readLine()) != null) {
                // Simulate reading from the file (e.g., processing the line)
                System.out.println(Thread.currentThread().getName() + ": " + line);
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            // Missing: Properly close the BufferedReader
            // Uncomment the following line to avoid resource contention
            // try { bufferedReader.close(); } catch (IOException e) { e.printStackTrace(); }
        }
    }
}

The main method creates two threads (thread1 and thread2) that concurrently attempt to read from the same file (shared-file.txt).

The readFromFile method is responsible for reading the content from the file using a BufferedReader.

The BufferedReader is not properly closed in the finally block, simulating a scenario where developers forget to close the resource, leading to resource contention.

To observe the resource contention, run this program and observe the empty output from both threads. Uncommenting the bufferedReader.close(); line in the finally block ensures that the resource contention is mitigated by properly closing the BufferedReader. Without proper closure, multiple threads may interfere with each other, leading to unpredictable and undesirable outcomes.

Resource Leaks:

File Locks:

When reading from files, especially in a multi-threaded environment, failing to close a BufferedReader can result in file locks not being released. This is critical because file locks prevent other processes or threads from accessing the file. Over time, accumulating file locks due to unclosed readers can lead to contention and potential deadlock situations.

In the above example of Resource contention can generate file locks that will prevent other instances of buffered reader to get the file to read.

Network Resource Leaks:

When dealing with network-related input streams, such as reading from a URL, leaving the BufferedReader unclosed can result in resource leaks in the network stack. This may lead to issues such as connection leaks, where network resources are not released promptly, affecting the application’s ability to establish new connections.

Now let us see a code example for this

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;

public class NetworkResourceLeakExample {

    private static final String URL_STRING = "https://www.example.com";

    public static void main(String[] args) {
        // Create two threads that read from the same URL
        Thread thread1 = new Thread(() -> readFromURL());
        Thread thread2 = new Thread(() -> readFromURL());

        // Start the threads
        thread1.start();
        thread2.start();
    }

    private static void readFromURL() {
        BufferedReader bufferedReader = null;

        try {
            URL url = new URL(URL_STRING);
            bufferedReader = new BufferedReader(new InputStreamReader(url.openStream()));

            String line;
            while ((line = bufferedReader.readLine()) != null) {
                // Simulate reading from the URL (e.g., processing the line)
                System.out.println(Thread.currentThread().getName() + ": " + line);
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            // Missing: Properly close the BufferedReader
            // Uncomment the following line to avoid network resource leak
            // try { bufferedReader.close(); } catch (IOException e) { e.printStackTrace(); }
        }
    }
}

The main method creates two threads (thread1 and thread2) that concurrently attempt to read from the same URL (https://www.example.com).

The readFromURL method is responsible for reading the content from the URL using a BufferedReader.

The BufferedReader is not properly closed in the finally block, simulating a scenario where developers forget to close the resource, leading to a potential network resource leak.

To observe the potential network resource leak, run this program and observe the interleaved output from both threads. Uncommenting the bufferedReader.close(); line in the finally block ensures that the network resource leak is mitigated by properly closing the BufferedReader. Without proper closure, multiple threads may interfere with each other, leading to unpredictable and undesirable outcomes when reading from the shared network resource.

In essence, proper closure of the BufferedReader is essential for efficient resource management. By closing the reader explicitly, developers release system resources promptly, preventing memory bloat, file descriptor exhaustion, and resource contention. Failure to do so can lead to a cascade of performance issues and resource leaks that, although subtle, can have a significant impact on the reliability and efficiency of the Java application over time.

Day 74: Java Security: Crafting a toy TLS Server with Java Security API

2023-12-12T00:00:00Z

In the vast realm of Java programming, security is not just a feature; it’s a necessity. In this article, we’ll embark on a journey to explore the intricate world of Java security by crafting a toy TLS server using the Java Security API. Buckle up as we delve into the nuts and bolts of secure communication!

Setting the Stage

Before we dive into the code, let’s set the stage. Understanding the basics of TLS (Transport Layer Security) is crucial. We’ll discuss why secure communication is essential and lay the groundwork for our TLS server.

TLS

Transport Layer Security (TLS) is a cryptographic protocol that ensures privacy and data integrity between two communicating applications over a network. It is widely used to secure communication over the internet, particularly in web browsers accessing websites, email communication, and other applications that require secure data transmission.

Here’s an overview of how TLS works:

Handshake Protocol:
- ClientHello: The process begins with the client sending a “Hello” message to the server, specifying the supported cryptographic algorithms and other parameters.
- ServerHello: The server responds with its own “Hello” message, selecting a cryptographic algorithm and other parameters from the client’s list.
- Key Exchange: The server provides its public key to the client, and they agree on a pre-master secret, which will be used to generate encryption keys.

Key Exchange:
- The client encrypts the pre-master secret using the server’s public key and sends it back to the server.
- Both the client and server independently generate a session key from the pre-master secret.
Authentication:
- The server may provide a digital certificate to prove its identity. The client verifies the certificate’s authenticity using a trusted Certificate Authority (CA).
- Optionally, the client may also provide its own certificate for server authentication.
Session Key Establishment:
- The client and server use the agreed-upon session key to generate encryption keys for securing the data transmission.
Secure Data Transmission:
- With the session keys established, the client and server use symmetric encryption to secure the data exchanged during the session.
- TLS provides confidentiality by encrypting the data, integrity by using Message Authentication Codes (MACs), and authenticity through digital certificates.
Finished:
- Both the client and server send a “Finished” message to confirm that the handshake is complete. The encrypted session is now established.

How TLS uses Key Pair

TLS uses key pairs, consisting of a public key and a private key, to secure communications over the internet. These keys serve various purposes during the TLS handshake process:

Authentication:
- Server Authentication: The server presents its public key certificate during the handshake to prove its identity. The client can verify the server’s authenticity using a trusted Certificate Authority’s public key.
- Client Authentication (Optional): In cases requiring mutual authentication, the client also presents its public key certificate to the server.
Key Exchange:
- TLS employs asymmetric key exchange algorithms to establish a shared secret key between the client and server. The public keys in the key pairs facilitate a secure exchange, ensuring that eavesdroppers cannot intercept the shared secret.
Data Encryption:
- Once the shared secret is established, symmetric encryption algorithms are used for efficient data encryption. The security of the initial key exchange, facilitated by the key pairs, is crucial for protecting the confidentiality and integrity of the transmitted data.
Perfect Forward Secrecy (PFS):
- TLS emphasizes Perfect Forward Secrecy, ensuring that compromising long-term private keys does not compromise past communications. Key pairs play a role in achieving PFS, especially with algorithms supporting forward secrecy. %%

TLS In Java

In Java, TLS is typically implemented using the Java Secure Socket Extension (JSSE) framework, which provides the necessary classes for secure communication.

Now let’s see how can we construct and toy TLS server and understand how it works

Code Crafting Begins

Now, the real fun begins. We’ll start coding our toy TLS server step by step. From setting up the server socket to handling client connections, we’ll navigate the Java Security API to ensure our server stands robust in the face of potential threats.

import javax.net.ssl.*;  
import javax.security.cert.CertificateException;  
import java.io.BufferedReader;  
import java.io.FileInputStream;  
import java.io.IOException;  
import java.io.InputStreamReader;  
import java.io.PrintWriter;  
import java.security.KeyManagementException;  
import java.security.KeyStore;  
import java.security.KeyStoreException;  
import java.security.NoSuchAlgorithmException;  
import java.security.UnrecoverableKeyException;  
  
public class Day74 {  
    public static void main(String[] args) {  
        try {  
            SSLContext sslContext = SSLContext.getInstance("TLS");  
            KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());  
            KeyStore keyStore = KeyStore.getInstance("JKS");  
            char[] password = "javaSecurityDay74".toCharArray(); // Replace with your keystore password  
            keyStore.load(new FileInputStream("keystore.jks"), password); // Replace with your keystore file path  
            keyManagerFactory.init(keyStore, password);  
            sslContext.init(keyManagerFactory.getKeyManagers(), null, null);  
  
            SSLServerSocketFactory sslServerSocketFactory = sslContext.getServerSocketFactory();  
            SSLServerSocket sslServerSocket = (SSLServerSocket) sslServerSocketFactory.createServerSocket(8888); // Replace with your preferred port  
  
            System.out.println("Server started. Waiting for client connection...");  
  
            SSLSocket sslSocket = (SSLSocket) sslServerSocket.accept();  
  
            BufferedReader in = new BufferedReader(new InputStreamReader(sslSocket.getInputStream()));  
            PrintWriter out = new PrintWriter(sslSocket.getOutputStream(), true);  
  
            String clientMessage = in.readLine();  
            System.out.println("Client message: " + clientMessage);  
  
            out.println("Hello, Client!");  
  
            in.close();  
            out.close();  
            sslSocket.close();  
            sslServerSocket.close();  
        } catch (NoSuchAlgorithmException | KeyManagementException | IOException | KeyStoreException |  
                 UnrecoverableKeyException | java.security.cert.CertificateException e) {  
            e.printStackTrace();  
        }  
    }  
}

SSL Context

Now lets understand the above code step by step to get understanding how it’s communicating using TLS

1
2

    SSLContext sslContext = SSLContext.getInstance("TLS");
    sslContext.init(keyManagerFactory.getKeyManagers(), null, null);

here we are instantiating SSLContext which is the main api that’s driving the security of the communication. We are requesting the SSLContext with "TLS" and then initializing it with KeyManagers from keyManager factory. Now let us understand what is KeyManagerFactory

KeyManager and KeyStore

In Java, a KeyManager is part of the Java Secure Socket Extension (JSSE) and is responsible for managing key materials for key exchange during SSL/TLS communication. It works in conjunction with TrustManager and SecureRandom to provide a comprehensive security framework for Java applications.

In Java, a KeyStore is a repository that stores cryptographic keys and their associated X.509 certificate chains. It is a fundamental component of the Java Cryptography Architecture (JCA) and is used for managing cryptographic keys, certificates, and related information in a secure manner. The KeyStore class is part of the java.security package.

KeyStores are commonly used in various security-related operations, such as SSL/TLS communication, code signing, and digital signatures.

Now lets instantiate a KeyManager and then use keystore to store the keypair

KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());  
KeyStore keyStore = KeyStore.getInstance("JKS");  
char[] password = "javaSecurityDay74".toCharArray(); // Replace with your keystore password  
keyStore.load(new FileInputStream("keystore.jks"), password); // Replace with your keystore file path  
keyManagerFactory.init(keyStore, password);

here we are instantiating KeyManagerFactory which manages keyStores which in turns manages keypair. Here we are creating a key manager by pointing it to an already created keystore and then initializing it.

KeyPair Generation

Keys are the backbone of encryption. We’ll explore the art of KeyPair generation. To generate key pair we need to create a keystore as keys and certificates are stored inside the keystore.

To generate a Java KeyStore (JKS) file, you can use the keytool command-line utility that comes with the Java Development Kit (JDK). Below is an example command to generate a simple self-signed certificate and store it in a JKS file named keystore.jks. This example uses a 2048-bit RSA key for simplicity:

keytool -genkeypair -keyalg RSA -keysize 2048 -alias mykey -keystore keystore.jks -validity 365 -keypass keyPassword -storepass keystorePassword -dname "CN=MyKey, OU=MyOrganizationalUnit, O=MyOrganization, L=MyCity, ST=MyState, C=MyCountry"

this command does the following

-genkeypair: Generates a key pair (public and private keys).
-keyalg RSA: Specifies the key algorithm (RSA in this case).
-keysize 2048: Specifies the key size (2048 bits in this case).
-alias mykey: Specifies the alias for the key pair.
-keystore keystore.jks: Specifies the name of the keystore file.
-validity 365: Specifies the validity period of the key pair in days.
-keypass keyPassword: Specifies the password for the private key.
-storepass keystorePassword: Specifies the password for the keystore.
-dname "CN=MyKey, OU=MyOrganizationalUnit, O=MyOrganization, L=MyCity, ST=MyState, C=MyCountry": Specifies the distinguished name (DN) for the certificate.

After running this command, you will have a keystore.jks file in your working directory. Remember to replace placeholder values (like passwords and distinguished name) with your own values.

SSL Server Socket Setup

An SSL Server Socket, or SSLServerSocket, is a class in Java that represents a server-side endpoint for SSL/TLS-secured communication. It is part of the Java Secure Socket Extension (JSSE) and is used for establishing secure connections between servers and clients over a network.

here we are creating a SSLServerSocketFactory that will provide us with a server socket connection. Then we configure the socket with which port it will listen. In this example I have selected 8888 as the port. The SSLServer will listen on this port. Furthermore we call accept() on SSLServerSocket which will now accept connections.

	SSLServerSocketFactory sslServerSocketFactory =  sslContext.getServerSocketFactory();  
	SSLServerSocket sslServerSocket = (SSLServerSocket) sslServerSocketFactory.createServerSocket(8888); // Replace with your preferred port  
  
	System.out.println("Server started. Waiting for client connection...");  
  
	SSLSocket sslSocket = (SSLSocket) sslServerSocket.accept();

Input and Output Stream Setup

After that we setup input and output stream for incoming and sending data back to client. SSLServerSocket includes an InputStream which alongside with a reader we can get client data and show it

BufferedReader in = new BufferedReader(new InputStreamReader(sslSocket.getInputStream()));  
PrintWriter out = new PrintWriter(sslSocket.getOutputStream(), true);  
  
String clientMessage = in.readLine();  
System.out.println("Client message: " + clientMessage);  
  
out.println("Hello, Client!");  
  
in.close();  
out.close();  
sslSocket.close();  
sslServerSocket.close();

to learn more about tls https://hpbn.co/transport-layer-security-tls/

Day 73: Java Security: Safeguarding Data with Encryption and Keys

2023-09-11T00:00:00Z

The Java Cryptography Extension (JCE) is a framework that provides cryptographic functionality within the Java platform. It offers a set of APIs, algorithms, and services for various cryptographic operations, including encryption, decryption, digital signatures, key management, and more. I will discuss in a 3 part series about the details of

Encryption and Decryption using Java
Digital Signatures
KeyManagement and why we need it.

So in the first part let us dive into the Encryption using AES algorithm by using some already prebuilt java apis.

Encryption and Decryption:

JCE allows you to perform encryption and decryption using symmetric and asymmetric encryption algorithms. So we should understand brefily about symmetric and asymmetirc encryption.

Symmetric Encryption

Symmetric Encryption is a type of encryption where only one key (a secret key) is used to both encrypt and decrypt electronic data. The entities communicating via symmetric encryption must exchange the key so that it can be used in the decryption process. This encryption method differs from asymmetric encryption where a pair of keys - one public and one private - is used to encrypt and decrypt messages. By using symmetric encryption algorithms, data is “scrambled” so that it can’t be understood by anyone who does not possess the secret key to decrypt it. Once the intended recipient who possesses the key has the message, the algorithm reverses its action so that the message is returned to its original readable form. The secret key that the sender and recipient both use could be a specific password/code or it can be random string of letters or numbers that have been generated by a secure random number generator (RNG).

Code Example - Symmetric Encryption (AES):

import javax.crypto.*;
import java.security.Key;
import java.security.NoSuchAlgorithmException;

public class Day73 {
    public static void main(String[] args) throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
        // Generate a secret key
        KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
        keyGenerator.init(128);
        SecretKey secretKey = keyGenerator.generateKey();

        // Initialize the cipher for encryption
        Cipher cipher = Cipher.getInstance("AES");
        cipher.init(Cipher.ENCRYPT_MODE, secretKey);

        String plaintext = "Sensitive information";
        byte[] encrypted = cipher.doFinal(plaintext.getBytes());

        System.out.println("Encrypted: " + new String(encrypted));

        // Initialize the cipher for decryption
        cipher.init(Cipher.DECRYPT_MODE, secretKey);
        byte[] decrypted = cipher.doFinal(encrypted);

        System.out.println("Decrypted: " + new String(decrypted));
    }
}

Now in this example we can see some java api’s. Specifically KeyGenerator, SecretKey and Cipher.

Java has a KeyGenerator class :

This class is designed to generate secret (symmetric) keys, offering the capabilities of a key generator. You can create KeyGenerator instances using any of the getInstance methods provided by this class.

KeyGenerator instances can be used multiple times; that is, once a key has been created, the same KeyGenerator can be used to create more keys.

There are two methods to create a key: one that is algorithm-independent, and another that is specific to an algorithm. The only distinction between these two methods is how the object is initialized. For the algorithm specific ones the java platform provides some algorithms we can choose from and they are

AES (128)
DES (56)
DESede (168)
HmacSHA1
HmacSHA256

Cipher class gives us the option to select the algorithms that we want to use to encrypt or decrypt. In our case we have chosen AES as algorithm to encrypt by initializing once as ENCRYPT_MODE and when decrypting as DECRYPT_MODE.

To learn more about AES and how it works watch this AES Explained (Advanced Encryption Standard) - Computerphile

Asymmetric Encryption

Asymmetric encryption, also known as public-key cryptography, is a cryptographic system that uses a pair of keys - a public key and a private key - to encrypt and decrypt data. These keys are mathematically related but cannot be derived from one another. The public key is used to encrypt data, while the private key is used to decrypt the data. This system allows for secure communication without the need for the sender and receiver to share the same key beforehand.

Here’s how asymmetric encryption works: Asymmetric encryption, also known as public-key cryptography, is a method of encrypting and decrypting information using a pair of keys: a public key and a private key. It provides a secure way to transmit sensitive data over insecure channels, such as the internet. Here’s a simple example for software developers:

Imagine two people, Alice and Bob, who want to communicate securely over an insecure channel. Both Alice and Bob have a pair of keys, one public and one private.

Key Generation:

Alice generates a public-private key pair. She keeps her private key secret and shares her public key with Bob. Similarly, Bob does the same and shares his public key with Alice.

Encryption:

If Alice wants to send a confidential message to Bob, she uses Bob’s public key to encrypt the message. This encrypted message can only be decrypted using Bob’s private key.

Decryption:

When Bob receives the encrypted message, he uses his private key to decrypt it. Only Bob possesses the private key necessary to unlock the message encrypted with his public key.

import javax.crypto.Cipher;
import java.security.*;
import java.util.Base64;

public class Day73 {

    public static void main(String[] args) throws Exception {

        // Generate Key Pair
        KeyPair keyPair = generateKeyPair();
        System.out.println(keyPair.getPrivate());
        System.out.println(keyPair.getPublic());

        // Message to be encrypted
        String originalMessage = "Hello, this is a secret message!";

        // Encryption
        String encryptedMessage = encrypt(originalMessage, keyPair.getPublic());

        System.out.println("Original Message: " + originalMessage);
        System.out.println("Encrypted Message: " + encryptedMessage);

        // Decryption
        String decryptedMessage = decrypt(encryptedMessage, keyPair.getPrivate());

        System.out.println("Decrypted Message: " + decryptedMessage);
    }

    public static KeyPair generateKeyPair() throws NoSuchAlgorithmException {
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(4096);
        return keyPairGenerator.generateKeyPair();
    }

    public static String encrypt(String plaintext, PublicKey publicKey) throws Exception {
        Cipher encryptCipher = Cipher.getInstance("RSA");
        encryptCipher.init(Cipher.ENCRYPT_MODE, publicKey);
        byte[] cipherText = encryptCipher.doFinal(plaintext.getBytes());
        return Base64.getEncoder().encodeToString(cipherText);
    }

    public static String decrypt(String encryptedText, PrivateKey privateKey) throws Exception {
        Cipher decriptCipher = Cipher.getInstance("RSA");
        decriptCipher.init(Cipher.DECRYPT_MODE, privateKey);
        byte[] decryptedText = decriptCipher.doFinal(Base64.getDecoder().decode(encryptedText));
        return new String(decryptedText);
    }
}

now lets see how this code does that

Key Pair Generation:

The generateKeyPair() method uses the KeyPairGenerator class to create a new key pair for encryption and decryption. It initializes the key pair generator with the RSA algorithm and a key size of 2048 bits.

Encryption:

The encrypt() method takes a plaintext message and a public key as input. It initializes a Cipher object for encryption using the RSA algorithm. The method then encrypts the plaintext message using the provided public key and returns the encrypted message as a Base64-encoded string.

Decryption:

The decrypt() method takes the encrypted text and the corresponding private key as input. It initializes a Cipher object for decryption using the RSA algorithm. The method then decrypts the Base64-encoded encrypted text using the provided private key and returns the decrypted message as a string.

In the main method, a new key pair is generated. The original plaintext message is encrypted using the public key from the generated key pair. The encrypted message is then printed to the console. Next, the encrypted message is decrypted using the private key from the same key pair, and the decrypted message is printed to the console.

The example demonstrates how to securely encrypt and decrypt messages using asymmetric encryption with the RSA algorithm in Java. The Base64 class is used to encode and decode byte arrays as strings to ensure that the encrypted and decrypted messages can be properly handled as strings.

Day 72: Can a HashMap Take Null or Empty String as a Key in Java?

2023-07-26T00:00:00Z

While working with a problem I came upon an intriguing question. Can a HashMap Take Null or Empty String as a Key in Java?. If possible how does it translate to the serialization and how popular libraries will handle this situation.

Before starting let us understand how does HashMap works in java. Sepcifically we will focus on the part of how it creates a hash for the hashmap.

What is a Hashmap

At the core of HashMap is the concept of hashing. When you put a key-value pair into a HashMap, the key is first hashed to determine its storage location within the underlying array. The hash code is an integer value computed from the key’s contents using the key’s hashCode() method.

Now a question arises. Do null have a hashcode?

Lets see

`1`	`System.out.println(Objects.hashCode(null));`

here I am using the native Objects class which havea hashCode(). It can create hash for the given object. In this case this method will return 0 for null.

In jdk source code for HashMap class one can see that below method is implemented with the hashCode() method.

1
2
3

        public final int hashCode() {
            return Objects.hashCode(key) ^ Objects.hashCode(value);
        }

this method calculates the hash code for a key-value pair by combining the hash codes of both the key and the value using the bitwise XOR (^) operation. The Objects.hashCode() method is used to obtain the hash codes for the key and value, and then they are XORed together to produce a single hash code.

So its returning a valid integer that will point to the bucket where the value will be stored. In this case what is a bucket? A bucket is a position in the underlying array, and multiple key-value pairs with the same hash code are stored in the same bucket as a linked list (known as a collision chain).

Now let us understand a little bit more about how this hash and storing works.

HashMap Internal Array

Internally, a HashMap uses an array to store its elements. The size of this array is initially set to a default capacity, but it dynamically resizes and rehashes its elements as necessary to maintain efficient performance.

When a key-value pair is added to the HashMap, the key’s hash code is used to compute an index in the array. If the bucket at that index is empty, the key-value pair is stored there. If there is already a key-value pair(s) in the bucket due to a hash code collision, the new key-value pair is linked to the existing ones as a part of the linked list.

Hash Collision Handling

Hash collisions occur when two different keys have the same hash code. In such cases, multiple key-value pairs are stored in the same bucket as a linked list. To find the correct value associated with a key during retrieval, the HashMap traverses the linked list (collision chain) until it finds the key or reaches the end of the chain.

To improve performance and minimize the impact of hash collisions, it’s crucial to have a good hash function that evenly distributes hash codes across the array. The ideal hash function produces distinct hash codes for distinct keys while avoiding excessive collisions.

So back to the question from this we can understand that null can be a valid key for an Hashmap

Also its mention in the documenation of JDK. Now lets see can empty string can be a valid key.

As an empty string still and String object in java so it will generate a valid hashcode when we do

`1`	`System.out.println("".hashCode());`

Similar to null it will generate a valid hashcode. By the way if you run both "" and null in Objects.hashCode() it will return 0 as int. From the code of Objects.hashCode() we can see why.

1
2
3

public static int hashCode(Object o) {
        return o != null ? o.hashCode() : 0;
    }

Also from the hashCode implementation of string we can see

    public int hashCode() {
        int h = hash; // hash by default 0
        if (h == 0 && value.length > 0) {
            char val[] = value;

            for (int i = 0; i < value.length; i++) {
                h = 31 * h + val[i];
            }
            hash = h;
        }
        return h;
    }

when the string is empty then it will return 0.

Day 71: Understanding Heap poullion in java and its causes and how to prevent it

2023-06-09T00:00:00Z

Java is a statically typed language that provides type safety to ensure that variables are used consistently and correctly. However, there are cases where type safety can be compromised, leading to unexpected behavior and runtime errors. One such scenario is heap pollution. In this blog post, we will explore the concept of Java heap pollution, understand why it happens, learn how to detect it, and discuss potential solutions to mitigate its risks.

What is Java Heap Pollution?

Heap pollution occurs in Java when a variable of a parameterized type references an object of an incompatible type. It results in the introduction of elements into a parameterized type structure that violate its type constraints, compromising type safety.

Why Does Heap Pollution Happen?

Heap pollution can happen due to several reasons:

Incompatible Assignments:

Heap pollution can occur when assigning objects of incompatible types to variables of parameterized types. For example, assigning a List to a List variable.

Let’s say you have a method that accepts a List parameter and attempts to add elements from a source list to it. However, if the source list is a List, heap pollution occurs. Here’s an example:

public static void addElementsToList(List<Object> destinationList, List<?> sourceList) {
    for (Object obj : sourceList) {
        destinationList.add(obj); // Heap pollution occurs here
    }
}

// Usage
List<String> stringList = Arrays.asList("Hello", "World");
List<Object> objectList = new ArrayList<>();
addElementsToList(objectList, stringList); // Heap pollution occurs

In this case, the attempt to add String objects to a List leads to heap pollution. The type safety is compromised, and unexpected behavior can occur when accessing elements from the objectList.

Unchecked Type Conversions:

Improper unchecked type conversions can introduce heap pollution. When casting objects to parameterized types without proper type checks, the wrong types can be assigned, leading to heap pollution. Consider the following example:

public static <T> T cast(Object obj) {
    return (T) obj; // Heap pollution occurs here
}

// Usage
List<Integer> integerList = new ArrayList<>();
List rawList = integerList;
List<String> stringList = cast(rawList); // Heap pollution occurs

In this case, the cast method attempts to perform an unchecked type conversion of a raw list to a list of strings. This unchecked conversion introduces heap pollution, as the list contains integer elements but is cast to a string list, potentially causing type safety violations and unexpected behavior.

Varargs and Generics:

Varargs methods combined with generics can also introduce heap pollution. When invoking varargs methods with incompatible types, heap pollution can occur. Consider the following example:

@SafeVarargs
public static <T> List<T> createList(T... elements) {
    List<T> list = new ArrayList<>();
    for (T element : elements) {
        list.add(element); // Heap pollution occurs here
    }
    return list;
}

// Usage
List<String> stringList = createList("Hello", "World");

Although the createList method is annotated with @SafeVarargs, indicating it is safe from heap pollution, it can still be misused. If the method is invoked with incompatible types, such as createList("Hello", 42), heap pollution occurs, leading to potential runtime errors when accessing the elements of the list.

Detecting Heap Pollution:

Detecting heap pollution can be challenging since it often leads to runtime errors rather than compilation errors. However, there are some approaches to detect heap pollution:

Compiler Warnings:

Enable compiler warnings using the -Xlint:unchecked flag. This provides warnings about potential heap pollution issues during compilation, giving you a chance to review and address them.

Static Code Analysis Tools:

Utilize static code analysis tools that can detect potential heap pollution issues. These tools analyze your code and provide suggestions for improvements to prevent heap pollution scenarios.

Solving Heap Pollution:

To mitigate the risks associated with heap pollution, consider the following solutions:

Use Parameterized Types Correctly:

Ensure that parameterized types are used consistently and correctly throughout your code. Avoid situations where variables of parameterized types reference objects of incompatible types.

Enable Compiler Warnings and Annotations:

Enable compiler warnings to get notified about potential heap pollution issues during compilation. Use the @SuppressWarnings(“unchecked”) annotation to suppress warnings for well-understood and intentional heap pollution cases.

Validate and Filter Input:

Validate and filter input data to ensure type compatibility and prevent incompatible objects from entering a parameterized type structure. Perform necessary type checks before performing type conversions or assignments.

Design Patterns and Best Practices:

Apply design patterns, such as the Factory pattern or Builder pattern, to encapsulate object creation and ensure type safety. Follow best practices for generic programming to promote type safety and avoid heap pollution scenarios.

Testing and Code Reviews:

Thoroughly test your code, including scenarios that involve parameterized types, to uncover potential heap pollution issues. Conduct code reviews to identify and address any heap pollution concerns.

Java heap pollution can introduce type safety violations and unexpected behavior in your code. By understanding the causes, detecting heap pollution, and applying appropriate solutions, you can mitigate the risks and ensure type safety. It is essential to use parameterized types correctly, enable compiler warnings, validate input, follow best practices, conduct thorough testing, and engage in code reviews to prevent heap pollution scenarios.

By prioritizing type safety and being vigilant about potential heap pollution, you can write more robust and reliable Java code.

Day 70:Diving deep into Array copy- Measuring Array Copy Performance in Java with JMH: A Comparative Analysis of Methods

2023-04-15T00:00:00Z

In software engineering, optimizing the performance of an application is crucial for delivering a high-quality user experience. One area where performance optimizations can make a significant impact is in the manipulation of arrays. Efficient array copying operations can lead to faster execution times and better application performance.

This is where the Java Microbenchmark Harness (JMH) library comes in handy. JMH is a benchmarking tool designed specifically for measuring the performance of Java code. In this article, we will use JMH to measure the performance of various array copying methods.

public class ArrayCopyBenchmarks {
    @State(Scope.Benchmark)
    public static class ArrState {
        public int[] arr = new int[3000];
        public int[] arr2 = new int[3000];

        @Setup
        public void setup() {
            Random random = new Random();
            Arrays.fill(arr, random.nextInt());
        }
    }
    //@Benchmark
    public int[] loopCopy(ArrState state) {
        int[] arr2 = new int[30];
        for (int i = 0; i < state.arr.length; i++) {
            arr2[i] = state.arr[i];
        }
        return arr2;
    }

    //@Benchmark
    public int[] systemArraysCopy(ArrState state) {
        int[] arr2 = new int[30];
        System.arraycopy(state.arr, 0, arr2, 0, state.arr.length);
        return arr2;
    }

    @Benchmark
    public int[] systemArraysCopyToExistingArray(ArrState state) {
        System.arraycopy(state.arr, 0, state.arr2, 0, state.arr.length);
        return state.arr2;
    }

    @Benchmark
    public int[] loopCopyToExistingArray(ArrState state) {
        for (int i = 0; i < state.arr.length; i++) {
            state.arr2[i] = state.arr[i];
        }
        return state.arr2;
    }

    //@Benchmark
    public int[] arraysCopy(ArrState state) {
        return Arrays.copyOf(state.arr, state.arr.length);
    }

    public static void main(String[] args) throws Exception {
        runBenchmark(ArrayCopyBenchmarks.class);
    }
}

Let’s start by taking a look at the Java code provided above. The code defines a class called ArrayCopyBenchmarks which contains several methods for copying arrays. These methods include:

loopCopy: This method uses a simple loop to copy the contents of one array to another.
systemArraysCopy: This method uses the System.arraycopy method to copy the contents of one array to another.
systemArraysCopyToExistingArray: This method uses the System.arraycopy method to copy the contents of one array to an existing array.
loopCopyToExistingArray: This method uses a simple loop to copy the contents of one array to an existing array.
arraysCopy: This method uses the Arrays.copyOf method to copy the contents of one array to another.

Each of these methods is annotated with the @Benchmark annotation, which tells JMH to measure their execution time.

The main method of the ArrayCopyBenchmarks class uses the runBenchmark method to run the benchmarks and display the results. When you run the program, JMH will execute each benchmark method several times and report the average execution time.

Now let’s look at the results of the benchmarks. We can see that the systemArraysCopy and systemArraysCopyToExistingArray methods are the fastest, followed by the arraysCopy method. The loopCopy and loopCopyToExistingArray methods are the slowest.

These results tell us that the System.arraycopy method is the most efficient way to copy arrays in Java. It is faster than using a loop or the Arrays.copyOf method. Additionally, the systemArraysCopyToExistingArray method is faster than creating a new array and copying the contents of the old array to it.

In conclusion, optimizing array copying operations can have a significant impact on application performance. By using JMH to measure the performance of different array copying methods, we can determine which method is the most efficient. In this case, the System.arraycopy method is the clear winner. By incorporating this method into your code, you can improve the performance of your Java applications.

Day 69 : Unlocking Java Performance Secrets: Harnessing the Power of JMH Microbenchmarking

2023-04-05T00:00:00Z

Java Microbenchmark Harness (JMH) is a Java library used to measure the performance of Java code snippets, methods, and classes. It is a useful tool for developers who want to optimize their Java applications, identify performance bottlenecks, and compare the performance of different implementations.

JMH provides a simple API for developers to write benchmarks and test their performance. In this blog post, we will explore the basics of JMH and how to write and run benchmarks using JMH.

What is a Benchmark Harness:

A benchmark harness is a software that provides the infrastructure to conduct benchmarks of a software and/or hardware system, typically with the goal to quantitatively assess the system’s characteristics and capabilities or to compare the characteristics and capabilities of multiple systems relative to each other

What is JMH:

JMH is built on top of the Java Virtual Machine’s (JVM) HotSpot compiler infrastructure. It uses the Just-In-Time (JIT) compiler to optimize code at runtime, which means that the code is executed multiple times before the actual benchmark is run. This ensures that the benchmark results are accurate and consistent.

To achieve this, JMH generates a benchmarking harness that consists of a loop that executes the benchmark method multiple times. This loop is called a “measurement iteration” and it is executed several times to ensure that the benchmark results are reliable.

JMH Execution Lifecyle

we’ll explore the different phases of the JMH execution lifecycle and what happens during each phase.

Fig: JMH

Setup Phase

The first phase of the JMH execution lifecycle is the setup phase. During this phase, JMH initializes the benchmark state and sets up the environment for the benchmark. The @Setup annotation can be used to define a method that will be executed during this phase.

Warmup Phase

The next phase is the warmup phase. During this phase, JMH runs the benchmark method multiple times to allow the JVM to warm up and optimize the code. The @Warmup annotation can be used to control the duration of the warmup phase and the number of iterations to run.

Measurement Phase

The measurement phase is the main benchmarking phase. During this phase, JMH measures the performance of the benchmark method. The @Benchmark annotation is used to mark the method to be benchmarked. JMH runs the benchmark method for a configurable number of iterations and measures the execution time of each iteration.

Iteration Tear Down Phase

After each iteration of the benchmark method, JMH executes any methods annotated with @TearDownIteration. This can be used to clean up any resources or reset the state of the benchmark.

Result Aggregation Phase

After all iterations have completed, JMH aggregates the results and computes statistics such as the mean, standard deviation, and confidence intervals. This provides a summary of the benchmark results.

Benchmark Tear Down Phase

Finally, JMH executes any methods annotated with @TearDown after the benchmark has completed. This can be used to release any resources or perform any necessary cleanup.

Setting up JMH

Before we dive into writing benchmarks, we need to set up JMH in our project. JMH can be easily added to your project by adding the following dependency to your Maven or Gradle build file:

<!-- Maven dependency -->
    <dependency>
        <groupId>org.openjdk.jmh</groupId>
        <artifactId>jmh-core</artifactId>
        <version>1.34</version>
    </dependency>
    
    <!-- Gradle dependency -->
    compile 'org.openjdk.jmh:jmh-core:1.34'

Writing a simple benchmark

To write a benchmark using JMH, we need to create a class and annotate it with @BenchmarkMode, @OutputTimeUnit, and @State annotations. The @BenchmarkMode annotation specifies the benchmark mode, the @OutputTimeUnit annotation specifies the time unit to use for reporting, and the @State annotation specifies the state of the benchmark.

Here is an example of a simple benchmark that measures the performance of adding two integers:

    import org.openjdk.jmh.annotations.Benchmark;
    import org.openjdk.jmh.annotations.BenchmarkMode;
    import org.openjdk.jmh.annotations.Mode;
    import org.openjdk.jmh.annotations.OutputTimeUnit;
    import org.openjdk.jmh.annotations.State;
    import org.openjdk.jmh.annotations.Scope;
    
    import java.util.concurrent.TimeUnit;
    
    @State(Scope.Thread)
    @BenchmarkMode(Mode.AverageTime)
    @OutputTimeUnit(TimeUnit.NANOSECONDS)
    public class AddBenchmark {
        private int a = 1;
        private int b = 2;
    
        @Benchmark
        public int add() {
            return a + b;
        }
    }

In this benchmark, we have annotated the class with @State(Scope.Thread) to indicate that the state of the benchmark is local to each thread, @BenchmarkMode(Mode.AverageTime) to indicate that we want to measure the average time taken by the benchmark, and @OutputTimeUnit(TimeUnit.NANOSECONDS) to indicate that we want to report the results in nanoseconds.

The benchmark method is annotated with @Benchmark, which indicates that this is the method that we want to measure. In this case, we are measuring the time taken to add two integers.

Running a benchmark

To run a benchmark, we can create an instance of the org.openjdk.jmh.runner.Runner class and pass it the class that contains the benchmark. Here is an example of how to run the AddBenchmark class we just created:

    import org.openjdk.jmh.runner.Runner;
    import org.openjdk.jmh.runner.RunnerException;
    import org.openjdk.jmh.runner.options.Options;
    import org.openjdk.jmh.runner.options.OptionsBuilder;
    
    public class Main {
        public static void main(String[] args) throws RunnerException {
            Options options = new OptionsBuilder()
                    .include(AddBenchmark.class.getSimpleName())
                    .build();
            new Runner(options).run();
        }
    }

In this example, we have created an instance of the OptionsBuilder class and used it to specify the benchmark class that we want to run. We then create an instance of the Runner class and pass it the options we just created.

For further learning Jenkov has a great tutorial about it. https://jenkov.com/tutorials/java-performance/jmh.html

Day 68 : Becoming a memory plumber; A tale of Memory Leak and how to find them ( part 3)

2023-03-30T00:00:00Z

Analyzing for memory leaks in Java involves identifying objects that are no longer being used by the program but are still being held in memory. which can cause memory usage to increase over time and potentially lead to out-of-memory errors. Here are the steps for analyzing and identifying memory leaks in Java:

Identify the symptoms:

The first step in analyzing for memory leaks is to identify the symptoms of the issue, such as out-of-memory errors or increasing memory usage over time.

Gather data:

Once the symptoms have been identified, gather data on the application’s memory usage. This can be done using tools such as Java’s built-in JMX monitoring, VisualVM or JConsole. JFR is another tool to get events and data that is occuring in the jvm. Java Mission Control provides these data. There are some other tools in this page mentioned below

https://docs.oracle.com/javase/9/troubleshoot/diagnostic-tools.htm#JSTGD117

Create heap dumps:

At first lets learn what is heap dump.

Heap dumps :

The term Heapdump describes the JVM mechanism that generates a dump of all the live objects that are on the Java™ heap, which are being used by the running Java application. There are two dump formats, the text or classic heap dump format and the Portable Heap Dump (PHD) format.

Create heap dumps at regular intervals or when the application experiences an out-of-memory error. Heap dumps can be analyzed using tools like Eclipse Memory Analyzer (MAT) or VisualVM.

Fig 1: VisualVM

Analyze heap dumps

Analyze the heap dumps to identify the objects that are being held in memory but are no longer being used by the application. MAT and VisualVM can help identify the root cause of memory leaks. Below is the snap for MAT where a heap dump file is loaded

Java heap dumps can be analyzed using various tools, such as Eclipse Memory Analyzer (MAT) and VisualVM.

Fig 2: Eclipse MAT

Here are the general steps for analyzing Java heap dumps:

Capture the heap dump: Heap dumps can be captured using command-line tools like jmap or via the application itself (if it supports such functionality). Heap dumps can also be automatically captured when the application experiences an OutOfMemoryError.
Load the heap dump into the analysis tool: After capturing the heap dump, load it into an analysis tool like Eclipse Memory Analyzer (MAT) or VisualVM. Both tools have built-in heap dump analysis capabilities.
Analyze the heap dump: Use the analysis tool to explore the heap dump and identify potential memory leaks. The analysis tool will provide information about the objects in the heap, their sizes, and the relationships between them.
Identify the root cause: Use the analysis tool to identify the root cause of the memory leak. This may involve identifying objects that are not being garbage collected, objects that are unnecessarily retained in memory, or objects that are being excessively created.
Take action: Once the root cause has been identified, take action to address the issue. This may involve modifying the code to properly release resources, updating third-party libraries, or tuning the JVM settings to better manage memory.
Verify the fix: After making the necessary changes, verify that the memory leak has been fixed and the application is functioning correctly.

Overall, analyzing Java heap dumps requires a deep understanding of the application’s memory usage patterns and the tools used for heap dump analysis. By following these general steps, developers can identify and address memory leaks in their Java applications.

Identify the cause:

Once the objects causing the memory leaks have been identified, determine the root cause of the issue. This may involve reviewing the code to identify incorrect memory management practices or third-party libraries causing the issue.

Fix the issue:

Fix the issue by correcting the root cause. This may involve modifying the code to properly release resources, updating third-party libraries, or tuning the JVM settings to better manage memory.

Test:

Test the application to ensure that the memory leak has been fixed and that the application is functioning correctly.

By following these steps, developers can identify and address memory leaks in their Java applications. Regular monitoring and analysis can help prevent memory leaks from becoming a significant issue in production environments.

Analyze for finding Memory leaks

In order analyze whether your program contains any potential Memory Leaks you will need some kind specialized tools like

HeapHero
JProfiler
VisualVM

these allow you view what exactly happening under hood during runtime & identify problematic areas ahead time before problems start manifesting themselves on production environment.

In the case I was working, we started looking into which classes were taking much memory and thread execution as well. Then exported a heap dump and analyzed it with Eclipse MAT and isolated the class which was an old version of a library.

Steps to prevent Memory leaks

To prevent Memory Leaks occurring its important ensure all resources get closed properly at end each operation ; try avoid creating too many temporary variables unnecessarily & keep track object lifetime create them only necessary basis then dispose off quickly once done with it ; finally make sure Garbage Collector running correctly so old unused objects get cleared up regularly thus freeing up valuable system resources

Day 67: Becoming a memory plumber; A tale of Memory Leak and how to find them ( part 2)

2023-01-21T00:00:00Z

In my previous post I briefly discussed about few types of memory leaks. In todays post going to further discuss about six other scenarios which can cause memory leaks. They are

Unclosed resource
custom equals and hashcode implementation
Inner class that references outer classes
Finalization bug
Thread local

Unclosed Resources

Unclosed resource memory leak in Java occurs when an application fails to release resources such as file handles, sockets, and database connections after they are no longer needed. These unclosed resources can remain allocated for extended periods of time resulting in a gradual buildup of system memory. This type of leak is particularly dangerous because it often goes unnoticed until the system runs out of available RAM or disk space.

public void getSaleResults() {
    try {
        URL url = new URL("http://api.com/saleResutlts");
        URLConnection urlConnection = url.openConnection();
        InputStream is = urlConnection.getInputStream();
        byte[] bytes = is.readAllBytes();
    } catch (IOException ioe) {
        ioe.printStackTrace();
    }
}

so to resolve this we should use try-with-resource

Java developers must be aware that any code which opens external resources such as files or databases should ensure that these are properly closed once their use has concluded. Failure to do so will result in a slow but steady increase in the amount of used memory on the system over time which can eventually lead to performance issues or even complete failure due to lack of available RAM and/or disk space on the machine hosting your application’s process(es).

Custom .equals() and .hashCode() implementation

Custom .equals() and .hashCode() implementation can cause memory leaks in Java due to the way they are used. When a class implements these methods, it is responsible for managing its own state and ensuring that all objects of the same type have unique references. If this is not done properly, an object can be created but never garbage collected because it will always exist as a reference from another object or collection. This leads to more objects staying in memory than necessary which causes a gradual increase in system resources over time until eventually there is no longer enough available for other tasks leading to poor performance or even crashing of the application.

Let’s see an example scenario, In HashSet and HashMap .equals() and .hashCode()uses these methods in many operations, and if they’re not overridden correctly, they can become a source for potential memory leak problems.

class SaleResult {
	int saleCount;
    boolean isSuccess;
    
    public SaleResult(int saleCount, boolean isSuccess) {
    	this.saleCount = saleCount;
        this.isSuccess = isSuccess;
    }
}

now if we set this object as key in a hashmap or hashset and if a string id for value of the cusomterId we would need to ensure they are unique as HashMap and HashSet dont allow duplicate keys.

Map<SaleResult, Long> map = new HashMap<>();
for(int i=0; i<10000; i++) {
	map.put(new Person("jon"), 1);
}
System.out.println(map.size());

here we will see 1000 objects are being inserted and thus the size of the map is 1000. Here we’re using SaleReuslt as a key. Since Map doesn’t allow duplicate keys, the numerous duplicate SaleResult objects that we inserted as a key shouldn’t increase the memory.

But since we haven’t defined the proper equals() method, the duplicate objects pile up and increase the memory, which is why we see more than one object in the memory.

However, if we’d overridden the equals() and hashCode() methods properly, then only one Person object would exist in this Map. Let’s take a look at the proper implementations of equals() and hashCode() for our SaleResult class:

class SaleResult {
        int id;
        boolean isSuccess;

        public SaleResult(int id, boolean isSuccess) {
            this.id = id;
            this.isSuccess = isSuccess;
        }

      @Override
      public boolean equals(Object o) {
          if (o == this) return true;
          if (!(o instanceof SaleResult)) {
              return false;
          }
          SaleResult result = (SaleResult) o;
          return result.id == this.id;
      }

      @Override
      public int hashCode() {
          int hash = 7;
          hash = 31 * hash + id;
          return hash;
      }
}

now after this there will be only 1 instance of SaleResult in the hashmap after insert.

Inner class that references outer classes

This happens in the case of non-static inner classes (anonymous classes). For initialization, these inner classes always require an instance of the enclosing class. This type of leak occurs when the inner class holds a reference to the outer class. which prevents the garbage collector from reclaiming any memory associated with outer instance. This causes significant performance degradation and even application crashes if not addressed properly.

 class SaleResult {
        long saleCount;

        public SaleResult(long saleCount) {
            this.saleCount = saleCount;
        }

        class SaleData {

        }

        SaleData getSaleData() {
            return new SaleData();
        }
    }

now if we run this program like this

public class Day67 {
	public static void main(String args[]) {
    	List<SaleResult.SaleData> saleResults = new ArrayList<>();
        
        while(infiniteLoopFlag) { // for analyzing the program
        	saleResults.add(new SaleResult(10).getSaleData()):
        }
    }
}

the inner class SaleData will keep the reference of the Outer class SaleResult thus causing memory not to be GC.

Inner classes are useful for organizing code better, but it is important to consider their impact on memory management when using them in your program design. The best way to prevent this type of issue is through proper usage of weak references within the inner class implementation or using static classes. so that it does not maintain a strong reference back up into its parent or containing object graph structure while still providing access as needed at runtime.

Using finalization

Sometimes using finalize() can cause memory leaks. Whenever a classes finalize() method is overridden, then objects of that class aren’t instantly garbage collected. Instead, the GC queues them for finalization, which occurs at a later point in time.

Additionally, if the code written in the finalize() method isn’t optimal, and if the finalizer queue can’t keep up with the Java garbage collector, then sooner or later our application is destined to meet an OutOfMemoryError.

ThreadLocal

ThreadLocal is a api that gives us the ability to store state to a particular thread, and thus allows us to achieve thread safety.

When using this construct, each thread will hold an implicit reference to its copy of a ThreadLocal variable and will maintain its own copy, instead of sharing the resource across multiple threads, as long as the thread is alive.

Despite its advantages, the use of ThreadLocal variables is controversial, as they’re infamous for introducing memory leaks if not used properly. Joshua Bloch once commented on thread local usage that:

“Can you cause unintended object retention with thread locals? Sure you can. But you can do this with arrays too. That doesn’t mean that thread locals (or arrays) are bad things. Merely that you have to use them with some care. The use of thread pools demands extreme care. Sloppy use of thread pools in combination with sloppy use of thread locals can cause unintended object retention, as has been noted in many places. But placing the blame on thread locals is unwarranted.” – Joshua Bloch

ThreadLocals are supposed to be garbage collected once the holding thread is no longer alive. But the problem arises when we use ThreadLocals along with modern application servers.

Modern application servers use a pool of threads to process requests, instead of creating new ones (for example, the Executor in the case of Apache Tomcat). Moreover, they also use a separate classloader. Since ThreadPools in application servers work on the concept of thread reuse, they’re never garbage collected; instead, they’re reused to serve another request.

If any class creates a ThreadLocal variable, but doesn’t explicitly remove it, then a copy of that object will remain with the worker Thread even after the web application is stopped, thus preventing the object from being garbage collected.

How does ThreadLocal Creates memory leak

Each Thread has a private field threadLocals, which actually stores the thread-local values.
Each key in this map is a weak reference to a ThreadLocal object, so after that ThreadLocal object is garbage-collected, its entry is removed from the map.
But each value is a strong reference, so when a value (directly or indirectly) points to the ThreadLocal object that is its key, that object will neither be garbage-collected nor removed from the map as long as the thread lives.

In this example, the chain of strong references looks like this:

Thread object → threadLocals map → instance of example class → example class → static ThreadLocal field → ThreadLocal object.

Lets see an example of this

public class Day67 {

    private static final ThreadLocal<List<String>> threadLocal = new ThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        List<Thread> threads = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            Thread thread = new Thread(() -> {
                List<String> list = new ArrayList<>();
                threadLocal.set(list);
                // add a lot of data to the thread-local list
                for (int j = 0; j < 100000; j++) {
                    list.add("This is a string that will consume some memory.");
                }
            });
            threads.add(thread);
            thread.start();
        }
        for (Thread thread : threads) {
            thread.join();
        }
        // At this point, all threads have completed execution.
        // However, the thread-local lists have not been cleared,
        // and will continue to consume memory until the program terminates.
    }
}

In this program, we define a ThreadLocal variable called threadLocal which stores a list of strings. We then create 10 threads and in each thread, we create a new list and add a lot of data to it. We then set this list as the value of the thread-local variable using threadLocal.set(list).

Because the ThreadLocal variable is thread-local, each thread has its own list and the lists are not shared between threads. However, since we are adding a lot of data to each list, they consume a significant amount of memory.

The problem is that once each thread has completed execution, the lists are not cleared. Because the ThreadLocal variable still holds a reference to each list, they will not be garbage collected and will continue to consume memory until the program terminates. This can lead to a memory leak, as the program’s memory usage will continue to grow over time.

To avoid this, we should always make sure to clear the thread-local variables once we are done with them, by calling threadLocal.remove() at the end of each thread’s execution.

Day 66: Becoming a memory plumber; A tale of Memory Leak and how to find them ( part 1)

2023-01-20T00:00:00Z

What is memory leak

Memory leaks are a major issue for software engineers, especially those working with Java. A memory leak occurs when an application continues to use more and more of the computer’s RAM without releasing it after it has been used. This can cause serious performance issues as the available RAM decreases and eventually leads to system crashes or outages.

Java has automated memory management system unlike its predecessor C . Java does this using GC. The GC implicitly takes care of allocating and freeing up memory, and thus is capable of handling the majority of memory leak issues.

While the GC effectively handles a good amount of memory, it doesn’t guarantee a foolproof solution to memory leaking. The GC is pretty smart, but not flawless. Memory leaks can still happen.

Now let us understand what is Memory Leak

Memory Leak

a memory leak is a type of resource leak that occurs when a computer program incorrectly manages memory allocations in a way that memory which is no longer needed is not released.

As a software engineer, it’s important to understand the concept of memory leaks in Java. A memory leak is when an application continues to hold onto memory that it no longer needs and this can lead to performance issues or even system crashes. In Java, a common cause of such leaks is objects not being garbage collected as expected due to references still pointing at them from other parts of the code.

When an object is created in Java, the JVM (Java Virtual Machine) allocates space for it on the heap and then assigns a reference variable which points towards that allocated space. As long as there are any active references pointing towards this object, it will remain alive on heap until all these references are removed and GC (Garbage Collector) reclaims its resources back from Heap Memory Pool. If somehow some reference(s) remains active even after they have been used up by program logic then those objects become eligible for Garbage Collection but never get collected since their respective reference variables still point at them causing unnecessary accumulation of unused/unrequired Objects over time resulting into what we call “Memory Leak” issue with our Application Codebase leading into Performance Degradation & System Crashes eventually!

To avoid such problems one should keep track if their code has any potential chances where Object References might be left dangling without getting released explicitly using null assignments or try-catch blocks etc., so that GC can reclaim those resources back once they become eligible otherwise Memory Leaks would continue accumulating over time leading us into trouble!

What problems it causes

Memory leaks in Java can be caused by a variety of factors such as incorrect garbage collection, resource leakage in APIs, unclosed streams or connections, poor coding practices etc. These issues can lead to decreased responsiveness from applications due to increased latency times; they may also result in OutOfMemoryError exceptions being thrown which causes applications to crash unexpectedly or become unstable over time due their inability handle large amounts of data efficiently anymore .

Types of Memory Leaks

There are many ways memory leaks can occur in a java program. Some of them are

Static fields
Loitering objects
In memory cache not evicted
Unclosed resource
custom equals and hashcode implementation
Inner class that references outer classes
Finalization bug
Interned strings
Thread local

now let us understand these typical memory leak issues

static fields

heavy use of static variables can cause memory leaks. In Java, static fields have a lifetime that usually matches the entire lifetime of the running program / application (unless ClassLoader becomes eligible for garbage collection).

lets see a case

public class Day65 {
    public static List<String> strings = new ArrayList<>();

    public void add() {
        for (int i = 0; i < 100000; i++) {
            list.add(new String());
        }
        System.out.println("check point add");
    }

    public static void main(String[] args) {
        System.out.println("Beforee calling add");
        new Day65().populateList();
        System.out.println("After calling add");
    }
}

here when observing with

Loitering Objects

These objects are allocated memory, but not used, and not garbage collected. These keep increasing the size of the JVM heap and represent memory leaks, which can cause an out-of-memory error or excessive overhead on the garbage collector.

Let’s understand this scenario with an example, consider a stack backed by an array, and you implement pop this way:

public T pop() {
    if (top == -1) {
        throw new NoSuchElementException();
    }
    T item = items[top--];
    return item;
}

Because the array holds a reference to the item at the former top of the stack, the item is still strongly reachable from the array and therefore won’t be garbage collected. Furthermore, because of the way a stack works, the item is no longer externally accessible. Thus, the item is said to be “loitering”. It hangs around for no reason.

The correct implementation of the pop method would be this:

public T pop() {
    if (top == -1) {
        throw new NoSuchElementException();
    }
    T item = items[top];
    // Clear the reference to allow garbage collection
    items[top] = null;
    top--;
    return item;
}

By setting the array entry to null, the item is no longer reachable from the array. Therefore it is eligible for garbage collection.

Garbage collection isn’t magic. It can do most of the work to clean up memory for you. But, you have to make sure you write your code correctly to eliminate unnecessary strong references. The garbage collector can’t read your mind, and figure out that you didn’t really mean to keep the strong reference.

In Memory Cache Eviction

when we build in memory cache (in this case Guava library) there is a possibility of memory leak when the cache get increased without clearing the cache. let us first understand what is cache eviction

Cache Eviction

Caches are small because cache memory is more expensive to produce and purchase. The small size of the cache limits the amount of data we can store. We need to consider what data we keep or remove over time. This dilemma is the core purpose behind cache eviction. It will depending on algorithms will remove some entries.

So by restricting the size or creating an eviction policy will ensure the cache doesn’t grow uncontrollably.

In the below example we will see a cache without a size or eviction policy

public class CustomCache<T> {
    private Cache<String, T> cache;

    //Constructor to build Cache Store
    public CustomCache() {
        cache = CacheBuilder.newBuilder().build();
    }


    public T get(String key) {
        return cache.getIfPresent(key);
    }

    //Method to put a new record in Cache Store with record key
    public void add(String key, T value) {
        if(key != null && value != null) {
            cache.put(key, value);
            System.out.println("Entry stored in "
                    + value.getClass().getSimpleName()
                    + " Cache with Key = " + key);
        }
    }
}

Now adding a size and cache eviction policy will help not to cause memory leak. In guava CacheBuilder by adding the properties maximumSize and expireAfterAccess will limit the size and when will be the entires will be deleted

public CustomCache() {
        cache = CacheBuilder.newBuilder()
        					.maximumSize(100)
                            .expireAfterAccess(30, TimeUnit.MINUTES)
        					.build();
 }

In part 2 will learn about other type of reasons for memory leak

Day 65: A tale of RMI (Remote Method Invocation) in java

2023-01-12T00:00:00Z

Remote Method Invocation (RMI) and Remote Procedure Call (RPC) are two important concepts in Java that allow for distributed computing. Both RMI and RPC enable software components to communicate with each other over a network, allowing code to be executed on different machines without the need for manual intervention. In this blog post, we will discuss what RMI and RPC are, how they differ from one another, their advantages/disadvantages as well as an example of each in Java.

What is RMI

At its core, Remote Method Invocation is a way of calling methods on remote objects over a network connection using the Object Request Broker Architecture (ORB). It provides developers with the ability to execute code remotely without having any knowledge about where or how it is being run – all you need is an interface definition file (.idl file), which describes your object’s methods signatures and return types along with some additional information related to security etc., then you can use it just like any other local object! The main benefit here lies in its flexibility; since there’s no requirement for manual coding or compilation when making changes across multiple systems simultaneously - instead all that needs doing is updating one centralised IDL file.

Remote invocation is nothing new. For many years C programmers have used remote procedure calls (RPC) to execute a C function on a remote host and return the results. The primary difference between RPC and RMI is that RPC, being an offshoot of the C language, is primarily concerned with data structures. It’s relatively easy to pack up data and ship it around, but for Java, that’s not enough. In Java we don’t just work with data structures; we work with objects, which contain both data and methods for operating on the data. Not only do we have to be able to ship the state of an object (the data) over the wire, but also the recipient has to be able to interact with the object (use its methods) after receiving it.

Now let us first understand some concepts regarding RMI and how it works. At first lets understad what are Remote and Non Remote Objects

Remote and Non Remote Obj

Before an object can be used with RMI, it must be serializable. But that’s not sufficient. Remote objects in RMI are real distributed objects. As the name suggests, a remote object can be an object on a different machine; it can also be an object on the local host. The term remote means that the object is used through a special kind of object reference that can be passed over the network. Like normal Java objects, remote objects are passed by reference. Regardless of where the reference is used, the method invocation occurs at the original object, which still lives on its original host. If a remote host returns a reference to one of its objects to you. Then you call that object’s methods; the actual method invocations will happen on the remote host, where the object is.

Non remote objects are simpler. They are just normal serializable objects. (You can pass these over the network). The catch is that when you pass a non remote object over the network it is simply copied. So references to the object on one host are not the same as those on the remote host. Non remote objects are passed by copy (as opposed to by reference).

Stub

Stub is used in the implementation of remote objects. When you invoke a method on a remote object (which could be on a different host), you are actually calling some local code that serves as a proxy for that object. This is the stub. (It is called a stub because it is something like a truncated placeholder for the object.)

The stub object on the client machine builds an information block and sends this information to the server.

The block consists of

An identifier of the remote object to be used
Method name which is to be invoked
Parameters to the remote JVM

Skeleton

The skeleton is another proxy that lives with the real object on its original host. It receives remote method invocations from the stub and passes them to the object.

The skeleton object passes the request from the stub object to the remote object. It performs the following tasks

It calls the desired method on the real object present on the server.
It forwards the parameters received from the stub object to the method.

Before creatin stubs and skeletons we need to create remote object and understand how it works

Remote Object

The first thing to do is to create an interface that will provide the description of the methods that can be invoked by remote clients. This interface should extend the Remote interface and the method prototype within the interface should throw the RemoteException.

Remote objects are objects that implement a special remote interface that specifies which of the object’s methods can be invoked remotely. The remote interface must extend the java.rmi.Remote interface. Your remote object will implement its remote interface; as will the stub object that is automatically generated for it. In the rest of your code, you should then refer to the remote object as an instance of the remote interface—not as an instance of its actual class. Because both the real object and stub implement the remote interface, they are equivalent as far as we are concerned (for method invocation); locally, we never have to worry about whether we have a reference to a stub or to an actual object. This “type equivalence” means that we can use normal language features, like casting with remote objects. Of course public fields (variables) of the remote object are not accessible through an interface, so you must make accessor methods if you want to manipulate the remote object’s fields.

All methods in the remote interface must declare that they can throw the exception java.rmi.RemoteException . This exception (actually, one of many subclasses to RemoteException) is thrown when any kind of networking error happens: for example, the server could crash, the network could fail, or you could be requesting an object that for some reason isn’t available.

Here’s a simple example of the remote interface that defines the behavior of RemoteObject; we’ll give it a method that can be invoked remotely

1
2
3

public interface MessageService extends Remote {
    String send(String message) throws RemoteException;
}

when we implement this object its called remote object which is for the server. For the client, the RMI library will dynamically create an implementation Stub.

implementation

public class MessengerServiceImpl implements MessengerService { 
 
    @Override 
    public String send(String message) { 
        return "Client Message".equals(message) ? "Server Message" : null;
    }
}

It’d be unusual for our remote object to throw a RemoteException since this exception is typically reserved for the RMI library to raise communication errors to the client. Leaving it out also has the benefit of keeping our implementation RMI-agnostic. Also, any additional methods defined in the remote object, but not in the interface, remain invisible for the client.

Once we create the remote implementation, we need to bind the remote object to an RMI registry.

RMI Registry

The registry is the RMI phone book. You use the registry to look up a reference to a registered remote object on another host. We’ve already described how remote references can be passed back and forth by remote method calls. But the registry is needed to bootstrap the process: the client needs some way of looking up some initial object.

The registry is implemented by a class called Naming and an application called rmiregistry . This application must be running on the local host before you start a Java program that uses the registry. You can then create instances of remote objects and bind them to particular names in the registry. (Remote objects that bind themselves to the registry sometimes provide a main( ) method for this purpose.) A registry name can be anything you choose; it takes the form of a slash-separated path. When a client object wants to find your object, it constructs a special URL with the rmi: protocol, the hostname, and the object name. On the client, the RMI Naming class then talks to the registry and returns the remote object reference.

So before registering in RMI registry we need to create a stub

1
2
3

MessengerService server = new MessengerServiceImpl();
MessengerService stub = (MessengerService) UnicastRemoteObject
  .exportObject((MessengerService) server, 0);

We use the static UnicastRemoteObject.exportObject method to create our stub implementation. The stub communicates with the server over the underlying RMI protocol.

The first argument to exportObject is the remote server object. The second argument is the port that exportObject uses for exporting the remote object to the registry.

Giving a value of zero indicates that we don’t care which port exportObject uses, which is typical and so chosen dynamically.

UnicastRemoteObject

The actual implementation of a remote object (not the interface we discussed previously) will usually extend java.rmi.server.UnicastRemoteObject. This is the RMI equivalent to the familiar Object class. When a subclass of UnicastRemoteObject is constructed, the RMI runtime system automatically “exports” it to start listening for network connections from remote interfaces (stubs) for the object. Like java.lang.Object, this superclass also provides implementations of equals( ) , hashcode( ), and toString( ) that make sense for a remote object.

RMI Architecture

Now lets create a RMI registry

Creating RMI Registry

We can start up a registry local to our server or as a separate stand-alone service. Here we will create for local

`1`	`Registry rmiRegistry = LocateRegistry.createRegistry(1099);`

This creates a registry to which stubs can be bound by servers and discovered by clients. Also, we’ve used the createRegistry method, since we are creating the registry local to the server.

By default, an RMI registry runs on port 1099. Rather, a different port can also be specified in the createRegistry factory method.

But in the stand-alone case, we’d call getRegistry, passing the hostname and port number as parameters.

Now we have to bind the stub which is generated by rmic to registry

Bind Stub

An RMI registry is a naming facility like JNDI etc. We can follow a similar pattern here, binding our stub to a unique key: here its MessageService

`1`	`registry.rebind("MessengerService", stub);`

after registering the stub in RMI registry we need to create a client.

Create Client

To do this, we’ll first locate the RMI registry. In addition, we’ll look up the remote object stub using the bounded unique key.

And finally, we’ll invoke the send method:

Registry registry = LocateRegistry.getRegistry();
MessengerService server = (MessengerService) registry
  .lookup("MessengerService"); // looking for the binded stub
String responseMessage = server.send("Client Message");
String expectedMessage = "Server Message";
 
if (expectedMessage.equals(responseMessage)) {
	System.out.println("Connection Successful");
} else {
	System.out.println("Not able to recognize client");
}

Because we’re running the RMI registry on the local machine and default port 1099, we don’t pass any parameters to getRegistry. Indeed, if the registry is rather on a different host or different port, we can supply these parameters. Once we lookup the stub object using the registry, we can invoke the methods on the remote server.

Day 64: Implementing a basic Bloom Filter Using Java BitSet api

2022-12-28T00:00:00Z

First of all lets understand what is a Bloom Filter and how does it work and what are its usages.

Bloom Filter :

Bloom filter is a data structure designed to tell you, rapidly and memory-efficiently, whether an element is present in a set.

The price paid for this efficiency is that a Bloom filter is a probabilistic data structure: it tells us that the element either definitely is not in the set or may be in the set

For example, checking availability of username. In this case its a set membership problem, where the set is the list of all registered username. The price we pay for efficiency is that it is probabilistic in nature. That means, there might be some False Positive results. False positive means, it might tell that given username is already taken but actually it’s not.

here in this scenario we are searching for the user name Mary in the bloom filter. So from the picture we can see a bloom filter is a combination of a hash function and a bit array or list. Where after hashing the user name will give us a number in which we will set the bit to true.

So if we use different hash functions and then update the bit array with 1 where the index of the array would be number provided by the hash function. Then if we search the name again with those hash functions and check the index’s again and if we find 1 there then we can plausibly say that, that name exist in the bloom filter.

So, in a nutshell:

If we search for a value and see any of the hashed indexes for this value is ‘0’ then, the value is definitely not on the list.
If all of the hashed indexes is ‘1’ then ‘maybe’ the searched value is on the list.

Properties :

unlike a standard hash table, a Bloom filter of a fixed size can represent a set with large number of elements.
False positive rate increases steadily as elements are added until all bits in the filter are set to 1, at which point all queries yield a positive result.

So let us discuss what is false positive in the case of getting information from a bloom filter.

The question is why we said “Probabilistic”, why this uncertainty? Let’s understand this with an example. Suppose we want to check whether “Mohibul” is present or not. We’ll calculate hashes using h1, h2 and h3 functions

String name = "Mohibul";
h1(name) % 10 = 5;
h2(name) % 10 = 2;
h3(name) % 10 = 4;

If we check the bit array, bits at these indices are set to 1.

Now lets check for another name “Mary”

String name = "Mary"
h1(name) % 10 = 1;
h2(name) % 10 = 2;
h3(name) % 10 = 5;

but we know that “Mary” was never added to the filter. Bit at index 2 and 5 was set when we added “Mohibul” . And if another name made 1 bit true then this bloom filter will say that “Mary” exists in the filter but in real we didnt add Mary.

This behavior causes false positives.

Bloom filters never generate false negative result, i.e., telling you that a username doesn’t exist when it actually exists.
Deleting elements from filter is not possible. Because, if we delete a single element by clearing bits at indices generated by k hash functions, it might cause deletion of few other elements. Example – if we delete “Mohibul” (in given example) by clearing bit at 4, 5 and 2, we might end up deleting “Mary” also if its present Because bit at index 2 and 5 becomes 0 and bloom filter claims that “ Mary ” is not present.

Let us make a bloom filter ourselves.

Before doing that let us ask some question that will help us better design and understand

What are these hash functions?
How big should I make the bloom filters?
How many hash functions should i use?
Benefits of bloom filter?
Where can I use them?

What is Hash functions

The hash functions used in a Bloom filter should be independent and uniformly distributed. They should also be as fast as possible (cryptographic hashes such as sha1, though widely used thus are not very good choices).

Examples of fast, simple hashes that are independent enough includes murmur, xxHash, Fowler–Noll–Vo hash function and many others

How big should I make the bloom filters

It’s a nice property of Bloom filters that you can modify the false positive rate of your filter. A larger filter will have less false positives, and a smaller one more.

Your false positive rate (P) will be approximately

(1-e^((-kn)/m)))^k

so you can just plug the number n of elements you expect to insert, and try various values of k and m to configure your filter for your application.

Here

m - is the size of the bit array
n - is the number of elements
k - is the number hash funtions

This leads to an obvious question

How many hash functions should I use?

The more hash functions you have, the slower your bloom filter, and the quicker it fills up. If you have too few, however, you may suffer too many false positives.

Since you have to pick k when you create the filter, you’ll have to ballpark what range you expect n to be in. Once you have that, you still have to choose a potential m (the number of bits) and k (the number of hash functions).

So now we can design a process to build a bloom filter

Choose a approx value for n
Choose a value for m
Calculate the optimal value of k
Calculate the error rate for our chosen values of n, m, and k. If it’s unacceptable, return to step 2 and change m; otherwise we’re done.

Now for the code we will use Java’s BitSet API

public class BloomFilter<T> {
        private BitSet bitSet;
        private int n;
        private int m;
        private List<Function<T, Integer>> hashFunctions;

        public BloomFilter(final int n, final int m,
                           final List<Function<T, Integer>> hashFunctions) {
            this.n = n;
            this.bitSet = new BitSet(n);
            this.m = hashFunctions.size();
            this.hashFunctions = hashFunctions;
        }

        public void add(T value) {
            for (Function<T, Integer> function : hashFunctions) {
                int hash = mapHashToInt(function.apply(value));
                bitSet.set(hash, true);
            }
        }

        public boolean mightContain(T value) {
            for (Function<T, Integer> function : hashFunctions) {
                int hash = mapHashToInt(function.apply(value));
                if (!bitSet.get(hash)) {
                    return false;
                }
            }
            return true;
        }

        private int mapHashToInt(int hash) {
            return hash & (n - 1);
        }

    }

here Function<T,Integer> hashFunctions supplied by the client. And BitSet exactly works like a bit array.

Now we have tried our custom BloomFilter Google guava has a implementation of BloomFilter which can be created like

BloomFilter<Integer> filter = BloomFilter.create(
  Funnels.integerFunnel(),
  500,
  0.01);

Benifits of Bloom Filter

Given a Bloom filter with m bits and k hashing functions, both insertion and membership testing are O(k). That is, each time you want to add an element to the set or check set membership, you just need to run the element through the k hash functions and add it to the set or check those bits.

The space advantages are more difficult to sum up; again it depends on the error rate you’re willing to tolerate. It also depends on the potential range of the elements to be inserted; if it is very limited, a deterministic bit vector can do better. If you can’t even ballpark estimate the number of elements to be inserted, you may be better off with a hash table or a scalable Bloom filter.

Where Can I Use It

Bloom filter is all about testing Membership in a set. The classic example of using bloom filters is to reduce expensive disk (or network) lookups for non-existent keys. As we can see that bloom filters can search for a key in O(k) constant time, where k is the number of hash functions, it will be very fast to test non-existence of a key.

If the element is not in the bloom filter, then we know for sure we don’t need to perform the expensive lookup. On the other hand, if it is in the bloom filter, we perform the lookup, and we can expect it to fail some proportion of the time (the false positive rate).

For some more concrete examples:

You’ve seen in our given example that we could’ve use it to warn the user for weak passwords.
You can use bloom filter to prevent your users from accessing malicious sites.
Instead of making a query to an SQL database to check if a user with a certain email exists, you could first use a bloom filter for an inexpensive lookup check. If the email doesn’t exist, great! If it does exist, you might have to make an extra query to the database. You can do the same to search for if a ‘Username is already taken’.
You can keep a bloom filter based on the IP address of the visitors to your website to check if a user to your website is a ‘returning user’ or a ‘new user’. Some false positive value for ‘returning user’ won’t hurt you, right?
You can also make a Spell-checker by using bloom filter to track the dictionary words.
Want to know how Medium used bloom filter to decide if a user already read post? Read this mind-blowing, freaking awesome article about it.

in this wikipidia link there are multiple other usage of bloom filter.

Day 63: Alert system for Java OutOfMemory Error

2022-12-14T00:00:00Z

What is OutOfMemory

java.lang.OutOfMemoryError exception is thrown when there is insufficient space to allocate an object in the Java heap. In this case, The garbage collector cannot make space available to accommodate a new object, and the heap cannot be expanded further. Also, this error may be thrown when there is insufficient native memory to support the loading of a Java class. In a rare instance, a java.lang.OutOfMemoryError may be thrown when an excessive amount of time is being spent doing garbage collection and little memory is being freed.

When a java.lang.OutOfMemoryError exception is thrown, a stack trace is also printed. In that stack trace the cause are mentioned for easier fixing of the issue.

This exception will be thrown when

Memory Leak occurs
Not enough heap space to allocate objects
If GC is running all the time
Trying to allocate memory larger than the heap size
When Metaspace memory is full
When native memory is not enough to allocate

How OOM happens

There are many more reasons OOM can occur. An OutOfMemoryError (OOME) is bad. It can happen at any time, with any thread. There is little that you can do about it, except to exit the program, change the -Xmx value, and restart the JVM. If you then make the -Xmx value too large, you slow down your application. The secret is to make the maximum heap value the right size, neither too small, nor too big. OOME can happen with any thread, and when it does, that thread typically stops. Often, there is not enough memory to build up a stack trace for the OOME, so you cannot even determine where it occurred, or why.

Now lets dive into the alert system code.

1
2
3

public interface Listener {
	void alertMemoryLow(long used, long max, Map<Thread, StackTraceElement[]> allThreadStackTrace);
}

Let us define a Listener which will listen for the alert. Then

 public static class OOMAlertService {
        private final List<Listener> listeners = new ArrayList<>();
        
        public OOMAlertService() {
            MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
            NotificationEmitter emitter = (NotificationEmitter) mbean;
            emitter.addNotificationListener((notification, o) -> {
                if (notification.getType().equals(
                        MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) {
                    long maxMemory = tenuredGenPool.getUsage().getMax();
                    long usedMemory = tenuredGenPool.getUsage().getUsed();
                    for (Listener listener : listeners) {
                        listener.alertMemoryLow(usedMemory, maxMemory, Thread.getAllStackTrace());
                    }
                }
            }, null, null);
        }

        public boolean addListener(Listener listener) {
            return listeners.add(listener);
        }

        public boolean removeListener(Listener listener) {
            return listeners.remove(listener);
        }

        private static final MemoryPoolMXBean tenuredGenPool = findTenuredGenPool();

        public static void setUsageThreshold(double threshold) {
            if (threshold <= 0.0 || threshold > 1.0) {
                throw new IllegalArgumentException("Threshold Percentage outside range");
            }
            long maxMemory = tenuredGenPool.getUsage().getMax();
            long warningThreshold = (long) (maxMemory * threshold);
            tenuredGenPool.setUsageThreshold(warningThreshold);
        }


        private static MemoryPoolMXBean findTenuredGenPool() {
            for (MemoryPoolMXBean pool : ManagementFactory.getMemoryPoolMXBeans()) {
                if (pool.getName().contains("Old")
                        && pool.getType() == MemoryType.HEAP
                        && pool.isUsageThresholdSupported()) {
                    return pool;
                }
            }
            throw new Exception("Could not find tenured space");
        }
    }

In our OOMAlterService we add listeners to implement the OOMAlertService.Listener interface, with one method alertMemoryLow(long used, long max) that will be called when the threshold is reached.

Once we have downcast the MemoryMXBean to a NotificationEmitter we can add a NotificationListener to the MemoryMXBean. You should verify that the notification is of type MEMORY_THRESHOLD_EXCEEDED.

This notification will be emitted fast.Something to note is that the listener is being called by a special thread, called the Low Memory Detector thread, that is part of the standard JVM.

What is the threshold? And which of the many pools should we monitor? The only sensible pool to monitor is the Tenured Generation (Old Space). When you set the size of the memory with -Xmx256m, you are setting the maximum memory to be used in the Tenured Generation. Searching in findTenuredGenPool() method, and returning the first one that was of type HEAP to get the Tenured gen memory.

In setUsageThreshold(doublethreshold) method, I specify when I would like to be notified. This threshold is a global setting. so only one usage threshold per Java Virtual Machine. The threshold value is used to calculate the usage threshold, based on the maximum memory size of the Tenured Generation pool (not the Runtime.getRuntime().maxMemory() value!).

In findTenuredGenPool() I am trying to find the Tenured / Old gen memory which is a heap memory. At first lets understand about JVM Heap and Non Heap memory.

Heap memory

The heap memory is the runtime data area from which the Java VM allocates memory for all class instances and arrays. The heap may be of a fixed or variable size. The garbage collector is an automatic memory management system that reclaims heap memory for objects.

Eden Space: The pool from which memory is initially allocated for most objects.
Survivor Space: The pool containing objects that have survived the garbage collection of the Eden space.
Tenured Generation or Old Gen: The pool containing objects that have existed for some time in the survivor space.

Non-heap memory

Non-heap memory includes a method area shared among all threads and memory required for the internal processing or optimization for the Java VM. It stores per-class structures such as a runtime constant pool, field and method data, and the code for methods and constructors. The method area is logically part of the heap but, depending on the implementation, a Java VM may not garbage collect or compact it. Like the heap memory, the method area may be of a fixed or variable size. The memory for the method area does not need to be contiguous.

Permanent Generation: The pool containing all the reflective data of the virtual machine itself, such as class and method objects. With Java VMs that use class data sharing, this generation is divided into read-only and read-write areas.
Code Cache: The HotSpot Java VM also includes a code cache, containing memory that is used for compilation and storage of native code.

And for the application, the below diagram will give you an idea about how memory is distributed.

so now lets go back to the method findTenuredGenPool().

private static MemoryPoolMXBean findTenuredGenPool() {
            for (MemoryPoolMXBean pool : ManagementFactory.getMemoryPoolMXBeans()) {
                if (pool.getName().contains("Old")
                        && pool.getType() == MemoryType.HEAP
                        && pool.isUsageThresholdSupported()) {
                    return pool;
                }
            }
            throw new Exception("Could not find tenured space");
        }
    }

in this method we are looking for a pool which is of type HEAP and also in its name contains the word old. This is one way we can find the Tenured gen pool.

So using this pools size and its threshold we can make alert service that will give us alert when memory is low. That way we can take necessary steps to prevent OOM error.

So now running this service

class Day63 {

    public static void main(String[] args) throws Exception {
        OOMAlertService.setUsageThreshold(60.0/100.0);

        OOMAlertService mws = new OOMAlertService();
        mws.addListener((usedMemory, maxMemory, stacktrace) -> {
            System.out.println("Memory usage low!!!");
            double percentageUsed = ((double) usedMemory) / maxMemory;
            System.out.println("percentageUsed = " + percentageUsed);
            OOMAlertService.setUsageThreshold(80.0/100.0);
            stacktrace.forEach((key, value) -> System.out.println(key + " " + Arrays.toString(value)));
        });

        List<List<Object>> numbers = new ArrayList<>();
        while (true) {
            numbers.add(new ArrayList<>());
        }
    }

Here I am just creating a list of object infinitely to induce OOM.