DEV Community: Moises Gamio

Rate Limiting in Spring Boot with Bucket4j: Token Bucket Algorithm per Client

Moises Gamio — Tue, 10 Nov 2026 17:50:32 +0000

A partner company starts integrating with your API. On day one, their developer writes a loop to load test data, and suddenly your API answers slowly for every other client. Nobody attacked you: one client simply had no limit. Rate limiting controls how many requests each client may send in a given time. Requests within the limit are served; the rest get the status code 429 Too Many Requests.

This post compares the common rate limiting algorithms, then implements a token bucket per client in Spring Boot with the Bucket4j library.

Why Rate Limit Your API?

Fair use: one client's traffic can't slow down the API for everyone else.
Protect expensive resources: database queries, calls to paid third-party APIs, and CPU-heavy work.
Security: rate limiting is one of the defenses against Unrestricted Resource Consumption, number 4 in the OWASP API Security Top 10, and it slows down brute-force attacks on login endpoints.
Business plans: a free plan with 10 requests per minute and a paid plan with 1,000 is a rate limit with a price tag.

What it won't do: stop a large distributed denial-of-service (DDoS) attack. By the time a request reaches your application, it has already used your network and your servers. That protection belongs at the network level, in a CDN or a cloud firewall.

Rate Limiting Algorithms Compared

Fixed window: count the requests per client in each calendar minute and reset the counter when the minute ends. It's simple and cheap, but a client can send the full limit at 12:00:59 and again at 12:01:00, twice the limit within two seconds.
Sliding window log: store the timestamp of every request and count those in the last 60 seconds. It's exact, but it stores one entry per request.
Sliding window counter: combine the counts of the current and the previous window, weighted by time. It's a cheap and close approximation of the sliding log.
Leaky bucket: requests enter a queue that is processed at a constant rate. It smooths the traffic, but bursts wait in the queue or are dropped when it's full.
Token bucket: a bucket holds tokens; each request takes one, and tokens are added back at a fixed rate. It allows short bursts up to the bucket's capacity while keeping the average rate under control.

The token bucket is the most widely used, because real clients are bursty: a mobile app opening a screen sends five requests at once, then nothing for a minute.

How the Token Bucket Works

Imagine a bucket with a finite capacity. A refiller adds tokens at a fixed rate, and tokens that arrive when the bucket is full are discarded. Every request takes a token out. When the bucket is empty, the request is rejected until the refiller adds more tokens.

Two numbers define the limit: the capacity (the largest burst a client can send) and the refill rate (the long-term average).

Add Bucket4j to Your Project

Bucket4j is a Java rate limiting library based on the token bucket algorithm. The Java 17 build of version 8.21:

<dependency>
  <groupId>com.bucket4j</groupId>
  <artifactId>bucket4j_jdk17-core</artifactId>
  <version>8.21.0</version>
</dependency>

Or with Gradle:

implementation 'com.bucket4j:bucket4j_jdk17-core:8.21.0'

Older tutorials use the artifact bucket4j-core and the methods Bandwidth.classic(...) and Refill.intervally(...), which are deprecated in current versions. This post uses the current builder API.

A bucket with a capacity of 10 tokens, refilled with 10 tokens every minute:

Bucket bucket = Bucket.builder()
    .addLimit(limit -> limit.capacity(10).refillIntervally(10, Duration.ofMinutes(1)))
    .build();

Bucket4j offers two ways to refill:

refillIntervally(10, Duration.ofMinutes(1)) waits until the whole minute has passed, then adds all 10 tokens at once. A client that sends 10 requests in the first 15 seconds must wait 45 seconds for the next one.
refillGreedy(10, Duration.ofMinutes(1)) adds tokens gradually, one every 6 seconds. Clients get a steadier flow, and the 11th request only waits a few seconds.

The Example: A Random Quote API

The API returns a random quote about software. A repository reads the quotes from a text file, a service picks a random one, and a REST controller exposes it:

@RestController
@RequestMapping("/v1")
public class QuoteController {

  private final QuoteService quoteService;

  public QuoteController(QuoteService quoteService) {
    this.quoteService = quoteService;
  }

  @GetMapping(value = "/quotes/random", produces = MediaType.APPLICATION_JSON_VALUE)
  public Quote getQuote() {
    return quoteService.getRandomQuote();
  }
}

A client such as Postman gets a quote:

Real clients, though, are programs. In B2B integrations, developers on the client side often send hundreds of requests per minute while they test their implementation. That's the traffic we want to limit.

The Rate Limit Interceptor

A Spring MVC HandlerInterceptor runs before the controller. If its preHandle method returns false, the request never reaches the controller, which makes it the right place for the limit. The controller doesn't need to know that rate limiting exists.

We give each client its own bucket. In this example, the client is identified by its IP address. With API keys or OAuth2, the client ID is a better key.

@Component
public class RateLimitInterceptor implements HandlerInterceptor {

  private static final long CAPACITY = 10;
  private static final Duration REFILL_PERIOD = Duration.ofMinutes(1);

  // One bucket per client IP. Buckets of clients that stay idle for 10 minutes are removed.
  private final Cache<String, Bucket> buckets = Caffeine.newBuilder()
      .expireAfterAccess(Duration.ofMinutes(10))
      .maximumSize(100_000)
      .build();

  @Override
  public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String clientIp = request.getRemoteAddr();
    Bucket bucket = buckets.get(clientIp, ip -> newBucket());

    ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);
    if (probe.isConsumed()) {
      response.addHeader("X-Rate-Limit-Remaining", Long.toString(probe.getRemainingTokens()));
      return true;
    }

    long waitMillis = TimeUnit.NANOSECONDS.toMillis(probe.getNanosToWaitForRefill());
    response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value()); // 429
    response.addHeader("Retry-After", Long.toString((waitMillis + 999) / 1000)); // seconds, rounded up
    response.addHeader("X-Rate-Limit-Retry-After-Milliseconds", Long.toString(waitMillis));
    return false;
  }

  private Bucket newBucket() {
    return Bucket.builder()
        .addLimit(limit -> limit.capacity(CAPACITY).refillIntervally(CAPACITY, REFILL_PERIOD))
        .build();
  }
}

What each part does:

buckets.get(clientIp, ip -> newBucket()) returns the client's bucket, or creates a new one on the client's first request. The cache is thread-safe, so two simultaneous first requests from the same client can't create two buckets.
The cache comes from the Caffeine library. A plain HashMap would keep a bucket for every IP that ever called your API, and memory would grow forever. Here, buckets of idle clients expire after 10 minutes, which is longer than the refill period, so expiry never resets an active limit.
tryConsumeAndReturnRemaining(1) takes one token if there is one. The probe says whether it succeeded, how many tokens are left, and how long the client must wait otherwise.
The response headers tell the client where it stands. Retry-After is the standard HTTP header, in seconds, which clients and proxies understand. X-Rate-Limit-Remaining and X-Rate-Limit-Retry-After-Milliseconds give more detail.

With Spring Boot 3 or 4, the servlet classes come from jakarta.servlet. On Spring Boot 2, use javax.servlet.

The Real Client IP

Many tutorials read the client IP from the X-Forwarded-For header. Don't do this yourself. Any client can send that header with a made-up IP, a different one on every request, and is never limited.

Use request.getRemoteAddr() and let Spring Boot handle the header. When your application runs behind a load balancer or a reverse proxy, add this to application.properties:

server.forward-headers-strategy=native

The embedded server then takes the client IP from X-Forwarded-For only when the request comes from a trusted, internal proxy address. A header sent directly by a client from the Internet is ignored.

Register the Interceptor

@Configuration
public class InterceptorConfig implements WebMvcConfigurer {

  private final RateLimitInterceptor rateLimitInterceptor;

  public InterceptorConfig(RateLimitInterceptor rateLimitInterceptor) {
    this.rateLimitInterceptor = rateLimitInterceptor;
  }

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(rateLimitInterceptor).addPathPatterns("/v1/**");
  }
}

addPathPatterns applies the limit to the API only, not to health checks or documentation. Older tutorials extend WebMvcConfigurerAdapter, which was removed in Spring 6, so that code doesn't compile on Spring Boot 3 or 4.

The interceptor handles rate limiting, the controller handles HTTP, and the service handles the business logic. Each class has one job, so you can change the limit without touching the API. Designing classes this way is what my book is about:

Software design principles provide guidelines to handle the design process's complexity, prepare your code when changes arise, and minimize the impact of introducing bugs. -- Software Design Principles

See It Work

Ten requests from the same client within a minute succeed, and the 11th is rejected:

$ curl -i http://localhost:8082/v1/quotes/random
HTTP/1.1 200
X-Rate-Limit-Remaining: 9
...
HTTP/1.1 200
X-Rate-Limit-Remaining: 0

HTTP/1.1 429
Retry-After: 60
X-Rate-Limit-Retry-After-Milliseconds: 59142

A request from another client still gets 200 with X-Rate-Limit-Remaining: 9, because every client has its own bucket.

A Bug to Avoid: The Shared Bucket

An earlier version of this post, like several tutorials online, had this code:

private final Bucket defaultBucket = Bucket.builder()...build();

if (buckets.containsKey(clientIP)) {
  bucket = buckets.get(clientIP);
} else {
  bucket = this.defaultBucket;     // the same object for every new client
  buckets.put(clientIP, bucket);
}

It looks like one bucket per client, but every client gets the same bucket object. The limit is then 10 requests per minute for all clients together: in a test, client A sent 10 requests and all were served, and client B then got 0 of its 10. Always create a new bucket per client, as newBucket() does above.

Production Notes

Several instances of your API: each instance has its own buckets in memory, so with three instances a client gets three times the limit. Store the buckets in a shared store instead. Bucket4j supports Redis, Hazelcast, and databases such as PostgreSQL and MySQL.
Limits per plan: look up the client's plan and create the bucket with that plan's capacity, for example 10 requests per minute on the free plan and 1,000 on the paid plan.
Know your traffic first: before you choose limits, measure how many requests per minute your clients actually send. A hot-warm architecture in Elasticsearch is one way to store and analyze those logs.

Get the Code

The complete project, with Spring Boot 4.1, Bucket4j 8.21 and tests for the limit, is on GitHub: https://github.com/mgamio/rateLimit.

Where to Go Next

Load-test the rate limit with concurrent Java clients: simulate several clients and watch the 429 responses arrive.
Handle 503 errors in the client: retry carefully when the server is overloaded.
REST API tutorial: resources, HTTP methods and status codes, the series' starting point.

"Design a rate limiter" is one of the classic system design interview questions. Practice with real interview questions:

Originally published at codersite.dev.

Clean Code Best Practices: 10 Rules with Java Examples

Moises Gamio — Thu, 05 Nov 2026 15:50:03 +0000

Clean code is code that a developer other than its author can read, change and extend without fear. The idea was made popular by Robert C. Martin in his book Clean Code.

This post shows ten clean code rules with real Java examples, each one a before taken from production code and an after you can copy. You will learn how to:

choose names that make comments unnecessary;
split functions so each one does one thing;
replace hard-coded values without waiting for a big project;
cut long argument lists down to one object;
make a block of code read like a story.

At the end there is a code review checklist with one line per rule.

1. Use intention-revealing names

A name should tell the reader why a variable, function or class exists, what it does and how it is used. If a name needs a comment, the name is wrong.

Real code from a project:

int sId; // supplier id
int artDelPrice;

Refactored:

int supplierId;
int articleDeliveredPrice;

The same applies to types from external libraries, whose names you can't change:

private Z_E2F_RS_Result e2fResult; // ingredients record set

You can't rename Z_E2F_RS_Result, but you can name your variable after what it holds:

private Z_E2F_RS_Result ingredients;

Now imagine the original code without the // ingredients record set comment. Further down, in a loop, you find this line:

e2f = e2fResult[i];

What is e2f? Someone suggests asking the developer who wrote the code. They're not in the office. You send them an email, and the auto-reply says they're on holiday for three weeks.

With an intention-revealing name, nobody has to ask:

ingredient = ingredients[i];

Robert C. Martin spends a whole chapter of Clean Code on naming, with dozens of before-and-after examples like this one. If this rule saves you a single "what does e2f mean?" conversation, the book has paid for itself.

2. Make functions do one thing

We retrieve images from an external web service. For each image we first receive metadata: two flags that tell us whether the image is valid, and up to three image IDs from different systems. We need the first ID that isn't null.

private String retrieveImageId(String[] values) {
  if (!values[2].equals("Y") || !values[3].equals("Y"))
    return null;

  String imageId = null;
  // get the first not null value as the imageId
  if (values[4] != null) {
    imageId = values[4]; // imageAIXId
  } else if (values[5] != null) {
    imageId = values[5]; // imageLIXId
  } else if (values[6] != null) {
    imageId = values[6]; // imageOIXId
  }
  return imageId;
}

This function does two things: it validates the image and it picks the ID. Its name only mentions the second one, so a caller can't tell that null might mean "invalid image" or "no ID". Split it into two functions, each with one job and a name that says it:

private static final int AIX_IMAGE_ID = 4;
private static final int LIX_IMAGE_ID = 5;
private static final int OIX_IMAGE_ID = 6;

private boolean isValidImage(String[] values) {
  return "Y".equals(values[2]) && "Y".equals(values[3]);
}

private Optional<String> findImageId(String[] values) {
  return Stream.of(values[AIX_IMAGE_ID], values[LIX_IMAGE_ID], values[OIX_IMAGE_ID])
      .filter(Objects::nonNull)
      .findFirst();
}

A few details changed on the way:

Named constants replace the // imageAIXId comments.
"Y".equals(...) doesn't throw a NullPointerException when a flag is missing.
Optional tells the caller that there might be no ID, so they can't forget to handle it.

The caller now reads like the requirement:

public void synchronizeImages() {
  Response response = api.getImages();
  for (Row row : response.getRows()) {
    String[] values = row.getValues();
    if (isValidImage(values)) {
      findImageId(values).ifPresent(this::downloadImage);
    }
  }
}

I tested the new functions against the original one with every combination of flags and IDs, and they return the same image ID in all 32 cases.

3. Don't comment bad code, rewrite it

We request metadata for a list of articles, but the external API also returns articles we didn't ask for. Before processing a row, we check that the article is in our map of requested articles, and we add a comment so our colleagues understand why:

public void synchronizeImages() {
  Response response = api.getImages(mapOfArticles);
  for (Row row : response.getRows()) {
    String[] values = row.getValues();
    String articleId = values[1];

    // only requested articles
    if (!mapOfArticles.containsKey(articleId))
      continue;

    // code omitted for brevity
  }
}

The comment exists only because the variable name is vague. Rename the map and the comment becomes unnecessary:

public void synchronizeImages() {
  Response response = api.getImages(requestedArticles);
  for (Row row : response.getRows()) {
    String[] values = row.getValues();
    String articleId = values[1];

    if (!requestedArticles.containsKey(articleId))
      continue;

    // code omitted for brevity
  }
}

The name also drops mapOf: the type already says it's a map. Comments go out of date because nobody runs them. Names are read every time the code is read.

4. Choose simplicity over cleverness

To build an article's image URL, the image ID must be valid, and if the image is restricted, the partner must be allowed to see it. Someone wrote it as one line:

String articleImageUrl = (imageId <= 0 || (imageIsRestricted && !partnerCanSeeImage)) ? null : IMAGE_URL + imageId;

It's short, but to understand it you have to evaluate the negations in your head. Nesting if statements spells it out, but three levels deep is hard to read too. Instead, give the rule a name and write it with early returns:

private boolean canShowImage(int imageId, boolean imageIsRestricted, boolean partnerCanSeeImage) {
  if (imageId <= 0) return false;
  if (!imageIsRestricted) return true;
  return partnerCanSeeImage;
}

String articleImageUrl = canShowImage(imageId, imageIsRestricted, partnerCanSeeImage)
    ? IMAGE_URL + imageId
    : null;

Each line of canShowImage is one business rule, and you can unit test the rule on its own. I checked all 12 combinations of inputs: it gives the same result as the one-line version.

This is the KISS principle (Keep It Simple, Stupid): the simplest code is the one the next developer understands fastest, not the one with the fewest characters.

Any software design is generally a matter of opinion. There is no definitive guide. -- codersite.dev

KISS is one of the principles my book Software Design Principles covers with worked Java examples, together with DRY, YAGNI and SOLID, and twelve clean code habits like the ones in this post.

5. Avoid hard-coded values

Hard coding means writing data, such as IDs, URLs or limits, directly into the source code instead of reading it from configuration, a file or a database.

Here is how it usually happens. A company has image copyright problems with two providers and must block their images for some customers immediately. The standard process is slow: a DBA writes a database function, developers add parameter classes, and the change goes through development, test and production. There's no time for that, so a developer writes this:

boolean pictureIsRestricted = result.getProviderId() == "530636" || result.getProviderId() == "36507";

This line has two problems.

It's a bug. In Java, == compares String references, not their text. A provider ID read from a database or a web service is a new String object, so == returns false even when the text is "530636". The restricted images are shown anyway. Always compare strings with equals.

It doesn't stay in one place. Other modules need the same check, then a third provider is added, and soon the same IDs are copied into many classes. Every new provider means a code change and a deployment.

You don't need the full database project to fix this. Put the IDs in a text file, one per line, and read them behind an interface:

public interface ProviderRepository {

  Set<String> findRestrictedProviders();
}

public class FileProviderRepository implements ProviderRepository {

  private final Path file;

  public FileProviderRepository(Path file) {
    this.file = file;
  }

  @Override
  public Set<String> findRestrictedProviders() {
    try (Stream<String> lines = Files.lines(file)) {
      return lines.map(String::strip)
          .filter(line -> !line.isEmpty())
          .collect(Collectors.toUnmodifiableSet());
    } catch (IOException e) {
      throw new UncheckedIOException("Cannot read restricted providers from " + file, e);
    }
  }
}

If the file is missing, the method throws an exception instead of returning an empty list. An empty list would silently mean "no provider is restricted", and every image would be shown again.

Every class that needs the check uses the same repository:

Set<String> restrictedProviders = providerRepository.findRestrictedProviders();
boolean pictureIsRestricted = restrictedProviders.contains(result.getProviderId());

contains on a Set uses equals, so the comparison bug is gone too. The day the database function is ready, you write a DatabaseProviderRepository that implements the same interface, and no other code changes.

Small, safe steps like this one, where you change the structure without changing the behavior, are what Martin Fowler calls refactoring. His book Refactoring is a catalog of more than 60 of them, each with the motivation, the mechanics and a before-and-after example.

6. Name variables by their context

A Buyer and a Supplier both have an email address:

public class Buyer {

  private int buyerId;
  private String lastName;
  private String email;

  // code omitted for brevity
}

public class Supplier {

  private int supplierId;
  private String contact;
  private String email;

  // code omitted for brevity
}

Inside each class, email is clear: the class is the context. Don't rename the fields to buyerEmail and supplierEmail. That repeats the class name in every call, as in supplier.getSupplierEmail(), and Clean Code warns against adding this kind of redundant context.

The context gets lost in local variables, far from the object they came from:

String email = supplier.getEmail();
// 40 lines later: whose email is this?

Put the context in the variable name instead:

String supplierEmail = supplier.getEmail();
String buyerEmail = buyer.getEmail();

The rule of thumb: the further a name is used from where its context is visible, the more context the name needs.

7. Use method overloading to keep existing callers working

A method subscribes a new buyer to an external service, and it is called from many places:

public int subscribe(String email, Buyer buyer) {
  // code omitted for brevity
}

subscriberId = wsClient.subscribe(email, buyer);

Now some callers must also send a tag that tells the service what to do with the subscriber. If you add a third parameter to the method, you must change every existing caller, and most of them would pass null:

subscriberId = wsClient.subscribe(email, buyer, null);

Instead, overload the method. The new version does the work, and the old version calls it, so the logic exists only once:

public int subscribe(String email, Buyer buyer) {
  return subscribe(email, buyer, null);
}

public int subscribe(String email, Buyer buyer, Integer tagId) {
  // code omitted for brevity
}

Existing callers don't change. Only the new code that needs a tag uses the new version:

subscriberId = wsClient.subscribe(email, buyer, 102911);

8. Avoid long argument lists

A function with more than three arguments is hard to call correctly. When two arguments have the same type, nothing stops a caller from swapping them:

public boolean validateAddress(String street, int number, String postalCode, String city, String country) {
  // code omitted for brevity
}

All these arguments describe one concept, an address, so pass one object:

public record Address(String street, int number, String postalCode, String city, String country) {}

public boolean validateAddress(Address address) {
  // code omitted for brevity
}

The same idea fixes a common pattern: a method that receives a String[] and decodes each position itself:

public ListOrdersResponse listOrders(String[] values) {
  Integer buyerId = Integer.valueOf(values[0]);
  Integer supplierId = Integer.valueOf(values[1]);
  LocalDate orderDateFrom = LocalDate.parse(values[2]);
  LocalDate orderDateTo = LocalDate.parse(values[3]);
  String sortBy = values[4];
  String sortOrder = values[5];
  Integer offset = Integer.valueOf(values[6]);
  Integer limit = Integer.valueOf(values[7]);

  // code omitted for brevity
}

Replacing the array with eight separate parameters would only trade one problem for another. Instead, parse the array once into a record, and let the method receive the record:

public record ListOrdersRequest(int buyerId, int supplierId,
                                LocalDate orderDateFrom, LocalDate orderDateTo,
                                String sortBy, String sortOrder,
                                int offset, int limit) {

  public ListOrdersRequest {
    if (orderDateFrom.isAfter(orderDateTo)) {
      throw new IllegalArgumentException("orderDateFrom must not be after orderDateTo");
    }
  }

  public static ListOrdersRequest from(String[] values) {
    return new ListOrdersRequest(
        Integer.parseInt(values[0]),
        Integer.parseInt(values[1]),
        LocalDate.parse(values[2]),
        LocalDate.parse(values[3]),
        values[4],
        values[5],
        Integer.parseInt(values[6]),
        Integer.parseInt(values[7]));
  }
}

public ListOrdersResponse listOrders(ListOrdersRequest request) {
  // code omitted for brevity
}

Now the array positions are decoded in one place, the date range is checked when the request is created, and listOrders works with named values: request.buyerId(), request.limit().

9. Make code tell a story

When you fix a bug, you read the sequence of calls to understand what the program does. Requirements change over time, so code that was clear on day one slowly stops telling a clear story. Refactoring it back is part of the job.

This job sends buyer data to a partner called ACME:

ACMEWebServiceClient.login();
if (process.equals("core")) {
    ACMEWebServiceClient.transfer_buyersCoreData_to_ACME();
}
if (process.equals("status")) {
    ACMEWebServiceClient.transfer_buyersStatusChanges_to_ACME();
}
if (process.equals("events")) {
    ACMEWebServiceClient.transfer_events_to_ACME();
}
ACMEWebServiceClient.logout();

The story is hidden by three problems:

Typos fail silently. If process is "statsu", no branch runs and the job logs in and out without doing anything.
An exception skips the logout. The session stays open on ACME's side.
The names repeat themselves. Every method says ACME on a class that is already the ACME client.

Here is the same job as a story:

public enum TransferProcess { CORE, STATUS, EVENTS }

public void transferToAcme(TransferProcess process) {
  acmeClient.login();
  try {
    switch (process) {
      case CORE -> acmeClient.transferBuyersCoreData();
      case STATUS -> acmeClient.transferBuyerStatusChanges();
      case EVENTS -> acmeClient.transferEvents();
    }
  } finally {
    acmeClient.logout();
  }
}

Read it aloud: log in, transfer the chosen data, always log out. Converting the input with TransferProcess.valueOf(process.toUpperCase()) throws an exception for an unknown value like "statsu", so a typo fails at once instead of doing nothing. The finally block logs out even when a transfer throws an exception.

10. Copy one constant instead of keeping a dead library

We migrate an application to a new application server and find out that a library it uses is no longer supported there:

import org.apache.axis.transport.http.HTTPConstants;

HttpServletRequest httpServletRequest =
    (HttpServletRequest) context.get(HTTPConstants.MC_HTTP_SERVLETREQUEST);

We spend a lot of time looking for a compatible version of Apache Axis. Then we notice that the whole application uses only one thing from that library: the MC_HTTP_SERVLETREQUEST constant, whose value is the string "transport.http.servletRequest".

The simple solution is to declare that constant in our own code:

public final class AxisContextKeys {

  // Same value as org.apache.axis.transport.http.HTTPConstants.MC_HTTP_SERVLETREQUEST
  public static final String SERVLET_REQUEST = "transport.http.servletRequest";

  private AxisContextKeys() {}
}

HttpServletRequest httpServletRequest =
    (HttpServletRequest) context.get(AxisContextKeys.SERVLET_REQUEST);

Before you remove the library, search the whole code base for other org.apache.axis imports. If this was the only one, the dependency can go, and the migration is no longer blocked by a library nobody maintains.

Clean code review checklist

Copy this list into your next code review. Each line is one of the rules above.

Names: can you understand every name without a comment?
One thing: does each function do what its name says, and nothing else?
Comments: does any comment explain something a better name could say?
Simplicity: can you read each condition aloud as a business rule?
Hard coding: are IDs, URLs and limits read from configuration, compared with equals, and kept in one place?
Context: do local variables far from their object say where they came from?
Callers: does a new parameter force changes on callers that don't need it?
Arguments: does any function take more than three arguments, or decode array positions?
Story: can you read the main flow aloud, and is cleanup in a finally block?
Dependencies: does a large library stay in the project for one constant or one small helper?

Clean code is one habit of a professional developer. The Pragmatic Programmer covers the rest: taking responsibility for your code, avoiding duplication, testing and automating, and knowing when code is good enough to ship. It's the book I recommend after Clean Code.

FAQ

What is clean code?

Clean code is code that another developer can read, understand and change safely. It has intention-revealing names, small functions that do one thing, no duplication, and tests. The term comes from Robert C. Martin's book Clean Code: A Handbook of Agile Software Craftsmanship (2008).

Does clean code mean no comments?

No. Clean code avoids comments that explain what the code does, because a better name or a smaller function can say that. Comments that explain why, such as a business rule, a legal requirement or a workaround for a bug in a library, are still useful. The // Same value as ... comment in rule 10 is an example.

Is clean code slower?

Almost never in a way you can measure. Small functions and named variables are optimized by the JIT compiler. Performance problems usually come from algorithms, database queries and network calls, which are easier to find and fix in clean code. See how to optimize Java application performance.

How do I start cleaning an existing code base?

Don't rewrite it. Follow the Boy Scout Rule: leave every file you touch a little cleaner than you found it. Rename one variable, extract one function, add one test. Small refactorings in the code you're already changing add up, and they're easy to review.

How does clean code relate to SOLID?

Clean code works at the level of names, functions and classes. SOLID works at the level of classes and their dependencies. Rule 5 above, with its ProviderRepository interface, is the dependency inversion principle in practice. See SOLID principles: the definitive guide.

Originally published at codersite.dev.

How a REST Client Should Handle 503 Service Unavailable: Retries with Backoff in Spring

Moises Gamio — Mon, 02 Nov 2026 12:32:09 +0000

Your nightly job sends 50,000 articles to a partner's API, in batches of 1,000. At batch 23, the API answers 503 Service Unavailable. What should your client do? Give up, and the data is incomplete. Retry immediately, and you make an overloaded server even slower. This post shows how a REST client should handle a 503: which errors to retry, how long to wait, and how Spring Framework 7 does it with one annotation.

What a 503 Means

The HTTP status code 503 Service Unavailable says that the server can't handle the request right now, but probably will later. Common causes:

The server is down for scheduled maintenance.
The server is overloaded by too much traffic.
A service the server depends on, such as a database or another API, is failing.

The server may add a Retry-After header that says how long to wait. The important word is temporarily: a 503 is an invitation to try again later, not a final answer.

The Client Can't Control the Server

Business-to-business (B2B) integrations are a typical case. One company's application is the client, the other company's API is the server, and the client has no say in how the server is built, deployed or scaled.

The first version of our client caught the exception, wrote it to the log and continued with the next batch. The job finished "successfully", and 1,000 articles were silently missing. Somebody had to read the logs, call the partner company, and send the batch again by hand.

The opposite reaction is just as bad: retrying in a tight loop, three times in a row without a pause. A server that's overloaded receives even more requests, exactly when it can handle the fewest. If hundreds of clients do the same, they keep the server down.

Which Errors Should You Retry?

Retry only when the same request has a real chance of succeeding later:

Response	Retry?	Why
503 Service Unavailable	Yes	Temporary by definition
429 Too Many Requests	Yes	Wait until your limit resets
502 Bad Gateway, 504 Gateway Timeout	Yes	Usually a temporary network or proxy problem
Timeout, connection refused	Yes	The server may be restarting
400, 401, 403, 404, 422	No	The same request will fail again
500 Internal Server Error	With care	Can be a bug, which a retry won't fix

Is the request safe to repeat? GET, PUT and DELETE are idempotent: sending them twice has the same effect as sending them once. Our request is a POST, but it's a search, so repeating it changes nothing. A POST that creates something, such as an order, is different: if the first attempt actually reached the server and only the response got lost, a retry creates a second order. APIs solve this with an idempotency key, a unique ID the client sends with the request, so the server can recognize a repeated request.

A Retry Loop with Backoff

A good retry waits longer after each failure (exponential backoff: 1, 2, 4 seconds...), adds a random part to each delay (jitter, so that many clients don't retry at the same moment), respects the server's Retry-After header, and gives up after a few attempts. Here it is with Spring's RestClient:

public class ArticlesClient {

  private static final Logger logger = LoggerFactory.getLogger(ArticlesClient.class);

  private static final int MAX_ATTEMPTS = 4;
  private static final Duration INITIAL_DELAY = Duration.ofSeconds(1);
  private static final Duration MAX_DELAY = Duration.ofSeconds(30);
  private static final Set<Integer> RETRYABLE_STATUS_CODES = Set.of(429, 502, 503, 504);

  private final RestClient restClient;

  public ArticlesClient(RestClient restClient) {
    this.restClient = restClient;
  }

  public SearchResponse searchArticles(List<String> articleNumbers) {
    for (int attempt = 1; ; attempt++) {
      try {
        return restClient.post()
            .uri("/articles/search")
            .contentType(MediaType.APPLICATION_JSON)
            .body(new SearchRequest(articleNumbers))
            .retrieve()
            .body(SearchResponse.class);
      } catch (RestClientException e) {
        if (attempt == MAX_ATTEMPTS || !isRetryable(e)) {
          throw e;
        }
        Duration wait = retryAfter(e).orElse(backoff(attempt));
        if (wait.compareTo(MAX_DELAY) > 0) {
          throw e;   // the server asks us to wait longer than we're willing to
        }
        logger.warn("Attempt {} of {} failed: {}. Retrying in {} ms",
            attempt, MAX_ATTEMPTS, e.getMessage(), wait.toMillis());
        sleep(wait);
      }
    }
  }
}

The helper methods decide whether and how long to wait:

private static boolean isRetryable(RestClientException e) {
  if (e instanceof RestClientResponseException responseError) {
    return RETRYABLE_STATUS_CODES.contains(responseError.getStatusCode().value());
  }
  return e instanceof ResourceAccessException;   // timeout, connection refused
}

// 1 s, 2 s, 4 s ... up to MAX_DELAY, each with random jitter between half and the full value
private static Duration backoff(int attempt) {
  long cap = Math.min(MAX_DELAY.toMillis(), INITIAL_DELAY.toMillis() << (attempt - 1));
  return Duration.ofMillis(ThreadLocalRandom.current().nextLong(cap / 2, cap + 1));
}

// Retry-After is either a number of seconds or an HTTP date
private static Optional<Duration> retryAfter(RestClientException e) {
  if (!(e instanceof RestClientResponseException responseError) || responseError.getResponseHeaders() == null) {
    return Optional.empty();
  }
  String value = responseError.getResponseHeaders().getFirst(HttpHeaders.RETRY_AFTER);
  if (value == null) {
    return Optional.empty();
  }
  try {
    return Optional.of(Duration.ofSeconds(Long.parseLong(value.trim())));
  } catch (NumberFormatException notSeconds) {
    try {
      ZonedDateTime retryAt = ZonedDateTime.parse(value.trim(), DateTimeFormatter.RFC_1123_DATE_TIME);
      Duration wait = Duration.between(ZonedDateTime.now(), retryAt);
      return Optional.of(wait.isNegative() ? Duration.ZERO : wait);
    } catch (DateTimeParseException invalid) {
      return Optional.empty();
    }
  }
}

private static void sleep(Duration duration) {
  try {
    Thread.sleep(duration);
  } catch (InterruptedException e) {
    Thread.currentThread().interrupt();
    throw new IllegalStateException("Interrupted while waiting to retry", e);
  }
}

The request and response are records:

public record SearchRequest(List<String> articleNumbers) {}
public record SearchResponse(List<Article> articles) {}
public record Article(String articleNumber, String name) {}

Don't Lose the Batches That Still Fail

Even with retries, a batch can fail, for example when the partner's API is down for an hour. Then the job must keep the data, not only a log line:

public List<List<String>> searchAll(List<String> articleNumbers) {
  List<List<String>> failedBatches = new ArrayList<>();
  for (int from = 0; from < articleNumbers.size(); from += BATCH_SIZE) {
    List<String> batch = articleNumbers.subList(from, Math.min(from + BATCH_SIZE, articleNumbers.size()));
    try {
      SearchResponse response = articlesClient.searchArticles(batch);
      save(response.articles());
    } catch (RestClientException e) {
      logger.error("Batch starting at {} failed after all retries: {}", from, e.getMessage());
      failedBatches.add(List.copyOf(batch));   // keep the data: retry later or report it
    }
  }
  return failedBatches;
}

The caller can store the failed batches in a table, send them again in the next run, or notify the team. In each case, nobody needs to search the logs.

Try It

I ran the client against a local test server that answers 503, then 503 with Retry-After: 2, then 200:

server: call 1 -> 503
WARN ArticlesClient -- Attempt 1 of 4 failed: 503 Service Unavailable: [no body]. Retrying in 618 ms
server: call 2 -> 503 (Retry-After: 2)
WARN ArticlesClient -- Attempt 2 of 4 failed: 503 Service Unavailable: [no body]. Retrying in 2000 ms
server: call 3 -> 200
result: SearchResponse[articles=[Article[articleNumber=4711, name=Potatoes]]]

The first wait is a random value from the backoff, and the second is exactly the 2 seconds the server asked for. In the other test runs, a 400 Bad Request failed immediately without a retry, a server that always answered 503 got four attempts with growing delays (0.8 s, 1.6 s, 2.1 s) before the client gave up, and a Retry-After of 120 seconds made the client stop instead of waiting.

To see a real 503 response, use the public test service httpbin.org:

$ curl -i https://httpbin.org/status/503
HTTP/1.1 503 SERVICE UNAVAILABLE
Content-Length: 0

The Spring Framework 7 Way: @Retryable

Since Spring Framework 7 (Spring Boot 4), retries are built into Spring itself, with no extra library. Enable them once:

@Configuration
@EnableResilientMethods
public class ResilienceConfig {
}

Then annotate the method:

@Service
public class ArticlesService {

  private final RestClient restClient;

  public ArticlesService(RestClient restClient) {
    this.restClient = restClient;
  }

  @Retryable(
      includes = {
          HttpServerErrorException.ServiceUnavailable.class,   // 503
          HttpServerErrorException.BadGateway.class,           // 502
          HttpServerErrorException.GatewayTimeout.class,       // 504
          HttpClientErrorException.TooManyRequests.class,      // 429
          ResourceAccessException.class },                     // timeout, connection refused
      maxRetries = 3,
      delay = 1000,
      multiplier = 2,
      maxDelay = 30_000,
      jitter = 250)
  public SearchResponse searchArticles(List<String> articleNumbers) {
    return restClient.post()
        .uri("/articles/search")
        .body(new SearchRequest(articleNumbers))
        .retrieve()
        .body(SearchResponse.class);
  }
}

In my test, this method also received 503, 503 and 200, with retries after about 1 and 2 seconds, and a 400 was not retried. The method itself contains no retry logic at all.

Which one should you use? @Retryable is shorter and keeps the business code clean, and it's the right choice in most cases. It can't read the Retry-After header, though, because it only sees the exception type. When an API sends Retry-After, typically with 429 and 503, the loop above respects it. On Spring Boot 3, the Spring Retry library offers a similar @Retryable.

Best Practices Checklist

Retry only errors that can succeed later: 429, 502, 503, 504 and timeouts.
Wait with exponential backoff and jitter, and respect Retry-After.
Limit the number of attempts and the longest wait.
Make sure a repeated request is safe; use idempotency keys for requests that create data.
Never lose data: keep failed requests for a later retry or a report.
On the server side, return Retry-After with your 503 and 429 responses. The rate limiting post shows how, and you can load-test it with concurrent clients.

"What happens when the service you call is down?" is a standard question in backend and system design interviews. Practice with real interview questions:

Originally published at codersite.dev.

From O(n ) to O(n): Replace Nested Loops with a HashMap in Java

Moises Gamio — Thu, 29 Oct 2026 11:07:55 +0000

One endpoint in a B2B order system I worked on returned 1,000 orders, and it was slow. The database wasn't the problem. Two innocent-looking nested loops were. Here's how one data structure, the HashMap, turned 2,000,000 comparisons into about 3,000.

A List data structure is an ordered collection of items, where each item has a specific position or index within the list.

A HashMap is a data structure that stores key-value pairs, enabling efficient retrieval of values based on their keys. It uses a hash function to determine the storage location (or "bucket") of each key-value pair within an underlying array, allowing for fast lookups, insertions, and deletions.

Use Case

We have a RESTful API endpoint to retrieve a list of orders placed by a given buyer.

The response includes different kinds of addresses per order, as you can see in the following schema:

[
  {
    "orderId": 123456,
    "buyerId": 1234,
    "customerNumberId": 12,
    "supplierId": 1,
    "orderDate": "2025-05-15",
    "orderDeliveryAddress": {
      "company": "string",
      "contact": "string",
      "countryCode": "string"
    },
    "orderInvoiceAddress": {
      "company": "string",
      "contact": "string",
      "countryCode": "string"
    },
    "desiredDeliveryDate": "2025-05-16",
    "orderPositions": [
      {
        "orderPositionNumber": 1,
        "orderPositionArticle": {
          "articleId": 4531
        },
        "orderPositionQuantity": 10
      }
    ]
  }
]

As you know, REST Controllers normally delegate the data retrieval to backend services.

To build the body of the list of orders, the backend service calls different database functions to retrieve data. One of these calls is to recover all historical addresses per orderId.

public List<Order> listOrders(Integer buyerId) {

  List<Order> listOfOrders = getOrdersByBuyerId(buyerId);

  //code omitted for brevity

  //retrieve headers and enrich listOfOrders
  //retrieve addresses and enrich listOfOrders
  //retrieve positions and enrich listOfOrders

  return listOfOrders;
}

If the user requests the first 1000 orders, the backend makes only one database function call to retrieve 2000 records (2 different addresses per orderId).

{
  //retrieve addresses
  Address[] listOfAddresses = getAddresses(order1, order2, ... order1000);
}

Here is the Object model to represent an Address:

public class Address   {
  private Integer orderId;
  private Integer addressId;
  private Integer type;
  private String company;
  private String contact;
  private String countryCode;
}

The problem comes when we need to include two loops nested in the code to assign the addresses to every order.

//retrieve addresses and enrich listOfOrders
for (Order order : listOfOrders) {
  for (Address address : listOfAddresses) {
    if (order.getOrderId().equals(address.getOrderId())) {
      switch(TYPEOFADDRESS.valueOf(address.getType())) {
        case DELIVERY:
        {
          //assign address to order
          break;
        }
        case INVOICE:
        {
          //assign address to order
          break;
        }
        default:
        {
          //assign null to order
          break;
        }
      } 
    }
  }
}

That means that the performance according to Big O Notation is N x N = O(N²).

This is exactly the kind of design decision that separates code that works from code that scales. Real-world cases like this one, with diagrams and explanations, fill Software Design Principles: A Practical Guide:

HashMap to the rescue

We need a fast lookup to iterate exactly the two addresses per order in sequential mode.

A HashMap allows us to associate values (the two addresses) with a unique key (orderId). So here is our new data structure:

HashMap<Integer, List<Address>> hashMapOfAddressesByOrderId = new HashMap<>();

We implement an algorithm to transform a List into a HashMap.

private HashMap<Integer, List<Address>> transformListToHashMap(Address[] listOfAddresses) {

  HashMap<Integer, List<Address>> hashMapOfAddressesByOrderId = new HashMap<>();

  for (Address address : listOfAddresses) {
    List<Address> listOfAddressesInHashMap = hashMapOfAddressesByOrderId.get(address.getOrderId());
    if (listOfAddressesInHashMap == null) {
        listOfAddressesInHashMap = new ArrayList<>();
        listOfAddressesInHashMap.add(address);
    } else {
        listOfAddressesInHashMap.add(address);
    }
    hashMapOfAddressesByOrderId.put(address.getOrderId(), listOfAddressesInHashMap);
  }

  return hashMapOfAddressesByOrderId;
}

Here is our new iteration through the new data structures.

//retrieve addresses and enrich listOfOrders

HashMap<Integer, List<Address>> hashMapOfAddressesByOrderId = transformListToHashMap(listOfAddresses);

for (Order order : listOfOrders) {

  List<Address> listOfAddressesInHashMap =
      hashMapOfAddressesByOrderId.getOrDefault(order.getOrderId(), List.of());

  for (Address address : listOfAddressesInHashMap) {

    switch(TYPEOFADDRESS.valueOf(address.getType())) {
      case DELIVERY:
      {
        //assign address to order
        break;
      }
      case INVOICE:
      {
        //assign address to order
        break;
      }
      default:
      {
        //assign null to order
        break;
      }
    } 
  }
}

getOrDefault returns an empty list for an order without addresses, so the loop simply doesn't run instead of throwing a NullPointerException.

The Java 8 One-Liner

Map<Integer, List<Address>> addressesByOrderId =
    Arrays.stream(listOfAddresses)
          .collect(Collectors.groupingBy(Address::getOrderId));

Same result, same O(N) cost. The loop above shows what's happening under the hood, and groupingBy is what you'd write in production.

Performance Comparison

Approach	Operations for 1,000 orders and 2,000 addresses	Big O
Nested loops	1,000 × 2,000 = 2,000,000 comparisons	O(N × M)
HashMap	2,000 inserts + 1,000 lookups ≈ 3,000 steps	O(N + M)

The new performance according to Big O Notation is linear: O(N).

The main idea in Analysis of Algorithms is always to improve the algorithm performance, by reducing the number of steps and comparisons. -- codersite.dev

When to use each

Use a List when:

You care about the order of elements.
You need to store duplicates.
You iterate over elements in a sequential manner.

Use a HashMap when:

You need to associate values with unique keys.
You need fast lookup, insertion, or deletion by key.
The data is best represented in a key-value format.

Replacing a nested loop with a HashMap is one of the most common optimizations interviewers look for. If you have interviews coming up, practice it on real questions:

Originally published at codersite.dev.