Circular strings come up in cyclic IDs, necklace matching, polygon normalization, and any case where the end loops back to the start. With that kind of string, several written forms can still represent the same circle. caba, abac, baca, and acab are all rotations of one another, but they refer to the same circular order of characters. Booth’s algorithm gives that circle one fixed written form by finding the lexicographically smallest rotation in linear time. It takes the failure table idea from Knuth-Morris-Pratt string matching, then lets mismatches rule out weaker starting positions without rebuilding and comparing every possible rotation.

Subscribe now

What the Problem Is Really Asking

Before Booth’s algorithm can make sense, the string has to be viewed in the right way. Nothing is being rearranged freely. The characters stay in the same circular order, and the question becomes which written version of that circle should count as the smallest in lexicographic order. That difference changes the whole problem. Booth’s algorithm is built for circular strings, so the first step is getting precise about what a rotation really is and why checking every starting position turns costly fast.

Rotation Means the Same Characters With a Different Start

You can think of the string as wrapped into a ring. Reading from one index gives one written form, and reading from a different index gives a different written form, but the circular order never changes. With caba, the rotations are caba, abac, baca, and acab. All four strings represent the same cycle of characters. The only thing that changes is where the read begins.

That detail keeps the problem grounded. Rotation is not sorting the letters. Rotation is not taking a small substring and calling it done. Rotation is not moving a character to a new spot while the rest stays still. Every character keeps the same neighbors in the circle. Only the starting point changes.

This Java helper makes that visible:

public static String rotationAt(String s, int start) {
    return s.substring(start) + s.substring(0, start);
}

public static void main(String[] args) {
    String s = "caba";

    System.out.println(rotationAt(s, 0)); // caba
    System.out.println(rotationAt(s, 1)); // abac
    System.out.println(rotationAt(s, 2)); // baca
    System.out.println(rotationAt(s, 3)); // acab
}

Nothing in that method changes character values or relative order. It takes the suffix from start to the end, then places the earlier prefix after it. Reading begins at a new spot, but the ring itself stays the same.

Lexicographic order then decides which rotation comes first. Java’s String.compareTo reads from left to right and stops at the first position where the two strings differ. The string with the smaller character at that position comes first. With the rotations of caba, abac beats acab because the first characters match as a, then b comes before c at the next position. abac also beats baca and caba right away because a comes before b and c.

Small checks can make that rule easier to see:

public static void main(String[] args) {
    String left = "abac";
    String right = "acab";

    System.out.println(left.compareTo(right) < 0); // true
}

That result means abac is lexicographically smaller than acab. Later characters do not need to be read after the first mismatch settles the comparison.

Repeated structure inside a string adds a useful detail. Some inputs can produce the same rotation string from more than one starting index. abab is a good case. Starting at index 0 gives abab, and starting at index 2 also gives abab. As a string result, the least rotation is still well defined. As a starting index, more than one index can produce that same least written form.

Beginners sometimes read this problem as though the whole goal were finding the smallest character and starting there. That idea is not quite enough by itself. If the smallest character appears in several positions, the rest of the rotation still has to be compared. Take baaa. Starting at index 1, 2, or 3 gives aaab, aaba, and abaa. All three begin with a, but only aaab is the least rotation. Full lexicographic comparison still decides the winner.

Why Checking Every Shift Is a Bad Deal

Brute-force rotation search is a reasonable first pass. You build every rotation, compare each candidate against the current best value, and keep the smallest one. That route states the problem in direct terms, which makes it useful for getting started. Trouble shows up in the repeated string comparisons hiding inside it.

A basic Java version looks like this:

public static String leastRotationBruteForce(String s) {
    if (s.isEmpty()) {
        return s;
    }

    String best = rotationAt(s, 0);

    for (int start = 1; start < s.length(); start++) {
        String candidate = rotationAt(s, start);
        if (candidate.compareTo(best) < 0) {
            best = candidate;
        }
    }

    return best;
}

That method is easy to read. For a short string, it is perfectly fine. If the input length is n, there are n candidate rotations. Each comparison can read up to n characters before it finds the first mismatch or reaches the end. Building each candidate rotation also touches the characters again. Put that all across the full scan, and the total cost grows roughly like n².

Repeated prefixes are what make the cost feel heavier than it first sounds. With a string such as aaaaab, several rotations begin with long runs of a. Comparing two candidates means reading through that repeated prefix until a later character finally breaks the tie. Then the next candidate can force a very similar read again. Large parts of earlier comparisons get repeated instead of reused.

That repeated effort is the real problem, not the fact that the code loops through starting indexes. If two candidate rotations share a long beginning, the brute-force method has no memory of what earlier failed comparisons already proved. It simply reads through the same territory again. Long repeated sections inside the input make that waste more noticeable. Space can stay fairly low if candidates are built one at a time, like the method above does. Storing every rotation at once would take more memory, but avoiding that still does not fix the repeated comparison cost. The heavy part comes from checking all candidate starts and rereading long common prefixes across those comparisons.

This is where the need for Booth’s algorithm starts to come into view. Checking every rotation is easy to explain, but that route keeps treating nearby starting positions almost like unrelated cases. A stronger string method keeps information from failed matches so those losing regions do not need to be tested from scratch every time.

How Booth’s Algorithm Moves the Start Point

Booth’s algorithm gets its speed from the way it treats comparisons as reusable information. Instead of treating every candidate start as a fresh attempt, it keeps a current best start, scans forward through a doubled view of the string, and records how far the current candidate had matched before a mismatch happened. That saved match length changes what the algorithm does next. A later mismatch can move the start forward by more than a single position, which is the whole reason the method stays linear.

Double the String So Rotation Becomes a Slice

Circular indexing can be turned into ordinary substring logic by writing the string twice in a row. If the original string is s, then s + s contains every rotation of s as a contiguous run of length n, where n is the original string length. That idea removes the need to wrap back to index 0 during each comparison, which keeps the scan far more readable.

Take caba. Writing it twice gives cabacaba, starting at index 0 and reading 4 characters gives caba. Starting at index 1 and reading 4 characters gives abac. Starting at index 2 gives baca, and starting at index 3 gives acab. Every possible rotation now lives inside a linear string, which means the algorithm can walk left to right without special-case wraparound rules at each step.

Let’s see that with a short helper:

public static String rotationWindow(String s, int start) {
    String doubled = s + s;
    return doubled.substring(start, start + s.length());
}

public static void main(String[] args) {
    String s = "caba";

    System.out.println(rotationWindow(s, 0)); // caba
    System.out.println(rotationWindow(s, 1)); // abac
    System.out.println(rotationWindow(s, 2)); // baca
    System.out.println(rotationWindow(s, 3)); // acab
}

That helper is not Booth’s algorithm by itself. Its only job is to make the indexing idea tangible. Rotation stops feeling circular as soon as the string is doubled, because every candidate can now be treated as a normal slice inside a longer string.

That trick also explains why Booth’s algorithm tracks a start index in the doubled string rather than building new strings again and again. If a better start is found, the algorithm does not need to create a new rotated value just to continue. It can keep scanning inside the doubled string and compare characters by index. Memory use stays lower that way, and the scan logic stays centered on positions rather than on newly built string objects.

Indices inside the doubled string still map back to the original string. If the best start ends up at 5 in a doubled view of a string of length 4, then the matching start in the original string is 5 % 4, which is 1. That remainder step is why the final answer can be returned as a position in the original input.

This index helper makes that link a bit more visual:

public static int originalIndex(int doubledIndex, int n) {
    return doubledIndex % n;
}

public static void main(String[] args) {
    System.out.println(originalIndex(5, 4)); // 1
}

Nothing deep is happening in that method, but it helps keep the later scan grounded. Booth’s algorithm may move through a string of length 2n, yet the answer still belongs to the original string of length n.

The Failure Table Stores What the Match Already Proved

Much of the saved time comes from the failure table. Booth’s algorithm borrows the general fallback idea from Knuth-Morris-Pratt preprocessing. During the scan, characters may match for a while before a mismatch appears. Instead of discarding that partial match and starting from zero, the algorithm keeps a table that records how far the match had gone and where a shorter fallback comparison should resume.

Picture a current candidate start at index start. As the scan moves forward to index j, the algorithm compares doubled.charAt(j) against a character inside the candidate rotation. If they match, the current matched length grows. If they do not, the failure table says which shorter matched prefix is still worth testing before giving up on the current prefix length completely.

That table is not storing full rotations. It stores matched-prefix lengths relative to the current candidate. Value -1 means no shorter fallback exists at that relative position. Nonnegative values mean a shorter matched prefix can still be reused. This is what stops the algorithm from rereading the full matched portion from the beginning after every failed comparison.

Let’s see a small view of the initialization:

import java.util.Arrays;

public static void main(String[] args) {
    String doubled = "cabacaba";
    int[] failure = new int[doubled.length()];
    Arrays.fill(failure, -1);

    System.out.println(Arrays.toString(failure));
}

Filling the table with -1 means fallback links do not exist yet. As the scan advances, positions that do have reusable prefix information get updated with nonnegative values. Booth’s algorithm then walks those values backward during mismatches, just as KMP-style preprocessing walks prefix links instead of starting the comparison from the front again.

Two moving values carry most of the scan. start marks the current best candidate rotation, and a relative match index derived from the failure table tells the algorithm how far the candidate had matched before trouble appeared. If the next character keeps the match alive, the new failure entry records that longer prefix. If the next character breaks the match, fallback values guide the scan through shorter prefixes that may still match.

That reuse is where the time savings come from because the brute-force comparison treats each failed long prefix as lost effort. Booth’s algorithm treats that same long prefix as information worth saving. If several candidate starts share the same beginning, the failure table stops the scan from proving the same prefix relationship from scratch every time.

Failed Matches Can Prove a Better Start Exists

Mismatches do more than stop a comparison. In Booth’s algorithm, a mismatch can prove that the current candidate start no longer deserves to stay in front. That part is what gives the method its character. The scan is not just asking did these two characters differ. It is also asking what that difference says about the best possible start from this point onward.

Let’s say the current candidate start is start, the scan is at position j, and the current matched prefix length is tied to i. If doubled.charAt(j) is smaller than the character it just failed against inside the current candidate, then the existing candidate cannot stay best. A lexicographically smaller character has appeared at the exact place where the old candidate lost. That gives the algorithm permission to move start forward.

Now let’s look at the fragment where the mismatch logic shows up:

while (i != -1 && doubled.charAt(j) != doubled.charAt(start + i + 1)) {
    if (doubled.charAt(j) < doubled.charAt(start + i + 1)) {
        start = j - i - 1;
    }
    i = failure[i];
}

That update to start is not arbitrary. j - i - 1 points to the position where the newly better candidate begins, based on how far the earlier match had already gone. In other words, the scan is taking the matched length into account when it decides how far the new start should jump. Nearby losing starts get ruled out in a single move.

There is also a shorter mismatch case where no fallback prefix remains. Then the algorithm compares the scan character directly against the first character of the current candidate. If the scan character is smaller, the start moves straight to j.

That case looks like this:

if (doubled.charAt(j) != doubled.charAt(start + i + 1)) {
    if (doubled.charAt(j) < doubled.charAt(start)) {
        start = j;
    }
    failure[j - start] = -1;
} else {
    failure[j - start] = i + 1;
}

Those two cases are the heart of the method. A mismatch after a long partial match can jump the start by more than one index. A mismatch with no shorter fallback can still replace the current start outright if the new character is smaller. Either way, failed comparisons are not wasted. They narrow the field of candidate starts.

Walk through caba and the movement becomes easier to follow. The scan begins with start = 0, so the current candidate rotation begins with c. Very early, the scan sees a. That a is smaller than c, which means the candidate beginning with c cannot stay best. The start moves to the position of that a. After that, later characters test the new candidate against nearby alternatives. By the time the scan finishes, the best start is 1, which gives the least rotation abac.

Repeated letters make the same rule more valuable. With a string such as aaaaab, the scan can match a long run before the deciding character appears. When that decision finally comes, the mismatch does more than say these two candidate views differ. It also rules out several nearby starts that would lose for the same reason. That is why the algorithm does not sink into quadratic behavior on strings with long repeated prefixes.

Time cost stays O(n) because the scan moves through the doubled string with bounded fallback steps, and the well-known comparison bound is at most about 3n character comparisons. Space cost for the table stays O(n).

Java Implementation

Java can express the full scan with only core library types. String, charAt, substring, arrays, and Arrays.fill are enough. The version below returns both the least-rotation start index and the final rotated string.

import java.util.Arrays;

public final class BoothRotation {
    private BoothRotation() {
    }

    public static int leastRotationIndex(String s) {
        int n = s.length();
        if (n == 0) {
            return 0;
        }

        String doubled = s + s;
        int[] failure = new int[doubled.length()];
        Arrays.fill(failure, -1);

        int start = 0;

        for (int j = 1; j < doubled.length(); j++) {
            int i = failure[j - start - 1];

            while (i != -1 && doubled.charAt(j) != doubled.charAt(start + i + 1)) {
                if (doubled.charAt(j) < doubled.charAt(start + i + 1)) {
                    start = j - i - 1;
                }
                i = failure[i];
            }

            if (doubled.charAt(j) != doubled.charAt(start + i + 1)) {
                if (doubled.charAt(j) < doubled.charAt(start)) {
                    start = j;
                }
                failure[j - start] = -1;
            } else {
                failure[j - start] = i + 1;
            }
        }

        return start % n;
    }

    public static String leastRotation(String s) {
        if (s.isEmpty()) {
            return s;
        }

        int start = leastRotationIndex(s);
        return s.substring(start) + s.substring(0, start);
    }

    public static void main(String[] args) {
        String s = "caba";

        System.out.println(leastRotationIndex(s)); // 1
        System.out.println(leastRotation(s));      // abac
    }
}

Several lines in that class carry most of the meaning. String doubled = s + s; turns the circular problem into a linear scan. Arrays.fill(failure, -1); sets the fallback table to a state where no reusable shorter prefix exists yet. start tracks the current best candidate. j scans forward through the doubled string. i follows failure links backward when a mismatch appears after a partial match.

Reading leastRotationIndex from top to bottom, the method starts by handling the empty string, then builds the doubled view, then sets up the failure table, and then enters the main scan. The outer for loop pushes j across the doubled string. The inner while loop handles repeated fallback after mismatches. That loop is what keeps the method linear. It does not restart a full comparison from the front each time. It reuses prefix information already recorded in failure.

leastRotation is short because all of the real logic lives in the index method. After the least start is known, building the final answer is just a suffix and prefix join based on that index. Keeping those responsibilities separate is useful for teaching and testing. If a reader wants to verify the scan itself, the index method can be checked alone. If a reader wants the final rotated string, the helper method can build it directly.

Time cost for the full implementation is O(n). Space cost is O(n) because of the doubled string and the failure table. Those costs are the reason Booth’s algorithm keeps coming up in string algorithm study. It takes a problem that invites repeated full comparisons and turns it into a scan where failed matches help decide what should happen next instead of becoming lost effort.

Conclusion

Booth’s algorithm turns a circular string problem into a left-to-right scan where the doubled string handles wraparound, the failure table carries forward earlier match progress, and a mismatch can move the candidate start ahead instead of forcing the search to begin again. That is what gives the method its O(n) time behavior. Rather than building every rotation and comparing them all in full, it keeps narrowing the search with information each failed comparison already revealed.

1. Java String Documentation

2. Java Arrays Documentation

3. Java String.compareTo Documentation

4. Java substring Documentation

5. Java charAt Documentation

Share Alexander Obregon's Substack

Services can reject an absent id before a miss turns into yet another trip to Redis or a database. That helps most with ids that do not exist at all. Without a front gate, the same missing row can miss Redis, miss the database, return not found, then run through that full cycle again on the next request. The filter keeps a compressed record of inserted ids, so definite negatives can be rejected right away while probable positives move into the usual lookup flow. False positives still happen for a small share of absent ids, but memory stays compact and the volume of repeated misses drops fast.

Subscribe now

What a Bloom Filter Stores

Membership is the whole job here. Rather than keeping full values in memory, a Bloom filter records only which bit positions were turned on after hashing. That choice is why the structure stays small. Row ids, usernames, slugs, or lookup tokens do not live in the filter as complete values. What remains is a compact bit-based representation that can answer a narrow question very quickly. Was this value ever added to the filter?

The Bit Array

Inside the filter lives a bit array with m positions, and every position begins at 0. Inserting a value does not place that value into the array. Hash results point to several positions, and those positions are flipped from 0 to 1. Later, a lookup repeats the same hash calculations and checks those same positions. Find any 0 and the answer is definite no. Find all 1 values and the filter can only say probably present.

Nothing in that array looks like a saved row id. No slot says account 9183 lives here, and no bucket holds a full primary key. Memory stays tight because the filter never keeps the original item. It keeps only the bit positions touched during insertion.

That storage choice is what makes Bloom filters so compact. Each bit carries almost no meaning by itself. Value comes from the collection of positions tied to a hashed item. Insert a value, mark several positions. Check that value later, revisit those same positions. That is enough to reject values that were never added without paying the memory cost of a normal set or map.

Take this Java example:

import java.util.BitSet;

public final class BitArrayBloom {
    private final BitSet bits;
    private final int size;

    public BitArrayBloom(int size) {
        this.size = size;
        this.bits = new BitSet(size);
    }

    public void mark(int index) {
        bits.set(index);
    }

    public boolean isMarked(int index) {
        return bits.get(index);
    }

    public int size() {
        return size;
    }
}

Nothing in that class stores an id directly. The class stores only bit positions, which is the first part of the structure.

Now connect that storage area to an inserted value. Say a row id hashes to three indexes such as 9, 31, and 88. Those positions are turned on. Checking that same row id later means reading those same positions again. If position 31 is still 0, the row id was never inserted. If all three positions are 1, the filter has enough evidence to say probably present.

public final class BitArrayDemo {
    public static void main(String[] args) {
        BitArrayBloom bloom = new BitArrayBloom(128);

        int[] positionsForUserId = {9, 31, 88};
        for (int position : positionsForUserId) {
            bloom.mark(position);
        }

        System.out.println(bloom.isMarked(9));
        System.out.println(bloom.isMarked(31));
        System.out.println(bloom.isMarked(88));
        System.out.println(bloom.isMarked(77));
    }
}

That example leaves hashing out on purpose so the storage side stays in focus. Separating the bit array from the hash step makes the physical storage rule much more readable. Positions are stored. Original values are not.

Standard Bloom filters also move bits in only one direction. Insertions turn positions on, but nothing turns those positions back off. That detail is part of why the structure stays small. It also explains why deletion needs a different variant, such as a counting Bloom filter, rather than the standard form.

The Hash Checks

Hashing turns a value into positions inside the bit array. Instead of relying on a single result, a Bloom filter uses k hash functions, so one inserted value maps to k different positions. Insert time sets all of those positions to 1. Lookup time repeats the same calculations and checks them again.

Take an id like user-9183. First hash result may point to position 14, a second to 67, and a third to 122. Inserting that id means flipping all three positions on. Checking it later means reading those same spots again. If position 67 is still 0, the answer is definite no. No extra interpretation is needed because that value could not have been inserted earlier.

That definite no is what gives the structure its value. Exact membership structures keep more information and cost more memory. Bloom filters trade away exact yes answers in return for a much smaller footprint. No remains exact. Yes becomes probably.

This code ties hashing and bit checks into the same class:

import java.nio.charset.StandardCharsets;
import java.util.BitSet;
import java.util.zip.CRC32;

public final class BloomMembership {
    private final BitSet bits;
    private final int size;
    private final int hashCount;

    public BloomMembership(int size, int hashCount) {
        this.size = size;
        this.hashCount = hashCount;
        this.bits = new BitSet(size);
    }

    public void add(String value) {
        for (int index : indexesFor(value)) {
            bits.set(index);
        }
    }

    public boolean probablyContains(String value) {
        for (int index : indexesFor(value)) {
            if (!bits.get(index)) {
                return false;
            }
        }
        return true;
    }

    private int[] indexesFor(String value) {
        int[] indexes = new int[hashCount];
        long hash1 = crc32(value);
        long hash2 = crc32(value + "#salt");

        for (int i = 0; i < hashCount; i++) {
            long combined = hash1 + (long) i * hash2;
            indexes[i] = (int) Math.floorMod(combined, size);
        }

        return indexes;
    }

    private long crc32(String value) {
        CRC32 crc32 = new CRC32();
        crc32.update(value.getBytes(StandardCharsets.UTF_8));
        return crc32.getValue();
    }
}

This version builds several positions from two base hash values. That keeps the example short while still matching the rule that each value touches several positions.

False positives come from overlap. user-9183 may set bits 14, 67, and 122. Later, user-4410 may set bits 67, 90, and 122. After enough insertions, the array contains marks left behind by different values that share some of the same positions. The filter never asks which value turned on a bit. It checks only that every needed position is already set.

Now the source of a false positive comes into play. Values that were never inserted can still land on positions that earlier values already turned on. If all of those positions are 1, the filter answers probably present. Nothing is broken when that happens. That is the trade Bloom filters make to stay small in memory. Inserted items do not produce false negatives, but absent items can still return a positive result.

Hash quality still matters because poor distribution fills some parts of the array faster than others. Better distribution spreads writes across the bit array more evenly, which helps keep the false positive rate closer to what was planned.

As a whole, the hash step turns a plain bit array into a membership filter. Without hash calculations, the array is just a block of bits. With repeatable position selection for each value, those bits become a compressed record of prior inserts.

How It Blocks Repeated Misses

Read traffic for absent ids can drain cache and storage in a very wasteful loop. Redis returns nothing, the database returns nothing, and the caller still gets only a not-found response. Then that same lookup can come back a second later and burn through that full chain again. Putting a Bloom filter at the front changes that loop. Definite negatives stop before Redis and before the database, while probable positives continue through the usual lookup flow.

The Absent Row Problem

Repeated lookups for data that does not exist are expensive because every request pays for a miss all the way down. Deleted rows, stale links, typoed ids, client bugs, and bot traffic can all create that kind of pressure. Without a front gate, storage keeps getting asked the same unanswerable question. Bloom filters fit this case well because their negative answer is definitive for membership. If the filter says an id is not present, the service can stop right there instead of burning another trip through cache and storage.

Hot-value expiry is a different failure mode. That case is about concurrent requests piling onto the backend after cached content is missing or expired. Bloom filters help earlier in the flow. Their job is to cut off lookups for absent ids before those requests ever reach Redis or the database.

The Request Path

Most services place the filter before both Redis and the database. Existing ids are loaded into the filter during startup, backfill, or a sync process, and new writes should add their ids too so the filter stays close to current data. After that, each read starts with a membership check. false returns not found immediately. true means probably present, so the request still moves into the normal cache lookup and then to the database if Redis misses.

The read flow looks like this:

public final class ProfileLookupService {
    private final ProfileIdGate profileIdGate;
    private final RedisClient redisClient;
    private final ProfileRepository profileRepository;

    public ProfileLookupService(
            ProfileIdGate profileIdGate,
            RedisClient redisClient,
            ProfileRepository profileRepository) {
        this.profileIdGate = profileIdGate;
        this.redisClient = redisClient;
        this.profileRepository = profileRepository;
    }

    public ProfileResult readProfile(long profileId) {
        String key = "profile:" + profileId;

        if (!profileIdGate.probablyHas(key)) {
            return ProfileResult.notFound();
        }

        String cachedJson = redisClient.get(key);
        if (cachedJson != null) {
            return ProfileResult.found(cachedJson);
        }

        ProfileRow row = profileRepository.findById(profileId);
        if (row == null) {
            return ProfileResult.notFound();
        }

        String json = ProfileJson.write(row);
        redisClient.set(key, json, 300);
        return ProfileResult.found(json);
    }
}

Bloom checking is not the source of truth in that flow. Positive means only that the lookup should continue. Redis or the database still decides the final result. Negative is the special case that saves time, because Bloom filters do not produce false negatives for items that were added.

Current Redis Bloom commands works nicely with that model:

BF.RESERVE profiles 0.001 1000000
BF.MADD profiles profile:101 profile:205 profile:390
BF.EXISTS profiles profile:101
BF.EXISTS profiles profile:999999

Pre-sizing helps because the filter starts with the capacity and error rate you intended, rather than falling back to defaults and growing later in a less predictable way. That becomes more important as the dataset grows and the filter carries a larger share of read traffic.

The Memory Math

Sizing is where Bloom filters move from theory into planning. Redis documents the bits-per-item rule as -ln(error_rate) / ln(2)^2 and the optimal hash-count rule as ceil(-ln(error_rate) / ln(2)). Those formulas turn quickly into numbers you can budget. 1% as a target needs 7 hash functions and 9.585 bits per item. 0.1% needs 10 hash functions and 14.378 bits per item.

For 10,000,000 ids at 1%, that comes out to about 95,850,000 bits, which is roughly 12 MB. For 50,000,000 ids at the same rate, the filter lands near 60 MB. 1,000,000,000 ids at 1% comes out around 1.2 GB. That is still a very small memory bill compared with holding full values or a heavier lookup structure just to reject absent ids.

Capacity planning has a direct effect on runtime cost. Redis supports scaling Bloom filters that can expand by adding subfilters, but those extra layers raise both storage and CPU cost compared with reserving the filter at the right size from the start. That does not mean scaling is wrong. It means a well-sized filter is cheaper to query and cheaper to store.

False Positives in Production

Positive answers from a Bloom filter are not proof that data exists. They mean only that the lookup should continue. If the filter says yes, Redis misses, and the database misses too, that request was a false positive. The response is still right. The caller gets not found, just as expected. False positives can happen, but false negatives do not occur for items that were added.

Tracking that number helps because it tells you how much absent traffic is still slipping past the front gate. Counters can do that job:

import java.util.concurrent.atomic.AtomicLong;

public final class BloomFilterMetrics {
    private final AtomicLong bloomPasses = new AtomicLong();
    private final AtomicLong bloomFalsePositives = new AtomicLong();

    public void recordBloomPass() {
        bloomPasses.incrementAndGet();
    }

    public void recordFalsePositive() {
        bloomFalsePositives.incrementAndGet();
    }

    public double falsePositiveRate() {
        long passes = bloomPasses.get();
        if (passes == 0) {
            return 0.0;
        }
        return (double) bloomFalsePositives.get() / passes;
    }
}

Rising false-positive rates usually point to a filter that is too full, a capacity estimate that was too low, or an error-rate target that no longer fits the dataset. Common fixes are a sizing change, a rebuild, or a lower target error rate with more bits per item.

Bloom filters also do not replace the protections used for expired hot entries. Resource locking and request coalescing still belong to the cache-stampede problem, where concurrent requests try to refill the same missing content at the same time. Bloom filters solve a narrower issue. They cut down the number of absent ids that ever get that far.

Conclusion

Bloom filters change the cost of a miss by turning it into a fast membership check before Redis or the database is touched. Bit positions record prior inserts, hash checks test those positions again during reads, and that small gate lets definite negatives stop early while probable positives continue through cache and storage. Memory stays low because the filter keeps bits instead of full values, and the trade is a measured false-positive rate in exchange for far fewer repeated misses against absent data.

1. Redis Bloom Filter Commands

2. Redis BF.RESERVE Command

3. Redis BF.ADD Command

4. Redis BF.EXISTS Command

5. Java BitSet Documentation

6. Java CRC32 Documentation

7. Guava BloomFilter Documentation

Share Alexander Obregon's Substack

Sampling from a stream gets tricky when items arrive one at a time, the total length is unknown, and storing every item in memory is not practical. You run into that with file lines, database cursors, log events, iterators, and network feeds. Reservoir sampling handles it by keeping only a fixed number of items while still giving every item seen so far the same chance of ending up in the final sample. That balance is what makes it useful for large input or data sources that do not have a known end.

Subscribe now

Why Reservoir Sampling Exists

Streaming input creates a hard sampling problem. Items arrive one at a time, the total count may stay unknown, and storing every value can be too expensive. Reservoir sampling was created for exactly that setting. It keeps a small sample in memory while input keeps moving forward, and it does so without giving early or late arrivals an unfair edge. Low memory use and fair selection are the whole reason the method exists.

A Fixed Memory Sample From a Growing Input

Memory pressure is the first issue reservoir sampling handles. Think about a source that keeps handing you values, such as file lines, rows from a database cursor, log entries, or data from a network feed. You can read each item as it arrives, but keeping all of them may not be realistic. Some inputs are huge. Some keep flowing for so long that reading everything first defeats the point of sampling. In that setting, a random sample still has value, while a full copy of the input does not.

Reservoir sampling handles that by picking a sample size up front. Call it k. The method keeps a container with exactly k slots after the first fill phase. The first k items go into those slots directly. After that, every new item faces a decision. It does not automatically enter the sample, and it is not automatically rejected. Instead, it gets a chance to replace one of the stored items.

That replacement rule is what keeps memory fixed. No matter how long the stream gets, the reservoir never grows past k. If k is 100, then the sample storage stays at 100 items after the initial fill. The stream length could be 1,000, 1,000,000, or still rising, and the storage tied to the sample stays the same.

Take a short trace to make that flow easier to follow:

int k = 3;
int[] reservoir = {12, 19, 25};

// item 4 arrives with value 31
// pretend the random draw is 1 from the range 0..3
reservoir[1] = 31;   // reservoir becomes [12, 31, 25]

// item 5 arrives with value 44
// pretend the random draw is 4 from the range 0..4
// no replacement happens, reservoir stays [12, 31, 25]

// item 6 arrives with value 58
// pretend the random draw is 0 from the range 0..5
reservoir[0] = 58;   // reservoir becomes [58, 31, 25]

That trace captures the flow of the method. The sample does not grow as input grows. It stays fixed, and incoming items compete for a slot. Early values are not locked in place. Later values still get a chance to enter. That balance is why the method stays useful on long input instead of turning into a biased record of only what arrived first.

Storage is only part of the story, though. A method that keeps memory low would not help much if it quietly favored one part of the stream over another. Reservoir sampling was built so the sample stays fair while the stream moves forward. Fairness comes from the replacement probability, not from storing everything first and picking later.

There is also a count-only view that helps make the memory side feel more tangible:

int processed = 0;
int k = 5;

// after reading 5 items
processed = 5;   // reservoir size is 5

// after reading 500 items
processed = 500; // reservoir size is still 5

// after reading 50_000 items
processed = 50_000; // reservoir size is still 5

The value in that count view is not the arithmetic itself. What stands out is the fact that processed input keeps rising while reservoir size stays flat. Reservoir sampling does not try to keep a large share of the stream. It tries to keep a fair sample of a chosen size without letting memory grow with the stream length.

Why Every Item Gets the Same Chance

Fairness is the second issue reservoir sampling handles, and this is where the logic gets more interesting. The method is built so every item seen so far has the same final chance to still be in the reservoir. That statement sounds compact, but walking through it slowly helps because the replacement rule can feel unusual at first.

Start with the smallest case, where the reservoir size is 1. The first item becomes the current sample. The second item replaces it with probability 1 / 2. The third item replaces the current sample with probability 1 / 3. The fourth item gets probability 1 / 4, and that same rule keeps going as the stream grows.

That can feel uneven at first because later items get smaller entry chances. The balancing force comes from survival. Early items get into the sample sooner, but they also face more replacement rounds. Later items get fewer entry chances, but they also face fewer chances of being removed after entry. Those two effects balance out.

Take the second item in a stream of five items. It gets selected when it arrives with probability 1 / 2. After that, it has to survive item three, item four, and item five. Its survival chances across those steps are 2 / 3, 3 / 4, and 4 / 5. Multiply those terms and the result is 1 / 5.

Now look at the fifth item. It enters with probability 1 / 5, and there are no later items left to remove it. Its final probability is also 1 / 5. The first, second, third, fourth, and fifth items all end with the same final chance.

Quick numeric checks put numbers on that idea:

double secondItemFinalChance =
        (1.0 / 2.0) *
        (2.0 / 3.0) *
        (3.0 / 4.0) *
        (4.0 / 5.0);

double fifthItemFinalChance = 1.0 / 5.0;

System.out.println(secondItemFinalChance); // 0.2
System.out.println(fifthItemFinalChance);  // 0.2

Both printed values are 0.2, which is the same as 1 / 5. That is the fairness rule in action for the size 1 case.

Take a reservoir with size k next. For an item arriving at position i, there are i possible random outcomes at that moment, and only k of them lead to entry into the reservoir. So the chance to enter is k / i.

After that item enters, later arrivals can remove it, but not all later arrivals will do that. At position i + 1, a replacement happens with chance k / (i + 1), and only one reservoir slot gets replaced. That means a stored item survives that step with probability i / (i + 1). That same survival factor keeps repeating as more items arrive.

By the time the stream reaches position n, the full probability for an item that arrived at position i becomes

(k / i) × (i / (i + 1)) × ((i + 1) / (i + 2)) × ... × ((n - 1) / n)

Most of the middle terms cancel, leaving k / n.

That cancellation is the heart of the method. A later item gets a smaller entry chance, but it also faces fewer future chances to be removed. An earlier item gets into the reservoir sooner, but it faces more future chances to be replaced. The arithmetic balances those effects so the final probability stays the same.

The first k items follow that same logic. They enter immediately because the reservoir still has open space. After the reservoir fills, they begin facing replacement risk from later arrivals. By the time the stream ends at position n, each of those first k items also ends with final probability k / n. So the early part of the stream and the late part of the stream finish on equal footing.

That is why random replacement is not a rough shortcut. It is the reason the sample stays fair. Fixed-size storage by itself would not be enough. Fair storage comes from letting new arrivals challenge older entries with exactly the right probability at each step.

Reservoir Sampling in Modern Java

Java fits reservoir sampling well because the language already gives you the parts this algorithm needs. You need sequential access to incoming values, a bounded random draw after the reservoir fills, and a place to hold only the chosen sample. Current Java covers that through Iterator, generic collections, and the RandomGenerator family. An implementation can stay fairly small, but the details still deserve careful attention, particularly around counting, bounded random selection, and the generator passed into the method.

Sample of One Item

Start with the smallest form first, reservoir sampling with size 1 keeps only one current choice while the source moves forward. The first item becomes the current value right away. After that, each new item gets a replacement chance of 1 / n, where n is the number of items seen so far. In Java, that maps nicely to a bounded random draw. If the random value comes back as zero, the new item replaces the stored item. If not, the stored item stays in place. RandomGenerator fits well here because it gives bounded methods such as nextLong(long bound), and that method returns a value from zero inclusive up to the bound exclusive.

This compact implementation keeps the full rule in one place:

import java.util.Iterator;
import java.util.Optional;
import java.util.random.RandomGenerator;

public final class SingleItemSampler {
    private SingleItemSampler() {
    }

    public static <T> Optional<T> sampleOne(Iterator<T> source, RandomGenerator random) {
        T chosen = null;
        long seen = 0;

        while (source.hasNext()) {
            T item = source.next();
            seen++;

            if (random.nextLong(seen) == 0) {
                chosen = item;
            }
        }

        return seen == 0 ? Optional.empty() : Optional.of(chosen);
    }
}

The seen counter is doing more than keeping a tally. It is part of the probability rule itself. On item 1, nextLong(1) can only return 0, so the first item is stored. On item 2, the method draws from 0 through 1, so replacement happens half the time. On item 3, replacement happens a third of the time. That same flow continues through the entire input. Returning Optional.empty() for an empty source also keeps the result honest instead of inventing a placeholder value that never appeared.

Take a short call site to make that flow easier to read:

import java.util.List;
import java.util.SplittableRandom;
import java.util.random.RandomGenerator;

List<String> events = List.of("login", "search", "checkout", "logout");
RandomGenerator random = new SplittableRandom(2026L);

var chosen = SingleItemSampler.sampleOne(events.iterator(), random);
System.out.println(chosen.orElse("no event"));

Passing the generator in from the outside keeps the sampling method focused on the replacement rule rather than generator creation. That also gives you repeatable runs during tests when you use a fixed seed, or thread-local generation when sampling happens inside concurrent code. SplittableRandom(long seed) is handy for repeatable output, while RandomGenerator keeps the method open to several generator types without changing the algorithm.

Sample of k Items

Move from size 1 to size k, and the structure gets wider without changing the probability rule. The first k items fill the reservoir directly. After the reservoir is full, each new item gets a random slot from the range of items seen so far. If the chosen number falls inside the reservoir range, replacement happens at that slot. If the number falls outside that range, the new item is skipped. Java collections fit this very naturally, and ArrayList is a strong choice here because indexed replacement through set is direct.

This generic method covers that version:

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.random.RandomGenerator;

public final class ReservoirSampler {
    private ReservoirSampler() {
    }

    public static <T> List<T> sample(Iterator<T> source, int k, RandomGenerator random) {
        if (k < 0) {
            throw new IllegalArgumentException("k must be at least 0");
        }

        List<T> reservoir = new ArrayList<>(k);
        long seen = 0;

        while (source.hasNext() && reservoir.size() < k) {
            reservoir.add(source.next());
            seen++;
        }

        while (source.hasNext()) {
            T item = source.next();
            seen++;

            long slot = random.nextLong(seen);
            if (slot < k) {
                reservoir.set((int) slot, item);
            }
        }

        return reservoir;
    }
}

Two counters are active in that method. reservoir.size() tells you how full storage is during the first fill phase. seen tracks how several items have passed through the sampler in total. That second value is the part tied to probability. If seen is 10 and k is 3, then only three random outcomes out of the ten possible values from nextLong(10) lead to entry into the reservoir. That gives the current item its correct 3 / 10 entry chance.

Choosing long for seen is helpful for long-running input. The reservoir still relies on indexed collection access, so k remains an int, but the count of processed items does not have to stop at Integer.MAX_VALUE. The cast from slot to int is safe here because the cast only happens after the code checks slot < k, and k already fits in int.

Edge behavior deserves a short note too. If the source ends before k items arrive, the method returns all available items. That matches the problem naturally because there is no way to return a sample of ten distinct items from an input that only had six.

Sampling from file lines gives this method a natural place to run:

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.SplittableRandom;

Path logFile = Path.of("events.log");

try (var lines = Files.lines(logFile)) {
    List<String> picked = ReservoirSampler.sample(
            lines.iterator(),
            5,
            new SplittableRandom(9001L)
    );

    for (String line : picked) {
        System.out.println(line);
    }
}

That example stays close to what reservoir sampling is built for. The file can be read as a stream of lines, the sampler stores only five of them, and the method does not need the full line count ahead of time. Files.lines also makes the sequential nature of the source very visible, which pairs nicely with a one-pass sampling method.

Picking a Generator in Current Java

Generator choice affects the call site more than the reservoir logic itself, but it still deserves attention because current Java gives you several strong options. RandomGenerator is the shared interface, so the sampling method can accept that type and stay open to several generator classes. That keeps the algorithm from being tied to any single generator implementation.

ThreadLocalRandom is a strong fit when each thread is sampling independently. ThreadLocalRandom.current() returns the generator for the current thread, which avoids sharing a single mutable generator across threads. That is useful when sampling runs inside concurrent code and each thread has its own input flow. SplittableRandom is also a very good fit. It was built with independent random generation in mind, and it supports splitting into new generators that can continue separately. It also has a constructor that takes a seed, which is useful when you want repeatable output during tests or while checking example runs.

A short comparison at the call site makes those choices easier to see:

import java.util.List;
import java.util.SplittableRandom;
import java.util.concurrent.ThreadLocalRandom;
import java.util.random.RandomGenerator;

List<Integer> values = List.of(3, 8, 13, 21, 34, 55, 89);

RandomGenerator seeded = new SplittableRandom(13579L);
List<Integer> seededSample = ReservoirSampler.sample(values.iterator(), 3, seeded);

RandomGenerator perThread = ThreadLocalRandom.current();
List<Integer> threadSample = ReservoirSampler.sample(values.iterator(), 3, perThread);

The first call is repeatable for the same seed within the same generator class, which is useful in tests. The second call suits per-thread activity better. Neither choice changes the reservoir algorithm itself. The algorithm only needs bounded random selection through the RandomGenerator API.

Security-sensitive code can call for a different generator family. SecureRandom belongs in that category. Because SecureRandom extends Random, and Random implements RandomGenerator, it can also be passed to the same method signature when that kind of generator is needed.

Cost on Large Input

Performance is one reason reservoir sampling remains attractive in Java. The sampler reads each item exactly one time in the basic form, so time cost rises linearly with the number of processed items. Storage stays tied to the sample size k, not to the full input length. In big-O terms, that gives O(n) time for a pass over n items and O(k) space for the reservoir. If the sample size is 1, storage drops to O(1).

What counts in practice is that the method does not need random access into the original source and does not need to buffer the full stream before deciding. Iterator<T> is enough. That matches file lines, cursor-backed results, stream iterators, and any other source that is already moving forward item by item.

There is also a useful boundary to keep in mind. Reservoir sampling gives a uniform sample from the sequence that actually reaches the sampler. If earlier filtering has already changed that sequence, the sampler will faithfully sample the filtered sequence rather than the raw source. So the fairness guarantee belongs to the data that entered the algorithm, not to data that never reached it.

Very large sampling jobs have inspired skip-based variants that reduce per-item random decisions. Those versions belong to the broader family, but the plain reservoir replacement rule is still the best starting point for most Java articles and codebases because it is short, readable, and lines up well with the standard library tools already in place.

Conclusion

Reservoir sampling comes down to a small set of moving parts. You keep a fixed reservoir, fill it with the first k items, then let each later item compete for a slot based on how far into the stream it arrived. That replacement rule is what keeps memory flat while still giving every seen item the same final chance to remain in the sample. Java fits that flow well through Iterator, bounded random draws, and a small collection for storage, which is why the method holds up so well for long streams and unknown input sizes.

1. RandomGenerator Interface

2. SplittableRandom Class

3. ThreadLocalRandom Class

4. SecureRandom Class

5. Iterator Interface

6. Files Class

7. Path Interface

8. ArrayList Class

Share Alexander Obregon's Substack

Client-side ring selection lets a client choose a backend in a repeatable way without handing that choice to a central balancer. The client hashes a stable request value, such as a tenant ID, session ID, account ID, or cache key, then maps it onto a ring where backends are placed through virtual points. The chosen target is the first backend clockwise from that hash position. If the backend set stays the same, the same request keeps going to the same backend. If one backend goes down, only that backend’s portion of the ring gets reassigned. That is why ring hashing is useful for sticky routing, caches, sharded reads, and similar traffic. Service discovery works nicely with that flow by giving the client an updated list of available instances so it can rebuild the ring from the active set.

Subscribe now

Picking a Target on the Ring

Client-side ring selection starts with a stable request value and ends with one backend chosen from a shared ring. That sentence sounds compact, but a fair amount happens between those two points. A client needs a repeatable way to turn request data into a number, a repeatable way to place backend entries on the ring, and a repeatable way to walk that ring so the same request token keeps reaching the same backend while membership stays the same.

Most of the behavior people care about in a ring begins right here. Stable placement does not come from luck. It comes from feeding the same input into the same hash function, keeping the ring layout consistent across clients, and walking clockwise in the same way every time. Once those rules stay fixed, target selection becomes predictable enough to support sticky routing, cache locality, and shard-aware traffic without handing every request to a central chooser.

Request Hash Meets Ring Points

Everything starts with the request value you decide to hash. That value has to stay tied to the thing you want to keep on one backend. Session traffic usually hashes a session identifier. Tenant traffic usually hashes a tenant identifier. Cache traffic usually hashes the cache key itself. If the client hashes something that changes from one call to the next, placement changes with it, and the ring stops giving you repeatable target selection for that unit of traffic.

Each request hash is just a number until it is compared with the ring. Backends already have points placed around the circle, and the client looks for the first backend point at or after the request hash while moving clockwise. If the request hash lands near the end of the ring and no backend point appears after it, the client wraps back to the first point at the start of the ring. That wraparound step is part of the ring lookup, not a special second rule bolted on later.

Java’s NavigableMap is a handy fit for that lookup because it keeps points ordered. A request hash can be matched with ceilingEntry, and if that returns null, the client wraps to firstEntry:

import java.util.NavigableMap;
import java.util.TreeMap;
import java.util.Map;

public final class RingLookup {
    private final NavigableMap<Long, String> ring = new TreeMap<>();

    public RingLookup() {
        ring.put(102L, "backend-east-1");
        ring.put(340L, "backend-west-2");
        ring.put(615L, "backend-east-2");
        ring.put(910L, "backend-central-1");
    }

    public String pick(long requestPoint) {
        Map.Entry<Long, String> entry = ring.ceilingEntry(requestPoint);
        if (entry != null) {
            return entry.getValue();
        }
        return ring.firstEntry().getValue();
    }
}

The lookup rule stays the same no matter how the request point was produced. What changes is the request value chosen before hashing. That part deserves care because it decides what kind of stickiness the client gets. Hashing a tenant ID keeps one tenant near one backend. Hashing a shopping cart ID keeps one cart near one backend. Hashing a per-request timestamp would make the ring behave almost randomly for that traffic, which defeats the purpose of ring-based selection in the first place.

Picking the hash input also affects how evenly request ownership spreads across the ring. If almost every request shares the same small set of identifiers, the ring may still be behaving exactly as written while traffic piles onto a narrow slice of backends. That is not a ring failure. That is a property of the request data. Good placement starts with a request token that has enough variety for the traffic you are routing.

This gets easier to understand with a small helper method that picks the token based on the kind of placement you want to preserve:

public final class RequestTokenSelector {

    public String selectToken(ClientRequest request) {
        if (request.sessionId() != null && !request.sessionId().isBlank()) {
            return request.sessionId();
        }
        if (request.tenantId() != null && !request.tenantId().isBlank()) {
            return request.tenantId();
        }
        return request.accountId();
    }
}

record ClientRequest(String sessionId, String tenantId, String accountId) {}

Notice what this code is really doing. It is deciding what should stay attached to one backend. That choice comes before any ring lookup happens, and it has a lasting effect on the traffic profile the client creates.

Placement on the ring itself also needs to be identical wherever the client logic runs. If one client builds backend points in a different order, hashes backend identifiers differently, or skips some points another client included, two clients can send the same request token to different backends. Ring hashing depends on shared rules, not on one lucky calculation. Same request token, same backend membership, same hashing steps, same ring walk. That is the chain that makes target selection repeatable.

Stable Placement Through Virtual Points

One ring point per backend sounds fine at first, but it usually produces rough ownership slices. Some backends end up with wide arcs, others with narrow ones, and traffic share drifts more than people expect. Virtual points fix that by placing each backend on the ring multiple times instead of just once. Each placement claims a small arc, and the combined arcs for that backend add up to its total share.

More points usually mean better balance across the circle, but that does not mean the ring becomes mathematically perfect. Hashing still spreads points based on the hash results, so some variation remains. What changes is the scale of that variation. With a thin ring, one unlucky placement can give a backend too much space. With a fuller ring, ownership is broken into smaller slices, which pulls the final share closer to what the client intended.

Weighted rings handle this by turning weight into repeated placements around the ring. If one backend is meant to carry about twice the share of another, it usually gets about twice as many virtual points. That means the client is not keeping a single backend entry and attaching extra traffic to it later. It is giving that backend more positions on the ring from the start, which gives it a larger share of ownership during lookup.

To see how that looks in code, a ring builder can place the same backend on the ring multiple times based on its weight:

import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.NavigableMap;
import java.util.TreeMap;
import java.util.zip.CRC32;

public final class WeightedRingBuilder {
    private final NavigableMap<Long, String> ring = new TreeMap<>();

    public WeightedRingBuilder(Map<String, Integer> weights, int pointsPerWeightUnit) {
        for (Map.Entry<String, Integer> entry : weights.entrySet()) {
            String backendId = entry.getKey();
            int weight = entry.getValue();

            for (int i = 0; i < weight * pointsPerWeightUnit; i++) {
                long point = hash32(backendId + "#" + i);
                ring.put(point, backendId);
            }
        }
    }

    public NavigableMap<Long, String> ring() {
        return ring;
    }

    private long hash32(String value) {
        CRC32 crc32 = new CRC32();
        crc32.update(value.getBytes(StandardCharsets.UTF_8));
        return crc32.getValue();
    }
}

The backendId + "#" + i part is what creates a different hash input for the same backend. Without that suffix, repeated hashing of the same backend identifier would keep landing on the same point, which would defeat the whole point of virtual placement. Each numbered entry usually lands at a different location on the ring, though hash collisions can still map two entries to the same point.

Traffic ownership gets easier to follow when the ring is viewed as a long run of small ownership slices rather than a single slice for each backend. The request token hashes to one location, then the client moves clockwise until it reaches the first virtual point. That point belongs to a backend, so that backend gets the request. Distance to the backend’s next virtual point does not change that result. If the same request token comes back later, it hashes to the same location and reaches that same winner again.

To make that easier to see in code, take this inspection helper that can count how those virtual points are distributed across the ring:

import java.util.Map;
import java.util.HashMap;
import java.util.NavigableMap;

public final class RingOwnershipCounter {

    public Map<String, Integer> countPoints(NavigableMap<Long, String> ring) {
        Map<String, Integer> totals = new HashMap<>();

        for (String backendId : ring.values()) {
            totals.merge(backendId, 1, Integer::sum);
        }

        return totals;
    }
}

Counting ring entries does not tell you the exact request share by itself, but it does give a quick read on how virtual placement was distributed. If a backend was meant to carry twice the traffic of another backend, its point count should usually be about twice as large as well. From there, the actual arc lengths still depend on where those points landed after hashing.

Ring size affects how placement behaves in practice too. Sparse rings with very few virtual points can create large arcs, so small changes in point placement carry more weight. Fuller rings break ownership into smaller arcs, which keeps distribution closer to the intended shares. That is why virtual points are not just an extra tuning choice. They are part of what makes ring-based target selection usable at scale.

Stable placement through virtual points also depends on backend identity staying consistent. If one refresh names a backend orders-7 and the next refresh names that same backend 10.1.4.23, the client hashes two different identifiers and places them at different positions. Membership may not have changed in any meaningful way, yet the ring would still be rearranged. Consistent backend identity is directly tied to consistent point placement.

Also, virtual points do not change the basic lookup rule. The request still hashes to one location, and the client still walks clockwise. What changes is the texture of the ring. Instead of a small number of wide ownership regions, the ring becomes a larger field of smaller regions that map back to backend identities in a more balanced way. That is what gives ring hashing its stable feel while keeping target selection repeatable enough for sticky traffic.

Failure Handling With Discovery

Routing on a ring gets more interesting the moment backend health starts changing. The request token still hashes to the same location, yet the client can no longer treat every backend on the ring as eligible. Discovery data and local health feedback are the two inputs that guide that decision. Discovery supplies a shared view of active membership, while local feedback lets the client react right after a connection or request fails. That split keeps the flow readable. Ring lookup still decides who owns traffic for a given token. Discovery and health status decide who is allowed to participate in that lookup at the current moment. From there, failover behavior, remap size, and refresh timing all follow from that same idea.

Failover After a Dead Node

Failover on a hash ring behaves very differently from modulo-based routing. With modulo hashing, a membership change can reshuffle a large share of placements because the divisor changes. On a ring, the token still hashes to the same location, and the client still moves clockwise from that point. What changed is the set of live backends. If a backend is gone, the client keeps moving until it reaches the next backend that is still eligible to receive traffic.

That part is what makes ring failover fairly intuitive once the lookup rule is already familiar. The token does not need to be reinterpreted during failure. No replacement hash is computed. No separate failover map is required. Traffic that used to stop at the dead backend now continues forward to the next live backend, while traffic that belonged elsewhere keeps the same destination.

Client implementations usually handle that in two broad ways. Some clients rebuild the active ring after discovery marks a backend unhealthy, then run lookup against that smaller ring. Others keep the full ring in memory for a short period and mark a failing backend as temporarily ineligible right after local errors such as connection refusal, TLS handshake failure, or repeated short timeouts. In both cases, the client still follows the same clockwise walk. The only difference is which source marked the backend unavailable.

This selector keeps that behavior visible in code:

import java.time.Instant;
import java.util.Map;
import java.util.NavigableMap;

public final class FailoverSelector {
    private final NavigableMap<Long, String> ring;
    private final Map<String, Instant> locallyBlockedUntil;

    public FailoverSelector(NavigableMap<Long, String> ring, Map<String, Instant> locallyBlockedUntil) {
        this.ring = ring;
        this.locallyBlockedUntil = locallyBlockedUntil;
    }

    public String pick(long requestPoint) {
        for (String backend : ring.tailMap(requestPoint, true).values()) {
            if (isUsable(backend)) {
                return backend;
            }
        }

        for (String backend : ring.headMap(requestPoint, false).values()) {
            if (isUsable(backend)) {
                return backend;
            }
        }

        throw new IllegalStateException("No live backend available");
    }

    private boolean isUsable(String backend) {
        Instant blockedUntil = locallyBlockedUntil.get(backend);
        return blockedUntil == null || Instant.now().isAfter(blockedUntil);
    }
}

Nothing about the ring lookup changed in that class. The client still starts from the token’s ring position and still scans clockwise with wraparound. Local blocking only changes which backend can stop that scan.

Timing is the part that makes this worth calling out. Discovery data is never perfectly instantaneous. A backend can fail after the last refresh and still remain present in the client’s current membership view for a short period. During that gap, local feedback lets the client stop routing traffic to a backend that has already started failing. Later, discovery catches up and removes that backend from the shared active set.

That local suppression window belongs to client policy rather than to the ring itself. Short windows let a backend return to traffic sooner after a brief network issue. Longer windows reduce repeated failures to the same destination, though they also keep a recovered backend out of local rotation for more time. The ring defines the walk and health policy defines which stops on that walk are currently acceptable.

How Much Traffic Moves

Consistent hashing reduces remapping, but it does not remove it. If one backend disappears, the tokens that used to belong to that backend move forward to the next live backend on the ring. Tokens that mapped to other backends stay where they were. That is the practical meaning of minimal remapping in ring-based routing.

For equal-share backends on a ring with decent partitioning, removing one backend from a set of N usually moves about 1/N of the tokens. Ten equal backends means roughly one tenth of the traffic moves after one loss. With a hundred equal backends, roughly one hundredth of the traffic moves. That estimate depends on the ring being partitioned well enough that backend ownership is close to the intended shares.

Smaller rings can drift from that target. If virtual points are sparse or bunched unevenly, one backend can own more arc length than intended, which means its failure moves more traffic than the equal-share estimate would suggest. That is why virtual point count and ring size have such a strong effect on observed remap size. They do not alter the clockwise lookup rule, but they do affect how evenly ownership is spread before anything fails.

Weighted backends follow the same logic. If a backend owns a larger share of the ring, losing that backend moves a larger share of traffic. No special outage formula is needed for that case. The amount of traffic that moves follows directly from how much ring ownership that backend had before it dropped out.

The same idea appears during scale-out. When a new backend joins, it takes over part of the ring from the current backends rather than forcing a full reshuffle. That is why ring-based routing is so useful for sticky traffic. Session tokens, tenant tokens, and shard tokens keep their placement unless the slice of the ring tied to that token changes ownership.

Remapping is easiest to follow when viewed as an ownership transfer around the ring. One backend loses its region, and neighboring live regions absorb it clockwise. The client is not rebalancing every token across the full backend set after a failure. It is handing off the failed backend’s portion to the next reachable owners on the circle.

Discovery Feeds the Active Set

Discovery answers a different question from the ring. The ring decides where traffic should go among the current candidates. Discovery decides which candidates belong in that active set at all. Keeping those two jobs separate makes the full flow much easier to reason about.

Kubernetes is a good example of that split. Backend membership for a Service is tracked through EndpointSlice objects. Clients that read those active endpoints can rebuild their ring from the current healthy membership instead of relying on a stale address list. The ring lookup itself does not change. What changes is who gets placed on the ring before lookup starts.

Consul follows the same overall model through a different API surface. Services register there, health checks update their status, and clients can read the healthy service view to populate the active backend set. The ring does not perform those health checks by itself. It consumes the active membership that discovery and health evaluation already produced.

This adapter keeps that handoff visible:

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

public final class ActiveRingFactory {

    public WeightedRingBuilder fromDiscovery(List<ServiceInstance> instances, int pointsPerWeightUnit) {
        Map<String, Integer> weights = new LinkedHashMap<>();

        for (ServiceInstance instance : instances) {
            if (instance.healthy()) {
                weights.put(instance.instanceId(), instance.weight());
            }
        }

        return new WeightedRingBuilder(weights, pointsPerWeightUnit);
    }
}

record ServiceInstance(String instanceId, boolean healthy, int weight) {}

That class does not perform discovery on its own. Its job is narrower. It takes membership data that discovery already returned, keeps only the healthy entries, and turns that active set into ring membership.

Clients that skip discovery can still build a ring, but membership then becomes fixed or manually maintained. That gets fragile in environments where instances appear and disappear, addresses change, or health status changes faster than configuration files do. Discovery without ring-based placement has the opposite weakness. The client knows who is active, but it still needs a repeatable rule for choosing one destination for a given token. Put those two pieces side by side, and the client gets live membership with stable placement.

Backend identity also needs to stay consistent across refreshes. If discovery reports the same backend under different identifiers from one update to the next, the client hashes different backend names and places them at different ring positions. Membership may be effectively the same, yet placement will still move because the ring sees those identifiers as different entries.

Refresh Windows Plus Local Health

Refresh timing decides how quickly discovery changes alter the ring, while local health decides what the client does between those refreshes. Those inputs are related, but they are not the same thing.

Shared discovery data gives the client a broader membership view. Local health gives the client the earliest sign that something just failed in front of it. Healthy routing flow uses both. Discovery is useful for giving the fleet a common view of membership. Local failure feedback is useful right after an outbound call starts failing.

Let’s see how that looks with a small tracker that keeps a short local quarantine window for failing backends:

import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;

public final class LocalHealthTracker {
    private final ConcurrentMap<String, Instant> blockedUntil = new ConcurrentHashMap<>();
    private final Duration blockTime = Duration.ofSeconds(20);

    public void markFailure(String backendId) {
        blockedUntil.put(backendId, Instant.now().plus(blockTime));
    }

    public void markSuccess(String backendId) {
        blockedUntil.remove(backendId);
    }

    public boolean isBlocked(String backendId) {
        Instant until = blockedUntil.get(backendId);
        return until != null && Instant.now().isBefore(until);
    }
}

Local quarantine does not replace discovery membership. It covers the gap between refreshes. If a backend starts failing right now, the client does not have to wait for the next registry update before reacting.

Refresh rate also affects stickiness and traffic churn. Long refresh windows can leave dead nodes on the ring longer than they should stay there, which leads to repeated local failovers before discovery catches up. Extremely short refresh windows can rebuild the ring too aggressively and move traffic more frequently than needed. The best interval depends on how quickly backend state changes, how fast the discovery source updates health, and how expensive extra remaps are for the traffic being routed.

Not every discovery update needs a rebuild either. If fresh discovery data arrives without any change to active membership, rebuilding the ring serves little purpose and still adds churn inside the client.

This small snapshot check helps keep rebuilds tied to actual membership changes:

import java.util.List;
import java.util.Objects;

public final class MembershipSnapshot {
    private final List<String> activeBackendIds;

    public MembershipSnapshot(List<String> activeBackendIds) {
        this.activeBackendIds = activeBackendIds.stream()
                .sorted()
                .toList();
    }

    public boolean sameMembership(MembershipSnapshot other) {
        return Objects.equals(this.activeBackendIds, other.activeBackendIds);
    }

    public List<String> activeBackendIds() {
        return activeBackendIds;
    }
}

Two health views are active through this whole flow. One comes from discovery and reflects the broader shared membership picture. The other comes from the client’s own request outcomes. Discovery can still report a backend as present while the client has already seen repeated failures to that same backend. Local suppression handles that near-term gap. After discovery removes the backend from the active set, the rebuilt ring no longer includes it as a candidate. That sequence fits naturally with ring routing. Local health reacts first, and discovery membership turns that temporary decision into shared ring membership on the next rebuild.

Conclusion

Ring-based client-side load balancing comes down to a repeatable routing flow. The client hashes a stable request value, moves clockwise to the matching backend point, and keeps sending that traffic to the same place while membership stays unchanged. Virtual points spread ownership across the ring more evenly, service discovery keeps the active backend set current, and local health checks let the client step past failing nodes before the next refresh arrives. When a backend drops out or a new one joins, only the affected slice of ring ownership is reassigned, which is why this model fits sticky routing, shard-aware traffic, and cache-heavy traffic so well.

1. Spring Cloud LoadBalancer Reference

2. Kubernetes Service Documentation

3. Kubernetes EndpointSlices Documentation

4. Consul Health Checks Documentation

5. Envoy Ring Hash Load Balancing

6. Spring Cloud Commons Reference

Share Alexander Obregon's Substack

Strongly connected components split a directed graph into maximal groups where every vertex can reach every other vertex in the same group. Two classic depth first search methods for finding those groups are the Kosaraju Sharir method and Tarjan’s method. They both run in linear time on an adjacency-list graph, yet they separate components in very different ways. Kosaraju records finish order, builds a reversed graph, then runs a second pass. Tarjan stays on the original graph, keeps an active vertex stack, and compares discovery indexes with low-link values to decide the exact moment a component is complete. In Java, that difference changes adjacency storage, stack handling, object allocation, and extra memory kept during traversal.

Subscribe now

Kosaraju in Java

Two full depth first search passes drive this method. The first pass walks the graph in its original direction and records vertices by exit time. The second pass walks a transposed copy of the graph in reverse exit order and pulls out one strongly connected component at a time. Sharir’s 1981 paper gives the linear-time foundation for this family of SCC algorithms, and the form most learn today still follows that same two-pass structure on adjacency-list graphs. What makes Kosaraju readable in Java is the way those two passes stay separate in purpose. The first pass has a single job, it captures finish order. The second pass has a different job. It follows reversed edges and gathers component members. That split keeps the code easy to scan because the first DFS is not trying to assign component ids while it is still walking outward from a vertex. Storage does grow, though. You keep the original adjacency list, build a reversed copy, track visited state, and hold an order container from the first pass.

Finish Order

Exit time is the first idea that needs to lock into place. During DFS, a vertex is not recorded when it is first reached. Recording happens only after DFS has followed every reachable outgoing edge from that vertex and returned all the way back. That stored order is what the second pass depends on. If one strongly connected component can reach a different component in the condensation graph, the source component finishes later than the destination component. That finish timing is what makes the later reverse-order scan meaningful instead of random.

Viewed through the recursion stack, the first pass keeps delaying a vertex until every deeper call below it is finished. Whole components inherit that timing. If a component has an edge that leads outward into a different component, DFS can keep moving before it finally comes back to the starting side. That outward reach pushes the source component later in the finish sequence. When the stored order is read back from the front of a stack-like container, those later-finishing components come out first.

Most Java versions keep the first pass compact:

private void fillOrder(int node, boolean[] visited, List<List<Integer>> graph, Deque<Integer> order) {
    visited[node] = true;

    for (int next : graph.get(node)) {
        if (!visited[next]) {
            fillOrder(next, visited, graph, order);
        }
    }

    order.push(node);
}

Placement of order.push(node) is the whole story in that method. It belongs after the neighbor loop, not before it. Move it to the top and the stored order turns into visit order instead of finish order. Put it inside the loop and the recorded sequence no longer matches DFS exit time. That single line is small in the code and very large in effect.

Visit order and finish order are easy to blur on a first read, so it helps to separate them very deliberately. Visit order tells you when DFS first touches a vertex. Finish order tells you when DFS is done with that vertex after every reachable outgoing branch has already been handled. Kosaraju depends on the second of those two timings, not the first. Two vertices can be visited in one order and finished in the reverse order, and that reversal is perfectly normal.

For stack-like storage, Deque backed by ArrayDeque is the better fit in modern Java. The library documentation treats Stack as legacy and points readers toward Deque for LIFO behavior. In practice, the mapping is exactly what this pass needs. push places a vertex at the front, pop removes from the front, and peek reads the next vertex that would come off.

That behavior is easy to see in this example:

Deque<Integer> order = new ArrayDeque<>();

order.push(7);
order.push(3);

int firstOut = order.pop();   // 3
int nextOut = order.peek();   // 7

That same LIFO behavior is what the first pass relies on. Vertices that finish later are pushed later, so they rise to the top of the deque and come off first during the second pass. Nothing fancy is happening there. The container is just preserving the exact order that the second sweep needs.

Tracing a DFS run can also make the finish-order rule much easier to read while testing a graph:

private void fillOrderTrace(
        int node,
        boolean[] visited,
        List<List<Integer>> graph,
        Deque<Integer> order
) {
    visited[node] = true;
    System.out.println("enter " + node);

    for (int next : graph.get(node)) {
        if (!visited[next]) {
            fillOrderTrace(next, visited, graph, order);
        }
    }

    order.push(node);
    System.out.println("exit  " + node + " push to order");
}

Those print lines tell two different stories. The enter line gives visit order. The exit line gives the order Kosaraju actually keeps. On a graph with one region leading into another, the gap between those two views becomes very visible. That gap is not a side detail. The algorithm depends on it.

Reverse Graph Pass

Every edge is flipped before the second DFS pass begins. If the original graph contains u -> v, the transpose stores v -> u. Strongly connected components themselves do not change under that reversal. Internal mutual reachability inside a component still holds after every edge is reversed. What does change is the direction of travel between components in the condensation graph. A source component in the original condensation graph becomes a sink in the transposed graph, and that is exactly what the second pass needs when it starts from the vertex with the largest recorded exit time.

That is the reason this method takes two passes. After the first pass has ordered vertices by decreasing exit time, the second pass can start from the front of that order and walk only within the reversed edges of the intended component. The transpose does not create new SCCs or destroy old ones. It changes the between-component direction so the next DFS stops at the correct boundary.

Building the transposed graph in Java is usually one full scan over the original adjacency list:

private static List<List<Integer>> transpose(List<List<Integer>> graph) {
    List<List<Integer>> reversed = new ArrayList<>(graph.size());

    for (int i = 0; i < graph.size(); i++) {
        reversed.add(new ArrayList<>());
    }

    for (int from = 0; from < graph.size(); from++) {
        for (int to : graph.get(from)) {
            reversed.get(to).add(from);
        }
    }

    return reversed;
}

That method allocates a new outer list with the same vertex count, then scans every original edge. For every from -> to, it appends from into the neighbor list of to. Runtime stays linear in vertices and edges on adjacency-list graphs, but memory grows because the graph is now stored twice, first in its original direction and then in reversed form. That extra edge storage is one of the main tradeoffs tied to Kosaraju in Java.

After the transpose is ready, the second pass is mechanically simple relatively. Pop the next vertex from the finish-order deque. If that vertex has not been visited in the second pass yet, launch DFS on the transposed graph from that vertex. Every vertex reached during that one search belongs to the same strongly connected component. No extra test is needed to discover the boundary during the walk. The ordering from the first pass and the reversed edges already did that job before the second DFS even started.

That keeps the second pass easier to read than readers sometimes expect. After the ordering is correct and the transpose exists, this pass is just DFS on a different adjacency list. What looked abstract during the first explanation becomes very mechanical in code. Start from the next recorded vertex, follow reversed edges, mark visited vertices, collect them into the current component, then move on to the next unvisited vertex in the stored order.

Recursion depth is still worth keeping in mind in Java. DFS reads nicely in recursive form, but a very deep graph can still overflow the thread stack. The algorithm itself does not require recursion. It requires depth-first traversal and finish-order recording. If graph depth is large enough to make stack depth a concern, an iterative translation with an explicit frame stack can preserve the same logic while avoiding recursive calls.

Tarjan in Java

Single-pass SCC detection is what sets Tarjan apart from Kosaraju. Instead of recording finish order, building a transposed graph, and returning for a second sweep, Tarjan stays on the original directed graph and decides component boundaries during the same DFS that first discovers the vertices. That difference changes the feel of the code right away. More live state has to travel through the traversal, but the graph itself stays in a single direction. Compared with Kosaraju, the trade is easy to see. Kosaraju keeps the DFS logic lighter in each pass and pays for that with a reversed graph and another traversal. Tarjan keeps everything inside one traversal and pays for that with more per-vertex bookkeeping. In Java, that bookkeeping usually lives in a few primitive arrays and one stack-like container, which makes the method compact in memory while still asking the reader to track more moving pieces during DFS.

Discovery Index

Every vertex gets a discovery index at the moment DFS reaches it for the first time. That number is assigned from a running counter and never changes later. Most Java versions store those values in an int[] index array, and unseen vertices start at -1. Tarjan also sets low[v] to that same index at first contact, because the vertex can always reach itself before any outgoing edge is checked.

That first assignment block is small, but it carries a lot of weight. Kosaraju spends its opening pass building finish order for later use. Tarjan starts attaching stable timestamps right away, and those timestamps become the anchor for every low-link update that follows. If index[v] is the moment the search entered v, then every later question about how far back v can still reach gets measured against that fixed number.

The first-visit code usually reads like this:

private void dfs(int node) {
    index[node] = time;
    low[node] = time;
    time++;

    stack.push(node);
    onStack[node] = true;

    for (int next : graph.get(node)) {
        if (index[next] == -1) {
            dfs(next);
            low[node] = Math.min(low[node], low[next]);
        } else if (onStack[next]) {
            low[node] = Math.min(low[node], index[next]);
        }
    }

    if (low[node] == index[node]) {
        popComponent(node);
    }
}

Two arrays are being given a starting value in those first three lines, and that is deliberate. index[node] records entry time. low[node] starts with the same value because DFS has not seen any edge yet that proves a path back to an earlier discovered vertex. From there, every child return and every back edge can pull low[node] downward, but index[node] itself stays fixed.

Initialization often looks like this in Java:

public TarjanScc(List<List<Integer>> graph) {
    this.graph = graph;
    int n = graph.size();
    this.index = new int[n];
    this.low = new int[n];
    this.onStack = new boolean[n];
    this.stack = new ArrayDeque<>();
    this.components = new ArrayList<>();
    Arrays.fill(index, -1);
}

Filling index with -1 gives the DFS a cheap unseen marker. Primitive arrays help here because they avoid per-vertex object overhead. Compared with Kosaraju, that is one of the first places the memory trade starts to show up. Tarjan spends memory on state arrays tied to vertices, while Kosaraju spends more memory on edge storage after the transpose is built.

Low Link Values

Low-link values are the part that usually takes the longest to settle in because they are not just visit timestamps with a new name. For a vertex v, low[v] tracks the smallest discovery index reachable from v while the DFS is still inside the current unfinished region. That route can move downward through DFS tree edges and can also use a back edge to an earlier discovered vertex that is still active on the stack.

Seen that way, low[v] answers a very specific question. From v, how far back into the current DFS history can the search still reach without leaving the unfinished region. If the answer is smaller than index[v], then v is tied to an earlier ancestor in the same still-open component. If the answer stays equal to index[v], then no vertex below v managed to reach an earlier active ancestor than v itself.

Two update cases drive the whole idea. First, DFS can walk from v into an unseen child w. After that recursive call returns, whatever earliest active ancestor w could reach is now also reachable from v, so low[v] gets compared against low[w]. Second, DFS can see an edge from v to a vertex that was already discovered and is still on the active stack. In that case, v has found a direct route back into the live DFS chain, so low[v] gets compared against index of that stack vertex.

That logic is usually written in one tight block:

for (int next : graph.get(node)) {
    if (index[next] == -1) {
        dfs(next);
        low[node] = Math.min(low[node], low[next]);
    } else if (onStack[next]) {
        low[node] = Math.min(low[node], index[next]);
    }
}

The difference between those two updates is what keeps the numbers honest. Child returns use low[next] because the child subtree may have reached farther back than its own entry time. Edges to a still-active vertex use index[next] because that edge is tying the current node directly to a known earlier point in the live stack. Swapping those two rules around breaks the logic.

Let’s see how a short tracing helper can make the values easier to follow while stepping through a graph:

private void dfsTrace(int node) {
    index[node] = time;
    low[node] = time;
    time++;

    stack.push(node);
    onStack[node] = true;

    System.out.println("visit " + node + " index=" + index[node] + " low=" + low[node]);

    for (int next : graph.get(node)) {
        if (index[next] == -1) {
            dfsTrace(next);
            low[node] = Math.min(low[node], low[next]);
            System.out.println("return to " + node + " from " + next + " low=" + low[node]);
        } else if (onStack[next]) {
            low[node] = Math.min(low[node], index[next]);
            System.out.println("back edge " + node + " -> " + next + " low=" + low[node]);
        }
    }

    if (low[node] == index[node]) {
        popComponent(node);
    }
}

Those trace lines help separate child-return updates from back-edge updates, which is usually where readers first get tangled up. After a child returns, the parent absorbs the child’s best reach into the active DFS chain. During a back edge, the current vertex reaches directly into that chain itself. Both cases can reduce low, but they do it for different reasons.

Kosaraju handles component boundaries through finish order and a later scan on reversed edges. Tarjan pushes that boundary logic into the current DFS frame instead. Low-link values are the mechanism that makes that possible. They let the method decide, during unwinding, if a vertex is still tied to an earlier active ancestor or if the search has closed a full component at the current vertex.

Active Stack Rule

Stack membership is the guardrail that keeps Tarjan from merging vertices that no longer belong to the same unfinished region. During DFS, every newly discovered vertex is pushed onto the active stack and marked in onStack. That mark stays true until the algorithm has proven the root of its component and pops the whole group. Vertices that have already been popped are finished. Edges to them do not pull low-link values backward anymore. That condition is why Tarjan does not treat every visited vertex the same way. Any discovered vertex that is still on the stack can affect low-link through a back edge. Any discovered vertex that has already been popped cannot. This marks a sharp difference from a plain visited-array DFS. Tarjan needs two states after discovery, not just visited and unvisited. It needs active and finished.

The root test is very precise because if low[node] == index[node], then the search has found the vertex that closes an SCC. That equality means no vertex reachable below node found a route back to any earlier active ancestor than node. At that moment, vertices are popped from the stack until node itself comes off, and every popped vertex belongs to that component.

That pop block usually looks something like this:

private void popComponent(int root) {
    List<Integer> component = new ArrayList<>();

    while (true) {
        int top = stack.pop();
        onStack[top] = false;
        component.add(top);

        if (top == root) {
            break;
        }
    }

    components.add(component);
}

The stack is doing more than storing DFS history there. It is storing the current unfinished region from which SCCs can still be formed. After a vertex leaves that stack, it is done. Future edges pointing to it no longer count as live links inside the current region. That is why the neighbor check uses onStack[next] instead of a plain visited test.

Compared with Kosaraju, this is where the boundary decision moves. Kosaraju waits until a later pass to gather SCC members. Tarjan gathers them the instant a root condition becomes true during the first traversal. The active stack is what makes that immediate decision safe.

Java Memory Considerations

Memory tradeoffs in Java are one of the easiest ways to separate Tarjan from Kosaraju. Tarjan stays on the original adjacency list and avoids building a transposed graph, so there is no second full copy of the edge structure. In return, it keeps more live per-vertex state while DFS is running. Typical storage is an int[] index, an int[] low, a boolean[] onStack, and a Deque<Integer> for the active vertex stack, along with the adjacency list itself and the output collection for components.

On adjacency-list graphs, runtime still stays at O(V + E). Space also stays linear, but the layout is different from Kosaraju’s layout. Tarjan pushes memory toward vertex bookkeeping. Kosaraju pushes memory toward duplicated edge storage after the transpose is built. That difference can stand out on edge-heavy graphs, where a second adjacency structure takes more room than a few primitive arrays.

For the stack container, Deque<Integer> backed by ArrayDeque is the better modern fit in Java. The older Stack class is synchronized and tied to Vector, which adds behavior Tarjan does not need for a normal single-threaded graph traversal. ArrayDeque gives push, pop, and peek directly, which lines up nicely with the active-stack rule.

Recursion depth still deserves a place in the discussion. Tarjan is usually presented recursively because the code mirrors the theory very closely that way. Deep directed graphs can still drive the call stack high enough to throw StackOverflowError in Java. If graph depth is a concern, an iterative DFS translation can keep the same algorithmic logic while moving call-state storage into an explicit frame stack. The trade then moves from JVM call-stack usage to a larger amount of manual bookkeeping in the code.

From a Java-reading angle, Tarjan asks more from the person reading it than Kosaraju does. Finish order and graph transposition are very visible ideas. Discovery indexes, low-link values, and active-stack membership take more patience the first time through. The payoff is that the graph never has to be rebuilt in reversed form, and SCCs are emitted during the same DFS that first discovers the vertices.

Conclusion

Kosaraju and Tarjan solve the same SCC problem, but the internal logic that gets them there is very different. Kosaraju splits the job into finish order first and component collection later on the reversed graph, while Tarjan keeps everything inside one DFS by tracking discovery indexes, low-link values, and the active stack at the exact moment a component closes. Put side by side in Java, that contrast makes the trade easy to see. Kosaraju spends more memory on a second adjacency structure, while Tarjan spends more thought on live traversal state.

1. Java Deque Interface Documentation

2. Java ArrayDeque Class Documentation

3. Java Stack Class Documentation

4. Java List Interface Documentation

5. Java ArrayList Class Documentation

6. Java Arrays Class Documentation

7. Java StackOverflowError Documentation

Share Alexander Obregon's Substack

Spring Boot gives you a current Redis stack through spring-boot-starter-data-redis, so request fingerprinting and short-lived duplicate tracking can stay close to tools people already use every day. RedisTemplate, StringRedisTemplate, TTL-based cache handling, and Caffeine all fit nicely in that process, which makes deduplication and idempotency feel less abstract and more like a question of how a request gets identified, stored for a limited window, and checked before the write happens.

Subscribe now

Request Identity in a Spring Boot Flow

Before a request can be blocked as a duplicate or treated as the same business action, the application has to decide what sameness means. That sounds small at first, but this is where the whole flow gets its meaning. Two HTTP requests can arrive with different headers, different trace ids, or a slightly different JSON field order and still be the same request in business terms. Spring Boot does not decide that for you. Your code does, and that decision needs to happen before any short-lived memory store gets involved.

Deduplication Versus Idempotency

Duplicate requests show up in ordinary traffic for ordinary reasons. Browser form submissions can fire twice. Mobile clients retry after a timeout. Gateways or load balancers can replay a request after a broken connection. From the server side, all of those can look like valid incoming calls, so the application needs a way to tell a fresh request from a repeat.

Deduplication usually means blocking a repeated request inside a small time window. That can be enough when the goal is just to stop accidental double submission. Think about a checkout button tapped twice in quick succession. If the server spots the second request fast enough, it can stop the duplicate before a second write happens.

Idempotency goes further than that. Instead of just saying this one was already seen recently, it treats repeated delivery of the same logical action as one action. That distinction changes the server behavior. A seen marker can block a second database insert, but fuller idempotency usually keeps enough state to connect the retry back to the first result. That way the client does not just get a rejection. It can get the same outcome tied to the first successful request.

Another way to put it is that deduplication is about suppression, while idempotency is about identity. Suppression says do not run that again right now. Identity says this retry belongs to an operation that already happened, so keep the outcome tied to that operation instead of creating a new one. Payment APIs, order creation endpoints, and external callback handlers usually need that second meaning more than the first.

Spring MVC gives you a natural place to read the incoming request details that may define that identity. One common input is an idempotency key sent by the client in a header. That header by itself is not the full story, but it is a strong starting point because it gives the client a stable token for the operation it is retrying.

package com.example.idempotency;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Component;

@Component
public class IdempotencyKeyReader {

    public String readKey(HttpServletRequest request) {
        String value = request.getHeader("Idempotency-Key");
        if (value == null) {
            return "";
        }
        return value.trim();
    }
}

That code only reads a header, but the point is larger than the method itself. The application is pulling out one field that can help name the operation across retries. A client can send the same Idempotency-Key again after a timeout, and the server can treat the retry as tied to the same business action rather than as a brand-new request.

Headers are not enough by themselves for every endpoint. Some routes need business fields in the identity too. A payment retry with the same header but a different amount should not silently count as the same operation. An order submit tied to a different cart or account should not reuse the first request’s identity either. That is why idempotency identity normally comes from a small group of fields rather than one transport detail in isolation.

Building a Stable Fingerprint

Request fingerprinting starts before hashing. Hashing only compresses the identity string you hand to it. If the input changes every time, the digest changes every time too, and duplicate detection falls apart. Stable fingerprinting begins with a canonical view of the request, where the application picks the fields that define the operation, normalizes them, and writes them in a repeatable order.

Good inputs come from the fields that actually define the action. Route, HTTP method, tenant or account id, an external request id, amount, and currency are common choices for a payment-style endpoint. Temporary values do not belong there. Trace ids, current timestamps, random request metadata, or raw JSON text with changing whitespace can turn the same logical action into different fingerprints by accident.

Field normalization keeps harmless formatting differences from changing the identity, while methods are usually folded to uppercase. Currency codes are better compared in one case. Paths can be normalized so doubled slashes do not create a different result. Numeric values need care too. BigDecimal amounts written as 10.0 and 10.00 usually mean the same business value, so both should collapse to the same canonical representation before hashing.

Let’s see what that normalization step looks like in code:

package com.example.idempotency;

import java.math.BigDecimal;
import java.util.Locale;

import org.springframework.stereotype.Component;

@Component
public class FingerprintCanonicalizer {

    public String canonicalize(PaymentRequest request, String method, String path, String idempotencyKey) {
        return String.join("\n",
                normalize(request.tenantId()),
                normalize(request.accountId()),
                normalizeMethod(method),
                normalizePath(path),
                normalize(idempotencyKey),
                normalizeAmount(request.amount()),
                normalizeCurrency(request.currency())
        );
    }

    private String normalize(String value) {
        return value == null ? "" : value.trim();
    }

    private String normalizeMethod(String value) {
        return normalize(value).toUpperCase(Locale.US);
    }

    private String normalizePath(String value) {
        return normalize(value).replaceAll("/+", "/");
    }

    private String normalizeCurrency(String value) {
        return normalize(value).toUpperCase(Locale.US);
    }

    private String normalizeAmount(BigDecimal value) {
        if (value == null) {
            return "";
        }
        return value.stripTrailingZeros().toPlainString();
    }
}

That canonical string is the part worth paying attention to. Newlines are only separators. The real value comes from turning the request into one repeatable text form. If the same logical request comes back after a retry, the canonical text should come out exactly the same. If the client changes a business field that actually changes the operation, the canonical text should change too.

SHA-256 is a good default digest for this job in Java because MessageDigest supports it as a standard algorithm, and UTF-8 gives a stable byte representation for the canonical text. The digest is not replacing your business identity. It is turning that identity into a compact token that is easy to store and compare.

package com.example.idempotency;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;

import org.springframework.stereotype.Component;

@Component
public class RequestFingerprintService {

    public String fingerprint(String canonicalRequest) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(canonicalRequest.getBytes(StandardCharsets.UTF_8));
            return HexFormat.of().formatHex(hash);
        } catch (NoSuchAlgorithmException ex) {
            throw new IllegalStateException("SHA-256 is not available", ex);
        }
    }
}

Notice what this service does not do. It does not read the servlet request directly, it does not pick which fields count, and it does not try to infer business meaning from a raw body. That separation keeps the fingerprinting logic easier to read. One small area of code decides identity. Another turns that identity into a digest.

Request bodies deserve special care here. Raw JSON text is a poor fingerprint source when taken as-is, because field order and spacing can differ across clients without changing the data. Parsing the body into a request object and then selecting the business fields gives a more stable result than hashing raw text. Spring Boot already maps JSON to Java records or classes through @RequestBody, which makes this step fit naturally into a controller flow.

package com.example.idempotency;

import java.math.BigDecimal;

public record PaymentRequest(
        String tenantId,
        String accountId,
        BigDecimal amount,
        String currency
) {}

A controller can then assemble the identity from the mapped request plus request metadata that actually belongs in the fingerprint:

package com.example.idempotency;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/payments")
public class PaymentController {

    private final IdempotencyKeyReader keyReader;
    private final FingerprintCanonicalizer canonicalizer;
    private final RequestFingerprintService fingerprintService;

    public PaymentController(
            IdempotencyKeyReader keyReader,
            FingerprintCanonicalizer canonicalizer,
            RequestFingerprintService fingerprintService
    ) {
        this.keyReader = keyReader;
        this.canonicalizer = canonicalizer;
        this.fingerprintService = fingerprintService;
    }

    @PostMapping
    public ResponseEntity<String> createPayment(
            @RequestBody PaymentRequest request,
            HttpServletRequest httpRequest
    ) {
        String idempotencyKey = keyReader.readKey(httpRequest);

        String canonical = canonicalizer.canonicalize(
                request,
                httpRequest.getMethod(),
                httpRequest.getRequestURI(),
                idempotencyKey
        );

        String fingerprint = fingerprintService.fingerprint(canonical);

        return ResponseEntity.ok(fingerprint);
    }
}

That controller is not doing duplicate checks yet. It is doing the earlier job, which is giving the request an identity that survives retries. Same tenant, same account, same route, same operation id, same amount, same currency, same method should lead to the same fingerprint. Different business meaning should lead to a different one.

Good request identity starts with plain questions. What fields make this operation the same operation on a retry. Which transport details can change without changing the business action. Which values need normalization before comparison. After those answers are settled, hashing becomes the compact final step rather than the place where the logic is supposed to come from.

Time Bound Request Memory

Duplicate checks need some place to remember what was seen a moment ago. After the fingerprint has been built, the next question is where that fingerprint should live and how long it should stay there. Spring Boot gives you room for both shared storage through Redis and process-local storage through Caffeine, and the right pick depends on scope, retry behavior, and how exact the expiration window needs to be. Redis expiration is attached to keys, Spring Data Redis exposes write calls that can claim a key with a timeout in one step, and Spring Boot can auto-configure a CaffeineCacheManager when Caffeine is present.

Redis String Keys with TTL

Shared request memory across several app instances is usually easiest to reason through when each fingerprint gets its own Redis string key. That model maps well to duplicate detection because the request either claims the fingerprint first or finds that someone else already claimed it. Redis SET supports NX so the write only happens when the key does not exist, and the same command also accepts expiration options on that key. Spring Data Redis mirrors that form through ValueOperations.setIfAbsent(key, value, Duration timeout), which writes only on absence and applies the timeout in the same call.

That flow keeps the decision generally small and direct. Fresh fingerprints create short-lived Redis keys. Retries that arrive during the active TTL window see the existing key and fail the claim.Nothing about that requires a large object model. Marker values like 1, a request id, or a short status token are enough for the first gate, and fuller result state can live elsewhere if the endpoint needs reply replay instead of a plain duplicate rejection. Redis TTL can then report how much life the key still has if you need visibility during debugging or metrics gathering.

Now, let’s look at what that write step can look like in Spring code:

package com.example.idempotency;

import java.time.Duration;

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

@Service
public class RedisFingerprintWindow {

    private final StringRedisTemplate redisTemplate;

    public RedisFingerprintWindow(StringRedisTemplate redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    public boolean claim(String fingerprint, Duration ttl) {
        String redisKey = "idem:" + fingerprint;
        Boolean created = redisTemplate.opsForValue()
                .setIfAbsent(redisKey, "1", ttl);

        return Boolean.TRUE.equals(created);
    }
}

claim returns true only for the first caller that writes the fingerprint during that TTL window. Later retries hit the same Redis key and get false, which is exactly the branch a duplicate check needs.

Fresh code should stay with SET plus expiration options rather than older string commands that baked expiration into a separate command name. Redis marks SETEX as deprecated and points new code toward SET with EX. That lines up well with Spring Data Redis, because setIfAbsent with a Duration already follows the newer direction instead of splitting the write into a plain set followed by a second expire call. Fixed TTL also needs to be kept separate from read-refreshed lifetime. Redis expiration is TTL by default, which means the clock starts when the key is written. Spring Data Redis cache support can emulate a time-to-idle style read refresh through GETEX, and that depends on Redis GETEX support. Duplicate request memory usually fits fixed TTL better than read-refreshed lifetime, because a retry should not keep extending the duplicate block unless you chose that behavior on purpose.

Redis Set Buckets by Time Slice

Sets can still do duplicate tracking, but the storage shape changes a little. Redis SADD adds a member to a set and ignores a repeat add for the same member, while SISMEMBER checks membership. Those commands are useful for fingerprint tracking, yet expiration in Redis belongs to the whole key, not to one member inside the key. EXPIRE sets a timeout on the key itself, so a plain set does not give every fingerprint its own private countdown.

That behavior leads to bucketed sets. Instead of storing every fingerprint in one long-lived set, the application writes each fingerprint into a bucket key tied to a short time slice such as a minute. The bucket key can then expire as a unit after the full detection window has passed. A request arriving at 9:14 could be written to idem:bucket:2026-03-30T09:14, while a retry check looks at the current bucket and perhaps the immediately previous bucket if the window spans more than one slice. Expiration stays cheap because Redis deletes the whole bucket key when its timeout runs out. SADD and SISMEMBER remain useful, but the time window belongs to the bucket, not to the individual fingerprint.

Code for a bucket name helper is short, though the naming choice affects how broad the window becomes near the edge of a minute:

package com.example.idempotency;

import java.time.Instant;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;

import org.springframework.stereotype.Component;

@Component
public class FingerprintBucketNamer {

    private static final DateTimeFormatter MINUTE_FORMAT =
            DateTimeFormatter.ofPattern("yyyyMMddHHmm").withZone(ZoneOffset.UTC);

    public String currentBucket(Instant now) {
        return "idem:bucket:" + MINUTE_FORMAT.format(now);
    }
}

That minute bucket name can then be paired with a set add and a key expiration:

package com.example.idempotency;

import java.time.Duration;
import java.time.Instant;

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

@Service
public class RedisBucketWindow {

    private final StringRedisTemplate redisTemplate;
    private final FingerprintBucketNamer bucketNamer;

    public RedisBucketWindow(StringRedisTemplate redisTemplate,
                             FingerprintBucketNamer bucketNamer) {
        this.redisTemplate = redisTemplate;
        this.bucketNamer = bucketNamer;
    }

    public boolean markSeen(String fingerprint, Instant now, Duration bucketTtl) {
        String bucketKey = bucketNamer.currentBucket(now);
        Long added = redisTemplate.opsForSet().add(bucketKey, fingerprint);
        redisTemplate.expire(bucketKey, bucketTtl);
        return added != null && added > 0;
    }
}

That write style is good for grouped windows and bulk cleanup, though it is less exact than a per-fingerprint string key. A fingerprint written near the start of a minute and one written near the end of the same minute share the same bucket lifetime unless you split the time slices more finely. Bucketed sets fit best when a short approximate window is fine and grouped expiry is acceptable.

Local Memory with Caffeine

Process-local duplicate memory is a good fit when traffic is routed to one JVM or when the duplicate window only needs to cover repeated calls that are likely to hit the same node. Spring Boot can auto-configure a CaffeineCacheManager when Caffeine is present, and Caffeine supports write-based expiration through expireAfterWrite. Caffeine also exposes a thread-safe map view through asMap(), which gives direct access to map methods such as putIfAbsent. That local path removes the Redis round trip and keeps duplicate memory inside the process. It also changes the scope. One instance only knows what that instance has seen. If two retries hit different pods, node-local memory has no shared view, so both requests can still pass their local checks. That tradeoff makes local memory useful for single-instance deployments, local development, scheduled jobs pinned to one node, or routes where near-term suppression on the same JVM is enough. Spring Boot’s cache docs and Caffeine’s own expiration support make that model very natural to build.

Small cache beans can hold that short-lived membership map:

package com.example.idempotency;

import java.time.Duration;
import java.time.Instant;

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class LocalFingerprintCacheConfig {

    @Bean
    Cache<String, Instant> fingerprintCache() {
        return Caffeine.newBuilder()
                .expireAfterWrite(Duration.ofMinutes(10))
                .maximumSize(200_000)
                .build();
    }
}

That cache can then back a first-write-wins check through the map view:

package com.example.idempotency;

import java.time.Instant;

import com.github.benmanes.caffeine.cache.Cache;
import org.springframework.stereotype.Service;

@Service
public class LocalFingerprintWindow {

    private final Cache<String, Instant> cache;

    public LocalFingerprintWindow(Cache<String, Instant> cache) {
        this.cache = cache;
    }

    public boolean claim(String fingerprint) {
        return cache.asMap().putIfAbsent(fingerprint, Instant.now()) == null;
    }
}

putIfAbsent gives a compact duplicate gate. The first caller inserts the timestamp marker. Later callers during the active write-expiration window see the prior value and fail the claim. The value could be a timestamp, a request id, or a tiny marker object. The actual duplicate memory lives in the cache entry itself, while expireAfterWrite controls how long that memory stays alive. Caffeine removes entries after a fixed duration from creation or replacement when write-based expiration is in play, which fits a short duplicate window well.

Collision Thinking for Window Choice

Hash collisions belong in the conversation, but they need to stay in proportion. The digest acts as a compact stand-in for the canonical request, so the application trusts the canonical input first and the hash second. With SHA-256, collision risk is tiny for ordinary request dedup windows, yet the digest is still only a compressed token for the request identity built earlier. Trouble usually starts much sooner with poor field selection or weak normalization than with the digest family itself.

High-stakes endpoints usually need more than a seen bit. Just a marker can stop a repeated write, but a saved status code, prior response id, or business reference gives retries something stable to reconnect to. That does not mean the first duplicate gate has to turn heavy. Payment or order flows usually need enough stored state to tell a retry what already happened, not just that it showed up late.

The time window should come from business timing rather than from the storage engine. Form-submit guards may need only a few seconds, while mobile retry logic may need a minute or two. Payment processing or outbound callback handling can need a much longer lifetime. Redis string entries with TTL fit exact per-fingerprint windows well. Bucketed Redis sets fit grouped windows with full-bucket expiration. Local Caffeine memory fits JVM-local suppression. Those options live in the same broad topic, but they do not behave the same way.

Redis also has a native option when you want one shared collection scored by time instead of a plain set or a string per fingerprint. Sorted sets accept members through ZADD, and score-based range reads now belong to ZRANGE with the BYSCORE option. ZRANGEBYSCORE is deprecated, so fresh code should stay with ZRANGE BYSCORE when score-range reads are needed. That route belongs to a different storage model than the ones above, but it still helps frame where current Redis points time-scored membership logic.

Conclusion

Deduplication and idempotency come down to a few moving parts that have to be in the right order. First the request becomes a stable fingerprint, then that fingerprint is checked against short-lived memory, and from there the write either moves forward or reconnects to a stored result. Get the request identity right and pair it with the right expiration window, and the behavior stays predictable from the first retry to the last one.

1. Spring Boot Caching Reference

2. Spring Data Redis Reference

3. Redis SET Command Reference

4. Redis EXPIRE Command Reference

5. Redis SADD Command Reference

6. Redis ZADD Command Reference

7. Java MessageDigest Documentation

8. Caffeine Eviction Documentation

Share Alexander Obregon's Substack

For max flow problems, Dinic’s algorithm takes a directed graph with capacities on its edges and pushes as much flow as possible from the source to the sink without going past those limits. It does this in phases. BFS builds a level graph from the current residual graph, then DFS sends flow through that layered graph until no source to sink route remains in it. Repeating those BFS and DFS passes is what makes Dinic faster than one-route-at-a-time methods and gives it the classic O(V^2E) bound in the standard adjacency-list form.

Subscribe now

How Dinic Starts a Phase

Every phase begins from the current state of flow, not from the original graph as it first appeared. That idea sets up the whole method. Early pushes may have filled part of an edge, opened room in a reverse direction, or cut off a route that looked open a moment ago. Dinic starts fresh by reading that updated state and building a layered view of what can still be reached from the source. Before that layered view can make sense, the graph needs a way to represent leftover room on forward edges and returned room on backward edges. That is why residual capacity and reverse edges come first.

Residual Capacity

Leftover room on an edge is what Dinic actually cares about at the start of a phase. If an edge can carry 10 units and 6 units are already flowing through it, only 4 units remain available in the forward direction. That remaining amount is the residual capacity. BFS does not walk through every original edge. It only walks through edges whose residual capacity is greater than 0, because those are the only edges that can still carry more flow from the source toward the sink.

That concept sounds small, but it changes the whole search. Original capacities tell you what the graph allowed at the start. Residual capacities tell you what the graph allows right now after earlier pushes changed it. If Dinic ignored that difference, BFS would keep acting like full edges were still open, and the level graph would be built from bad information.

Java code usually stores both the capacity and the current flow directly on the edge object. Residual capacity can then be computed with one subtraction:

private static final class Edge {
    int to;
    long capacity;
    long flow;

    Edge(int to, long capacity) {
        this.to = to;
        this.capacity = capacity;
        this.flow = 0L;
    }

    long residualCapacity() {
        return capacity - flow;
    }
}

That residualCapacity() method is what the search reads, not the raw capacity field by itself. If flow changes after a push, the next phase sees the new state right away without rebuilding a separate data structure.

Small number examples make this much easier to to see in practice. Say an edge from node 2 to node 5 has capacity 9, like this:

Edge edge = new Edge(5, 9L);

System.out.println(edge.residualCapacity()); // 9

edge.flow = 4L;
System.out.println(edge.residualCapacity()); // 5

edge.flow = 9L;
System.out.println(edge.residualCapacity()); // 0

At 0 residual capacity, that edge is fully saturated in the forward direction, so BFS should not walk across it while building the next level graph. That does not mean the connection is gone forever. It only means there is no forward room left at that moment.

Phase construction depends on this rule. BFS starts from the source and visits neighbors only when the edge to that neighbor still has positive residual room. If the sink cannot be reached through such edges, the algorithm is done. If the sink is reachable, the levels written by BFS form the layered view for that phase. None of that can be trusted unless residual capacity reflects the current flow state exactly.

Reverse Edges

Flow algorithms need a way to back out part of an earlier choice. Sending flow forward should never trap the graph in a bad decision. Reverse edges solve that problem.

At the start, a reverse edge usually has capacity 0. That sounds odd until flow begins moving. Suppose 6 units travel from u to v. At that point, the graph should allow up to 6 units to move back from v to u if a later phase finds a better route. That backward room is represented by the reverse edge. Without it, the algorithm could push flow forward but would have no formal way to reroute that flow later.

Most Java implementations add forward and reverse edges as a pair, and each one stores the index of its partner inside the other node’s adjacency list:

private static final class Edge {
    int to;
    int reverseIndex;
    long capacity;
    long flow;

    Edge(int to, int reverseIndex, long capacity) {
        this.to = to;
        this.reverseIndex = reverseIndex;
        this.capacity = capacity;
        this.flow = 0L;
    }

    long residualCapacity() {
        return capacity - flow;
    }
}

@SuppressWarnings("unchecked")
private final List<Edge>[] graph = new ArrayList[6];

{
    for (int i = 0; i < graph.length; i++) {
        graph[i] = new ArrayList<>();
    }
}

public void addEdge(int from, int to, long capacity) {
    Edge forward = new Edge(to, graph[to].size(), capacity);
    Edge reverse = new Edge(from, graph[from].size(), 0L);

    graph[from].add(forward);
    graph[to].add(reverse);
}

That pairing matters because flow updates always affect both directions. If a push later sends 4 units through the forward edge, the reverse edge needs to record that same amount in the opposite direction.

Edge forward = graph[1].get(0);
Edge reverse = graph[forward.to].get(forward.reverseIndex);

long pushed = 4L;
forward.flow += pushed;
reverse.flow -= pushed;

After those two lines run, the forward edge has less room left, and the reverse edge gains room for cancellation. The reverse edge can still keep capacity 0, because its residual room comes from the negative flow value. If reverse.flow becomes -4, then reverse.capacity - reverse.flow becomes 0 - (-4), which is 4.

This paired update is the reason reverse edges are built in from the start instead of being invented later as a side structure. Dinic needs a residual graph that changes immediately as flow changes. Forward edges record what more can be sent in the original direction. Reverse edges record what can be taken back and redirected. At the start of a phase, BFS reads both kinds of edges through the same residual capacity rule. That gives the search an accurate picture of the current graph state, including routes created by canceling part of earlier flow. Without reverse edges, the phase would be built from a graph that could only move forward and could never repair an earlier routing choice.

Level Graphs

After residual capacities and reverse edges are in place, BFS can build the level graph. This is the part that gives Dinic its structure. Starting from the source, BFS assigns level 0 to the source itself, level 1 to every reachable neighbor through a positive-residual edge, level 2 to the next layer, and so on until no more vertices can be reached.

Those level values are not decoration. They are the rulebook for the current phase. Only edges that go from level d to level d + 1 belong to the level graph. Edges that stay on the same level are ignored for that phase. Edges that go backward to an earlier level are ignored too. That restriction keeps the search moving through the shortest residual-distance layers from the source.

Another way to put it is that the BFS builds a filtered view of the residual graph. The original residual graph may have cycles, sideways connections, and backward links created by reverse edges. The level graph strips that down to a directed layered structure based on current reachability depth. That is what keeps Dinic from wandering through long detours during a phase.

Let’s see what a compact BFS in Java usually looks like:

private int[] level;

private boolean bfs(int source, int sink) {
    Arrays.fill(level, -1);
    ArrayDeque<Integer> queue = new ArrayDeque<>();

    level[source] = 0;
    queue.add(source);

    while (!queue.isEmpty()) {
        int node = queue.poll();

        for (Edge edge : graph[node]) {
            if (edge.residualCapacity() > 0 && level[edge.to] == -1) {
                level[edge.to] = level[node] + 1;
                queue.add(edge.to);
            }
        }
    }

    return level[sink] != -1;
}

Several things in that loop are worth paying attention to. The level array starts at -1 so unreached vertices are easy to spot. The queue gives BFS its layer-by-layer order. Most importantly, the condition checks both positive residual capacity and an unreached destination. If an edge has no room left, BFS acts as if that edge does not exist for this phase.

After BFS finishes, the level array tells you which edges belong to the level graph. That test is very small:

boolean inLevelGraph(Edge edge, int from) {
    return edge.residualCapacity() > 0 && level[edge.to] == level[from] + 1;
}

An edge passes that test only if it has room left and moves exactly one layer farther from the source. If a node at level 2 points to a node at level 4, BFS did discover both vertices, but that edge still does not belong to the level graph because it skips a layer. If a reverse edge points from level 3 back to level 2, that edge is part of the residual graph but not part of the level graph for the current phase.

This layered restriction is what limits search depth. If the sink is first reached at level 5, the phase is built around routes that move through those shortest available layers. The graph may still contain longer residual routes, but Dinic does not let the current phase chase them. Later phases can revisit the graph after residual capacities change and a new BFS writes new levels.

Sink reachability is the final check that makes the phase meaningful. If level[sink] stays -1, the source can no longer reach the sink through any positive-residual route. That means no new phase can be formed, so the current flow is already maximum. If the sink does get a level, the algorithm has a fresh layered graph ready for the next stage of flow pushes.

How Flow Moves Forward

After the level graph is built, Dinic turns that layered view into actual flow updates. This part gives the method much of its speed. Instead of rebuilding the search after every successful source to sink route, it keeps pushing through the same layered graph until that phase has no more source to sink route left inside it. DFS sends the flow, a pointer array cuts repeated scans, and the outer control loop keeps the phase moving in the right order.

Blocking Flow

Within a BFS phase, Dinic does not stop after the first successful source to sink route. It keeps sending flow through the same level graph until every remaining source to sink route is cut off by at least one saturated edge. That state is called a blocking flow.

Put a little more plainly, the layered graph still exists, but no full source to sink route inside it can carry added flow. At that point, staying in the current phase does not help. DFS would only hit full edges or dead ends, so the algorithm returns to BFS and rebuilds the levels from the updated residual graph. The next phase then starts from a fresh layered view, not from the one that has already been drained as far as it can go.

This phase-by-phase structure is a big part of why Dinic usually runs faster than older methods that rebuild after every single successful route. One BFS pass is reused for a whole batch of flow updates inside the same level graph. That reuse cuts repeated search cost, which helps explain the standard O(V^2E) time bound for the adjacency-list form.

Take a current level graph where the source can still reach the sink through three valid routes. DFS may fill an edge on the first route, send flow through a different branch on the next pass, then saturate a shared edge that cuts off the last route still open in that phase. When no complete route remains inside that layered graph, the blocking flow has been reached. BFS can then rebuild levels from the new residual state and start the next phase from there.

DFS Pushes Units

Flow moves through the level graph by recursive DFS calls, but this DFS does more than mark reachability. Every call carries a number that says how much flow can still pass through the partial route seen so far. At the source, that value starts very large. As recursion follows edges, it drops to the smallest residual capacity seen along the current route. That running minimum becomes the bottleneck for the whole push.

This code makes the base cases easy to see:

private long dfs(int node, int sink, long pushed) {
    if (pushed == 0L) {
        return 0L;
    }
    if (node == sink) {
        return pushed;
    }

    return 0L;
}

The first base case stops recursion when nothing useful can be sent. The second returns the amount that reached the sink. That returned value is the bottleneck collected along the route from source to sink in the current level graph.

As recursion examines an outgoing edge, the amount to send is narrowed by the smaller of the carried value and that edge’s residual capacity:

long nextPushed = Math.min(pushed, edge.residualCapacity());
long sent = dfs(edge.to, sink, nextPushed);

If the carried value is 8 and the next edge has only 3 units left, the rest of that route can carry at most 3. If the edge has more room than the carried value, the bottleneck stays where it already was. That repeated narrowing is what makes the return value meaningful when the sink is finally reached.

Dead ends are part of the normal control flow here. If recursion reaches a vertex where no valid outgoing edge can carry flow farther toward the sink in the current phase, the call returns 0. That 0 does not end the whole phase. It only tells the caller that this branch cannot send anything right now, so DFS backs up and tries the next outgoing edge from the earlier vertex.

When a recursive call does reach the sink with a positive amount, that value moves back up through the call stack and updates every edge on that successful route:

edge.flow += sent;
Edge reverse = graph[edge.to].get(edge.reverseIndex);
reverse.flow -= sent;
return sent;

Forward flow goes up, and the paired reverse edge moves the same amount in the negative direction. That negative value is what gives the residual graph room to send flow back later if a later phase finds a better routing choice.

For space, the recursion stack can grow to O(V) in the worst case, because a source to sink route in the level graph can include up to V - 1 edges. Time for one DFS call depends on how far it travels before it either reaches the sink or runs out of useful edges, which is why the pointer array in the next subsection makes such a difference.

Current Edge Pointers

Repeated scanning can quietly waste time during DFS. If a vertex has several outgoing edges and the first few have already been proved useless for the current phase, restarting from index 0 every time recursion returns to that vertex would force the algorithm to recheck the same edges again and again. Dinic avoids that with a current-edge pointer for every vertex. Java code usually stores those positions in an int[] named nextEdge or ptr. That array records the first outgoing edge that still deserves attention in the current BFS phase. Any earlier edge has already been rejected for the wrong level, found full, or fully drained for the current layered graph.

That loop usually takes this form:

for (; nextEdge[node] < graph[node].size(); nextEdge[node]++) {
    Edge edge = graph[node].get(nextEdge[node]);

    if (level[edge.to] != level[node] + 1 || edge.residualCapacity() <= 0) {
        continue;
    }

    long sent = dfs(edge.to, sink, Math.min(pushed, edge.residualCapacity()));
    if (sent == 0L) {
        continue;
    }

    edge.flow += sent;
    Edge reverse = graph[edge.to].get(edge.reverseIndex);
    reverse.flow -= sent;
    return sent;
}

That loop does more than scan adjacency lists. It also stores progress inside the current phase. If recursion later returns to the same vertex, the scan resumes from the saved index instead of going back to the start of the adjacency list. That cuts repeated checks and keeps the blocking-flow search far more efficient.

This is part of why finding one blocking flow in the adjacency-list version is usually analyzed as O(VE). Without the pointer array, the same outgoing edges could be revisited far too repeatedly during the same phase. With the pointer array, edge scans stay much more controlled.

Fresh BFS levels mean fresh scanning positions, so the pointer array must be reset at the start of every new phase. Edges that were useless in the old level graph may become valid in the next one after flow values change.

Java Implementation

Putting these pieces into Java comes down to connecting DFS with the outer loop that alternates between BFS phases and repeated pushes. The fragment below focuses on the control flow after the levels already exist.

The full flow-update loop reads like this:

private long dfs(int node, int sink, long pushed) {
    if (pushed == 0L) {
        return 0L;
    }
    if (node == sink) {
        return pushed;
    }

    for (; nextEdge[node] < graph[node].size(); nextEdge[node]++) {
        Edge edge = graph[node].get(nextEdge[node]);

        if (level[edge.to] != level[node] + 1 || edge.residualCapacity() <= 0) {
            continue;
        }

        long sent = dfs(edge.to, sink, Math.min(pushed, edge.residualCapacity()));
        if (sent == 0L) {
            continue;
        }

        edge.flow += sent;
        Edge reverse = graph[edge.to].get(edge.reverseIndex);
        reverse.flow -= sent;
        return sent;
    }

    return 0L;
}

public long maxFlow(int source, int sink) {
    long totalFlow = 0L;

    while (bfs(source, sink)) {
        Arrays.fill(nextEdge, 0);

        long sent;
        do {
            sent = dfs(source, sink, Long.MAX_VALUE);
            totalFlow += sent;
        } while (sent != 0L);
    }

    return totalFlow;
}

The while (bfs(source, sink)) loop means the algorithm keeps forming new phases as long as the sink is still reachable in the residual graph. Inside that phase, Arrays.fill(nextEdge, 0) resets the per-vertex scan positions so DFS can start scanning the new level graph from the front. The do and while loop then keeps calling dfs until it returns 0, which means the current phase has reached a blocking flow and cannot send any more source to sink flow through its current layered graph.

This outer structure is fairly compact, but the control flow is very deliberate. BFS forms the layered graph. Repeated DFS calls drain that graph as far as it can go. A 0 return marks the end of the phase. BFS then either builds the next level graph or reports that the sink can no longer be reached.

For runtime, the usual bound for this adjacency-list form is O(V^2E). Space stays at O(V + E) for the graph storage, level array, and pointer array, with recursion adding up to O(V) stack depth during DFS. Those bounds fit the way Dinic spends more of its time pushing flow through one BFS phase before paying for the next search rebuild.

Conclusion

Dinic’s max flow algorithm gets its speed from how it organizes the search. BFS builds a level graph from the current residual graph, DFS pushes flow only through edges that move forward by level, and a phase ends only after that layered graph has been drained into a blocking flow. After that, the residual graph is read again, new levels are assigned, and the cycle repeats until the sink can no longer be reached. That repeated rebuild of levels followed by focused flow pushes is what gives Dinic its O(V^2E) bound in the standard adjacency-list form.

1. Java ArrayDeque Documentation

2. Java Arrays Documentation

3. Java List Documentation

4. CP-Algorithms on Dinic’s Algorithm

5. Princeton Network Flow Notes

Share Alexander Obregon's Substack

Expiration starts as a timing question, because every entry has a deadline and the application needs some way to notice that deadline without spinning up a separate scheduled action for every item. Spring Boot gives you caching support and scheduling tools, but the rules for entry expiry still live in the cache code itself, which is why a time wheel fits so well here. Instead of scanning the whole cache, it groups deadlines into buckets and moves through those buckets on a fixed tick, so the expiration cost stays tied to the current slot. Spring Boot cache support also sits on top of provider-backed stores, while Spring scheduling centers on TaskScheduler, so a bucketed expiration model fits naturally with in-memory caches, delayed cleanup, and other time-based cleanup flows.

Subscribe now

Why a Time Wheel Even Fits TTL Expiration

Managing expiration gets harder as the number of live entries climbs, not because removal is hard by itself, but because the cache has to keep track of a growing set of deadlines while still staying fast on reads and writes. Every TTL value points to a future moment, and a busy cache can hold thousands of those moments at the same time. When that count rises, the cost no longer comes from deleting expired data alone. Scheduler activity, queue churn, memory use, and repeated deadline bookkeeping all start to take a larger share of the total load.

Time wheels fit that problem space well because they swap a large collection of separate timers for a fixed ring of time slots. Expiration records are placed into buckets tied to future ticks, and the scheduler advances through those buckets at a regular interval. Instead of checking the whole cache or keeping an individual scheduled removal for every entry, the expiration pass stays focused on the current slot. That keeps the timing side of TTL cleanup tied to the small slice of entries that are due near the current tick.

Per Entry Timers Get Expensive Fast

Giving every cache entry its own timer can feel appealing early on because the logic reads almost like the TTL rule itself. Put a value in the map, schedule its removal, and let the scheduler handle the rest. That model starts to get heavy as entry counts rise, though, because every cached value now carries timer registration, scheduler queue state, cancellation pressure, and callback overhead along with the data itself.

Short TTL caches bring that issue into view quickly. Session tokens, short-lived API responses, and temporary lookup data can turn over fast enough that entries are added, replaced, and removed in large waves. If every write schedules its own future removal, the scheduler now has to track not only deadlines that will still be relevant later, but also deadlines tied to entries that may be overwritten long before their timer fires. The cache is then spending more CPU time and memory on timer handling than the removal step itself.

Early code can look like this:

import java.util.Map;
import java.util.concurrent.*;

public class PerEntryTimerCache {
    private final Map<String, String> values = new ConcurrentHashMap<>();
    private final ScheduledExecutorService scheduler =
            Executors.newScheduledThreadPool(4);

    public void put(String key, String value, long ttlSeconds) {
        values.put(key, value);

        scheduler.schedule(() -> values.remove(key), ttlSeconds, TimeUnit.SECONDS);
    }

    public String get(String key) {
        return values.get(key);
    }
}

Code like that gets the TTL idea in a nice visual, but it also leaves a hole behind. If the same key is written again before the prior timer fires, the earlier scheduled removal is still waiting in the scheduler queue. At that point, the cache needs some way to find and cancel the stale removal before it deletes fresh data by mistake.

More bookkeeping follows from that:

import java.util.Map;
import java.util.concurrent.*;

public class CancelingTimerCache {
    private final Map<String, String> values = new ConcurrentHashMap<>();
    private final Map<String, ScheduledFuture<?>> removals = new ConcurrentHashMap<>();
    private final ScheduledExecutorService scheduler =
            Executors.newScheduledThreadPool(4);

    public void put(String key, String value, long ttlSeconds) {
        values.put(key, value);

        ScheduledFuture<?> oldFuture = removals.remove(key);
        if (oldFuture != null) {
            oldFuture.cancel(false);
        }

        ScheduledFuture<?> future = scheduler.schedule(() -> {
            values.remove(key);
            removals.remove(key);
        }, ttlSeconds, TimeUnit.SECONDS);

        removals.put(key, future);
    }

    public String get(String key) {
        return values.get(key);
    }
}

Now every write does more than store a value and record a deadline. It has to look up prior scheduling state, cancel the older future if one exists, register a replacement, and keep that future around until it fires or gets replaced again. Under a heavy rewrite rate, that extra bookkeeping can become one of the larger moving parts in the cache.

Timing precision also needs a little perspective here, cache expiration usually does not depend on exact wall-clock timing down to the last tiny unit. In most TTL caches, removing an entry at the next suitable tick is good enough. That opens the door to a structure that spends less time managing separate timers and more time focusing on groups of entries that are due around the same moment.

Time wheels fit nicely into that gap. Instead of scheduling a separate future for every key, they place expiration records into shared buckets. The scheduler then advances through those buckets on a fixed interval, which keeps timer bookkeeping from growing in lockstep with the number of live entries.

Buckets, Ticks, Round Trips

Ring-based timing starts with a fixed number of slots arranged in a circle. Every slot stands for one tick interval, such as one second or 250 milliseconds. New expiration records are placed into the slot that matches how far away their deadline is from the current position on the wheel. As the clock moves forward, the wheel advances slot by slot and checks only the entries stored in the slot it has just reached. Placement comes from very small arithmetic. If the wheel is at slot 10, the delay is 5 ticks, and the wheel size is 60, the expiration record goes into slot 15. If the current position is near the end of the ring, the slot index wraps back to the beginning.

Small helper methods make the math easier to follow visually, like this one:

public class WheelMath {
    public static int slotIndex(long currentTick, long delayTicks, int wheelSize) {
        return (int) ((currentTick + delayTicks) % wheelSize);
    }

    public static void main(String[] args) {
        long currentTick = 10;
        long delayTicks = 5;
        int wheelSize = 60;

        System.out.println(slotIndex(currentTick, delayTicks, wheelSize)); // 15
    }
}

That handles short delays well, but longer TTL values need one more piece. If an entry has to wait longer than a full pass around the wheel, the slot number will repeat. The wheel handles that by storing a round count with the record. The slot tells the wheel where to look, and the round count tells it how many full trips still have to pass before removal is allowed.

Round counts can be calculated like this:

public class WheelRounds {
    public static long rounds(long delayTicks, int wheelSize) {
        return (delayTicks - 1) / wheelSize;
    }

    public static void main(String[] args) {
        long delayTicks = 135;
        int wheelSize = 60;

        System.out.println(rounds(delayTicks, wheelSize)); // 2
    }
}

With a 60-slot wheel, a delay of 135 ticks points to a repeated slot. The first return to that slot does not expire the entry. The second return does not either. The later visit after those two full trips is the point where the record becomes due. That lets a compact wheel represent deadlines that reach much farther into the future without growing the ring itself.

People usually consider wheel movement as O(1) per tick, and the reason is narrow but useful. Advancing from one slot to the next does not require a scan through every timer stored in memory. The pointer moves to the next slot in constant time, and the scheduler touches only the bucket tied to that tick. If the current bucket is empty, the pass is very cheap. If the current bucket is crowded, the cost comes from that bucket alone instead of the full timer population.

Late wakeups deserve some attention as well. A scheduler does not always run at the exact intended instant. JVM pauses, CPU pressure, or a slow expiration callback can delay the next tick. If the wheel assumes the scheduler was perfectly on time and only checks the slot directly in front of it, entries can remain in the cache after their deadline has already passed.

Storing the absolute deadline in tick form gives the expiration pass a firmer answer. The wheel still uses slot placement to know where a record belongs, but the deadline value tells it if the entry is actually due when the bucket is processed.

This small block handles that check:

public class ExpirationCheck {
    static boolean isExpired(long currentTick, long deadlineTick) {
        return currentTick >= deadlineTick;
    }

    public static void main(String[] args) {
        long deadlineTick = 120;
        long currentTick = 123;

        System.out.println(isExpired(currentTick, deadlineTick)); // true
    }
}

Late processing then becomes much less risky. If the wheel wakes after the intended tick, it can compare the current tick against recorded deadlines and remove entries whose expiry moment has already passed. Slot position still matters, but absolute deadline tracking gives the final answer when timing drifts.

Grouped timing is the reason a time wheel fits TTL expiration so well. Entries with nearby deadlines travel through the same bucket instead of forcing the scheduler to manage separate removal futures for every key. That keeps expiration focused on the current window of time and avoids turning the scheduler into the busiest part of the cache.

Building It in Spring Boot

Spring Boot already gives you two pieces that line up well with a wheel-based TTL cache. The cache abstraction gives application code a common way to read and write cached data, while Spring scheduling gives you a recurring clock through TaskScheduler. The abstraction does not own the storage engine or the expiry engine by itself, and if you do not bring in a separate cache library, Spring Boot falls back to an in-memory concurrent-map based provider. That leaves room for a wheel-based TTL cache when you want in-process expiration tied to your own data structure rather than to provider-specific expiry behavior. Putting those pieces side by side helps make it all make sense. Spring handles recurring execution, your cache holds live values, and the wheel stores future expiration records. That keeps the scheduler focused on time and keeps the cache focused on data. Annotation-based scheduling on its own does not build bucket queues, store deadline ticks, or deal with overwritten entries, so those details still belong inside the cache class.

Scheduling the Tick in Current Spring Boot

Current Spring scheduling centers on TaskScheduler, and the current API favors Instant and Duration methods for fixed-rate and fixed-delay scheduling. Older overloads that take Date and long values are deprecated in Spring Framework 6, so a time wheel fits best with Duration-based scheduling from the start. ThreadPoolTaskScheduler remains Spring’s traditional scheduler for recurring timing like this, and its contract also points out that scheduled callbacks run on the scheduler thread or threads themselves rather than on a separate execution layer.

That changes how the tick loop should be written. Bucket selection, map lookups, version checks, and queue moves fit well inside the recurring callback. Slow database calls, network calls, and heavier follow-up logic do not. If the wheel tick blocks for too long, later ticks can drift, which leaves expired records around longer than planned. Pool size affects behavior too. A single scheduler thread keeps tick order very predictable for one wheel, while a larger pool only makes sense when separate scheduled jobs should not wait behind the wheel.

Take this scheduler configuration for example:

package com.example.ttlwheel;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;

@Configuration
class WheelSchedulerConfig {

    @Bean
    ThreadPoolTaskScheduler ttlWheelScheduler() {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(1);
        scheduler.setThreadNamePrefix("ttl-wheel-");
        scheduler.setRemoveOnCancelPolicy(true);
        scheduler.setErrorHandler(ex -> System.err.println("Wheel tick failed: " + ex.getMessage()));
        return scheduler;
    }
}

setRemoveOnCancelPolicy(true) helps because the scheduler can drop canceled entries from the underlying queue instead of leaving canceled handles around until their trigger time passes. That does not replace stale-record protection inside the wheel, but it does keep the scheduler side lighter when the recurring tick is stopped during shutdown or replaced in tests. ThreadPoolTaskScheduler also exposes the underlying ScheduledExecutorService and ScheduledThreadPoolExecutor when lower-level access becomes useful.

Starting and stopping the recurring tick usually belongs to bean lifecycle methods:

package com.example.ttlwheel;

import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import org.springframework.scheduling.TaskScheduler;

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

public class WheelClock {

    private final TaskScheduler scheduler;
    private ScheduledFuture<?> ticker;

    public WheelClock(TaskScheduler scheduler) {
        this.scheduler = scheduler;
    }

    @PostConstruct
    void start() {
        ticker = scheduler.scheduleAtFixedRate(this::tick, Duration.ofSeconds(1));
    }

    @PreDestroy
    void stop() {
        if (ticker != null) {
            ticker.cancel(false);
        }
    }

    private void tick() {
        // advance the wheel
    }
}

Code like that keeps the wheel clock tied to application startup and shutdown. Startup registers the repeating callback, shutdown cancels it, and the returned ScheduledFuture<?> gives you direct control over that recurring execution. Spring’s scheduler contract also states that repeated execution ends when the scheduler shuts down or when that future is canceled, which lines up neatly with a wheel owned by a singleton bean.

Cache State with Bucket Queues

State inside the wheel usually breaks into three layers. Live cache values live in a concurrent map for fast reads. Bucket storage lives in a fixed collection of queues, with one queue per slot. Expiration records carry the data needed later during removal, such as the key, the deadline tick, the remaining wheel rounds, and a token that ties the record to a specific write. Spring Boot’s fallback in-memory caching already rests on concurrent maps, so building a custom in-process wheel around concurrent collections fits naturally with that direction.

Keeping live values separate from wheel records helps in two ways. Reads stay focused on the value map instead of searching through timer state, and expiration records can come and go without changing the storage layout for cached values. That separation also leaves room for metadata that belongs to expiry rather than to the value itself. Deadline ticks, wheel rounds, and write tokens belong on expiration records, not on the scheduler or on the bucket list.

State like that can be laid out with records and concurrent collections:

package com.example.ttlwheel;

import java.util.List;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.atomic.AtomicLong;
import java.util.stream.IntStream;

public class WheelState<K, V> {

    private final int wheelSize;
    private final List<ConcurrentLinkedQueue<ExpirationRecord<K>>> wheel;
    private final ConcurrentHashMap<K, CacheEntry<V>> entries = new ConcurrentHashMap<>();
    private final AtomicLong tokenSequence = new AtomicLong();

    public WheelState(int wheelSize) {
        this.wheelSize = wheelSize;
        this.wheel = IntStream.range(0, wheelSize)
                .mapToObj(i -> new ConcurrentLinkedQueue<ExpirationRecord<K>>())
                .toList();
    }

    record CacheEntry<V>(V value, long deadlineTick, long token) {
    }

    record ExpirationRecord<K>(K key, long deadlineTick, long rounds, long token) {
    }

    int wheelSize() {
        return wheelSize;
    }

    List<ConcurrentLinkedQueue<ExpirationRecord<K>>> wheel() {
        return wheel;
    }

    ConcurrentHashMap<K, CacheEntry<V>> entries() {
        return entries;
    }

    long nextToken() {
        return tokenSequence.incrementAndGet();
    }
}

Fresh values then go through a write flow that stores the live entry, computes its deadline tick, and drops an expiration record into the proper bucket:

package com.example.ttlwheel;

import java.time.Duration;

public class WheelWriter<K, V> {

    private final WheelState<K, V> state;
    private final long tickNanos;

    public WheelWriter(WheelState<K, V> state, Duration tickDuration) {
        this.state = state;
        this.tickNanos = tickDuration.toNanos();
    }

    public void put(K key, V value, Duration ttl, long currentTick) {
        long ttlNanos = ttl.toNanos();
        long delayTicks = Math.max(1L, (ttlNanos + tickNanos - 1) / tickNanos);
        long deadlineTick = currentTick + delayTicks;
        long rounds = (delayTicks - 1) / state.wheelSize();
        long token = state.nextToken();

        state.entries().put(key, new WheelState.CacheEntry<>(value, deadlineTick, token));

        int slot = (int) (deadlineTick % state.wheelSize());
        state.wheel().get(slot).offer(
                new WheelState.ExpirationRecord<>(key, deadlineTick, rounds, token)
        );
    }
}

Rounding the TTL upward to at least one tick keeps zero-length scheduling from slipping through by accident. Round counts let a compact wheel carry deadlines that go far beyond a single ring pass, and the token lets the cache connect each expiration record to the specific write that created it. Those parts become more important as keys get rewritten before older expiry records have a chance to fire. Read behavior usually stays separate from bucket handling. The value map answers get calls directly, and a read can also check the stored deadline tick to reject expired data before the background tick reaches that bucket. That keeps stale values from slipping through in the gap between deadline time and the next wheel pass, while the wheel still handles scheduled cleanup in the background.

Late Expirations with Stale Timer Records

Delayed ticks are unavoidable in any scheduler-based structure. GC pauses, CPU contention, machine-level pressure, or code inside the callback that takes longer than planned can all push the next wheel pass behind schedule. A wheel that only increments by one slot per callback can drift farther behind during those moments, so it is safer to compare the clock-derived target tick against the last processed tick and catch up through every missed tick in order. TaskScheduler supports recurring fixed-rate and fixed-delay execution, but it does not promise perfectly on-time callback execution.

Stale timer records create a second problem that shows up in the same area. Say a cache entry for alex-token is written with a 30 second TTL, then written again ten seconds later with a fresh value and a new TTL. The first expiration record is still sitting in the wheel. If the wheel later drains that older bucket and blindly removes the key, it can delete the newer value by mistake. That is why the expiration record needs a token or version number that also appears on the live entry. If the tokens differ, the record is stale and should be ignored.

Catch-up logic and stale-record checks can live in the same flow:

package com.example.ttlwheel;

import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.atomic.AtomicLong;

public class WheelAdvancer<K, V> {

    private final WheelState<K, V> state;
    private final AtomicLong processedTick = new AtomicLong(-1);

    public WheelAdvancer(WheelState<K, V> state) {
        this.state = state;
    }

    public void advanceTo(long targetTick) {
        long nextTick = processedTick.get() + 1;

        while (nextTick <= targetTick) {
            drainSlot(nextTick);
            processedTick.incrementAndGet();
            nextTick++;
        }
    }

    private void drainSlot(long tick) {
        ConcurrentLinkedQueue<WheelState.ExpirationRecord<K>> bucket =
                state.wheel().get((int) (tick % state.wheelSize()));

        int bucketSize = bucket.size();
        for (int i = 0; i < bucketSize; i++) {
            WheelState.ExpirationRecord<K> record = bucket.poll();
            if (record == null) {
                break;
            }

            WheelState.CacheEntry<V> entry = state.entries().get(record.key());
            if (entry == null) {
                continue;
            }

            if (entry.token() != record.token()) {
                continue;
            }

            if (record.rounds() > 0) {
                bucket.offer(new WheelState.ExpirationRecord<>(
                        record.key(),
                        record.deadlineTick(),
                        record.rounds() - 1,
                        record.token()
                ));
                continue;
            }

            if (entry.deadlineTick() <= tick) {
                state.entries().remove(record.key(), entry);
            }
        }
    }
}

Absolute deadline ticks carry a lot of weight there. Bucket position tells the wheel where to look, but the stored deadline tick gives the final answer about expiry. That distinction helps when the scheduler wakes late, when the wheel is catching up through missed ticks, or when a record circles back through a bucket after one or more full ring passes. Token comparison protects against stale removals, and remove(key, entry) keeps the delete tied to the exact entry object that was checked a moment earlier.

Read-side code can also reject expired entries before the wheel drains their bucket. That step does not replace scheduled cleanup, but it does tighten read behavior around the TTL boundary:

public V get(K key, long currentTick) {
    WheelState.CacheEntry<V> entry = state.entries().get(key);
    if (entry == null) {
        return null;
    }

    if (entry.deadlineTick() <= currentTick) {
        state.entries().remove(key, entry);
        return null;
    }

    return entry.value();
}

Read-time expiry and wheel-time expiry serve different purposes. The read path keeps callers from seeing stale values after the deadline has passed. The wheel removes entries that have gone cold and would otherwise remain in memory without being touched again. Paired this way, TTL behavior stays tighter without forcing every entry onto its own private scheduler handle.

Fits for Eviction, Delayed Jobs, Session Cleanup

In-memory cache eviction is the most natural match for this structure. Values already live inside the application, deadlines are usually short or medium in length, and bucket-based cleanup is more than enough for the timing precision involved. Session cleanup fits the same profile. Login state, temporary verification tokens, and short-lived user state can all expire on wheel ticks without needing their own scheduled callback per entry. Spring Boot’s cache abstraction can sit above that store, but the timing data structure still lives inside the cache implementation itself.

Delayed jobs fit too, with an important boundary in mind. For a delay queue that lives inside a single process, a wheel-based model fits well when the delay only needs to survive for as long as that instance is running. If the process stops, that in-memory wheel stops with it. Calendar-based scheduling, restart survival, or cross-node coordination call for a different scheduler. Spring Framework includes Quartz integration, and Spring Boot can auto-configure Quartz with either an in-memory job store or a JDBC-backed store through spring.quartz.job-store-type. That marks a useful dividing line between lightweight in-process expiry timing and durable scheduled job management.

Session cleanup falls between those two cases. If session state already lives in local memory and losing it on restart is acceptable, the wheel keeps cleanup cheap and predictable. If session lifetime needs durable storage across restarts or across several application instances, the data store itself usually needs to own expiration rather than the application’s in-memory scheduler. Picking the wheel for the first case and Quartz or provider-managed expiry for the second keeps the timing model aligned with the data lifetime you actually have.

Conclusion

Time wheel expiration keeps TTL cleanup tied to time slots instead of a separate timer for every entry. Live values stay in the cache, future expiry records stay in the wheel, and the scheduler advances the current tick so only the active bucket needs attention at that moment. Deadline ticks, round counts, and stale-record checks give the cache a practical way to remove expired entries, catch up after delayed ticks, and keep cleanup cost centered on the records due near the current slot.

1. Spring Boot Caching

2. Spring Framework Scheduling

3. TaskScheduler Javadoc

4. ThreadPoolTaskScheduler Javadoc

5. ConcurrentHashMap Javadoc

6. ConcurrentLinkedQueue Javadoc

Share Alexander Obregon's Substack

Palindrome search gets expensive fast when every center has to expand outward from the beginning with no memory of what was already found. Manacher’s Algorithm cuts out that repeated checking by carrying forward palindrome length data from earlier positions, so a center inside a larger confirmed match can start with information that is already available before any fresh character comparisons begin. That reuse gives the algorithm a linear-time scan while still finding the longest palindromic substring and the palindrome radius at every center. In Java, arrays and index-based access fit this logic naturally, so the full process is easier to follow than it first appears.

Subscribe now

Why Repeated Expansion Becomes Expensive

Most palindrome checks begin with a center and grow outward one step at a time while the characters on both sides still match. That starting idea is easy to follow because every palindrome has some middle point. Odd-length palindromes place that middle on a character, as with racecar, while even-length palindromes place it between two characters, as with abba.

The slowdown starts because neighboring centers overlap so heavily. A long match found at one center does not automatically help the next center beside it, so the scan ends up rechecking part of the same region again. Small strings can hide that cost, but wider palindromic spans make the repeated comparisons add up quickly.

Center Expansion From Scratch

Basic center expansion treats every center as if nothing has already been learned. Pick an index, grow outward, stop at the first mismatch, then move to the next index and do nearly the same scan again. That behavior can hide inside compact code because each expansion loop is short. The total cost only becomes obvious when the full pass across the string is viewed as a whole.

Take abacaba for example, starting from the middle finds a long palindrome. Move one center to the left and the scan still covers a shorter palindrome that overlaps heavily with the earlier result. Move one more center and part of that same region gets checked again. Strings such as aaaaaaa make the repetition easier to notice, because nearly every center expands across a wide span. Each center is valid on its own, but the full search keeps paying for the same character comparisons again and again.

This Java helper shows the basic expansion rule:

public static int expandAroundCenter(String text, int left, int right) {
    while (left >= 0 && right < text.length()
            && text.charAt(left) == text.charAt(right)) {
        left--;
        right++;
    }

    return right - left - 1;
}

Left and right move outward while the characters match, and the returned value gives the palindrome length for that single center.

Finding the longest substring with that helper means calling it across the full string:

public static String longestPalindromeByExpansion(String text) {
    if (text == null || text.isEmpty()) {
        return "";
    }

    int bestStart = 0;
    int bestLength = 1;

    for (int i = 0; i < text.length(); i++) {
        int oddLength = expandAroundCenter(text, i, i);
        int evenLength = expandAroundCenter(text, i, i + 1);
        int currentLength = Math.max(oddLength, evenLength);

        if (currentLength > bestLength) {
            bestLength = currentLength;
            bestStart = i - (currentLength - 1) / 2;
        }
    }

    return text.substring(bestStart, bestStart + bestLength);
}

Odd centers call expandAroundCenter(text, i, i). Even centers call expandAroundCenter(text, i, i + 1). That covers both palindrome forms, but it also means each position or gap starts a fresh expansion with no stored radius data from nearby centers.

Counting comparisons makes the repeated cost easier to track:

public static int countComparisons(String text, int left, int right) {
    int comparisons = 0;

    while (left >= 0 && right < text.length()) {
        comparisons++;
        if (text.charAt(left) != text.charAt(right)) {
            break;
        }
        left--;
        right++;
    }

    return comparisons;
}

Call this method at every center on a string filled with repeated characters and the total comparison count climbs much faster than the input length. That is why the worst-case time cost for center expansion is usually treated as O(n²). The outer scan visits each center, and the inner loop can travel far for a large share of those centers.

The expensive part is not the long expansion at a single center. Cost grows because nearby centers keep revisiting overlapping territory from the beginning. That wording gets closer to the real source of the slowdown than a bare statement that the method is quadratic.

Odd and even centers add more repetition because strings like abbaabba need character-based centers and gap-based centers to cover every case. That full coverage is correct and useful for learning palindromes, but it still doubles the set of starting points. Nothing is carried forward from an earlier expansion, so overlapping checks keep returning.

Why Mirrored Radii Help

Mirrored radius data changes the question from what this center can prove from zero to what has already been proved near its mirrored partner. That single change removes a large share of the repeated comparison cost.

Let’s say a long palindrome has already been found around some midpoint. Any center inside that span has a matching center on the other side of the midpoint. If the left-side center already has a stored radius, the mirrored center on the right begins with part of its own answer already available before any new comparison starts.

We can see that borrowing step in this Java helper:

public static int borrowedRadius(int[] radii, int currentCenter, int currentRight, int index) {
    int mirror = 2 * currentCenter - index;

    if (index >= currentRight) {
        return 0;
    }

    return Math.min(currentRight - index, radii[mirror]);
}

If the current index falls outside the known right edge, borrowing is not possible and the start radius stays at 0. If the index is inside that known span, the mirrored center supplies a starting radius. Math.min caps that borrowed value so it never claims more than the current right edge can support.

That cap is important. Mirrored centers can store a large radius, yet not all of it is safe to copy. Part of that palindrome may extend into territory the current center has not proved on its side. Borrowed radius data gives a trusted starting length, not always the final length.

Take a region where a known palindrome runs from index 4 to index 14, with center 9. Look at index 11. Its mirror across center 9 is index 7. If the stored radius at index 7 is 2, then index 11 can begin with radius 2 as long as that borrowed length stays inside the known right boundary. Inner characters do not need to be compared again. Fresh comparison starts only after that borrowed distance ends.

This brief calculation makes the index relationship easier to trace:

int currentCenter = 9;
int currentRight = 14;
int index = 11;
int mirror = 2 * currentCenter - index;

int mirroredRadius = 2;
int startRadius = Math.min(currentRight - index, mirroredRadius);

startRadius equals 2, so index 11 does not restart from radius 0. Expansion begins farther out, near the boundary of what still has to be checked.

That idea forms the bridge between basic center expansion and the later linear-time scan. Earlier center-by-center search repeats inner comparisons at nearby positions. Mirrored radii remove that repetition by carrying forward what earlier centers already proved. New checks still happen, but they begin closer to the unexplored edge, which is why the total comparison count drops so sharply across the full string.

How Manacher’s Algorithm Works in Java

After the repeated overlap problem is known, the next step is to see how Manacher’s Algorithm reorganizes the scan. Instead of treating every center as a separate outward expansion with no carried-forward length data, it restructures the string into a format where every palindrome behaves like the same kind of object. From there, the algorithm keeps track of the farthest confirmed right edge and borrows radius data from mirrored centers whenever that borrowed length is already supported by the palindrome currently in view. Java works great for this logic because arrays, integer indexing, and loops make the moving parts easy to trace from left to right.

Turning Every Palindrome Into One Center Style

Odd-length palindromes and even-length palindromes create an awkward split if both are handled as two unrelated cases. racecar has a middle character. abba has a middle gap. Without some kind of reformatting, a palindrome scan has to keep remembering which kind of center it is dealing with at each step.

Manacher’s Algorithm removes that split by placing separator positions between characters and at both ends. After that change, every palindrome has a center at a single index in the transformed layout. The original string abba can be viewed like this in a teaching-only layout:

public static String visualLayout(String text) {
    StringBuilder layout = new StringBuilder("^");

    for (int i = 0; i < text.length(); i++) {
        layout.append('|').append(text.charAt(i));
    }

    layout.append("|$");
    return layout.toString();
}

Calling visualLayout("abba") produces ^|a|b|b|a|$. The even palindrome now has a center at the separator between the two b values, while odd palindromes also still have a center of their own. That means the scan no longer needs separate logic for odd and even cases.

This string-based view is helpful for learning, but the later full Java version is better off keeping the transformed layout in an int[] rather than a String. Fixed separator characters such as | or # can collide with data already present in the input. An integer layout avoids that issue by reserving sentinel values that do not overlap with real Unicode code points. That transformed layout does more than make the string look uniform. It also gives the radius array a uniform meaning. Each entry records how far a palindrome extends from its center in the transformed space. There is no branch for odd length and no second branch for even length. Every center expands by checking one step left and one step right inside the same layout.

Mapped back to the original string, that means an odd palindrome such as aba and an even palindrome such as abba both become radius problems with the same rules. When that reformatted view is in place, later parts of the algorithm can focus on boundary tracking and borrowed radius values without having to worry about two separate center types.

Tracking the Active Right Boundary

Two running values drive the scan after the transformed layout is ready. One holds the center of the palindrome that currently reaches farthest to the right. The other holds that palindrome’s right edge. Those two values are usually named center and right.

As the scan moves from left to right, each new index asks a very narrow question. Does this index fall inside the current right boundary, or has it gone past it. That small check determines how much prior radius data can be trusted before any new outward expansion begins.

If an index falls outside the current right edge, no borrowed radius is available yet. Expansion begins at radius 0, because nothing about that new center has been confirmed by the earlier rightmost palindrome.

If an index falls inside the right edge, then part of the answer is already known. The current rightmost palindrome gives a safe zone where symmetry can be trusted. The scan does not need to restart from zero at that index. Instead, it can begin from a radius value supported by the palindrome already in view. This is also where the linear-time behavior starts to become easier to see. Fresh outward comparison only happens when a center reaches beyond the old right boundary. Every successful push beyond that boundary moves right farther to the right, and that boundary never moves backward. Total outward boundary growth across the full scan therefore stays proportional to the input length, which is a big part of why the total time stays at O(n).

The algorithm is still checking centers from left to right, but the scan is no longer blind. It carries a live right boundary and a live center from the farthest-reaching palindrome found so far. That running state changes the full traversal from a sequence of isolated expansions into a connected pass where earlier radius data continues to inform later positions.

Reusing Mirrored Data Safely

Symmetry is where the saved comparisons come from. When an index falls inside the current right boundary, there is a mirrored index on the opposite side of the current center. Radius data already stored at that mirrored position can give the current index a starting radius before any new character check begins.

The mirror index comes from a short arithmetic rule:

int mirror = 2 * center - i;

If i is inside the active right boundary, the algorithm can borrow radius data from radius[mirror]. Still, that borrowed value cannot blindly cross the current right edge. The right boundary marks the farthest territory already confirmed by the current enclosing palindrome, so borrowed length has to stop there if the mirrored radius extends farther.

We can see an example of this here:

if (i < right) {
    radius[i] = Math.min(right - i, radius[mirror]);
}

right - i is the maximum radius that stays fully inside the current boundary from index i. radius[mirror] is the amount already known at the mirrored position. Taking the smaller of those two values keeps the borrowed radius inside territory that is already verified by symmetry.

Fresh expansion starts after that borrowed radius has been assigned.

while (layout[i + radius[i] + 1] == layout[i - radius[i] - 1]) {
    radius[i]++;
}

That loop does not repeat the inner comparisons already supported by the current rightmost palindrome. It begins at the first position that still needs new confirmation. This is the reason mirrored data removes so much repeated checking. The algorithm is not copying the full answer from the mirror every time. It is copying the part that is already justified by the active boundary, then asking for new comparisons only beyond that.

Three situations can come up around that mirrored radius idea. Sometimes the mirrored radius stays fully inside the current right edge. In that case, the borrowed value can be accepted as-is. Sometimes the mirrored radius runs past the left side of the enclosing palindrome, which means only part of it is safe to reuse. In the third case, the current index is outside the right boundary, so no borrowed value is available and expansion begins from zero.

There is one other thing to keep in mind for the scan. Borrowed radius data is never treated as a blind shortcut. It is only trusted within the span already supported by the current enclosing palindrome. New expansion still happens, but it starts at the edge of known territory instead of at the center. That is what cuts away the repeated inner checks that slowed down basic center expansion.

Java Code for the Longest Palindromic Substring

The full Java code makes the moving parts easier to connect from start to finish. The version below returns the longest palindromic substring in O(n) time with O(n) extra space. It reads the string as Unicode code points rather than raw UTF-16 char values, so supplementary characters stay intact.

public final class ManacherLongestPalindrome {
    private ManacherLongestPalindrome() {
    }

    public static String longestPalindrome(String text) {
        if (text == null || text.isEmpty()) {
            return "";
        }

        int[] original = text.codePoints().toArray();
        int[] layout = toLayout(original);
        int[] radius = new int[layout.length];

        int center = 0;
        int right = 0;
        int bestCenter = 0;
        int bestRadius = 0;

        for (int i = 1; i < layout.length - 1; i++) {
            int mirror = 2 * center - i;

            if (i < right) {
                radius[i] = Math.min(right - i, radius[mirror]);
            }

            while (layout[i + radius[i] + 1] == layout[i - radius[i] - 1]) {
                radius[i]++;
            }

            if (i + radius[i] > right) {
                center = i;
                right = i + radius[i];
            }

            if (radius[i] > bestRadius) {
                bestRadius = radius[i];
                bestCenter = i;
            }
        }

        int start = (bestCenter - bestRadius) / 2;
        return new String(original, start, bestRadius);
    }

    private static int[] toLayout(int[] original) {
        int[] layout = new int[original.length * 2 + 3];
        layout[0] = -1;

        int j = 1;
        for (int codePoint : original) {
            layout[j++] = -3;
            layout[j++] = codePoint;
        }

        layout[j++] = -3;
        layout[j] = -2;
        return layout;
    }
}

text.codePoints().toArray() reads the input as Unicode code points. That avoids splitting supplementary characters into two UTF-16 units, which would throw off palindrome comparisons for some text.

toLayout() builds the transformed array. Negative integers act as sentinels and separators, while real code points remain non-negative. The left sentinel at index 0 and the right sentinel at the last slot let the expansion loop stop naturally at both ends without extra boundary checks inside the while condition.

radius[i] holds the palindrome radius for transformed index i. center and right track the active palindrome that currently reaches farthest to the right. mirror gives the reflected position across center, which is where borrowed radius data comes from when i falls inside the active boundary.

The line int start = (bestCenter - bestRadius) / 2; maps the transformed layout back to the original code point array. That division by 2 comes from the separator layout, where every original code point is separated by one inserted slot.

Look at the result for abba. In the transformed layout, the longest palindrome grows around a separator center rather than around a character center. Look at racecar, and the longest palindrome grows around a code point center. Both cases still end up with a single radius value in the transformed array, which is exactly why this reformatted layout is so useful for the rest of the scan.

The full scan still visits each transformed index, but fresh outward comparison only happens at the edge of borrowed radius information. That keeps the total time at O(n). Extra space stays at O(n) because the code holds the original code point array, the transformed layout, and the radius array.

Conclusion

Manacher’s Algorithm gets its speed from the way it reorganizes palindrome search into a single left-to-right pass with carried-forward radius data. After the string is transformed so every palindrome uses the same center format, the scan can track the current rightmost palindrome, borrow safe radius length from mirrored positions, and only compare new characters when the known boundary can be pushed farther. In Java, that logic fits naturally into arrays and index math, which makes the full process easier to trace from the transformed layout all the way back to the longest palindromic substring.

1. Java String Class Documentation

2. Java StringBuilder Class Documentation

3. Java Character Class Documentation

4. Java String.codePoints() Documentation

5. Java Language Basics on Unicode

Share Alexander Obregon's Substack

In Spring Boot, LRU caching fits a fairly specific set of problems. It works best for a small in-memory set where recently read entries should stay near the front of attention while older ones fall away as fresh data comes in. Java already provides most of what is needed through LinkedHashMap with access order turned on, so the interesting part is not the surface-level API. What actually deserves attention is how the map tracks entry order, what a read changes internally, when eviction happens, what size() is really measuring, and where this kind of in-memory LRU cache belongs inside a Spring Boot application.

Subscribe now

How LinkedHashMap Drives LRU Order

LinkedHashMap does more than its name first suggests. Most people know it as a map that keeps a stable order, but that order can follow two very different rules. It can follow insertion order, where entries stay in the sequence they were added. It can also follow access order, where entries move after they are touched. LRU behavior comes from that second mode.

That is why this class appears so frequently in cache discussions. The hash table part still gives quick lookup by key, while the linked entry chain keeps a running memory of recency. One part answers where a value is stored. The other tracks how recently that value was touched compared with everything else already in the map. Those two jobs living in the same structure are what make LinkedHashMap useful for a small LRU cache.

The Structure Behind the Map

Inside LinkedHashMap, entries do not just live in buckets the way people usually think of a basic HashMap. Every entry is also linked to the one before it and the one after it. That linked chain is what preserves encounter order across the map. Without that chain, a map can answer lookups, but it cannot tell you which entry counts as oldest or newest in any meaningful cache sense.

Insertion order is the default behavior. Put entries into the map in the order user:1, user:2, user:3, and iteration gives that same order back. Access order changes the story. If the map was created with access order turned on, the entry that gets read or updated moves toward the most recent end of the chain. That turns the linked chain into a running history of recency.

Seeing the code makes that easier to follow:

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

public class AccessOrderMapDemo {
    public static void main(String[] args) {
        Map<String, String> sessions = new LinkedHashMap<>(16, 0.75f, true);

        sessions.put("alex", "token-101");
        sessions.put("kaitlyn", "token-202");
        sessions.put("pippin", "token-303");

        System.out.println(sessions.keySet());
    }
}

That constructor changes the entire behavior of the map. The first value is the initial capacity, the second is the load factor, and the final true tells the map to track access order instead of insertion order. Without that last true, the map still keeps order, but not the order an LRU cache needs.

The linked entry chain also explains why iteration over a LinkedHashMap feels stable. A plain HashMap does not promise a predictable iteration order. LinkedHashMap does, because iteration walks the linked sequence of entries. In cache terms, the start of iteration gives the least recently encountered entry in access mode, while the end gives the newest.

Let’s imagine we have a small map with four entries added in this sequence:

A B C D

If access order is off, reading B changes nothing about iteration. The order stays:

A B C D

Turn access order on, read B, and it moves to the newest end:

A C D B

That movement is the heart of LRU tracking. No separate queue is required. No side list is required. The map’s linked chain already carries the recency information.

This small helper makes that behavior easier to follow while the order changes:

import java.util.LinkedHashMap;

public class EntryOrderPreview {
    public static void main(String[] args) {
        LinkedHashMap<String, Integer> recentViews =
                new LinkedHashMap<>(16, 0.75f, true);

        recentViews.put("article-11", 11);
        recentViews.put("article-27", 27);
        recentViews.put("article-63", 63);
        recentViews.put("article-88", 88);

        printOrder("Initial order", recentViews);

        recentViews.get("article-27");
        printOrder("After reading article-27", recentViews);

        recentViews.get("article-11");
        printOrder("After reading article-11", recentViews);
    }

    private static void printOrder(String label, LinkedHashMap<String, Integer> map) {
        System.out.println(label + " -> " + map.keySet());
    }
}

Reading article-27 does not create a new entry. It does not change the stored value. Placement in the linked chain is what changes. After that read, article-27 stops being older than the entries behind it and becomes the newest encountered entry. Reading article-11 later repeats that relocation.

That helps explain why LinkedHashMap works so well for LRU logic. Least recently used is really just oldest by recency order. The map keeps that ordering alive as code interacts with entries.

What a Read Changes in Access Order Mode

Reading from an access-ordered LinkedHashMap is not passive. That is one of the biggest things to keep in mind while reading or writing LRU cache code based on this type. Calling get for an existing entry does more than hand back the value. It also refreshes that entry’s recency position.

Let’s say the map currently holds these entries from oldest to newest:

profile-9 profile-12 profile-18 profile-25

After get("profile-12"), profile-12 moves to the newest end, so the order becomes:

profile-9 profile-18 profile-25 profile-12

After get("profile-9"), the order changes again:

profile-18 profile-25 profile-12 profile-9

That is node movement on reads in practical terms. The node for the accessed entry is detached from its current spot in the linked chain and reattached at the newest end. The lookup still comes from hash-based access. The recency update comes from relinking.

Seeing it in code makes the movement easier to follow:

import java.util.LinkedHashMap;

public class ReadMovementDemo {
    public static void main(String[] args) {
        LinkedHashMap<String, String> recentProfiles =
                new LinkedHashMap<>(16, 0.75f, true);

        recentProfiles.put("profile-9", "Alex");
        recentProfiles.put("profile-12", "Kaitlyn");
        recentProfiles.put("profile-18", "Pippin");
        recentProfiles.put("profile-25", "Jordan");

        System.out.println("Start  " + recentProfiles.keySet());

        recentProfiles.get("profile-12");
        System.out.println("Read 12 " + recentProfiles.keySet());

        recentProfiles.get("profile-9");
        System.out.println("Read 9  " + recentProfiles.keySet());
    }
}

That output makes the linked order more straight forward to follow. The map does not need a remove followed by a put to refresh an entry. The read itself is enough to change recency.

People new to this class sometimes ask why an LRU cache built on LinkedHashMap cannot be treated like a normal read-only map during reads. The reason is that access order changes the internal ordering from the cache’s point of view. Every cache hit refreshes the entry’s recency position. Every miss leaves the map unchanged because there is no stored entry to move.

Looking at insertion order next to access order makes that difference much easier to see visually:

import java.util.LinkedHashMap;

public class OrderComparisonDemo {
    public static void main(String[] args) {
        LinkedHashMap<String, Integer> insertionOrder =
                new LinkedHashMap<>(16, 0.75f, false);

        LinkedHashMap<String, Integer> accessOrder =
                new LinkedHashMap<>(16, 0.75f, true);

        insertionOrder.put("invoice-101", 101);
        insertionOrder.put("invoice-205", 205);
        insertionOrder.put("invoice-319", 319);

        accessOrder.put("invoice-101", 101);
        accessOrder.put("invoice-205", 205);
        accessOrder.put("invoice-319", 319);

        insertionOrder.get("invoice-205");
        accessOrder.get("invoice-205");

        System.out.println("Insertion order map " + insertionOrder.keySet());
        System.out.println("Access order map    " + accessOrder.keySet());
    }
}

The insertion-order map still prints invoice-101, invoice-205, invoice-319 after the read. The access-order map prints invoice-101, invoice-319, invoice-205. Both maps store the same entries. Only the ordering rule changes.

Not every interaction refreshes recency in the same way people expect. Iterating through keySet(), values(), or entrySet() does not act like a read of every entry. That distinction keeps cache inspection from rewriting LRU history. If simply printing the contents refreshed all entries, then any debug view would scramble the entire recency order and the cache would stop reflecting actual lookup activity.

That also ties the read behavior back to LRU logic. Least recently used does not mean least recently inserted and those can drift apart very quickly. An entry added earlier can remain fresh if requests keep hitting it. An entry added later can become stale if requests stop touching it. Access order captures that difference directly, which is why it maps so naturally to LRU behavior.

Eviction Timing Size Accounting and Spring Boot Fit

Recency and removal follow different moments in an LRU cache built with LinkedHashMap. Entry order changes as records are touched, but removal waits for a later point. That timing affects how the cache grows, when older entries leave, and what the map is actually counting while it lives inside a Spring Boot application. Spring Boot does not alter the internal behavior of LinkedHashMap. What changes is the environment around it. Put a cache field inside a singleton service and it lives across requests and across request threads. Build a cache for a narrower scope and the behavior around ownership and sharing changes with it. Before placement makes sense, eviction timing, entry counting, and concurrency need to be pinned down.

Eviction Happens After a Write Not After a Read

Recency updates happen during access, but eviction does not run during a read. That separation is one of the first things people need to lock in while reading an LRU cache built on LinkedHashMap. Reading an entry can move it to the most recent end of the order, but every current mapping stays in the map after that read. Removal enters the picture only after a new mapping is added and the map checks its eldest entry.

removeEldestEntry is where that policy lives and the method is checked after put or putAll adds a mapping. If the map now holds more entries than the chosen cap, the eldest entry is removed. Put differently, the cache can move past the size limit during insertion, then trim itself as part of that write path.

Walking through a small example helps. Let’s say the cache limit is 3 and the access order from eldest to newest is:

A B C

Read A, and the order becomes:

B C A

Nothing leaves the cache at that point. The read refreshed recency, but the entry count stayed the same. Add D, and the map now has four entries just long enough to decide who should go. B is eldest at that moment, so B is the entry that gets removed. The resulting order is:

C A D

Keeping the policy centered on entry count makes the timing easier to see:

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

public class SmallLruMap<K, V> extends LinkedHashMap<K, V> {
    private final int maxEntries;

    public SmallLruMap(int maxEntries) {
        super(16, 0.75f, true);
        this.maxEntries = maxEntries;
    }

    @Override
    protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
        return size() > maxEntries;
    }
}

That override does a single job. It does not try to remove entries manually from inside the method, and it does not update outside state. It only tells the map when the eldest entry should be removed.

Running a small driver makes the sequence much easier to follow:

public class EvictionTimingDemo {
    public static void main(String[] args) {
        SmallLruMap<String, String> cache = new SmallLruMap<>(3);

        cache.put("order-101", "packed");
        cache.put("order-205", "shipped");
        cache.put("order-319", "delivered");
        System.out.println(cache.keySet());

        cache.get("order-101");
        System.out.println(cache.keySet());

        cache.put("order-444", "processing");
        System.out.println(cache.keySet());
    }
}

After the first print, the order is order-101, order-205, order-319. After get("order-101"), the order becomes order-205, order-319, order-101. After put("order-444", "processing"), the order becomes order-319, order-101, order-444 because order-205 was the eldest entry when the write finished.

People testing LRU behavior sometimes expect the oldest entry to disappear right after a read refreshes something else. That never happens with this structure. Reads change who counts as oldest. Writes trigger the decision to remove the eldest entry.

What Size Accounting Really Means

size() answers a very narrow question. It tells you how many mappings are in the map at that moment. It does not tell you how large those values are in memory. It does not tell you how expensive they were to create. It does not tell you how much heap pressure the cache is causing. It only counts entries.

That sounds obvious at first, but the effect is bigger than it looks. Entry count is easy to reason about, which is why the classic LinkedHashMap LRU form is built around size() > maxEntries. Still, two caches with the same entry count can consume very different amounts of memory if one stores tiny strings and the other stores large graphs of objects, nested collections, or large byte arrays.

Take two maps that both report a size of 100. One holds short product codes. The other holds parsed report data with hundreds of rows per entry. Entry count matches, but memory cost is nowhere near the same.

We can see this a bit better with an example that shows how little size() knows about a value beyond the fact that a mapping exists:

import java.util.LinkedHashMap;
import java.util.List;

public class SizeCountingDemo {
    public static void main(String[] args) {
        LinkedHashMap<String, Object> cache = new LinkedHashMap<>(16, 0.75f, true);

        cache.put("status", "ok");
        cache.put("recentIds", List.of(11, 27, 63, 88, 105));
        cache.put("profileBlob", new byte[1024 * 1024]);

        System.out.println(cache.size());
    }
}

The printed value is 3. That result stays the same no matter how different the stored values are internally. From the map’s point of view, three mappings exist, so size() returns three.

Entry-count LRU works best when cached values live in roughly the same cost range or when the cache cap is small enough that rough counting is good enough. If memory footprint has to track value weight much more closely, then a plain LinkedHashMap entry cap is only a rough stand-in, not a byte-aware cache policy.

Entry counting also stays separate from recency. Touching an entry moves it in the access order, but size() does not change. Replacing a value for an existing key keeps the same mapping count. Adding a new key increases the count. Removing a key decreases it. Bookkeeping stays easy to follow, but it is still only entry bookkeeping.

Thread Safety Inside a Spring Boot Singleton

LinkedHashMap LRU inside a Spring Boot singleton needs concurrency protection. That point catches people off guard because reads in an access-ordered map are not passive from the structure’s point of view. Successful get calls move entries to the most recent end, so a read can change internal ordering.

Spring Boot service beans are singleton by default. Put a mutable cache field inside such a bean, and every request thread that reaches the service can touch the same map. With no coordination, those threads can interfere with the map’s internal state while reads and writes happen at the same time.

Look at this service, which stays very close to what people usually write first:

import org.springframework.stereotype.Service;

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

@Service
public class CatalogCacheService {

    private final Map<Long, String> cache = new LinkedHashMap<>(16, 0.75f, true) {
        @Override
        protected boolean removeEldestEntry(Map.Entry<Long, String> eldest) {
            return size() > 256;
        }
    };

    public String getCached(Long id) {
        return cache.get(id);
    }

    public void putCached(Long id, String value) {
        cache.put(id, value);
    }
}

Nothing in that class protects the map from concurrent access. Two request threads can call getCached at the same time, and both reads can try to refresh order. Read and write activity can also collide. That is where trouble begins.

For a small in-memory cache, a synchronized wrapper is usually enough:

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

public class SynchronizedLruCache<K, V> {
    private final LinkedHashMap<K, V> map;

    public SynchronizedLruCache(int maxEntries) {
        this.map = new LinkedHashMap<>(16, 0.75f, true) {
            @Override
            protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
                return size() > maxEntries;
            }
        };
    }

    public synchronized V get(K key) {
        return map.get(key);
    }

    public synchronized void put(K key, V value) {
        map.put(key, value);
    }

    public synchronized int size() {
        return map.size();
    }
}

Synchronized methods keep access to the map serialized through that wrapper, which is enough for a small hot set inside a service. That does not turn the cache into a high-throughput general-purpose cache library. It does keep internal ordering and entry updates from being modified by multiple threads at the same instant.

Bean scope and cache safety are closely tied in Spring Boot. Singleton fields live across requests and need thread coordination. Narrower-scoped caches created inside a single request flow do not carry the same shared-state pressure because only that request touches them.

Where This Fits Best in a Modern App

LinkedHashMap LRU fits best where the cache is small, local, and easy to reason about. Good examples include a tiny hot set of recently requested lookups, a service-local memoization map for repeated reads during a short call chain, parsed fragments that get reused heavily for a brief period, or a request-scoped map that avoids repeating the same work inside a single request.

That local nature is part of the appeal because no outside cache server is involved. No extra infrastructure is required. The structure lives right in the JVM, and the cost of checking it is low. For a small hot set, that can be enough.

Inside a request-scoped component, the cache can stay very narrow and vanish at the end of the request. Lifetime and ownership stay easy to follow. This example shows a request-scoped lookup cache that only lives for one request:

import org.springframework.stereotype.Component;
import org.springframework.web.context.annotation.RequestScope;

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

@Component
@RequestScope
public class RequestPriceCache {

    private final Map<Long, String> cache = new LinkedHashMap<>(8, 0.75f, true) {
        @Override
        protected boolean removeEldestEntry(Map.Entry<Long, String> eldest) {
            return size() > 8;
        }
    };

    public String get(Long id) {
        return cache.get(id);
    }

    public void put(Long id, String value) {
        cache.put(id, value);
    }
}

Placement like that works nicely when repeated lookups can happen during one request and there is no need to carry cached values into later requests.

Small singleton hot sets can also work well if thread safety is handled and the entry cap stays modest. Think about a service that repeatedly loads a narrow set of recently requested summaries, route lookups, or short-lived reference data that is cheap to refresh. Local reuse in that range is where LinkedHashMap LRU usually earns its keep.

Limits still deserve attention here because this cache stays local to a single application instance. If the same Spring Boot service is running on four instances, each one keeps its own separate cache contents rather than participating in a shared cache. Built-in time-based expiration is not part of this structure, weight-based eviction is not built in either, and richer cache statistics are also absent unless you add that logic yourself.

That is why this form of LRU is best treated as a narrow in-memory tool, not as the answer to every cache need inside a Spring Boot application. It works well for request-scoped caches and small hot sets where local recency is exactly what you want. Broader caching needs usually call for Spring’s cache abstraction with a dedicated cache provider, where features such as eviction policy choices, expiry, and metrics go further than a hand-rolled LinkedHashMap field.

Conclusion

LinkedHashMap gives LRU caching its behavior through a very specific set of moving parts. Access order keeps recency up to date as reads happen, removeEldestEntry removes the oldest mapping after a write pushes the map past its limit, and size() tracks entry count rather than memory cost. Put inside a Spring Boot app, that makes this cache style a good fit for small in-memory hot sets where local recency is the main thing you want to preserve.

1. LinkedHashMap Java Documentation

2. Map Java Documentation

3. Spring Boot Caching Reference

4. Spring Framework Cache Abstraction

5. ConcurrentHashMap Java Documentation

Share Alexander Obregon's Substack

One slow downstream dependency can put an entire Spring Boot service under pressure if nothing limits how much work reaches it at the same time. Putting a hard cap on in-flight calls for a specific downstream target gives you a fixed boundary, then the service can either wait briefly for capacity or reject extra requests right away after that limit is hit. Semaphores fit that job nicely because they hold a set number of permits and let only that amount of traffic pass at one time. In the current Spring stack, that usually means a servlet Filter or OncePerRequestFilter on the MVC side, and a WebFilter or reactive operator-based limit on the WebFlux side.

Subscribe now

How Semaphore Bulkheads Work

Concurrency limits help only when the boundary is firm and easy to reason about. That is why semaphores fit this job well. They give you a fixed count of permits, they let callers enter until that count is exhausted, and they force a decision for everyone who arrives after that point. That decision is where bulkhead behavior starts to matter. Some services reject extra work right away so latency does not stretch upward. Others let callers wait briefly in case a permit frees up soon. Either choice come from the same starting point, which is a fixed ceiling on work already in progress.

Permits Set the Hard Ceiling

A permit is simply one slot for active downstream work. If a semaphore starts with 20 permits, then no more than 20 callers can pass through that gate at the same time. Caller 21 does not get special treatment just because it arrived a fraction of a second later. It has to wait, or it has to be rejected, based on the policy wrapped around the semaphore.

That hard ceiling is what gives bulkheads their value. Without a limit, a slow dependency can keep accepting more work until the calling service is tied up with rising response times, backed up threads, or a growing pile of unfinished reactive work. With a semaphore in front of that dependency, the service stops admitting extra load past a fixed point. The downstream call may still be slow, but the amount of damage it can spread is bounded by the permit count.

Java’s Semaphore keeps the mechanics small and direct. acquire() waits until a permit is available. tryAcquire() returns right away with true or false. release() gives the permit back. That compact API is enough to build several different admission styles.

This basic class makes the idea easy to follow:

import java.util.concurrent.Semaphore;

public final class InventoryGatewayLimit {

    private final Semaphore permits = new Semaphore(12, false);

    public boolean tryEnter() {
        return permits.tryAcquire();
    }

    public void leave() {
        permits.release();
    }

    public int availablePermits() {
        return permits.availablePermits();
    }
}

Nothing in that class calls a downstream service yet, but the main rule is already in place. Only 12 callers can be inside the guarded area at one time. availablePermits() can help with visibility during testing or metrics work, but the number that matters most is the starting permit count because that is the upper limit on concurrent access.

Fairness changes how waiting callers are handed permits when one becomes free. Fair mode tries to honor arrival order among waiting threads. Nonfair mode allows barging, so a later caller can take a permit ahead of an older waiter. The cap itself stays the same. What changes is the handoff order when there is contention.

We can see in this shorter example that makes the distinction more visual:

import java.util.concurrent.Semaphore;

public final class BillingLane {

    private final Semaphore fairPermits = new Semaphore(3, true);
    private final Semaphore nonFairPermits = new Semaphore(3, false);

    public Semaphore fairPermits() {
        return fairPermits;
    }

    public Semaphore nonFairPermits() {
        return nonFairPermits;
    }
}

Both semaphores cap active work at 3. The difference appears only when callers are waiting. Fair mode favors first-in, first-out ordering at the semaphore boundary. Nonfair mode can move work through with a bit less coordination cost. Capacity does not change there. Order does.

One rule matters a great deal when code is built around permits. Every successful acquire needs a matching release. Lose track of a permit and the gate slowly shrinks. Nothing external changed, yet the service starts acting like its limit got tighter and tighter. That is why the release step belongs in a finally block whenever a permit has been taken.

This version shows the release in the place where it belongs:

import java.util.concurrent.Semaphore;

public final class CatalogLookup {

    private final Semaphore permits = new Semaphore(8, false);

    public String fetchItem(String itemId) throws InterruptedException {
        permits.acquire();
        try {
            return callDownstream(itemId);
        } finally {
            permits.release();
        }
    }

    private String callDownstream(String itemId) throws InterruptedException {
        Thread.sleep(75);
        return "item-" + itemId;
    }
}

The finally block is doing the protective work there. If the downstream call throws, returns early, or gets interrupted after admission, the permit still goes back. That keeps the ceiling stable.

Permit count selection deserves careful thought too. Semaphores with 500 permits still count as limits, but that is not much of a boundary if the downstream starts struggling after 30 in-flight calls. Setting the value too low can reject traffic earlier than needed. Setting it too high gives the downstream room to pull the caller into the same slowdown you were trying to contain. The cap should reflect how much work that dependency can tolerate while latency and error rates remain acceptable.

Fail Fast Versus Queueing

Admission policy starts right after the last permit is gone. One option is fail fast. The caller tries tryAcquire(), gets false, and the service refuses the work immediately. The other option is queueing. That caller waits for a permit and enters later if capacity opens up in time.

Fail fast keeps pressure from stacking up inside the service. Requests that cannot enter do not sit around holding thread state, request data, timeouts, and downstream hopes. It gets a quick answer, and the service holds the line on in-flight work. Latency usually stays more predictable that way because excess traffic is not quietly turned into waiting traffic.

Take this class for example that shows the basic fail-fast style:

import java.util.concurrent.Semaphore;

public final class ShippingBulkhead {

    private final Semaphore permits = new Semaphore(15, false);

    public boolean tryStartCall() {
        return permits.tryAcquire();
    }

    public void finishCall() {
        permits.release();
    }
}

A caller can check tryStartCall(), and if it returns false, reject the work right away. That style is easy to reason about. No hidden line forms behind the limit. Capacity either exists right now or it does not.

Queueing changes the behavior in a very real way. Instead of refusing entry immediately, the caller waits for a permit. That can help during brief bursts where one permit is about to free up and the wait will be short. Waiting still has a cost. The service is now carrying extra callers that are not doing useful downstream work yet. They are parked at the gate, hoping for admission. If that wait grows, request latency grows with it, and upper-layer timeouts can start firing before the downstream call has even begun.

Timed waiting is usually the safer form of queueing because it puts a bound on how long a caller can remain at the gate. Untimed waiting is harder to control and can turn pressure into long stalls.

For example this uses a short wait window:

import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;

public final class PartnerApiGate {

    private final Semaphore permits = new Semaphore(10, true);

    public boolean tryStartCall() throws InterruptedException {
        return permits.tryAcquire(150, TimeUnit.MILLISECONDS);
    }

    public void finishCall() {
        permits.release();
    }
}

That code says a caller can wait up to 150 milliseconds for a permit. If no permit appears during that window, admission fails. Short waits like this can smooth out brief bursts, though the tradeoff is still there. The service is spending part of the request time budget at the gate before the downstream call has even started.

Fairness matters more when queueing is involved. If callers are waiting, fair ordering gives older waiters a better chance to move forward in arrival order. Nonfair mode can admit newer callers ahead of them. That can raise throughput a bit, but it can also leave older waiters behind for longer. In fail-fast mode, fairness has less room to matter because most callers are not waiting at all. They either get in immediately or they do not.

Something else worth knowing is that tryAcquire() without a timeout does not respect fairness in the same way waiting acquisition does. That matters because fail-fast bulkheads commonly rely on plain tryAcquire(). So a service can declare a fair semaphore and still see immediate attempts succeed out of arrival order if they hit the gate at the right moment. That is one reason fair mode matters most in queue-heavy admission rather than strict fail-fast admission.

Service behavior changes a great deal depending on which side you choose. Fail fast favors quick refusal and tighter latency control. Queueing favors giving a burst one more chance to pass. Neither choice changes the permit ceiling itself. The semaphore still caps active work. The difference is what the service does with work that arrives after the gate is full.

Spring Boot Implementations

Spring Boot supports two different web stacks, and bulkhead placement depends on which one is handling the request and what needs to be capped. Servlet applications process requests through request threads, so a filter is a natural gate before controller work begins. WebFlux handles requests through a reactive, non-blocking model, so request admission can still live in a web filter, while downstream fan-out inside a reactive chain is usually better capped inside the pipeline itself. Current Spring APIs line up with that split through OncePerRequestFilter for servlet applications and WebFilter for reactive applications.

Servlet Stack Bulkheads with OncePerRequestFilter

Servlet-based Spring MVC applications already have a request interception layer in front of controllers, and OncePerRequestFilter fits that boundary well. It is built to run a filter one time per request dispatch and exposes doFilterInternal(HttpServletRequest, HttpServletResponse, FilterChain) for request processing. That makes it a natural place to cap in-flight requests before controller logic starts expensive work or calls a dependency that is already under pressure.

Spring Boot 3 and 4 use the Jakarta Servlet API, so code in this part of the stack should import jakarta.servlet types rather than the older javax.servlet package names. That matters because it affects copy-paste accuracy for current applications. OncePerRequestFilter also remains part of Spring’s current org.springframework.web.filter package and still fits normal servlet filter work.

This fail-fast filter keeps the gate narrow for one request path family and rejects extra work immediately when all permits are in use:

package com.example.bulkhead;

import java.io.IOException;
import java.util.concurrent.Semaphore;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public final class PaymentBulkheadFilter extends OncePerRequestFilter {

    private final Semaphore permits = new Semaphore(20, false);

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return !request.getRequestURI().startsWith("/api/payments");
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        if (!permits.tryAcquire()) {
            response.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
            response.setContentType(MediaType.TEXT_PLAIN_VALUE);
            response.getWriter().write("Too many payment requests in flight");
            return;
        }

        try {
            filterChain.doFilter(request, response);
        } finally {
            permits.release();
        }
    }
}

Two parts matter a lot in that filter. shouldNotFilter() narrows the cap to the request group that actually needs protection, which keeps unrelated endpoints from competing for the same permits. The finally block gives the permit back no matter how the request finishes. If that release is skipped after an exception or early return, the bulkhead slowly tightens until the application starts rejecting traffic that should have been allowed. This example assumes the guarded endpoint finishes within the initial servlet dispatch. If the endpoint enters servlet async processing, permit release has to be tied to async completion rather than the return of the initial filter chain.

Short timed waiting is possible in the servlet stack too. That gives a request a brief chance to enter if a permit is about to free up, but it also means a servlet request thread is sitting at the gate rather than doing useful work. This version shows that style:

package com.example.bulkhead;

import java.io.IOException;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public final class InventoryBulkheadFilter extends OncePerRequestFilter {

    private final Semaphore permits = new Semaphore(12, true);

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return !request.getRequestURI().startsWith("/api/inventory");
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        boolean acquired = false;
        try {
            acquired = permits.tryAcquire(100, TimeUnit.MILLISECONDS);
            if (!acquired) {
                response.setStatus(HttpServletResponse.SC_TOO_MANY_REQUESTS);
                return;
            }
            filterChain.doFilter(request, response);
        } catch (InterruptedException ex) {
            Thread.currentThread().interrupt();
            response.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
        } finally {
            if (acquired) {
                permits.release();
            }
        }
    }
}

That version can help with very brief bursts, but it changes the tradeoff. Part of the request time budget is now spent waiting for admission, and the request thread remains occupied during that wait. For servlet applications, that is one of the biggest reasons fail-fast admission stays attractive for bulkheads tied to strained downstream work.

Picking Status Codes for Failure Responses

Status code choice shapes how clients interpret the refusal. Most bulkhead rejections end up as either 429 Too Many Requests or 503 Service Unavailable, and both can make sense depending on what you want the response to say.

429 is a good fit when the response should read as an admission limit being hit. That can work well when the service is intentionally capping request entry and the client should treat it as a load-related refusal at the edge of the application.

503 fits well when the refusal is really about temporary service capacity, such as a downstream dependency that is already saturated or a request class that the service cannot safely admit right now. That framing keeps the message tied to temporary unavailability rather than client behavior.

Utility code can keep that decision consistent across filters and handlers:

package com.example.bulkhead;

import org.springframework.http.HttpStatus;

public final class BulkheadResponses {

    private BulkheadResponses() {
    }

    public static HttpStatus paymentRefusal() {
        return HttpStatus.SERVICE_UNAVAILABLE;
    }

    public static HttpStatus searchRefusal() {
        return HttpStatus.TOO_MANY_REQUESTS;
    }
}

Consistency matters more than forcing every endpoint into the same status code. Payment requests tied to a fragile downstream provider may read best as temporary unavailability, while a search endpoint with a deliberately narrow concurrency cap may read more naturally as too many requests.

Headers deserve a brief note too. Retry-After can help if clients are supposed to retry, but it should not be attached casually. Automatic retries from large groups of callers can keep pressure high long after the first overload event. A quick refusal without aggressive retry hints is sometimes the safer choice when downstream capacity is the real problem.

Error body wording should stay short and factual. Clients usually do not need a long explanation to act on a concurrency refusal. Stable status codes, a compact message, and predictable behavior from one call to the next are what matter most.

WebFlux Request Caps with WebFilter

Reactive request handling changes the runtime model, but request admission still needs a fixed boundary when a certain route should not accept unlimited in-flight work. WebFilter is Spring’s interception contract for cross-cutting request processing on the reactive side, so it serves as the direct counterpart to servlet filtering in WebFlux. Because WebFlux runs on a non-blocking model, a request-level bulkhead should avoid blocking waits on request-processing threads. That is why fail-fast admission with tryAcquire() maps nicely to a WebFilter. The request either gets a permit immediately or it is rejected right away. No thread is parked waiting for capacity to appear.

For example this filter caps reactive request entry for one route group:

package com.example.bulkhead;

import java.util.concurrent.Semaphore;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;

import reactor.core.publisher.Mono;

@Component
public final class ReactivePaymentBulkheadFilter implements WebFilter {

    private final Semaphore permits = new Semaphore(20, false);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String path = exchange.getRequest().getPath().value();

        if (!path.startsWith("/api/payments")) {
            return chain.filter(exchange);
        }

        if (!permits.tryAcquire()) {
            exchange.getResponse().setStatusCode(HttpStatus.SERVICE_UNAVAILABLE);
            return exchange.getResponse().setComplete();
        }

        return chain.filter(exchange)
                .doFinally(signalType -> permits.release());
    }
}

doFinally handles the lifecycle work there. Reactive request processing can complete normally, fail, or be canceled. Permit release should happen for all of those terminal outcomes so the gate stays accurate.

Timed waiting with a semaphore is much less attractive in WebFlux than in servlet applications. Blocking permit acquisition does not fit naturally with a non-blocking request pipeline. Thread offloading can make it possible, but that adds moving parts and can blur the bulkhead’s intent. For request-level gating in WebFlux, immediate admission or immediate refusal usually stays much easier to reason about.

Per Downstream Call Caps Inside a Reactive Pipeline

Request-level filters cap whole requests. That works particularly well when each request leads to one downstream call or when the request itself is the right boundary to protect. Some endpoints behave differently. One incoming request can fan out into dozens or hundreds of downstream calls through WebClient. In that case, the request may be allowed in, but the downstream fan-out still needs its own cap.

WebClient is Spring’s reactive HTTP client, and Reactor gives you a direct concurrency cap through flatMap overloads that accept a concurrency value. That gives you a natural way to limit in-flight downstream calls inside a reactive chain without turning the request admission layer into a waiting line.

This service caps downstream detail lookups at 10 active calls per request:

package com.example.bulkhead;

import java.util.List;

import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@Service
public final class ItemDetailsService {

    private final WebClient webClient;

    public ItemDetailsService(WebClient.Builder builder) {
        this.webClient = builder.baseUrl("https://details.example.com").build();
    }

    public Mono<List<ItemDetails>> fetchDetails(List<String> ids) {
        return Flux.fromIterable(ids)
                .flatMap(this::loadDetails, 10)
                .collectList();
    }

    private Mono<ItemDetails> loadDetails(String id) {
        return webClient.get()
                .uri("/items/{id}", id)
                .retrieve()
                .bodyToMono(ItemDetails.class);
    }
}

In that code, it caps downstream concurrency without rejecting the entire request at the door. The request enters, but only 10 of its downstream lookups can be active at a time. If the input list contains 200 IDs, the remaining calls wait inside the reactive sequence until one of the active slots finishes. For fan-out work, that usually fits better than a request-level semaphore because the thing being limited is not whole-request entry. It is the number of active downstream calls inside the request.

Ordering matters too, plain flatMap merges results as inner publishers complete, so result order can differ from source order. If order matters, Reactor also provides flatMapSequential with a maximum concurrency value. That keeps a concurrency cap while preserving source ordering in the merged output.

Take this example that shows where that becomes useful:

package com.example.bulkhead;

import java.util.List;

import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@Service
public final class ReportAssemblyService {

    private final WebClient webClient;

    public ReportAssemblyService(WebClient.Builder builder) {
        this.webClient = builder.baseUrl("https://pricing.example.com").build();
    }

    public Mono<List<PricingView>> loadPricingViews(List<String> skuIds) {
        return Flux.fromIterable(skuIds)
                .flatMapSequential(this::fetchPrice, 6)
                .collectList();
    }

    private Mono<PricingView> fetchPrice(String skuId) {
        return webClient.get()
                .uri("/prices/{skuId}", skuId)
                .retrieve()
                .bodyToMono(PricingView.class);
    }
}

flatMapSequential keeps six calls active at a time while still emitting results in the original input order. That small change matters when the caller expects output to stay aligned with the original sequence.

Fairness Tradeoffs in Real Services

Fairness affects who gets admitted next when callers are waiting, and first-come, first-served can sound attractive right away. The tradeoff is that fairness is about admission order, not extra capacity. The semaphore still allows only the configured number of active holders. What changes is how waiting callers get newly freed permits.

Queue-heavy admission is where fairness matters most. If a bulkhead allows waiting, fair mode gives older waiters a better shot at moving first. Nonfair mode can let a newer arrival take a permit ahead of them. That can reduce coordination cost a bit, but it can also leave earlier waiters around longer than expected. Fail-fast bulkheads reduce the practical weight of fairness because there is little waiting to order. Immediate tryAcquire() either gets a permit right now or it does not. That means fairness is usually a more visible choice in timed-wait servlet bulkheads than in reactive fail-fast filters or servlet fail-fast filters.

Seeing code of this can make that contrast easy to understand:

Semaphore fairGate = new Semaphore(10, true);
Semaphore nonFairGate = new Semaphore(10, false);

The two gates cap active work at 10. Under contention, the first favors waiting order and the second favors faster handoff freedom. There is no universal winner there. Bulkheads attached to a route with short waits and tight latency goals are commonly left nonfair. Bulkheads where queued callers should move in arrival order can justify fair mode, particularly if timed waiting is part of the admission policy.

There is another subtle point that can surprise people the first time they rely on fair mode. Immediate tryAcquire() does not behave the same way as blocking acquisition with respect to fairness. That means a service built around fast rejection can still see immediate arrivals succeed out of turn if a permit becomes free at just the right moment. For that reason, fairness is most visible when callers are actually waiting, not when the service is built around instant admission decisions.

Conclusion

Bulkhead concurrency limits with semaphores work because they turn shared capacity into a fixed gate that every request or downstream call has to pass through before work begins. That fixed gate is what keeps pressure from spreading past the point you chose. On the servlet side, that can live at request entry in a filter, while WebFlux can apply the same idea at request entry or deeper in a reactive chain when fan-out work needs its own cap. When permit count, release handling, and admission behavior are set carefully, the service stops taking on more in-flight work than that boundary allows, which keeps overload from quietly piling up in the background.

1. Java Semaphore Javadoc

2. Spring OncePerRequestFilter Javadoc

3. Spring WebFilter Javadoc

4. Spring WebClient Reference

5. Project Reactor Flux Javadoc

6. Project Reactor Mono Javadoc

7. Spring WebFlux Reference

Share Alexander Obregon's Substack

Prime number generation shows up in interviews, math tools, and performance benchmarks, and the Sieve of Eratosthenes is a classic way to list primes up to a chosen limit. It does that by keeping a flag table for the numbers 0 through n, then stepping through candidates and marking their multiples as not prime until only primes remain flagged.

How the Sieve Works Mechanically

Prime sieving stays easy to follow when you keep two ideas separate. One part is a flag table that records the current prime status for every number in range. The other part is the marking pass that walks through multiples and flips flags off when a divisor is found.

Flag Table Meaning

You can think of the flag table as a direct lookup from an integer to its current prime status. Index i corresponds to the number i, so reading or writing the state for a number is just reading or writing one array slot. In Java, a boolean[] fits this well because indexed access is fast. Default values really matter, a fresh boolean[] starts with false everywhere, so the usual start is to set indices 2 through n to true and leave 0 and 1 as false because they are not prime. Those true values represent prime candidates at the beginning, then marking removes the composites.

Array sizing is the first boundary detail that tends to trip people up. If the goal is to cover the numbers from 0 through n, index n needs a slot, which means the array length must be n + 1. With length n, the last slot is n - 1, and the number n cannot be represented at all.

This helper sets up that starting state with the inclusive range in mind:

static boolean[] primeFlagsUpTo(int n) {
  boolean[] isPrime = new boolean[n + 1]; // index n exists
  for (int i = 2; i <= n; i++) {
    isPrime[i] = true;
  }
  return isPrime;
}

Reading the table later stays literal. Interpret isPrime[i] as the current flag value for i, not as a mathematical proof in that moment. Before marking runs, most entries from 2 through n start as true, and after marking finishes, the indices that remain true correspond to primes.

Printing a small range makes it easier to spot what the marking pass changed without flooding the output, and a helper method keeps the read range inside the array:

static void printFlagSlice(boolean[] isPrime, int from, int toInclusive) {
  int end = Math.min(toInclusive, isPrime.length - 1);
  for (int i = from; i <= end; i++) {
    System.out.println(i + “ -> “ + isPrime[i]);
  }
}

The Math.min guard keeps the read range inside the array, which is useful when you are experimenting with different limits and want consistent behavior.

Marking Multiples

Composite removal happens by walking through multiples of a prime candidate p. Every composite that has p as a factor shows up at positions p * 2, p * 3, p * 4, and so on, so the loop steps through those positions by adding p each time and writes false into the flag table. The start position changes both performance and how easy the logic is to reason about. Starting at p * 2 works, but it repeats work that was already done by smaller factors. Starting at p * p avoids that repetition because any multiple smaller than p * p has a factor smaller than p, which means it would have been handled earlier when that smaller factor was processed.

That same reasoning gives a natural stopping point for the outer loop. After p * p is greater than n, there is no marking work left for p inside the table, because the first multiple you would touch is already outside the range. That is why the outer loop can stop at the condition p * p <= n.

Something to consider in Java is that multiplying two int values can overflow, and p * p is a multiplication. Casting to long before multiplying keeps the comparison stable for larger limits.

The method here marks composite numbers by starting at p * p, stepping by p, and stopping at n:

static void markMultiples(boolean[] isPrime, int n) {
  for (int p = 2; (long) p * p <= n; p++) {
    if (!isPrime[p]) {
      continue;
    }

    long start = (long) p * p;
    for (long m = start; m <= n; m += p) {
      isPrime[(int) m] = false;
    }
  }
}

The inner loop walks the arithmetic sequence p * p, p * p + p, p * p + 2p, and writes false at each visited index. The cast back to int is safe in this context because m never exceeds n, and n is an int bound.

Helper methods can print the multiple positions so the step size is easy to track while reading the logic. It is separate from the sieve itself, but it follows the same p * p start and + p stepping as the marking loop:

static String multiplesFromSquare(int p, int n) {
  StringBuilder sb = new StringBuilder();
  for (long m = (long) p * p; m <= n; m += p) {
    if (sb.length() > 0) sb.append(”, “);
    sb.append(m);
  }
  return sb.toString();
}

Calling multiplesFromSquare(5, 50) yields 25, 30, 35, 40, 45, 50, which lines up with the idea that 10, 15, and 20 were already handled earlier through smaller factors like 2 and 3.

Java Sieve Implementation With Correct Bounds

Array indexing in Java lines up directly with the sieve’s number range, so the main work is getting bounds right and picking a flag representation that matches the size of n. Array length, mark start at p * p, the p * p <= n stop rule, and flag storage choices are the points that decide how the code behaves.

Baseline Implementation With boolean Array

Start by reserving one flag per integer from 0 through n. Index i represents the number i, so the array must be length n + 1 so index n exists. New boolean[] values start as false, so prime candidates need to be turned on for 2 through n, while 0 and 1 stay false.

Lets see how it plays out in code, the method below builds the flags, runs marking, then collects the surviving indices as primes. Casting to long before multiplying avoids overflow in p * p when n is large:

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

public final class SieveBoolean {

  public static List<Integer> primesUpTo(int n) {
    if (n < 2) return List.of();

    boolean[] isPrime = new boolean[n + 1];

    for (int i = 2; i <= n; i++) {
      isPrime[i] = true;
    }

    for (int p = 2; (long) p * p <= n; p++) {
      if (!isPrime[p]) continue;

      long start = (long) p * p;
      for (long m = start; m <= n; m += p) {
        isPrime[(int) m] = false;
      }
    }

    List<Integer> primes = new ArrayList<>();
    for (int i = 2; i <= n; i++) {
      if (isPrime[i]) primes.add(i);
    }
    return primes;
  }

  private SieveBoolean() {}
}

If you want to keep the memory layout and the output layout mentally aligned, it can be useful to treat the array as the source of truth and derive results from it only at the end. That keeps the marking pass focused on flipping flags, and it keeps the result pass focused on reading flags.

Loop Boundaries That Prevent Off-by-One Bugs

The outer loop condition and the marking start need to match. Marking starts at p * p, so the outer loop only needs to run while p * p <= n. Once p * p is greater than n, the first multiple that would be marked is already outside the array range, so continuing the outer loop would not change any flags. The stop check can also be written with Math.sqrt(n), but the p * p form stays tied to the same arithmetic used to start marking. The main detail is the equality case. Exact squares must be handled, so the loop should continue when p * p equals n.

This helper method shows the stop condition directly as p * p <= n, which is the point where marking still reaches at least one value inside the range:

static boolean markingStillHasWork(int p, int n) {
  return (long) p * p <= n;
}

That helper is not required for performance, but it keeps the boundary rule visible. It also makes it harder to accidentally write < where <= is needed.

Memory Layout for Flags

boolean[] keeps one flag for every number, and the code reads naturally because the array index matches the number you are talking about. Memory still grows with n + 1, so very large limits can run into memory pressure. BitSet stores flags as bits rather than bytes, so the same range takes far less space. BitSet keeps the same indexing meaning. Index i still refers to the number i, and 0 and 1 stay not prime. The set(from, to) overload takes an exclusive upper bound, so including n means passing n + 1.

import java.util.ArrayList;
import java.util.BitSet;
import java.util.List;

public final class SieveBitSet {

  public static List<Integer> primesUpTo(int n) {
    if (n < 2) return List.of();

    BitSet isPrime = new BitSet(n + 1);
    isPrime.set(2, n + 1);

    for (int p = 2; (long) p * p <= n; p++) {
      if (!isPrime.get(p)) continue;

      long start = (long) p * p;
      for (long m = start; m <= n; m += p) {
        isPrime.clear((int) m);
      }
    }

    List<Integer> primes = new ArrayList<>();
    for (int i = isPrime.nextSetBit(2); i >= 0 && i <= n; i = isPrime.nextSetBit(i + 1)) {
      primes.add(i);
    }
    return primes;
  }

  private SieveBitSet() {}
}

Two boundary rules show up in that version. The first is set(2, n + 1) rather than set(2, n), because the upper bound is exclusive. The second is the scan loop, which starts at nextSetBit(2) so the first candidate is 2, not 0 or 1.

Common Off-by-One Issues

Small limits make boundary bugs show up fast because there are fewer numbers to hide mistakes. With n = 2, the correct output contains 2. If the initialization loop runs i < n instead of i <= n, index 2 never gets set to true, so the output becomes empty.

With n = 4, the number 4 must be marked not prime because it equals 2 * 2. If the outer loop runs while p * p < n instead of <= n, then p = 2 does not run when n is 4, and 4 stays flagged as prime. With inclusive behavior, the array length must be n + 1. Allocating new boolean[n] silently turns the meaning into less than n, because index n cannot exist. That changes the contract of the method even if the rest of the loops look right.

This small test checks a few of those edge values and prints what the method returned. The goal is not exhaustive testing. The goal is catching boundary slips that happen at the smallest inputs:

import java.util.List;

public final class SieveSanity {

  static void check(int n) {
    List<Integer> primes = SieveBoolean.primesUpTo(n);
    System.out.println(”n=” + n + “ -> “ + primes);
  }

  public static void main(String[] args) {
    check(0);
    check(1);
    check(2);
    check(3);
    check(4);
    check(10);
  }

  private SieveSanity() {}
}

Mark starts can also create off-by-one behavior. Starting at p * p + p skips the square itself, which leaves perfect squares behind as prime. Starting at p * p marks the square on the first iteration, which matches the idea that p * p is composite whenever p is greater than 1.

Time and Space Complexity in Big O

Runtime for the sieve up to n is O(n log log n). The marking work is driven by prime candidates, and each prime p touches positions spaced p apart, so the total number of flag writes grows a little faster than linear but far slower than n log n. After marking, scanning the table to collect primes is O(n) because it checks each index from 2 through n once.

Space cost is O(n) because the flag table keeps one entry per value from 0 through n. With boolean[], space grows with the array length and stores one boolean value per index. With BitSet, the same 0 through n range is represented as bits, so space stays O(n) but with a smaller constant factor, which matters when n is large enough that memory starts to become the limiter rather than CPU time.

Conclusion

Sieve code stays reliable when the number range and the storage line up exactly. Allocate n + 1 so index n exists, set 2 through n as prime candidates, then mark composites starting at p * p while the loop condition stays p * p <= n. Keep the multiplication in long so the stop test does not break at larger limits, and pick boolean[] or BitSet based on how large n can get and how much memory you want to spend on flags.

1. Java Arrays Documentation

2. Java BitSet Documentation

3. Java Math Documentation

4. Java List Documentation

5. Java ArrayList Documentation

Share Alexander Obregon's Substack

Topological sorting shows up any time a directed graph is really a set of ordering rules, like build steps, course prerequisites, or dependency chains between jobs. You’re trying to produce one linear order of nodes where every arrow points forward in the list, meaning a prerequisite always appears before what depends on it. Kahn’s algorithm handles that by keeping a running count of incoming edges for each node, pushing all currently unblocked nodes into a queue, then repeatedly taking one out and removing its outgoing edges from the graph. If the queue runs dry and some nodes still have incoming edges, those leftovers point to a cycle, which means no topological order exists for the whole graph.

Subscribe now

Mechanics of Kahn’s Algorithm

Kahn’s algorithm runs on a directed graph where every edge means a one way dependency. That dependency meaning is the whole story for the sort. If there is an edge from node U to node V, U has to appear earlier than V in the final ordering, because V depends on U.

Graph Setup

Directed graphs are easiest to work with when you pick a consistent node identity. Most implementations label nodes as integers from 0 through n - 1, then keep a separate count n so arrays stay practical later for indegree tracking. The other choice is how to store edges. Kahn’s method repeatedly takes a node and walks every outgoing edge from it, so you want fast access to neighbors. That is why an adjacency list is common. Each node stores a list of nodes it points to, meaning the nodes that depend on it.

A good way to think about it is to treat node U as work that has already been completed. Every outgoing edge from U to V means V was waiting on U, so removing U also removes those outgoing edges and moves V closer to being ready. That only works smoothly when outgoing neighbors are easy to access.

This builds an adjacency list from a set of directed edges:

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

public final class GraphBuild {

    public static List<List<Integer>> buildAdjacency(int n, int[][] edges) {
        List<List<Integer>> graph = new ArrayList<>(n);
        for (int i = 0; i < n; i++) {
            graph.add(new ArrayList<>());
        }

        for (int[] e : edges) {
            int from = e[0];
            int to = e[1];
            graph.get(from).add(to);
        }

        return graph;
    }

    public static void main(String[] args) {
        int n = 5;
        int[][] edges = {
                {0, 2},
                {1, 2},
                {2, 3},
                {2, 4}
        };

        List<List<Integer>> graph = buildAdjacency(n, edges);
        System.out.println(graph);
    }
}

That graph structure stores outgoing edges only. If you need incoming edges later, Kahn’s method does not store them directly, because incoming edge counts are tracked in a separate table. Keeping outgoing neighbors in the adjacency list keeps dependency removal cheap, because removal is represented by walking neighbors and decrementing counts rather than physically deleting entries from lists. With a cycle, every node in the cycle has an incoming edge from inside the cycle, so none of them can ever be the first item in an ordering.

Some inputs come in as prerequisite pairs where the meaning is prereq to course. Converting that meaning into a directed edge is the main step. If prereq P must happen before item C, the edge should go P to C.

This helper keeps that direction explicit at the call site, which reduces the chance of reversing the edge by mistake:

import java.util.List;

public final class EdgeAdd {

    public static void addDependency(List<List<Integer>> graph, int prereq, int dependent) {
        graph.get(prereq).add(dependent);
    }
}

Sticking to one consistent direction matters because all later reasoning depends on it. Once the graph is built, every other step in Kahn’s method reads like bookkeeping on top of that direction.

Indegree Table

Indegree means the number of incoming edges for a node. In dependency terms, it is the number of prerequisites that still point into that node.

The indegree table is built by scanning every edge U to V and incrementing indegree of V. That count is the only part of the method that represents incoming edges directly. After the table is built, the rest of the work happens by decrementing those counts as dependencies are removed.

Reading the count as a blocked level works well. Indegree 0 means nothing has to come before the node, so it can appear right at the front of the ordering. Indegree greater than 0 means it’s still waiting on that many prerequisites.

This code computes indegree from the same edge list:

import java.util.Arrays;

public final class IndegreeBuild {

    public static int[] buildIndegree(int n, int[][] edges) {
        int[] indegree = new int[n];

        for (int[] e : edges) {
            int to = e[1];
            indegree[to]++;
        }

        return indegree;
    }

    public static void main(String[] args) {
        int n = 5;
        int[][] edges = {
                {0, 2},
                {1, 2},
                {2, 3},
                {2, 4}
        };

        int[] indegree = buildIndegree(n, edges);
        System.out.println(Arrays.toString(indegree));
    }
}

That output tells you which nodes have no prerequisites right away. In this sample, node 2 has indegree 2 because two nodes point to it. Nodes 3 and 4 each have indegree 1 because node 2 points to them. Nodes 0 and 1 have indegree 0 because nothing points into them. Those numbers are also what make cycle detection possible later. Every time an edge is removed, indegree drops. If a directed cycle exists, every node in that cycle always has at least one incoming edge from within the cycle, so indegree for those nodes never falls to 0.

Time cost for building indegree is O(E), where E is the number of edges, because each edge is scanned one time. Space cost for the indegree table is O(V), where V is the number of nodes, because it stores one integer per node.

Queue Flow in Kahn’s Algorithm

After the adjacency list and indegree array exist, the rest of Kahn’s algorithm is a repeating flow that moves ready nodes through a queue and updates indegrees as dependencies get removed. The queue is the working set of nodes that currently have no remaining incoming edges, so every pop from that queue is safe to place next in the final order.

Starting Queue

First step is filling the queue with every node whose indegree is 0. That set represents nodes with no prerequisites, so they can appear at the front of the ordering without breaking any edge rule.

Multiple nodes can have indegree 0 at the same time. Picking any of them is valid, which is why a topological order is often not unique. A FIFO queue is common because it is fast and keeps the algorithm easy to follow. Some problems want a predictable smallest-id result, and that swaps the FIFO queue for a min-heap like PriorityQueue<Integer> so the smallest available node is chosen each time. The underlying rules do not change, only tie handling changes.

Take this helper that builds the initial queue from an indegree array. It uses ArrayDeque and adds nodes in numeric order, which keeps the initial insert stable:

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

public final class StartQueueBuild {

    public static Deque<Integer> buildStartQueue(int[] indegree) {
        Deque<Integer> queue = new ArrayDeque<>();
        for (int node = 0; node < indegree.length; node++) {
            if (indegree[node] == 0) {
                queue.addLast(node);
            }
        }
        return queue;
    }
}

That scan is O(V) time with O(V) storage for the queue in the worst case, where V is the number of nodes. Graphs with no edges put every node into the queue at the start, which is a helpful sanity check when stepping through the algorithm by hand.

Processing Loop

Work happens in a loop that runs until the queue is empty. Each iteration takes one node from the queue, appends it to the output order, then visits every outgoing neighbor of that node to update indegrees. Removing from the queue means the node is being committed into the ordering. It is safe because indegree 0 means no remaining prerequisites point to it. Appending it to the output is the physical record of that commitment.

The loop skeleton here keeps attention on queue movement and building the output order, leaving the neighbor updates for the next step:

import java.util.ArrayList;
import java.util.Deque;
import java.util.List;

public final class ProcessLoopCore {

    public static List<Integer> drainQueue(Deque<Integer> queue) {
        List<Integer> order = new ArrayList<>();
        while (!queue.isEmpty()) {
            int node = queue.removeFirst();
            order.add(node);
        }
        return order;
    }
}

In the full algorithm, the queue is not drained in one pass like this because neighbor updates keep adding more nodes. Still, the control flow is the same. Pop a node, record it, then do work based on that node. ArrayDeque is a solid choice in Java for this queue behavior. addLast and removeFirst are constant time, and it avoids the overhead that comes with linked structures.

Indegree Drop Step

Indegree dropping is the bookkeeping step that turns edge removal into numbers. After a node is placed into the output, treat all edges that leave it as removed. For each neighbor next in graph.get(node), decrement indegree[next] by 1. If that decrement makes indegree[next] equal 0, that neighbor has no remaining prerequisites, so it gets pushed into the queue.

This is the point where newly unblocked nodes enter the flow, so it belongs directly inside the loop, right after the node is taken from the queue.

Let’s see a Java method next that runs the loop and applies the indegree updates. It assumes graph is an adjacency list where graph.get(u) returns outgoing neighbors from u.

import java.util.ArrayList;
import java.util.Deque;
import java.util.List;

public final class KahnStep {

    public static List<Integer> runSteps(List<List<Integer>> graph, int[] indegree) {
        Deque<Integer> queue = StartQueueBuild.buildStartQueue(indegree);

        List<Integer> order = new ArrayList<>(indegree.length);

        while (!queue.isEmpty()) {
            int node = queue.removeFirst();
            order.add(node);

            for (int next : graph.get(node)) {
                indegree[next]--;
                if (indegree[next] == 0) {
                    queue.addLast(next);
                }
            }
        }

        return order;
    }
}

Each edge is processed exactly one time in that inner for loop, because each edge appears once in the adjacency list and gets visited when its from node is removed. That is the reason the full run time lands at O(V + E). Storage stays O(V + E) as well, driven by the adjacency list plus the arrays and output list.

Duplicate edges follow the same math. If the edge U to V appears twice, indegree for V starts higher by 2, and the two entries in U’s adjacency list will cause two decrements later. The queue only receives V when indegree hits 0, so it still becomes ready at the right time relative to the stored edges.

Nodes Left at the End

The algorithm finishes when the queue becomes empty. At that point, check how many nodes made it into the output list. If the output list size equals V, then every node was placed in order. If the output list is shorter than V, some nodes never reached indegree 0. That only happens when the remaining nodes still have incoming edges that never get removed, which means there is a directed cycle somewhere in that remaining set. In a cycle, each node depends on another node in the cycle, so no member of the cycle can ever be placed into the queue.

This check keeps cycle detection tied to the algorithm’s own state rather than adding a separate pass:

import java.util.List;

public final class CycleCheck {

    public static boolean hasCycle(int nodeCount, List<Integer> order) {
        return order.size() != nodeCount;
    }
}

Different call sites handle the cycle case differently. Some return an empty list. Some throw an exception. Some return the partial order plus a boolean. The shared idea is that a short output is not a partial win for topological sorting, it is the signal that a full ordering does not exist for that graph.

Conclusion

Kahn’s algorithm works by turning dependency arrows into counts, then letting those counts drive the order. Build the adjacency list so outgoing edges are easy to walk, build indegree so incoming pressure is tracked per node, then push every indegree 0 node into the queue as the starting set. Each time a node leaves the queue, it gets recorded in the output and its outgoing edges get removed by decrementing indegree on neighbors, with any neighbor that hits indegree 0 joining the queue next. When the queue empties, a full output of size V means a valid topological order was found, while any leftover nodes point directly to a cycle that prevents a complete ordering.

1. Topological Sort

2. Directed Acyclic Graph

3. Java Platform SE ArrayDeque

4. Java Platform SE Deque

5. Java Platform SE PriorityQueue

6. Java Platform SE Collections

7. Java Platform SE List

   Share Alexander Obregon's Substack

Streaming numbers one at a time is common in dashboards, logging, and anything that keeps a live metric running, and you usually want the median value right after every insert without sorting the full set again. A good way to do that is to keep the values split into a lower half and an upper half, then keep the split balanced so the boundary stays tight. With that split in place, the answer is always sitting right at the top edges of those halves, so reading it out takes constant time after each insert. This median tracking technique is commonly known as the two heaps method.

Subscribe now

What Two Heaps Store

The two heaps method gives you a very specific storage layout. One heap always exposes the largest value from the lower side, and the other heap always exposes the smallest value from the upper side, so the boundary values stay at the surface through peek(). The storage goal is to keep those boundary values meaningful as inserts happen, with the rest of each half tucked away inside heap order rather than fully sorted order.

Heap Configuration

Lower half means the smaller side of the stream so far. Fast access to the largest value in that lower half matters because it sits right at the boundary between the two halves. When the total count is odd, the median is one of the boundary values. When the total count is even, the median lives between them, so the boundary values still matter. That is why the lower half is stored in a max heap. In a max heap, the head is the largest item, so peek() gives the boundary value in constant time. Java’s PriorityQueue is a min heap by default, so the common move is to build it with Collections.reverseOrder() to flip the ordering and get max heap behavior.

As new values come in, this heap keeps representing the lower side of the stream, and its head stays the largest value from that side. The heaps themselves are just two PriorityQueue<Integer> instances configured differently, and you read the boundary with peek():

PriorityQueue<Integer> lower = new PriorityQueue<>(Collections.reverseOrder()); // max heap
PriorityQueue<Integer> upper = new PriorityQueue<>(); // min heap

if (!lower.isEmpty()) {
    int lowerBoundary = lower.peek();
}

if (!upper.isEmpty()) {
    int upperBoundary = upper.peek();
}

Early in the stream, one heap can be empty and the other can have values. That is normal at the start. It just means only one boundary exists until at least one value lands in the other heap.

The upper heap also handles duplicates naturally, including duplicates that match the lower boundary. If values equal to the boundary show up on both sides, upper.peek() can equal lower.peek() and the boundary still makes sense. The two halves can touch at the boundary value, and median reads later still work because the boundary values are meant to meet. The lower head is the maximum of the lower half and the upper head is the minimum of the upper half. Those two values are what the median logic reads later.

How Inserts Balance and Median Reads Out

Insert work comes down to two actions that repeat for every number. First, place the new value into one of the heaps based on where it belongs relative to the boundary. Second, rebalance sizes if one heap pulled ahead by more than one item. With those two actions done, the median is always available from peek() calls.

Picking a Side for a New Value

Placing the next value starts by looking at the boundary on the lower side. That boundary value is lower.peek(), which is the largest value in the lower half. If the lower heap is empty, the first value goes there so a boundary exists right away.

After that first insert, the rule is based on a single comparison. Values less than or equal to lower.peek() belong in the lower half, so they go into the max heap. Values greater than lower.peek() belong in the upper half, so they go into the min heap. This keeps the ordering relationship intact, where all values in the lower heap stay less than or equal to all values in the upper heap.

Putting the placement rule into a helper method keeps it in one place:

final class PlacementRule {
    public static void placeValue(
            int value,
            PriorityQueue<Integer> lowerMaxHeap,
            PriorityQueue<Integer> upperMinHeap
    ) {
        if (lowerMaxHeap.isEmpty() || value <= lowerMaxHeap.peek()) {
            lowerMaxHeap.add(value);
        } else {
            upperMinHeap.add(value);
        }
    }
}

That helper checks the empty start case, then compares against lowerMaxHeap.peek() to decide which heap receives the new value.

Rebalancing After the Insert

Size balance follows one rule. The heap size difference cannot exceed one. If it does, one value moves across the boundary.

If the lower heap grows to more than one item larger than the upper heap, the lower heap has too many values. The correct value to move is the lower heap head from poll(), because it is the largest value in the lower half and sits on the boundary. If the upper heap grows to more than one item larger than the lower heap, the upper heap has too many values. The correct value to move is the upper heap head from poll(), because it is the smallest value in the upper half and also sits on the boundary.

Only one transfer is needed after a single insert, because each insert changes size by one, and a single move changes the difference by two. The ordering relationship stays intact because the transferred value is a boundary value.

Reading the Median After Every Step

Median read depends on the combined count and the heap sizes, and it is available immediately after every insert through a getMedian() call. If no values exist yet, there is no median, so throwing an exception is reasonable. If the heaps have the same size, the stream has an even count. The median is the arithmetic mean of the two boundary values, lower.peek() and upper.peek().

If one heap has one extra value, the stream has an odd count. The median is the head of the heap with the extra value.

It’s worth mentioning that in java, adding two int values can overflow before the division happens. Casting to long before addition avoids that, and dividing by 2.0 returns a double median.

Median read logic can live in a small helper and look like:

final class MedianRead {
    public static double readMedian(
            PriorityQueue<Integer> lowerMaxHeap,
            PriorityQueue<Integer> upperMinHeap
    ) {
        int total = lowerMaxHeap.size() + upperMinHeap.size();
        if (total == 0) {
            throw new IllegalStateException(”No values added”);
        }

        if (lowerMaxHeap.size() == upperMinHeap.size()) {
            long left = lowerMaxHeap.peek();
            long right = upperMinHeap.peek();
            return (left + right) / 2.0;
        }

        return (lowerMaxHeap.size() > upperMinHeap.size())
                ? lowerMaxHeap.peek()
                : upperMinHeap.peek();
    }
}

This method reads without moving anything. Size checks decide which case applies, then peek() pulls the boundary values without changing heap contents. The even-count case casts to long before the add, which avoids overflow when two large int values are summed, and the / 2.0 keeps the return type as double so midpoints like 2.5 stay accurate.

Complete Java Implementation

To make a complete tracker, keep two PriorityQueue instances, place each new value into the correct heap, rebalance when a heap gets more than one item ahead, then read the median from the heap heads. The implementation below depends on PlacementRule and MedianRead from earlier in the article, so copy those too if you want this section to compile by itself. Insert cost is O(log n) due to heap add() and the possible poll() plus add() during rebalance. Median read cost is O(1) due to size checks and peek(). Space cost is O(n) because both heaps store the full set of inserted values.

import java.util.Collections;
import java.util.PriorityQueue;

public final class MedianStreamTracker {
    private final PriorityQueue<Integer> lower =
            new PriorityQueue<>(Collections.reverseOrder()); // max heap
    private final PriorityQueue<Integer> upper =
            new PriorityQueue<>(); // min heap

    public void addValue(int value) {
        placeValue(value);

        if (lower.size() > upper.size() + 1) {
            upper.add(lower.poll());
        } else if (upper.size() > lower.size() + 1) {
            lower.add(upper.poll());
        }
    }

    public double getMedian() {
        return readMedian();
    }

    private void placeValue(int value) {
        PlacementRule.placeValue(value, lower, upper);
    }

    private double readMedian() {
        return MedianRead.readMedian(lower, upper);
    }

    public static void main(String[] args) {
        MedianStreamTracker tracker = new MedianStreamTracker();

        int[] values = {5, 15, 1, 3, 8, 7, 9, 10, 6};
        for (int v : values) {
            tracker.addValue(v);
            System.out.println(”Value “ + v + “ median “ + tracker.getMedian());
        }
    }
}

MedianStreamTracker keeps two heaps as fields so state lives across inserts. lower is built with Collections.reverseOrder() so it behaves like a max heap, and upper stays the default min heap.

addValue does two steps. First it calls placeValue(value), which pushes the new number into the correct heap based on the current lower.peek() boundary. After that, addValue checks heap sizes and runs a rebalance only when one heap has more than one extra element. When that happens, it transfers one boundary element with a poll() from the larger heap and an add() into the other heap. That transfer is why the size gap cannot grow beyond one for more than a single insert.

getMedian calls readMedian(). That method reads only, meaning it never calls poll() and never changes heap contents. When sizes match, it averages the two boundary values, casting to long before the addition to avoid int overflow, and dividing by 2.0 so the return stays a double. When sizes differ by one, it returns the peek() from the larger heap, which is the middle value for an odd count.

Conclusion

The two heaps method keeps the stream split into a lower side and an upper side, with the boundary always visible through peek(). Each insert does two things, it places the value on the correct side based on the lower boundary, then it moves one boundary value across if a heap gets more than one item ahead. After that, median read becomes a quick size check and one or two peek() calls, with the even case averaging the two boundary values safely by casting to long before the add.

1. Java PriorityQueue Documentation

2. Java Collections Documentation

3. Java Comparator Documentation

4. Java Collections.reverseOrder Documentation

Share Alexander Obregon's Substack

Shortest path problems come up any time you’re hunting for the lowest total cost through a network, a grid, a dependency graph, or a routing table. Dijkstra’s algorithm is the usual tool, but the priority queue adds a log factor that you pay on every push and pop. With edge weights limited to 0 or 1, 0 1 BFS gives the same shortest distances as Dijkstra while swapping the priority queue for a deque, so the runtime stays linear in the size of the graph.

Subscribe now

What 0 1 BFS Solves

0 1 BFS targets shortest path problems where every edge cost is either 0 or 1. That small rule changes how you can schedule work, because distance values grow in steps of zero or one rather than jumping by larger amounts. The result is the same minimum total cost you’d get from Dijkstra, but the queueing behavior can be handled with a deque.

Weight Restriction and What it Buys You

Edge weights limited to 0 and 1 sound narrow, yet they show up a lot in practice. Think about decisions that are free versus decisions that cost one unit, or state transitions where one action is preferred and the other is a penalty of one. Once costs stay in that two value world, every move from a node with distance d lands you at either d again through a 0 edge or d + 1 through a 1 edge. That tight distance growth is the entire reason 0 1 BFS exists. Dijkstra’s algorithm handles any nonnegative weights by always pulling the smallest known distance from a priority queue. The priority queue has to keep itself ordered, so each insert and extract pays a log factor. With 0 and 1 weights, you can keep the work ordered without a full heap, because new distances can only match the current distance or be exactly one larger than it. A deque matches that behavior with constant time pushes and pops at both ends.

One way to internalize the restriction is to look at a tiny graph and see what the distances mean. The cost is literally the count of 1 edges along the cheapest route, because 0 edges do not add anything.

That example is intentionally small, but the idea scales. You still measure total weight, not edge count. Paths with more hops can win when they avoid 1 edges.

Deque Ordering That Matches Shortest Distance

Deque ordering is the whole trick. The deque holds nodes that still need their outgoing edges processed. The front of the deque represents the next best distance work you know about, while the back holds work that is one cost step behind.

When an edge of weight 0 improves a neighbor, the neighbor ends up with the same distance as the current node. It belongs right up front because it competes with nodes already sitting at that distance. When an edge of weight 1 improves a neighbor, the neighbor lands at distance dist[u] + 1. That belongs at the back because every node already reachable at the current distance should be handled first.

The deque operations map directly to that idea. Java’s ArrayDeque gives the calls you want, like this:

Those three lines capture the ordering rule without any sorting or heap bookkeeping. The ordering works because the only distances that get introduced from a node at distance d are d and d + 1. In a broader weight range, pushing to front or back would not keep the deque aligned with distance order.

Something that helps this feel less mysterious is to thinks of the deque as holding two bands of work at any moment. The front band is distance d, and the back band is distance d + 1. When the front band empties, the d + 1 band naturally becomes the new front band. That shift happens without moving elements around, because the deque already holds them in that order.

Why the Result Matches the Minimum Cost

This follows the same general story as Dijkstra. Keep a distance array dist[] where dist[x] is the best cost found so far from the source to x. Start with dist[source] = 0 and all other entries set to a large number. The deque starts with the source.

The loop repeatedly takes the node from the front of the deque and tries to improve its neighbors. Improving a neighbor means finding a smaller value than what is stored in dist[neighbor]. When that happens, store the new value and push the neighbor into the deque at the front or back based on edge weight.

Let’s see the core rule in the smallest useful form, without dragging in a full implementation:

The main question beginners ask is why it is safe to pop from the front without a priority queue. The answer lives in the distance steps, popping from the front always gives you some node with the smallest distance currently reachable through the deque rules. Any time a node gets a distance equal to the current best frontier distance, it gets pushed to the front, so it cannot get stuck behind nodes with larger distance. Any time a node gets a distance that is one larger, it goes to the back, which is exactly where the next distance layer belongs.

It also helps to know what you do not need. There is no requirement to mark a node final and refuse future updates. A node can appear in the deque more than once, because multiple routes can discover it. The distance check blocks stale work naturally. If a later pop reaches a node u after dist[u] has already been improved through a better route, the relax attempts compute nd values that do not beat the current dist[] entries, so nothing changes and the loop moves on.

The final state is what you want. Every dist[x] is the minimum total cost from the source to x, measured as the smallest sum of 0 and 1 weights along any route.

Mechanics in Java

Java gives you everything needed for 0 1 BFS without any special libraries. The work comes down to picking the right containers, sticking to a consistent distance rule, and keeping graph input in a form that is fast to traverse.

Data Structures for Graph Storage

Adjacency lists fit well for this algorithm. Each node stores a collection of outgoing edges, and each edge stores a destination plus a weight that must be 0 or 1. With nodes labeled 0 through n - 1, List<Edge>[] is a common layout and performs well for scanning neighbors. Distances live in an int[] dist array. Initialize every value to a large sentinel, then set the source to 0. The deque tracks which node gets processed next, and ArrayDeque is the standard choice because it supports fast operations at both ends.

This code sets up a lightweight edge type and graph creation helpers:

Directed versus undirected is decided by how you insert edges. The search logic does not change.

Core Implementation for 0 1 BFS

The loop always does the same thing. Pop the next node from the front of the deque, then try to improve distances for neighbors by relaxing outgoing edges. Relaxing means checking if dist[u] + w beats the stored distance for the neighbor. When it does, store the new distance and push the neighbor to the front for weight 0 or to the back for weight 1.

This version returns the full distance array from a source node:

INF is just a large placeholder so every node starts out as unreachable, then dist[source] = 0 marks the starting point as free to reach; the deque begins with that source so the loop has somewhere to start. Each time u is pulled from the front, du captures the best known cost to reach u, and the for loop scans every outgoing edge e to see if going from u to v improves dist[v]. The line nd = du + e.w is the whole cost rule, and the if (nd < dist[v]) check is what prevents worse routes from overwriting better ones. When an improvement happens, pushing v to the front for weight 0 keeps same cost work moving immediately, while pushing to the back for weight 1 delays that work behind all nodes that are already reachable with the current best cost.

Sometimes only one destination matters, not the full set of distances. Early exit works when the target is removed from the front of the deque, because nodes are processed in nondecreasing distance order with the deque rule. That keeps the result the same while skipping work that would only improve distances to other nodes.

This version returns the minimum cost to a target node:

The only new behavior is the early return at if (u == target) return dist[u];, which takes advantage of deque ordering. After target reaches the front, the cost stored in dist[target] cannot be beaten by some node sitting deeper in the deque, because deeper entries are either at the same cost but were placed behind by earlier pushes, or they sit at a higher cost after 1 weight pushes. The rest of the method matches the same distance update rule as the full version, so it still finds the minimum cost to the target, it just stops scanning edges once that target cost is settled.

Grid Problems as 0 1 Graphs

Grids work well because each cell maps naturally to a node, and each move to a neighbor maps to an edge. One common interpretation is that stepping into a cell costs 0 or 1, based on the destination cell value. The starting cell begins at distance 0, and every move adds the entry cost of the destination cell. Neighbors can be computed on the fly instead of stored in an adjacency list. That keeps memory lower and keeps the loop focused on scanning nearby cells.

This method computes the minimum cost to every cell from the top left. Each grid entry must be 0 or 1, and its value is treated as the cost to enter that cell:

This grid form runs the same algorithm as the adjacency list form. The only difference is where neighbors come from. Instead of iterating stored edges, it checks up to four directions and treats each valid move as an edge with weight 0 or 1.

Time and Space Complexity in Big O

Using V for the number of nodes and E for the number of edges.

Runtime is O(V + E). Each edge relaxation attempt is constant work, and the algorithm only enqueues a node when dist[v] is improved. That keeps total deque operations proportional to the number of successful improvements, which stays within O(E) in this setting. Combined with scanning adjacency lists, the total work stays O(V + E).

Space cost is O(V + E) for the adjacency list form. The distance array takes O(V), the deque can grow to O(V), and the adjacency structure takes O(V + E).

For a grid with rows * cols cells, V = rows * cols. With four directional movement, E stays proportional to V, so runtime stays linear in the number of cells and space stays linear as well.

Conclusion

0 1 BFS works because the distance values can only stay the same or go up by one when you cross an edge, so the deque naturally keeps the next best work at the front without any heap ordering. The distance array starts with a large sentinel, the source begins at zero, and every relaxation checks dist[u] + w against dist[v] before writing an update. Weight 0 updates go to the front with addFirst, weight 1 updates go to the back with addLast, and that single rule keeps nodes flowing in nondecreasing cost order. From there, the graph version and the grid version follow the same loop, just with different neighbor access, and the runtime stays O(V + E) with space O(V + E) in adjacency list form or linear in the number of grid cells when neighbors are generated on the fly.

1. Deque Interface Java SE Documentation

2. ArrayDeque Class Java SE Documentation

3. List Interface Java SE Documentation

4. Arrays Class Java SE Documentation

5. ArrayList Class Java SE Documentation

Share Alexander Obregon's Substack

Graphs pop up anywhere you have connections between things, like service dependencies, network links, or rules where two items can’t end up in the same bucket. Bipartite checks show up most in that last case, because bipartite means you can split vertices into two groups and every edge goes across the split, never staying within one group. BFS fits nicely here because it visits vertices in waves from a starting point, so assigning one color to the start and flipping the color as you step across edges stays consistent all the way through the traversal.

Subscribe now

What Bipartite Actually Means

Bipartite is a property that puts a strict rule on edges. When the property holds, every connection can be seen as linking across two groups, never staying inside the same group. Thinking in terms of group membership helps later because the check comes down to keeping one consistent rule for every edge you read.

The Two Set Rule

Bipartite means the vertices can be split into two sets where every edge goes from one set to the other. Put into everyday terms, every vertex gets one of two labels, and any pair of adjacent vertices must always end up with opposite labels. That label idea is why two-color language shows up so much. A practical way to represent the two sets is to store 1 for one side and -1 for the other side. An edge from u to v then carries a single requirement. If u has 1, v must have -1, and if u has -1, v must have 1.

Graphs with no edges are bipartite because there are no constraints to violate. Trees are bipartite because there are no cycles, so alternating labels as you move outward never forces you back into a conflicting requirement. Disconnected graphs can still be bipartite too, because the same two-set rule can be applied separately to each connected component.

Some graph details are worth calling out because they affect the rule immediately. Self-loops, meaning an edge from a vertex back to itself, make the graph non-bipartite right away. The edge would require the vertex to be opposite of itself, and that requirement cannot be satisfied. Parallel edges, meaning repeated edges between the same two vertices, do not change the outcome. They repeat the same requirement and either remain consistent or repeat the same conflict.

This helper shows the rule an edge has to follow, without doing any BFS work yet:

Unassigned values are treated as unknown, which matches how the reasoning works. Until both endpoints have labels, the edge cannot contradict anything yet. The moment both endpoints are labeled, the edge either agrees with the opposite-label rule or it does not.

Odd Cycles Create a Contradiction

Odd-length cycles are the classic reason a graph fails the bipartite test. The reason comes straight from the opposite-label rule. Moving across one edge flips the label. Moving across two edges flips twice and returns to the starting label. Moving across three edges flips again and lands on the opposite label, and that parity difference is what causes trouble when a cycle closes.

Take a cycle with three vertices. Start by assigning the first vertex label 1. The next vertex must be -1. The third vertex must be 1. When the cycle closes back to the first vertex, the closing edge demands the first vertex be -1 as well, which clashes with the original assignment. That is the entire contradiction. The same logic holds for any odd cycle length, not just triangles. Even-length cycles do not create that conflict, because an even number of flips returns you to the original label. Squares, hexagons, and other even cycles can be labeled with two sets without forcing an endpoint to change its label after the cycle closes.

This tiny utility keeps the parity idea visible without getting into traversal:

Odd cycles can sit inside much larger graphs, and the full graph does not need to be one big cycle to fail the bipartite check. One odd cycle anywhere in a component is enough, because eventually the labeling logic reaches a closing edge that requires a vertex to take a second label that disagrees with the one it already has.

Seeing the contradiction play out with explicit assignments helps cement the idea. This example hard-codes a triangle and assigns labels step by step, then checks the closing edge:

The last check prints false, because the alternating assignments around a three-edge cycle land on the same label at both endpoints of the closing edge, while the edge requires opposite labels.

Disconnected graphs follow the same rule. One component can be fully consistent while a different component contains an odd cycle. Bipartite only holds when every component can be split into two sets without contradiction, so a single odd cycle anywhere in the graph is enough to make the full graph fail.

BFS Mechanics for Two Color Labeling

Layer-based traversal works nicely for bipartite checks because every edge crossing flips the label, and BFS naturally moves outward in waves from a starting vertex. That steady outward expansion keeps the two-color rule consistent within the connected component, and it also places every edge in front of you at the moment it matters, right when you can confirm that the two endpoints still satisfy the opposite-label requirement.

Color Storage and Queue Behavior

Storing labels is the entire state of the check. One int[] works well, with 0 meaning unassigned and 1 and -1 representing the two labels. That choice keeps the state compact, and the opposite label reads naturally as a sign flip, so assigning a neighbor becomes a direct expression of the rule rather than a separate mapping step. Queue choice affects how readable the BFS loop feels. ArrayDeque<Integer> fits well because it supports efficient insert at the back and removal from the front, and it avoids the per-node overhead that comes with a linked structure. As vertices receive labels, they go into the queue, and when a vertex comes out, its neighbor list gets scanned to push the labeling outward.

The flow is consistent within a component. Pick a start vertex, assign it 1, push it into the queue, then repeat this loop until the queue is empty: pop u, scan each neighbor v, and if v has no label, assign -color[u] and push v. That is the propagation step that spreads labels through the component while preserving the two-color rule.

This helper colors a single connected component:

That sign flip color[v] = -cu is doing real work. It is both the assignment and the guarantee that every edge you traverse tries to keep endpoints opposite. Some code stores labels as booleans, but booleans still need an extra state for unassigned, and the opposite assignment tends to read less directly than a sign flip.

Conflict Detection During Traversal

Contradictions are found during edge scans, right when both endpoints already have labels. When u already has a label and neighbor v has a label too, the edge requires them to be opposites. If they match, the component is not bipartite, and continuing the traversal cannot repair that edge without breaking earlier edges that already matched.

Placing the check inside the neighbor loop keeps the logic local. The moment a bad edge is seen, the method returns false, and the caller can stop immediately instead of carrying inconsistent state forward.

Self-loops naturally fail with the same check. If a vertex lists itself as a neighbor, the labels match immediately. Parallel edges do not change the answer, because repeated edges repeat the same constraint, so they either keep agreeing or keep conflicting.

This helper keeps the rule readable without hiding it:

That helper assumes color[u] is already assigned, which matches the BFS loop where only labeled vertices are removed from the queue. Unassigned neighbors remain unknown at that moment, so a contradiction cannot be declared yet.

A short check shows how a self-loop triggers the rule without special casing:

Traversal is not introducing conflicts. The graph already contains constraints, and scanning edges reveals contradictions when an edge forces two adjacent vertices to share the same label.

Disconnected Graphs and Component Restarts

Graphs can have multiple connected components, and a single BFS run only covers the component that contains its start vertex. Any component that remains unvisited would never get labels, and a contradiction sitting in that untouched component would never be discovered. Looping through all vertices fixes that. Each time an unassigned vertex is found, it becomes the seed for a new BFS run, receives an initial label, and the traversal labels and checks that component. If any component reports a contradiction, the whole graph fails the bipartite check.

The restart loop here is short, but it is what makes the check cover every connected component in the graph:

Starting each new component with label 1 is always fine because components have no edges between them, so the label choice in one component cannot constrain another component. Isolated vertices behave well too, because an isolated vertex has no neighbors, so it gets labeled and the queue drains immediately.

Data Structures to Use

Representation choice drives neighbor scanning cost, so the storage should match what BFS does most. The traversal repeatedly takes a vertex and iterates its neighbors, so fast neighbor iteration is what matters most. Adjacency lists fit that workflow well. In Java, List<List<Integer>> is a common choice, where the outer list index is the vertex id and the inner list contains neighbor ids. Sparse graphs benefit the most, because memory tracks actual edges rather than all possible pairs, and the BFS work stays close to V + E because each adjacency entry is visited once.

Adjacency matrices like boolean[][] can be good for very small graphs because adjacency checks are direct. Memory cost grows as n * n, and neighbor scanning tends to scan a full row, which can turn the traversal into a dense operation even when few edges exist. Queue choice also matters, ArrayDeque supports addLast and removeFirst efficiently and keeps memory overhead low. LinkedList can act as a queue too, but it carries extra node objects and pointer chasing that provide no benefit for BFS.

Building the undirected adjacency list up front keeps the representation consistent and puts all edge insertion logic in one place:

Most of the work during traversal is iterating neighbor lists, so ArrayList is a good default for those inner lists. Duplicate edges do not change correctness for bipartite checks, so storing neighbors in a list is usually enough without paying hashing overhead from sets.

Time Complexity and Space Complexity

Running the bipartite check with BFS takes O(V + E) time, where V is the number of vertices and E is the number of edges. Each vertex gets labeled at most one time, and each adjacency entry gets scanned during neighbor iteration. In an undirected adjacency list, each edge appears twice, but that still stays linear in V + E, so the total work grows with the graph and its connections.

Extra working memory stays at O(V). The color array holds one integer per vertex, and the queue can hold up to V vertices in the worst case. If you include the graph storage itself, the adjacency list takes O(V + E) space, but that is the input representation rather than extra memory created by the check.

Conclusion

Two-color bipartite checks come down to one rule repeated consistently across edges. Every time you move from a vertex to a neighbor, the label flips, and BFS makes that flip easy to carry forward because vertices leave the queue in a steady order and each neighbor list gets processed exactly when its vertex is popped. Conflicts show up the moment an edge connects two vertices that already share a label, which includes self-loops and odd-cycle closures. Disconnected graphs stay covered by restarting the traversal from any vertex that still has label 0, while an adjacency list, int[] for labels, and ArrayDeque for the queue keep the work focused on scanning actual edges rather than checking every possible pair.

1. Java Platform SE Documentation

2. Java Collections Framework Overview

3. ArrayDeque JavaDoc

4. Deque JavaDoc

5. List JavaDoc

6. Graph Theory Bipartite Graph (Great for visuals!)

7. Breadth-First Search

Share Alexander Obregon's Substack

Legacy SOAP services still handle a lot of important business work, but newer client builds often prefer gRPC for quicker calls, tight contracts, and better cross language support, so a gateway service ends up as the middle layer that keeps the legacy side working while giving modern clients a nicer interface. This article is beginner friendly, so it starts with a quick overview of the gateway flow and does not assume prior experience with gRPC or SOAP.

Subscribe now

How the Gateway Works at Runtime

Think of the gateway as a translator between two contracts that do not share the same language. gRPC clients send protobuf messages over HTTP 2, the gateway receives those messages as typed Java objects, then it builds a SOAP XML request that matches the WSDL contract, sends it over HTTP, and maps the SOAP response back into a protobuf response before returning to the client.

Request Flow From Client to SOAP

Client traffic arrives as a gRPC call with a method name and a protobuf payload. The gRPC server decodes that payload into the generated request type and calls your service method. From there, the gateway has to do two jobs without letting either side leak into the other. First, it pulls inputs from the protobuf request and validates them in a way that fits the public API. Second, it translates those inputs into what the SOAP operation expects, including namespaces, wrapper elements, and the operation name that the legacy endpoint recognizes.

SOAP operations typically have a request wrapper type, and sometimes a response wrapper type too, plus XML schema details like optional elements. gRPC does not care about any of that. The gateway bridges the gap by building a SOAP request object, sending it, then extracting the SOAP response into an internal result type that maps cleanly into protobuf.

Keeping SOAP generated classes away from the gRPC surface helps a lot. One clean way to do that is to keep all SOAP object creation and extraction inside the SOAP client, then use small helper methods inside that client for the repetitive mapping work.

That helper can live next to the SOAP client and be called from inside fetchAccountSummary, so the gRPC layer never needs to touch SOAP request or response types:

public final class AccountSoapMapper {

    private AccountSoapMapper() {}

    public static com.legacy.account.GetAccountSummaryRequest toSoapRequest(String accountId) {
        var req = new com.legacy.account.GetAccountSummaryRequest();
        req.setAccountId(accountId);
        return req;
    }

    public static GatewayTypes.AccountSummary fromSoapResponse(com.legacy.account.GetAccountSummaryResponse res) {
        return new GatewayTypes.AccountSummary(
                res.getAccountId(),
                res.getStatus(),
                MoneyMapper.toMinorUnits(res.getCurrentBalance()),
                res.getCurrency()
        );
    }
}

With that separation, the service method stays focused on orchestration. It receives a protobuf request, calls the SOAP client, maps the internal result into protobuf, and returns.

@Override
public void getAccountSummary(
        GetAccountSummaryRequest request,
        StreamObserver<GetAccountSummaryResponse> responseObserver
) {
    String accountId = request.getAccountId();

    if (accountId == null || accountId.isBlank()) {
        responseObserver.onError(
                Status.INVALID_ARGUMENT.withDescription("account_id is required").asRuntimeException()
        );
        return;
    }

    try {
        GatewayTypes.AccountSummary summary = soapClient.fetchAccountSummary(accountId);

        var reply = GetAccountSummaryResponse.newBuilder()
                .setAccountId(summary.accountId())
                .setStatus(summary.status())
                .setCurrentBalance(
                        Money.newBuilder()
                                .setAmountMinor(summary.balanceMinor())
                                .setCurrency(summary.currency())
                                .build()
                )
                .build();

        responseObserver.onNext(reply);
        responseObserver.onCompleted();
    } catch (AccountSoapClient.NotFound e) {
        responseObserver.onError(
                Status.NOT_FOUND.withDescription("account not found").asRuntimeException()
        );
    } catch (AccountSoapClient.LegacyUnavailable e) {
        responseObserver.onError(
                Status.UNAVAILABLE.withDescription("legacy service unavailable").asRuntimeException()
        );
    } catch (Exception e) {
        responseObserver.onError(
                Status.INTERNAL.withDescription("gateway error").asRuntimeException()
        );
    }
}

Problem cases deserve the same attention as the successful call. gRPC completes a call when the server finishes the response observer. SOAP calls run as outbound HTTP requests that can time out, throw transport exceptions, or return SOAP faults. The gateway translates those failure modes into gRPC status codes that clients already handle well.

Later in the mapping section, the same idea is handled by a small mapper so each service method can call one helper instead of repeating Status handling in every catch block.

Protobuf as the Public Contract

Protobuf definitions act as the contract that modern clients build against, so those messages should reflect business meaning instead of XML quirks. SOAP schemas frequently have wrapper elements, optional tags, and naming choices that exist because of XML schema constraints. Protobuf does not need to copy that structure to stay correct. The gateway can keep protobuf messages stable and client friendly, then handle the SOAP specific mapping internally.

This pays off in two places, client developers see a consistent gRPC API even if the SOAP schema has awkward corners. The gateway also becomes the place where you control change, because SOAP contracts may stay frozen for years while the gRPC contract can add fields in a forward compatible way.

public final class AccountTranslator {

    private AccountTranslator() {}

    public static GetAccountSummaryResponse toGrpcResponse(GatewayTypes.AccountSummary summary) {
        return GetAccountSummaryResponse.newBuilder()
                .setAccountId(summary.accountId())
                .setStatus(summary.status())
                .setCurrentBalance(
                        Money.newBuilder()
                                .setAmountMinor(summary.balanceMinor())
                                .setCurrency(summary.currency())
                                .build()
                )
                .build();
    }
}

That translator looks intentionally plain. It makes it harder for SOAP details to creep into the protobuf contract. Extra fields in the SOAP response can stay internal until the gRPC API is ready to expose them. When the gRPC API needs a new field later, protobuf can add it without breaking older clients, and the gateway can populate it from SOAP if the data exists.

Type normalization belongs here too. SOAP commonly returns decimals for money and strings for dates or codes. Protobuf tends to work better with normalized types like integers for minor currency units or a structured timestamp type. The gateway can apply one consistent conversion rule at the boundary so clients do not repeat the same conversion work in different languages.

Deadlines and Latency Boundaries

gRPC supports deadlines, which give the server a client supplied time budget for the call. That budget matters because the gateway spends part of the request on translation and transport, then spends the rest waiting on the SOAP endpoint. SOAP does not carry a native deadline concept in the same way, so the gateway needs to connect the gRPC deadline to SOAP client timeouts and to its own behavior.

SOAP calls through WebServiceTemplate block the thread until the HTTP request finishes or times out. In Java gRPC, your service method normally runs on a worker thread, not on Netty event loop threads, so the main rule is to avoid running blocking SOAP work on an event loop if you ever configure a direct executor or otherwise move application work onto event loop threads.

Start by reading the deadline from the gRPC context. Java gRPC exposes this via io.grpc.Context. When a deadline exists, treat it as the upper bound for the call. The gateway can read the remaining time at the start and pass that value down so the SOAP client can set timeouts that fit inside the budget.

import io.grpc.Context;

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

public final class GrpcDeadline {

    private GrpcDeadline() {}

    public static Duration remainingOrNull() {
        var deadline = Context.current().getDeadline();
        if (deadline == null) return null;

        long nanos = deadline.timeRemaining(TimeUnit.NANOSECONDS);
        if (nanos <= 0) return Duration.ZERO;

        return Duration.ofNanos(nanos);
    }
}

After the remaining time is available, choose SOAP timeouts that align with it. Leaving a small buffer helps because mapping work and response write back still need time after the SOAP call returns. Without that buffer, the SOAP call can finish successfully while the gRPC deadline expires right before the response goes out, which leads to confusing client behavior.

Latency boundaries matter for another reason. The gateway adds overhead compared to direct client to SOAP calls. Some of that overhead is unavoidable, like protobuf decode and encode, XML marshalling and parsing, and network hops. Keeping that overhead predictable helps a lot. Reuse SOAP client objects, reuse JAXB contexts and marshallers, and avoid building heavy XML infrastructure per request. When the SOAP endpoint slows down, the gateway should fail fast in a consistent way, translating timeouts into DEADLINE_EXCEEDED or UNAVAILABLE rather than tying up threads until the process becomes unhealthy.

Building the Spring Boot Service

Spring Boot fits this gateway well because it gives you one process to host the gRPC server, the SOAP client, and the translation code, while still letting you separate those concerns in your own packages. Spring Boot 3 already moved the stack to the jakarta.* namespace through Spring Framework 6 and a Jakarta EE 9 baseline, and Spring Boot 4 carries that forward on Spring Framework 7 with a Jakarta EE 11 baseline, so the SOAP stack and JAXB marshalling should come from libraries in the jakarta.* generation such as Spring Web Services 4.x.

Project Setup With Modern Dependencies

Dependency choices fall into two buckets. gRPC in Java typically runs on Netty, so the service process hosts a Netty based gRPC server that accepts HTTP 2 calls and routes them to your generated service implementation. SOAP calls go out over HTTP, and Spring Web Services pairs well with WebServiceTemplate plus JAXB marshalling so request and response objects can move between Java types and XML without hand built XML strings.

Spring Boot 4.0.x expects a current toolchain, so run the gateway on Java 17 or newer and use a supported Gradle version like 8.14 or later. Getting those basics lined up early prevents confusing build errors that have nothing to do with gRPC or SOAP.

Build files vary by team, so focus on the moving parts you bring in. gRPC needs the protobuf compiler step plus the runtime libraries, while SOAP needs Spring Web Services and an XML marshaller. Lets see it in the build file so the moving parts are visible:

plugins {
  id "java"
  id "org.springframework.boot" version "4.0.3"
  id "io.spring.dependency-management" version "1.1.7"
  id "com.google.protobuf" version "0.9.6"
}

repositories {
  mavenCentral()
}

dependencies {
  implementation "org.springframework.boot:spring-boot-starter"

  implementation platform("io.grpc:grpc-bom:1.79.0")
  implementation "io.grpc:grpc-netty-shaded"
  implementation "io.grpc:grpc-protobuf"
  implementation "io.grpc:grpc-stub"

  implementation "org.springframework.ws:spring-ws-core"
  implementation "org.springframework.boot:spring-boot-starter-web-services"
  implementation "org.springframework:spring-oxm"

  implementation "org.apache.httpcomponents.client5:httpclient5:5.6"
}

protobuf {
  protoc { artifact = "com.google.protobuf:protoc:4.34.0" }
  plugins {
    grpc { artifact = "io.grpc:protoc-gen-grpc-java:1.79.0" }
  }
  generateProtoTasks {
    all().each { t ->
      t.plugins { grpc {} }
    }
  }
}

Gradle can manage BOMs with platform(), so io.spring.dependency-management is optional here.

Operational settings belong in configuration rather than scattered in constructors. gRPC has its own port and TLS story, while SOAP has endpoint URIs and timeout values that vary between environments. Centralizing those values helps prevent accidental cross environment drift:

gateway:
  grpc:
    port: 9090
  soap:
    accountServiceUri: https://legacy.example.com/AccountService
    connectTimeoutMs: 2000
    responseTimeoutMs: 3000

Proto and gRPC Service Implementation

The proto file defines the public contract. Java code is generated from it, then your service class extends the generated base type and implements the methods that clients call. That service class should stay small. Let it validate the request at the API boundary, call a SOAP client abstraction, map returned data into protobuf, then complete the gRPC response.

Proto generation creates two sets of Java types. Message types come from the message definitions, while a generated service base class comes from the service block, usually ending in Grpc with an inner ImplBase class that you extend. Keeping option java_package and option java_multiple_files set in the proto keeps generated class names and packages predictable, which makes imports and refactors less painful.

This is what that looks like in a small proto excerpt:

syntax = "proto3";

package gateway.v1;

option java_package = "com.example.gateway.v1";
option java_multiple_files = true;

service AccountGateway {
  rpc GetAccountSummary(GetAccountSummaryRequest) returns (GetAccountSummaryResponse);
}

Hosting the gRPC server inside the Spring Boot process keeps deployment smooth, but the server lifecycle still matters. Startup and shutdown should be clean so ports are not left open and in flight requests are not dropped abruptly.

Spring collects your gRPC service classes through normal component scanning. Any bean that implements BindableService can be injected into the lifecycle wrapper, which is why List<BindableService> works without extra registration code. Each service gets added to the NettyServerBuilder, and the server ends up listening on its own port, separate from any Spring MVC or WebFlux HTTP server you may run in the same process.

This server wrapper ties into Spring lifecycle hooks:

package com.example.gateway.grpc;

import io.grpc.BindableService;
import io.grpc.Server;
import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.util.List;

@Component
public class GrpcServerLifecycle implements InitializingBean, DisposableBean {

    private final int port;
    private final List<BindableService> services;
    private Server server;

    public GrpcServerLifecycle(
            @Value("${gateway.grpc.port}") int port,
            List<BindableService> services
    ) {
        this.port = port;
        this.services = services;
    }

    @Override
    public void afterPropertiesSet() throws IOException {
        var builder = NettyServerBuilder.forPort(port);

        for (var service : services) {
            builder.addService(service);
        }

        server = builder.build();
        server.start();
    }

    @Override
    public void destroy() {
        if (server != null) {
            server.shutdown();
        }
    }
}

Netty hosts the gRPC server, Spring handles startup and shutdown, and you can layer in TLS, reflection, and health checks later without changing how the server is created.

SOAP Client With Spring Web Services

Generally, SOAP integration goes smoother when the gRPC layer never touches SOAP generated types directly. Put SOAP work behind a client class that accepts plain inputs and returns a small internal value object. That client owns WebServiceTemplate, marshalling, headers, timeouts, and fault handling.

Begin with a JAXB marshaller configuration that points at the generated classes package. This example assumes your WSDL code generation step outputs JAXB annotated types into a stable package:

package com.example.gateway.soap;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;

@Configuration
public class SoapMarshallingConfig {

    @Bean
    public Jaxb2Marshaller accountServiceMarshaller() {
        var marshaller = new Jaxb2Marshaller();
        marshaller.setContextPath("com.legacy.account");
        return marshaller;
    }
}

setContextPath should match the package that contains the JAXB annotated classes generated from the WSDL. When that package is wrong, WebServiceTemplate can fail at runtime because the marshaller cannot find the types that match the XML it needs to write.

Timeouts belong on the HTTP client that backs WebServiceTemplate. With Spring Web Services 4.0.5 and newer, use HttpComponents5MessageSender for Apache HttpClient 5 configuration:

package com.example.gateway.soap;

import org.apache.hc.client5.http.config.RequestConfig;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.util.Timeout;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.ws.transport.http.HttpComponents5MessageSender;

@Configuration
public class SoapHttpConfig {

    @Bean
    public HttpComponents5MessageSender soapMessageSender(
            @Value("${gateway.soap.connectTimeoutMs}") long connectTimeoutMs,
            @Value("${gateway.soap.responseTimeoutMs}") long responseTimeoutMs
    ) {
        var config = RequestConfig.custom()
                .setConnectTimeout(Timeout.ofMilliseconds(connectTimeoutMs))
                .setResponseTimeout(Timeout.ofMilliseconds(responseTimeoutMs))
                .build();

        var client = HttpClients.custom()
                .setDefaultRequestConfig(config)
                .build();

        var sender = new HttpComponents5MessageSender(client);
        return sender;
    }
}

With those pieces in place, the SOAP client can focus on turning inputs into a request object, calling the legacy endpoint, and converting the response into a compact internal result. SOAP actions, headers, and response unwrapping tend to be where the gritty details live, and Spring Web Services can return the response object directly or wrapped in a JAXBElement depending on how the WSDL types were generated, so handling both cases keeps the call site consistent:

package com.example.gateway.soap;

import jakarta.xml.bind.JAXBElement;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
import org.springframework.stereotype.Component;
import org.springframework.ws.client.WebServiceIOException;
import org.springframework.ws.client.core.WebServiceTemplate;
import org.springframework.ws.soap.SoapMessage;
import org.springframework.ws.soap.client.SoapFaultClientException;
import org.springframework.ws.transport.http.HttpComponents5MessageSender;

import java.util.UUID;

@Component
public class AccountSoapClient {

    public record AccountSummary(String accountId, String status, long balanceMinor, String currency) {}

    public static final class NotFound extends RuntimeException {}
    public static final class LegacyUnavailable extends RuntimeException {}

    private final WebServiceTemplate template;

    public AccountSoapClient(
            Jaxb2Marshaller accountServiceMarshaller,
            HttpComponents5MessageSender soapMessageSender,
            @Value("${gateway.soap.accountServiceUri}") String uri
    ) {
        template = new WebServiceTemplate(accountServiceMarshaller);
        template.setDefaultUri(uri);
        template.setMessageSender(soapMessageSender);
        template.setInterceptors(new org.springframework.ws.client.support.interceptor.ClientInterceptor[] {
                new CorrelationHeaderInterceptor()
        });
    }

    public AccountSummary fetchAccountSummary(String accountId) {
        try {
            var request = new com.legacy.account.GetAccountSummaryRequest();
            request.setAccountId(accountId);

            Object raw = template.marshalSendAndReceive(request, message -> {
                if (message instanceof SoapMessage soap) {
                    soap.setSoapAction("GetAccountSummary");
                }
            });

            com.legacy.account.GetAccountSummaryResponse response = unwrap(raw);

            return new AccountSummary(
                    response.getAccountId(),
                    response.getStatus(),
                    MoneyMapper.toMinorUnits(response.getCurrentBalance()),
                    response.getCurrency()
            );
        } catch (SoapFaultClientException e) {
            if (faultLooksLikeNotFound(e)) {
                throw new NotFound();
            }
            throw new LegacyUnavailable();
        } catch (WebServiceIOException e) {
            throw new LegacyUnavailable();
        }
    }

    private static com.legacy.account.GetAccountSummaryResponse unwrap(Object raw) {
        if (raw instanceof JAXBElement<?> el && el.getValue() instanceof com.legacy.account.GetAccountSummaryResponse cast) {
            return cast;
        }
        if (raw instanceof com.legacy.account.GetAccountSummaryResponse cast) {
            return cast;
        }
        throw new IllegalStateException("unexpected SOAP response type: " + raw.getClass().getName());
    }

    private static boolean faultLooksLikeNotFound(SoapFaultClientException e) {
        String reason = e.getFaultStringOrReason();
        return reason != null && reason.toLowerCase().contains("not found");
    }

    static final class CorrelationHeaderInterceptor implements org.springframework.ws.client.support.interceptor.ClientInterceptor {
        @Override
        public boolean handleRequest(org.springframework.ws.context.MessageContext messageContext) {
            var request = messageContext.getRequest();
            if (request instanceof SoapMessage soap) {
                var header = soap.getSoapHeader();
                header.addHeaderElement(new javax.xml.namespace.QName("urn:gateway", "correlationId"))
                        .setText(UUID.randomUUID().toString());
            }
            return true;
        }

        @Override
        public boolean handleResponse(org.springframework.ws.context.MessageContext messageContext) {
            return true;
        }

        @Override
        public boolean handleFault(org.springframework.ws.context.MessageContext messageContext) {
            return true;
        }
    }
}

Mapping Rules, Errors, and Observability

Mapping rules are where contracts stay stable. SOAP responses can carry values as decimals, strings, or nested wrapper objects, while protobuf messages tend to favor normalized types. Money is a good example. Keeping money as minor units in protobuf avoids floating point issues, then the gateway handles decimal conversion in one place. Dates follow the same idea. Decide on a representation for the gRPC API and convert at the gateway boundary instead of pushing that work into every client.

Error mapping needs equal attention. SOAP faults, transport failures, and timeouts should become gRPC status codes that client libraries already speak. Small mapping helpers keep that logic consistent across methods, and the service implementation stays readable:

package com.example.gateway.grpc;

import com.example.gateway.soap.AccountSoapClient;
import io.grpc.Status;

import java.util.concurrent.TimeoutException;

public final class GrpcErrorMapper {

    private GrpcErrorMapper() {}

    public static Status toStatus(Throwable t) {
        if (t instanceof AccountSoapClient.NotFound) {
            return Status.NOT_FOUND.withDescription("account not found");
        }
        if (t instanceof AccountSoapClient.LegacyUnavailable) {
            return Status.UNAVAILABLE.withDescription("legacy service unavailable");
        }
        if (t instanceof TimeoutException) {
            return Status.DEADLINE_EXCEEDED.withDescription("deadline exceeded");
        }
        return Status.INTERNAL.withDescription("gateway error");
    }
}

Status becomes a gRPC error only after it is thrown as an exception. In the service method, call GrpcErrorMapper.toStatus(t).asRuntimeException() so the framework sends the status code and description back to the client. That helper can live next to the mapper so service methods stay short:

public static RuntimeException toGrpcException(Throwable t) {
    return GrpcErrorMapper.toStatus(t).asRuntimeException();
}

Observability belongs in the gateway because it touches both sides. A correlation ID should be attached to the outbound SOAP call when the legacy service can accept it, and that same value should be logged on the gRPC side so you can trace one client call through the gateway and into the SOAP dependency. Distributed tracing fits naturally too. Create a span around the outbound SOAP call, record latency and status, then propagate identifiers through headers where possible so traces link across boundaries.

Conclusion

gRPC to SOAP gateways work best when the boundaries stay tight. Protobuf stays as the public contract, the SOAP client owns XML and WSDL details, and the gateway handles translation in the middle so the two sides do not leak concerns into each other. After that, the mechanics stay pretty consistent across endpoints. Convert types in a single place, translate failures into Status in a single place, and treat deadlines and timeouts as a shared budget across the full request. When those parts stay in their lanes, service methods stay short, failure behavior stays predictable, and tracing a call from gRPC through the gateway into SOAP becomes a normal part of debugging.

1. gRPC Java Documentation

2. Protocol Buffers Language Guide proto3

3. Protocol Buffers Java Generated Code Guide

4. Spring Boot Reference Documentation

5. Spring Web Services Reference Documentation

6. Spring Web Services WebServiceTemplate API

7. Apache HttpClient 5 Documentation

8. gRPC Status Codes and io.grpc.Status

9. gRPC Java Context and Deadlines

10. OpenTelemetry Tracing Docs

Share Alexander Obregon's Substack

Starting Java can feel scattered because people talk about tools, syntax, and the JVM like they are the same thing. They connect, but they answer different beginner questions. When I teach Java through the posts in my Java Basics and Fundamentals section, I like to separate those ideas early so the rest of the learning feels less jumpy. This guide is my suggested starting route through my own articles, with a quick map of what matters first and a short set of reads to begin with in a order that makes sense.

Subscribe now

What To Learn First In Java

Java has two layers you learn at the same time. One layer is the language you type, like variables, loops, methods, objects, and strings. The other layer is how Java runs, meaning compiled bytecode, the JVM, and the tools that build and run your code. Beginners get stuck when those layers blur. Things go smoother when you have a basic idea of both in your head, then you practice small problems until the syntax starts to feel natural.

Tooling Basics To Get Out Of The Way Early

Before jumping into drills, it helps to know what you are installing and what runs your code. JDK is the developer kit that includes the compiler and tools. JVM is the runtime that executes bytecode. JRE is the runtime bundle that people still mention, and learning how it relates to the JDK clears up confusion fast when different tutorials use different terms.

Start with:

That post gives you the vocabulary you will keep bumping into, so the rest of your reading stays focused on code instead of naming.

If you want a much longer optional read that walks you through Java in one connected pass before you jump into the smaller posts, A Guide to Object-Oriented Programming in Java is a really good next stop. It covers the fundamentals in a broader arc, then you can come back to this guide and use the quick answer posts and practice posts as focused follow ups when you want repetition on one topic at a time.

Core Language Behavior That Pays Off Right Away

After the JVM and JDK terms start to make sense, it helps to zoom in on what Java is doing with objects and memory. People say new creates an object, but there is a lot packed into that one word, like constructors running, references being set up, and what it means for an object to exist long enough to be collected later. Having that picture in your head also makes it easier to debug those moments when something works differently than you expected.

Read:

It gives you a solid picture of objects and references that will keep helping as you move through the rest of the section.

Strings come next because they show up everywhere. Java strings have rules that surprise beginners, like immutability and how repeated edits create new objects. You do not need performance tuning on day one, but you do want to know what stays stable and what changes when you build and combine text.

Go next to:

It gives you a stable way to think about string behavior while you write everyday code.

Platform independence is worth reading once the JVM terms and the object model are in place. When people say write once run anywhere, they are talking about bytecode that a JVM can run on each platform, plus libraries that cover OS differences. Getting that idea into your head early helps explain why Java apps ship the way they do.

Read this next:

Practice Posts That Make Syntax Feel Normal

Concept posts give you the basic idea, then practice helps it stay with you. Small problems build comfort with loop boundaries, condition checks, indexing, and breaking work into steps without getting buried in project scaffolding.

If you want a first loop practice post, start with:

Output is easy to verify, and it reinforces loop control without extra moving parts.

If you want a first string practice post, follow with:

Reversal work forces you to think about indexing and building results without losing track of what the loop is doing.

Picking Your Next Reads Without Getting Lost

After those first posts, pick your next reads based on what you want to practice next. Number focused posts help you get comfortable with int and long, arithmetic, and edge cases. String focused posts help with scanning characters and building results. Array focused posts help you learn indexing and loops with a bit more structure.

If number work is the rough spot, start with Integer Overflow in Java Explained, then move to Adding Numbers From One to N With Java Loops, then try a check style post like Checking Armstrong Numbers with Java Logic or Checking Harshad Numbers with Java.

If string work is the rough spot, start with Checking if Text Contains Only Numbers in Java, then Counting Capital Letters in Java Strings, then Finding the First Non Repeated Character in Java Strings.

If arrays feel slippery, start with Finding the Minimum Value in a Java Array, then Finding the Sum of Odd Numbers in Java Arrays, then Reversing the Order of an Array with Java Loops.

What To Read After Java Basics And Fundamentals

When the basics start to feel natural, choose your next section based on what you want to get better at. Algorithms And Data Structures In Java is a good next stop if you want more practice turning a problem into steps, then turning those steps into working code. That section keeps you working with arrays, trees, graphs, and common problem types, so repetition builds comfort without feeling random.

If you are curious about what happens during execution JVM Internals And Class Behavior is the next section to read. It connects your source code to class files, loading, casting, and JIT behavior, so performance and memory results stop feeling random when something behaves differently than you expected.

Spring Boot reads best after you have spent time in either of those areas, because it is less about learning syntax and more about how an application is put together and how it behaves. Start with Spring Boot Project Setup And Build Work to get familiar with repo layout and build workflow, then move to Spring Boot APIs, Contracts, And Gateways when you want to think about how services communicate. Spring Boot Background Work, Async Calls, And Scheduling fits when you want to run work off the request thread, and Spring Boot Reliability, Resilience, And Performance fits when you want to reason about timeouts, pools, memory, and load.

Interview prep is also a common next step if you are practicing for coding screens. My Java LeetCode Solutions section is made for coding problem practice in Java, with problem statements broken down into steps and then translated into code you can study and reuse, with time and space complexity discussed along the way. When you want repetition on common interview themes, that section pairs well with Algorithms And Data Structures In Java.

Share Alexander Obregon's Substack

Markdown shows up in many writing tools, from blog engines to personal note apps. Projects often accept Markdown from a client, turn it into HTML on the server, sanitize the result so it is safe to render, then store or serve that HTML. With a Spring Boot REST API, this flow maps nicely onto a controller that takes Markdown in, calls a Java Markdown library, and returns sanitized HTML to whatever blog, notes app, or CMS is talking to it.

Subscribe now

Project Setup For The Markdown Service

Project structure for a Markdown to HTML API rests on a few basic choices. The stack needs a current Java version, a Spring Boot web starter for HTTP handling, and a small group of libraries that know how to parse Markdown and scrub HTML. All of that lives inside a standard Spring Boot project, so routing, configuration, and deployment behave the same way as any other REST API built on the same framework. The goal at this stage is to decide where responsibilities sit. Spring Boot takes care of HTTP, JSON mapping, lifecycle management, and dependency injection. Markdown libraries like commonmark-java and flexmark-java focus on translating text into HTML. On top of that, a sanitizer such as the OWASP Java HTML Sanitizer or Jsoup filters the HTML so only safe tags and attributes reach the client. With those three concerns mapped out, the project layout becomes more predictable and easier to extend later.

Spring Boot Dependencies For Markdown

Project creation usually starts from a standard Spring Boot starter with web support. Current releases work well with Java 17 or newer, and the spring-boot-starter-web dependency brings in Spring MVC, Jackson, and embedded Tomcat for HTTP traffic. On top of that base, the build file brings in the Markdown libraries and a sanitizer.

For example, a typical Maven pom.xml section can look like this:

This set of dependencies gives Spring Boot web support, CommonMark parsing, Flexmark parsing with a broad extension set, and a sanitizer that can strip scripts and unsafe attributes. Flexmark can stand in for CommonMark, but having both in the same project helps when a group of developers wants to compare their behavior or support different feature sets behind different endpoints.

Some projects are built with Gradle instead of Maven, and the same idea carries over with a different syntax. The build.gradle file with the Kotlin DSL can carry the same libraries in a compact form:

Both build styles place the Markdown libraries at the same level as any other dependency. Spring itself does not need any special configuration to work with them, because they are plain Java libraries without Spring specific starters.

Projects commonly rely on a small Spring Boot entry point that ties the project into a runnable application and gives the REST controller a place to live. One common layout keeps a single top level application class in the root package:

That class triggers component scanning for controllers and services in the same package tree. After the dependencies are in place and this main class exists, Spring Boot can start an embedded server, load the Markdown components, and begin handling HTTP requests.

Controller Structure For The Api

Controllers bridge the HTTP layer and the Markdown service. They accept JSON input, turn that into Java objects, call a service method, then wrap the result back into JSON. For a Markdown to HTML API, the input is usually a block of Markdown text plus optional flags, and the output is HTML text that has already passed through a sanitizer.

Input that carries only raw Markdown can be represented with a compact record:

This record pairs a field name with the Markdown text, which keeps the request body small while still working well with JSON mapping.

Many APIs also send structured HTML back instead of a bare string, which keeps the response structure flexible if extra metadata needs to appear later:

This response wrapper keeps the door open for future fields such as a content id, warnings about stripped tags, or a separate plain text preview.

The controller can then accept MarkdownRequest and return HtmlResponse while delegating all conversion details to a service bean. Routing can keep endpoints separate for CommonMark and Flexmark so clients can pick the behavior they prefer.

In this, the controller keeps HTTP concerns narrow. Parsing and sanitization stay inside MarkdownRendererSelector, while validation happens at the request edge through Bean Validation. That separation helps beginners see the boundary between the web layer and the Markdown logic.

Some projects add a small amount of validation at the controller edge, either with Bean Validation annotations or manual checks, so empty Markdown payloads do not move further into the system. Bean Validation works well in this context and stays close to the REST boundary.

With annotations like @NotBlank, Spring Boot can respond with a 400 status code when a client sends an empty string. That keeps the Markdown service from handling invalid input and keeps error handling localized near the HTTP layer.

Markdown Parsing In The API Layer

Controllers pass raw Markdown into a service, and that service turns the text into HTML before it ever reaches a template or front-end component. Parsing and rendering live in that service layer, while HTTP details stay in the controller. CommonMark Java and Flexmark Java both produce HTML from Markdown strings, and a sanitizer runs afterward so the final output is safe to embed in a browser page.

CommonMark Java Parser Flow

CommonMark defines a shared Markdown specification that many tools follow. The commonmark-java library takes a Markdown string, builds an internal node tree, and then renders that tree into HTML. Spring only needs a small service bean that holds a Parser and an HtmlRenderer and exposes a method that the controller can call.

Take this service example focused on CommonMark:

Here, the class keeps two long lived objects, the parser and the renderer, and calls them on every request that needs CommonMark output. The toHtml method receives the Markdown text from a controller or another service, builds the node tree, then turns that tree into HTML in one call.

It’s common for applications to need GitHub style Markdown features such as tables or strikethrough. CommonMark Java offers extensions that plug into the same parser and renderer builder pattern. An extension enriches the node tree with additional node types and tells the renderer how to emit HTML for them.

The configuration can grow a little as extensions come into play:

Extensions are passed into both the parser and renderer builders so the node tree and HTML output stay in sync. That alignment means a CommonMark based API can accept Markdown with tables in the request body and still produce well formed table elements in the HTML response.

CommonMark Java keeps its public API small, which suits service code that just wants to call a parser and renderer without a lot of moving parts. More advanced use cases can walk the node tree for custom processing, but a plain pipeline like this is usually enough for blog posts, documentation blocks, and note content.

Flexmark Java Parser Flow

Flexmark Java builds on the CommonMark grammar and adds a large extension family, which suits projects that want GitHub style features, table of contents generation, definition lists, and many other extras. The flexmark-all artifact pulls in the core parser, renderer, and a wide collection of extensions so the build in a Spring Boot project stays short.

Configuration begins with a MutableDataSet that carries options and the list of active extensions. That data object travels into both the parser builder and the HTML renderer builder.

The core parts fit into a service class like this:

Here the Markdown string gets parsed into a Flexmark node tree that includes extra nodes for things like tables and auto linked URLs, and then the renderer converts that structure into HTML in a single call. Extensions are centralized in the options object so the configuration for parser and renderer stays consistent.

Some APIs want to support more than one flavor and allow clients to select a style that matches their editor. That choice can sit in a higher level service that delegates to CommonMark or Flexmark based on a flag in the request.

A small dispatcher service can layer on top of the two specific services:

Controllers can accept a flavor field in the JSON body or a query parameter and then call this selector, which hands the Markdown string to the correct parser and renderer pair. That pattern keeps the parsing logic isolated in its own service classes while still allowing the API surface to grow features related to Markdown dialects.

Flexmark exposes many configuration points, such as custom link resolvers and node visitors, and those advanced hooks allow CMS or note taking tools to inject project specific behavior. The core flow in a REST API still follows a simple rhythm of parse, render, and forward the HTML to the sanitizer.

HTML Sanitization With Security In Mind

Markdown content passes through a parser and renderer before it turns into HTML, but that HTML still needs a safety pass so untrusted content cannot inject scripts or unsafe attributes into a page. Both CommonMark and Flexmark accept raw HTML in the input, and that raw HTML can contain script tags, event handlers, or links crafted to run JavaScript in the browser. Sanitization strips unsafe pieces and leaves only a set of approved elements and attributes.

OWASP Java HTML Sanitizer focuses on this exact work. The library builds a PolicyFactory by combining policies such as Sanitizers.FORMATTING, Sanitizers.LINKS, and Sanitizers.BLOCKS. The policy acts as a whitelist, and the sanitizer walks the HTML string and removes or escapes any content that does not match that configuration.

For example, a service method that takes unsafe HTML and returns a sanitized string can look like this:

Markdown text travels through parsing and rendering first, then the sanitizer removes any content that falls outside the allowed policies. A controller that calls toSafeHtml does not need to know which sanitizer implementation is in use or which HTML tags the policy accepts, which keeps those details inside the service.

Some teams prefer Jsoup for sanitization. Jsoup parses HTML into a node tree and then filters that tree through a Safelist. Current versions use Safelist rather than the older Whitelist class, and the Jsoup.clean method applies the safelist rules to produce a safer HTML string.

And a small helper built around Jsoup can look like this:

The Safelist.basic configuration permits a small set of formatting tags and links while dropping scripts and unsafe attributes. Projects that favor Jsoup as a general HTML parsing library often use this style of helper side by side with Markdown parsing to keep browser output under control.

Conclusion

The whole Markdown to HTML pipeline in this Spring Boot API comes down to a few stages where the controller accepts Markdown text, a service hands that text to CommonMark or Flexmark to build HTML, and a sanitizer such as the OWASP Java HTML Sanitizer or Jsoup removes unsafe pieces before anything reaches the browser. Keeping HTTP handling, Markdown parsing, and HTML sanitization in their own places makes the code easier to reason about and lets a blog engine, note app, or CMS plug the API in wherever rendered HTML is needed.

1. Spring Boot Reference Documentation

2. Spring Web MVC Documentation

3. CommonMark Java Project

4. Flexmark Java Project

5. OWASP Java HTML Sanitizer

6. Jsoup HTML Parser Javadoc

Share Alexander Obregon's Substack

It’s common for IoT projects to rely on MQTT brokers to move device readings, commands, and status updates between small devices and backend services. Instead of talking directly to the broker from every client, a Spring Boot gateway can sit beside it as a bridge that takes MQTT messages from devices and normalizes them into well defined objects. The gateway then serves that data over HTTP or streaming transports like WebSockets or RSocket, so constrained devices keep their lightweight MQTT link while web clients and backend systems talk to the gateway through familiar web protocols.

Subscribe now

MQTT Gateway Mechanics In Spring Boot

In a Spring Boot gateway, that service runs as an MQTT client, subscribes to device topics, receives raw payloads from the broker, and forwards them into the Spring messaging infrastructure. From there, normalizer components can turn byte arrays into typed objects, attach metadata, and hand those objects to downstream layers that eventually provide HTTP or streaming access.

Spring Integration gives this gateway a consistent way to bring MQTT traffic into Spring. The spring-integration-mqtt module wraps the Eclipse Paho client library and exposes inbound and outbound channel adapters, so the gateway code works with Spring Message objects and channels instead of talking directly to the MQTT client API all the time. This keeps the connection details, subscriptions, and message acknowledgments together in configuration classes while other parts of the code focus on parsing, validation, and storage.

Message Flow from Device to Broker To Gateway

From the device side, a tiny MQTT client publishes readings to a topic such as devices/eau-claire-sensor-01/state on a broker like Mosquitto, EMQX, or HiveMQ. The broker stores the session, handles retained messages if configured, and forwards each publish packet to any subscribed clients. One of those clients is the Spring Boot gateway, which connects with its own client identifier, subscribes to one or more topic filters, and receives MQTT packets that carry payload bytes and headers.

Topic filters such as devices/+/state use MQTT wildcards so the gateway does not need a separate subscription per device. A plus symbol in the filter matches exactly one level between slashes, which means devices/+/state matches devices/eau-claire-sensor-01/state and devices/wisconsin-sensor-02/state, while devices/# matches deeper paths as well. The gateway can combine these filters with Quality of Service levels to balance delivery guarantees against bandwidth and storage needs for a given deployment.

With Spring Integration, a configuration class defines the MQTT connection factory, the inbound adapter, and the channel where messages land. The configuration below uses DefaultMqttPahoClientFactory and an inbound adapter that subscribes to all device state messages:

This configuration treats mqttInputChannel as the handoff point between the MQTT adapter and the rest of the application. The adapter handles MQTT connection management, subscriptions, and message receipt. To keep the payload as raw bytes for the normalizer, configure the inbound adapter with a DefaultPahoMessageConverter and set payloadAsBytes to true. Anything connected to mqttInputChannel then receives Message<byte[]> instances with headers like mqtt_receivedTopic, plus related headers like mqtt_receivedQos and mqtt_receivedRetained.

Downstream, a normalizer component can subscribe to that channel and convert raw MQTT payloads into device reading objects that make sense to other services. A handler with @ServiceActivator works well for this stage:

DeviceReading can parse JSON or another encoding, pull out sensor values, and attach the device identifier derived from the topic, so the rest of the code works with a stable domain object rather than raw byte arrays. That same object later feeds REST controllers or streaming endpoints, but the translation work stays in one place near the MQTT edge.

Some projects prefer to start with a direct MQTT client before moving to Spring Integration. For a basic connection with Eclipse Paho v3 inside a Spring managed bean, is can look like this:

This style of client keeps MQTT related concerns in a single component, while other Spring beans receive decoded readings through method calls or messaging channels. Spring Integration then becomes an option when the project needs more routing, transformation, and monitoring features with less custom glue code around the client.

MQTT Version Choices 3.1.1 vs 5.0

Device fleets that talk to a broker today usually use MQTT 3.1.1 or MQTT 5.0, and a gateway has to match what the broker and devices support. Version 3.1.1 remains common in existing deployments, while 5.0 brings message properties, richer reason codes, shared subscriptions, and more detailed error reports. Both versions keep the publish and subscribe model, QoS levels, retain flags, and topic filters, but MQTT 5.0 adds structured data that helps operations and routing.

Message properties in MQTT 5.0 include user properties, correlation data, and response topics. User properties are name value pairs attached to the publish packet, and they travel with the message through the broker. Gateways can treat user properties as metadata that holds device firmware versions, tenant identifiers, or building tags, then carry those values into HTTP headers, database columns, or Spring message headers without touching the payload body.

Spring Integration adds separate adapters for MQTT v3 and MQTT v5, both inside the spring-integration-mqtt module. The v3 adapter uses MqttPahoMessageDrivenChannelAdapter, while the v5 adapter uses Mqttv5PahoMessageDrivenChannelAdapter, and the inbound MqttHeaderMapper maps MQTT PUBLISH properties, including user properties, into Spring message headers. That mapping keeps MQTT specific details near the edge of the system while letting internal components work with plain Spring messages that already have all needed metadata attached.

Now, let’s see how an MQTT 5 inbound adapter can be set up in a Spring Boot gateway:

Gateways that subscribe to devices/+/events in this way can process MQTT 5 packets and still pass byte[] payloads into the normalizer layer, while MQTT 5 PUBLISH properties, including user properties, are mapped into message headers through a HeaderMapper<MqttProperties>. Downstream handlers can read those headers and store or forward the values without parsing the payload again.

Not every gateway project uses Spring Integration for MQTT connectivity. Some prefer to interact with MQTT clients directly, in which case the choice of library matters. Eclipse Paho v3, provided by the org.eclipse.paho.client.mqttv3 artifact, speaks MQTT 3.1.1 and remains in wide use on brokers that have not moved to v5. For MQTT 5.0, Eclipse Paho offers org.eclipse.paho.mqttv5.client, and the HiveMQ MQTT Client gives a single API that can talk to both protocol versions with blocking, asynchronous, and reactive styles.

Code that uses the HiveMQ MQTT Client to connect with MQTT 5.0 and attach user properties to an outgoing message can be as simple as:

Gateways do not need to publish readings themselves if devices already send data, yet this style of code is useful when the Spring service has to push commands back to the broker while keeping track of metadata such as firmware and site for auditing or debugging.

When choosing between MQTT 3.1.1 and 5.0 for a gateway, the decision usually comes down to the broker and devices that already exist and the amount of metadata the system expects to carry in headers. Legacy hardware that only understands MQTT 3.1.1 keeps the gateway on that version, while new projects that want user properties, shared subscriptions, and richer diagnostics tend to align with MQTT 5.0. Spring Integration and modern client libraries make it possible to support both versions in a single codebase, with dedicated client beans per broker or device group.

Gateway Outputs for REST WebSocket or RSocket Clients

After MQTT messages pass through the gateway’s normalization layer, the service holds device data in a form that Java code can work with easily, such as domain objects backed by a repository or a cache. From that point, the main question turns into how different clients reach that data. Some callers only want a quick snapshot over HTTP, some browser dashboards want a continuous feed without reconnecting, and some backend services need long running streams with backpressure so they do not get flooded. Spring Boot supports all three styles inside one application. REST controllers handle request and response traffic, WebSocket endpoints carry push updates into browsers, and RSocket routes reactive streams between services that share a more advanced protocol. The MQTT gateway ends up as a hub that speaks MQTT on one side and a mix of HTTP, WebSocket, and RSocket on the other, while the normalization layer keeps the data model consistent across all three paths.

REST Endpoints for Normalized Snapshots

REST fits callers that think in terms of request and response cycles. A mobile app, a scheduled job, or a configuration panel may only need the latest device state or a small window of recent readings, and can tolerate polling every few seconds or minutes. The gateway can expose controllers that read from the normalized store and return JSON payloads without any awareness of MQTT topics or QoS flags.

One common starting point is a Spring MVC controller that fetches the most recent state for a single device. The code can lean on a service that hides persistence details:

This controller suits clients that occasionally ask for one device’s status and then disconnect again, while the service behind loadLatestState talks to a repository that was filled by the MQTT normalizer.

Gateway endpoints sometimes also expose short history ranges so clients can draw charts or run basic analytics. For example this next method returns a collection of readings for the last hour:

That method gives callers a simple query knob through the minutes parameter, while the gateway still shields them from MQTT topics, client identifiers, and any protocol specific details that the devices use.

Some projects adopt Spring WebFlux when they expect a larger number of concurrent HTTP clients or want tighter alignment with reactive repositories. With WebFlux, the same idea shows up through Mono and Flux return types instead of blocking calls:

Reactive controllers fit well when the MQTT normalization pipeline already works with Flux and Mono, because the same reactive stream can feed persistence and HTTP endpoints without extra thread handoffs.

WebSocket Streams for Browsers

Browser dashboards usually benefit from a push model where the server sends new readings as soon as they arrive, instead of waiting for clients to poll. WebSockets give a full duplex connection between browser and server over a single HTTP upgrade, and Spring’s STOMP over WebSocket support fits that need without forcing front end code to deal with binary frames directly.

In a gateway, the first step is to configure the message broker for WebSocket traffic and register a STOMP endpoint for the browser to connect to:

Front end code can connect to /ws/device-stream and subscribe to destinations that make sense for a dashboard, such as /topic/device-stream/eau-claire-sensor-01. The gateway then needs a bridge that takes normalized readings from the MQTT side and forwards them to those destinations.

One way to handle that bridge is to have the MQTT normalizer publish domain objects onto a Spring channel like deviceUpdateChannel, and then use a dedicated service to forward those objects through SimpMessagingTemplate:

Browser subscribers that point to the same destination see a JSON representation of DeviceStateDto every time the MQTT pipeline produces a new state update for that device.

Browsers sometimes also send commands back toward devices, such as toggling relays or requesting configuration changes. STOMP message mappings can handle those inbound messages on the WebSocket side, and the gateway then publishes corresponding MQTT messages to reach devices. The controller that handles those commands can look like this:

Command handling brings the gateway full circle, with MQTT traffic carrying both telemetry and control messages, while browsers only ever talk through STOMP frames over WebSocket.

RSocket Streams for Backend Services

Backend services that consume device data in bulk often need more than occasional snapshots or browser friendly feeds. RSocket addresses that by providing a binary protocol with support for request and response, request and stream, fire and forget, and bidirectional channels, all built around reactive streams semantics and backpressure. Spring Boot integrates RSocket so a gateway can expose its normalized device streams directly to other JVM services or polyglot clients that speak the protocol.

RSocket server support in Spring Boot usually lives in configuration or in properties. When the gateway runs as a separate RSocket server on a TCP port, the port and mapping are controlled through application configuration, while controllers declare message mappings for RSocket routes. Let’s see how a controller that streams device readings to a consumer service can look:

Client services that connect over RSocket can subscribe to the devices.stream.by-id route and receive a continuous Flux of device state updates, while backpressure requests from the client control how fast new elements are delivered.

Some gateways also need an RSocket path for aggregated streams that combine MQTT data from many devices. In that case, the backing service can accept filters as part of the request and route them into the reactive pipeline:

Gateway code behind streamBySite can use Reactor operators to filter, group, or window MQTT derived readings before pushing them to downstream consumers, while RSocket keeps backpressure signals flowing so slow clients do not cause unbounded queues inside the process.

Conclusion

Spring Boot MQTT gateways bring device traffic, brokers, and clients into one coherent flow built from a small set of responsibilities. The service connects as an MQTT client, subscribes to device topics over MQTT 3.1.1 or 5.0, and turns byte payloads plus message properties into normalized domain objects. Those objects move through Spring messaging into REST controllers, WebSocket broadcasts, or RSocket streams, so HTTP callers, browsers, and backend services all see the same structure while devices keep a lightweight MQTT link. With transport, normalization, and delivery held in separate layers, developers can adjust how clients reach the data without touching device firmware or broker behavior.

1. Spring Boot Reference Documentation

2. Spring Integration MQTT Module Docs

3. MQTT Version 5 OASIS Specification

4. Eclipse Paho Java Client Docs

5. RSocket Java

Share Alexander Obregon's Substack