DEV Community: Vishnu B

How Java Garbage Collection Works: A Quick Walkthrough

Vishnu B — Mon, 09 Nov 2026 12:30:16 +0000

Java has no free() and no delete. You stop referencing an object, and at some point its memory quietly comes back. Someone is doing that work: the garbage collector. Let's pin down the rule it uses, watch a real JVM collect live, and then be honest about where the JVM ends and the operating system begins.

The one rule: reachability

The collector does not count references or guess. It starts from a fixed set of entry points called GC roots - local variables on every live thread's stack, static fields, and a few JVM internals - and walks the object graph from there. Anything it can reach stays. Everything else is garbage, even if two unreachable objects still point at each other.

That animation is the classic mark-and-sweep idea, and it is a mental model, not a literal description of any one collector: mark everything reachable from the roots, sweep away the rest. Real collectors add generations, regions, threads and concurrency on top, but reachability is the law underneath all of them.

Watch a real JVM collect

Theory is nice; logs are better. This program allocates 20 objects of ~100 KB each per round, then drops them - 6000 objects, roughly 600 MB of garbage in total, inside a heap capped at 64 MB. It also parks one object behind a WeakReference so we can watch a single object die:

import java.lang.ref.WeakReference;
import java.util.ArrayList;
import java.util.List;

public class GCDemo {
    static class Page { byte[] data = new byte[1024 * 100]; } // ~100 KB each

    public static void main(String[] args) throws Exception {
        long allocated = 0;
        for (int round = 0; round < 300; round++) {
            List<Page> live = new ArrayList<>();
            for (int i = 0; i < 20; i++) {
                live.add(new Page());   // alive only inside this round
                allocated++;
            }
            // 'live' goes out of scope here -> all 20 pages become garbage
        }
        System.out.println("allocated " + allocated + " short-lived Page objects");

        Page p = new Page();
        WeakReference<Page> watcher = new WeakReference<>(p);
        p = null;            // the only strong reference is gone
        System.gc();         // a REQUEST, not a command - more below
        Thread.sleep(200);
        System.out.println("after System.gc() in THIS run: watcher.get() == null -> "
                + (watcher.get() == null));
    }
}

Compiled and run on JDK 21 (Temurin 21.0.13) with GC logging on (-Xmx64m -Xlog:gc). Real output:

[0.001s][info][gc] Using Serial
[0.034s][info][gc] GC(0) Pause Young (Allocation Failure) 9M->2M(30M) 1.122ms
[0.035s][info][gc] GC(1) Pause Young (Allocation Failure) 11M->2M(30M) 0.518ms
...
allocated 6000 short-lived Page objects (~600 MB total)
after System.gc() in THIS run: watcher.get() == null -> true
[0.067s][info][gc] GC(69) Pause Full (System.gc()) 26M->2M(31M) 2.068ms

Read a log line like 9M->2M(30M) 1.122ms as: heap used went from 9 MB down to 2 MB (of 30 MB currently committed), and the pause lasted about a millisecond. (Allocation Failure) is the trigger's name, not an error - it means a new didn't fit, so the JVM collected and then continued. The headline result: 600 MB of objects flowed through a 64 MB heap and nothing ran out of memory. The collector reclaimed each round's dead pages before the next round needed the space. That is the entire promise of GC, in one number pair.

"Most objects die young" - and who collects them

Notice the pattern in the demo: every Page is dead by the end of its loop iteration. This turns out to be the normal case in most programs, and collectors exploit it with the generational hypothesis: collect the young part of the heap often and cheaply, because most of it is already garbage; examine long-lived objects rarely.

Treat generations as a strategy, not a JVM law - how it is implemented is collector-specific. JDK 21 ships several collectors, and the official tuning guide says the serial collector "uses a single thread to perform all garbage collection work" and is "selected by default on certain hardware and operating system configurations", while G1 "is selected by default on most hardware and operating system configurations". That is exactly what happened here: this small sandbox VM picked Serial (Using Serial in the log), while most server-class machines get G1.

Same program, one flag different (-XX:+UseG1GC), real output:

[0.001s][info][gc] Using G1
[0.036s][info][gc] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 3M->2M(34M) 1.013ms
...

Serial ran 69 young collections over the run; G1 ran 26 evacuation pauses for the same workload. Two honest caveats: these numbers are one machine, one run, one toy workload - not a benchmark and not a ranking - and G1's "evacuation" works differently inside (it copies live objects out of chosen heap regions rather than sweeping in place). The tuning guide's actual selection advice: serial for small data sets (up to ~100 MB) or single processors; G1 when "response time is more important than overall throughput and garbage collection pauses must be kept shorter"; ZGC when response time is a high priority.

Reclaiming objects is not returning memory to the OS

One distinction worth keeping straight: when the collector reclaims a dead object, that space returns to the Java heap, which the JVM already owns. Whether the JVM later hands memory back to the operating system is a separate decision - it depends on the collector and its flags, and the JVM is allowed to keep the memory for future allocations. So "GC freed my objects" and "my process shrank in Task Manager" are different events, and the first does not imply the second.

Where the kernel fits

The collector itself is ordinary JVM code running in user space - marking, sweeping, and copying are memory operations inside the process, no system calls needed. But it does not float above the OS:

Memory mapping and commit. The heap sits in address space the JVM obtained from the kernel (via mmap on Linux - "creates a new mapping in the virtual address space of the calling process", per the man page). Growing or committing heap, and any return of memory to the OS, crosses that boundary.
Page faults. Touching freshly mapped pages traps into the kernel to back them with physical memory - during allocation, inside your code and the collector's alike.
Thread scheduling and wakeups. GC work runs on threads (dedicated GC threads, and yours during stop-the-world pauses). The OS schedules them; parking and waking threads is kernel-assisted synchronization.

How much of this you feel depends on the collector and platform - a single-threaded Serial pause and G1's concurrent phases interact with the OS very differently.

System.gc(), WeakReference, and why nothing here is a promise

Two things in the demo deserve skepticism, and the docs back the skepticism. The JavaDoc for System.gc() says calling it "suggests that the Java Virtual Machine expend effort toward recycling unused objects" and warns: "There is no guarantee that this effort will recycle any particular number of unused objects ... or complete at any particular time, if at all." A WeakReference simply lets you observe the outcome: get() returns the object while it lives and null after the collector clears it.

In this run the request was honored - you can see Pause Full (System.gc()) in the log and the watcher went null. In another JVM, another run, or with -XX:+DisableExplicitGC, neither has to happen. Treat System.gc() as a hint you almost never need in production code.

What to take away

Reachability decides life and death - from GC roots, not reference counts.
You almost never manage memory manually - but allocation rate is real cost; every new is future GC work.
Read your collector's log first. -Xlog:gc is one flag and tells you trigger, sizes, and pause time.
Pick the collector for the workload with the official guide's rules of thumb, and distrust single-run numbers - including the ones in this article, quoted as one machine's experiment.

Sources

Written with AI assistance; every code example and GC log above comes from real runs on JDK 21 (Temurin 21.0.13), and the collector counts and timings are one machine's results, not benchmarks. The animation is an illustration of mark-and-sweep as a mental model, not a trace of any specific collector.

How a Stack Works: A Quick Walkthrough with Java

Vishnu B — Sat, 07 Nov 2026 12:30:23 +0000

A browser's Back button, an undo feature, and the JVM's own method call stack all share one idea: the last thing added is the first thing removed. That structure is a stack, and it earns its name honestly - it behaves like a stack of plates. You add a plate to the top, you take a plate from the top, and you never slide one out from the middle.

Let's build the browser-history version in Java, watch it run, and then go under the hood: where the stack's memory actually comes from, what the JVM's own stack does on every call, and whether the operating system's kernel is involved at all. (Spoiler: mostly not.)

Just three moves

A stack only needs three operations, all at the top:

push - put an item on top
pop - take the top item off
peek - look at the top item without removing it

That restriction is the whole point. Because you can only touch the top, "last in, first out" (LIFO) is guaranteed - no indexing, no searching, no surprises. Here is the full life of a small browser-history stack, animated:

The code

Java has a legacy Stack class, but you should not use it in new code. The official JavaDoc for java.util.Stack says it directly: "A more complete and consistent set of LIFO stack operations is provided by the Deque interface and its implementations, which should be used in preference to this class." Their own example is Deque<Integer> stack = new ArrayDeque<Integer>(); - and that is what we will use.

import java.util.ArrayDeque;
import java.util.Deque;

public class StackDemo {

    public static void main(String[] args) {
        // The JDK's recommended stack: ArrayDeque used through the Deque interface
        Deque<String> history = new ArrayDeque<>();

        // push: visit three pages
        for (String page : new String[]{"home", "search", "product"}) {
            history.push(page);
            System.out.println("[push] visited '" + page + "'   -> stack now: " + history);
        }

        // peek: look at the top without removing it
        System.out.println("[peek] current page is '" + history.peek()
                + "'   (stack unchanged: " + history + ")");

        // pop: press the browser Back button until history is gone
        while (!history.isEmpty()) {
            String left = history.pop();
            System.out.println("[pop]  pressed Back, left '" + left + "'   -> stack now: " + history);
        }

        System.out.println("[done] stack empty? " + history.isEmpty()
                + " - no more pages to go back to");
    }
}

I compiled and ran this on JDK 21 (Temurin 21.0.13) before publishing. This is the real, unedited output:

[push] visited 'home'   -> stack now: [home]
[push] visited 'search'   -> stack now: [search, home]
[push] visited 'product'   -> stack now: [product, search, home]
[peek] current page is 'product'   (stack unchanged: [product, search, home])
[pop]  pressed Back, left 'product'   -> stack now: [search, home]
[pop]  pressed Back, left 'search'   -> stack now: [home]
[pop]  pressed Back, left 'home'   -> stack now: []
[done] stack empty? true - no more pages to go back to

Three things to notice:

Order flipped on the way out. We pushed home, search, product - we popped product, search, home. That reversal is LIFO, and it is exactly why a stack models Back buttons and undo: the most recent action is the first one you reverse.
peek changed nothing. The stack printed identically before and after. Use peek when you need the current page; use pop when you are leaving it.
ArrayDeque's toString prints the top first. [product, search, home] reads top-to-bottom, which is handy for quick debugging.

Where the stack actually lives: the heap

So where do those pushed strings go? The JVM specification says the heap is "the run-time data area from which memory for all class instances and arrays is allocated" - one big shared region, cleaned up by the garbage collector.

ArrayDeque has no node objects or pointers. It keeps one plain Object[] and two ints, head and tail. A push (which is addFirst underneath) moves head one slot backward and writes your reference into that slot. That is the entire memory cost of a push: one array slot.

This is private implementation detail, so I verified it with reflection instead of trusting the docs - a small program that reads the actual backing array out of a live ArrayDeque (run with --add-opens java.base/java.util=ALL-UNNAMED, since the module system hides these fields). Real output:

new ArrayDeque<>(): one Object[] allocated on the heap, id=1528902577, length=17
push("home"):   head=16 tail=0 -> elements[16]=home
push x3:         head=14 tail=0 -> elements[head..]=product, search, home (push writes BEFORE head; same array, no new allocation)
pop():           head=15 -> old slot elements[14]=null (nulled so the GC can collect the string)
after 22 pushes: array id=1528902577 -> id=2046562095, length 17 -> 36
same array object? false - full array means: allocate a bigger one, copy across, drop the old one for the GC

Four real behaviors, straight from the running JVM:

Construction allocates the deque object plus one array on the heap - the object's own fields (head, tail, the array reference), the array's header and 17 slots, and later whatever elements you store in it.
A push is one write into an existing slot - no allocation, no copying, as long as the array has spare capacity. (It writes before head, which is why head walks backward: 16, then 14. What happens when capacity runs out is the last bullet.)
A pop nulls the slot it freed. ArrayDeque deliberately overwrites the removed reference with null so the garbage collector can reclaim the popped object even though the array still exists.
Growth means reallocation. When the array fills, ArrayDeque allocates a bigger array, copies everything across, and abandons the old one for the GC. The definitive check in the output is same array object? false - plain Java reference inequality. The identity hash change (1528902577 -> 2046562095) corroborates that: an object's identity hash stays constant for its lifetime, so differing hashes mean different objects (equal hashes, by contrast, would prove nothing). Either way, identity hashes are identifiers, not memory addresses.

The other stack: the JVM call stack

Your program's stack is a data structure you control. The JVM also keeps a stack of its own for every thread, and you never touch it directly. The spec: "Each Java Virtual Machine thread has a private Java Virtual Machine stack, created at the same time as the thread. A Java Virtual Machine stack stores frames." A frame holds one method call: its local variables, its return address, and - satisfyingly - "a last-in-first-out (LIFO) stack known as its operand stack". Every Java method runs on top of a tiny private stack of its own.

You can watch this without any tools beyond javap. Here is the real bytecode the compiler produced for the first push in the demo above:

 8: aload_1
 9: ldc           #10                 // String home
11: invokeinterface #12,  2           // InterfaceMethod java/util/Deque.push:(Ljava/lang/Object;)V

Read it as three moves: aload_1 pushes the deque reference onto main's operand stack, ldc pushes the constant "home" on top of it, and invokeinterface consumes both to make the call - conceptually, a fresh frame for push() goes onto this thread's JVM stack, and when push returns, its frame pops off. Call, push frame; return, pop frame. LIFO all the way down, animated:

One honest caveat: frames and operand stacks are the JVM specification's conceptual model - a contract for how execution must behave, not a description of the silicon. HotSpot's JIT compiler routinely inlines small calls like this one, so at full speed there may be no separate physical frame for push() at all, and operand-stack values may sit in CPU registers instead of real stack slots. The JVM only has to behave as if the spec's stack exists; the optimized machine code underneath is free to cheat, invisibly. The animation above shows the spec's model, which is exactly what the bytecode means.

How deep can the call stack go? The spec is blunt: "If the computation in a thread requires a larger Java Virtual Machine stack than is permitted, the Java Virtual Machine throws a StackOverflowError." The stack size is a real, settable quantity - the -Xss flag. A quick recursion experiment on this machine:

$ java StackDepth
StackOverflowError after 10731 nested calls
$ java -Xss256k StackDepth
StackOverflowError after 3471 nested calls

Treat the exact counts as one machine's experiment, not a promise - they shift between runs because JIT inlining changes how much stack each frame consumes. But the pattern is the lesson: shrink the per-thread stack to 256 KB and the same recursion dies roughly three times sooner. Every frame costs real memory, and the budget is finite.

Does the kernel get involved?

Almost never, and it is worth being precise about this rather than vaguely saying "it goes to the OS."

Everything above happens inside the JVM process, in ordinary user-space memory. A push is a few writes to an array the process already owns. Creating a frame is bookkeeping inside memory the thread already has. No system call is made, so the kernel - the privileged core of the OS that manages hardware, processes, and memory - never enters the story for these operations.

The kernel does appear at a few boundaries:

Reserving memory. When the JVM starts (or grows the heap), it asks the kernel for address space with mmap, which the Linux man page defines as creating "a new mapping in the virtual address space of the calling process". After that, the JVM manages that memory itself - that's why pushes don't need the kernel.
Page faults. The first time a thread touches a freshly reserved page, the CPU traps into the kernel to actually back it with physical memory. This is invisible and automatic, not something your code requests.
Threads and I/O. Scheduling your thread onto a CPU, and any real file or network I/O, is kernel work.

And the kernel has its own stack, separate from everything here: when a thread does enter the kernel through a system call or interrupt, the CPU switches to a small per-thread kernel stack, used only for that visit. So there are really three stacks in this story - the ArrayDeque data structure on the heap, the JVM call stack of your thread, and the kernel's own stack - and a Java push only ever touches the first two.

Two habits that save real bugs

Check before you pop. Calling pop() on an empty stack throws NoSuchElementException. The while (!history.isEmpty()) guard in the demo is not decoration - it is the standard pattern. If you would rather get a signal than an exception, poll() returns null on an empty stack instead of throwing.

Declare the type as the interface. Writing Deque<String> history = new ArrayDeque<>(); instead of ArrayDeque<String> history = ... means the rest of your code only depends on the stack operations, and you could swap the implementation later without touching it.

Where stacks show up

Undo/redo and browser history - reverse the most recent action first.
Every running Java program - the JVM call stack above, plus the operand stack inside each frame.
Matching and parsing - balanced brackets, HTML tags, and nested expressions are classic stack problems: push an opener, pop when you meet its closer.
Depth-first search - DFS is a loop with a stack; binary search halves a range, DFS dives down a stack.

All three operations are O(1) - constant time, however big the stack grows. Now you also know why: each one is a pointer move plus, at most, one memory write.

Sources

Written with AI assistance; every code example above, including the reflection probe and the bytecode and recursion experiments, was compiled and run on JDK 21 (Temurin 21.0.13) before publishing, and the outputs quoted are real. Both animations are illustrations of JVM behavior, not screen recordings; the frame counts in the recursion experiment are one machine's results and will vary.

How Kafka Works: A Quick Walkthrough with Java

Vishnu B — Fri, 06 Nov 2026 06:14:11 +0000

Your order service needs to tell the invoice service, the email service, and the analytics pipeline that an order happened. You could wire them together directly - but every new consumer means changing the producer, and if a consumer is down, messages get lost.

Kafka takes a different approach: the producer drops the message into a durable log, and each consumer reads that log whenever it is ready, at its own pace, without the producer even knowing who they are. Let's see the whole flow working, with a real Kafka broker and a real Java client.

The five pieces that matter

Topic: a named stream of messages, like greetings. Producers write to it, consumers read from it.
Partition: a topic is split into partitions. Each partition is an ordered, append-only log. Partitions are how Kafka scales: different consumers can read different partitions in parallel.
Offset: a message's position in its partition - 0, 1, 2, ... Once written, a message never changes; consumers just move forward through the offsets.
Producer: the app that appends messages. If you give the message a key, the key's hash decides which partition it lands in, so all messages with the same key stay in order in the same partition.
Consumer group: consumers with the same group id share the partitions between them and Kafka tracks how far each group has read.

Here is the whole journey, animated - three messages go in, and a consumer pulls them back out:

Running a real broker

The official Kafka quickstart runs a single-node broker without ZooKeeper (KRaft mode) in three commands, which is exactly what I did - this article's output is from Apache Kafka 4.4.0 on JDK 21:

# 1. generate a cluster id
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# 2. format the log directories
bin/kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID -c config/server.properties

# 3. start the broker
bin/kafka-server-start.sh config/server.properties

Startup logged Kafka Server started (kafka.server.KafkaRaftServer), and the broker was ready on localhost:9092.

A Java producer and consumer in one file

This complete program creates a topic with 3 partitions, produces 3 keyed messages, and reads them back. It uses only the kafka-clients jar that ships in the Kafka download's libs folder - no extra dependencies:

import org.apache.kafka.clients.admin.AdminClient;
import org.apache.kafka.clients.admin.NewTopic;
import org.apache.kafka.clients.consumer.ConsumerConfig;
import org.apache.kafka.clients.consumer.ConsumerRecords;
import org.apache.kafka.clients.consumer.KafkaConsumer;
import org.apache.kafka.clients.producer.KafkaProducer;
import org.apache.kafka.clients.producer.ProducerConfig;
import org.apache.kafka.clients.producer.ProducerRecord;
import org.apache.kafka.common.serialization.StringDeserializer;
import org.apache.kafka.common.serialization.StringSerializer;

import java.time.Duration;
import java.util.List;
import java.util.Properties;

public class KafkaWalkthrough {

    static final String TOPIC = "greetings";

    public static void main(String[] args) throws Exception {
        createTopic();
        produce();
        consume();
    }

    static void createTopic() throws Exception {
        Properties p = new Properties();
        p.put("bootstrap.servers", "localhost:9092");
        try (AdminClient admin = AdminClient.create(p)) {
            admin.createTopics(List.of(new NewTopic(TOPIC, 3, (short) 1))).all().get();
            System.out.println("[setup] created topic '" + TOPIC + "' with 3 partitions");
        }
    }

    static void produce() throws Exception {
        Properties p = new Properties();
        p.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        p.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        p.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        try (KafkaProducer<String, String> producer = new KafkaProducer<>(p)) {
            String[][] msgs = {
                {"vishnu", "hello kafka"},
                {"asha", "kafka is a log"},
                {"ravi", "partitions scale reads"},
            };
            for (String[] m : msgs) {
                var meta = producer.send(new ProducerRecord<>(TOPIC, m[0], m[1])).get();
                System.out.printf("[producer] sent key=%s value='%s' -> partition=%d offset=%d%n",
                        m[0], m[1], meta.partition(), meta.offset());
            }
        }
    }

    static void consume() {
        Properties p = new Properties();
        p.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        p.put(ConsumerConfig.GROUP_ID_CONFIG, "walkthrough-group");
        p.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
        p.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
        p.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
        try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(p)) {
            consumer.subscribe(List.of(TOPIC));
            int got = 0;
            long deadline = System.currentTimeMillis() + 15000;
            while (got < 3 && System.currentTimeMillis() < deadline) {
                ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(500));
                records.forEach(r -> {
                    System.out.printf("[consumer] read key=%s value='%s' from partition=%d offset=%d%n",
                            r.key(), r.value(), r.partition(), r.offset());
                });
                got += records.count();
            }
        }
    }
}

I compiled it with javac -cp "libs/*" KafkaWalkthrough.java and ran it against the live broker. This is the real, unedited output:

[setup] created topic 'greetings' with 3 partitions
[producer] sent key=vishnu value='hello kafka' -> partition=0 offset=0
[producer] sent key=asha value='kafka is a log' -> partition=0 offset=1
[producer] sent key=ravi value='partitions scale reads' -> partition=0 offset=2
[consumer] read key=vishnu value='hello kafka' from partition=0 offset=0
[consumer] read key=asha value='kafka is a log' from partition=0 offset=1
[consumer] read key=ravi value='partitions scale reads' from partition=0 offset=2

Four honest observations from that output:

All three keys hashed to partition 0. With only three partitions and three keys, that is chance, not a rule - other keys land in partitions 1 and 2. The guarantee is narrower: the same key always goes to the same partition.
Offsets count up within a partition. 0, 1, 2 - the append-only log in action.
The consumer replayed history. The producer had already finished and exited when the consumer started. Nothing was lost, because the topic stores messages; AUTO_OFFSET_RESET_CONFIG = "earliest" told the new consumer group to start from offset 0.
Order is per-partition. The consumer got the messages in offset order. Across partitions there is no global order - another reason keys matter when order matters.

When Kafka is the right tool

Decoupling services: the producer does not know or care who consumes.
Buffering bursts: consumers catch up after a spike or an outage instead of dropping work.
Multiple independent readers: analytics, email, and search can each have their own consumer group over the same topic.
Replay: because messages persist, a new service can rebuild its state by reading from offset 0.

It is more machinery than a plain queue, so for one producer talking to one consumer with no replay needs, a simpler tool can be the better call. Kafka earns its keep when the log itself - durable, ordered per partition, readable by many groups - is what you need.

Sources

Written with AI assistance; code examples were compiled and run against a real single-node Kafka 4.4.0 broker on JDK 21 before publishing. The animation is an illustration of the message flow, not a screen recording.

How a Spring Boot Request Travels: A Quick Walkthrough

Vishnu B — Thu, 05 Nov 2026 12:30:26 +0000

You type a URL, hit enter, and JSON comes back. Between those two moments, your Spring Boot app runs a small relay race: the request passes through an embedded web server, a front controller, and a few helpers before your code ever runs. Once you can picture that path, debugging gets much easier - a 404, a missing parameter, and a broken interceptor all fail at different stops on the same road.

Let's follow one GET request end to end, with a real app you can run yourself.

The five stops

Here is the whole journey, animated. Watch the request packet travel from the client to the controller and the response come back:

In plain words:

The client sends the request. A browser, curl, or another service sends GET /api/greet?name=Vishnu.
The embedded server accepts it. Spring Boot runs its own web server inside the app. Per the Spring Boot reference, "Spring Boot includes support for embedded Tomcat and Jetty servers", and by default it "listens for HTTP requests on port 8080". No separate server install - main() starts everything.
The DispatcherServlet takes over. Spring MVC is "designed around the front controller pattern where a central Servlet, the DispatcherServlet, provides a shared algorithm for request processing, while actual work is performed by configurable delegate components" (Spring Framework docs). In practice: one servlet receives everything, then looks up which @GetMapping matches the path.
Interceptors get a look. Before and after your controller, interceptors can inspect or reject the request - good for logging, auth checks, and timing.
Your controller runs. The method returns data, Spring converts it to JSON, and the response travels back out the way it came.

A real app that shows its own journey

This is a complete Spring Boot app. The interceptor and controller print a line at each stop, so the server's own log narrates the relay:

package com.example.reqdemo;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.Map;

@SpringBootApplication
public class ReqDemoApplication {

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

    @RestController
    static class GreetController {
        @GetMapping("/api/greet")
        public Map<String, String> greet(@RequestParam(defaultValue = "world") String name) {
            System.out.println("[controller] DispatcherServlet handed me GET /api/greet, name=" + name);
            return Map.of("message", "Hello, " + name + "!");
        }
    }

    @Component
    static class FlowInterceptor implements HandlerInterceptor {
        @Override
        public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
            System.out.println("[interceptor] request passed the servlet and filters: "
                    + req.getMethod() + " " + req.getRequestURI());
            return true;
        }

        @Override
        public void afterCompletion(HttpServletRequest req, HttpServletResponse res,
                                    Object handler, Exception ex) {
            System.out.println("[interceptor] response written, status=" + res.getStatus()
                    + " - request journey complete");
        }
    }

    @Component
    static class WebConfig implements WebMvcConfigurer {
        private final FlowInterceptor interceptor;
        WebConfig(FlowInterceptor interceptor) { this.interceptor = interceptor; }
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            registry.addInterceptor(interceptor);
        }
    }
}

I compiled and ran this on JDK 21 (Temurin 21.0.13) with Spring Boot 3.5.7 before publishing. Here is the real, unedited output.

Startup - the embedded Tomcat coming up inside the app (port 8090 here, because 8080 was already in use in the run environment):

Tomcat initialized with port 8090 (http)
Tomcat started on port 8090 (http) with context path '/'
Started ReqDemoApplication in 1.054 seconds

Then curl http://localhost:8090/api/greet?name=Vishnu returned:

{"message":"Hello, Vishnu!"}

And the app's own log narrated the journey, exactly in the order of the animation:

[interceptor] request passed the servlet and filters: GET /api/greet
[controller] DispatcherServlet handed me GET /api/greet, name=Vishnu
[interceptor] response written, status=200 - request journey complete

Three things worth noticing:

The interceptor's preHandle runs before the controller, and afterCompletion runs after the response is written. Your controller is the middle of the sandwich, not the start.
Returning a Map was enough to get JSON. Spring Boot auto-configures an HTTP message converter that serializes the return value - you never wrote JSON yourself.
The journey back through the server is mostly invisible to your code, which is why the interceptor's completion callback is a handy place to log it.

A 404 travels the same road

One detail that surprises people: an unknown path goes through the same pipeline. Calling curl http://localhost:8090/api/nope produced this log:

[interceptor] request passed the servlet and filters: GET /api/nope
[interceptor] response written, status=404 - request journey complete
[interceptor] request passed the servlet and filters: GET /error
[interceptor] response written, status=404 - request journey complete

Two journeys for one request. The DispatcherServlet found no mapping for /api/nope, so it raised an error, and the servlet container then dispatched the request again, this time to Spring Boot's built-in /error endpoint - which is what generated the JSON error body:

{"timestamp":"2026-11-05T10:56:56.906+00:00","status":404,"error":"Not Found","path":"/api/nope"}

So when you debug a 404, the first question is: did the request reach the DispatcherServlet at all? If your interceptor logged it, the server side is fine and the path or mapping is wrong. If it did not, the problem is earlier - wrong port, wrong context path, or something in front of the app.

When this mental model pays off

Debugging 404s and 405s: find out which stop rejected the request instead of guessing.
Placing cross-cutting logic: auth checks, request IDs, and timing belong in interceptors or filters, not copied into every controller.
Reading startup logs: Tomcat started on port ... tells you the embedded server is the entry point, and it is part of your app's process.

If dependency injection is how your beans find each other, the DispatcherServlet is how the outside world finds your beans. Both are quiet machinery that runs before your code does.

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing. The animation is an illustration of the request flow, not a screen recording.

How Binary Search Works: A Quick Walkthrough with Java

Vishnu B — Tue, 03 Nov 2026 12:30:27 +0000

Imagine you are looking for a word in a paper dictionary. You would not start at page 1 and flip one page at a time. You open it near the middle, see whether your word comes before or after that page, and throw away the half that cannot contain it. A few more halvings and you are on the right page.

That is binary search. It is one of the most useful algorithms to know, and Java ships it built in. Let's walk through exactly how it works, step by step, with real code and real output.

The one rule: the data must be sorted

Binary search only works on a sorted collection. Sorting is what makes the "throw away half" trick safe: if the middle value is smaller than your target, every value to the left of it is also smaller, so none of them can be the target.

On a sorted array, the algorithm is three simple steps, repeated:

Look at the middle element of the current range.
If it equals the target, you are done.
If it is smaller, the target must be in the right half. If it is larger, the target must be in the left half. Repeat on that half only.

Here is the whole search for the value 61 in a 12-element sorted array, animated. Watch the low and high markers close in as each probe eliminates half of what is left:

Four probes found the answer. A plain left-to-right scan could have taken up to twelve.

The same search in Java

Here is a complete, runnable version. It prints every probe so you can see the range shrink:

import java.util.Arrays;

public class BinarySearchDemo {

    static int binarySearch(int[] a, int target) {
        int low = 0, high = a.length - 1, step = 1;
        while (low <= high) {
            int mid = (low + high) >>> 1;   // middle index, overflow-safe
            System.out.printf("step %d: low=%d high=%d mid=%d -> a[%d]=%d%n",
                    step, low, high, mid, mid, a[mid]);
            if (a[mid] == target) {
                System.out.println("found " + target + " at index " + mid);
                return mid;
            }
            if (a[mid] < target) {
                low = mid + 1;              // target is in the right half
            } else {
                high = mid - 1;             // target is in the left half
            }
            step++;
        }
        System.out.println(target + " is not in the array");
        return -1;
    }

    public static void main(String[] args) {
        int[] scores = {3, 8, 15, 21, 34, 42, 55, 61, 78, 85, 91, 99};
        binarySearch(scores, 61);
        binarySearch(scores, 30);
    }
}

I compiled and ran this on JDK 21 (Temurin 21.0.13) before publishing. This is the real, unedited output:

step 1: low=0 high=11 mid=5 -> a[5]=42
step 2: low=6 high=11 mid=8 -> a[8]=78
step 3: low=6 high=7 mid=6 -> a[6]=55
step 4: low=7 high=7 mid=7 -> a[7]=61
found 61 at index 7

And for a value that is not in the array, 30:

step 1: low=0 high=11 mid=5 -> a[5]=42
step 2: low=0 high=4 mid=2 -> a[2]=15
step 3: low=3 high=4 mid=3 -> a[3]=21
step 4: low=4 high=4 mid=4 -> a[4]=34
30 is not in the array

A few small things in the code are worth knowing:

(low + high) >>> 1 is the average of low and high, computed in a way that avoids integer overflow on very large arrays. (low + high) / 2 works for small arrays too.
while (low <= high) keeps going while the range still has elements. When low passes high, the range is empty and the target is not there.
After each probe we move one marker past the middle (mid + 1 or mid - 1), because we just checked mid itself.

You usually do not write this by hand

The JDK already ships binary search: Arrays.binarySearch for arrays and Collections.binarySearch for lists. The official Java 21 documentation states the two rules that matter:

"The array must be sorted ... prior to making this call. If it is not sorted, the results are undefined." Undefined means the method will not throw an error to warn you; it can simply return a wrong answer.
The return value is "index of the search key, if it is contained in the array; otherwise, (-(insertion point) - 1)". So a negative result means "not found", and the exact negative number tells you where the value would sit.

Running the built-in against the same array confirms both rules:

Arrays.binarySearch(scores, 61) = 7
Arrays.binarySearch(scores, 30) = -5

The -5 decodes like this: insertion point is 4 (30 would belong at index 4), and the documented formula gives -(4) - 1 = -5. A negative result is never a valid index, so checking result >= 0 is all you need.

Why it is fast

Every probe discards half of what remains, so the number of steps grows with the logarithm of the size, not the size itself:

elements	worst-case probes (binary)	worst-case checks (linear)
12	4	12
1,000	10	1,000
1,000,000	20	1,000,000

That is why binary search is described as O(log n) time and why sorting your data once can pay off when you search it many times. It needs O(1) extra space when written iteratively, as above.

When to reach for it

The data is already sorted, or sorted once and searched often.
You need a plain value lookup in an array or list.
The data is unsorted and searched rarely: just do a linear scan, or sort first if you can.
You need frequent inserts and lookups together: a HashMap (covered in an earlier walkthrough) or a TreeSet is usually a better fit.

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing. The animation is an illustration of the algorithm's flow, not a screen recording.

How Dependency Injection Works in Spring Boot: A Quick Walkthrough

Vishnu B — Sun, 01 Nov 2026 12:32:27 +0000

If you have written any Spring Boot code, you have seen this: a class asks for another class in its constructor, and somehow the right object is just there. Nobody called new. Nobody looked anything up. Let's see who does that work, with plain words and a tiny Spring Boot app you can run yourself.

The idea in one minute

You mark classes with annotations like @Service or @Component.
When the app starts, Spring Boot scans your code and creates an object of each one. These managed objects are called beans, and they live in the Spring container (the ApplicationContext).
When a bean's constructor asks for another bean, the container passes it in. That passing-in is dependency injection.

The Spring documentation calls this Inversion of Control: instead of your object building or finding its own helpers, the container creates them and hands them over. Your class just declares what it needs.

Watch the flow

The animation follows the real program below: main() hands control to Spring Boot, the scan finds the two annotated classes, the container creates the GreetingService bean, creates WelcomeRunner while injecting GreetingService into its constructor, and run() uses the injected bean.

Run it yourself

A complete Spring Boot app in one file (run with mvn compile exec:java -Dexec.mainClass=com.example.di.DiDemoApplication in a project with the spring-boot-starter dependency, Spring Boot 3.5.7):

package com.example.di;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

@SpringBootApplication
public class DiDemoApplication {

    // 1. A bean the container will create and manage
    @Service
    static class GreetingService {
        GreetingService() {
            System.out.println("[container] created bean: GreetingService");
        }
        String greet(String name) {
            return "Hello, " + name + "!";
        }
    }

    // 2. A bean that NEEDS a GreetingService: constructor injection
    @Component
    static class WelcomeRunner implements CommandLineRunner {
        private final GreetingService greetingService;

        WelcomeRunner(GreetingService greetingService) {   // container injects it here
            this.greetingService = greetingService;
            System.out.println("[container] injected GreetingService into WelcomeRunner");
        }

        @Override
        public void run(String... args) {
            System.out.println("[app] WelcomeRunner.run() called with the injected bean");
            System.out.println("[app] " + greetingService.greet("Spring Boot"));
        }
    }

    public static void main(String[] args) {
        System.out.println("[you] main(): handing control to SpringApplication.run()");
        SpringApplication.run(DiDemoApplication.class, args);
        System.out.println("[you] main(): container shut down");
    }
}

What it actually printed (Spring Boot 3.5.7, Java 21)

Real run, startup banner and framework log lines trimmed:

[you] main(): handing control to SpringApplication.run()
:: Spring Boot ::                (v3.5.7)
... Starting DiDemoApplication using Java 21.0.13 ...
[container] created bean: GreetingService
[container] injected GreetingService into WelcomeRunner
... Started DiDemoApplication in 0.774 seconds ...
[app] WelcomeRunner.run() called with the injected bean
[app] Hello, Spring Boot!
[you] main(): container shut down

Read it in order and you can see the handoff:

Your main() does exactly one thing: start the container.
The container's log lines come before the app's: it creates GreetingService, then builds WelcomeRunner and passes the service into the constructor. All before "Started DiDemoApplication".
Only then does run() execute, already holding a ready-to-use bean. CommandLineRunner is just Spring Boot's way of saying "call this once everything is wired up".

What the docs add

Two ways to inject. The Spring Framework docs describe constructor-based and setter-based DI. The rule of thumb they give: constructors for mandatory dependencies, setters for optional ones.
Constructor injection is the recommended style. The Spring team advocates it because components stay immutable, required dependencies can never be null, and the object is always fully initialized when you get it. The Spring Boot docs give the same advice: use constructor injection plus @ComponentScan, which @SpringBootApplication already includes.
It pays off in tests. Because your class receives its helpers instead of building them, a test can hand it a stub or mock instead of the real thing.

One honest caveat: the container does much more than this tiny demo shows (scopes, lazy init, configuration properties, proxies). But the core loop you saw above - scan, create, inject, use - is the part everything else builds on.

Sources

Written with AI assistance; code examples were compiled and run on Spring Boot 3.5.7 with JDK 21 before publishing.

How a HashMap Works: A Quick Walkthrough with Java

Vishnu B — Fri, 30 Oct 2026 12:31:05 +0000

You probably used a HashMap today without thinking about it. But what actually happens when you call map.put("apple", 3)? Let's open the box, with plain words and a small Java program you can run yourself.

The idea in one minute

A HashMap is an array of buckets. When you store something:

The key goes through hashCode(), which turns it into a number.
That number is reduced to a bucket index (in our model: hash % 8).
The key and value are stored in that bucket.

Two different keys can land on the same bucket. That is a collision, and the bucket simply keeps them as a small chain. Finding a value means: hash the key, jump to the bucket, walk the short chain comparing keys.

Watch the flow

The animation walks three moments: storing apple in an empty bucket, storing mango which collides with apple and joins its chain, then finding apple again by walking that chain. (It shows a simplified 8-bucket teaching model - the same one the code below runs.)

Run it yourself

This tiny hash map prints every step, so you can see the hashing, the bucket choice, the collision and the chain walk:

import java.util.HashMap;

public class HashMapDemo {

    // A tiny hand-rolled hash map so we can watch every step
    static class SimpleHashMap {
        static final int BUCKETS = 8;
        static class Node {
            String key; int value; Node next;
            Node(String k, int v) { key = k; value = v; }
        }
        Node[] table = new Node[BUCKETS];

        int bucketIndex(String key) {
            return (key.hashCode() & 0x7fffffff) % BUCKETS;
        }

        void put(String key, int value) {
            int i = bucketIndex(key);
            for (Node n = table[i]; n != null; n = n.next) {
                if (n.key.equals(key)) {
                    System.out.println("put(" + key + ", " + value + ") -> bucket " + i + ": key exists, value overwritten");
                    n.value = value;
                    return;
                }
            }
            Node n = new Node(key, value);
            n.next = table[i];
            table[i] = n;
            System.out.println("put(" + key + ", " + value + ") -> hash " + (key.hashCode() & 0x7fffffff)
                + " -> bucket " + i + (n.next != null ? " (collision: added to chain)" : ""));
        }

        Integer get(String key) {
            int i = bucketIndex(key);
            int steps = 0;
            for (Node n = table[i]; n != null; n = n.next) {
                steps++;
                if (n.key.equals(key)) {
                    System.out.println("get(" + key + ") -> bucket " + i + ", found after " + steps + " step(s): " + n.value);
                    return n.value;
                }
            }
            System.out.println("get(" + key + ") -> bucket " + i + ": not in chain, returns null");
            return null;
        }

        void printTable() {
            System.out.println("\nFinal table (" + BUCKETS + " buckets):");
            for (int i = 0; i < BUCKETS; i++) {
                StringBuilder sb = new StringBuilder("bucket " + i + ": ");
                if (table[i] == null) sb.append("(empty)");
                for (Node n = table[i]; n != null; n = n.next) sb.append(n.key).append("=").append(n.value).append(" -> ");
                if (sb.toString().endsWith(" -> ")) sb.setLength(sb.length() - 4);
                System.out.println(sb);
            }
        }
    }

    public static void main(String[] args) {
        SimpleHashMap map = new SimpleHashMap();
        map.put("cat", 1);
        map.put("dog", 2);
        map.put("apple", 3);
        map.put("banana", 4);
        map.put("mango", 5);
        map.put("cat", 9);   // same key again: overwrite
        map.printTable();
        System.out.println();
        map.get("dog");
        map.get("apple");
        map.get("zebra");

        System.out.println("\n-- The real java.util.HashMap --");
        HashMap<String, Integer> real = new HashMap<>();
        real.put("cat", 1);
        real.put("dog", 2);
        real.put("apple", 3);
        real.put(null, 99);           // null key is allowed
        System.out.println("real.get(\"cat\") = " + real.get("cat"));
        System.out.println("real.get(null) = " + real.get(null));
        System.out.println("iteration order: " + real.keySet() + "  (not guaranteed, do not rely on it)");
    }
}

What it actually printed (JDK 21)

put(cat, 1) -> hash 98262 -> bucket 6
put(dog, 2) -> hash 99644 -> bucket 4
put(apple, 3) -> hash 93029210 -> bucket 2
put(banana, 4) -> hash 751128421 -> bucket 5
put(mango, 5) -> hash 103662530 -> bucket 2 (collision: added to chain)
put(cat, 9) -> bucket 6: key exists, value overwritten

Final table (8 buckets):
bucket 0: (empty)
bucket 1: (empty)
bucket 2: mango=5 -> apple=3
bucket 3: (empty)
bucket 4: dog=2
bucket 5: banana=4
bucket 6: cat=9
bucket 7: (empty)

get(dog) -> bucket 4, found after 1 step(s): 2
get(apple) -> bucket 2, found after 2 step(s): 3
get(zebra) -> bucket 6: not in chain, returns null

-- The real java.util.HashMap --
real.get("cat") = 1
real.get(null) = 99
iteration order: [null, apple, cat, dog]  (not guaranteed, do not rely on it)

Three things to notice:

mango and apple both hash to bucket 2, so they sit in one chain. get("apple") checks mango first, then finds apple on step 2.
Storing cat again does not add a second entry; it overwrites the value (1 becomes 9).
zebra hashes to bucket 6, which holds cat. The map walks that chain, finds no match, and returns null - a wrong bucket is never even looked at.

The real HashMap adds a few upgrades

Our 8-bucket model keeps the moving parts visible. Per the Java 21 HashMap documentation, the real one:

Gives constant-time get and put, assuming the hash function spreads keys well across buckets.
Grows automatically: when entries exceed capacity x load factor (default 0.75), it rehashes to roughly twice the buckets.
Permits one null key and any number of null values.
Makes no order guarantees - do not rely on iteration order.
Is not synchronized; for concurrent access wrap it with Collections.synchronizedMap (or use a concurrent map).
Can use comparison order to break ties when many keys share a hash code (in practice, very long chains are turned into trees to keep lookups fast).

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing.

AWS IAM Policy Evaluation: A Quick Walkthrough with Java

Vishnu B — Wed, 28 Oct 2026 12:30:16 +0000

AWS IAM Policy Evaluation: A Quick Walkthrough with Java

"Why is my S3 request denied? I literally have an Allow for it." If you have worked with AWS for more than a week, you have hit this. Getting unstuck starts with how IAM evaluates policies - and while the full evaluation has several layers, the core rules are simpler than they feel once you see them in code.

In this walkthrough we will look at three rules at the core of identity-based policy evaluation inside a single AWS account, then simulate them in a small Java program you can run yourself. This is a simplified identity-policy example, not the full IAM evaluation: the real engine also layers in resource-based policies, permissions boundaries, Organizations SCPs/RCPs, session policies, and conditions, which this demo intentionally leaves out.

The three rules (single account)

Per the AWS policy evaluation logic docs:

By default, everything is denied (implicit deny). If no statement matches your request with an Allow, the answer is no.
An explicit Allow overrides the default. Match a statement with Effect: Allow and the request goes through...
...unless an explicit Deny matches. An explicit deny in any applicable policy overrides any allow. Always.

For an IAM user or role inside one account, AWS takes the union of identity-based policies and resource-based policies: if either allows the action and nothing explicitly denies it, the request is allowed.

A policy is just JSON

From the IAM JSON policy element reference, the pieces that matter for evaluation:

Effect - Allow or Deny
Action - what is being requested, e.g. s3:GetObject. Wildcards like s3:Get* are allowed.
Resource - the ARN the action applies to, also wildcard-friendly, e.g. arn:aws:s3:::photos/*

Simulating the evaluator in Java

Here is a minimal evaluator that follows the three rules. It is a simplified simulation of the single-account, identity-based flow - the real AWS engine also considers resource-based policies, permissions boundaries, Organizations SCPs/RCPs, session policies, and conditions, which this demo intentionally leaves out.

import java.util.List;

public class IamPolicyDemo {

    enum Effect { ALLOW, DENY }

    record Statement(Effect effect, List<String> actions, List<String> resources) {}

    record Request(String principal, String action, String resource) {}

    // IAM-style wildcard match: '*' matches any sequence of characters
    static boolean wildcardMatch(String pattern, String value) {
        String regex = pattern.replace(".", "\\.").replace("*", ".*");
        return value.matches(regex);
    }

    static boolean matches(Statement s, Request r) {
        boolean actionOk = s.actions().stream().anyMatch(a -> wildcardMatch(a, r.action()));
        boolean resourceOk = s.resources().stream().anyMatch(res -> wildcardMatch(res, r.resource()));
        return actionOk && resourceOk;
    }

    // Simplified single-account flow: explicit deny > allow > implicit deny
    static String evaluate(List<Statement> policy, Request r) {
        List<Statement> matching = policy.stream().filter(s -> matches(s, r)).toList();
        boolean explicitDeny = matching.stream().anyMatch(s -> s.effect() == Effect.DENY);
        if (explicitDeny) return "DENIED  (explicit deny)";
        boolean allow = matching.stream().anyMatch(s -> s.effect() == Effect.ALLOW);
        if (allow) return "ALLOWED";
        return "DENIED  (implicit deny - no statement matched Allow)";
    }

    public static void main(String[] args) {
        List<Statement> alicePolicy = List.of(
            new Statement(Effect.ALLOW, List.of("s3:GetObject"), List.of("arn:aws:s3:::photos/*"))
        );

        List<Statement> bobPolicy = List.of(
            new Statement(Effect.ALLOW, List.of("s3:*"), List.of("arn:aws:s3:::photos", "arn:aws:s3:::photos/*")),
            new Statement(Effect.DENY,  List.of("s3:DeleteObject"), List.of("arn:aws:s3:::photos/*"))
        );

        Request[] requests = {
            new Request("alice", "s3:GetObject",      "arn:aws:s3:::photos/cat.jpg"),
            new Request("alice", "s3:DeleteObject",   "arn:aws:s3:::photos/cat.jpg"),
            new Request("bob",   "s3:PutObject",      "arn:aws:s3:::photos/dog.jpg"),
            new Request("bob",   "s3:DeleteObject",   "arn:aws:s3:::photos/dog.jpg"),
        };

        for (Request r : requests) {
            List<Statement> policy = r.principal().equals("alice") ? alicePolicy : bobPolicy;
            System.out.printf("%-5s %-16s %-30s -> %s%n",
                r.principal(), r.action(), r.resource(), evaluate(policy, r));
        }

        // Wildcard in Action: "s3:Get*" covers every read action
        List<Statement> readOnly = List.of(
            new Statement(Effect.ALLOW, List.of("s3:Get*"), List.of("*"))
        );
        System.out.println();
        System.out.println("Wildcard policy: Allow s3:Get* on *");
        for (String action : List.of("s3:GetObject", "s3:GetBucketLocation", "s3:PutObject")) {
            Request r = new Request("carol", action, "arn:aws:s3:::photos/cat.jpg");
            System.out.printf("%-5s %-20s -> %s%n", "carol", action, evaluate(readOnly, r));
        }
    }
}

Running it (real output)

Compiled and run locally on Temurin JDK 21:

alice s3:GetObject     arn:aws:s3:::photos/cat.jpg    -> ALLOWED
alice s3:DeleteObject  arn:aws:s3:::photos/cat.jpg    -> DENIED  (implicit deny - no statement matched Allow)
bob   s3:PutObject     arn:aws:s3:::photos/dog.jpg    -> ALLOWED
bob   s3:DeleteObject  arn:aws:s3:::photos/dog.jpg    -> DENIED  (explicit deny)

Wildcard policy: Allow s3:Get* on *
carol s3:GetObject         -> ALLOWED
carol s3:GetBucketLocation -> ALLOWED
carol s3:PutObject         -> DENIED  (implicit deny - no statement matched Allow)

Walk through it:

alice / GetObject matches her Allow - allowed.
alice / DeleteObject matches nothing, so the default kicks in: implicit deny. This is the rule that surprises people most; missing permission looks exactly like an explicit block from the client side.
bob / PutObject is covered by s3:* - allowed.
bob / DeleteObject is covered by s3:* and by the explicit Deny. Deny wins. This is why one deny statement can lock down an action even when a broad admin-style policy is attached.
carol shows the Action wildcard: s3:Get* covers both GetObject and GetBucketLocation, but not PutObject.

See the decision flow

The animation walks the same three scenarios through the decision tree: check for an explicit Deny first, then look for an Allow, and fall back to the implicit deny when nothing matches.

What this leaves out

This is a teaching model of the within-account, identity-based path. Real AWS evaluation additionally layers in resource-based policies (union within an account), permissions boundaries (intersection with identity policies), Organizations SCPs/RCPs (intersection again), session policies, and Condition elements. The explicit-deny-wins rule holds across all of them, which is why it is the one rule worth memorizing.

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing.

Embeddings Explained: A Quick Walkthrough with Java

Vishnu B — Tue, 27 Oct 2026 12:30:20 +0000

If you have used semantic search, a recommendation engine, or any "chat with your documents" feature, you have used embeddings. They are the way modern AI systems represent meaning as numbers, and the idea is simpler than the name suggests.

In this walkthrough we will cover what an embedding actually is, then run a small Java program that shows the two things that make embeddings useful: measuring similarity and doing arithmetic on meaning. The code was compiled and run on JDK 21 (Temurin 21.0.13), and the outputs shown are real runs.

Core concepts

An embedding is just a vector. A list of floating point numbers, like [0.12, -0.44, 0.87, ...]. An embedding model turns a piece of text (a word, a sentence, a whole document) into one of these vectors. The numbers are not chosen by hand; the model learns them from large amounts of text, so that the position of each vector captures something about the meaning of the text.

Distance means relatedness. As the OpenAI embeddings guide puts it: the distance between two vectors measures their relatedness. Texts with similar meaning end up close together; unrelated texts end up far apart. The usual way to measure this is cosine similarity, which looks at the angle between two vectors: 1.0 means pointing the same way, 0 means unrelated, -1 means opposite.

Real embeddings are big. Our demo below uses 4 numbers per word so we can see what is happening. A production model like text-embedding-3-small returns 1,536 numbers per input, and text-embedding-3-large returns 3,072.

This animation sums up the whole idea:

Why should you care? Because with a decent embedding model, "close in vector space" is often a good proxy for "similar meaning", and that powers a lot of features: search ranked by relevance instead of keyword, clustering documents by topic, recommendations, anomaly detection, and classification by nearest label. It is a proxy, not a guarantee: how well similarity tracks meaning depends on the model, the data it was trained on, and the similarity metric you choose, and it can break down on text that is very different from that training data.

Walkthrough: embeddings from first principles in Java

We will hand-build tiny 4D "embeddings" for six words. Each dimension pretends to be one learned feature: royalty, humanness, masculinity, fruitiness. A real model discovers these features on its own; we pick them so the mechanics are visible. One honest limitation up front: because we choose the numbers ourselves, this demo shows the mechanics of similarity and vector arithmetic, not learned semantic behavior. It does not independently reproduce what trained models do; it makes their math visible.

import java.util.LinkedHashMap;
import java.util.Map;

public class EmbeddingsDemo {
    // Hand-built 4D "embeddings". Real models learn these from data;
    // ours are chosen by hand so we can see the mechanics.
    // dimensions: [royalty, humanness, masculinity, fruitiness]
    static final Map<String, double[]> VECTORS = new LinkedHashMap<>();
    static {
        VECTORS.put("king",   new double[]{1.0, 0.8, 0.6, 0.0});
        VECTORS.put("queen",  new double[]{1.0, 0.8, 0.0, 0.0});
        VECTORS.put("man",    new double[]{0.0, 0.8, 0.6, 0.0});
        VECTORS.put("woman",  new double[]{0.0, 0.8, 0.0, 0.0});
        VECTORS.put("apple",  new double[]{0.0, 0.0, 0.0, 1.0});
        VECTORS.put("orange", new double[]{0.0, 0.0, 0.1, 0.9});
    }

    static double cosineSimilarity(double[] a, double[] b) {
        double dot = 0, normA = 0, normB = 0;
        for (int i = 0; i < a.length; i++) {
            dot += a[i] * b[i];
            normA += a[i] * a[i];
            normB += b[i] * b[i];
        }
        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
    }

    static void printSimilarity(String a, String b) {
        System.out.printf("cos(%s, %s) = %.3f%n", a, b,
                cosineSimilarity(VECTORS.get(a), VECTORS.get(b)));
    }

    static String nearest(double[] v, String... exclude) {
        String best = null;
        double bestSim = -2;
        for (var e : VECTORS.entrySet()) {
            boolean skip = false;
            for (String x : exclude) if (e.getKey().equals(x)) skip = true;
            if (skip) continue;
            double sim = cosineSimilarity(v, e.getValue());
            if (sim > bestSim) { bestSim = sim; best = e.getKey(); }
        }
        return best + " (similarity " + String.format("%.3f", bestSim) + ")";
    }

    public static void main(String[] args) {
        System.out.println("--- Cosine similarity between word vectors ---");
        printSimilarity("king", "queen");
        printSimilarity("king", "man");
        printSimilarity("king", "woman");
        printSimilarity("king", "apple");
        printSimilarity("apple", "orange");

        System.out.println();
        System.out.println("--- Vector arithmetic: king - man + woman ---");
        double[] king = VECTORS.get("king"), man = VECTORS.get("man"), woman = VECTORS.get("woman");
        double[] result = new double[4];
        for (int i = 0; i < 4; i++) result[i] = king[i] - man[i] + woman[i];
        System.out.println("result vector: " + java.util.Arrays.toString(result));
        System.out.println("nearest word: " + nearest(result, "king", "man", "woman"));
    }
}

Real output from my run:

--- Cosine similarity between word vectors ---
cos(king, queen) = 0.906
cos(king, man) = 0.707
cos(king, woman) = 0.566
cos(king, apple) = 0.000
cos(apple, orange) = 0.994

--- Vector arithmetic: king - man + woman ---
result vector: [1.0, 0.8, 0.0, 0.0]
nearest word: queen (similarity 1.000)

Two things to notice:

Similarity matches intuition. king is closest to queen (0.906), less close to man and woman, and completely unrelated to apple (0.000). Meanwhile apple and orange sit on top of each other (0.994). No string comparison anywhere; it all falls out of the geometry.
Arithmetic works on meaning. king - man + woman produces exactly the vector [1.0, 0.8, 0.0, 0.0], which is our queen vector, and a nearest-neighbor search finds queen with similarity 1.000. This mirrors the famous finding of the original word2vec paper (Mikolov et al., 2013), which showed that vectors learned from a large corpus exhibit this kind of regularity. The difference matters: our queen match is exact because we built the vectors to make it so, while word2vec's result was empirical, emerging from vectors learned from data. The demo illustrates the arithmetic; it does not prove the learned behavior.

That nearest-neighbor search at the end is not a toy detail: it is the core of semantic search and RAG. You store the embedding of every document, embed the query, and return the documents with the highest cosine similarity, exactly the retrieval step described in the OpenAI guide.

Where do real embeddings come from?

You do not hand-pick the numbers like we did. An embedding model is trained on a large text corpus so that words and documents used in similar contexts get similar vectors. Today you typically get embeddings by sending text to a model: an API such as OpenAI's embeddings endpoint (text-embedding-3-small returns 1,536 dimensions) or an open model you run yourself. The input is text, the output is the float vector, and from that point on everything is the math we just ran.

Where you will use them

Semantic search: rank documents by cosine similarity to the query embedding, not by keyword overlap.
RAG (retrieval augmented generation): fetch the most similar document chunks and hand them to the LLM as context.
Recommendations and clustering: group or suggest items whose embeddings are close.
Classification and anomaly detection: nearest label wins; outliers are the vectors far from everything else.

Wrap-up

An embedding is a learned vector of floats where distance encodes meaning. Cosine similarity gives you "how related are these two texts" as one number, nearest-neighbor search over stored embeddings gives you semantic search and RAG, and vector arithmetic can even solve analogies. The whole mechanism fits in the small Java program above; the only thing a real model adds is learning the numbers instead of choosing them.

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing.

Java Virtual Threads: A Quick Walkthrough

Vishnu B — Mon, 26 Oct 2026 12:30:21 +0000

Java 21 shipped one of the biggest changes to Java concurrency in years: virtual threads (JEP 444). They let you write plain, blocking-style code that scales to thousands of concurrent tasks, without reactive programming or careful thread-pool tuning.

In this walkthrough we will look at what virtual threads are, run three small programs you can copy and run yourself, and finish with how to switch them on in a Spring Boot app. Every example was compiled and run on JDK 21 (Temurin 21.0.13), and the outputs shown are real runs.

Core concepts

Platform threads vs virtual threads. A platform thread is a thin wrapper around an operating system thread, and it keeps that OS thread for its whole lifetime. OS threads are expensive, so an application can only have a limited number of them. A virtual thread is also a java.lang.Thread, but it is not tied to one OS thread. The JVM maps a large number of virtual threads onto a small number of platform threads, called carrier threads, in the same spirit as an OS mapping a large virtual address space onto limited RAM.

Mount, unmount, repeat. When code running in a virtual thread makes a blocking I/O call (a database query, an HTTP request, Thread.sleep), the Java runtime suspends the virtual thread and unmounts it from its carrier. The carrier is immediately free to run another virtual thread. When the I/O finishes, the virtual thread mounts again on whichever carrier is free and resumes. This animation shows the cycle:

Scale, not speed. Virtual threads are not faster threads; they do not run your code any faster than platform threads. They exist to provide scale (higher throughput), not speed (lower latency). They shine when tasks spend most of their time waiting on I/O, which is exactly what server applications do.

One caveat: pinning. A virtual thread cannot unmount while it is running inside a synchronized block or method, or inside a native call. That is called pinning. It does not break correctness, but it can hurt scalability if it happens often or for long stretches. The usual fix is to guard long I/O operations with java.util.concurrent.locks.ReentrantLock instead of synchronized. From Java 24, JEP 491 removes nearly all pinning caused by synchronized.

Walkthrough 1: Your first virtual thread

public class HelloVirtualThread {
    public static void main(String[] args) throws InterruptedException {
        // 1. Quickest way: create and start in one call
        Thread thread = Thread.startVirtualThread(() -> System.out.println("Hello from a virtual thread"));
        thread.join();

        // 2. Builder: gives you names and other thread properties
        Thread.Builder builder = Thread.ofVirtual().name("worker-", 0);
        Runnable task = () -> System.out.println("Running in " + Thread.currentThread());

        Thread t1 = builder.start(task);
        t1.join();
        Thread t2 = builder.start(task);
        t2.join();
    }
}

Save it as HelloVirtualThread.java, then:

javac HelloVirtualThread.java
java HelloVirtualThread

Output from my run:

Hello from a virtual thread
Running in VirtualThread[#16,worker-0]/runnable@ForkJoinPool-1-worker-2
Running in VirtualThread[#17,worker-1]/runnable@ForkJoinPool-1-worker-1

Look at the thread names: VirtualThread[#16,worker-0] is the virtual thread, and the part after @ (ForkJoinPool-1-worker-2) is the carrier platform thread it happened to be mounted on. Same API as any thread, but the JVM is doing the carrier juggling for you.

Walkthrough 2: An executor that starts a virtual thread per task

For real code, use Executors.newVirtualThreadPerTaskExecutor(). Every submitted task gets its own fresh virtual thread:

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

public class ExecutorDemo {
    public static void main(String[] args) throws Exception {
        // A new virtual thread is started for every submitted task
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            Future<String> future = executor.submit(() -> {
                Thread.sleep(100); // simulates a blocking I/O call
                return "Fetched order #42 on " + Thread.currentThread();
            });
            System.out.println(future.get());
            System.out.println("Task completed");
        }
    }
}

Output:

Fetched order #42 on VirtualThread[#13]/runnable@ForkJoinPool-1-worker-1
Task completed

Two things worth noticing. The ExecutorService is AutoCloseable, so try-with-resources shuts it down and waits for running tasks. And there is no pool size to tune: one task, one virtual thread.

Walkthrough 3: The scale test

Here is where it clicks. Take 2,000 tasks that each simulate 100 ms of blocking I/O with Thread.sleep, and run them two ways: a classic fixed pool of 8 platform threads, and a virtual thread per task.

import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.stream.IntStream;

public class ScaleDemo {
    static void run(String label, ExecutorService pool, int tasks) {
        Instant start = Instant.now();
        try (pool) { // close() shuts down and waits for all tasks
            IntStream.range(0, tasks).forEach(i -> pool.submit(() -> {
                Thread.sleep(100); // simulates 100 ms of blocking I/O
                return i;
            }));
        }
        System.out.printf("%s: %,d tasks finished in %,d ms%n",
                label, tasks, Duration.between(start, Instant.now()).toMillis());
    }

    public static void main(String[] args) {
        int tasks = 2_000;
        run("Fixed pool of 8 platform threads", Executors.newFixedThreadPool(8), tasks);
        run("Virtual thread per task          ", Executors.newVirtualThreadPerTaskExecutor(), tasks);
    }
}

Real output from my run:

Fixed pool of 8 platform threads: 2,000 tasks finished in 25,062 ms
Virtual thread per task          : 2,000 tasks finished in 141 ms

The platform pool can only work on 8 tasks at a time, so 2,000 tasks x 100 ms takes about 25 seconds. With virtual threads, all 2,000 tasks start at once; when they block on the sleep they unmount, and the whole batch finishes in about one sleep's worth of time. This animation uses the real measured times:

Your numbers will vary by machine, but the shape of the result will not. Note that the tasks got throughput, not speed: each task still takes 100 ms of waiting.

Using virtual threads in Spring Boot

If your app is on Spring Boot and Java 21 or later, switching to virtual threads is one property:

spring.threads.virtual.enabled=true

With this on, the embedded web server handles each request on a virtual thread, so your controllers can stay simple blocking code. Two things from the Spring Boot reference to keep in mind:

Spring recommends Java 24 or later for the best experience, partly because of the synchronized pinning improvements mentioned above.
Virtual threads are daemon threads, so they will not keep the JVM alive. If you rely on something like a @Scheduled bean to keep the app running, also set spring.main.keep-alive=true.
Once virtual threads are enabled, properties that configure thread pools no longer have an effect, because virtual threads are scheduled on a JVM-wide carrier pool.

When to use (and when not)

Good fit: I/O-bound work with lots of concurrent tasks: web requests, database calls, calling other services. This is most server-side Java.

Not a fit: CPU-bound work. Virtual threads do not create more CPU capacity; a task that burns CPU still occupies a carrier the whole time. For those workloads, sizing a platform pool to your cores is still the right tool.

Wrap-up

Virtual threads let you keep the simple, one-thread-per-request programming model and throw away the thread-pool sizing gymnastics for I/O-bound services. The API is just Thread and ExecutorService, the mental model is "one virtual thread per task", and on JDK 21+ you can try it today with the three programs above.

If you try the scale demo yourself, I would be curious what numbers you get on your machine.

Sources

Written with AI assistance; code examples were compiled and run on JDK 21 before publishing.

AWS Lambda Basics: A Quick Walkthrough with Spring Boot

Vishnu B — Mon, 26 Oct 2026 06:21:38 +0000

Introduction

If you have ever deployed an application the traditional way - provision an EC2 instance, install a runtime, keep it patched, watch it sit idle most of the day - AWS Lambda feels almost unfair. Lambda is AWS's serverless compute service: you upload your code, and AWS runs it for you in response to events. No servers to provision, no operating system to patch, and no paying for idle time. You are charged per request and for the exact duration your code runs, down to the millisecond.

This post is for Java and Spring Boot developers. We go through the basic concepts of Lambda - handlers, events, triggers, and limits - and then do two quick hands-on implementations with Spring Boot and Spring Cloud Function: a function you build locally with Maven, deploy through the AWS console and test, and the same idea exposed as an HTTP endpoint you can call with curl. We finish with how to clean everything up, because even small experiments can cost money if you leave them running or expose them publicly.

Everything below is verified against the official AWS and Spring documentation as of October 2026, and every code listing was compiled and executed locally while writing. Both ecosystems update regularly, so check the linked docs pages if something looks different for you.

What exactly is AWS Lambda?

Lambda is a Function-as-a-Service (FaaS). The mental model is simple:

You write a function - a small piece of code with a defined entry point.
You configure a trigger - what should invoke the function. This can be a manual test, an HTTP request, a file landing in S3, a message in SQS, a schedule, and many more.
Lambda runs your function when the trigger fires, scaling out to as many parallel copies as needed - up to your account's concurrency quota (1,000 concurrent executions per region by default, which you can raise or lower). Environments are kept warm and reused between invocations.

Because there is no always-on server, you pay nothing while nothing runs. The free tier includes 1 million requests and 400,000 GB-seconds of compute per month, and the experiments in this post are tiny next to that. Two honest caveats: the free tier is shared across everything in your account, and services around Lambda (like CloudWatch log storage) can bill separately. A billing alarm in AWS Budgets can help you spot spend, but alerts can be delayed and they do not stop charges - AWS has no hard spend cap. Deleting what you created when you are done (cleanup below) stops future charges from those resources - it does not erase anything already accrued, and anything else in the account bills as usual.

Core concepts in five minutes

The handler. The handler is the entry point - the method Lambda calls when your function is invoked. For plain Java it is a method reference like example.Handler::handleRequest. In this post we use Spring Cloud Function, so we never write a handler class ourselves: we set the handler to Spring's built-in org.springframework.cloud.function.adapter.aws.FunctionInvoker::handleRequest, and it routes each invocation to a @Bean of type Function<I, O>. Whatever you choose must match the handler setting on the function, or Lambda will not find your code.

The event object. The first argument to your handler is the event - a JSON document with the input for this invocation. Its shape depends on the trigger: an S3 trigger delivers bucket and object details, an HTTP trigger delivers the request method, headers and body, and a console test event is whatever JSON you type in. Spring Cloud Function converts that JSON into your function's declared input type automatically - a small record you define, or an AWS event type such as APIGatewayV2HTTPEvent.

The context object. The second argument is provided by Lambda itself and describes the invocation: the request ID, the CloudWatch log group name, and how much time remains before the timeout. Useful for logging and monitoring.

The execution role. Your function runs with an IAM role that decides what AWS resources it is allowed to touch. When you create a function in the console, Lambda creates a basic role that only permits writing logs to CloudWatch. If your function needs to read from S3 or write to DynamoDB, you add those permissions to this role - following least privilege, grant only what the function actually needs.

Cold starts. The first time a function is invoked (or after it has been idle), Lambda provisions a fresh execution environment - this adds a delay called a cold start, visible as Init Duration in the logs. Later invocations reuse the warm environment and skip it. For Spring Boot functions the JVM plus Spring context startup makes cold starts more noticeable than for a small Node.js or Python script. AWS Lambda SnapStart (available for the Java runtimes) and giving the function more memory both help - in Walkthrough 1 we raise the memory and timeout from the console defaults so the first cold start fits comfortably.

Runtimes. Lambda offers managed runtimes for Java, Node.js, Python, .NET and Ruby, plus custom runtimes. For Java, prefer java21 or java25 - both are Amazon Linux 2023 based, while the older Amazon Linux 2 based runtimes are on a deprecation path. One practical difference from the scripted languages: the console's inline code editor does not work for Java, so the workflow is always build locally, upload the JAR.

Limits worth memorising

15 minutes maximum per invocation - Lambda is for short tasks, not long-running jobs.
128 MB to 10,240 MB of memory per function. CPU power scales proportionally with memory, so more memory can actually make a function finish faster (and sometimes cheaper).
512 MB to 10,240 MB of temporary storage in /tmp, wiped between environments - never rely on it for persistence.
6 MB payload for synchronous invocations, 1 MB for asynchronous ones.
50 MB zipped deployment package on direct upload - larger zips go through S3, but the 250 MB unzipped limit applies either way. The shaded Spring Boot JAR we build below is about 38 MB, so it still fits a direct upload.

Walkthrough 1 - your first Lambda function with Spring Boot

You need a JDK 21 and Maven installed locally, plus an AWS account. The function receives a length and a width, multiplies them, and returns the area - deliberately tiny, so the moving parts stay visible.

Step 1 - Create the Maven project. Make a folder lambda-area with this pom.xml, and put the Java files under src/main/java/example:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>example</groupId>
    <artifactId>lambda-area</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.2</version>
        <relativePath/>
    </parent>

    <properties>
        <java.version>21</java.version>
        <spring-cloud-function.version>5.0.5</spring-cloud-function.version>
        <aws-lambda-events.version>3.16.1</aws-lambda-events.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-function-adapter-aws</artifactId>
        </dependency>
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-lambda-java-events</artifactId>
            <version>${aws-lambda-events.version}</version>
        </dependency>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-lambda-java-core</artifactId>
            <version>1.4.1</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-function-dependencies</artifactId>
                <version>${spring-cloud-function.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <dependencies>
                    <dependency>
                        <groupId>org.springframework.boot.experimental</groupId>
                        <artifactId>spring-boot-thin-layout</artifactId>
                        <version>1.0.31.RELEASE</version>
                    </dependency>
                </dependencies>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <configuration>
                    <createDependencyReducedPom>false</createDependencyReducedPom>
                    <shadedArtifactAttached>true</shadedArtifactAttached>
                    <shadedClassifierName>aws</shadedClassifierName>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

What each piece does: spring-cloud-function-adapter-aws is the bridge between a Spring Boot app and Lambda. aws-lambda-java-events gives us typed AWS events (used in Walkthrough 2). aws-lambda-java-core is marked provided because the Lambda runtime already has it. jackson-databind here is Jackson 3 (the tools.jackson group) - the JSON library Spring Boot 4 uses; we need it directly in Walkthrough 2. The Spring Boot plugin with the thin layout plus the shade plugin builds a single deployable JAR with the aws classifier - the same build setup as the official Spring Cloud Function AWS sample. All versions were current on Maven Central when this was written.

Step 2 - The application and the function bean. src/main/java/example/AreaApplication.java:

package example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import java.util.function.Function;

@SpringBootApplication
public class AreaApplication {

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

    @Bean
    public Function<AreaInput, AreaResult> area() {
        return input -> new AreaResult(input.length() * input.width());
    }
}

And the two records, AreaInput.java and AreaResult.java:

package example;

public record AreaInput(double length, double width) {}

package example;

public record AreaResult(double area) {}

This is an ordinary Spring Boot application. The Lambda-specific idea is the bean: a Function<AreaInput, AreaResult> named area. Spring Cloud Function collects every Function/Consumer/Supplier bean into a function catalogue, converts the incoming event JSON into AreaInput, and serialises the returned AreaResult back to JSON.

Step 3 - Build the deployment package.

mvn clean package

This produces target/lambda-area-0.0.1-SNAPSHOT-aws.jar - the one with the -aws classifier is the shaded, deployable JAR.

Step 4 - Create the function. Open the Lambda console, go to the Functions page, and choose Create function. Select Author from scratch, enter myLambdaFunction as the name, pick Java 21 as the runtime, leave the architecture at x86_64, and create. Lambda also creates the basic execution role automatically.

Step 5 - Upload the JAR and set the handler. In the Code tab, choose Upload from, then .zip or .jar file, and upload target/lambda-area-0.0.1-SNAPSHOT-aws.jar. Then open Runtime settings, choose Edit, set the handler to org.springframework.cloud.function.adapter.aws.FunctionInvoker::handleRequest, and save. Since the project currently has exactly one function bean, the invoker routes to it automatically.

Step 6 - Set memory and timeout for the demo. A new console function starts with Lambda's defaults: 128 MB of memory and a 3-second timeout. A Spring Boot cold start (JVM start plus Spring context initialisation) can exceed 3 seconds at 128 MB, so the first test could time out before your code ever runs. On the function's Configuration tab, open General configuration, choose Edit, set Memory to 512 MB (the same value Spring's own Lambda sample uses) and Timeout to 30 seconds, and save. Treat these as demo settings, not production sizing: CPU scales with memory, and the bill is configured memory x billed duration, so once things run, right-size from the REPORT lines or with AWS Lambda Power Tuning.

Step 7 - Test it. In the Test section, create a test event named myTestEvent with this JSON:

{
  "length": 6,
  "width": 7
}

Click Test. You should see the response {"area":42.0} along with the function logs. Every invocation ends with a REPORT line showing Duration, Billed Duration, Memory Size, Max Memory Used, and on cold starts Init Duration. The bill itself is computed from the billed duration and the memory you configured - Max Memory Used is not billed, but it tells you whether you can right-size the function down to a cheaper memory setting. When you invoke the function from outside the console, output goes to CloudWatch Logs under the log group /aws/lambda/myLambdaFunction.

Walkthrough 2 - expose it over HTTP with a Function URL

A test button is nice, but usually you want to call your function from somewhere else. The simplest way is a function URL - a dedicated HTTPS endpoint for one function, no API Gateway required. (For a full API with routes, stages and API keys, API Gateway is the right tool; for a webhook or a quick endpoint, a function URL is enough.)

Step 1 - Add an HTTP function bean. A function URL wraps the incoming HTTP request into an event with the same shape as an API Gateway HTTP API (v2) event, so we write a function from APIGatewayV2HTTPEvent to APIGatewayV2HTTPResponse. The JSON body arrives as a string in event.getBody(), so we parse it, validate the input, and return a proper 400 instead of an unhandled 500 on bad input. Add this to AreaApplication:

    private static final ObjectMapper mapper = new ObjectMapper();

    @Bean
    public Function<APIGatewayV2HTTPEvent, APIGatewayV2HTTPResponse> areaHttp() {
        return event -> {
            if (Boolean.TRUE.equals(event.getIsBase64Encoded())) {
                return error("Send JSON as plain text");
            }
            Map<String, Object> body;
            try {
                body = mapper.readValue(
                        event.getBody() == null ? "{}" : event.getBody(),
                        new TypeReference<Map<String, Object>>() {});
            } catch (MismatchedInputException e) {
                return error("Body must be a JSON object");
            } catch (Exception e) {
                return error("Body must be valid JSON");
            }
            if (body == null) {
                return error("Body must be a JSON object");
            }
            Object length = body.get("length");
            Object width = body.get("width");
            if (!(length instanceof Number) || !(width instanceof Number)) {
                return error("Provide non-negative numeric length and width");
            }
            double l = ((Number) length).doubleValue();
            double w = ((Number) width).doubleValue();
            if (!Double.isFinite(l) || !Double.isFinite(w) || l < 0 || w < 0) {
                return error("Provide non-negative numeric length and width");
            }
            double area = l * w;
            if (!Double.isFinite(area)) {
                return error("Dimensions too large");
            }
            return APIGatewayV2HTTPResponse.builder()
                    .withStatusCode(200)
                    .withHeaders(Map.of("Content-Type", "application/json"))
                    .withBody("{\"area\":" + area + "}")
                    .build();
        };
    }

    private static APIGatewayV2HTTPResponse error(String message) {
        return APIGatewayV2HTTPResponse.builder()
                .withStatusCode(400)
                .withHeaders(Map.of("Content-Type", "application/json"))
                .withBody("{\"error\":\"" + message + "\"}")
                .build();
    }

with these imports at the top:

import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPResponse;
import tools.jackson.core.type.TypeReference;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.exc.MismatchedInputException;

import java.util.Map;

Step 2 - Rebuild, re-upload, and route. Run mvn clean package again and upload the new -aws.jar the same way as before. The project now has two function beans, so tell the invoker which one this Lambda should use: on the function's Configuration tab, open Environment variables and add spring_cloud_function_definition = areaHttp. Lambda environment variable names cannot contain dots, so the usual Spring property spring.cloud.function.definition is written with underscores - Spring maps it back.

Step 3 - Create the URL. On the Configuration tab, choose Function URL, then Create function URL. For the auth type, choose NONE for this experiment, save, and Lambda gives you an endpoint like https://<url-id>.lambda-url.<region>.on.aws/.

A word of caution on NONE: it makes the endpoint public - anyone who has the URL can invoke your function, and every invocation runs on your account. Treat it as a temporary experiment: delete it right after testing (cleanup steps below), and for anything real use the AWS_IAM auth type (callers must present valid AWS credentials) or put proper authentication behind it. If you call the URL from browser JavaScript, you will also need to configure CORS on the function URL.

Step 4 - Call it. From any terminal:

curl -X POST 'https://<url-id>.lambda-url.<region>.on.aws/' -H 'Content-Type: application/json' -d '{"length": 6, "width": 7}'

# {"area":42.0}

That is a working serverless HTTP endpoint written as a Spring Boot function: no server, no framework to manage, no load balancer - and it scales on its own. If you want a safety brake while experimenting, set reserved concurrency on the function (Configuration, then Concurrency) to a small number like 5 - it hard-limits how many copies can run at once. It caps concurrency, not rupees: there is no setting that stops all spending, so treat it as a brake, not a wall.

Cleaning up afterwards

A few clicks keeps the account tidy and stops new charges from the resources you created:

Delete the function URL (Configuration, Function URL, Delete). If the auth type was NONE, also check the resource-based policy on the Permissions tab - the docs note that deleting the URL does not remove that policy automatically.
Delete the function itself if you are done with it.
Delete the CloudWatch log group /aws/lambda/myLambdaFunction if you do not need the logs - stored logs are one of the small charges that can outlive the experiment.

When Lambda fits - and when it doesn't

Lambda shines for:

Event-driven work - react to an S3 upload, an SQS message, a DynamoDB stream update.
Scheduled jobs - cron-style tasks with EventBridge, without keeping a server alive for them.
Webhooks and lightweight APIs - function URLs or API Gateway in front.
Glue between services - small pieces of logic that connect AWS services together.

It is the wrong tool for jobs longer than 15 minutes, workloads that need state kept in memory between invocations, or sustained high-throughput services where containers or EC2 can be more economical.

One last pointer: Spring Cloud Function (what we used here) fits small, single-purpose functions. If you instead want to take an existing Spring Boot REST API with its @RestController classes and run it on Lambda as-is, look at the AWS Serverless Java Container project - Spring's own documentation presents both options side by side. Either way, measure the cold start before putting latency-sensitive traffic on it.

Summary

Lambda runs your code in response to events - no servers to manage, billed per request plus milliseconds of runtime.
The handler is the entry point, the event is the input JSON, the context carries invocation metadata, and the execution role controls AWS permissions.
With Spring Cloud Function, your Lambda code is a plain @Bean of type Function<I, O>; the handler is always FunctionInvoker::handleRequest, and spring_cloud_function_definition picks the bean when there are several.
Key limits: 15 minutes per run, up to 10 GB memory, 6 MB sync payload, 50 MB direct-upload JAR.
Java means build locally and upload the shaded -aws.jar - the console editor only works for scripted languages.
A function URL turns the function into a public HTTPS endpoint - use auth type NONE only briefly, and delete it when done.
Clean up when you finish: delete the function URL, the function, and the CloudWatch log group.

Happy coding, and stay tuned for the next post!

This article was drafted with the help of AI and reviewed by me before publishing.

Sources

Tips for Token Optimisation in Claude Code

Vishnu B — Mon, 26 Oct 2026 05:07:54 +0000

Introduction

If you use Claude Code daily, you have already paid the context-window tax: every file Claude reads, every command output, and every message in the conversation sits in the context window and is sent to the model again on every turn. If you are on API billing, that repeated input is a direct per-token cost; on a Pro or Max subscription, the same usage counts against your plan's usage limits. A debugging session or a codebase exploration can consume tens of thousands of tokens on its own. The docs also warn that Claude's performance tends to degrade as the context fills - it can start "forgetting" earlier instructions and making more mistakes. So trimming context waste is worth doing for focus as much as for usage.

The good news: most token waste comes from a few habits, and Claude Code ships with built-in commands to find and fix it. In this post, we will see nine practical tips to reduce token usage in Claude Code - measuring usage, clearing and compacting context, keeping CLAUDE.md lean, delegating to subagents, taming MCP servers, and preprocessing with hooks.

Everything below is verified against the official Claude Code documentation as of October 2026. Claude Code changes fast, so check the linked docs pages if a command behaves differently for you.

Tip 1 - Measure first: /usage and /context

You cannot optimize what you cannot see. Claude Code has two built-in commands for this:

/usage shows the Session block with token usage and an estimated cost for the current session (the dollar figure is computed locally at list price and is meant for API users; Pro/Max subscribers see plan usage bars instead). After the first API response, it also shows a Prompt cache line, for example 14 requests · 91% of input tokens from cache - more on caching in Tip 9.
/context shows a live breakdown of what is filling your context right now, by category, with optimization suggestions - including which CLAUDE.md and memory files were loaded.

On a subscription plan, /usage also shows an attribution breakdown - what share of your recent usage went to skills, subagents, plugins, and individual MCP servers - plus recommendations, one per row, such as:

25% Trim ~/code/api/CLAUDE.md · 49k tokens per request

When the footer shows a hint like f to fix 2 of 3, pressing f makes Claude Code apply the recommendations it can (this shortcut requires Claude Code v2.1.305 or later).

There is also /insights, which writes an HTML report on how you work - friction points, misunderstood requests, and suggestions - based on your recent sessions on that machine.

Tip 2 - Clear between tasks: /clear

This is the cheapest token saver there is. Stale context wastes tokens on every subsequent message, so run /clear whenever you switch to unrelated work.

Two habits that make clearing painless:

Run /rename before clearing so you can find the session later, and /resume to return to it.
If you have corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. The docs' advice: run /clear and start fresh with a more specific prompt that includes what you learned. A clean session with a better prompt almost always outperforms a long session full of accumulated corrections.

Note that /clear also resets the session cost counters in /usage, so the next session's total starts at $0.

Tip 3 - Compact with a focus: /compact

When a session grows long, Claude Code compacts automatically as you approach the context limit: it summarizes the conversation history and keeps working. You can do better than the automatic pass by compacting on your own terms:

/compact Focus on the auth bug fix and the list of modified files

With instructions, the summary keeps what you choose instead of what the automatic pass guesses is important.

You can also set standing compaction instructions in your project's CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

More options from the current docs:

/rewind lets you select a message checkpoint and choose Summarize from here (condenses everything after that point) or Summarize up to here (condenses earlier messages, keeping recent ones in full).
/autocompact with a token count (for example /autocompact 500k) sets how full the context window gets before the automatic pass runs.

Tip 4 - Keep CLAUDE.md lean

CLAUDE.md is loaded at the start of every conversation, so every line in it costs tokens on every message you send - forever, until you remove it. The docs' test for each line is simple: "Would removing this cause Claude to make mistakes?" If not, cut it. Bloated CLAUDE.md files are doubly expensive: they burn tokens AND cause Claude to ignore your actual instructions.

Practical ways to slim it down:

Run /doctor - its checkup proposes trims for a checked-in CLAUDE.md, cutting content Claude can derive from the codebase itself (directory layouts, dependency lists, architecture overviews) and keeping the parts it cannot (pitfalls, rationale, conventions that differ from tool defaults).
Move knowledge that is only relevant sometimes into skills (.claude/skills/). Skill descriptions load at startup, but the full body loads only when the skill is invoked - domain knowledge on demand instead of in every conversation.
Use path-scoped rules for instructions that apply only to certain files; they load on demand alongside matching files.
If you use the auto-memory file MEMORY.md, note that only its first 200 lines (or 25KB) load at startup - keep the index concise and move detail into topic files.

One more detail worth knowing: @path imports in CLAUDE.md help organization but do NOT reduce context, because imported files load together with the file that imports them.

Tip 5 - Send heavy reading to subagents

Subagents run in their own context window with their own system prompt and return only a summary to your main conversation. That makes them the right tool whenever a side task would flood your context with search results, logs, or file contents you will never reference again - codebase exploration and research are the classic cases. Claude Code's built-in Explore subagent exists exactly for this: Claude delegates searching and understanding the codebase to it, and the large file reads stay out of your main conversation.

Two cost controls for subagents:

For simple subagent tasks, set model: haiku in the subagent configuration to run it on a lower-cost model. Defining a user or project subagent named Explore overrides the built-in one while keeping its model field.
Keep subagent description fields short. All descriptions load into context so Claude can decide when to delegate, and Claude Code warns at startup when the combined custom descriptions exceed 15,000 tokens. Move detail into the subagent's system prompt, which loads only when that subagent runs.

One honest caveat: a subagent sends its own API requests, which count toward the same usage limits as your main conversation. Subagents save main-context tokens (the ones you repay on every turn); they do not make the work itself free.

Tip 6 - Tame your MCP servers

MCP servers are the quiet token leak in many setups. The good news first: in current Claude Code, MCP tool definitions are deferred by default - only tool names and server instructions enter your context until Claude actually uses a specific tool. Still, every connected server adds overhead, and the docs recommend two moves:

Prefer CLI tools where they exist. Tools like gh, aws, gcloud, and sentry-cli are more context-efficient than MCP servers because they add no per-tool listing at all - Claude just runs the CLI commands.
Disable servers you are not actively using. Run /mcp to see the configured servers and toggle them off per project; the configuration is kept for when you need them back.

To find out whether a server earns its keep, check the per-server attribution in /usage (Tip 1) - an MCP server's share counts only the requests that actually consumed one of its tool results.

Tip 7 - Pick the right model for the job

Model choice is the biggest per-token lever you have:

Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning.
Switch mid-session with /model, or set a default in /config. Note that switching to Opus also applies to subagents that inherit your session's model.
For simple subagent work, specify model: haiku in the subagent configuration (Tip 5).

If you routinely hit context limits on big tasks, the docs also list models with a 1 million token context window (Sonnet 4.6 and later, Haiku 5.5, Opus 4.6 and later), selectable as [1m] variants. A bigger window raises the ceiling; the tips above lower the bill.

Tip 8 - Preprocess with hooks

Hooks run scripts automatically at points in Claude's workflow, and unlike CLAUDE.md instructions they are deterministic - the action always happens. A PreToolUse hook can filter command output before it ever reaches the context. The docs' example: instead of Claude reading a 10,000-line log to find errors, a hook greps for ERROR and returns only matching lines - tens of thousands of tokens become a few hundred.

Here is the docs' pattern, adapted to also catch Maven and Gradle test runs. Add the hook to your settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

Then save this as ~/.claude/hooks/filter-test-output.sh and make it executable (chmod +x):

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# If running tests, filter to show only failures
pattern='^(npm test|pytest|go test|mvn test|./mvnw test|./gradlew test)( [^;&|<>`$#\\[:cntrl:]]*)?$'
if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="f=\$(mktemp); $cmd > \"\$f\" 2>&1; s=\$?; grep -A 5 -E '(FAIL|ERROR|error:)' \"\$f\" | head -100; echo \"[exit \$s - full output at \$f]\"; exit \$s"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

When the command is a test run, the hook rewrites it so Claude sees only the failure lines; anything else passes through unchanged.

A word on doing this safely, because the naive version of this idea can mislead Claude:

Preserve the exit status. A pipeline's exit code is its last command's, so cmd | grep | head would report success whenever grep and head succeed - even when the tests themselves failed. That is how Claude ends up believing broken tests are green. The script above saves the original exit code (s=$?) and exits with it, so a failing run still looks like a failure. (Verified locally: failing tests exit 1, a crash with no matching output still exits 134.)
Keep the full output reachable. grep -A 5 and head -100 can cut a stack trace's root cause, and merging stderr into the filter (2>&1) drops any error text that does not match the pattern - compiler errors in an unusual format, OOM crashes, "Aborted". The script writes the complete output to a temp file and prints its path, so Claude can read the full log when the filtered view is not enough.
Only simple commands get filtered. The pattern's argument part rejects |, ;, &, $, backticks and other shell metacharacters, so anything complex (pipelines, command substitution) runs exactly as written instead of being mangled by the rewrite.
Filtering is lossy by design. Treat the filtered view as a first look. For security-sensitive output (dependency audits, secret scanners), do not filter at all - a hidden warning is worse than a big context.

The same pattern works for build logs or any chatty, non-sensitive command you run often - apply the safety points above each time.

Tip 9 - Small habits that add up

A few one-liners from the docs that are easy to adopt:

Use /btw for side questions. The answer never enters the conversation history, so you can check a detail without growing (and paying for) the context on every following turn.
Be specific in prompts. "fix the login bug" sends Claude exploring; "login fails after session timeout - check the auth flow in src/auth/, especially token refresh, and write a failing test first" goes straight to the files that matter. Specific prompts mean fewer exploratory file reads.
Install code intelligence plugins for typed languages. A single "go to definition" call replaces a grep plus reading multiple candidate files, and the language server reports type errors after edits without a compiler run.
Let prompt caching work for you. Claude Code automatically caches repeated content like the system prompt, and the Prompt cache (main) line in /usage tells you the share of input tokens served from cache - in the docs' example session, 91% - so you can see it working.

Summary

Measure first: /usage for cost and attribution, /context for what is filling the window, /insights for patterns.
/clear between unrelated tasks (/rename first, /resume to return); compact long sessions with focused instructions.
Keep CLAUDE.md lean - every line rides along on every message. Move on-demand knowledge to skills and path-scoped rules.
Delegate heavy reading to subagents, run simple ones on haiku, and keep their descriptions short.
Prefer CLI tools over MCP servers, and disable servers you are not using.
Match the model to the task: Sonnet by default, Opus for the hard parts, Haiku for simple subagents.
Preprocess noisy command output with PreToolUse hooks, and use /btw for questions that do not need to stay in context.

Token optimization in Claude Code is really context optimization. Trimming irrelevant context reduces the input you send on each turn - on API billing that is direct cost saved, and on a subscription it stretches your usage limits further. And since the docs note that performance degrades as context fills, a leaner context can also help Claude stay focused.

Happy coding, and stay tuned for the next post!

Sources (official Claude Code docs, checked October 2026):

Manage costs effectively - /usage, prompt cache line, recommendations, reduce token usage checklist
Explore the context window - /context, /compact, /rewind, /autocompact, /clear, what survives compaction
Best practices - specific prompts, /btw, CLAUDE.md guidance, code intelligence plugins
Memory (CLAUDE.md) - file loading rules, /doctor trims, MEMORY.md limits, @path imports
Subagents - separate context windows, Explore, model: haiku, description token warning
MCP - deferred tool definitions, /mcp panel, disabling servers