DEV Community: Ahmed Jaad

Designing and Implementing an API Rate Limiter

Ahmed Jaad — Sun, 19 Jan 2025 22:52:55 +0000

The implementation is available on GitHub.
Introduction
Understanding the Architecture of an API Rate Limiter
What is Throttling?
Client Responsibilities
Designing the Application
Introduction

Introduction

APIs serve as the backbone of modern software systems, enabling communication between different applications. However, without proper control, APIs can be overwhelmed by excessive requests, potentially leading to degraded performance or even downtime. This is where API rate limiting comes into play.

API rate limiting is a mechanism that restricts the number of requests a client can make to an API within a specified time period. By doing so, it ensures fair usage among clients, protects system resources, and maintains service stability. In this article, we will first explore important concepts(components) relevant to API rate limiting, and then we see the design and implementation of an API rate limiter using the Spring framework and Redis. The full implementation code is available on GitHub.

Why Should You Rate Limit Your API?

APIs are integral to many businesses, and their reliability is critical. Implementing a rate limiter provides several benefits:

Enhancing Security: Rate limiting prevents denial-of-service (DoS) attacks by limiting the number of requests a malicious user can make.
Mitigating Noisy Neighbors: In multi-tenant systems, one client’s excessive use should not degrade the performance experienced by others.
Preventing Resource Starvation: Rate limiting ensures that API consumers cannot monopolize resources, safeguarding the infrastructure from being overwhelmed.

Understanding the Architecture of an API Rate Limiter

A robust API rate limiter consists of several key components working together to manage and enforce rate limits. Let’s delve into the architecture:

Load Balancer

A load balancer is a standard component in distributed systems. It evenly distributes incoming network traffic across multiple service instances to ensure reliability and scalability. In the context of rate limiting, it ensures that no single instance of the rate limiter or the protected API server is overwhelmed.

Rate Limiter

The rate limiter is the core component. It intercepts requests before they reach the protected API server (often called the Request Processor). Based on predefined rules, the rate limiter decides whether to allow or throttle requests. Throttling may involve rejecting requests or queuing them for later processing.

Request Processor

This is the actual API server that processes valid requests. In our prototype, the rate limiter and the request processor are combined for simplicity. However, in real-world scenarios, these are often separate applications.

Redis as a Distributed Cache

Redis is used to store and sync rate limit states across distributed instances of the rate limiter. It ensures that all instances share a consistent view of the rate limits, making the system scalable and fault-tolerant.

Rules Engine Service and Database

The rules engine service defines the rate-limiting policies, such as the maximum number of requests allowed per time window and the actions to take when limits are exceeded. For brevity, our prototype uses hardcoded rules, but in a production-grade system, these rules would be dynamically retrieved from a database.

Queue

A queue can serve multiple purposes, such as:

Temporarily holding requests during high traffic periods for later processing.
Implementing soft throttling by delaying requests instead of outright rejecting them.

High-Level Architecture

What is Scaling and How Is It Implemented?

Scaling refers to the ability of a system to handle increasing amounts of workload by adding resources. In the context of an API rate limiter, scaling ensures that the system can manage growing traffic without performance degradation. There are two types of scaling:

Vertical Scaling: Adding more resources (e.g., CPU, memory) to a single instance. While straightforward, it has physical limits and can become costly.
Horizontal Scaling: Adding more instances of a service to distribute the workload. This is the preferred approach for modern distributed systems as it offers better resilience and flexibility.

In our implementation, horizontal scaling is achieved by:

Deploying multiple instances of the rate limiter, each paired with a request processor.
Using Redis as a distributed cache to synchronize rate limit states across all instances.

Scaling

What is Throttling?

Throttling is the process of regulating the rate of incoming requests to an API. When a client exceeds its allowed quota, throttling mechanisms decide how to handle the excess requests. There are two main strategies:

Hard Throttling

Hard throttling enforces strict limits. Once a client reaches its quota, any additional requests are immediately rejected. This approach is straightforward and is typically applied to general or untrusted clients.

Soft Throttling

Soft throttling provides a more lenient approach, especially for premium or trusted clients. Instead of outright rejecting requests, soft throttling may:

Allow a certain percentage of excess requests to pass through.
Queue excess requests for processing once traffic subsides.

The choice between hard and soft throttling depends on business requirements. For instance, a subscription-based service might implement soft throttling for premium users to enhance their experience, while applying hard throttling for standard users.

Client Responsibilities

To ensure the effectiveness of the rate limiter, clients should adopt best practices:

Exponential Backoff: Retry requests after progressively longer delays when encountering failures. This reduces server load and avoids immediate retries.
Jitter: Add random delays (Jitter) to retry intervals to prevent simultaneous retries from multiple clients, which can overwhelm the server.

Designing the Application

High-Level Architecture

Our application’s architecture is simplified for clarity and practicality, with some components removed or merged:

The RateLimiter (under the api_rate_limiter package) and RequestProcessor (under the request_processor package) are combined into a single Spring Boot application. In real-world scenarios, these two components might exist as separate applications.
The application does not include a Load Balancer or a Queue.
Rules are hard-coded, eliminating the need for a Rules Service and a Rules Engine Database.
Distributed caching is supported using Redis. However, for scenarios where Redis is unavailable, an alternative approach is provided with a standalone runtime profile, where rules are stored in the application’s memory.

All applicable rules, including system-wide and tenant-specific rules, are applied dynamically. This ensures fair and precise enforcement of rate limits for every tenant.

Domain Modeling

The application revolves around a few core domain entities:

RateLimit: Defines the properties of a rate limit, such as capacity and time period.
TenantRateLimit: Represents the rate limits applicable to a specific tenant. It includes properties for monthly and time-window limits.
Bucket: Tracks the live state of rate limits for each tenant. There is also a system-wide bucket for global limits.

Domain Model

Service Interactions

TenantBucketProvider: This is the actual service that the Rate Limiter relies on to make the decision whether to let a request through or not. Manages the limit states for tenants. It has two implementations:
1. StandaloneBucketProvider: Uses in-memory storage, suitable for standalone applications but not scalable.
2. RedisBucketProvider: Uses Redis for distributed environments, enabling horizontal scalability.
ApiServerSender: Forwards valid requests to the protected API server.

Services Interactions

Endpoints

The application includes a RateLimitController, which processes requests matching /api/v1/**. It checks the tenant’s bucket state using the TenantBucketProvider. If the request is within limits, it is forwarded; otherwise, it is throttled.

Throttling

Again, for the sake of simplicity, we Hard-Throttle requests that exceed the tenant’s limits

Profiles

The application supports two runtime profiles:

standalone: Uses the StandaloneBucketProvider.
distributed: Uses the RedisBucketProvider.

Conclusion

API rate limiting is essential for maintaining the stability, security, and fairness of APIs. By understanding its architecture, scaling mechanisms, and implementation strategies, developers can design robust systems that handle diverse usage patterns effectively. For a hands-on demonstration, check out the implementation code on GitHub.

Learn about Java cleaners and while you're at it you will also learn about Phantom references.

Ahmed Jaad — Tue, 24 Dec 2024 23:42:16 +0000

Java Cleaners: The Modern Way to Manage External Resources

Ahmed Jaad ・ Aug 13 '24

#java #programming #coding #development

Spring MVC Unveiled: How It Leverages Servlet Technology

Ahmed Jaad — Tue, 24 Dec 2024 05:29:44 +0000

This is the second part of the Inside Spring series. If you haven’t read the first part, Servlet: The Foundation of Java Web Technology, we recommend doing so even if you’re familiar with the topic, it is a great refresher.
We’ve mixed XML and annotation-based configurations to broaden your understanding of Spring and the Servlet API, and for illustration purposes, not a preference for XML, modern practices favor annotations.
This article is accompanied by source code on GitHub. Following along with the code, while reading will help you better understand the concepts discussed.
Unfortunately images here are of poor quality, for better quality, checkout the ones in the GitHub repository.

Introduction
Bootstrapping and Configuring Spring MVC
- ApplicationContext Creation
- Self-Configuration
- Programmatic Initialization
- Hierarchical WebApplicationContext Structure
Dispatching Request
- Key Workflow Steps
- HandlerExecutionChain
- HandlerAdapter and Invoking the Handler
How it all fits in with SpringBoot
Conclusion

Introduction

Back in 2013, as I began exploring Spring, I had a basic grasp of Servlet technology but couldn’t quite understand why deploying a Spring MVC application required Tomcat, a Servlet container, despite not writing a single Servlet.

I also wondered how Spring’s ApplicationContext was initialized, or how Tomcat mapped HTTP requests without definitions in the deployment descriptor. Fast-forward 11 years, and with Spring Boot’s rise, answering these questions has only grown more challenging.

In this article, we’ll attempt to answer these questions by exploring how Servlet technology bootstraps and configures a Spring MVC application, how Spring MVC dispatches requests to the right handlers, and finally, how all of this integrates seamlessly with Spring Boot.

We won’t go into the details of the MVC pattern, the concept of a front controller, or the basics of the Spring Framework. It’s assumed that you already understand what the ApplicationContext is and its role in a Spring application. If these concepts are new to you, I encourage exploring the many excellent resources available to learn about them.

Bootstrapping and Configuring Spring MVC

Since you’re here, you likely know what a servlet is, so let’s view Spring MVC from a fresh perspective: it’s essentially one giant, powerful, and highly customizable servlet.

📌 Note
While typically there’s one DispatcherServlet in a Spring MVC application, multiple can be configured if needed. Spring MVC creates and maintains one ApplicationContext per DispatcherServlet, each of these servlets operates in their own namespace and resources

At its core, Spring MVC revolves around a single servlet, the DispatcherServlet, which handles every incoming request. Spring essentially tells the Servlet API:

I’ll use you to bootstrap and configure myself. Once that’s done, forward all requests to me—I’ll handle them better.

— Spring MVC to Servlet API

Spring MVC Overview

Here’s how Spring MVC leverages Servlet technology to bootstrap and configure itself:

Request Mapping: The servlet container maps all requests to the DispatcherServlet, enabling Spring MVC to control the request-handling lifecycle.
ApplicationContext Creation: The servlet container instantiates and initializes the DispatcherServlet, which itself initializes the Spring ApplicationContext.
Self-Configuration: When the servlet container calls init() on the DispatcherServlet, it configures itself based on the application’s setup.
Programmatic Initialization: Spring allows developers to influence the initialization process using the ServletContainerInitializer interface and the @HandlesTypes annotation.
Hierarchical WebApplicationContext Structure: Spring uses the ContextLoaderListener, an implementation of ServletContextListener, to create and initialize a root WebApplicationContext, establishing a hierarchy where the root context provides shared beans to all DispatcherServlet instances.

There isn’t that much more to say about the first point. Spring maps requests to the DispatcherServlet using the <servlet-mapping> element in web.xml or the urlPatterns attribute of the @WebServlet annotation. For dynamic servlet registration, it relies on the addMapping() method of the ServletRegistration interface.

Now, let’s take a closer look at the remaining four points.

ApplicationContext Creation

Creating WebApplicationContext

When a DispatcherServlet is registered statically, either via web.xml or the @WebServlet annotation, the servlet container uses its default no-argument constructor to instantiate it, the servlet container then calls the servlet’s init() lifecycle method.

Spring MVC takes advantage of the init() method call by loading a configuration file named [servletName]-servlet.xml from the WEB-INF directory, and then creates and initializes an instance of WebApplicationContext, a sub-interface of ApplicationContext.

Spring offers flexibility through the contextConfigLocation initialization parameter, which allows you to specify alternative XML configuration files. Similarly, the contextClass parameter lets you define the ApplicationContext implementation to use, typically a class like AnnotationConfigWebApplicationContext.

For greater control, the DispatcherServlet provides methods to set these values. A preferred approach is to extend the DispatcherServlet and override its default constructor to configure these parameters programmatically.

Practical Example: Dedicated DispatcherServlet for Integration

In our banking application, suppose we want a DispatcherServlet named integrationAppServlet dedicated to third-party integrations. We can register it in web.xml as follows:

web.xml


        <servlet>
            <servlet-name>integrationAppServlet</servlet-name>
            <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
            <load-on-startup>1</load-on-startup>
        </servlet>
        <servlet-mapping>
            <servlet-name>integrationAppServlet</servlet-name>
            <url-pattern>/integration/*</url-pattern>
        </servlet-mapping>

Spring MVC will then look for a configuration file named WEB-INF/integrationAppServlet-servlet.xml. Here’s how it might look:

integrationAppServlet-servlet.xml


            <!-- xmlns declarations removed for brevity -->
    <beans>
        <context:component-scan base-package="spring_mvc_unveiled.integration"/>
    </beans>

This setup instructs Spring MVC to scan the spring_mvc_unveiled.integration package for beans, create a WebApplicationContext with them, and associate that context with the integrationAppServlet. This servlet will handle all requests with the /integration URL pattern.

📌 Note
The static registration of DispatcherServlet is demonstrated in web.xml and WEB-INF/integrationAppServlet-servlet.xml. For @WebServlet registration, see the CustomerAppServlet class and its nested CustomerAppApplicationContext class.

Self-Configuration

Spring not only creates the WebApplicationContext for the DispatcherServlet during its init() method call but also registers essential beans called Special Bean Types.
DispatcherServlet delegates the real work of processing requests to these beans, there are eight such bean types in total, but discussing all of them is beyond the scope of this article. To provide clarity on what Spring MVC configures within the DispatcherServlet, we’ll briefly highlight three key examples:

HandlerMapping: This bean helps DispatcherServlet determine the bean that will handle a request, for instance in our banking application, in the BalanceController class we have the balance() method which is annotated with @GetMapping annotation, when a GET /customer/balance request comes DispatcherServlet's way, it will ask the HandlerMapping bean to map the request to the right handler, the HandlerMapping bean will then map the request to the BalanceController#balance method. The implementation of HandlerMapping that supports mapping of methods annotated with @RequestMapping is RequestMappingHandlerMapping

HandlerExceptionResolver: If an exception is thrown during mapping or processing of a request,DispatcherServlet will ask a bean of type HandlerExceptionResolver to determine an exception handler. You’ve probably used the @ControllerAdvice and @ExceptionHandler annotation to globally handle exceptions in your applications, you might have thought it was magic that calls you methods, I’m here to tell it is not, it’s actual an implementation of HandlerExceptionResolver by name ExceptionHandlerExceptionResolver that does this

ViewResolver: When your handler return a String, Spring MVC assumes it is a name of a view, and the DispatcherServlet will ask a bean of type ViewResolver to resolve the real view that will be returned to the client

As already mentioned Spring MVC configures the DispatcherServlet with these beans by first checking if the programmer defined these beans, if not it will go ahead with the default strategy that creates all the beans that the DispatcherServlet needs.

If customization is needed, you can either provide your own beans of these types, and Spring will pick them up, or use the @EnableWebMvc annotation with the WebMvcConfigurer interface. This approach allows fine-grained control over the Spring MVC flow while still leveraging the framework’s defaults where needed.

Programmatic Initialization

Programmers can implement the WebApplicationInitializer interface, which includes a single method: onStartup(ServletContext servletContext). Spring MVC calls this method and provides the ServletContext instance, allowing developers to perform tasks during the application startup. This gives developers a say over the initialization process.

But how does Spring achieve this? It uses SpringServletContainerInitializer, an implementation of ServletContainerInitializer which is annotated with @HandlesTypes(WebApplicationInitializer.class). As explained in the ServletContainerInitializer section, the servlet container passes all instances of WebApplicationInitializer to the onStartup method of SpringServletContainerInitializer. Spring then invokes the onStartup method of each WebApplicationInitializer instance and provides the ServletContext instance.

Practical Example: Dedicated DispatcherServlet for Backoffice

Given the multi-module nature of our banking app, a dedicated DispatcherServlet is needed to handle backoffice requests under the /back_office URL path. By implementing the WebApplicationInitializer interface, we can dynamically register a DispatcherServlet without relying on annotations or web.xml. Here’s an example:

BackOfficeAppInitializer.java


        @Override
        public void onStartup(ServletContext servletContext) {
            var webApplicationContext = new AnnotationConfigWebApplicationContext();
            webApplicationContext.register(BackOfficeWebConfig.class);
            var dispatcherServlet = new DispatcherServlet(webApplicationContext);
            var dispatcher = servletContext.addServlet("backOfficeAppServlet", dispatcherServlet);
            dispatcher.setLoadOnStartup(1);
            dispatcher.addMapping("/back_office/*");
        }

This programmatic approach provides full control over how the DispatcherServlet and WebApplicationContext are created and configured, making it a powerful alternative to static registration.

Spring provides a convenient abstract implementation of WebApplicationInitializer in AbstractAnnotationConfigDispatcherServletInitializer, that makes it easy to initialize DispatcherServlet based on Java config classes. Check out our OthersAppServlet that extends the abstract class.

Hierarchical WebApplicationContext Structure

Spring leverages the ServletContextListener interface to support a hierarchical structure for WebApplicationContexts, enabling shared beans across multiple contexts. This is achieved through ContextLoaderListener, Spring’s implementation of ServletContextListener. The ContextLoaderListener creates a root WebApplicationContext that acts as the parent context for all child contexts in the application. Beans defined in the root context are accessible to its child contexts, but not vice versa. To use this feature, developers need to register ContextLoaderListener as a listener via one of the following methods:

The web.xml <listener> element.
The @WebListener annotation.
Programmatically with the ServletContext.

Spring checks for the contextClass parameter at the web.xml <context-param> level to determine the context class to initialize. If not specified, it defaults to the contextConfigLocation parameter. Spring also provides an overloaded constructor where you can pass in a WebApplicationContext, this is useful when the ContextLoaderListener is registered dynamically

This is the second point in the application lifecycle where Spring creates and configures a WebApplicationContext, the first being within the DispatcherServlet.

Hierarchical WebContext

Practical Example: Shared DAO Beans

In our banking application, even though it is modular, certain beans are shared across modules, such as infrastructure or business logic components. For instance, data access layer (DAO) beans are common to all modules, and maintaining separate versions in each WebApplicationContext would be inefficient. A root application context is the ideal solution for sharing these beans.

To set up a root context, the ContextLoaderListener can be registered in web.xml like this:

web.xml


    <listener>
            <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    <context-param>
           <param-name>contextClass</param-name>
           <param-value>spring_mvc_unveiled.root.RootApplicationContext</param-value>
    </context-param>

📌 Note
This can also be achieved using the @WebListener annotation. For implementation details, refer to our RootContextLoaderListener class and its Javadoc.

Spring MVC Startup Process

Dispatching Request

The DispatcherServlet is at the core of Spring MVC, functioning as the front controller for the application. For every incoming request, the servlet container invokes the service() method of the DispatcherServlet, just as it does for any other servlet in the Servlet API lifecycle. From there, the DispatcherServlet takes charge, leveraging this foundational servlet mechanism to prepare and dispatch the request to the appropriate handler, showcasing how Spring MVC is seamlessly built on top of the Servlet API.

Key Workflow Steps

DispatcherServlet organizes its workflow by delegating specific tasks to specialized components, adhering to the separation of concerns principle.

The DispatcherServlet processes requests in four primary steps:

Prepare the Request: Performs cross-cutting tasks such as determining the locale, resolving multipart requests, and storing the request attributes in the RequestContextHolder.
Determine and Execute the Handler: Uses a HandlerMapping to identify the handler and invokes it through a HandlerAdapter.
Resolve Exceptions: Delegates exception handling to a HandlerExceptionResolver. Also mentioned here
Prepare the Response: Involves tasks like resolving the View by a ViewResolver to determine how to render the response. Also mentioned here

Request Process Flow

This section focuses on the second step: determining and executing the handler, let us see the components involved in this process.

HandlerExecutionChain

The HandlerMapping does not directly return a handler but instead an instance of HandlerExecutionChain, which bundles:

The Handler: This is the object that processes the request. It can be any Object, offering flexibility in design. For example, HandlerMethod is a handler that represents controller methods annotated with @RequestMapping and similar annotations (@GetMapping, @PostMapping, etc.)
Interceptors: These are pre- and post-processing hooks, implemented using HandlerInterceptor.
- The preHandle() method runs before the handler and can block the request.
- The postHandle() method runs after the handler and can modify the response.

Interceptors are reusable and can be applied to multiple handlers. For example, a security interceptor can validate credentials across all handlers for secured paths. While similar to servlet filters, interceptors are more powerful as they integrate into the Spring MVC workflow.

Handler Execution Chain

Example: HandlerMethod

A handler is referenced as an Object by HandlerExecutionChain, meaning that, for the DispatcherServlet, a handler is essentially just an Object. The real type of the handler can be anything; for instance, it could be a HandlerMethod. A HandlerMethod represents methods annotated with @RequestMapping and its variants (like @GetMapping, @PostMapping). When a request is received, Spring creates a HandlerMethod bean for each annotated method, allowing the adapter to call the method via reflection.

The HandlerMethod does more than wrap a reference to the method, it also maintains state to represent the arguments and return values of the method. This is essential because it allows Spring to dynamically resolve method parameters (such as HTTP request data) and invoke the method with the correct context at runtime.

Example: Registering an Interceptor

Developers are responsible to define their interceptors and register them to Spring MVC this can be achieved by using the @EnableWebMvc annotation and WebMvcConfigurer interface. In our banking application say that we want to intercept /balance path, we will register it like below:

CustomerWebConfig


    @Configuration
    @EnableWebMvc
    public class CustomerWebConfig implements WebMvcConfigurer {
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
    /*
            the path pattern is relative to the DispatcherServlet root path
            in this case /customer
    */
            registry.addInterceptor(new BalanceInterceptor()).addPathPatterns("/**");
        }
    }

And the BalanceInterceptor:

BalanceInterceptor.java


    public class BalanceInterceptor implements HandlerInterceptor {
        @Override
        public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
            // Logic goes here
            return true; // Return true to continue; false to block the request
        }
    }

HandlerAdapter and Invoking the Handler

Since handlers are generic Object instances, the DispatcherServlet uses HandlerAdapter objects to invoke them. Each HandlerAdapter knows how to handle a specific type of handler. For example, RequestMappingHandlerAdapter knows how to invoke HandlerMethod, a handler for methods annotated with @RequestMapping.

The two key methods of HandlerAdapter are:

supports(): Determines if the adapter can handle a given handler type.
handle(): Invokes the handler using the request and response objects, returning a ModelAndView.

For each handler, that the DispatcherServlet encounters there must be an adapter that supports it, otherwise, the DispatcherServlet will throw a ServletException. As already mentioned, HandlerAdapter is one of the Special Bean Types, and the default strategy of the DispatcherServlet creates four beans of type HandlerAdapter.

Now that we’ve explored the key components the DispatcherServlet uses to locate and invoke handlers, let’s see the whole flow:

Spring MVC Handling Request

Below is a simplified code flow:

DispatcherServlet.java


            HandlerExecutionChain  executionChain = getExecutionChain(request);
            HandlerAdapter adapter = getHandlerAdapter(executionChain.getHandler());
            if (!executionChain.applyPreHandle(request, response)) {
                return;// Request blocked by one of the preHandle() methods
            }
            // Use the adapter to invoke the handler
            ModelAndView  mv = adapter.handle(request, response, executionChain.getHandler());
            executionChain.applyPostHandle(request, response, mv);

            // continue with preparing the response

📌 Note
This code is a simplified representation of the actual Spring Framework implementation to clarify the flow.

Code Highlights:

getExecutionChain(request): Iterates through all HandlerMapping beans to find a HandlerExecutionChain for the request. Returns null if none match.
getHandlerAdapter(handler): Iterates through HandlerAdapter beans, calling their supports() method. Throws ServletException if no adapter supports the handler.
applyPreHandle(request, response): Executes the preHandle() methods of all applicable HandlerInterceptor objects. If any returns false, the request is blocked.
adapter.handle(): Delegates the actual invocation of the handler to the appropriate HandlerAdapter, which knows how to call it.
applyPostHandle(request, response, mv): Executes the postHandle() methods of all interceptors after the handler has processed the request.

How it all fits in with SpringBoot

This text wouldn’t be complete without pointing out how all of this is related to Spring Boot. Spring Boot simplifies the process of setting up and running a Spring MVC application by removing much of the boilerplate configuration associated with traditional setups. Let’s explore how Spring Boot makes this possible and how it integrates seamlessly with the Servlet technology we’ve discussed so far.

Embedded Servlet Container

One of the key features of Spring Boot is its ability to bundle an embedded servlet container, such as Tomcat, Jetty, or Undertow. Instead of deploying your application to an external servlet container, Spring Boot packages your application as a "fat JAR" that includes everything needed to run the application. This allows you to run your application as a standalone Java process, simplifying deployment and enabling portability.

When your Spring Boot application starts, it initializes the embedded servlet container by using the EmbeddedServletContainerFactory. This factory is responsible for configuring and starting the servlet container, allowing Spring Boot to dynamically register the DispatcherServlet and other components as part of the initialization process.

@EnableAutoConfiguration

Spring Boot further reduces complexity through the @EnableAutoConfiguration annotation. This annotation scans the classpath for Spring components and configuration files, automatically creating and wiring the necessary beans, including the DispatcherServlet.

For example:

It detects the presence of Spring MVC-related libraries and automatically configures a DispatcherServlet.
It creates and registers default components such as HandlerMapping, HandlerAdapter, and ViewResolver.
It even sets up default error handling, static resource serving, and other conveniences out of the box.

Automatic Inclusion of @EnableWebMvc

Spring Boot automatically includes @EnableWebMvc when Spring MVC is present in your application. This ensures that Spring MVC’s default configuration is applied without requiring explicit inclusion of the annotation. Developers can still override and customize these configurations by implementing the WebMvcConfigurer interface if necessary.

Bringing It All Together

With Spring Boot, setting up a Spring MVC application no longer requires extensive configuration. It leverages the power of Spring’s core framework while making it easier to focus on business logic rather than infrastructure. By bundling everything into a single fat JAR, providing embedded servlet containers, and automatically configuring essential components, Spring Boot transforms the development and deployment experience.

This simplification, combined with the flexibility to customize as needed, makes Spring Boot a natural choice for modern Java web application development.

Conclusion

In this article, we explored how Spring leverages key features of Servlet technology to bootstrap itself and efficiently dispatch requests. From understanding the foundational role of the DispatcherServlet to examining how RequestMapping and HandlerAdapter work together to route and process requests, we also delved into hierarchical WebApplicationContext structures and Spring’s self-configuration mechanisms.

Mastering these concepts is an essential step toward deepening your understanding of the Spring framework, moving beyond basic usage to appreciating the underlying architecture and design principles.

To solidify your learning, I encourage you to experiment with the accompanying code provided in this article. Use it as your playground to test and explore how Spring MVC works behind the scenes. Additionally, for further reading and reference, the Spring Framework Reference Documentation is an invaluable resource.

Please like and follow for more incoming Java/Spring contents.
Leave comments for questions or any further clarification

🚀 New article alert! Dive into "Servlet: The Foundation of Java Web Technology" and explore the backbone of Java web development. From handling HTTP requests to enabling frameworks like Spring MVC, servlets are where it all begins.

Ahmed Jaad — Sun, 22 Dec 2024 23:38:34 +0000

Servlet: The Foundation of Java Web Technology

Ahmed Jaad ・ Dec 22 '24

#java #spring #springboot #web

Servlet: The Foundation of Java Web Technology

Ahmed Jaad — Sun, 22 Dec 2024 01:17:09 +0000

We’ve mixed XML and annotation-based configurations to broaden your understanding of Servlet API, and for illustration purposes, not a preference for XML, modern practices favor annotations.
This article is accompanied by source code on GitHub. Following along with the code, while reading will help you better understand the concepts discussed.

Introduction
What is a Servlet?
Servlet Container
Servlet API
- Servlet
- Filters
- ServletContext
- Listeners
- ServletContainerInitializer
Registering Components with the Servlet Container
Conclusion

Introduction

If you’re a Spring developer like me, you’ve likely encountered mentions of the DispatcherServlet in articles or books. It’s often described as the "Front Controller" of the Spring MVC framework, accompanied by well-crafted diagrams explaining the concept.

But in my experience, many of these resources fail to address a crucial question: How does Spring MVC make the DispatcherServlet its Front Controller?

Answering this question requires a solid understanding of the Servlet technology ecosystem, which forms the backbone of Spring MVC. Gaining this knowledge can elevate you from being an okay Spring Boot developer to a Spring professional with in-depth expertise.

In this article, we’ll begin by exploring the core concepts of Servlet technology. Then, in the next parts of this series, we’ll uncover how Spring leverages these concepts to build the powerful Spring MVC framework.

What is a Servlet?

If you’ve been asked this question in an interview, I’d like to know what your answer was, this is such a multifaceted question I myself don’t know if I could give a straight answer. Let us look at some ways one can answer this question

Servlet is part of the suite of specifications that make up Jakarta EE. Formerly known as Java Enterprise Edition(Java EE), it is a set of specifications that standardizes how we write Java enterprise applications, Jakarta Servlet specifies server-side API for handling HTTP request and responses. More commonly known specifications are Jakarta Persistence(JPA), Jakarta Transactions(JTA) and Jakarta RESTful Web Services(JAX-RS).
Servlet is a Java object that can handle a web request on a particular path and can give a dynamic response to it. An instance of a jakarta.servlet.Servlet implementation, this object is registered to a Java-based web server (more to come about it) together with the path it wants to handle. Say you’re developing a banking app, and you want the path /balance to return the balance of the user, you’d do the following:
- Define a class say Balance that implements jakarta.servlet.Servlet interface, the class should handle all the business logic related to the user’s balance.
- Register the Balance class and the path /balance to the Web server.
Whenever a client sends a request to the /balance path, the web server will handle that request to the instance of the Balance class.
A servlet is the basic building block unit of a Jakarta EE web application. As simple as Servlets seem to be, they’re the foundation of Java Web technologies everything else is based on them, technologies like JSP, JSF, Spring MVC, and many more wouldn’t exist without servlets. Non-web technologies like JTA and JPA do not depend on servlets

Each of these perspectives helps paint a clearer picture of servlets and brings us closer to understanding Java web technology. Before we get into the specifics of the Servlet API lets us first clarify an important concept, a term that most of us probably have heard it before Servlet container, an important component of Jakarta EE ecosystem that a servlet object lives in.

Servlet Container

Spring Boot is incredibly popular for simplifying Java web application development. However, one of the trade-offs of this simplicity is that it often obscures the foundational components of Java web technology. This can make it easy for new developers to feel confident, but when issues arise that require understanding of how things work under the hood, the challenge becomes clear. One such component that Spring Boot abstracts away is the servlet container. If you’ve never heard of servlet containers, or if they’re a mystery to you, this section is for you as I’ll do my best to demystify them. A servlet container like Apache Tomcat and Eclipse Jetty, is a Java program, like any other Java program, an example of which the infamous "Hello World" program, it starts by invoking the main method and runs inside the JVM.

What makes the Servlet container a bit more special java program is that it provides the running environment and manages servlets, and it achieves this by doing at least the following things

Instantiate an instance of your Servlet implementation
Providing Servlet and JSP APIs at runtime: that’s why you don’t package your application with these APIs.
Listening for HTTP requests from a port of your choice by default, both Tomcat and Jetty listen to port 8080.
Parsing HTTP requests: Unmarshalling an HTTP request(plain text) into Java objects representing HTTP requests and responses, as HTTP is a plain text protocol.
Invoking servlet object: The servlet container will spawn a thread(or using an existing one from a pool) to invoke the servlet object that matches the HTTP path and pass the corresponding Java HTTP object.
Format and return the response: Marshalling the Java object representing the HTTP response into plain text HTTP response ready for the client to receive it.

When you think about it, a servlet container is an HTTP server, think of it as a minified Java based HTTP server. Emphasis on minified, because servlet containers know only how to run servlets and JSPs unlike full-blown application servers like Glassfish and Weblogic that support full spectrum Jakarta EE specifications like EJB, JTA, and CDI.

Multiple web applications can run in the same servlet container as long as they’re installed in different URL workspaces. In our Banking system example, we can have two web applications the customer application, installed at /customer that handles all customer requests and the back office application, installed at /back_office that handle requests from the Bank’s employees these two applications will be exposed at mybankdomain.com:port/customer and mybankdomain.com:port/back_office respectively. At the end of this article, we talk about how to register Servlets and other components with the container

Servlet Container

Servlet API

Apart from Servlets themselves, other important building blocks in servlet-powered applications are Listeners and Filters. Listeners are objects that are registered to listen to container events, and the container will notify them whenever such events happen while Filters are components that are meant to pre-process servlet requests and post-process servlet response. In this section, we will also see another two components that play a crucial role in DispatcherServlet, that is ServletContext and ServletContainerInitializer

Servlet

📌 NOTE
Usages for these methods are demonstrated in the BalanceGenericServlet class

The jakarta.servlet.Servlet is a protocol-independent interface that defines minimal specification for a servlet. The interface defines three life-cycle methods that are invoked by the Servlet Container.

Servlet Lifecycle:

init(ServletConfig servletConfig): The initializing method It is called by the Servlet container just after the Servlet instance has been constructed, a ServletConfig is passed to the servlet by the Servlet Container via this method, ServletConfig is servlet configuration object that contains values like servlet name, servlet initial parameters. This method is the place where the Servlet Container notifies the servlet that is being put into service(for handling request)
service(ServletRequest req, ServletResponse res): We have already mentioned that the servlet container will call the corresponding servlet for each request from the client This is the method that the Servlet container calls, and the request from the client is parsed in to jakarta.servlet.ServletRequest object and passed through this method.
destroy(): The cleanup method, when the Servlet object is done being used, it is taken out of service then get destroyed by calling its destroy() method before being eligible to Garbage Collector(GC). The Logic to clean up any resource that the servlet possesses should be placed in this method

The interface also define the ServletConfig getServletConfig() method which returns a ServletConfig which the servlet can use to get the start-up info and the String getServletInfo() method that the servlet can use to get information about itself like version, author and copyright

Servlet Life-Cycle

Servlet In Action: Handling Account Balance Requests

We will implement a simple servlet,BalanceGenericServlet, that handles an HTTP GET request on the /balance URL pattern and returns random integer value as the balance.

BalanceGenericServlet.java


        @Override
        public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
            logger.info(MessageFormat.format("Servlet Request is {0}\n", req));
            if (!(req instanceof HttpServletRequest httpReq && res instanceof HttpServletResponse httpRes)) {
                throw new ServletException("I can only handle Http requests");
            }
            if (httpReq.getMethod().equals("GET")) {
                httpRes.setStatus(200);
                httpRes.setContentType("text/plain");
                try (PrintWriter writer = httpRes.getWriter()) {
                    writer.println(MessageFormat.format("Your balance is {0}", new Random().nextInt() ));
                }
            } else httpRes.sendError(400, "http.method_not_supported");
        }

The service method first makes sure that the incoming request is an HTTP request by checking the type of ServletRequest and ServletResponse. Throws an Exception if the request is not an HTTP request, remembers jakarta.servlet.Servlet is protocol-independent, which means even non-HTTP requests will be passed to the servlet. It then goes on to handle the GET request.

Simpler Servlet For HTTP Requests:

You probably think "that is a lot of work to handle a simple GET request." You’re right, you almost have no reason to override the serivce method, the Servlet API comes with two abstract implementations of the Servlet interface that make you job simpler, the protocol-independent class jakarta.servlet.GenericServlet and its subclass jakarta.servlet.HttpServlet, the two classes together do the following

GenericServlet: Provides the no-argument, simpler overloaded version the init(ServletConfig servletConfig) method.
HttpServlet: Should be the superclass for all HTTP servlets, it defines HTTP-specific methods in the form of doXXX() where XXX is the HTTP verb the method handles, e.g doGet(), doPost(), doPut()

📌 Warning
Remember the Servlet Container does not call the individual Http-specific methods, it calls the service() method.

By extending the HttpServlet, writing HTTP servlets becomes way simpler. You don’t need to implement all the methods from the Servlet interface and all you have to do is overriding the corresponding HTTP method. We can now handle the /balance GET request as

BalanceHttpServlet.java


        @Override
        public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
            resp.setStatus(200);
            resp.setContentType("text/plain");
                try (PrintWriter writer = httpRes.getWriter()) {
                    writer.println(MessageFormat.format("Your balance is {0}", new Random().nextInt()));
                }
        }

You can compare our two classes servlet_basics.BalanceGenericServlet and servlet_basics.BalanceHttpServlet to observe the differences

Filters

By default, servlet containers handle some aspects of requests and responses, such as setting cookies, managing sessions, and interpreting headers. However, this default behavior is not always sufficient. You may need to address cross-cutting concerns like authentication, logging, or request/response encryption. Filters provide a way to intercept requests and responses for pre-processing or post-processing tasks, and they can be applied to specific servlets or URL patterns.

Filters

When to Use Filters:

Use filters for common concerns across multiple servlets.
Avoid filters for concerns specific to a single servlet; place such logic directly in the servlet.

Filter Lifecycle:

Filters follow a well-defined lifecycle managed by the servlet container. If filters are registered correctly and successfully, the Servlet Container will invoke the three methods defined in the jakarta.servlet.Filter interface in this order

init(FilterConfig filterConfig): This is the place where the Servlet Container is notifying the filter that it is about to be placed in service. This method must complete successfully in order for the doFilter method to be invoked. A FilterConfig instance is passed to this method, implementations can opt to save this instance in a field, so information like the filter’s name, filter’s initial parameters can be obtained from it. The FilterConfig class also contains the getServletContext method which returns reference to ServletContext instance
doFilter(): This method is invoked for each request whenever the URL matches the url-pattern or the servlet names specified in the filter definition. The method is invoked before the request reaches the servlet. Instances of ServletRequest and ServletResponse are passed to this method, as well as an instance of FilterChain whose method doFilter must be called to propagate the call to the next filter in the chain. Remember this method will be invoked only if the init method is completed successfully, there is the happens before relationship between this method and the init method
destroy(): Is invoked after the filter has been taken out of service and before is eligible to the Garbage Collector, this method is called only once and the doFilter method of this instance is not called anymore after this method has been called. This method is called once all threads have exited the doFilter method.

Important to note that the init and destroy methods are called only once for each filter instance. Also, just like with Servlet there are two abstract implementations of the Filter interface GenericFilter and HttpFilter, for all HTTP-based filters should implement the HttpFilter class.

Example: Securing the `/balance` Path

Let us leverage filters to secure the path /balance with HTTP basic authentication, to do that we need a filter that would intercept the URL patterns /balance, say AuthenticationFilter and override the doFilter. The AuthenticationFilter must be registered to the Servlet Container that it wants to intercept any request that matches the /balance URL pattern, see the Registering Components with the Servlet Container section.

AuthenticationFilter.java

        @Override
        public void doFilter(HttpServletRequest req, HttpServletResponse res, FilterChain chain) 
throws IOException, ServletException {
            String authenticationHeader = req.getHeader("Authorization");
            if (authenticationHeader == null) {
                res.sendError(HttpServletResponse.SC_BAD_REQUEST, "Authorization Header must be supplied");
                return;
            }
            if (!authenticationHeader.startsWith("Basic ")) {
                res.sendError(HttpServletResponse.SC_BAD_REQUEST, "Only Basic Authorization is supported");
                return;
            }
            String[] credentials = authenticationHeader.substring(6).split(":");
            if (credentials[0].equalsIgnoreCase("user") && credentials[1].equals("password")) {
                chain.doFilter(req, res);
            } else {
                res.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Wrong username/password combination");
            }
        }

📌 Warning
This is an oversimplified example of how to implement an authentication filter. It assumes the credentials are submitted as plain text, but Base64 decoding is the standard for Basic Authentication. For a production-grade implementation, ensure proper decoding and secure credential handling.

The path /balance is now secured, every HTTP request must contain the Authorization header with the value Basic user:password otherwise it will be rejected by the filter. A Spring developer should have a clear understanding of filters as they’re extensively used in Spring MVC and Spring Security, in fact Spring Security has a filter with the same name as ours AuthenticationFilter.

ServletContext

jakarta.servlet.ServletContext is an interface for your web application to interact with the servlet container. It acts as a communication bridge between your application and the container, offering functionality such as:

Retrieving container-specific information, like the supported Servlet API version or the context path of your web application.
Dynamically registering servlets, filters, and listeners during application startup.
Providing a shared storage area for servlets, filters, and listeners via context attributes (key-value pairs).

Context Path

The context path is the portion of the URL that uniquely identifies a web application in the container. From our example in the Servlet Container section the value for context paths will be cutomer and back_office respectively. Each application deployed in a servlet container has its own context path.

Dynamic Component Registration

Since Servlet 3.0, ServletContext provides methods like addServlet and addFilter for programmatically adding components during startup. This allows more flexible and dynamic configurations compared to static configurations in web.xml or annotations.

Global Application Storage

ServletContext attributes serve as a global storage for your web application, accessible to all servlets, filters, and listeners within the same context. For example, you can store shared configuration data or application state:

    servletContext.setAttribute("config", configObject);
    Object config = servletContext.getAttribute("config");

In distributed web applications (marked as "distributed" in web.xml), each JVM maintains its own ServletContext. Here ServletContext shouldn’t be used as the application state as the data in the context isn’t really global.

Unlike servlets or filters, ServletContext is not something you’ll frequently use in day-to-day development. However, it plays a vital role in bridging your application with the servlet container and enabling advanced features. We will see ServletContext demo in conjunction with the ServletContainerInitializer.

Servlet Context

Listeners

The Servlet specification allows developers to track key events in a servlet application’s lifecycle and respond to them through listeners. Listeners are components that listen for events in the web application’s lifecycle and act accordingly. When registered, the servlet container invokes the corresponding listener methods in response to specific events.

Listeners operate at three levels in a servlet application:

Servlet Context-Level (Application-Level): Events involving the state or resources of the application-wide ServletContext.
Session-Level: Events tied to individual user sessions (HttpSession).
Request-Level: Events tied to individual requests (ServletRequest).

Each level supports two event categories:

Lifecycle Changes: Involve events when resources are initialized or destroyed, e.g.
- ServletContextListener: For ServletContext initialization and destruction events.
- HttpSessionListener: For Http Session creation and destruction.
- ServletRequestListener: For servlet request creation and destruction.
Attribute Changes: Events triggered by changes to attributes within these resources. Examples include:
- ServletContextAttributeListener: For attribute additions, removals, or replacements in ServletContext.
- HttpSessionAttributeListener: For similar changes in HttpSession.

Practical Example: Managing User Data with `HttpSessionListener`

Going back to our banking system, say we want to improve the experience of customer users by having their personal data managed in a session so the data is available throughout the session’s lifetime. We can leverage HttpSessionListener by overriding the sessionCreated method, the servlet container will notify us through this method when a new session is created, below code gives us the idea how we would approach this

UserDataLoader.java

        @Override
        public void sessionCreated(HttpSessionEvent se) {
            HttpSession session = se.getSession();
            UserData userData = getUserData();
            // Retrieve user data from a database or service
            session.setAttribute("userData", userData); 
        }

📌 Note
The getUserData() method represents the logic to fetch user data, typically from a database or external service.

Another example that logs ServletContext attributes after the ServletContext has been initialized is demonstrated in the ServletContextLogger class.

ServletContainerInitializer

The last interface we’ll explore is ServletContainerInitializer. This interface allows third-party libraries to be notified during the web application startup phase through its onStartup method. Using this method, libraries can programmatically register servlets, filters, and listeners.

ServletContainerInitializer

How Does It Work?

The servlet container discovers implementations of ServletContainerInitializer using the META-INF/services mechanism. Specifically, a file named jakarta.servlet.ServletContainerInitializer in the META-INF/services directory of a JAR contains the fully qualified name of the initializer class. During startup, the container invokes the onStartup method of the discovered implementations.

Practical Example: Centralized Security

Consider a microservices-based of our banking system requiring extra layered security. For example:

In the back_office service, all endpoints under /admin should only be accessible to users with the ADMIN authority.
In the customer service, all endpoints under /transactions should require re-authentication.

A centralized security configuration can be implemented as a JAR containing a ServletContainerInitializer. The initializer uses a servlet context attribute (serviceName) to determine the service and register appropriate security filters. Here’s how this might look:

SecurityFilterInitializer.java

        @Override
        public void onStartup(Set<Class<?>> clazzes, ServletContext ctx) {
            Object serviceName = ctx.getAttribute("serviceName");
            if (serviceName.equals("back_office")) registerAdminFilter(ctx);
            if (serviceName.equals("customer")) registerTransactionFilter(ctx);
        }

📌 Note
The serviceName attribute is set in the servlet context before deployment through web.xml. Check the class SecurityFilterInitializer for the full implementations. Depending on the value of the serviceName you can send an HTTP request that starts with either /transactions or /admin paths to see the filters in action.

The Role of `@HandlesTypes`

An implementation of ServletContainerInitializer can be annotated with @HandlesTypes. This annotation specifies class types (interfaces or abstract classes) the initializer can handle. The container will pass implementations or subclasses of these types as the first argument to the onStartup method. This mechanism is particularly useful for frameworks like Spring, which uses SpringServletContainerInitializer to delegate servlet context initialization to programmer-defined classes implementing WebApplicationInitializer.

📌 Note
If this is still somehow confusing, Check our SecurityFilterInitializer and OtherSecurityInitializer and their Javadoc to see the whole thing in action.

In the next part of this series, we’ll explore how Spring MVC leverages ServletContainerInitializer and the @HandlesTypes annotation to register the DispatcherServlet programmatically.

Registering Components with the Servlet Container

When working with servlets, filters, and listeners, you need to inform the servlet container about their existence and how they should be used. This process is called component registration. Servlet containers provide two main ways to register these components:

Declarative Registration (web.xml Deployment Descriptor): The traditional way of registering servlets, filters, and listeners, is by defining them in the web.xml file. This XML file resides in the WEB-INF directory of your web application. For example:

web.xml

    <!-- Registering a Servlet -->
    <!-- xmlns declaration removed for brevity-->
    <web-app>
    <servlet>
        <servlet-name>BalanceGenericServlet</servlet-name>
        <servlet-class>servlet_basics.BalanceGenericServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>BalanceServlet</servlet-name>
        <url-pattern>/balance</url-pattern>
    </servlet-mapping>

    <!-- Registering a Filter -->
    <filter>
        <filter-name>AuthenticationFilter</filter-name>
        <filter-class>servlet_basics.AuthenticationFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>AuthenticationFilter</filter-name>
        <url-pattern>/balance</url-pattern>
    </filter-mapping>

    <!-- Registering a Listener -->
    <listener>
        <listener-class>servlet_basics.UserDataLoader </listener-class>
    </listener>
    </web-app>

Programmatic Registration (Annotations): Since Servlet 3.0, you can use annotations to register components directly in the source code, simplifying the process and avoiding the need for a web.xml file.

Servlet Registration:

BalanceGenericServlet.java


    @WebServlet(name = "Balance", urlPatterns = {"/balance"})
    public class BalanceGenericServlet implements Servlet {
            // Implementation

 }

Filter Registration:

AuthenticationFilter.java


    @WebFilter(filterName = "AuthenticationFilter", urlPatterns = {"/balance"})
    public class AuthenticationFilter implements HttpFilter {
    // Implementation
    }

Listener Registration:

UserDataLoader.java


   @WebListener
   public class UserDataLoader implements HttpSessionListener {
  // Implementation
 }

Both methods achieve the same outcome but serve different needs. Use web.xml when you require centralized configuration and annotations for a more modern, streamlined approach.

By registering your components correctly, the servlet container knows how to manage them and route requests effectively within your application.

Conclusion

In this first part of our series, we explored the foundational concepts of servlet technology. We discussed servlets, filters, listeners, servlet containers, and how these building blocks work together to create robust Java web applications. However, we haven’t touched on everything there is to know about the servlet technology. Our focus has been on aspects most relevant to understanding how Spring MVC’s is bootstrapped and how DispatcherServlet works.

If you’re eager to deepen your knowledge, we encourage you to explore the Servlet Specification and Jakarta EE further, as it offers many features and possibilities beyond what we’ve covered here.

In the next part of this series, we’ll dive into how Spring leverages the servlet ecosystem to bootstrap Spring MVC and make its DispatcherServlet a powerful front controller.

Please like and follow for more incoming Java/Spring contents.
Leave comments for questions or any further clarification

Java Cleaners: The Modern Way to Manage External Resources

Ahmed Jaad — Tue, 13 Aug 2024 20:49:21 +0000

This article is accompanied by source code on GitHub. Following along with the code, while reading will help you better understand the concepts discussed.
If you’re the type of programmer who likes to understand the internals of how things work before seeing examples, you can jump directly to Cleaners behind the scene after the introduction.

Introduction
Simple Cleaner in action
Cleaners, the right way
Cleaners, the effective way
Cleaners behind the scene

Introduction

Think of a scenario where you have an object that holds references to external resources (files, sockets, and so on). And you want to have control over how these resources are released once the holding object is no longer active/accessible, how do you achieve that in Java?. Prior to Java 9 programmers could use a finalizer by overriding the Object’s class finalize() method. Finalizers have many disadvantages, including being slow, unreliable and dangerous. It is one of those features that are hated by both those who implement the JDK and those who use it.

Since Java 9, Finalizers have been deprecated and programmers have a better option to achieve this in Cleaners, Cleaners provide a better way to manage and handle cleaning/finalizing actions. Cleaners work in a pattern where they let resource holding objects register themselves and their corresponding cleaning actions. And then Cleaners will call the cleaning actions once these objects are not accessible by the application code.
This is not the article to tell you why Cleaners are better than Finalizers, though I will briefly list some of their differences.

Finalizers Vs Cleaners

Finalizers	Cleaners
Finalizers are invoked by one of Garbage Collector’s threads, you as a programmer don’t have control over what thread will invoke your finalizing logic	Unlike with finalizers, with Cleaners, programmers can opt to have control over the thread that invokes the cleaning logic.
Finalizing logic is invoked when the object is actually being collected by GC	Cleaning logic is invoked when the object becomes *Phantom Reachable*, that is our application has no means to access it anymore
Finalizing logic is part of the object holding the resources	Cleaning logic and its state are encapsulated in a separate object.
No registration/deregistration mechanism	Provides means for registering cleaning actions and explicit invocation/deregistration

Simple Cleaner in action

Enough chit-chats let us see Cleaners in action.

ResourceHolder

import java.lang.ref.Cleaner;

public class ResourceHolder {
 private static final Cleaner CLEANER = Cleaner.create();
        public ResourceHolder() {
            CLEANER.register(this, () -> System.out.println("I'm doing some clean up"));
        }
        public static void main(String... args) {
            ResourceHolder resourceHolder = new ResourceHolder();
            resourceHolder = null;
            System.gc();
        }}

Few lines of code but a lot is happening here, Let us break it down

The constant CLEANER is of type java.lang.ref.Cleaner, as you can tell from its name, this is the central and starting point of the Cleaners feature in Java. The CLEANER variable is declared as static as it should be, Cleaners should never be instance variables, they should be shared across different classes as much as possible.
In the constructor, instances of ResourceHolder are registering themselves to the Cleaner along with their cleaning action, the cleaning action is a Runnable job that the Cleaner guarantees to invoke at most once (at most once, meaning it is possible not to run at all). By calling Cleaner’s register() method, these instances are basically saying two things to the Cleaner
- Keep track of me as long as I live
- And once I am no longer active (Phantom Reachable), please do your best and invoke my cleaning action.
In the main method we instantiate an object of ResourceHolder and immediately set its variable to null, since the object has only one variable reference, our application can no longer access the object, i.e., it has become Phantom Reachable
We call System.gc() to request JVM to run the Garbage Collector, consequentially this will trigger the Cleaner to run the cleaning action. Typically, you don’t need to call System.gc() but as simple as our application, we need to facilitate the Cleaner to run the action

Run the application, and hopefully you see I’m doing some clean up somewhere in your standard output.

🔥 CAUTION
We started with the simplest possible way to use Cleaners, so we can demonstrate its usage in a simplified way, bear in mind though this is neither effective nor the right way to use Cleaners

Cleaners, the right way

Our first example was more than good enough to see Cleaners in action,
but as we warned, it is not the right way to use Cleaners in a real application.
Let’s see what is wrong with what we did.

We initiated a Cleaner object as a class member of the ResourceHolder: As we mentioned earlier Cleaners should be shared across Classes and should not belong to individual classes, reason behind being each Cleaner instance maintains a thread, which is a limited native resource, and you want to be cautious when you consume native resources.
In a real application, we typically get a Cleaner object from a utility or a Singleton class like
```
  private static CLEANER = AppUtil.getCleaner();
```
We passed in a lambda as our Cleaning action: You should NEVER pass in a lambda as your cleaning action.
To understand why,
let us refactor our previous example by extracting the printed out message and make it an instance variable

ResourceHolder
```
public class ResourceHolder {
   private static final Cleaner CLEANER = Cleaner.create();
   private final String cleaningMessage = "I'm doing some clean up";
   public ResourceHolder() {
       CLEANER.register(this, () -> System.out.println(cleaningMessage));
   }
}
```
Run the application and see what happens.
I will tell you what happens,
the cleaning action will never get invoked no matter how many times you run your application.
Let us see why
- Internally, Cleaners make use of PhantomReference and ReferenceQueue to keep track of registered objects, once an object becomes Phantom Reachable the ReferenceQueue will notify the Cleaner and the Cleaner will use its thread to run the corresponding cleaning action.
- By having the lambda accessing the instance member we’re forcing the lambda to hold the this reference(of ResourceHolder instance), because of this the object will never ever become Phantom Reachable because our Application code still has reference to it.
📌 NOTE
If you still wonder how in our first example, the cleaning action is invoked despite having it as a lambda. The reason is, the lambda in the first example does not access any instance variable, and unlike inner classes, Lambdas won’t implicitly hold the containing object reference unless they’re forced to.

The right way is to encapsulate your cleaning action together with the state it needs in a static nested class.

📌 Warning
Don’t use inner class anonymous or not, it is worse than using lambda because an inner class instance would hold a reference to the outer class instance regardless of whether they access their instance variable or not.
We didn't make use of the return value from the Cleaner.create(): The create() actually returns something very important.a Cleanable object, this object has a clean() method that wraps your cleaning logic, you as a programmer can opt to do the cleanup yourself by invoking the clean() method. As mentioned earlier, another thing that makes Cleaners superior to Finalizers is that you can actually deregister your cleaning action. The clean() method actually deregisters your object first, and then it invokes your cleaning action, this way it guarantees the at-most once behavior.

Now let us improve each one of these points and revise our ResourceHolder class

ResourceHolder

import java.lang.ref.Cleaner;

public class ResourceHolder {

    private final Cleaner.Cleanable cleanable;
    private final ExternalResource externalResource;

    public ResourceHolder(ExternalResource externalResource) {
        cleanable = AppUtil.getCleaner().register(this, new CleaningAction(externalResource));
        this.externalResource = externalResource;
    }

//    You can call this method whenever is the right time to release resource
    public void releaseResource() {
        cleanable.clean();
    }

    public void doSomethingWithResource() {
        System.out.printf("Do something cool with the important resource: %s \n", this.externalResource);
    }

    static class CleaningAction implements Runnable {
        private ExternalResource externalResource;

        CleaningAction(ExternalResource externalResource) {
            this.externalResource = externalResource;
        }

        @Override
        public void run() {
//          Cleaning up the important resources
            System.out.println("Doing some cleaning logic here, releasing up very important resource");
            externalResource = null;
        }
    }

    public static void main(String... args) {
        ResourceHolder resourceHolder = new ResourceHolder(new ExternalResource());
        resourceHolder.doSomethingWithResource();
/*
        After doing some important work, we can explicitly release
        resources/invoke the cleaning action
*/
        resourceHolder.releaseResource();
//      What if we explicitly invoke the cleaning action twice?
        resourceHolder.releaseResource();
    }
}

ExternalResource is our hypothetical resource that we want to release when we’re done with it.
The cleaning action is now encapsulated in its own class, and we make use of the CleaniangAction object, we call it’s clean() method in the releaseResources() method to do the cleanup ourselves.
As stated earlier, Cleaners guarantee at most one invocation of the cleaning action, and since we call the clean() method explicitly the Cleaner will not invoke our cleaning action except in the case of a failure like an exception is thrown before the clean method is called, in this case the Cleaner will invoke our cleaning action when the ResourceHolder object becomes Phantom Reachable, that is we use the Cleaner as our safety-net, our backup plan when the first plan to clean our own mess doesn’t work.

❗ IMPORTANT
The behavior of Cleaners during System.exit is implementation-specific. With this in mind, programmers should always prefer to explicitly invoke the cleaning action over relying on the Cleaners themselves..

Cleaners, the effective way

By now we’ve established the right way to use Cleaners is to explicitly call the cleaning action and rely on them as our backup plan.What if there’s a better way? Where we don’t explicitly call the cleaning action, and the Cleaner stays intact as our safety-net.
This can be achieved by having the ResourceHolder class implement the AutoCloseable interface and place the cleaning action call in the close() method, our ResourceHolder can now be used in a try-with-resources block. The revised ResourceHolder should look like below.

ResourceHolder

import java.lang.ref.Cleaner.Cleanable;

public class ResourceHolder implements AutoCloseable {

    private final ExternalResource externalResource;

    private final Cleaner.Cleanable cleanable;

    public ResourceHolder(ExternalResource externalResource) {
        this.externalResource = externalResource;
        cleanable = AppUtil.getCleaner().register(this, new CleaningAction(externalResource));
    }

    public void doSomethingWithResource() {
        System.out.printf("Do something cool with the important resource: %s \n", this.externalResource);
    }
    @Override
    public void close() {
        System.out.println("cleaning action invoked by the close method");
        cleanable.clean();
    }

    static class CleaningAction implements Runnable {
        private ExternalResource externalResource;

        CleaningAction(ExternalResource externalResource) {
            this.externalResource = externalResource;
        }

        @Override
        public void run() {
//            cleaning up the important resources
            System.out.println("Doing some cleaning logic here, releasing up very important resources");
            externalResource = null;
        }
    }

    public static void main(String[] args) {
//      This is an effective way to use cleaners with instances that hold crucial resources
        try (ResourceHolder resourceHolder = new ResourceHolder(new ExternalResource(1))) {
            resourceHolder.doSomethingWithResource();
            System.out.println("Goodbye");
        }
/*
    In case the client code does not use the try-with-resource as expected,
    the Cleaner will act as the safety-net
*/
        ResourceHolder resourceHolder = new ResourceHolder(new ExternalResource(2));
        resourceHolder.doSomethingWithResource();
        resourceHolder = null;
        System.gc(); // to facilitate the running of the cleaning action
    }
}

Cleaners behind the scene

📌 NOTE
To understand more and see how Cleaners work, checkout the OurCleaner class under the our_cleaner package that imitates the JDK real implementation of Cleaner. You can replace the real Cleaner and Cleanable with OurCleaner and OurCleanable respectively in all of our examples and play with it.

Let us first get a clearer picture of a few, already mentioned terms, phantom-reachable, PhantomReference and ReferenceQueue

Consider the following code
```
Object myObject = new Object();
```
In the Garbage Collector (GC) world the created instance of Object is said to be strongly-reachable, why? Because it is alive, and in-use i.e., Our application code has a reference to it that is stored in the myObject variable, assume we don’t set another variable and somewhere in our code this happens
```
myObject = null;
```
The instance is now said to be unreachable, and is eligible for reclamation by the GC.
Now let us tweak the code a bit
```
Object myObject = new Object();
PhantomReference<Object> reference = new PhantomReference<>(myObject, null);
```
Reference is a class provided by JDK to represent reachability of an object during JVM runtime, the object a Reference object is referring to is known as referent, PhantomReference is a type(also an extension) of Reference whose purpose will be explained below in conjunction with ReferenceQueue.
Ignore the second parameter of the constructor for now, and again assume somewhere in our code this happens again
```
myObject = null;
```
Now our object is not just unreachable it is phantom-reachable because no part of our application code can access it, AND it is a referent of a PhantomReference object.
After the GC has finalized a phantom-reachable object, the GC attaches its PhantomReference object(not the referent) to a special kind of queue called ReferenceQueue. Let us see how these two concepts work together
```
Object myObject = new Object();
ReferenceQueue<Object> queue = new ReferenceQueue<>();
PhantomReference<Object> reference1 = new PhantomReference<>(myObject, queue);
myObject = null;
PhantomReference<Object> reference2 = (PhantomReference)queue.remove()
```
We supply a ReferenceQueue when we create a PhantomReference object so the GC knows where to attach it when its referent has been finalized. The ReferenceQueue class provides two methods to poll the queue, remove(), this will block when the queue is empty until the queue has an element to return, and poll() this is non-blocking, when the queue is empty it will return null immediately.
With that explanation, the code above should be easy to understand, once myObject becomes phantom-reachable the GC will attach the PhantomReference object to queue and we get it by using the remove() method, that is to say reference1 and reference2 variables refer to the same object.

Now that these concepts are out of the way, let’s explain two Cleaner-specific types

For each cleaning action, Cleaner will wrap it in a Cleanable instance, Cleanable has one method, clean(), this method ensure the at-most once invocation behavior before invoking the cleaning action.
PhantomCleanable implements Cleanable and extends PhantomReference, this class is the Cleaner’s way to associate the referent(resource holder) with their cleaning action

From this point on understanding the internals of Cleaner should be straight forward.

Cleaner Life-Cycle Overview

Let us look at the life-cycle of a Cleaner object

The static Cleaner.create() method instantiates a new Cleaner but it also does a few other things
- It instantiates a new ReferenceQueue, that the Cleaner objet’s thread will be polling
- It creates a doubly linked list of PhantomCleanable objects, these objects are associated with the queue created from the previous step.
- It creates a PhantomCleanable object with itself as the referent and empty cleaning action.
- It starts a daemon thread that will be polling the ReferenceQueue as long as the doubly linked list is not empty.
By adding itself into the list, the cleaner ensures that its thread runs at least until the cleaner itself becomes unreachable
For each Cleaner.register() call, the cleaner creates an instance of PhantomCleanable with the resource holder as the referent and the cleaning action will be wrapped in the clean() method, the object is then added to the aforementioned linked list.
The Cleaner’s thread will be polling the queue, and when a PhantomCleanable is returned by the queue, it will invoke its clean() method. Remember the clean() method only calls the cleaning action if it manages to remove the PhantomCleanable object from the linked list, if the PhantomCleanable object is not on the linked list it does nothing
The thread will continue to run as long as the linked list is not empty, this will only happen when
- All the cleaning actions have been invoked, and
- The Cleaner itself has become phantom-reachable and has been reclaimed by the GC

Please like and follow for more incoming Java/Spring contents.
Leave comments for questions or any further clarification

DEV Community: Ahmed Jaad

Designing and Implementing an API Rate Limiter

Introduction

Why Should You Rate Limit Your API?

Understanding the Architecture of an API Rate Limiter

Load Balancer

Rate Limiter

Request Processor

Redis as a Distributed Cache

Rules Engine Service and Database

Queue

What is Scaling and How Is It Implemented?

What is Throttling?

Hard Throttling

Soft Throttling

Client Responsibilities

Designing the Application

High-Level Architecture

Domain Modeling

Service Interactions

Endpoints

Throttling

Profiles

Conclusion

Learn about Java cleaners and while you're at it you will also learn about Phantom references.

Java Cleaners: The Modern Way to Manage External Resources

Ahmed Jaad ・ Aug 13 '24

Spring MVC Unveiled: How It Leverages Servlet Technology

Introduction

Bootstrapping and Configuring Spring MVC

ApplicationContext Creation

Practical Example: Dedicated DispatcherServlet for Integration

Self-Configuration

Programmatic Initialization

Practical Example: Dedicated DispatcherServlet for Backoffice

Hierarchical WebApplicationContext Structure

Practical Example: Shared DAO Beans

Dispatching Request

Key Workflow Steps

HandlerExecutionChain

Example: HandlerMethod

Example: Registering an Interceptor

HandlerAdapter and Invoking the Handler

Code Highlights:

How it all fits in with SpringBoot

Embedded Servlet Container

@EnableAutoConfiguration

Automatic Inclusion of @EnableWebMvc

Bringing It All Together

Conclusion

🚀 New article alert! Dive into "Servlet: The Foundation of Java Web Technology" and explore the backbone of Java web development. From handling HTTP requests to enabling frameworks like Spring MVC, servlets are where it all begins.

Servlet: The Foundation of Java Web Technology

Ahmed Jaad ・ Dec 22 '24

Servlet: The Foundation of Java Web Technology

Introduction

What is a Servlet?

Servlet Container

Servlet API

Servlet

Servlet Lifecycle:

Servlet In Action: Handling Account Balance Requests

Simpler Servlet For HTTP Requests:

Filters

When to Use Filters:

Filter Lifecycle:

Example: Securing the /balance Path

ServletContext

Context Path

Dynamic Component Registration

Global Application Storage

Listeners

Practical Example: Managing User Data with HttpSessionListener

ServletContainerInitializer

How Does It Work?

Practical Example: Centralized Security

The Role of @HandlesTypes

Registering Components with the Servlet Container

Conclusion

Java Cleaners: The Modern Way to Manage External Resources

Introduction

Example: Securing the `/balance` Path

Practical Example: Managing User Data with `HttpSessionListener`

The Role of `@HandlesTypes`