1. Introduction

When it comes to big data and many potential parties interested in it, distribution is critical. To that end, there are simple and complex solutions.

In this tutorial, we’ll take a look at Alibaba Nacos. First, we see what it is. After that, we go over different ways to configure and use Nacos. Finally, we demonstrate what we can do with the platform.

2. What Is Nacos?

Nacos is a platform offering various tools:

• dynamic service discovery
• configuration management
• distributed locking

It’s mainly used for building highly distributed systems.

At its core, Nacos provides a service discovery system enabling us to dynamically start and stop instances of different services, and still have other services able to reach them. This is particularly valuable in microservices applications where we might have a larger number of applications that each have a varied number of running instances.

Nacos also offers tools for managing the configuration of applications, providing a way to configure everything in a single place and have the suite of running instances automatically reflect this. Furthermore, we also have tools for distributed locking, enabling distributed applications to share finite resources without conflict.

As expected, there are some more recently introduced features for working with AI Agents – including MCP Servers, Skills, Prompts, and AgentCard discovery. However, these are out of scope for this article.

3. Running Nacos

The easiest way to get started quickly with Nacos is by using Docker.

In particular, we can start a standalone Nacos instance using a fairly simple docker-compose.yml file:

services:
  nacos:
    image: nacos/nacos-server:latest
    environment:
      - MODE=standalone
      - NACOS_AUTH_TOKEN=U2VjdXJlTmFjb3NBdXRoVG9rZW5Gb3JEZW1vUHVycG9zZXMxMjM=
      - NACOS_AUTH_IDENTITY_KEY=serverIdentity
      - NACOS_AUTH_IDENTITY_VALUE=nacos-demo-node
    ports:
      - "8080:8080"
      - "8848:8848"
      - "9848:9848"

The NACOS_AUTH_TOKEN variable must contain a string that’s at least 32 characters long and then base-64 encoded. On the other hand, NACOS_AUTH_IDENTITY_KEY and NACOS_AUTH_IDENTITY_VALUE can contain any values that identify the current Nacos instance.

At this point, we can run the setup:

$ docker compose up
.....
nacos-1  | 2026-04-27 14:20:53,304 INFO Nacos Console started successfully in 311 ms

Once started, we can access the console on http://localhost:8080.

On first access, we need to configure a password for the nacos user:

Now, let’s log into the management console:

Running Nacos in this way, we get a set of default data already present to work with, but we can use this UI to configure a custom environment.

4. Using Nacos With Java SDK

Now that we’ve got Nacos running, we can use it from applications.

To do this, we first need to add the client dependency to the project. At the time of writing, the latest version is 3.2.1.

If using Maven, we can include this dependency in the pom.xml file:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>3.2.1</version>
</dependency>

To leverage Nacos within the application, we need to know the address of the Nacos server we’re working with, the namespace we’re going to use if it’s not the default, and any other configuration properties for the service in question:

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
properties.setProperty(PropertyKeyConst.NAMESPACE, "public");

Now, we can then create a client for each of the Nacos services that we require:

ConfigService configService = NacosFactory.createConfigService(properties);
NamingService namingService = NacosFactory.createNamingService(properties);
LockService lockService = NacosFactory.createLockService(properties);

These service clients are then ready for us to use.

5. Configuration Management

Nacos enables the management of configuration settings in a single, central place, so services can make use of them automatically.

5.1. Managing Configuration

In particular, we can manage the configuration settings from within the management console by selecting the Configurations entry on the sidebar:

This section gives us a list of all the configuration entries that are currently in the system, as well as letting us add new ones.

New entries are added using the New Config button at the top:

From here, we enter values for each configuration element:

• Data ID: ID of the configuration entry, typically in the same format as a fully qualified class name
• Group: group the configuration entry belongs to, typically representing the product the configuration is for
• Format: format that the configuration entry is in, typically one of Text, JSON, XML, YAML, HTML, Properties, or TOML
• Content: actual configuration entry, in the specified format

In addition, we can specify description, application, and tags. However, these are only metadata about the entry and don’t influence its use at all.

Conveniently, we can see historical versions of configurations:

Thus, we have the ability to edit or delete configuration settings, as well as see the details of the entry and the history of all changes to it.

5.2. Fetching Configuration

Once we’ve got the configuration set up, we need to be able to use it. To that end, we set configurations via the ConfigService that we created earlier.

Specifically, perhaps the easiest way is to simply call getConfig() passing in the data ID and group, as well as a timeout in milliseconds:

String config = configService.getConfig("com.baeldung.nacos.Example", "DEFAULT_GROUP", 1000);

This way, we immediately get the value of this configuration setting. In the event that the configuration doesn’t exist, or Nacos can’t be reached, we get null back instead.

However, this only gives us the raw value. Normally, we need to already know what type it is to know what to do with it. To avoid this, we can instead use getConfigWithResult() to get back a richer object that includes the type of config setting (text, JSON, or similar), so that we know how to handle that:

ConfigQueryResult config = configService.getConfigWithResult("com.baeldung.nacos.Example", "DEFAULT_GROUP", 1000);
String configType = config.getConfigType();
String configValue = config.getContent();

This way, we always get a result, even if the config setting doesn’t exist or the Nacos server is unreachable. In those cases, we get a valid ConfigQueryResult object that contains null for the content and config type.

5.3. Listening to Configuration Changes

As well as simply fetching the configuration value at a single point in time, we can register a callback for whenever the value changes. This way, we can be responsive to configuration changes without needing to manually poll the values ourselves.

In particular, let’s register a listener for a specific configuration setting using addListener():

configService.addListener("com.baeldung.nacos.Example", "DEFAULT_GROUP", new AbstractListener() {
    @Override
    public void receiveConfigInfo(String configInfo) {
        LOG.info("Received config info: {}", configInfo);
    }
});

This block runs every time the config setting changes, with the new value. Unfortunately, this only happens when the value changes, not immediately.

As an alternative, we can use getConfigAndSignListener() to retrieve the current configuration and immediately register a listener:

String config = configService.getConfigAndSignListener("com.baeldung.nacos.Example", "DEFAULT_GROUP", 1000, new AbstractListener() {
    @Override
    public void receiveConfigInfo(String configInfo) {
        LOG.info("Received config info: {}", configInfo);
    }
});

Thus, we get the current config for use right now, and to also respond whenever the configuration changes as needed. In a way, this is a shorthand for both getConfig() and addListener() in a single call.

6. Service Discovery

On top of configuration, Nacos also provides service discovery of distributed services. This works by services registering their address and port against a well-known name, and then enabling clients to look up these by name later on.

6.1. Registering a Service

To begin with, we register services using the NamingService that we constructed earlier.  We do this using the registerInstance() method, passing in the service name and address:

namingService.registerInstance("BaeldungTest", "localhost", 8848);

Alternatively, we can pass in an Instance class containing some more details about the service:

Instance instance = new Instance();
instance.setIp("localhost");
instance.setPort(8848);
instance.setEnabled(true);
instance.setHealthy(true);
Map<String, String> metadata = new HashMap<>();
metadata.put("Example", "value");
instance.setMetadata(metadata);
namingService.registerInstance("BaeldungTest", instance);

Notably, if we do this, we need to ensure that the enabled and healthy flags are set, since they default to false, and therefore the service won’t be available for discovery.

If we need to update the service registration – for example, to change whether the service is healthy – then we can simply re-register the same service name and address with the new details. Nacos detects that these are the same details and updates them instead of creating a new registration.

6.2. Unregistering a Service

Importantly, the NamingService client automatically unregisters any services that it registered when it closes down. This means that we don’t need to do anything special, and as soon as the service shuts down, Nacos should remove it automatically. Still, this depends on other factors such as heartbeat and ephemeral instances.

However, sometimes we need to do this ourselves without shutting down the entire service. To do so, we turn to deregisterInstance():

namingService.deregisterInstance("BaeldungTest", "localhost", 8848);

This takes the service name and either the address and port, or the Instance class, as with registerInstance(). With that information, deregisterInstance() immediately removes this address from the Nacos server to prevent discovery.

6.3. Discovering Service Instances

Once services are registered, we need to be able to discover them to actually leverage what they offer. Nacos offers several ways that we can achieve this.

Perhaps the most useful way to service discovery is selectOneHealthyInstance(). The method takes the service name and randomly returns one healthy registered instance:

Instance baeldungTest = namingService.selectOneHealthyInstance("BaeldungTest");
String address = baeldungTest.getIp();
int port = baeldungTest.getPort();

If nothing is registered for the given service name, the code throws an IllegalStateException to indicate that fact, since this means there are no services that we can use right now.

Alternatively, selectInstances() and getAllInstances() are able to return every registered instance instead of just one of them:

List<Instance> allInstances = namingService.getAllInstances("BaeldungTest");
List<Instance> allHealthyInstances = namingService.selectInstances("BaeldungTest", true);

Notably, selectInstances() and selectOneHealthyInstance() only return services that are marked as enabled, and where the healthy flag is as expected. getAllInstances() returns every instance regardless of these flags.

6.4. Listening to Service Discovery Changes

In addition to selecting an instance when we need to, we can register a callback to be triggered whenever there’s a change to the instances for a given service name:

namingService.subscribe("BaeldungTest", (event) -> {
    NamingChangeEvent namingChangeEvent = (NamingChangeEvent) event;
    LOG.info("Added Instances: {}", namingChangeEvent.getAddedInstances());
    LOG.info("Removed Instances: {}", namingChangeEvent.getRemovedInstances());
    LOG.info("Modified Instances: {}", namingChangeEvent.getModifiedInstances());
});

We can then do whatever we want with this information – for example, we might want to maintain a local cache of instances so that we don’t need to make a call to Nacos every time we want to look one up.

7. Distributed Locks

Another important feature that Nacos has is support for distributed locking of resources. Specifically, Nacos enables access control to resources so that they can’t be accessed by different services or threads at the same time.

To obtain locks, we use the LockService that we created earlier and call the lock() method, providing a definition of the lock that we want:

Boolean result = lockService.lock(new NLock("Baeldung", 5000L));

When obtaining a lock, we need to provide the identifier of the resource and a maximum time period for the lock, measured in milliseconds. Critically, we receive a result indicating whether we got the lock or not.

Locks release either after the provided time period or by explicitly unlocking them with the unlock() method:

lockService.unlock(new NLock("Baeldung", 5000L));

Unlike with service registrations, locks aren’t automatically removed when the client disconnects, so we need to ensure that we manage this sensibly.

8. Summary

In this article, we took a quick look at Alibaba Nacos, we saw what it is and how we can use it in applications.

In summary, Nacos is a platform for managing distributed systems by providing service discovery, centralized configuration, and coordination capabilities.

As usual, all of the examples from this article are available over on GitHub.

       

1. Introduction

In this tutorial, we’ll study two Java solutions for the Sock Merchant problem.

2. The Sock Merchant Problem

In the Sock Merchant problem, we have a merchant with a large pile of socks for sale that must be paired by color. We represent the socks’ colors by an array of integers, socks. The merchant’s goal is to determine how many pairs of matching socks there are.

Therefore, we have three inputs:

• n: the number of socks in the collection
• socks: the array holding the colors of n socks
• k: the maximal color ID in this array, meaning 1 <= socks[i] <= k (for 0 <= i < n).

For example, let’s say we have n = 7 socks with socks = [11, 22, 22, 11, 111, 33, 222] and k=222:

Here, we have only 5 colors. with one pair of color 11 and one of color 222. There are three odd socks left, one of each color. Hence, we return 2 as the number of pairs.

3. Array-Based Solution

An array-based solution works best when we know k is small. Here, we use an array counts to count the occurrences of each sock. Then, we iterate through it, dividing each count by two to calculate the total number of pairs:

public int countPairsWithArray(int n, int[] socks, int k) {
    int[] counts = new int[k];
    int pairs = 0;
    for (int i = 0; i < n; i++) {
        counts[socks[i]]++;
    }
    for (int count : counts) {
        pairs += count / 2;
    }
    return pairs;
}

Technically, we could omit n from the argument list and use socks.length in the code. We kept n in the method signature to follow the problem formulation more closely and make the solution easier to read.

This solution has time and space complexities of O(n + k). If k is O(n), the complexity simplifies to O(n).

4. HashSet-Based Solution

An array-based solution degrades performance when the range of color IDs is unbounded, unknown, or very large. For instance, the counts array for a very large k could not only be sparse (mostly 0s) if the number of unique colors is much smaller, but also too large to fit in the memory.

For such cases, we use HashSet. Here, our HashSet unmatchedSocks stores unmatched socks. As we iterate through the input array,we check if the current sock’s color is already in unmatchedSocks:

• if it isn’t, we add it
• otherwise, we have successfully found a pair!

Whenever we find a pair, we increment our pair counter and remove that color from  unmatchedSocks, so that the next pair of that color can be identified correctly:

public int countPairsWithSet(int[] socks) {
    Set<Integer> unmatchedSocks = new HashSet<>();
    int pairs = 0;
    for (int sock : socks) {
        if (unmatchedSocks.contains(sock)) {
            pairs++;
            unmatchedSocks.remove(sock);
        } else {
            unmatchedSocks.add(sock);
        }
    }
    return pairs;
}

The HashSet-based solution’s average time complexity is O(n) since we iterate through the set exactly once, and HashSet operations add() and size() are O(1) on average.

However, HashSet suffers from collisions, so it has a log-linear O(n log n) worst-case time complexity for case where k is O(n). If k is O(1), the time complexity evaluates to O(n), which is same as that of  the array-based algorithm.

The space complexity is O(n + k).

5. Testing

5.1. Array-based Solution Testing

First, we test the array-based solution.

We create our socks array and pass it along with its length and the maximum color ID:

public void givenSockArray_whenUsingArray_thenReturnsCorrectPairCount() {
    SockMerchant merchant = new SockMerchant();
    int[] socks = {11, 22, 22, 11, 33, 3, 33, 111111, 33, 222222};
    int colorMax = 222223;
    int foundPairs = merchant.countPairsWithArray(socks.length, socks, colorMax);
    assertEquals(3, foundPairs);
}

We expect the test to return 3 for success.

5.2. HashSet-based Solution Testing

Let’s test the HashSet-based solution:

public void givenSockArray_whenUsingSet_thenReturnsCorrectPairCount() {
    SockMerchant merchant = new SockMerchant();
    int[] socks = {11, 22, 22, 11, 33, 3, 33, 111111, 33, 222222};
    int foundPairs = merchant.countPairsWithSet(socks);
    assertEquals(3, actualPairs);
}

As before, we expect the test to return 3 for success.

6. Conclusion

In this article, we studied two solutions, based on two different Java data structures, for the Sock Merchant problem.

The array-based method is fast and memory-efficient when the color domain is small and the color IDs are contiguous. However, it wastes memory and computation time if the color IDs are sparse or k is exceedingly large.

On the other hand, the HashSet approach is more versatile since it can handle arbitrarily large integers and sparse datasets without allocating massive contiguous blocks of memory. Furthermore, we can adapt the HashSet logic to group custom objects or strings.

As always, the complete code examples are available over on GitHub.

       

1. Introduction

When testing applications with Selenium, waiting for a page to load completely is more complex when it comes to modern pages, as they rely heavily on JavaScript for rendering. These kinds of pages make asynchronous calls and manipulate the DOM after the initial HTML has loaded. Therefore, checking if it’s loaded isn’t sufficient to ensure the app is ready for interaction.

Introducing an arbitrary delay is a common but problematic choice. If the page loads faster than the delay, the test wastes time. Otherwise, if the page loads slower due to network conditions or server response time, the test may fail.

In this tutorial, we’ll explore different strategies for waiting until a JavaScript-heavy page is fully loaded in Selenium WebDriver without introducing arbitrary delays.

2. Problem and Setup

We’ll define a page as loaded when all asynchronous operations for the current view have completed. This includes HTTP requests, dynamic DOM updates, and framework-specific processing. Navigating to a new view is treated as a new page load that requires its own wait strategy.

Selenium provides two main wait strategies. With implicit waits, we set a global timeout for element lookups. On the other hand, with explicit waits, we wait for specific conditions using a WebDriverWait instance. We’ll only use explicit waits, which provide precise control over what conditions to check.

2.1. Creating a Helper Class

Let’s create a helper class that encapsulates our waiting logic. It wraps a WebDriverWait instance and requires a timeout value so our tests don’t wait indefinitely in unexpected scenarios:

public class PageLoadHelper {
    private final WebDriverWait wait;
    public PageLoadHelper(WebDriver driver, Duration timeout) {
        this.wait = new WebDriverWait(driver, timeout);
    }
    // ...
}

We’ll add all the different wait strategies to this class, making them easy to reuse. We’ll only need the until() method from WebDriverWait, which polls the condition until it returns true or times out. This condition is written as a lambda that takes the current driver:

public void waitUntil() { 
    wait.until(driver -> { 
        JavascriptExecutor js = (JavascriptExecutor) driver; 
        return // condition...
    }); 
}

While we won’t need a specific driver implementation, the only requirement is that it implements the JavaScriptExecutor interface. We need this because the states we want to query are only accessible through the browser’s JavaScript runtime, not via the standard WebDriver API.

Also, since some of the checks rely on specific frameworks, most methods in this article start with checks such as typeof someFrameworkObject === ‘undefined’. If the framework isn’t there, the condition returns true immediately, making the method safe to call on any page and useful when chaining.

3. Waiting for Document Ready State

The most fundamental check is inspecting the browser’s document.readyState property. This property becomes complete when the page and all its resources have finished loading. It’s the default behavior of driver.get(). It’s useful for SPA navigation, such as right after clicking a link that changes the view without a full page reload.

Let’s add a method to our PageLoadHelper that executes a script and waits until it returns the result we’re looking for:

public void waitForDocumentReady() {
    wait.until(driver -> {
        JavascriptExecutor js = (JavascriptExecutor) driver;
        return js.executeScript("return document.readyState")
          .equals("complete");
    });
}

While this covers the initial HTML page load, it doesn’t apply to asynchronous JavaScript that runs after the DOM is ready.

4. Waiting for jQuery AJAX Calls to Complete

Many apps still use jQuery for AJAX requests. It maintains an internal counter, jQuery.active, that tracks the number of pending requests. When this reaches zero, all requests have completed.

Let’s add a method that checks whether there are any pending requests:

public void waitForJQueryToFinish() {
    wait.until(driver -> {
        JavascriptExecutor js = (JavascriptExecutor) driver;
        return (Boolean) js.executeScript(
          "return (typeof jQuery === 'undefined') || (jQuery.active === 0)");
    });
}

It first checks whether jQuery is present on the page. If not, the condition returns true immediately. This type of guard is useful when building a universal test suite, and not all pages use jQuery.

However, if an AJAX request hasn’t started yet when we call it, the condition sees jQuery.active === 0 and returns before any request fires. So, let’s create another method that waits for a request to start:

public void waitForJQueryToStart() {
    wait.until(driver -> {
        JavascriptExecutor js = (JavascriptExecutor) driver;
        return (Boolean) js.executeScript(
          "return (typeof jQuery === 'undefined') || (jQuery.active > 0)");
    });
}

We can then chain these two to ensure that requests start before waiting for them to finish. But even with this approach, if all requests fire and complete before we have a chance to observe jQuery.active increasing, we’ll end up waiting until Selenium times out.

5. Waiting for Modern Angular Apps to Stabilize

Angular 2+ uses RxJS for HTTP calls, and it provides a testability API that allows us to check if the app is stable, meaning that it has completed all pending requests:

public Boolean waitForModernAngularAppStable() {
    return wait.until(driver -> {
        JavascriptExecutor js = (JavascriptExecutor) driver;
        String script = """
          return (
            typeof getAllAngularTestabilities === 'undefined' 
            || getAllAngularTestabilities().every(t => t.isStable())
          )
          """;
        return (Boolean) js.executeScript(script);
    });
}

We check whether getAllAngularTestabilities is undefined to guard against future API changes.

6. Waiting for React Apps to Be Ready

React apps don’t have a built-in JavaScript API we can use to test app readiness universally, so we have to handle it on a case-by-case basis. A common approach is to make an element visible only after we’ve finished making all the requests we need.

Something as simple as a “done” flag that adds a CSS class to a button is enough:

<button id="doneButton" className={done ? 'visible' : ''}>
    All Done
</button>

Then, we can add an all-purpose method to wait for elements to be clicked:

public void waitForElementToBeClickable(By locator) {
    wait.until(ExpectedConditions.elementToBeClickable(locator));
}

Finally, we can test it by passing the ID of the element:

@Test
void whenWaitForElementClickable_thenClickable() {
    driver.get(PAGE_URL);
    pageLoadHelper.waitForElementToBeClickable(By.id("doneButton")); 
    
    assertTrue(driver.findElement(By.id("doneButton")).isDisplayed()); 
}

This approach isn’t limited to React and can be used with any page. Most importantly, the done flag must be set when the application is truly ready for interaction. If completing the initial set of requests triggers additional requests, the flag must account for the entire chain before being set to true.

7. Injecting a Custom Flag in the Window Object

In modern JavaScript apps, we usually use Promises to make requests, and we can use the “Promise.all()” function to wait for a set of promises to complete. Most importantly, if we don’t have access to a universal tool, we can always modify the window variable to include our own flags.

So, if we know the slowest part of the app is completing a set of promises and we can’t reliably use the app before that, one alternative is creating a simple listener that adds a flag indicating when our app is ready:

window.appReady = false;
// start promises ...
Promise.all(promises).then(() => {
    window.appReady = true;
});

It’s important to initialize the variable to false so we don’t get undefined when reading its value. We can then wait until this flag appears when testing the app with Selenium:

public void waitForJsAppReady() {
    wait.until(driver -> {
        JavascriptExecutor js = (JavascriptExecutor) driver;
        return (Boolean) js.executeScript(
          """
          return (
            typeof window.appReady === 'undefined' 
            || window.appReady === true
          )
          """);
    });
}

This will work for any app running in a modern browser.

8. Patching the Fetch API

Another common approach in modern JavaScript apps is to use fetch, which also doesn’t provide a standard way to count pending requests. So, one option is to implement it on our own. We can do this by replacing the fetch implementation with a custom one that increments a global fetchPending counter and delegates the actual execution to the original implementation:

window.fetchPending = 0;
const originalFetch = window.fetch;
window.fetch = function(...args) {
    window.fetchPending++;
    return originalFetch.apply(this, args)
      .finally(() => window.fetchPending--);
};

This must be called before the requests we want to track are fired. Then, every request made with the fetch command becomes trackable (even on error, since we decrement it in a finally block). Finally, we can wait until fetchPending reaches zero, like in our appReady solution.

For requests that fire automatically on page load, the interception must happen before navigation. Selenium now supports this via the Chrome DevTools Protocol, but that is beyond the scope of this article.

9. Summary

The strategies we covered address different scenarios. Let’s see how they compare:

In practice, combining strategies works best: start with waitForDocumentReady(), apply a framework-specific check, then confirm a meaningful element is interactable.

10. Conclusion

In this article, we explored several strategies for waiting until JavaScript-heavy pages fully load using Selenium. We started with the basic document.readyState check and covered Selenium’s built-in WebDriverWait for waiting on element states. We also extended our approach to handle jQuery AJAX calls, modern Angular applications, alternatives to React components, and pure JavaScript apps.

No single strategy covers all cases, and the right choice depends on the technologies the app uses and the level of control we have over its source code. Using a helper class like PageLoadHelper simplifies composing and reusing strategies across a test suite.

As always, the source code is available over on GitHub.

       

1. Overview

As AI systems grow more capable, a single “generalist” agent often becomes inefficient. It tries to handle everything in one context window, which leads to noisy prompts, slower responses, and degraded output quality. A better approach is to split responsibilities across specialized agents and let a central orchestrator coordinate them.

This is exactly what Subagent Orchestration enables in Spring AI. Using the Task tool from the spring-ai-agent-utils library, we can build hierarchical agent systems where each subagent works in an isolated context and returns only essential results.

In this tutorial, we’ll implement this pattern end-to-end using real APIs from the Spring ecosystem. We’ll learn how the orchestration works, how to configure subagents, and how to build a working system that dynamically delegates tasks.

2. Understanding Subagent Orchestration

Subagent orchestration is a pattern where a primary AI agent delegates work to smaller, specialized agents. Each subagent is designed for a specific responsibility and operates in its own context window. This isolation ensures that prompts remain focused and prevents unnecessary information from polluting the reasoning process.

Unlike traditional service orchestration, the delegation decision isn’t hardcoded. The main agent uses LLM to decide when a task should be delegated. This decision is based on natural language descriptions provided for each subagent, making the system flexible and adaptive. This approach improves separation of concerns, prompt clarity, maintainability, extensibility, and model specialization.

2.1. Why Use Specialized Subagents?

Specialized subagents help us create more modular AI systems. For example, in an AI travel assistant, one subagent can search flights, another can recommend hotels, and another can build personalized itineraries based on user preferences. This allows each subagent to focus on a specialized responsibility instead of relying on a single large prompt.

Each subagent receives a focused responsibility instead of competing for context inside a shared workflow. This pattern becomes especially useful in enterprise systems where AI applications continue to grow in complexity over time.

2.2. How Spring AI Supports Orchestration

Spring AI Community Agent Utils provides orchestration utilities through TaskTool and ClaudeSubagentReferences. These components help us register subagents, load subagent definitions dynamically, delegate tasks automatically, and orchestrate multiple AI workflows.

One of the most interesting aspects of this approach is that subagents can be defined in markdown files instead of Java classes.

3. Project Setup

Before implementing Subagent Orchestration, we’ll set up a simple Spring Boot application using Spring Initializr with Spring AI starter OpenAI, starter-test, and Spring AI Community Agent Utils. We’ll first add the required dependencies and then configure the OpenAI model and markdown-based subagent definitions.

In this application, we’ll build an AI-powered orchestration system that delegates work to multiple specialized subagents. One subagent reviews the code quality of a Spring Boot application, while another generates concise technical documentation. A central orchestrator analyzes the user request and coordinates these subagents to produce a combined response.

3.1. Adding Maven Dependencies

First, let’s configure the required dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
        <version>2.0.0-M5</version>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>org.springaicommunity</groupId>
        <artifactId>spring-ai-agent-utils</artifactId>
        <version>0.4.2</version>
    </dependency>
</dependencies>

This configuration adds the core dependencies required for our application. These dependencies provide Spring Boot application support, OpenAI integration through Spring AI, orchestration utilities for subagents, and testing support. After adding the dependencies, we’ll configure the OpenAI API key.

3.2. Configuring OpenAI Access

Next, we’ll configure the OpenAI API key, the default LLM model, and the location of the markdown-based subagent definitions inside application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4.1-mini
spring.application.name=spring-ai-subagent
agent.tasks.paths=classpath:/agents/*.md

We should replace OPENAI_API_KEY with a valid OpenAI API key or expose it through an environment variable to avoid storing sensitive credentials directly in the codebase.

The agent.tasks.paths property points to the markdown-based subagent definitions located under src/main/resources/agents/. Spring AI uses these files to dynamically load and register specialized subagents during application startup.

4. Creating Specialized Subagents

This project uses markdown files to define specialized subagents. Their locations are declared as classpath resources. This approach keeps agent behavior externalized and easy to maintain. First, we’ll create an agents directory under the path src/main/resources/.

4.1. Creating the Code Reviewer Subagent

Let’s create a subagent responsible for reviewing code quality. The Markdown body acts as the subagent’s system prompt and defines its specialized behavior.

We’ll add a code-reviewer.md file under path src/main/resources/agents/ with the following instructions:

---
name: code-reviewer
description: >
  Expert code reviewer. Use proactively after writing or modifying code
  to surface quality, security, and readability issues.
tools: Read, Grep, Glob
disallowedTools: Edit, Write
model: sonnet
---
You are a senior code reviewer with expertise in software quality.
**When Invoked:**
1. Run `git diff` to identify recent changes
2. Inspect the modified files and surrounding context
3. Check for issues in the areas listed below
**Review Checklist:**
- Code clarity and readability
- Proper naming conventions
- Error handling and edge cases
- Security vulnerabilities
**Output:** Clear, actionable feedback organized by file, with line references.

This subagent focuses only on code analysis responsibilities. Externalizing the behavior into markdown files makes it easier to evolve prompts without modifying Java classes.

4.2. Creating the Documentation Writer Subagent

Next, let’s create another subagent that specializes in technical documentation. We’ll add a documentation-writer.md file under src/main/resources/agents/and define the following instructions:

---
name: documentation-writer
description: >
  Technical documentation specialist for architecture explanations,
  workflow summaries, and concise developer-facing docs.
model: default
---
You are a senior technical documentation specialist.
Your responsibilities:
- Generate concise technical documentation
- Explain Spring Boot and Java application architecture
- Summarize workflows clearly
- Produce developer-friendly explanations
- Keep documentation simple and technically accurate

This subagent focuses entirely on generating developer documentation. Now we have two specialized subagents named code-reviewer and documentation-writer.

5. Configuring the Main Orchestrator Agent

The orchestrator is responsible for loading subagents, registering orchestration tools, and executing delegated workflows. This main agent is the entry point that a user interacts with directly. Its underlying large language model (LLM) has access to the Tasktool, which exposes a catalog of available subagents. When the main agent decides that a specialist better handles a portion of a user request, it invokes the Tasktool, passing in the subagent name and a task description.

5.1. Configuring Subagent References

Spring AI Community Agent Utils provides ClaudeSubagentReferences to load markdown-based subagents. The following configuration dynamically loads subagents from the markdown resources directory:

@Configuration
public class AgentConfig {
    @Value("${agent.tasks.paths}")
    private List<Resource> agentPaths;
    @Bean
    @Primary
    public ChatClient orchestratorChatClient(ChatClient.Builder chatClientBuilder) {
        SubagentType claudeType = ClaudeSubagentType.builder()
          .chatClientBuilder("default", chatClientBuilder.clone())
          .build();
        ToolCallback taskTool = TaskTool.builder()
          .subagentReferences(ClaudeSubagentReferences.fromResources(agentPaths))
          .subagentTypes(claudeType)
          .build();
        return chatClientBuilder.clone()
          .defaultToolCallbacks(taskTool)
          .build();
    }
}

The two key classes wire together are TaskTool (the tool that the orchestrator’s LLM calls) and ClaudeSubagentType (which tells the tool how to spawn a subagent and which ChatClient.Builder to use). Note this .clone() calls on chatClientBuilder. This is important because the orchestrator and each subagent need their own independent ChatClient.Builder instance so they do not share default options or system prompts.

5.2. Creating the Orchestrator Service

This service acts as the entry point for orchestrated AI requests. The main agent’s LLM automatically decides whether to delegate to a subagent based on the task descriptions in the Agent Registry:

@Service
public class OrchestratorService {
    private final ChatClient chatClient;
    public OrchestratorService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    public String ask(String userMessage) {
        return chatClient.prompt(userMessage).call().content();
    }
}

The service itself remains very small because the orchestration complexity is handled internally through Spring AI tools. Notice that there is no manual subagent invocation code here. The delegation happens transparently inside the LLM reasoning loop when the model selects the Task tool.

5.3. Execute Orchestrated Workflows

Now we’ll execute orchestrated workflows. The following method triggers multiple specialized subagents:

public class SpringAiSubagentApplication {
    private static final Logger logger = LoggerFactory.getLogger(SpringAiSubagentApplication.class);
    public static void main(String[] args) {
        SpringApplication.run(SpringAiSubagentApplication.class, args);
    }
    @Bean
    CommandLineRunner demo(OrchestratorService orchestratorService) {
        return args -> {
            String response = orchestratorService.ask(
              """
              Perform the following tasks:
              - Review the code quality.
              - Generate concise technical documentation like user guide.
              """
            );
            logger.info("{}", response);
        };
    }
}

This prompt allows the orchestrator to delegate responsibilities across multiple subagents. When we run the application, Spring AI loads the markdown-based subagents, routes the request through the orchestration layer, and generates a combined response from the specialized agents.

The following screenshot shows the output generated by the multi-subagent orchestration workflow:

From the generated response, we can clearly see how each subagent handles its own specialized responsibility. The code-reviewer subagent focuses on analyzing code quality concerns, while the documentation-writer subagent generates concise technical documentation. This separation of responsibilities is one of the main advantages of subagent orchestration.

6. Testing Subagent Orchestration

AI orchestration workflows should still be tested like any other application component. The application includes integration testing for orchestration behavior.

6.1. Testing Subagent Loading

The following test verifies that Spring AI can load subagent definitions correctly:

@Test
void givenSubagentDefinitions_whenLoadingSubagents_thenReferencesAreCreated() {
    var references = ClaudeSubagentReferences.fromResources(agentPaths);
    assertThat(references).isNotNull();
}

This test ensures the orchestration layer can successfully load markdown-based subagents.

6.2. Testing Orchestrated Responses

Next, let’s verify that the orchestrator can execute requests successfully:

@Test
void givenPrompt_whenExecutingOrchestration_thenResponseIsGenerated() {
    List<Resource> agentResources = List.of(
      new ClassPathResource("agents/test-agent.md")
    );
    SubagentType claudeType = ClaudeSubagentType.builder()
      .chatClientBuilder("default", chatClientBuilder.clone())
      .build();
    ToolCallback taskTool = TaskTool.builder()
      .subagentReferences(ClaudeSubagentReferences.fromResources(agentResources))
      .subagentTypes(claudeType)
      .build();
    ChatClient chatClient = chatClientBuilder.clone()
      .defaultToolCallbacks(taskTool)
      .build();
    String result = chatClient.prompt("Explain how the authentication module works.")
      .call()
      .content();
    assertThat(result).isNotBlank();
    assertThat(result).contains("authentication");
}

This integration test validates the orchestration flow. Here, the unit test should mock the model layer and verify the orchestration output. This test validates the service contract and keeps orchestration behavior verifiable without external API calls.

7. Conclusion

In this article, we built a subagent orchestration system using Spring AI and Spring AI Community Agent Utils. We  created specialized subagents for code review and technical documentation, then orchestrated them through a centralized AI workflow. This approach helps keep AI systems modular, maintainable, and easier to evolve.

We also explored how Spring AI provides a clean and declarative way to build hierarchical multi-agent systems. By isolating each subagent within its own context window, we can reduce the context pollution that often impacts single-agent workflows. The Markdown-based configuration makes it straightforward to define and version subagents without introducing additional Java implementations. We also saw how TaskTool acts as the bridge between the orchestrator and specialized subagents.

As AI applications continue to grow in complexity, subagent orchestration offers a practical way to distribute responsibilities among focused agents rather than relying on a single large prompt.

As always, the code for this example is available over on GitHub.

       

1. Overview

MCP (Model Context Protocol) servers are the basis of modern AI handling and development. To that end, knowing how to configure one and integrate it into projects can be essential.

In this tutorial, we’ll learn how to build an MCP server with Spring AI and connect it to an AI harness such as Claude Desktop. To start, we create a simple hello-world tool, test it using the MCP Inspector, and then register it with Claude Desktop as a custom connector.

Once the basics are in place, we’ll take it one step further and expose a rich, interactive HTML UI — a fortune wheel that randomly picks today’s sport. In that implementation, we’ll see how Spring AI’s @McpTool and @McpResource annotations let the harness render the page inline in the chat and feed the result back into the conversation.

2. Creating an MCP Server

The Model Context Protocol (MCP) provides a standardized way for AI assistants such as Claude Code or Claude Desktop to invoke some custom functionality whenever the model sees fit. An MCP server is the lightweight backend that exposes this functionality via tools, resources, and prompts.

Let’s start by creating a simple hello-world MCP server. First, we add the spring-ai-starter-mcp-server-webmvc dependency to the pom.xml:

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

Additionally, we use spring-ai-bom for version management:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.0-M6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Then, let’s configure the server port and the MCP transport protocol that the server exposes. Spring AI supports three transport options:

• stdio for local process-based communication
• sse for the legacy HTTP transport based on Server-Sent Events
• streamable for the newer Streamable HTTP transport that handles both requests and streamed responses over a single endpoint

Here, we use the streamable protocol. So, let’s configure it in application.properties:

server.port=3001
spring.ai.mcp.server.protocol=STREAMABLE

Finally, we add a tool that says hello from the server back to the user:

@SpringBootApplication
class McpUiApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpUiApplication.class, args);
    }
    @McpTool(
        title = "Say Hello",
        name = "say-hello",
        description = "A simple tool that returns a greeting message."
    )
    String sayHello() {
        return "Hello from the MCP UI Application!";
    }
}

As expected, this tool is exposed to the AI agent, and the greeting message is returned to the user whenever the model decides to invoke it.

3. Testing the MCP Server

There are several ways to connect to and test an MCP server. Let’s try to use some of them to do that and trigger the Say Hello tool.

3.1. Test Using MCP Inspector

One convenient option is the MCP Inspector, an interactive developer tool designed for testing and debugging MCP servers:

npx @modelcontextprotocol/inspector

This command starts a local proxy server along with a web-based UI that we can open in the browser to test the MCP. Using this interface, we can perform different actions:

1. connect to an MCP server
2. see the resources, prompts, and tools it exposes
3. trigger tools

The interface is fairly straightforward:

As we can see, we are connected to the MCP server we created using Spring AI, and we successfully ran its Say Hello tool.

3.2. Test Using Claude Desktop

Alternatively, we can use an AI harness to test the MCP server. After all, the end goal here is to use the MCP server from a desktop application such as Claude Desktop.

Firstly, we need to register it in the claude_desktop_config.json file, the location of which varies:

• on Windows, it’s %APPDATA%\Claude\claude_desktop_config.json
• on macOS, it’s ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop natively supports only the stdio transport for local MCP servers, but the server speaks streamable HTTP. To bridge that gap, we use mcp-remote — a small npm utility that runs as a local stdio process and forwards every MCP message to a remote HTTP endpoint. Simply put, Claude Desktop talks to mcp-remote over standard input-output, and mcp-remote relays the traffic to the Spring AI server at http://localhost:3001/mcp:

"mcpServers": {
  "sport-spinner": {
    "command": "npx",
    "args": [
      "mcp-remote",
      "http://localhost:3001/mcp",
      "--transport",
      "http-only",
      "--allow-http"
    ]
  }
}

As we can see, we also need to assign a name to the MCP application. Let’s call it sport-spinner, since we extend it to recommend a sport for the user to practice on any given day.

Finally, if we restart Claude Desktop, we should be able to see the MCP server as a custom connector:

Therefore, the model can now decide to invoke the tools exposed by the MCP server:

Looks like we managed to connect to the MCP application and return a String that AI Harness can use or display to the user. Now, let’s upgrade the application to return HTML that can be rendered in Claude Desktop.

4. Embedding HTML

So far, the MCP server only returns plain text. However, modern AI harnesses such as Claude Desktop can also render rich, interactive UIs that the server exposes as HTML resources. We can achieve this by combining an @McpTool that triggers the UI with an @McpResource that serves the actual HTML.

Let’s enhance the sport-spinner to display a real fortune wheel that picks today’s sport. First, we add an HTML file under src/main/resources/static/sport-spinner.html, containing the HTML, CSS, and JavaScript that animates the wheel.

4.1. Exposing the HTML as an MCP Resource

Let’s create a new Spring bean that loads the HTML file and exposes it via the @McpResource annotation:

@Component
class SportSpinnerUI {
    @Value("classpath:/static/sport-spinner.html")
    private Resource sportSpinnerResource;
    @McpResource(
        name = "Sport Spinner App Resource",
        uri = "ui://sport/sport-spinner.html",
        mimeType = "text/html;profile=mcp-app",
        metaProvider = CspMetaProvider.class)
    public String getSportSpinnerResource() throws IOException {
        return sportSpinnerResource.getContentAsString(Charset.defaultCharset());
    }
}

A few things worth highlighting here:

• the uri uniquely identifies the resource within the MCP server
• the mimeType uses the text/html;profile=mcp-app profile – signaling to the client that this HTML should be rendered as an interactive MCP app rather than displayed as raw text
• the metaProvider attaches additional metadata to the resource — in this case, a Content Security Policy that allow-lists unpkg.com so the page can load external scripts from that CDN

Let’s have a look at the CspMetaProvider:

class CspMetaProvider implements MetaProvider {
    @Override
    public Map<String, Object> getMeta() {
        return Map.of("ui",
            Map.of("csp",
                Map.of("resourceDomains", List.of("https://unpkg.com"))));
    }
}

At this point, we should be ready to connect the UI to the tool.

4.2. Linking the Tool to the UI Resource

Finally, let’s add an MCP tool that instructs the harness to open the wheel:

@McpTool(
    title = "Spin Sport Wheel",
    name = "spin-sport-wheel",
    description = "Opens a fortune wheel that spins and randomly picks today's sport.",
    metaProvider = SportSpinnerToolMetaProvider.class)
public String spinSportWheel() {
    return "Opening the sport spinner wheel.";
}

The key element here is metaProvider, which links this tool to the HTML resource we defined earlier:

class SportSpinnerToolMetaProvider implements MetaProvider {
    @Override
    public Map<String, Object> getMeta() {
        return Map.of("ui",
            Map.of("resourceUri", "ui://sport/sport-spinner.html"));
    }
}

When the model invokes spin-sport-wheel, the harness reads this metadata, fetches the resource at ui://sport/sport-spinner.html, and renders it inline in the chat, giving the user a fully interactive wheel instead of a plain text reply.

Let’s restart Claude Desktop and ask it what sport we should practice today:

As expected, the HTML from the Spring Boot application is now rendered directly inside the Claude Desktop chat. At this point, we can spin the wheel to let it pick today’s sport, with the result fed back into the conversation so the model can react to it.

5. Conclusion

In this tutorial, we learned how to build an MCP server with Spring AI and connect it to an AI harness such as Claude Desktop.

Specifically, we started with a simple hello-world tool and tested it using the MCP Inspector and Claude Desktop. Then, we took it one step further by exposing a rich, interactive HTML UI through Spring AI’s @McpTool and @McpResource annotations. As a result, we made the harness render a fortune wheel inline in the chat and feed the result back into the conversation.

As always, the full source code is available over on GitHub.

       

1. Spring and Java

>> On Default Values for Primitive-Like Classes [openjdk.org]

One of the thorniest problems standing between us and value classes: what happens when a value object never gets explicitly initialized? A deep exploration of how primitive-like classes might nominate their own default values, and what that means across the language, the JVM, and the runtime. Good stuff for the weekend.

>> The VibeSec Reckoning [martinfowler.com]

As AI-assisted coding moves into the mainstream, prompting an LLM toward “secure” output isn’t, of course, enough. Security has to be structural and enforced mechanically in the harness.

Also worth reading:

• >> Java AOT in Production at Netflix [inside.java]
• >> A New Generation of Java Libraries Is Born: Wasm Becomes the Implementation Detail [foojay.io]
• >> JEP targeted to JDK 27: 523: Make G1 the Default Garbage Collector in All Environments [inside.java]
• >> JEP targeted to JDK 27: 537: Vector API (12th Incubator) [inside.java]
• >> Agentic AI Workflows for OpenJDK Development [inside.java]
• >> Parallel voting and adaptive model selection: smarter agentic AI on a budget [quarkus.io]
• >> Context Is a Budget – Eight levers and three workflow patterns [foojay.io]
• >> TamboUI Promises to Bring Better Capabilities to Build TUIs in Java [infoq.com]
• >> The Schema Proliferation Problem in Kafka and Flink Pipelines: How to Solve It [infoq.com]
• >> Introducing a Security Support Policy for the Kotlin Standard Library [jetbrains.com]
• >> Spring Developers Have a Blindspot When It Comes to Container Security [bell-sw.com]
• >> NixOS first impressions: writing system-level tests [advancedweb.hu]
• >> Seasons time-lapse – alignment [frankel.ch]

Webinars and presentations:

• >> Foojay Podcast #96: Local AWS Development Without LocalStack: Meet Floci, the GraalVM-Powered Alternative [foojay.io]
• >> Podcast: Chasing Efficient Java Development: From 1BRC to Developing Hardwood AI Natively [infoq.com]
• >> A Bootiful Podcast: Hadi Hariri, Jetbrains legend [spring.io]

Time to upgrade:

• >> Hibernate 7.4.0.Final [in.relation.to]
• >> Hibernate Search 8.4.0.Final is out [in.relation.to]
• >> WildFly 40 is released! [wildfly.org]
• >> Spring AI 1.0.8, 1.1.7, 2.0.0-M7 Available Now [spring.io]
• >> Koog 1.0 Is Out: Stable Core, Better Interop, and Multiplatform Observability [jetbrains.com]
• >> IntelliJ IDEA 2026.2 EAP Is Open [jetbrains.com]
• >> Vert.x 5.1.0 [github.com/eclipse-vertx]

2. Pick of the Week

>> How to break a Monolith into Microservices [martinfowler.com]

       

1. Overview

Since MySQL is one of the most common database management systems, we might need a way to establish a stable connection between MySQL and a Java application. Usually, this happens via the MySQL Connector/J JDBC driver. However, a common problem is the Communications link failure error, typically thrown as CommunicationsException. Although the error message may appear simple, the underlying causes can vary significantly.

In this tutorial, we explain how to fix the Communications link failure error in Java applications using MySQL. First, we explore what the exception means and when it appears. After that, we go over configuration issues, networking problems, MySQL settings, and other potential causes. Finally, we discuss different ways to diagnose the problem and work around or fix it.

Notably, we mainly refer to MySQL Connector/J 8.x used with MySQL Server 5.7 and 8.x. Since there are some differences between older Connector/J 5.1.x versions and newer 8.x releases, we’ll mention them explicitly throughout the text when necessary.

2. Understanding the Error

Before attempting to fix the issue, let’s understand how and when the error appears.

2.1. CommunicationsException

Usually, the error happens in Java applications, causing a JDBC CommunicationsEsception:

com.mysql.jdbc.exceptions.jdbc4.CommunicationsException:
Communications link failure
The last packet sent successfully to the server was 0 milliseconds ago.
The driver has not received any packets from the server.

Basically, the JDBC driver attempts to exchange data with the MySQL server, but no data goes through.

When it comes to Connector/J 5.1.x, the exception commonly appears under the com.mysql.jdbc.exceptions.jdbc4.CommunicationsException package. However, Connector/J 8.x changed the package to com.mysql.cj.jdbc.exceptions.CommunicationsException. Such changes aren’t unexpected, and future versions may continue the trend.

In practice, we often encounter this error in two scenarios:

• during the initial connection attempt
• when executing queries on an already established connection

Considering this, let’s inspect common causes.

2.2. Common Causes

Although the error itself is generic, several underlying issues appear frequently in production systems:

• Our MySQL server isn’t running
• JDBC connection URL contains incorrect hostname or port
• DNS resolution fails for the configured host
• MySQL isn’t listening for TCP/IP connections
• firewall or proxy rules block database traffic
• server closing idle connections
• application exhausts available database connections
• JDBC driver version incompatible with the server

Since multiple factors can lead to the same exception, diagnosing the problem may require multiple steps.

3. Verifying Basic Connectivity

To begin with, let’s confirm that the application can reach the database server.

3.1. Verify MySQL Server Is Running

Perhaps the most straightforward cause for the error is a non-running MySQL server instance. Naturally, if the service isn’t up, the JDBC driver can’t reach it.

Here, a simple restart can resolve the issue:

# sudo service mysql restart

After the server restarts, the application should be able to reconnect normally. Still, the problem can also occur due to intermittent restarts, in which case further debugging might be required.

3.2. Check JDBC Connection URL

The key parameters of the initial MySQL connection can cause communication failures.

Let’s analyze a typical MySQL JDBC connection string:

jdbc:mysql://localhost:3306/mydatabase

When troubleshooting, we should verify the correctness of at least several parameters:

• hostname or IP address
• port number (default: 3306)
• database name
• username and password

Specifically, an incorrect port or hostname can prevent the application from connecting to the server entirely.

3.3. Test Hostname Resolution

As with any networking issue, the difference between a hostname and a host address is critical. Failure at name resolution is enough to block a connection. There are typically several possible reasons for this:

• bad operating system configuration
• incorrect hosts file entries
• misconfigured DNS server
• DNS server unaware of host
• DNS server not responding

Any of these factors can prevent the JDBC driver from reaching the server. To troubleshoot, we can try replacing a name like localhost or MYSQL-1 with the explicit IP address, such as 127.0.0.1 or 192.168.6.66.

If the connection works with an explicit IP address but not a hostname, DNS or hostname resolution issues are probably the culprit. In contrast, if the connection still fails even with the direct IP address, the root cause is more likely related to networking, firewall rules, incorrect ports, or the MySQL server configuration. Let’s look at each of these possibilities.

4. MySQL Configuration Issues

If we can reach the actual hardware that hosts the server, but still experience issues, then MySQL might not be configured to accept network connections as expected. To diagnose this, we often check the options and values in the MySQL configuration file (my.cnf or my.ini).

4.1. Verify the bind-address Setting

One common MySQL option is bind-address.

Specifically, the value of bind-address determines the network interfaces that the server listens on:

bind-address = 127.0.0.1

In this case, we only expect connections from within localhost.

On the other hand, we can accept connections to any address or interface:

bind-address = 0.0.0.0

Checking whether bind-address is properly set with the expected value is critical for diagnosing connectivity issues.

4.2. Disable skip-networking

Some MySQL installations support the skip-networking configuration option, which disables TCP/IP connections entirely.

Thus, if the setting appears in the configuration file, we should comment it out:

# skip-networking

Although this is a rare cause, checking for such edge cases takes little time and can fix the issue. So, it’s worth exploring.

4.3. Adjust Connection Timeout Settings

To prevent resource waste, MySQL may close connections that remain idle for too long.

Several parameters control this behavior:

• wait_timeout: maximum time to wait before closing an idle non-interactive connection
• interactive_timeout: maximum time to wait before closing an idle interactive connection (such as mysql CLI)
• connect_timeout: maximum time to wait for a client to complete the initial connection handshake

As expected, increasing these values can reduce unexpected connection failures:

wait_timeout = 28800
interactive_timeout = 28800

In all cases, after changing the configuration, we should restart the MySQL service.

5. Network and Environment Issues

Even when MySQL is configured correctly, external factors may still prevent the application from connecting.

5.1. Firewall and Antivirus or Proxy Restrictions

Network controls can block the traffic between the application and the MySQL server. For instance, a firewall rule, antivirus software, or a proxy can be the reason for connectivity issues.

To ensure the connection goes through, we can use tools such as ping or telnet for simple checks and nmap for port testing.

Regardless of the network setup, we should ensure that port 3306 is open and accessible through the whole chain. Naturally, if MySQL is configured to listen on another port, we should verify connectivity against that specific port instead of 3306.

5.2. IPv6 Versus IPv4 Issues

Some environments resolve names to IPv6 addresses, such as ::1 for localhost instead of its IPv4 equivalent 127.0.0.1. However, if the Java application environment and the MySQL server don’t use the same IP version, we can experience connection failures.

Common solutions:

1. use 127.0.0.1 instead of localhost
2. start Java with the JVM option -Djava.net.preferIPv4Stack=true

This forces the application to prefer IPv4 networking.

6. Application-Level Causes

The way that an application is implemented also affects the establishment and stability of connections.

6.1. Stale Connections in Connection Pools

Connection pools with stale entries are a common culprit for problematic MySQL connectivity. When the application tries to execute a query over a connection that the server has already closed, the JDBC driver reports a communication failure.

Usually, the solution is to switch over to a modern connection pool:

• HikariCP
• Apache DBCP
• C3P0

The reason is that these implementations validate connections before returning them to the application.

In practice, connection pools may require explicit configuration to validate or recycle stale connections. For example, HikariCP uses several settings:

• maxLifetime
• idleTimeout
• keepaliveTime

Apache DBCP and C3P0 support validation queries and connection test options. The exact specifics are outside the scope of this text.

6.2. Connection Pool Exhaustion

Connection limits may necessitate closing old connections before attempting new ones. Otherwise, the MySQL server may reject the connection attempt.

In particular, ensuring the JDBC resources are closed correctly is essential:

try (Connection conn = dataSource.getConnection()) {
    // execute queries
}

Connection pools can also limit and recycle connections.

Even if the application closes all JDBC resources, the database server may still reject new connections. For example, MySQL may reach the max_connections limit or experience temporary overload conditions. In such cases, the application could receive different exceptions, including errors such as Too many connections, instead of a generic CommunicationsException.

Furthermore, the configured pool size matters significantly. If the connection pool allows more concurrent connections than MySQL accepts, server connections can be depleted. Therefore, there should be a proper balance between the pool connection size and max_connections in MySQL.

6.3. Update the JDBC Driver

Older versions of the MySQL Connector/J driver may not work reliably with newer database versions.

Updating the dependency often resolves compatibility problems:

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.33</version>
</dependency>

For Connector/J 8.x, the Maven artifact may also appear under the newer coordinates com.mysql:mysql-connector-j, depending on the project setup and repository metadata.

As with other areas of computing, keeping the driver up to date ensures compatibility with the MySQL protocol and improves connection stability.

7. Summary

In this article, we explored how to diagnose and fix the Communications link failure error in Java applications using MySQL.

This error occurs when the JDBC driver is unable to communicate with the database server. Common causes include server downtime, incorrect connection configuration, MySQL network settings, firewall restrictions, IPv6 resolution problems, stale pooled connections, and connection exhaustion within the application.

Carefully verifying connectivity, reviewing MySQL configuration, using reliable connection pools, updating JDBC drivers, and examining diagnostic logs can significantly reduce communication failures in Java applications that rely on MySQL.

       

1. Overview

ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism) is a post-quantum cryptographic key exchange algorithm that allows two parties to securely establish a shared secret key even against attacks from future quantum computers. ML-DSA (Module-Lattice-Based Digital Signature Algorithm), on the other hand, is a post-quantum digital signature algorithm that enables secure authentication and message integrity protection, resistant to attacks by quantum computers.

ML-KEM  and ML-DSA  weren’t part of the standard JDK (Java Development Kit) before Java 24. We had to use external libraries like Bounty Castle to perform cryptographic operations.

Both algorithms have been part of the native Java API since Java 24. The ML-KEM and ML-DSA implementations within the native Java API were proposed by JEP 496 and JEP 497, respectively.

In this tutorial, we’ll discuss the usage of quantum-resistant ML-KEM and ML-DSA in Java.

2. Quantum-Resistant ML-KEM

A key encapsulation mechanism allows two parties, i.e., a sender and a receiver, to securely exchange a shared secret key over an insecure network. The mechanism consists of the following steps:

• The receiver creates a public/private key pair
• The sender creates an encrypted shared secret key using the public key
• The receiver decrypts the encrypted shared secret key using the private key

Consequently, both parties obtain the same secret key. This shared key can be used with symmetric-key algorithms such as AES (Advanced Encryption Standard) and Blowfish.

ML-KEM is based on the M-LWE (Module Learning with Errors) problem, which is computationally hard. The hardness of the M-LWE problem further depends on the hardness of certain computational problems in module lattices. Therefore, ML-KEM is resistant to both classical and quantum attacks.

2.1. Generating a Key Pair

Let’s start by generating an ML-KEM key pair at the receiver side:

KeyPairGenerator kpg = KeyPairGenerator.getInstance("ML-KEM");
kpg.initialize(NamedParameterSpec.ML_KEM_768);
KeyPair receiverKeyPair = kpg.generateKeyPair();
PrivateKey privateKey = receiverKeyPair.getPrivate();
PublicKey publicKey = receiverKeyPair.getPublic();

Firstly, we get a KeyPairGenerator object for the ML-KEM algorithm. Then, we choose ML_KEM_768 to set the security strength of the keys we’ll generate. JEP 496 adds support for ML-KEM-512, ML-KEM-768, and ML-KEM-1024. Indeed, ML_KEM_768 is the default option, i.e., if we don’t initialize the KeyPairGenerator object with the initialize() method, the security level will still be ML_KEM_768.

It’s also possible to pass the security strength directly to getInstance(). We don’t have to call the initialize() method in this case, either:

KeyPairGenerator kpg = KeyPairGenerator.getInstance("ML-KEM-768");
KeyPair receiverKeyPair = kpg.generateKeyPair();

receiverKeyPair, of type KeyPair, holds a public and private key. We can access these keys using the getPublic() and getPrivate() member methods, respectively. It’s safe for the receiver to share the public key with the sender, but the private key must be kept secret.

2.2. Generating and Encapsulating a Secret Shared Key

Once the sender receives the receiver’s public key, it generates and encapsulates a shared secret key that will be used by both the sender and the receiver:

KEM senderKem = KEM.getInstance("ML-KEM");
KEM.Encapsulator encapsulator = senderKem.newEncapsulator(publicKey);
KEM.Encapsulated encapsulated = encapsulator.encapsulate();
SecretKey senderSharedSecret = encapsulated.key();
byte[] ciphertext = encapsulated.encapsulation();

senderSharedSecret is the actual secret key used in communication. But the sender doesn’t send it directly to the receiver. It sends it encrypted by encapsulating it with the receiver’s public key. ciphertext corresponds to the encrypted version of senderSharedSecret.

2.3. Decapsulating the Secret Shared Key

After the receiver receives the encrypted secret key, it decapsulates the secret key using the private key:

KEM receiverKem = KEM.getInstance("ML-KEM");
KEM.Decapsulator decapsulator = receiverKem.newDecapsulator(privateKey);
SecretKey receiverSharedSecret = decapsulator.decapsulate(ciphertext);

The actual secret key, receiverSharedSecret, is extracted by decapsulating the received ciphertext. Consequently, both sides obtain the same shared secret key for symmetric encryption and decryption. We can check that both parties use the same key as follows:

boolean match = Arrays.equals(senderSharedSecret.getEncoded(), receiverSharedSecret.getEncoded());

The comparison returns true. Therefore, we achieve secure communication over insecure networks. Besides, the method is resistant to quantum attacks, unlike RSA or Diffie-Hellman.

3. Quantum-Resistant ML-DSA

A digital signature algorithm is a cryptographic method that verifies the authenticity and integrity of digital messages or documents. The algorithm consists of the following steps:

• The signer (sender) creates a public/private key pair
• The signer creates a signature using the message and the private key
• The verifier (receiver) verifies the signature using the received message and the public key

Like ML-KEM, ML-DSA is based on the M-LWE problem and on another computationally hard problem, M-SIS (Module Short Integer Solution). Therefore, ML-DSA is resistant to both classical and quantum attacks.

3.1. Generating a Key Pair

Let’s start by generating an ML-DSA key pair on the signer side:

KeyPairGenerator kpg = KeyPairGenerator.getInstance("ML-DSA");
kpg.initialize(NamedParameterSpec.ML_DSA_65);
KeyPair kp = kpg.generateKeyPair();
PrivateKey privateKey = kp.getPrivate();
PublicKey publicKey = kp.getPublic();

Firstly, we get a KeyPairGenerator object for the ML-DSA algorithm. Then, we choose ML_DSA_65 to set the security strength of the keys we’ll generate. Indeed, ML_DSA_65 is the default option. JEP 497 adds support for ML-DSA-44, ML-DSA-65, and ML-DSA-87.

Like ML-KEM, it’s possible to pass the security strength directly to getInstance().

3.2. Signing

Then, we, the signer, sign the message to be sent using the private key:

Signature signature = Signature.getInstance("ML-DSA");
String message = "This is a test message signed";
byte[] messageBytes = message.getBytes();
signature.initSign(privateKey);
signature.update(messageBytes);
byte[] sigBytes = signature.sign();

Firstly, we get a Signature object that implements the ML-DSA algorithm. Then, we initialize this object for signing using the initSign() method. We pass the private key to this method. Then, we feed the message to the Signature object using the update() method. Finally, we create the digital signature using the Signature object’s sign() method.

3.3. Verification

Then, having received the message and the signature, we, the verifier, verify the signature using the public key:

signature.initVerify(publicKey);
signature.update(messageBytes);
boolean isValid = signature.verify(sigBytes);

This time, we initialize the Signature object for verification using the initVerify() method. Then we feed the message received from the signer to the Signature object using update(). Finally, we verify the signature using the Signature object’s verify() method. It returns true. Successful validation means that the signature was created using the corresponding private key.

4. Conclusion

In this article, we discussed the usage of quantum-resistant ML-KEM and ML-DSA in Java. Firstly, we learned that these algorithms weren’t available in the standard JDK before Java 24.

Then, we saw the usage of the algorithms in Java. We simulated the secret key exchange between a receiver and a sender using ML-KEM. Similarly, we simulated message signing and signature verification between two parties using ML-DSA. As we saw in the examples, Java 24 provided ML-KEM implementations of the KeyPairGenerator and KEM classes, and ML-DSA implementations of the KeyPairGenerator and Signature classes.

As usual, the complete source code for the examples is available over on GitHub.

       

1. Introduction

Basic Authentication is the most common security mechanism for HTTP services. Its popularity stems from simplicity and ease of implementation. In this tutorial, we’ll explore how HTTP Basic Authentication works and how to extract credentials, specifically the password, from an incoming HTTP request in a Spring-based application.

2. HTTP Basic Authentication

HTTP Basic Authentication is a simple authentication scheme where the client sends credentials in the HTTP request header. The client sends the request with the credentials included in the Authorization header, and the server then validates them. The header format is:

Authorization: Basic <base64(username:password)>

The username and password are combined into a single string separated by a colon. This string is then encoded using Base64. For example, if the username is admin and the password is secret, the combined string is admin:secret. The Base64 encoded version of this string is YWRtaW46c2VjcmV0. The final HTTP header looks like this:

Authorization: Basic YWRtaW46c2VjcmV0

It’s important to note that Base64 is encoding, not encryption. It is easily reversible, which is why HTTPS is strictly required when using Basic Authentication.

3. Maven Dependency

Let’s start by importing the spring-boot-starter-web dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

4. Retrieving Credentials from the Authorization Header

In this section, we describe the step-by-step process of retrieving the raw username and password from the incoming HTTP request.

4.1. Manual Extraction from the HTTP Request

The most direct way to get the password is to read the Authorization header directly from the HttpServletRequest and decode it. Let’s create a BasicAuthExtractor class and a utility method to do this:

public class BasicAuthExtractor {
    public static String[] extractCredentials(String authHeader) {
        if (authHeader != null && authHeader.startsWith("Basic ")) {
            String base64Credentials = authHeader.substring("Basic ".length()).trim();
            byte[] credDecoded = Base64.getDecoder().decode(base64Credentials);
            String credentials = new String(credDecoded, StandardCharsets.UTF_8);
            final String[] values = credentials.split(":", 2);
            if (values.length == 2) {
                return values;
            }
        }
        return null;
    }
}

The extractCredentials() method first checks whether the Authorization header exists. It also verifies that the header starts with the “Basic ” prefix. Next, it removes the prefix from the header value. Then, it decodes the remaining Base64-encoded string using Base64.getDecoder(). After decoding, the bytes are converted into a UTF-8 string. The resulting string should follow the username:password format. Finally, the method splits the string on the first colon. It returns a two-element array containing the username and password. If the header is invalid or incorrectly formatted, the method returns null. We can easily use the extractCredentials() method inside a RestController:

@GetMapping("/extract")
public ResponseEntity<String> extract(@RequestHeader("Authorization") String authHeader) {
    String[] credentials = BasicAuthExtractor.extractCredentials(authHeader);
    if (credentials != null) {
        String username = credentials[0];
        String password = credentials[1];
        return ResponseEntity.ok("Extracted Username: " + username +
          " Extracted Password: " + password);
    }
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}

We use the @RequestHeader annotation for getting the Authorization header value from the incoming request.

4.2. Custom Servlet Filter

Another way is to create a custom Filter that reads the header, extracts the password, and stores it in a request attribute for later use. Let’s create an AuthFilter class to do this:

@Component
public class AuthFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
        FilterChain filterChain) throws ServletException, IOException {
        String authHeader = request.getHeader("Authorization");
        String[] credentials = BasicAuthExtractor.extractCredentials(authHeader);
        if (credentials != null) {
            request.setAttribute("rawPassword", credentials[1]);
        }
        filterChain.doFilter(request, response);
    }
}

This filter intercepts every incoming HTTP request and reads the Authorization header. Then, it extracts the password using the extractCredentials() method and stores it as a request attribute before continuing the filter chain. Later, in our service or controller, we can retrieve it safely:

String rawPassword = (String) request.getAttribute("rawPassword");

5. Testing the BasicAuthExtractor

Let’s start by testing the core extraction logic. First, we need to ensure it correctly handles a valid Basic Authentication header and returns the expected credentials array:

@Test
void givenValidHeader_whenExtract_thenReturnCredentialsArray() {
    // Given
    String header = encodeCredentials("admin", "secret");
    // When
    String[] credentials = BasicAuthExtractor.extractCredentials(header);
    // Then
    assertThat(credentials).isNotNull();
    assertThat(credentials).hasSize(2);
    assertThat(credentials[0]).isEqualTo("admin");
    assertThat(credentials[1]).isEqualTo("secret");
}

To keep our tests clean and readable, we utilize a helper method that handles the Base64 encoding and header formatting for us:

private String encodeCredentials(String username, String password) {
    String credentials = username + ":" + password;
    return "Basic " + Base64.getEncoder().encodeToString(credentials.getBytes());
}

Additionally, we need to verify that the method safely returns null for invalid headers, such as those missing the Basic prefix or using a different authentication scheme:

@Test
void givenMissingBasicPrefix_whenExtract_thenReturnNull() {
    // Given
    String header = "Bearer some-token";
    // When
    String[] credentials = BasicAuthExtractor.extractCredentials(header);
    // Then
    assertThat(credentials).isNull();
}

6. Conclusion

In this article, we learned how HTTP Basic Authentication encodes credentials and how to decode them manually using Java’s Base64 utility. We also explored how to capture the raw password using a custom filter. While extracting passwords is sometimes necessary for legacy integrations, it should be avoided whenever possible due to the inherent security risks. As always, the source code is available over on GitHub.

       

1. Spring and Java

>> Java 26: Better Language, Better APIs, Better Runtime [inside.java]

Nicolai walks through the Java platform’s recent evolution, from JDK 21 through 25 and into JDK 26. Good way to catch up.

Also worth reading:

• >> Caching for Agentic Java Systems: Internal, Distributed, and Semantic [inside.java]
• >> Don’t Panic: The Thymeleaf Template Injection That Only Hurts If You Let It (CVE-2026-40478) [foojay.io]
• >> From Zero (Really Zero) to OpenTelemetry [foojay.io]
• >> Built for Productivity: What the Data Finally Shows About Kotlin [jetbrains.com]
• >> All Azul Zulu Container Images Explained: CA, SA, and Chainguard [foojay.io]
• >> BoxLang AI Series: Complete Guide to Building AI Agents [foojay.io]
• >> Quality Outreach Heads-up – JDK 27: Numeric Fields in JSON Thread Dumps [inside.java]
• >> JEP targeted to JDK 27: 531: Lazy Constants (3rd Preview) [inside.java]
• >> Quality Outreach Heads-up – JDK 27: Post-Quantum Hybrid Key Exchange for TLS 1.3 [inside.java]
• >> Post-Mortem JVM Crash Analysis with jcmd [inside.java]
• >> Quality Outreach Heads-up – JDK 26: Warnings About Final Field Mutation [inside.java]
• >> Getting Started With MockK: The Setup [petrikainulainen.net]

Webinars and presentations:

• >> Spring Office Hours Podcast: S5E16 – May Release Train Shift & What’s Coming in Spring Boot 4.1 [spring.io]

Time to upgrade:

• >> GlassFish 8.0.2 Released: With important security fixes, other improvements, and commercial support [foojay.io]
• >> BoxLang v1.13.0: Compatibility, Concurrency, and Formatter Maturity [foojay.io]
• >> IntelliJ IDEA 2026.1.2 Is Out! [jetbrains.com]
• >> Compose Multiplatform 1.11.0 Is Now Available [jetbrains.com]
• >> Quarkus 3.36.0, Quarkus 3.35.4, Quarkus 3.33.2, and Quarkus 3.27.4 [github.com/quarkusio]
• >> Zuul v3.6.8, Zuul v3.6.7, Zuul v3.6.6, and Zuul v3.6.5 [github.com/Netflix]

2. Technical & Musings

>> Maintainability sensors for coding agents [martinfowler.com]

A practical look at keeping AI-assisted codebases maintainable, using “sensors” such as linting, dependency rules, coupling data, and modularity reviews to give coding agents fast feedback. Good stuff.

Also worth reading:

• >> The Human Bottleneck [scottlogic.com]
• >> The Evolution of Cassandra Data Movement at Netflix [netflixtechblog.com]
• >> Seasons time-lapse – the foundations [frankel.ch]
• >> Interrogatory LLM [martinfowler.com]
• >> Finding Your Voice: A Guide to Technical Communication [scottlogic.com]
• >> Alternative Coding Agents: Pi [scottlogic.com]

3. Pick of the Week

>> The Backwards Law—Why the Best Things in Life Must Be Let Go [markmanson.net]

       

1. Spring and Java

>> Scaling ArchUnit with Nebula ArchRules [netflixtechblog.com]

Netflix shares how its JVM Ecosystem team scales architecture rules across thousands of Java repositories with Nebula ArchRules and ArchUnit. A strong practical read on build-time feedback, technical debt visibility, and turning architecture guidance into enforceable, fleet-wide checks.

Also worth reading:

• >> Native Interoperability with JDK 25 and the FFM API [inside.java]
• >> Tokensparsamkeit for coding assistants [frankel.ch]
• >> Java is Not the Dark Side: Why Learning Java is Easier Than You Think [foojay.io]
• >> Liquid Glass, Material 3, And A Lot Of Plumbing [foojay.io]
• >> Using the Azul Zulu Docker Official Images: From Simple Pull to Lean Container [foojay.io]
• >> BoxLang AI Deep Dive – Part 7 of 7: MCP – The Protocol That Connects Everything [foojay.io]
• >> JEP 533 Tightens Exception Handling in Java’s Structured Concurrency for JDK 27 [infoq.com]
• >> Quality Outreach Heads-up – JDK 27: Removal of Deprecated Java Launcher Options [inside.java]
• >> JEP targeted to JDK 27: 533: Structured Concurrency (7th Preview) [inside.java]
• >> JEP targeted to JDK 27: 532: Primitive Types in Patterns, instanceof, and switch (5th Preview) [inside.java]
• >> Release of the new Java Card Development Kit version 26.0 [oracle.com]
• >> How Preview Features Support Java Card Evolution [oracle.com]
• >> Next-Gen Management Console for WildFly [wildfly.org]
• >> Simplifying ANTI JOIN with jOOQ Syntax [jooq.org]
• >> Designing safer listItems and getItem permissions [advancedweb.hu]

Webinars and presentations:

• >> Foojay Podcast #95: Is Your Java App Actually Secure, Or Does It Just Look That Way? [foojay.io]
• >> Podcast: From Java EE to Quarkus and LLMs: Adam Bien’s Playbook for Boring, Future-Proof Systems [infoq.com]
• >> Java Gets Post-Quantum TLS – Inside Java Newscast #112 [inside.java]
• >> A Bootiful Podcast: the legendary Adib Saikali [spring.io]
• >> A Bootiful Podcast: Daniel Garnier-Moiroux on his new book ‘Testing Spring Boot Applications’ [spring.io]
• >> Spring Office Hours Podcast: S5E15 – Upgrading Spring and OSS Security [spring.io]

Time to upgrade:

• >> THE 12 LABOURS OF PRIMEFACES 15.0.15 #release [foojay.io]
• >> Hibernate Search 8.4.0.CR1 is out [in.relation.to]
• >> Spring AI 1.0.7, 1.1.6, 2.0.0-M6 available now [spring.io]
• >> Quarkus 3.35.3 – Maintenance release [quarkus.io]
• >> Maven 3.9.16 [github.com/apache]
• >> Elasticsearch 9.4.1 [github.com/elastic]
• >> Zuul 3.6.4 [github.com/Netflix]
• >> Micronaut Core 5.0.0 [github.com/micronaut-projects]
• >> Payara Platform Community 7.2026.5 [github.com/payara]

2. Technical & Musings

>> What is Code [martinfowler.com]

A thoughtful piece for anyone thinking about what software development means as AI changes how code is written and maintained. A weekend read.

Also worth reading:

• >> Pushing Local Models With Focus And Polish [lucumr.pocoo.org]
• >> Data Projects: Managing Data Assets at Netflix Scale [netflixtechblog.com]
• >> Web Feeds in 2026: A Survey [mnot.net]
• >> Data Engineering on a Budget [scottlogic.com]
• >> Don’t overestimate domain knowledge [event-driven.io]

3. Pick of the Week

>> 5 Years and $5M Later: Inventing a New Programming Language for Web Development Was a Mistake [wasp.sh]

       

1. Introduction

The purpose of web automation in Java is simple. In essence, the idea is to open a browser and interact with a web page. However, an immediate challenge appears from the browser itself, namely, the binary compatibility. To elaborate, each browser requires a corresponding driver binary, and that binary must match the installed browser version. Even a small mismatch leads to runtime errors. WebDriverManager in Java addresses this issue by automating driver management in Java-based Selenium projects.

In this tutorial, we’ll introduce WebDriverManager. First, we’ll explore the purpose and need for this driver. Subsequently, we’ll look at how to include WebDriverManager in the code. Lastly, we’ll discuss integrating WebDriverManager with different libraries.

2. What Is WebDriverManager?

WebDriverManager is a Java library that automatically resolves, downloads, and configures browser drivers required by Selenium. Instead of manually managing binaries and system properties, the library handles these steps programmatically. It determines which browser version is installed, finds the correct driver version, downloads it if necessary, and configures the system so Selenium can use it.

Notably, Selenium includes a built-in tool called Selenium Manager, which also automates driver management. Selenium Manager removes the need to manually download browser drivers. However, WebDriverManager is an enhanced alternative with additional features, such as driver caching control, support for Dockerized browsers, and flexibility in complex environments.

A traditional Selenium setup requires explicitly specifying the driver path in the code. For instance, for a Chrome browser, we set the driver using setProperty:

System.setProperty("webdriver.chrome.driver", "/path/to/chromedriver");
WebDriver driver = new ChromeDriver();

This approach works initially but doesn’t scale well. Every time the browser updates, the corresponding driver should also be updated manually. In shared environments such as CI/CD pipelines or team projects, maintaining consistent driver versions becomes difficult. Moreover, hardcoded paths make the code less portable across systems.

In addition, WebDriverManager removes this burden by handling driver resolution dynamically. It also caches downloaded drivers locally, so repeated executions don’t trigger unnecessary downloads. As a result, test execution becomes both faster and more reliable.

To use WebDriverManager, we should include it as a dependency in the XML file.

For Maven, we use the <dependency> tag:

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>webdrivermanager</artifactId>
    <version>6.3.3</version>
    <scope>test</scope>
</dependency>

For Gradle, we use dependencies:

dependencies {
    testImplementation("io.github.bonigarcia:webdrivermanager:6.3.3")
}

This ensures the library is available during test execution without affecting production builds.

3. Using WebDriverManager

In this example, we look at a basic way to use WebDriverManager for a simple call:

import io.github.bonigarcia.wdm.WebDriverManager;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class SimpleWebDriver {
     public static void main(String[] args) {
          WebDriverManager.chromedriver().setup();
          WebDriver driver = new ChromeDriver();
          driver.get("https://google.com");
          driver.quit();
}
}

In the example above, WebDriverManager.chromedriver() creates a manager instance specifically for Chrome. This instance hides all logic required to handle ChromeDriver binaries.

To explain the code further, calling .setup() triggers the resolution process:

1. 1. Inspect the system to detect the installed Chrome version.
   2. Determine the compatible driver version.
   3. Download the correct driver version if not already cached.
   4. Set the appropriate system property webdriver.chrome.driver.

Because of this, the subsequent line of ChromeDriver() works without any manual configuration.

In addition, driver.get() opens the desired URL, and driver.quit() closes the browser and releases resources.

4. Using WebDriverManager With Different Libraries

In this section, we explore how WebDriverManager integrates with JUnit for structured test execution and how it supports multiple browsers through a consistent interface. Furthermore, we also explore how it extends into more advanced use cases such as generic driver instantiation and browser detection.

4.1. Using WebDriverManager With JUnit

In professional test environments, it’s considered best practice to perform setup operations once per test class rather than repeating them before every individual test. WebDriverManager fits into this pattern when combined with JUnit 5’s @BeforeAll annotation:

import io.github.bonigarcia.wdm.WebDriverManager;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class GoogleTest {
    @BeforeAll
    static void setupClass() {
        WebDriverManager.chromedriver().setup();
    }
    @Test
    void testGoogle() {
        WebDriver driver = new ChromeDriver();
        driver.get("https://www.google.com");
        driver.quit();
    }
}

The @BeforeAll annotation guarantees that the setupClass() method is executed exactly once before any test methods in the class run. By calling WebDriverManager.chromedriver().setup() at this stage, the framework downloads and configures the correct ChromeDriver binary ahead of time, so that later tests don’t need to repeat this process. This avoids redundant driver resolution for each test case. Once the setup is complete, each individual test method can focus on browser interactions, navigating to a URL, and quitting the driver.

4.2. Working With Multiple Browsers

One of the strengths of WebDriverManager is its ability to manage drivers for multiple browsers using the same consistent pattern. Rather than writing separate setup logic for each browser, the library provides dedicated manager methods that follow an identical structure regardless of which browser is being targeted:

// Firefox
WebDriverManager.firefoxdriver().setup();
WebDriver driver = new org.openqa.selenium.firefox.FirefoxDriver();
// Microsoft Edge
WebDriverManager.edgedriver().setup();
WebDriver driver = new org.openqa.selenium.edge.EdgeDriver();

Each method returns a browser-specific manager object that handles the resolution and configuration of the appropriate driver binary for that browser.

4.3. Generic Manager Usage

One of the scenarios for generic manager usage is when we don’t know the type of target browser at compile time.

For example, when the browser type is passed as a runtime parameter, or it is read from a configuration file, we use WebDriverManager to determine the appropriate manager dynamically:

import io.github.bonigarcia.wdm.WebDriverManager;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class GenericExample {
    public static void main(String[] args) {
        WebDriverManager.getInstance(ChromeDriver.class).setup();
        WebDriver driver = new ChromeDriver();
        driver.get("https://example.com");
        driver.quit();
    }
}

In the code above, the getInstance(ChromeDriver.class) call accepts a driver class as its argument and uses it to identify and return the correct manager at runtime. This means the same line of code can resolve the manager for any supported browser simply by swapping out the class reference. In practice, this is useful in parameterized or data-driven test frameworks where the browser type is injected from an external source.

5. Conclusion

In this article, we began with a basic introduction to WebDriverManager. We also discussed how to use this driver for Selenium automation. Lastly, we explored how to use this driver with various libraries.

To conclude, WebDriverManager simplifies Selenium automation by eliminating manual driver management. Instead of handling downloads, version compatibility, and configuration, projects can rely on a single method call to perform all setup tasks. This assists in maintaining a clean code, fewer runtime errors, and improved maintainability.

The source code is available over on GitHub.