1. Overview

Codename One is an open-source, commercially supported platform that lets Java and Kotlin developers build cross-platform applications from a single codebase, while integrating with modern Maven-based workflows.

Its cloud-based build model reduces much of the platform-specific setup required for native development, letting us target iOS, Android, JavaScript, Windows, and macOS from the same project.

In this tutorial, we’ll build a Java 17 app named Daily Routine. It manages daily activities, has language and appearance settings, searches for places through a REST API, and displays map previews.

2. Big Picture

Let’s first look at the workflow, the finished app, and the source code we use as a reference.

2.1. Understanding the Codename One Workflow

Codename One applications are Maven projects. During development, the fastest loop is usually local, i.e., we run the app in the simulator, edit Java or Kotlin code, update CSS, and run tests from the IDE or command line:

This workflow is also automation-friendly: Maven commands, simulator runs, tests, cloud builds, and real-device debugging can be driven from scripts, CI jobs, or AI agents. Java 17 projects generated by the Codename One Initializr include agent-facing guidance for realistic end-to-end app development with AI assistance.

2.2. Preview and Sources

Before setting up the project locally, let’s download the JavaScript port and open it as a local HTML file. This gives us a quick preview of the forms, navigation, activity editor, settings screen, place search, and map preview.

Let’s see an example with Firefox:

The app is intentionally more complete than a minimal example, as it includes several features:

• local JSON persistence
• service classes
• responsive styling
• localization
• REST integration
• diagnostics
• UI tests
• network error handling
• fallback logic

Rather than covering every part of the repository line by line, we use the complete source code as a reference while focusing on the main Codename One patterns.

2.3. Opening the Complete Sources From GitHub

When opening the sources from GitHub, IDE-specific actions may be missing because local IDE metadata usually isn’t committed.

When using IntelliJ IDEA, we can recreate the Codename One run configurations fairly easily:

mvn cn1:configure-intellij

This restores actions such as running the simulator, opening Codename One Settings, and updating Codename One. Other IDEs can still open the project as a Maven project, but may require running the needed Maven goals manually.

3. Setting Up the Project

Now, let’s generate a new project, inspect its structure, and run it locally.

3.1. Creating the Project With Codename One Initializr

In the Codename One Initializr, let’s use a simple configuration:

• Main class: DailyRoutine
• Package: com.baeldung.cn1tutorial
• Localization: Include resource bundles

The other defaults are fine. After clicking Generate Project, a multi-module Maven structure appears:

We write most of the application in the shared common module: UI forms, business logic, CSS, localization files, services, and tests. Platform-specific modules for iOS, Android, Java SE, and JavaScript are present, but we usually touch them only for native integration or platform-specific configuration.

The generated AGENTS.md file and .agent-skills directory are meant to guide AI agents, but they also help explain the project structure and workflow.

3.2. Opening the Project in IntelliJ IDEA

For this tutorial, we use IntelliJ IDEA, although the Maven structure works with other major Java IDEs.

We should open the project root, not only the common module, because the root pom.xml defines the full Maven reactor.

When we first open it, a warning informs us that the Java SDK isn’t configured:

Let’s select OpenJDK 17.

3.3. Running the App in the Simulator

For UI work, we can treat the simulator as a reliable preview of real devices, as long as we compare the same platform family and a reasonably matching skin. There are options to try orientation changes, skins, system font size, light and dark styles, and much more:

The first place to inspect if we notice any odd behavior is theme.css. Additionally, certain changes to the simulator settings require us to close and reopen the simulator, so the app can adapt properly.

4. Creating the App Skeleton

Now that the project runs, let’s replace the generated screen with the structure of Daily Routine.

4.1. The Application Lifecycle

The Initializr starts with a class that extends the Codename One Lifecycle class and overrides runApp(). The DailyRoutine class keeps that entry point, but adds the setup needed by the app.

In Codename One, a Form represents one screen:

public class DailyRoutine extends Lifecycle {
    private AppContext appContext;
    @Override
    public void init(Object context) {
        super.init(context);
        Toolbar.setGlobalToolbar(true);
        // Configure logging, error handling, toolbar behavior, and network defaults
        // Create repositories, services, localization, and shared application context
        // Load saved settings and activities
        // Apply the initial theme, language, and font scale
    }
    @Override
    public void runApp() {
        if (appContext == null) {
            return;
        }
        showHome();
    }
    @Override
    public void start() {
        super.start();
        Form current = CN.getCurrentForm();
        if (current != null) {
            // App-specific refresh logic omitted for brevity
        }
    }
    public void showHome() {
        new HomeForm(appContext).show();
    }
}

The lifecycle is easier to understand visually:

The base Lifecycle class provides the default behavior. We override only the hooks where the app needs extra setup, while calls such as super.init(context) and super.start() keep framework defaults in place.

4.2. Initializing Services and Shared State

Once super.init(context) has applied the lifecycle defaults, our init() method creates the objects that the rest of the app uses. Here, context is provided by Codename One itself; it’s not the AppContext that we create later for the forms.

This approach is a lightweight alternative to a dependency-injection framework: instead of making forms create repositories or know about application setup, we pass them an AppContext with the services, settings, localized text helpers, and navigation methods they need.

First, let’s create the persistence layer and the in-memory store:

ActivityRepository activityRepository = createActivityRepository();
SettingsRepository settingsRepository = createSettingsRepository();
ActivityStore activityStore = new ActivityStore(activityRepository);

ActivityRepository persists the activities, while SettingsRepository stores user preferences. ActivityStore keeps the current list of activities in memory and delegates loading and saving to the repository.

Next, let’s create the services used by the UI:

Resources themeResources = getTheme();
LocalizationService localizationService =
  createLocalizationService(themeResources);
PlaceSearchService placeSearchService = createPlaceSearchService();

getTheme() returns the resources already loaded by the Lifecycle base class. We discuss themes and CSS later; for now, the important point is that we pass theme resources to LocalizationService because the app localization bundles are stored there and then installed into UIManager. PlaceSearchService is the abstraction we later implement with the Geoapify REST API.

Then, let’s load the saved settings and assemble the shared application context:

AppSettings settings = settingsRepository.load();
appContext = createAppContext(
    activityStore,
    settingsRepository,
    localizationService,
    placeSearchService,
    settings
);

AppContext is the object we pass to the forms. It gives them access to shared state, services, localized text, settings, and navigation helpers, without making each form create those dependencies itself.

Finally, let’s apply the saved settings and load the activity list:

applySettings(settings, false);
activityStore.load();

This way, we keep startup code centralized in the lifecycle class, while the forms can focus on UI and user interaction.

4.3. Navigating Between Forms

A layered navigation structure may look more complex than directly creating forms everywhere, but it keeps the app easier to maintain and extend:

AppContext acts as a facade: forms call simple navigation methods, while DailyRoutine creates and shows destination forms. All screens inherit from BaseForm, so toolbar, back commands, and side-menu entries stay consistent.

5. Building Responsive Forms With Layouts and CSS

So, let’s look at the UI model: component trees, layout managers, UIIDs, and CSS.

5.1. Forms, Containers, and Layout Managers

Codename One UIs are easier to understand as component trees. Components live inside containers, and each container uses a layout manager to position its children.

The official Codename One tutorial on positioning components using layout managers gives a deeper explanation. For this app, the relation between the home screen and its component tree is fairly straightforward:

Each form has a title area and a content pane, and it can also expose overlay panes whose transparent background lets content underneath remain visible. The floating action button (FAB) is placed in the layered pane, so it floats above the activity list.

This hierarchy of components and overlapping layers is the basis for pixel-perfect designs in Codename One. Instead of hard-coding positions, we combine containers, layout managers, and CSS styling to adapt to device fragmentation: screen sizes, orientations, densities, safe areas, system font settings, and languages.

5.2. Styling Components With UIIDs and CSS

After defining the component hierarchy, we style components with UIIDs. A UIID is a style identifier assigned to a component, similar to a CSS class name.

The simulator’s Component Inspector helps us inspect the selected component’s class, UIID, layout, coordinates, padding, and margin. To open it, we right-click a component in the simulator and choose Inspect Component:

Here, the selected activity card has UIID ActivityCard and layout LayeredLayout. In Java, we assign the UIID to the card container:

Container card = new Container(new LayeredLayout());
card.setUIID("ActivityCard");

Then, CSS defines its visual appearance:

ActivityCard {
    background: #ffffff;
    background-color: #ffffff;
    color: #1f2933;
    border: 1px solid #d6dde7;
    border-radius: 3mm;
    font-family: "native:MainLight";
    font-size: 3mm;
    margin: 1.2mm 0 1.2mm 0;
    padding: 1.4mm;
}

Codename One CSS is intentionally close to web CSS, but has its own properties and conventions. Here, we use native fonts and dimensions in millimeters. The card appears pink in the screenshot because the Component Inspector highlights the selected component.

We can also define pressed and selected states and separate dark-mode rules:

ActivityCardPressed,
ActivityCard.pressed,
ActivityCard.selected {
    [...]
}
@media (prefers-color-scheme: dark) {
    ActivityCard {
        [...]
    }
    ActivityCardPressed,
    ActivityCard.pressed,
    ActivityCard.selected {
        [...]
    }
}

The UIID is the bridge between the component tree and the final appearance of the app.

5.3. Supporting Small Screens, Large Screens, and Font Scaling

If the user increases the system font size or changes the app font scale from the Settings form, labels may need more room, cards may become taller, and scrollable containers must absorb the extra content. This is useful on large screens, but can become problematic on small screens.

The complete source code includes defensive helpers for edge cases where single-line text doesn’t fit. These helpers can cap the font size so text stays within the available width. This is useful, but it adds complexity and should be evaluated on a case-by-case basis.

From this point on, we focus on the main Codename One patterns rather than implementation details. Daily Routine is the reference example, but the goal is to learn how to structure Codename One apps in general.

6. Building the Core Activity Workflow

The activity workflow gives us the core of the app: a model, a store, a list screen, an editor, and a details screen.

6.1. Modeling Activities

The central domain object is Activity, implemented as a Java record:

public record Activity(
        String id,
        String title,
        ActivityCategory category,
        LocalDate date,
        LocalTime time,
        String notes,
        boolean completed,
        PlaceInfo place,
        Instant updatedAt
) [...]

Categories are modeled with an enum. Each category has a storage code, a localization key, and a sort order:

public enum ActivityCategory {
    APPOINTMENT("appointment", "category.appointment", 0),
    ROUTINE("routine", "category.routine", 1),
    WORK("work", "category.work", 2),
    [...]
}

This keeps the model simple to persist, localize, and display.

6.2. Listing Activities on the Home Form

The home screen reads activities from ActivityStore and rebuilds the list when data changes.

Unlike a web page, a Codename One form doesn’t always update the visible UI immediately after we change the component hierarchy. This is a design choice that helps reduce unnecessary layout work, especially in complex component trees. The final call to revalidate() tells Codename One to lay out the updated listContainer again, so the changes are reflected on screen:

private void refreshList() {
    List<Activity> activities =
            context.getActivityStore().getActivitiesInInsertionOrder();
    listContainer.removeAll();
    for (Activity activity : activities) {
        listContainer.add(createCard(activity));
    }
    listContainer.revalidate();
}

The form doesn’t load JSON directly. Instead, it uses AppContext to access the current ActivityStore, keeping UI code focused on rendering and user interaction.

Each activity is displayed as a card:

private Container createCard(Activity activity) {
    Container card = new Container(new LayeredLayout());
    card.setUIID("ActivityCard");
    Container content = new Container(new BorderLayout());
    Container textColumn = new Container(BoxLayout.y());
    // Add icon, title, category, schedule, place, and status labels
    content.add(BorderLayout.CENTER, textColumn);
    card.add(content);
    Button overlay = createCardOverlayButton(
            "activityCard-" + activity.id(),
            () -> context.showActivityDetails(this, activity)
    );
    card.add(overlay);
    return card;
}

The card structure, CSS styling, and navigation follow the same pattern: component tree for structure, UIID for appearance, and AppContext for navigation.

6.3. Adding and Editing Activities

The editor form handles both new and existing activities. When saving, it validates required fields, builds an ActivityDraft, converts it into an Activity, and stores it:

private void saveActivity() {
    String title = titleField.getText() == null
            ? ""
            : titleField.getText().trim();
    if (title.length() == 0) {
        Dialog.show(
                context.text("validation.title"),
                context.text("validation.activity.title"),
                context.text("ok"),
                null
        );
        return;
    }
    ActivityDraft draft = new ActivityDraft();
    draft.setTitle(title);
    draft.setCategory(selectedCategory());
    draft.setNotes(notesArea.getText());
    draft.setCompleted(completedSwitch.isValue());
    draft.setPlace(selectedPlace);
    String id = existingActivity == null
            ? IdGenerator.newId()
            : existingActivity.id();
    context.getActivityStore().save(draft.toActivity(id));
    context.showHome();
}

The exact form has more fields, such as date and time. The pattern is that the form edits a temporary state, while the store receives a complete activity only when the user confirms.

6.4. Showing Activity Details

The details screen shows one activity and offers actions such as editing or toggling completion:

public void toggleCompleted() {
    context.getActivityStore().toggleCompleted(activityId);
    refresh();
}

Since Activity is immutable, the store toggles completion by creating a new instance and saving it.

The edit action uses the same navigation pattern:

public void editCurrentActivity() {
    context.showActivityForm(this, currentActivity());
}

At this point, the core workflow is complete: list, editor, and details form.

7. Saving and Testing Data Locally

The activity workflow now works, but data must survive restarts.

7.1. Persisting Activities as JSON

The UI doesn’t interact with files directly. It calls the store, and the store delegates persistence to ActivityRepository:

public class ActivityRepository {
    public List<Activity> loadActivities() throws IOException {
        String path = filePath();
        if (!FileSystemStorage.getInstance().exists(path)) {
            return new ArrayList<>();
        }
        String json = IOUtil.readUtf8File(path);
        return codec.decodeActivities(json);
    }
    public void saveActivities(List<Activity> activities) throws IOException {
        IOUtil.writeUtf8File(
            filePath(),
            codec.encodeActivities(activities)
        );
    }
}

The repository keeps forms independent from file storage, and its logic can be tested without involving forms or user interaction.

The JSON conversion is handled by a codec:

String json = codec.encodeActivities(activities);
List<Activity> activities = codec.decodeActivities(json);

Thus, the model stays independent, the repository owns persistence, and the UI works with domain objects.

7.2. Using the App Home Directory

Codename One provides an app-specific home directory for local files. The lifecycle creates the repositories, while each repository owns its storage path:

protected ActivityRepository createActivityRepository() {
    return new ActivityRepository();
}
protected SettingsRepository createSettingsRepository() {
    return new SettingsRepository();
}

The activity repository stores JSON under the app home directory:

public String filePath() {
    return appHomePath() + "activities.json";
}

The settings repository follows the same idea:

protected String filePath() {
    return CN.getAppHomePath() + "settings.json";
}

In the complete implementation, both repositories support a test-only override, so tests can write to a dedicated location.

This keeps persistence portable: the actual location differs between targets, but the app uses the same repository abstraction. In the simulator, the JSON files are easy to inspect and edit; on real devices and browser builds, storage is platform-specific and usually less convenient to inspect directly.

7.3. Testing the Repository

Codename One includes a testing API based on AbstractTest, usable through the simulator and device testing workflow.

Among the tests in the complete source code, one focused example verifies local persistence:

public class ActivityRepositoryRoundTripTest extends AbstractTest {
    @Override
    public boolean runTest() throws Exception {
        String path = FileSystemStorage.getInstance().getAppHomePath()
                + "tests/activity-round-trip-"
                + System.currentTimeMillis()
                + ".json";
        TestActivityRepository repository = new TestActivityRepository(path);
        List<Activity> activities = new ArrayList<>();
        Activity original = createActivity();
        activities.add(original);
        try {
            repository.saveActivities(activities);
            List<Activity> loaded = repository.loadActivities();
            assertEqual(1, loaded.size(), "Exactly one activity should be loaded");
            assertEqual(original, loaded.get(0), "The activity should survive a JSON round trip");
            return true;
        } finally {
            repository.reset();
        }
    }
}

TestActivityRepository redirects persistence to a test-specific file. Codename One also supports JUnit 5 for simulator-side tests on the JavaSE port, while AbstractTest remains the most portable option inside the Codename One runtime model.

8. Adding Place Autocomplete, REST, and Maps

Finally, we add place search and map display: a concise example of REST, JSON parsing, and embedded web content.

8.1. Searching Places With Geoapify

The editor lets the user search for a place and attach it to an activity. We use Geoapify because it provides autocomplete and map preview APIs, has a generous free tier, and enables the creation of a free API key without a credit card.

The complete source code includes a free example key, lightly obfuscated with XOR, so the demo can run out of the box. XOR isn’t security; it only avoids storing the key as plain text. For production, we should use a private key. Even better, the key shouldn’t live inside the app: the app should call the backend, and the backend should call Geoapify.

The form depends on a service interface, not on Geoapify directly:

public interface PlaceSearchService {
    SearchHandle search(
            AppContext context,
            String query,
            SuccessCallback<List<PlaceSuggestion>> onSuccess,
            FailureCallback<List<PlaceSuggestion>> onFailure
    );
    interface SearchHandle {
        void cancel();
    }
}

The implementation builds an autocomplete URL and submits a Codename One network request:

private String buildAutocompleteUrl(AppContext context, String query) {
    StringBuilder builder = new StringBuilder(
            "https://api.geoapify.com/v1/geocode/autocomplete?"
    );
    builder.append("text=").append(Util.encodeUrl(query));
    builder.append("&format=geojson");
    builder.append("&limit=").append(AppConfig.GEOAPIFY_RESULT_LIMIT);
    builder.append("&lang=").append(context.getSettings().languageCode());
    builder.append("&apiKey=").append(AppConfig.geoapifyApiKey());
    return builder.toString();
}

Again, the form depends on an application service, while provider-specific code stays in one place.

When working with callbacks and UI updates, we should also keep Codename One’s EDT (Event Dispatch Thread) in mind, so slow work, such as a network request, doesn’t block the interface.

8.2. Parsing the REST Response

Geoapify returns GeoJSON. The service extracts only the fields the app needs and creates PlaceSuggestion objects:

@SuppressWarnings("rawtypes")
private List<PlaceSuggestion> parseSuggestions(String json) throws IOException {
    JSONParser parser = new JSONParser();
    Map<String, Object> root = parser.parseJSON(new StringReader(json));
    List<PlaceSuggestion> suggestions = new ArrayList<>();
    List features = (List) root.get("features");
    // Read properties, geometry, and coordinates
    // Convert each feature into a PlaceSuggestion
    return suggestions;
}

The form receives domain objects, not raw JSON maps.

8.3. Showing a Map Preview With BrowserComponent

After the user selects a place, GeoapifyMapView checks whether a native browser component is available, then shows a Leaflet page:

browser = new BrowserComponent();
browser.setPinchToZoomEnabled(true);
browser.setNativeScrollingEnabled(true);
browser.setPage(buildMapHtml(place), null);
add(BorderLayout.CENTER, browser);

The page loads Leaflet, uses Geoapify map tiles, centers the map, and adds a marker:

private String buildMapHtml(PlaceInfo place) {
    String tileUrl = "https://maps.geoapify.com/v1/tile/"
            + AppConfig.GEOAPIFY_TILE_STYLE
            + "/{z}/{x}/{y}.png?apiKey="
            + AppConfig.geoapifyApiKey();
    return "<!doctype html><html><head>"
            + "<link rel=\"stylesheet\" "
            + "href=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.css\"/>"
            + "</head><body><div id=\"map\"></div>"
            + "<script src=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.js\"></script>"
            + "<script>"
            + "var map = L.map('map').setView(["
            + place.latitude() + "," + place.longitude() + "],"
            + AppConfig.MAP_ZOOM + ");"
            + "L.tileLayer('" + tileUrl + "').addTo(map);"
            + "L.marker([" + place.latitude() + ","
            + place.longitude() + "]).addTo(map);"
            + "</script></body></html>";
}

The rest of the app works with a normal Codename One component, while the embedded browser handles the map. If native browser support isn’t available, the complete source code falls back to a static Geoapify map image.

9. Conclusion

In this tutorial, we built a realistic Codename One application with Java 17 and Maven. Furthermore, we used the Daily Routine application to understand the main patterns behind Codename One development: lifecycle, shared context, navigation, forms, layout managers, UIIDs, CSS, persistence, testing, REST, and map previews.

The same design principle appeared repeatedly: keep forms focused on UI and user interaction, and move persistence, networking, localization, settings, and reusable logic into small services and repositories.

As always, the complete source code for this tutorial is available over on GitHub.

       

1. Spring and Java

>> Spring and Security In The Times Of AI [spring.io]

A candid look at why the May release train moved into June, and why this round of upgrades deserves real attention: AI-assisted scanning is changing the volume of security reports across open source. An interesting read.

Also worth reading:

• >> Hibernate 7.4 New Features [jetbrains.com]
• >> Tiberius: A Security Testing Framework for LLM Applications in Java [foojay.io]
• >> Intelligent JVM Monitoring: Combining JDK Flight Recorder with AI [inside.java]
• >> Two Hibernate Annotations That Cut Our JSON Processing Time in Half [in.relation.to]
• >> Empower your AI migrations to Quarkus with Skills [quarkus.io]
• >> Jakarta EE is Ready for AI – But Don’t Just Take My Word for It! [foojay.io]
• >> Bumping the minimum officially supported GraalVM version to 25.0 [quarkus.io]
• >> Quarkus Hibernate with Panache Next renamed to Quarkus Data Hibernate [quarkus.io]
• >> PEM Encodings of Cryptographic Objects (Third Preview) [openjdk.org]
• >> Post-Mortem Crash Analysis with jcmd [openjdk.org]
• >> JFR In-Process Data Redaction [openjdk.org]
• >> Endive and the next chapter of WebAssembly on the JVM [bytecodealliance.org]

Webinars and presentations:

• >> Episode 59 “Java *is* Memory Efficient” [AtA] [inside.java]
• >> A Bootiful Podcast: JetBrains’ Marit van Dijk [spring.io]
• >> A Bootiful Podcast: Microsoft’s Martijn Verburg [spring.io]

Time to upgrade:

• >> Hibernate Reactive 4.4.0.Final released [in.relation.to]
• >> IntelliJ IDEA 2026.1.3 Is Out! and IntelliJ IDEA 2025.3.6 Is Out! [jetbrains.com]
• >> Kotlin 2.4.0 Released [jetbrains.com]
• >> Quarkus 3.36.1 – Maintenance release [quarkus.io]
• >> Spring AI 2.0.0-M8 is available now [spring.io]
• >> Jetty 12.1.10, 12.0.36, and 12.0.35 [github.com/jetty]
• >> Vert.x 4.5.28 and 5.1.1 [github.com/eclipse-vertx]
• >> Elasticsearch 9.4.2, 9.3.5, and 8.19.16 [github.com/elastic]
• >> Zuul v3.6.10 [github.com/Netflix]
• >> Micronaut Core 5.0.2, 5.0.1, 4.10.25, 4.10.24, 3.10.8, and 3.10.7 [github.com/micronaut-projects]

2. Technical & Musings

>> From Silos to Service Topology: Why Netflix Built a Real-Time Service Map [netflixtechblog.com]

Netflix moved toward a live topology map of service dependencies.

Also worth reading:

• >> AI gateways: why and how [frankel.ch]
• >> With Claude: Less Coding, More Testing [henrikwarne.com]
• >> Dynamic Repartitioning for Time Series Workloads [netflixtechblog.com]
• >> Building an autonomous ML researcher with Claude Code dynamic workflows [krasserm.github.io]
• >> 1,000 Data Breaches Later, the Disclosure Lag is Worse Than Ever [troyhunt.com]
• >> NFC, Crypto, Biometrics, And A New Build Cloud [foojay.io]
• >> Humans In The Way [satisfice.com]

3. Pick of the Week

>> Subtract [sive.rs]

       

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.

       

Comments

• In reply to Daizcone. Hey, Daixcone. We're glad to hear the ... by Ulisses Lima
• The article is very well structured and explained. I really ... by Daizcone

 

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]