Implementing Throttling in Java (Spring Boot)

Heshan Sudarshana
Published in
3 min readDec 4, 2018


Wonder what’s throttling is? Or you have an understanding of throttling, but struggling to implement it in Java Spring Boot? Then this might be the article you were looking for!

What is Throttling?

Throttling is the process of limiting the rate that an API is being used in a server. It limits the number of service requests which can be executed in a unit time (for a second, minute..).

Simple flow of throttling

As the definition suggests, throttling is essential to limit the load on a server and to keep it performing smoothly. In this article I will go through two methods, I have used to do throttling.

  1. RateLimitter
  2. weddini/spring-boot-throttling library

RateLimitter Class (Guava)

RateLimitter is a class from Guava library for Java. You can implement throttling using RateLimitter by following the simple steps below.

  1. Add maven dependency

2. Create an instance of RateLimitter class declaring the rate of execution

RateLimitter class is based on permits. Thus when you instantiate an object from the class, you have to give the number of permits allowed per second. (i.e. If you create a RateLimitter with 5 permits, it means that you are basically allowing 5 requests per second max)

Furthermore, not only we can limit the number of requests per second, but also we can limit the number of bytes that flows through, if we are producing a stream of data. The constructor is the same in both scenarios.

3. Acquire a permit and use it

acquire() method is used to acquire permits from the RateLimitter object. Therefore acquire(3) means that the acquiring of 3 permits. (In simple terms, if there were 5 permits left, after acquiring 3 permits, another task of 3 permits will not be performed until a previous task is completed and the permits are released). Thus, acquiring a permit or multiple permits does not affect throttling of that particular request. acquire() without parameters is equivalent to acquire(1).

The specialty of this implementation is that it maintains a smooth performance by using waits. Unlike in normal throttling, the request is not
terminated and it is taken to the next unit time to be executed.

To study this method in-depth I recommend you to read the official documentation from here.

weddini/spring-boot-throttling Library

When we consider about throttling and rate limiting in Spring Boot, there is another opensource library named spring-boot-throttling. Following the steps below, you will be able to implement a simple throttling mechanism in Spring Boot.

  1. Add maven repository and dependency

2. Use @Throttling annotation to implement throttling

You can implement throttling by adding @Throttling annotation to the service method of the request that should be throttled.

As you can see @Throttling annotation alone is equivalent to the annotation below with parameters. The default is 1 method call per second. Thus by changing the type, limit and timeUnit you can customize the throttling as you wish.

3. Error Handling

Unlike in the previous method, this library will work like a conventional throttling mechanism terminating/rejecting the requests after exceeding the configured limit for a unit time. ThrottlingException is thrown when the throttling limit is reached and the serviceMethod() will not be executed.

You can study about the different types of throttling that can be implemented using this library from the GitHub repository here.

Using these methods you can implement a simple throttling mechanism in Java/Spring Boot. Hope this will help! :)