Java Code Geeks

Credential	Provider	Exam Cost	Avg Salary	Best For
SAA-C03	AWS	$150	~$136k	Entry-level architects, startups
SAP-C02	AWS	$300	~$175k	Senior architects, enterprise AWS
AZ-305	Azure	$165 (+prereq)	~$147k	Enterprise, Microsoft-shop environments
GCP PCA	Google Cloud	$200	~$152k	Data/AI/ML-heavy workloads

Career Stage	Recommended Certs	Why
Early (0–2 yrs)	AWS SAA-C03 → Terraform Associate	Best ROI and job market entry point; IaC shows immediate practical value
Mid (2–5 yrs)	AWS SAP-C02 or AZ-305 → CKA	Architect-level credentials that open senior roles; Kubernetes for platform work
Senior (5+ yrs)	GCP PCA + AWS Security Specialty or MLS-C01	Multi-cloud positioning; AI/security specialisation for premium roles
Leadership track	CISSP	Security governance credibility for Principal/Distinguished/CISO-adjacent roles

How to Wait for Dynamic Content in Selenium Without Delays

Omozegie Aziegbe — Wed, 24 Jun 2026 14:15:00 +0000

How to Wait for Dynamic Content in Selenium Without Delays

Modern web applications are no longer simple HTML pages served from a server and rendered once in the browser. Instead, they are dynamic, JavaScript-driven systems where most of the UI is built or modified after the initial page load. Frameworks like React, Angular, and Vue frequently render content asynchronously, fetch data through API calls, and continuously update the DOM based on user interaction or background processes.

This shift creates a major challenge for automated testing with Selenium WebDriver: how do you reliably know when a page is actually ready?

A page may return a complete load event while still rendering critical UI components. Elements may exist in the DOM but not yet be visible or interactive. Data may still be loading in the background. As a result, traditional approaches to waiting for page loads are often insufficient.

In this article, we’ll explore how to correctly wait for JavaScript-heavy pages in Selenium without relying on arbitrary delays like Thread.sleep(), and instead build reliable and stable synchronization strategies.

1. Why Waiting is Hard in JavaScript-Heavy Applications

In traditional server-rendered applications, page load behavior was relatively predictable:

The browser requests a page
Server responds with fully rendered HTML
Page finishes loading
Test proceeds

But modern applications behave differently:

Initial HTML is often minimal (a “shell”)
JavaScript loads and renders content dynamically
Data is fetched asynchronously via APIs
DOM updates occur multiple times after initial load
UI components may load at different speeds

This means that even if Selenium detects that the page has loaded, the application may still be:

Fetching data from APIs
Rendering components
Hydrating client-side frameworks
Updating the DOM dynamically

So the real challenge is not detecting page load but detecting application readiness.

The Problem With Arbitrary Waits

A common beginner approach is using Thread.sleep(5000), but while it may seem effective at first, it introduces several problems:

Wasted Test Time: If the page loads in 1 second, the test still waits 5 seconds unnecessarily, increasing overall execution time significantly when repeated across many tests.
Flaky Tests: If the page takes longer than expected due to slow network, server latency, CI/CD load, or API delays, the test may fail even when the application is functioning correctly.
Non-deterministic Behaviour: Fixed delays do not adapt to real runtime conditions, making test execution inconsistent and reducing the overall reliability of the test suite.

2. Understanding Selenium Wait Strategies

Selenium provides two main synchronization mechanisms:

Implicit Wait

driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));

This tells WebDriver to poll the DOM for a certain amount of time when trying to find elements. Limitations include the fact that it only applies to element lookup, does not guarantee full page readiness, and can slow down test execution when used excessively.

Explicit Wait (Recommended Approach)

Explicit waits are the main way to reliably synchronize tests in Selenium.

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

We define exact conditions that must be met before proceeding.

wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("submit")));

This is far more reliable than waiting for a fixed time.

3. Waiting for Document Ready State

One common way to detect page load completion is by checking the browser’s document readiness.

public class SeleniumWaitDemo {

    public static void main(String[] args) {
        WebDriverManager.chromedriver().setup();
        WebDriver driver = new ChromeDriver();

        driver.get("https://demoqa.com");

        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
        JavascriptExecutor js = (JavascriptExecutor) driver;

        wait.until(d
                -> js.executeScript("return document.readyState").equals("complete")
        );

        driver.quit();
    }
}

The document ready state helps you understand how far the browser has gone in loading a page. When the state is “loading”, the page is still in the process of loading. When it becomes “interactive”, the DOM is ready and can be accessed, but some resources like images or scripts may still be loading. Finally, when the state reaches “complete”, it means the page and its resources have finished loading from the browser’s perspective.

However, this approach has important limitations, especially with modern web applications. Even after the state is “complete”, frameworks like React or Vue may still be rendering components, API calls may still be in progress, and parts of the UI may continue updating dynamically. Because of this, the document ready state should be treated as a starting point or baseline check, rather than a final confirmation that the page is fully ready for interaction.

4. Waiting for AJAX Requests (jQuery)

Many pages load content via AJAX. Selenium cannot directly see network activity, but we can approximate it.

public class AjaxWaitExample {
    
    public static void main(String[] args) {
        WebDriverManager.chromedriver().setup();
        WebDriver driver = new ChromeDriver();

        driver.get("https://demoqa.com");

        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(15));

        wait.until(d -> {
            JavascriptExecutor js = (JavascriptExecutor) d;
            return (Boolean) js.executeScript("return jQuery.active === 0");
        });

        driver.quit();
    }
}

This code checks the number of active AJAX requests using jQuery.active. When the value becomes 0, it means all AJAX calls have finished. Selenium then waits until this condition is met before continuing. This ensures the page has completed background data loading. However, it only works if the application uses jQuery for AJAX requests.

5. Wait for JavaScript Framework Stability

Modern frameworks often introduce delayed rendering. You may need to wait for framework-specific signals.

React applications

You can wait for a root element:

wait.until(driver ->
    driver.findElements(By.cssSelector("#root")).size() > 0
);

Then wait for content:

wait.until(ExpectedConditions.visibilityOfElementLocated(
    By.cssSelector(".app-loaded")
));

This check ensures that the main React root element has been mounted in the DOM. In React applications, the UI is often rendered inside a single root container, so verifying its presence confirms that the initial rendering phase has started.

However, this does not guarantee that all components or data inside the application have fully loaded. It only indicates that the React application has been initialized and attached to the DOM, making it a useful early-stage synchronization point.

Angular Applications

wait.until(driver ->
    ((JavascriptExecutor) driver).executeScript(
        "return window.getAllAngularTestabilities()[0].isStable()"
    ).equals(true)
);

This approach checks Angular’s internal testability API to determine whether the application is stable. When isStable() returns true, it means Angular has finished processing all asynchronous tasks such as HTTP requests, timers, and change detection cycles.

This makes it a more reliable signal compared to generic DOM checks, as it reflects the actual internal state of the Angular framework. However, it only works in environments where Angular testability is enabled and properly exposed.

6. Wait for Visibility + Interactivity

In many cases, an element may already exist in the DOM but still not be ready for user interaction. It might be hidden, disabled, or still being rendered by JavaScript. Because of this, simply checking that an element is present is not enough. You need to ensure that the element is both visible and ready to be interacted with before performing actions like clicks or typing.

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

WebElement button = wait.until(
    ExpectedConditions.elementToBeClickable(By.id("submit"))
);

button.click();

This code waits until the target element is not only present in the DOM but also visible and enabled, meaning it can be safely interacted with. Once Selenium confirms that the element is clickable, it returns the WebElement and allows the action to proceed.

This helps prevent common issues such as ElementNotInteractableException or click actions being ignored because the element was still loading or covered by another UI layer.

7. Combining Multiple Wait Conditions

In real-world applications, a single wait condition is often not enough to confirm that a page is fully ready. Modern web apps load in multiple stages, including initial rendering, API calls, and dynamic UI updates. Because of this, a reliable approach is to combine multiple wait strategies to ensure the application is truly stable before interacting with it.

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(20));

JavascriptExecutor js = (JavascriptExecutor) driver;

// 1. Wait for document ready
wait.until(d -> js.executeScript("return document.readyState").equals("complete"));

// 2. Wait for main container
wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("app")));

// 3. Wait for final UI element
wait.until(ExpectedConditions.elementToBeClickable(By.id("dashboard-link")));

This approach ensures that different layers of the application are validated step by step. First, it confirms that the browser has completed the initial page load. Then it checks that the main application container is visible, indicating that the UI has been rendered.

Finally, it waits for a specific interactive element to become clickable, ensuring the page is fully ready for user actions. By combining these conditions, tests become significantly more stable and less prone to timing issues.

8. Conclusion

In this article, we explored how to handle waiting for complex JavaScript-driven pages in Selenium WebDriver using Java. We looked at why traditional approaches like Thread.sleep() are unreliable and how modern web applications require more intelligent synchronization strategies.

We also examined several practical techniques, including explicit waits, document ready state checks, framework-specific stability checks for React and Angular, AJAX completion handling, and visibility-based element waits. Each approach helps address different layers of modern web application behaviour. Ultimately, the key takeaway is that effective Selenium automation is not about waiting for time, but waiting for conditions.

9. Download the Source Code

Download
You can download the full source code of this example here: Java Selenium wait for complex JavaScript

This article explored how to manage wait strategies in Java Selenium for complex, JavaScript-driven pages.

Tags

[FREE EBOOKS] How to Do More with Less, 90 Days to Level Up Your Leadership & Four More Best Selling Titles

Java Code Geeks — Wed, 24 Jun 2026 10:30:30 +0000

Meta JCG

[FREE EBOOKS] How to Do More with Less, 90 Days to Level Up Your Leadership & Four More Best Selling Titles

Hello fellow geeks,

Fresh offers await you on our Information Technology Research Library, please have a look!

	How to Do More with Less: Future-Proofing Yourself in an AI-driven Economy ($28.00 Value) FREE for a Limited Time An honest and practical strategy guide to working in a world transformed by AI. In today’s workplace, headlines about artificial intelligence can feel overwhelming. With headlines swinging between promises of utopia and warnings of mass unemployment, for most knowledge workers, the truth feels unclear. In this book, Sharon Gai cuts through the noise. Drawing from real-world examples and global insights, she explains how AI is reshaping the way we work-without hype or fearmongering. Instead of choosing between blind optimism or outright pessimism, she offers a practical, balanced perspective that helps readers make sense of the rapidly evolving AI landscape. You’ll learn how to: Reskill and future-proof your career in the face of AI disruption. Identify which parts of your role can be automated, and which require human creativity and judgment. Use proven frameworks to evaluate AI’s impact on your work and your organization. Apply actionable tips and tools to boost productivity, make smarter decisions, and do more with less. Gain clarity as a parent, leader, or professional navigating what this means for the next generation. Whether you’re an employee anxious about your future, a parent concerned about your children’s opportunities, or a leader managing a lean team with tight budgets, this book provides the strategies and mindset you need to adapt so you can stop worrying and start preparing. Offer Expires 6/30/2026. Get it FREE!
	90 Days to Level Up Your Leadership ($22.00 Value) FREE for a Limited Time Supercharge your leadership skills in just three months with expert advice from an industry leader. In 90 Days to Level Up Your Leadership, executive fellow at Harvard Business School and bestselling author Bill George will teach you how to become a better leader by focusing on a specific step each week. From laying the groundwork for your leadership journey all the way through to tackling contemporary leadership challenges, this book walks you through exactly how to develop your leadership skills, one step at a time. Inside you’ll find: A crystal-clear, week-by-week roadmap to help you improve your leadership skills. Actionable steps and practical tasks you can apply immediately to become a better leader. Tools to help you embrace and personify authentic leadership. If you’re ready to transform your career and achieve your goals in just one quarter, the 90 Days to Level Up series is for you. Whether you’re brand-new to a business, stepping into a leadership role for the first time, or looking to enhance your skills, this series will be your personal guide to unlocking your potential and reaching new professional heights. Offer Expires 6/30/2026. Get it FREE!
	Cloud Security Fundamentals: Building the Foundations for Secure Cloud Platforms ($131.95 Value) FREE for a Limited Time A hands-on toolkit for securing contemporary cloud environments. In Cloud Security Fundamentals: Building the Foundations for Secure Cloud Platforms, cybersecurity leader and educator, Jason Edwards, delivers a comprehensive guide to safeguarding data, applications, and infrastructure in the cloud. The author offers a complete walkthrough of cloud security, moving from foundational concepts to advanced, forward-looking practices. The book is filled with practical examples, hands-on guidance, and lessons drawn from real-world cloud security incidents and breaches. It equips readers with the tools and knowledge they need to defend against threats in cloud environments and how to understand coming developments in cloud technology that will impact organizations in all industries. Inside the book: A thorough introduction to cloud-native and advanced security practices for contemporary firms. A chapter on relevant cloud security certifications and professional growth advice. Practical discussions of foundational concepts in cloud security, including IAM, Zero Trust, and DevSecOps. Complete treatments of advanced cloud security themes, like leadership strategies, operational best practices, and techniques for dealing with common and emerging threats. Perfect for cloud security professionals, IT managers, and DevOps professionals, Cloud Security Fundamentals will also benefit system administrators, compliance and risk officers, consultants, auditors, and technology students in a variety of fields who require a foundational understanding of cloud security concepts. Get it FREE!
	The Vibe Coding Playbook: Building Your Tech Business with AI ($35.00 Value) FREE for a Limited Time A detailed and up-to-date walkthrough for entrepreneurs with limited (or non-existent) coding skills who want to build profitable software companies using new gen-AI tools. In The Vibe Coding Playbook: Building Your Tech Business With AI, renowned AI and data science educator Siraj Raval walks you through exactly what you need to do to build a technology business with generative AI-powered code assistants. Raval offers step-by-step guidance for non-technical professionals and entrepreneurs interested in creating scalable, profitable enterprises without spending years learning how to code. This book conceives of new artificial intelligence tools, like Cursor, as “co-founders,” lighting your way to constructing valuable software products and services. You’ll learn to build minimally viable products (MVPs), iterate on your software products as you develop and after launch, and grow your company while maintaining a lean, efficient, solopreneur-focused structure. Inside the book: Detailed guidance for entrepreneurs interested in creating powerful tech solutions for niche problems and markets without hiring expensive software developers. Strategies for using generative AI tools to substitute for traditional technical co-founders. Illustrative case studies from real-world founders who built successful technology businesses without learning to code. Useful tools for non-technical entrepreneurs, including prompt libraries, decision trees, QR codes linking to video tutorials demonstrating key techniques, and access to an exclusive online community of like-minded founders. Perfect for ambitious professionals and entrepreneurs who want to build a successful technology company now – using commercially available AI tools – The Vibe Coding Playbook is your personal roadmap to creating useful and profitable software for customers without learning how to code. Get it FREE!
	The Wellbeing Centered Workplace: 10 Strategies Fuelling Business Growth & Performance ($30.00 Value) FREE for a Limited Time A heartfelt personal journey that unlocks the power of evidence-based wellbeing at work. In The Wellbeing-Centered Workplace, Chris Cummings shares a powerful personal and professional journey following his partner’s mental health challenges that motivated him to quit his corporate career and start Wellbeing at Work, a global purpose-led business empowering organizations to prioritize employee wellbeing through community engagement, meaningful connections, and expert knowledge sharing. This book offers an honest account of how prioritizing wellbeing-both personal and organizational-became the cornerstone of sustainable growth, stronger leadership, and elevated team performance. Through real-world experiences, strategic insights, and lessons learned, the author reveals how wellbeing is not a soft skill but a strategic advantage that drives innovation, resilience, and results. Readers will also find 10 practical steps that organizations can take forward to create thriving workplaces, with each step supported by case studies from senior business leaders who have found standout success in a particular area. A must-read for leaders, entrepreneurs, and change-makers looking to build purpose-driven organizations where people and profits thrive together. In this book, readers will find discussion on: The huge benefits of flexibility in courting the global talent pool and how we can engage with wider communities. The unique desires of Millennials and Gen Z and the growing number of people taking career breaks or shifting to new careers in their fifties. How to ensure the human aspect in the workplace while complementing the rapidly developing technological landscape. The Wellbeing-Centered Workplaceis a practical, thought-provoking read for business leaders and managers to understand and adapt to the new world of work across every level of their organizations. Get it FREE!
	The Persuasion Engine: How Any Business Can Use AI-Powered Neuromarketing to Understand and Win Customers ($28.00 Value) FREE for a Limited Time Tap into your customers’ unconscious minds with cutting-edge AI and neuromarketing techniques. The Persuasion Engine, by neuromarketing and behavioral science expert Roger Dooley, solves the most pressing challenge faced by every marketer: how to figure out why customers make the decisions they do when 95% of their thought processes occur at an unconscious level. Dooley explains how artificial intelligence democratizes sophisticated neuromarketing tools that were once available only to Fortune 500 companies, making powerful customer insight and persuasion techniques accessible to businesses of any size. The book walks you through the evolution of traditional neuromarketing into “Neuromarketing 2.0,” where AI-powered tools eliminate the need for expensive lab studies and human behavioral science experts. It offers a comprehensive roadmap for implementing eye tracking, facial coding, biometrics, implicit testing, and advanced AI behavioral techniques that dramatically improve marketing effectiveness while reducing costs and time investment. Inside the book, you’ll find: Revolutionary AI prompting strategies that bring world-class behavioral science expertise to your desktop. Practical frameworks for leveraging attention, emotion, credibility, and decision architecture to boost conversions. Step-by-step guidance for implementing biometric tools and implicit testing without laboratory resources. Advanced techniques for creating scarcity, urgency, and FOMO that drive immediate customer action. Comprehensive methods for auditing and enhancing empathy in customer communications. Perfect for marketing professionals, business owners, entrepreneurs, and anyone with a stake in customer acquisition and retention, The Persuasion Engine provides actionable strategies that will transform your approach to marketing. Whether you’re working on a shoestring or managing enterprise campaigns, you’ll discover how to use your customers’ non-conscious motivations and create compelling marketing that work on real people in the real world. Offer Expires 6/24/2026. Get it FREE!

That’s it for now, we hope you found them insightful. Stay tuned for more!

Till next time, keep geeking!

Tags

GIS Map Service Introduction in Java

young.gon — Wed, 24 Jun 2026 10:13:51 +0000

Core Java Desktop Java Java Software Development

GIS Map Service Introduction in Java

Java Map Service

1. Introduction

You can see various map services like google maps, bing map and more in your ordinary life. This post describes how we start to build a GIS map service server and a simple WMS(Web Map Service) client using java. I will make a GIS map service with Honolulu GIS data. I also implement a simple map client for that in java open source based technologies such as GeoServer and geotools. The target system is running on Windows OS but you can also use other operating system like LINUX or UNIX and so on with a little effort.

2. GIS

GIS, which stands for Geospatial Information System, is a system that provides data about the real world we live in. This real-world information allows us to view and analyze regional data directly on a map, enabling better decision-making. This type of data possesses absolute positioning (coordinates) and elevation, making it inherently valid as independent system information.

Customers/Buildings: Locations of retail stores or apartment complexes
Topography: Elevation and relief of mountains and valleys (Altitude)
Hydrography: Locations of rivers, oceans, and lakes
Roads: Line data for highways, national roads, and alleys

Ultimately, GIS map service renders complex geographic data into visual maps, transforming it into actionable information that users can easily verify and analyze with their own eyes.

3. Prerequisites

Our upcoming GIS map service will be implemented using Java. Consequently, several essential prerequisites are required. In this section, we will explore the necessary tools and environment setups needed to successfully build our map service.

3.1. JDK

The map service client will be built using Java Swing. To support this, OpenJDK 17 or higher is required; however, for the purpose of this post, we will be using OpenJDK 21.

Download openJDK 21

After downloading the compressed file, we need to designate a directory to create our project, where we will extract the files into the following folder to ensure consistency in installation and environment configuration

C:\DEV\Works\MapService

3.2. Maven

Downloading every single library used in this post one by one would be an overwhelming task for any developer. Therefore, we will define the required libraries in a Maven file, allowing them to be downloaded automatically to set up our development environment efficiently.

To ensure consistency in our development environment, we will extract the downloaded file into the following directory.

C:\DEV\Works\MapService

3.3. Geotools

This is a famous open-source software that every GIS developer knows. It provides a vast array of libraries designed to make reading, writing, and rendering spatial data effortless. In the case of GeoTools, we will use the Maven repository to download it automatically. Using this library, we will build a simple GIS map service client.

3.4. GeoServer

This is an open-source map server. To provide map services, we need a system capable of delivering geographic data. Specifically, these map servers read raw GIS data to serve it directly to clients or render it into map images. Accordingly, since we will be using the standalone version of GeoServer, please download it from the following site.

To ensure consistency in our development environment, we will extract the downloaded file into the following directory.

C:\DEV\Works\MapService

4. Selecting GIS Data for the Honolulu Region

To build a map service, GIS data is essential. However, since geographic data can contain sensitive information—such as military logistics or critical infrastructure—some countries heavily restrict its export or usage. Fortunately, there are several platforms that provide this data as open data. Specifically, we will be using the Honolulu dataset for our project.

For instance, if only a single road were to be drawn on the map, it would be difficult to determine whether that line represents a road, a river, or some other feature. Therefore, for someone familiar with Honolulu to actually recognize the region, multiple layers are necessary. To this end, we have selected several key datasets as follows.

Data set	Description
Building Footprint Centerpoints	Identifies locations of buildings on Oahu.
Zoning	Zoning designation boundaries from the City and County of Honolulu Zoning Code.
Right of Way	The street Right of Ways that extend between parcels.
Coastline	To reference the coastline for cartographic display.
Oahu Street Centerlines	To support common geographic and network analysis, routing and base mapping for City staff, Emergency Management, Homeland Security and Public Safety organizations
Building Footprint	Building Footprint Centerpoints
Zoning Map Boundary	Zoning Map Boundary
All Parcels	All_Parcels of Honolulu

5. Download GIS Data

There are various standard formats used to store geographic data. For development convenience, we plan to build a file-based service. Therefore, we will download and utilize SHP (Shapefile) format data—a standardized file format capable of storing GIS data—in a compressed archive format. As previously outlined in the data selection section, we have already chosen the Honolulu GIS datasets for our map service. You can follow the sequential steps below to download the data, and this exact process applies to all datasets identified in the previous section.

Visit https://honolulu-cchnl.opendata.arcgis.com/search
Use the keyword search; for example, type ‘Zoning’ to download Honolulu’s zoning data.
Click the Download button for the SHP file

To maintain development environment consistency, we have extracted the downloaded archive files and stored the datasets inside the following folders.

C:\DEV\Works\MapService\data

6. GeoServer Configuration

For GeoServer, we assume that the downloaded geoserver-2.28.4-bin.zip file has been extracted into the following directory, resulting in the folder geoserver-2.28.4-bin.

C:\DEV\Works\MapService\geoserver-2.28.4-bin

Once inside that directory, navigate to the bin folder and open the startup.bat file. As long as the JAVA_HOME variable is properly configured inside this file, GeoServer will launch without any issues. The procedure for specifying the JAVA_HOME variable is as follows:

Open your favorite text editor
Open the startup.bat file located in the geoserver-2.28.4-bin\bin\ directory.
Add the JAVA_HOME variable.

@echo off
SET JAVA_HOME=C:\DEV\Works\MapService\jdk-21

Next, let’s run the startup.bat file. If you see a screen like the one below, GeoServer has been launched successfully.

6.1. Logging into GeoServer

As verified in the startup section, our GeoServer instance is now running. Let’s make sure the GeoServer Web Interface is working properly. You can access GeoServer using the following URL:

http://localhost:8080/geoserver

When you access the URL, the GeoServer Web Interface screen will appear as shown below.

Web User Interface of GeoServer

After installing GeoServer, the default username for the web interface is admin, and its default password is geoserver. Enter this username and password, then click the Login button to perform your initial login as the administrator. Once logged in, the GeoServer configuration dashboard will appear as shown below.

7. Loading Honolulu GIS Data

Now, let’s load the Honolulu data into GeoServer. This process is essential for instructing GeoServer to ingest raw GIS data—in our case, Shapefiles (SHP)—and transform it into an active, ready-to-use map service.

7.1. Loading Honolulu SHP Data

You can load the downloaded SHP files into GeoServer by following the procedures below.

⚠️ IMPORTANT: Prior to uploading the Shapefile, verify that the dataset—including all companion extensions (.shp, .shx, .dbf, .prj)—resides in a specific server directory. All associated files must share an identical base name to ingest properly.

1. Workspace Creation

First, we need to create a Workspace. A workspace acts as the top-level container (or namespace) for managing all your GIS data. You can create one by following the steps below:

Click on Workspaces under the Data section in the left-hand menu.
Click the Add new workspace button located at the top.
Enter the following information and click the Save button.
- Name: Honolulu
- Namespace URI: https://honolulu-cchnl.opendata.arcgis.com/

Note: The Namespace URI does not need to be a live, active website. It is simply used as a unique identifier for your workspace.

As shown below, you can verify that the “Honolulu” workspace has been successfully created.

2. Data Store Configuration and Shapefile Registration

In this step, we will link the actual file path of the Shapefile on your local computer to GeoServer. The procedure described below applies to all data generated and saved in the “GIS Data Selection” section. Therefore, please repeat this process for every individual SHP file you have.

Click on Stores under the Data section in the left-hand menu.
Click the Add new Store button located at the top.
Select Shapefile from the Vector Data Sources list.
Configure the Data Store information as follows:
- Workspace: Honolulu (Select the workspace you created in Step 1)
- Data Source Name: Building_Footprint_Centerpoints_SHP
Configure the Connection Parameters (CRITICAL):
- URL: Click the Browse… button, navigate to the directory on your server where the SHP files are stored, and select the target .shp file.
- DBF charset: UTF-8.
- Click the Save button at the bottom.

3. Publishing a Layer and Configuring Spatial Reference

This is the final step to publish your map service to the web based on the saved data. First, you must verify that the data for our map service is successfully contained within the “Honolulu” workspace from Step 2, as shown below.

Simply navigate to Layers -> Add a new resource from the left-hand menu and select the corresponding data store.

Note: The procedure described below applies to all data generated and saved in the “GIS Data Selection” section. Therefore, please repeat this process for every individual SHP file.

Select the workspace/store you want to publish from the dropdown menu.
Click the Publish link next to the SHP file name listed on the screen.
On the Edit Layer page, configure the following mandatory fields:
Coordinate Reference Systems (공간 참조계)
- In most cases, GeoServer will automatically detect and configure the coordinate system. However, if the coordinate system for your SHP file is not automatically detected, click the Find… button next to Declared SRS, search for the correct EPSG code, and select it.
Bounding Boxes
- You must compute the bounding boxes so GeoServer can recognize the spatial extent of your map. Simply click the buttons in the following order to let GeoServer calculate them automatically:
- Click Compute from data (Calculates the bounding box from the raw data).
- Click Compute from native bounds (Calculates the spatial extent bounds).

4. Completion and Verification (Layer Preview)

Click the Save button at the very bottom of the page to complete the data loading and publishing process. To verify that your layer has been successfully published, click on Layer Preview at the very top of the left-hand menu. Find the name of the layer you just published (e.g., honolulu:layer_name), and click the OpenLayers link on the right. A new window will open, and you will see your SHP file beautifully visualized as a live map!

Once you have added layers for all the datasets from the “GIS Data Selection” section, you can search and verify the list of added layers as shown below.

Now, we have successfully completed the data loading process for the Honolulu regional GIS map service. The next step is to verify whether the web service we created has been generated and deployed correctly..

8. Understanding Web Map Services

We decided to use data from the Honolulu area for our map service. Viewing a map of Honolulu essentially means overlaying and combining multiple layers of data into a single, cohesive view, as shown below. The data we have downloaded and processed so far represents only a tiny fraction of that entire ecosystem.

Zoning

Building Footprint Centerpoints
Zoning
Right of Way
Coastline
Oahu Street Centerlines
Building Footprint Centerpoints
Zoning Map Boundary
All Parcels

To display this geospatial data, it is necessary to examine the GIS map service defined by the OGC (Open Geospatial Consortium), which serves as the industry standard.

8.1. WMS(Web Map Service)

WMS(Web Map Service) is a standard protocol that renders GIS data into map images (such as PNG or JPEG) on the server side and serves them to the web.

Requires a slight processing overhead as images are generated by the server on demand.
Reflects real-time data modifications instantly since the server queries the live data source for every request.

8.2. WFS(Web Feature Service)

A standard protocol that retrieves raw vector datasets (geographic features and attributes) from the server, allowing the client to handle the rendering and data processing.

Increases client-side complexity and computational load, as the client application is responsible for rendering large amounts of coordinate data.
Supports advanced GIS capabilities, enabling clients to query, manipulate, and directly edit/update (WFS-T) the underlying geospatial data attributes.

8.3. WPS(Web Process Service)

WPS provides client access to pre-defined spatial data processing algorithms and analytical functions (e.g., buffering, intersection, spatial analysis) on the server side.

Enables highly customized geospatial services tailored specifically to complex user business logic and rules.
Increases server-side computational load and architectural complexity exponentially as the business logic and analytical rules become more intricate.

8.4. WMTS(Web Map Tile Service)

WMTS serves pre-rendered, cached map tiles partitioned by predefined grids and LOD (Level of Detail) scales to maximize web map delivery performance.

Guarantees exceptionally fast loading speeds by serving optimized, small-sized static image tiles instead of rendering on the fly.
Widely adopted as the industry standard by major global map providers, including Google Maps and Bing Maps.
Introduces a data reflection delay (near real-time) since changes in the raw spatial data require re-generating or purging the cached tiles.

9. Simple WMS Client Application

To verify and interact with the Honolulu geospatial data we configured earlier, we will build a simple WMS client application. We will implement this GIS map service client using the robust capabilities provided by the open-source GeoTools library.

When it comes to WMS, the behavior of a GIS map service client is actually very simple.

It invokes the WMS service to check what kind of GIS map services are currently available.
Then, it simply requests the specific map image it wants from the WMS list.

Although you can merge multiple map layers into a single view, handling this feature is beyond the scope of this post. I will make sure to explain it in detail in the next article.

9.1. Configuring the Client Environment

First, to ensure consistency and proper environment configuration, we will set up our map service client in the following folder.

C:\DEV\Works\MapService\MapClient

1. Batch File Configuration

To configure the Maven environment, the following two environment variables are required:

JAVA_HOME: The installation path of the downloaded OpenJDK 21.
MVN_HOME: The installation path of the downloaded Apache Maven.

To streamline this setup, we have created a batch file named setenv.bat as shown below:

SET JAVA_HOME=C:\DEV\Works\MapService\jdk-21
SET MVN_HOME=C:\DEV\Works\MapService\apache-maven-3.9.16

SET PATH=%JAVA_HOME%\BIN;%MVN_HOME%\BIN;%PATH%;

2. Executing the Batch File

Open a Windows Command Prompt (cmd) window, navigate to the project directory, and enter setenv.bat as shown below.

3. Verifying the Maven Environment

Run the Maven version check command as shown below. If the output displays the exact Maven version you downloaded, your map service client environment configuration is successfully complete.

9.2. Configuring the Client Development Environment

First, create a pom.xml file as shown below to configure the project packages and manage the GeoTools library dependencies.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.honolulu.gis</groupId>
    <artifactId>map-client</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <geotools.version>32.2</geotools.version>
    </properties>

    <repositories>
        <repository>
            <id>osgeo</id>
            <url>https://repo.osgeo.org/repository/release/</url>
        </repository>
    </repositories>

    <dependencies>

        <dependency>
            <groupId>org.geotools</groupId>
            <artifactId>gt-main</artifactId>
            <version>${geotools.version}</version>
        </dependency>

        <dependency>
            <groupId>org.geotools</groupId>
            <artifactId>gt-wms</artifactId>
            <version>${geotools.version}</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.3</version>

                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>

                        <configuration>                           <createDependencyReducedPom>false</createDependencyReducedPom>

                            <filters>
                                <filter>
                                    <artifact>*:*</artifact>
                                    <excludes>
                                        <exclude>META-INF/*.SF</exclude>
                                        <exclude>META-INF/*.RSA</exclude>
                                        <exclude>META-INF/*.DSA</exclude>
                                    </excludes>
                                </filter>
                            </filters>

                            <transformers>

                                <transformer implementation=
                                        "org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>

                                <transformer implementation=
                                        "org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">

                                    <mainClass>
                                        com.honolulu.gis.Main
                                    </mainClass>
                                </transformer>
                            </transformers>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Subsequently, execute the mvn install command to validate the integrity of the build and ensure the absence of configuration errors. Upon a successful verification check, the system will autonomously resolve and download the necessary dependency artifacts, as depicted in the diagram below.

9.3. Establishing the Maven Source Directory Layout

To align with standard development practices, we will configure the Maven directory layout and provision the required folders to initialize the execution environment for the Java map service client application.

MapClient/                       (Project Root)
 ├── src/
 │    ├── main/
 │    │    ├── java/             (Java source code root)
 │    │    │    └── com/
 │    │    │         └── honolulu/
 │    │    │              └── gis/
 │    │    │                   ├── Main.java      (Application entry point)
 │    │    │                   ├── MainFrame.java (Main GUI window container)
 │    │    │                   ├── MapPanel.java  (Dedicated map rendering screen)
 │    │    │                   ├── GeoServerClient.java (WMS connection &amp; communication handler)
 │    │    │                   └── WmsLayerInfo.java (Data model for WMS layer metadata)
 │    │    └── resources/        (Application resources and configurations)
 │    │         └── logback.xml  (Optional: Logging framework configuration)
 │    └── test/                  (Unit test source root)
 │         └── java/
 └── pom.xml             (Project object model for dependencies and build setup)

Please place and create the project folder structure within our designated workspace directory as shown below.

C:\DEV\Works\MapService

10. Implementing the GeoServer WMS Client

All setups and environment configurations are now complete. It is time to implement the Java source code inside our established project directory.

The architecture consists of the MainFrame class as the primary UI window container. The core functionality is driven by two main components: GeoServerClient, which communicates with GeoServer to fetch map graphics via WMS, and MapPanel, which renders those retrieved map images onto the screen. This section provides a detailed breakdown and explanation of each source file.

10.1. The Main Class

The Main class serves as the application entry point. It handles the secure initialization of the graphical user interface.

Event Dispatch Thread (EDT) Safety: By utilizing SwingUtilities.invokeLater(), the application guarantees that the creation and manipulation of Swing UI components are executed strictly on the single-threaded Event Dispatch Thread, preventing potential concurrency or rendering anomalies.
Main Window Lifecycle: It instantiates the top-level UI container, MainFrame, and invokes setVisible(true) to render it visible to the end user.

package com.honolulu.gis;

import javax.swing.*;

public class Main {

    public static void main(
            String[] args) {

        SwingUtilities.invokeLater(
                () -> {
                    try {
                        MainFrame frame = new MainFrame();
                        frame.setVisible(true);
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
        );
    }
}

10.2. The `MainFrame` Class

MainFrame extends JFrame and acts as the central coordinator of the application. It manages UI layout partitioning, layer data modeling, and WMS state transitions.

Split Layout Architecture: It implements a JSplitPane with a divider to isolate concerns:
- Left Pane (createTree()): Displays a hierarchical tree view of remote GIS metadata layers.
- Right Pane (mapPanel): Hosts the customized image component designated for geospatial canvas rendering.

Stream-driven Layer Categorization:
- The createTree() method consumes list metadata from client.loadLayers().
- It leverages Java Streams to filter for targets matching the “Honolulu” namespace, groups them efficiently using Collectors.groupingBy(), and builds a robust component hierarchy using DefaultMutableTreeNode.

public class GeoServerClient {
    private final String wmsUrl;
    private WebMapServer server;

    public GeoServerClient(String wmsUrl) throws Exception {
        this.wmsUrl = wmsUrl;

        server = new WebMapServer(new URL(
            wmsUrl + "?service=WMS&request=GetCapabilities"
        ));
    }	
	
	...
	
	public List<WmsLayerInfo> loadLayers() {
        List<WmsLayerInfo> result = new ArrayList<>();
        collect(server.getCapabilities().getLayer(), result);
        return result;
    }
	
	...
}

Asynchronous Selection and Map Refreshment:
- A TreeSelectionListener continuously monitors user interactions. When a user selects a valid WmsLayerInfo leaf node, the application updates the active selectedLayers cache.
- The refreshMap() mechanism queries the GeoServer backend to parse the target layer bounds (BBox) and spatial reference system (CRS). It automatically calculates dimensions based on the current mapPanel viewport scale and dispatches a WMS GetMap transaction, dynamically mapping the incoming buffer stream straight to the canvas display.

package com.honolulu.gis;

import javax.swing.*;
import javax.swing.tree.*;
import java.awt.*;
import java.util.*;
import java.util.List;
import java.util.stream.Collectors;

public class MainFrame extends JFrame {

    private final MapPanel mapPanel =
            new MapPanel();

    private final Set<String> selectedLayers =
            new HashSet<>();

    private final GeoServerClient client;

    public MainFrame() throws Exception {
        client 
          = new GeoServerClient(                                                                 "http://localhost:8080/geoserver/wms");

        setTitle("GeoServer WMS Client");

        setSize(1400,900);

        setDefaultCloseOperation(
                JFrame.EXIT_ON_CLOSE
        );

        JSplitPane split =
                new JSplitPane();

        split.setDividerLocation(300);

        split.setLeftComponent(
                createTree()
        );

        split.setRightComponent(
                mapPanel
        );

        add(split);
    }

    private JScrollPane createTree()
            throws Exception {

        List<WmsLayerInfo> layers =
                client.loadLayers();

        DefaultMutableTreeNode root =
                new DefaultMutableTreeNode(
                        "Layers"
                );
        //Filter 'Honolulu' namespace only
        Map<String, List<WmsLayerInfo>> grouped =
			layers.stream()
                .filter(l -> "Honolulu".equals(l.namespace()))
                .collect(Collectors.groupingBy(WmsLayerInfo::namespace));

        for(var entry : grouped.entrySet()) {

            DefaultMutableTreeNode ns =
                    new DefaultMutableTreeNode(
                            entry.getKey()
                    );

            for(var layer : entry.getValue()) {

                ns.add(
                        new DefaultMutableTreeNode(
                                layer
                        )
                );
            }

            root.add(ns);
        }

        JTree tree =
                new JTree(root);

        tree.addTreeSelectionListener(e -> {

            Object node =
                    ((DefaultMutableTreeNode)
                            tree.getLastSelectedPathComponent())
                            .getUserObject();

            if(node instanceof WmsLayerInfo layer) {

                try {

                    selectedLayers.clear();

                    selectedLayers.add(
                            layer.name()
                    );

                    refreshMap();

                } catch (Exception ex) {
                    ex.printStackTrace();
                }
            }
        });

        return new JScrollPane(tree);
    }

    private void refreshMap()
            throws Exception {

		GeoServerClient.BBoxInfo binfo = client.getBoundsFromLayers(new ArrayList<>(selectedLayers));
		String bbox = binfo.bbox;
		String crs = binfo.crs;
		var image =
				client.getMap(
						new ArrayList<>(selectedLayers), // String OK
						bbox,crs,
						mapPanel.getWidth(),
						mapPanel.getHeight()
				);

        mapPanel.setImage(image);
    }
}

10.3. The `GeoServerClient` Class

The GeoServerClient class serves as the dedicated network interface controller that manages OGC WMS transactions with the remote GeoServer container using the GeoTools API capabilities.

Capabilities Lifecycle Initialization:
- The constructor accepts the root WMS endpoint and instantiates a WebMapServer component by issuing an implicit GetCapabilities metadata handshake. This caches the entire server capabilities tree schema in application storage upon startup.

server = new WebMapServer(new URL(
    wmsUrl + "?service=WMS&request=GetCapabilities"
 ));

Automated Bounding Box (BBox) and CRS Retrieval:
- The getBoundsFromLayers() routine automates spatial boundary detection. It queries the target mapping layer properties, retrieves the primary Coordinate Reference System (CRS), maps it to a GeoTools CRSEnvelope, and serializes the lower/upper bounds into a standard comma-delimited bounding box coordinate string ("minx,miny,maxx,maxy").
Recursive Metadata Tree Traversal (loadLayers() & collect()):
- GeoServer layers inherently possess nested hierarchical characteristics. To resolve this, the client deploys a recursive algorithm within the collect() function.
- It runs depth-first searches across all getLayerChildren() arrays, splits namespace domains by identifying character colons (:), and constructs an iterable list model containing sanitized WmsLayerInfo records.
Dynamic WMS GetMap Compilation:
- The getMap() function compiles raw viewport geometries directly into compliant WMS URL specifications.
- It binds array collections, spatial boundaries (bbox), spatial references (srs), and target output resolutions (width, height) into a query pipeline.
- By piping this connection stream through ImageIO.read(), it smoothly captures the pixel-perfect image/png response and maps it seamlessly into an immutable native BufferedImage layer context.

package com.honolulu.gis;

import org.geotools.ows.wms.Layer;
import org.geotools.ows.wms.WebMapServer;
import org.geotools.ows.wms.WMSCapabilities;
import org.geotools.geometry.jts.ReferencedEnvelope;
import org.geotools.ows.wms.CRSEnvelope;

import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;


public class GeoServerClient {

    private final String wmsUrl;

    private WebMapServer server;

    public GeoServerClient(String wmsUrl) throws Exception {
        this.wmsUrl = wmsUrl;

        server = new WebMapServer(new URL(
                wmsUrl + "?service=WMS&request=GetCapabilities"
        ));
    }
	
	public static class BBoxInfo {
		public String bbox;
		public String crs;
	}
	
	public BBoxInfo getBoundsFromLayers(List<String> layers) {

		Layer layer = findLayerByName(layers.get(0));

		var map = layer.getBoundingBoxes();

		String crs = map.keySet().iterator().next();
		CRSEnvelope env = map.get(crs);

		double minx = env.getLowerCorner().getOrdinate(0);
		double miny = env.getLowerCorner().getOrdinate(1);
		double maxx = env.getUpperCorner().getOrdinate(0);
		double maxy = env.getUpperCorner().getOrdinate(1);

		BBoxInfo info = new BBoxInfo();
		info.bbox = minx + "," + miny + "," + maxx + "," + maxy;
		info.crs = crs;

		return info;
	}
	
    public List<WmsLayerInfo> loadLayers() {

        List<WmsLayerInfo> result = new ArrayList<>();

        collect(server.getCapabilities().getLayer(), result);

        return result;
    }

    private void collect(Layer layer, List<WmsLayerInfo> result) {

        if (layer.getName() != null) {

            String ns = "";

            if (layer.getName().contains(":")) {
                ns = layer.getName().split(":")[0];
            }

            result.add(new WmsLayerInfo(
                    ns,
                    layer.getName(),
                    layer.getTitle()
            ));
        }

        for (Layer c : layer.getLayerChildren()) {
            collect(c, result);
        }
    }
	
	private org.geotools.ows.wms.Layer findLayerByName(String name) {

		return find(server.getCapabilities().getLayer(), name);
	}

	private org.geotools.ows.wms.Layer find(
			org.geotools.ows.wms.Layer root,
			String name
	) {
		if (name.equals(root.getName())) {
			return root;
		}

		for (var c : root.getLayerChildren()) {
			org.geotools.ows.wms.Layer r = find(c, name);
			if (r != null) return r;
		}

		return null;
	}

    public BufferedImage getMap(
		List<String> layers,
		String bbox,
		String crs,
		int width,
		int height
    ) throws Exception {

        String url =
			wmsUrl +
			"?service=WMS" +
			"&request=GetMap" +
			"&version=1.1.1" +
			"&layers=" + String.join(",", layers) +
			"&bbox=" + bbox +
			"&width=" + width +
			"&height=" + height +
			"&srs=" + crs +
			"&format=image/png";
		
        return ImageIO.read(new URL(url));
    }
}

10.4. The `MapPanel` Class

The MapPanel class extends JPanel and serves as a custom graphics canvas dedicated to drawing the fetched WMS map imagery (BufferedImage) onto the client UI application framework.

Image State Invalidation and Repainting (setImage):
- This method acts as a standard state mutator. When called by the master controller, it caches the newly fetched geospatial bitmap into the local image field.
- It immediately invokes repaint(), which posts an asynchronous paint event to the Swing Event Dispatch Thread (EDT), prompting the framework to refresh the visible graphical region without lagging the main UI loop.
Graphics Pipeline Lifecycle Hooks (paintComponent):
- The class overrides paintComponent(Graphics g) to inject custom drawing logic directly into the native window composite layer.
- super.paintComponent(g) is executed sequentially at the absolute beginning of the routine to properly clear the background buffer and purge the component canvas, eliminating potential artifact ghosts or visual rendering anomalies.
Dynamic Viewport Boundary Scaling (g.drawImage):
- If a valid BufferedImage frame resides in the pipeline memory, the rendering engine triggers g.drawImage().
- It anchors the mapping source coordinates at the localized screen origin (0, 0). By supplying the dynamic runtime boundaries getWidth() and getHeight() into the layout matrix parameters, the client application ensures that the remote map grid stretches and conforms scaling matrices on the fly to perfectly snap fit into the container dimensions whenever window resizing triggers.

package com.honolulu.gis;

import javax.swing.*;
import java.awt.*;
import java.awt.image.BufferedImage;

public class MapPanel extends JPanel {

    private BufferedImage image;

    public void setImage(BufferedImage image) {
        this.image = image;
        repaint();
    }

    @Override
    protected void paintComponent(
            Graphics g) {

        super.paintComponent(g);

        if (image != null) {

            g.drawImage(
                    image,
                    0,
                    0,
                    getWidth(),
                    getHeight(),
                    null
            );
        }
    }
}

10.5. The `WmsLayerInfo` Class

The WmsLayerInfo component represents the lightweight data access model utilized to encapsulate the primary remote Web Map Service (WMS) layer specifications parsed from GeoServer.

Immutable Java Record Architecture:
- The class leverages the modern Java Record configuration framework. This design pattern intrinsically eliminates traditional boilerplates such as boilerplate explicit Accessors (Getters), equals(), hashCode(), and toString() generation blocks.
- By default, records evaluate fields as implicitly private final, enforcing complete object immutability that ensures thread safety and component integrity throughout the data stream workflow.
Metadata Fields Breakdown:
- namespace: Identifies the operational work domain workspace (e.g., "Honolulu"), facilitating smooth upstream filter streams and grouping transformations inside the tree panel component.
- name: Contains the raw, fully qualified canonical system identifier required by the remote GeoServer container to compile target map visuals within WMS URL parameters.
- title: Represents the localized, human-readable display string used for populating label text within the user interface graphical component tree views.

package com.honolulu.gis;

public record WmsLayerInfo(
        String namespace,
        String name,
        String title
) {
}

10.6. Build and Execution

You can now proceed with building and running the application by executing the following commands in the currently open Windows Command Prompt (cmd) window.

mvn clean package
mvn exec:java -Dexec.mainClass=com.honolulu.gis.Main

Once the application is running, you can use the developed WMS client to interactively view and inspect each geospatial dataset loaded into GeoServer, one layer at a time, as shown below.

11. Conclusion

In this post, we have briefly introduced how to load geospatial data into a map server and how to consume that loaded data via a Web Map Service (WMS). To transition this into a fully-featured, production-ready map service, various additional capabilities and advanced functionalities would need to be incorporated.

12. Download Links

Open JDK : https://jdk.java.net/java-se-ri/21
Maven Project : https://maven.apache.org/download.cgi
GeoServer Project :
- https://geoserver.org/download/
- https://sourceforge.net/projects/geoserver/files/GeoServer/2.28.4/
Honolulu GIS Data : https://honolulu-cchnl.opendata.arcgis.com

13. Trouble Shooting

In an intranet environment, you may need to recompile your project using Maven with the following flags to bypass SSL verification:

mvn clean compile -Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true

Alternatively, you can update the Java certificate chain. First, open the osgeo website in your browser and download its certificate (nexus.osgeo.org.crt). Then, run the following command to import it into your keystore:

keytool -importcert -keystore "C:\DEV\Works\MapService\jdk-21\lib\security\cacerts" -storepass changeit -file "C:\DEV\Works\MapService\MapClient\nexus.osgeo.org.crt" -alias osgeo_repo

14. Download the source code

The source code for this post is available for download. Keep in mind that the Object Detector App requires specific models and resources to run properly. You can download these essential model files and assets in Section 14: Resources below.

Download
You can download the app source code of this post here:
Simple Java Gis Map Service Client

Tags

OpenCV Android Object Detector

young.gon — Wed, 24 Jun 2026 09:44:28 +0000

Android Android Core Core Java Java

OpenCV Android Object Detector

This post will be the final chapter of my series on object detection since we have explored the possibility of detecting various objects within camera frames, tracing the journey from Java-based applications to our ultimate goal that implements a mobile app on android devices.

1. Introduction

2. Objectives

3. Android Development Setup

3.1. Development Tools Setup

4. Build OpenCV Samples

4.1. Extracting the OpenCV SDK

4.2. OpenCV Sample Configuration

4.3. Android Studio Configuration

5. OpenCV Inference Models

5.1. Object Inference Model Overview

6. Android Overview

6.1. Activity Lifecycle Stages

6.2. About AndroidManifest

6.3. Activity Lifecycle in Practice

7. Hello World App

7.1. Hello World Layouts

7.2. Creating Menu

8. Hello OpenCV App

8.1. Components and Resources

8.2. Hello OpenCV Layout

8.3. MyHelloOpenCVActivity

8.4. Results

9. Object Detector App

9.1. Camera Calibration Overview

9.2 My Object Detecor

9.3. Object Detection Process

9.4. The Role of DetectorNetData

9.5. Managing Model Life Cycle

9.6. DnnModelRepository

9.7. Interaction Flow

9.8. Object Detection Options

9.9. Final Results of Object Detector

10. Summary

11. References

12. Links

13. Download the source code

14. How to Download Models and Resources

1. Introduction

You have some insight what an object detector looks like and explored various detection models and those usage So far, I will focus on object detection specifically on the real Android mobile device.
Then, we will discuss how to adapt our existing object detector with minimal changes—rather than starting from scratch on Android system. For more context, you may refer to my previous articles on References part.

2. Objectives

My goal is to conduct a series of experiments to detect objects on mobile with various object detection models—such as Mask R-CNN, the YOLO series, and other state-of-the-art models—on actual mobile devices. When it comes to mobile development, we can consider the two major ecosystems: Android and iOS, I selected Android because it natively supports Java, our preferred language, allowing us to build a seamless environment..

The ultimate objective is to implement a standalone object detector using OpenCV Android. When I first began this project, OpenCV samples did not include a mobile-ready object detector. However, recent versions of OpenCV now provide samples integrated with MobileNet. Therefore, I have decided to use these official samples as a baseline for comparison with other models.

3. Android Development Setup

Before implementation of the android app, you must first configure your Android development environment if you haven’t already. Developing an Android app means it is a procedure to building an executable for the Android OS, while Google provides the base OS, various manufacturers—such as Samsung, Xiaomi, and Vivo—adapt it for their devices with specific drivers for components like Bluetooth, Wi-Fi, and GPS. To build apps for this ecosystem, you can download the necessary SDK from the Google Developers site.

There are several software languages available for Android development in which Kotlin is a popular choice, and its syntax is quite similar to Java, making it easy to learn for those with a Java background. (In my view, Kotlin’s rise was partly influenced by the long-standing legal disputes between Google and Oracle). While C/C++ and Python are also options, they can be more challenging to implement than Java or Kotlin. As emphasized throughout this series, I will be using Android Java. Not only is it my preferred language, but sticking with pure Java ensures consistency across all the articles we have covered so far.

3.1. Development Tools Setup

In this section, I will introduce the essential development tools and SDK required to build and run our object detection application on Android.

1. JDK (Java Development Kit)

Java Development Kit (JDK) is an essential tool as the foundation of Android Java and it is impossible to develop Android applications without it, so downloading and installing the JDK should be your first priority. Although Google now promotes Kotlin as the primary development language but Java still remains a fundamental pillar of the Android ecosystem.

For this project, I recommend using OpenJDK. You can download the compressed binaries from the official OpenJDK site. I will be using JDK 17 or higher to ensure compatibility with the latest Android build tools and libraries.

2. Android Studio

Android Studio is the free, standard IDE from Google, offering an intuitive and user-friendly GUI. While Eclipse was the primary tool when I first started, Android Studio has now become the undisputed mainstream choice for developers worldwide, providing a much more robust environment for building modern apps.

Another major benefit of developing with Android Studio is its seamless integration with the Android SDK. It bundles essential components, such as platform tools and build tools, directly within the IDE. This integrated approach allows us to save significant time and effort when setting up the development environment, letting us focus more on building the app itself.

3. Gradle

Building an Android application is a complex process that culminates in the creation of an APK (Android Package) file. This requires a robust build tool to manage everything from code compilation to final integration. While there are three major build tools available—Ant, Maven, and Gradle—I prefer using Gradle. It is the modern standard for Android development, offering the flexibility and power needed to streamline the entire build pipeline.

The Build Process with Gradle
By choosing Gradle as our build tool, we can efficiently manage the complex process of creating an Android app. The typical workflow consists of the following key stages:

Code Compilation: Converting Java or Kotlin source code into bytecode.
Resource Integration: Compiling and packaging app resources, such as images and XML layout files.
Dependency Management: Linking external libraries and frameworks (like OpenCV) as required.
Code Optimization & Obfuscation: Improving app performance and protecting the source code using tools like R8 or ProGuard.
Signing & Archiving: Digitally signing the application for security and packaging it into the final APK (or AAB) file for distribution.

Why We Use Gradle
As developers, it is technically possible to perform each of these complex steps manually. However, doing so is far more complicated and error-prone than using a dedicated build tool. Utilizing a standardized build process through a tool like Gradle is not just natural—it is essential for efficiency and consistency. For this project, we will be using Gradle version 8.9, the latest stable release at this time.

4. OpenCV Android SDK

We are building our object detector on the OpenCV library. The OpenCV Android SDK offers not only the core libraries but also various practical samples to jump-start your development. Ensure you download the latest version to take full advantage of current features and optimizations.

5. About Android Mobile Device

While you can use the emulator provided by the Android SDK (which can be downloaded and configured via Android Studio), I believe it is not sufficient for this project so I have decided to use a physical device for optimal performance and testing —specifically, a Galaxy Tab S8. Or It is possible to use your own Android phone or any other tablet for development.

Specifications of Galaxy Tab S8 (Reference Device):

Category	Specification
Model	Samsung Galaxy Tab S8 (Standard)
OS	Android 12 (Upgradable to 14+)
Processor (AP)	Qualcomm Snapdragon 8 Gen 1
Memory (RAM)	8 GB / 12 GB
Storage	128 GB / 256 GB (microSD up to 1TB)
Display	11-inch LTPS TFT (2560 x 1600), 120Hz
GPU	Adreno 730
NPU	7th Gen Qualcomm AI Engine

Please note that I assume your device is relatively modern. It is practically impossible to build an app that runs flawlessly on every version of Android ever released by providing the table below lists the specifications of my tablet. These are not necessarily the minimum requirements, but rather a reference for a high-performance setup. You should be able to follow the development process as long as your device is not outdated.

4. Build OpenCV Samples

This section, I will describe how to build OpenCV samples since you’ve downloaded all tools and SDK completely from previous section.

4.1. Extracting the OpenCV SDK

After downloading opencv-version-android-sdk.zip, extract its contents to a folder of your choice. Once extracted, you will see a directory structure similar to the one shown below:

sdk: It contains the Android library projects, Java helper classes, and native JNI libraries (.so files) required for your app.
samples: This directory provides various sample applications that demonstrate OpenCV’s capabilities, such as camera handling, image manipulation, and—most importantly for us—object detection.

The included samples are excellent resources for understanding how OpenCV code integrates and functions within the Android environment. By exploring these examples, you can gain practical insights into implementing computer vision features in a mobile context.

4.2. OpenCV Sample Configuration

Now that we have downloaded the OpenCV SDK and explored its contents, we are ready to begin Android mobile development. Before diving into our custom implementation, let’s look at how to build and run the provided samples using Android Studio. Testing these official examples ensures that your environment is correctly configured and gives you a functional baseline to work from.

1. Launching Android Studio

If you have followed the setup steps described above, you can now launch the IDE. Navigate to the installation directory and locate the 64-bit executable file, studio64.exe or studio.bat in the bin folder.

For example, based on our setup, the path should look like this:

~\android-studio\bin\studio64.exe
~\android-studio\bin\studio.bat

Double-click this file to start Android Studio and begin the project configuration.

2. SDK Components Setup

When you launch Android Studio for the first time, you will encounter a window titled “SDK Components Setup.” Fortunately, Android Studio automates the entire process—handling the download, configuration, and setup of the SDK and its components for us, as shown in the following screenshots:

3. Development Toolchain

We call the process of building software for a different architecture or OS ‘cross-compilation.’ Since Android relies on the Linux kernel, its applications inherently run within a Linux-based environment. To bridge the gap between our Windows development machines and the Android environment, we utilize a ‘Toolchain’.

4. OpenCV Sample Folder

Once the setup process described in the previous chapter is complete, the project selection window will appear then, In the window shown below, navigate to and select the samples folder within the extracted OpenCV SDK :

4.3. Android Studio Configuration

Set the JDK and Gradle versions we downloaded in the previous sections is first thing to do, before building. Setting these manually ensures that our build environment is consistent and stable.

Follow these steps to complete the configuration:

Crucially, verify that the Gradle JDK is set to version 17. This ensures compatibility between the build tool and your Java source code.
Navigate to: Settings > Build, Execution, Deployment > Build Tools > Gradle
In the “Build process” or “Gradle projects” section, look for the Gradle distribution options.
Choose “Specified location” (or local installation) from the drop-down menu and enter the path where you extracted the Gradle 8.9 binaries.

1. Exploring Sample Projects

With the configuration complete, you will now see a wide array of samples and examples —from basic camera preview to complex image processing filters — populated within the Android Studio project explorer that tells us these projects now “active,” meaning the IDE has recognized the Gradle files and linked the necessary OpenCV libraries.

On the official OpenCV site, there are available samples with description in which you can use these as a valuable reference throughout the development process:

2. Running Samples

You can build all these sample sources at a time by build, compile all sources at the menu of the android studio then, you simply select and run each of those samples with run button on the studio.

Those samples cover a wide range of functionalities, from basic camera access to advanced image processing techniques. Referring to them will help you understand the standard patterns for handling frame data and optimizing performance on mobile devices.

5. OpenCV Inference Models

Basically, Mask-RCNN or Yolo v3 model we’ve been developing through the windows system is not suitable choice on the android system so I have to investigate some proper models on mobile system because I intent to build such circumstance that figure differences among the current models used so far and proper models as an aspect of accuracy or performance.

5.1. Object Inference Model Overview

We newly choose MobileNet-SSD v3, Yolo v3 tiny and Yolo v7 tiny as a mobile model downloaded from internet without any modification or training it following table is description of each models :

Model Name	Description	Focus Area
Mask R-CNN / YOLOv3	High accuracy models used in our Windows environment.	Accuracy & Precision
MobileNet-SSD v3	Google’s efficient CNN architecture designed for mobile vision.	Efficiency & Low Power
YOLOv3-tiny	A simplified, faster version of YOLOv3 with fewer layers.	Speed & Latency
YOLOv7-tiny	An optimized version of the YOLOv7 series for edge devices.	Balanced Speed/Accuracy

1. Model Download

I am certain that you already have the Mask R-CNN and YOLOv3 models from the previous article. The table below lists the filenames and details for the remaining models. You can find these by searching the internet.

For the experimental purposes of this article, you are also free to download any related model files or use your own custom-trained models instead.

File Name	Location
frozen_inference_graph_ssd.pb ssd_mobilenet_v3_large_coco_2020_01_14.pbtxt	1. github.com/opencv/opencv/wiki/tensorflow-object-detection-api
yolov3-tiny.weights	1. github.com/pjreddie/darknet/issues/2483 2. pjreddie.com/media/files/yolov3-tiny.weights
yolov7-tiny.weights	1.github.com/WongKinYiu/yolov7/releases/tag/v0.1

2. Inference Parameters

The OpenCV library provides the blobFromImage() method, which is essential for preprocessing images or video frames into “blobs” that our object detection app can process. To ensure accurate results, this method requires specific inference parameters—such as scale factor, size, and mean subtraction—which vary significantly depending on the architecture of the model being used.

The following table details the specific configurations for the blobFromImage() method when using MobileNet-SSD, YOLO, and Mask R-CNN models:

Model Name	Size	Scale Factor	Mean Value
MobileNet-SSD	(512, 512)	1.0 / 127.5	Scalar(127.5, 127.5, 127.5)
YOLO v3 / v7 Tiny	(416, 416)	1.0 / 255.0	Scalar(0, 0, 0)
Mask R-CNN	(800, 800)	1.0	Scalar(0, 0, 0)

3. Performance Uncertainty

At this stage, I am not entirely certain whether the heavier models, like Mask R-CNN and YOLOv3, will function properly on a mobile device. Similarly, the actual performance of the more lightweight options, such as MobileNet-SSD and the Tiny YOLO variants, remains to be seen in a real-world Android environment.

This uncertainty is exactly why we are conducting these tests—to determine which models are truly viable for mobile object detection.

6. Android Overview

The Activity class is the fundamental component used to develop an Android application before we proceed, it is essential to understand some basic Android GUI concepts. Every Android app operates by inheriting from a child class of the Activity class.

This class follows six main lifecycle stages, which define how the GUI components are internally created, initialized, and eventually destroyed.

For example, rotating your device from landscape to portrait mode changes the screen orientation naturally, but it triggers the Android system to destroy and recreate the activity behind the scenes.

This means Android completely shuts down the current instance of your activity and starts a fresh one to accommodate the new screen dimensions. Understanding this behavior is crucial because it dictates how we manage data and resources—such as our camera feed and object detection models—preventing unnecessary loss or reloads during a rotation.

6.1. Activity Lifecycle Stages

Generally speaking, the Android app lifecycle consists of six main stages.

1. onCreate()

Initial Setup: Called when the activity is first created. This is where you perform the basic application startup logic that should occur only once.
UI Binding: Responsible for connecting XML layout resources to the Activity and handling class instantiation.
Interaction Status: At this stage, the activity is not yet able to interact with the user.

2. onStart()

Visibility: Invoked as the activity becomes visible to the user, preparing it to enter the foreground.
App Restart: This method is also called when the app is being restarted after having been stopped.
Interaction Status: Although the UI is visible at this stage, the activity is not yet able to interact with the user.

3. onResume()

Active Status: Called when the activity starts interacting with the user. At this stage, the app is in the foreground and fully active.
Foreground Entry: This method is invoked once the activity moves to the foreground.
Interaction Status: The activity is now completely able to interact with the user.

4. onPause()

System Transition: Triggered when the system is about to resume a previous activity or start a new one.
Partial Obstruction: This method is called when another activity partially covers the current activity (e.g., a semi-transparent dialog or a multi-window mode).
Resource Management: It is primarily used to pause ongoing actions that should not continue in the background, such as animations, video playback, or camera previews.

5. onStop()

Visibility: Executed when the activity is no longer visible to the user.
User Interaction: This method is called when the activity has disappeared from view, typically because another activity has taken over the full screen or the user has navigated back to the home screen.
Resource Management: Any resources that are not needed while the user is not seeing the app should be released at this stage to save system memory and power.

6. onDestroy()

Final Call: This is the final call received before the activity is destroyed.
Destruction Scenarios: It can occur either because the activity is finishing (e.g., the user presses the ‘Back’ button or finish() is called) or because the system is temporarily destroying the instance to recover valuable memory space.
Termination: This method is invoked when the activity is being permanently removed or killed by either the system or the user.

6.2. About AndroidManifest

The following table summarizes the essential features and components defined within the AndroidManifest.xml file:

Feature	Description	Core Components
Component Declaration	Registers the four essential building blocks of the Android system.	Activity: UI screens. Service: Background tasks. Receiver: System signals (e.g., Boot, Battery). Provider: Data sharing.
Permission Management	Defines explicit permissions required to access sensitive device data or features.	Permissions: `INTERNET`, `CAMERA`, `ACCESS_FINE_LOCATION`, etc.
Basic Information Setup	Configures the app’s identity and visual presence on the system and Play Store.	Package Name: Unique App ID. Icon & Label: Home screen visuals. Theme: Global design style.
Hardware/Software Requirements	Specifies the minimum conditions necessary for the app to be installed and run correctly.	SDK Versions: Min/Target compatibility. Uses-feature: e.g., `<uses-feature android:name="android.hardware.location.gps" />` prevents installation on devices without GPS.

1. Intent-filter

The following definitions are included within the intent-filter element:

File Association: Ensures our app is automatically executed when a user opens a specific file type, such as .pdf or .doc files.”

<activity android:name=".FileViewerActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="application/pdf" />
    </intent-filter>
</activity>

Launcher: Designates which screen should be the initial entry point (the first screen to start) among multiple activities.

<activity
	android:name=".MyHelloWorldActivity"
	android:exported="true">
	<intent-filter>
		<action android:name="android.intent.action.MAIN" />
		<category android:name="android.intent.category.LAUNCHER" />
	</intent-filter>
</activity>

6.3. Activity Lifecycle in Practice

As a result, an app continuously iterates through these stages—from creation to destruction—driven by the lifecycle events. We can categorize the order of these method calls based on common user actions, as shown in the table below:

User action	Lifecycle Methods Called (In Order)
Launch the app	`onCreate()` → `onStart()` → `onResume()`
Press the Home button	`onPause()` → `onStop()`
Return to the app (from Home)	`onRestart()` → `onStart()` → `onResume()`
Press the Back button	`onPause()` → `onStop()` → `onDestroy()`
Screen Rotation (Orientation Change)	`onPause()` → `onStop()` → `onDestroy()` → `onCreate()` → `onStart()` → `onResume()`
Dialog/Popup appears (partially covers)	`onPause()`

In the following sections, we will build a simple application using Android Java, integrating it with the OpenCV Android SDK.

If you are already experienced with Android programming and familiar with its core concepts, you may choose to skip these introductory sections and proceed directly to the implementation details. However, for those new to the platform, these steps will provide a necessary foundation for the object detection tasks ahead.

7. Hello World App

This article is not intended for absolute beginners. I assume you already have a fundamental understanding of what an Android app is and are familiar with running tests on the Android SDK emulator. However, it is still essential to understand how to set up a basic “Hello World” project within the context of our specialized environment.

Rather than starting from a blank template, we will work with a simple “Hello World” example found within the OpenCV samples folder. To get started, you will need to create a new module for the application:

Path: File > New > New Module

1. Configuring the New Module

Next, you need to fill in the attributes in the New Module setup dialog as follows. These settings ensure that your new module is correctly initialized within your project structure:

Application Name	My Hello World
Module name	myhelloworld
Package name	com.example.myhelloworld
Language	Java
Minimum SDK	API 26
Build Configuration Language	Groovy DSL (build.gradle)

2. Activity Template

Android Studio provides multiple activity styles, each offering different pre-configured features. For this project, we will focus on a simple activity creation process.

However, you should select “No Activity” from the template list. This is a critical step because the latest activity templates provided by Android Studio are based on AndroidX, which often features library versions and structures that do not match the older OpenCV sample configurations. By starting with “No Activity,” we can manually set up the component to ensure full compatibility with the OpenCV Android SDK.

7.1. Hello World Layouts

Now that the new app module, myhelloworld, has been created, we need to add the functional source code. We will implement an Option Menu that allows users to interact with the app. When a user selects an item from the menu, the text on the screen will update instantly to reflect their choice.

1. Defining the User Interface

The application screen will consist of a simple layout (typically a TextView) that serves as the primary display for our app’s status and the results of user actions.

2. Adding the Option Menu

The Option Menu is a key GUI component in Android. We will override two essential methods in our Activity class:

onCreateOptionsMenu(): To inflate the menu resource and display it in the app bar.
onOptionsItemSelected(): To handle the logic that changes the screen text based on which menu item the user clicks.

3. Expected Behavior

This exercise demonstrates the basic flow of an Android app:

The app initializes (Lifecycle: onCreate).
The user interacts with the GUI (Option Menu).
The app responds by updating the UI components in real-time.

To implement the app, we need an activity and related resources the table as describe as follows:

File Name	Resource Type	Description
MyHelloWorldActivity.java	Activity (Java)	Main Logic: Handles lifecycle events and the logic for updating the UI based on menu interactions.
AndroidManifest.xml	Manifest (XML)	Registration: Declares the activity to the Android system so it can be recognized and launched.
activity_main.xml	Layout (XML)	UI Structure: Defines the placement of the `TextView` and other visual elements.
option_menu.xml	Menu (XML)	Interaction Points: Defines the individual items and icons available in the Option Menu.

4. Common Resource Folders

In Android development, all non-code assets— such as images, layouts, and menus—are stored in the res (resource) folder. The primary goal of this folder is to optimize resources for various screen sizes, languages, and device settings automatically. Instead of writing code to handle different environments, you provide alternative resources in specifically named folders, and the Android system selects the most appropriate one at runtime.

Below are the standard folder names used within the res directory and their descriptions:

Folder Name	Description	Files
`drawable`	Contains bitmaps (PNG, JPEG), vector graphics, or XML-defined shapes and states.	`ic_launcher.png`, `button_background.xml`
`layout`	Defines the visual structure of the user interface (UI) for different screen orientations or sizes.	`activity_main.xml`, `list_item.xml`
`menu`	Defines the structure and items for options menus, context menus, or popup menus.	`main_menu.xml`
`values`	Stores XML files for strings, colors, integers, and dimensions to support localization and theming.	`strings.xml`, `colors.xml`, `styles.xml`
`mipmap`	Specifically used for application launcher icons to ensure they look sharp across different pixel densities.	`ic_launcher_round.png`
`raw`	For assets like video or audio clips that should be saved in their raw form without XML compilation.	`sample_video.mp4`, `custom_font.ttf`

7.2. Creating Menu

Since we started with a “No Activity” template, the project structure is currently empty. Android Studio has not generated any default resource files for us. To implement our Option Menu, we must first manually create the appropriate directory within the res folder.

Step-by-Step Guide:

Locate the Resource Folder: In the Project window, find and right-click on the res folder.
Create Directory: Select New > Directory.
Naming: Type menu as the directory name and press Enter.

1. Generating Menu Resource

Now that the menu directory is ready, you can create the actual XML file that will define your menu items.

Step-by-Step Guide:

Select the Directory: Right-click on the newly created menu folder.
Create New File: Select New > Menu Resource File.
Naming: In the File name field, type option_menu.
Completion: Click OK.

Once finished, you will see the option_menu.xml file appear inside the res/menu/ directory.

2. Menu on Palette View

Now, instead of writing raw XML, you can utilize the Palette View in Android Studio to visually design your menu. This drag-and-drop interface is highly efficient for quickly prototyping the user interface.

The visual actions you performed in the Palette are translated into the following XML structure. Each tag represents a specific option in your menu.

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    
    <item
        android:id="@+id/option_my_name"
        android:title="My Hello World Activity"
        app:showAsAction="never" />
        
    <item
        android:id="@+id/option_greeting"
        android:title="Greeting My Hello World"
        app:showAsAction="never" />
</menu>

3. Menu Layout

This means you have created both the ‘My Hello World Activity’ and the ‘Greeting My Hello World’ messages, allowing the screen text to change dynamically whenever a user selects an option from the menu. The final result is as follows:

Once the option menu is created, you need a layout to which the menu will be attached before the main activity is finalized. The next step is to create the main layout. In Android Studio,

select New > Layout Resource File to generate the layout file for your activity.

In the New Layout Resource File dialog, enter activity_main.xml as the file name and set RelativeLayout as the root element. RelativeLayout is one of the standard layout managers provided by Google; for more detailed information, you can refer to Google’s official Android Developer documentation.

Click OK to create the empty layout. You can then find the activity_main.xml file under the res/layout folder, initialized with the RelativeLayout as its root element.

We need a TextView to display the text that changes based on the user’s selection. The TextView’s content can be updated via a listener or logic that responds to component actions. You can find more details regarding the various attributes of this class on Google’s official Android Developer site.

<TextView
	android:id="@+id/statusTextView"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:layout_centerInParent="true"
	android:text="My Hello World Activity"
	android:textSize="24sp"
	android:textColor="#000000" />

At this point, we have an app where the on-screen text changes based on user menu selections, utilizing option_menu.xml and activity_main.xml. Finally, we need to define and manage our activities by configuring the AndroidManifest.xml, which serves as the formal specification of the app.

4. AndroidManifest

The Android system automatically recognizes the AndroidManifest.xml file, reads its contents, and executes the appropriate activity to launch the application. The following source code demonstrates how this specification is structured:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myhelloworld">

    <application
        android:allowBackup="true"
        android:icon="@drawable/icon"
        android:label="My App"
        android:theme="@style/Theme.AppCompat.Light.DarkActionBar">

        <activity
            android:name=".MyHelloWorldActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>
</manifest>

7. MyHelloWorldActivity

Now, let’s implement the logic for the Activity to handle user interactions and bridge the resources and layouts we have created. To begin, select New > Java Class from the menu and name the class ‘MyHelloWorldActivity’.

The complete source code for ‘MyHelloWorldActivity’ is provided below, demonstrating how to integrate the layout, handle menu selections, and update the UI dynamically:

package com.example.myhelloworld;

import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.view.Menu;
import android.view.MenuInflater;
import android.view.MenuItem;
import android.widget.TextView;

public class MyHelloWorldActivity extends AppCompatActivity {

    // Declare a TextView variable to handle dynamic text updates.
    private TextView statusTextView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Link the activity_main.xml layout to this Activity.
        setContentView(R.layout.activity_main);

        // Initialize the TextView by linking it to its corresponding ID defined in the XML.
        statusTextView = (TextView) findViewById(R.id.statusTextView);
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.option_menu, menu);
        return true;
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        int id = item.getItemId();

        if (id == R.id.option_my_name) {
            statusTextView.setText("Selected: My name is OpenCV!");
            return true;
        }

        if (id == R.id.option_greeting) {
            statusTextView.setText("Selected: Nice to meet you!");
            return true;
        }

        return super.onOptionsItemSelected(item);
    }
}

In the source code, two key methods handle the user interface setup: onCreate(), which initializes the main activity, and onCreateOptionsMenu(), which populates the GUI with the options menu.

The setContentView() method is called within onCreate() to inflate and display the activity_main.xml layout file.

@Override
protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	// Link the activity_main.xml layout to this Activity.
	setContentView(R.layout.activity_main);
	// Initialize the TextView by linking it to its corresponding ID defined in the XML.
	statusTextView = (TextView) findViewById(R.id.statusTextView);
}

Inside onCreateOptionsMenu(), we populate the menu by calling the inflate() method of the MenuInflater, which links the option_menu.xml resource to the Activity’s menu bar

@Override
public boolean onCreateOptionsMenu(Menu menu) {
	MenuInflater inflater = getMenuInflater();
	inflater.inflate(R.menu.option_menu, menu);
	return true;
}

In the onOptionsItemSelected() method, we define the logic to update the text on the screen whenever a user selects an item from the options menu.

@Override
public boolean onOptionsItemSelected(MenuItem item) {
	int id = item.getItemId();

	if (id == R.id.option_my_name) {
		// Display the string when the user selects 'option_my_name'
		statusTextView.setText("Selected: My name is OpenCV!");
		return true;
	}

	if (id == R.id.option_greeting) {
		// Display the string when the user selects 'option_greeting'
		statusTextView.setText("Selected: Nice to meet you!");
		return true;
	}

	return super.onOptionsItemSelected(item);
}

Using Android Studio, you can build and launch your ‘Hello World’ app directly on a physical device. Once running, your results should match the interface shown in the following image:

So far, we have explored the fundamental relationship between Activities and GUI components in Android. In the next section, we will build upon this foundation to create our own custom OpenCV samples, integrating computer vision capabilities into our mobile environment.

8. Hello OpenCV App

In the previous section, we built a simple ‘Hello World’ app. However, developing an application for object detection using the OpenCV library requires a more specialized approach.

Utilizing OpenCV as a vision library allows us to manipulate and manage image sources via camera functions. The goal of this section is to create a simple camera application where you can process live image sources using OpenCV methods and callbacks. Before we begin processing frames, our application must first obtain the necessary Camera Permissions by declaring them in the AndroidManifest.xml file.

8.1. Components and Resources

While the development process follows a similar workflow to the ‘Hello World’ app, we will introduce several new classes and resources specific to OpenCV integration. The following list outlines the Project components and resources we are about to implement:

Category	File Name	Description
Source code(Java)	MyHelloOpenCVActivity.java	The primary Activity class that manages OpenCV initialization and updates the UI with specific messages based on the user’s menu selections.
Manifest File	AndroidManifest.xml	The essential configuration file that defines app components and declares the required hardware permissions, such as Camera access.
Layout File	activity_main.xml	The XML definition of the user interface, acting as the container for both the camera view and UI elements.
Menu File	option_menu.xml	Defines the interactive menu items that allow the user to trigger different OpenCV processing modes or messages.
String Resource File	string.xml	A centralized resource file for managing all text constants, ensuring clean separation between logic and UI content.

8.2. Hello OpenCV Layout

In our layout, we use a LinearLayout as the root container. The focal point of this layout is the JavaCameraView class, which is provided by the OpenCV Android SDK. As the name suggests, JavaCameraView is a specialized view that inherits from android.view.SurfaceView, designed specifically to handle real-time camera frames efficiently.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:opencv="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent" >

    <org.opencv.android.JavaCameraView
        android:layout_width="fill_parent"
        android:layout_height="fill_parent"
        android:id="@+id/camera_java_surface_view" />

</LinearLayout>

You can visualize the GUI design and layout structure directly within the Palette and Design views of the Android Studio Layout Editor.

1. Menu Layout

The menu structure in this section is more advanced than our previous example. We utilize the element with the android:checkableBehavior=”single” attribute, ensuring that the user can only select one option at a time—similar to a radio button interaction.

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <group android:checkableBehavior="single">
        <item
            android:id="@+id/hellocv"
            android:showAsAction="ifRoom|withText"
            android:title="@string/cv_message" />
        <item
            android:id="@+id/hellocv_title"
            android:title="@string/normal">
            <menu>
                <group android:checkableBehavior="single">
                    <item android:id="@+id/normal_message"
                        android:title="@string/normal"
                        android:checked="true" />
                    <item android:id="@+id/cv_message1"
                        android:title="@string/cv_message1"/>
                    <item android:id="@+id/cv_message2"
                        android:title="@string/cv_message2" />
                </group>
            </menu>
        </item>
    </group>

</menu>

2. String Resource

Starting with ‘@’ symbol is a special identifier called “Resource Reference” that you can access a string from the other resource or file by the id and this time, string.xml file.

In the strings.xml file, you define string resources associated with unique IDs. These IDs serve as references that allow the system to dynamically substitute the appropriate text based on varying conditions, such as the device’s language settings or specific app states.

<resources>
    <string name="app_name">My Hello OpenCV</string>
    <string name="title_hellocv">Welcome to the OpenCV World</string>
    <string name="mode_default">normal mode</string>
    <string name="normal">normal message</string>
    <string name="cv_message1">cv message_1</string>
    <string name="cv_message2">cv message_2</string>
    <string name="message1">Welcome to the OpenCV World</string>
    <string name="message2">Hello from the OpenCV World</string>
    <string name="message3">Greetings from the OpenCV World</string>
</resources>

3. Android Manifest

The AndroidManifest.xml file defines the entry point of the application. By placing the <intent-filter> element within the declaration for MyHelloOpenCVActivity, we designate this class as the main activity that launches when the user opens the app.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myhelloopencv">

    <application
        android:allowBackup="true"
        android:icon="@drawable/icon"
        android:label="My App">

        <activity
            android:name="MyHelloOpenCVActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>

    <uses-permission android:name="android.permission.CAMERA"/>

    <uses-feature android:name="android.hardware.camera" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.front" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.front.autofocus" android:required="false"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

</manifest>

It is crucial to define the <uses-permission> element carefully, as it informs the Android system and the user which protected features the app needs to access. By specifying a permission name—such as android.permission.WRITE_EXTERNAL_STORAGE—the application explicitly requests the necessary rights to perform sensitive operations, like saving files to the device’s storage

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA"/>
    <uses-feature android:name="android.hardware.camera" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.front" android:required="false"/>
    <uses-feature android:name="android.hardware.camera.front.autofocus" android:required="false"/>

While we use the <uses-permission> element to request authorization from the Android system to access sensitive data or hardware, we can further refine our app’s requirements using the <uses-feature> element. In this project, we explicitly request permissions for both Camera and External Storage. By declaring these, we ensure the app has the necessary environment to capture and process images while also being able to save or load data as needed.

8.3. MyHelloOpenCVActivity

The main class, MyHelloOpenCVActivity, extends CameraActivity. Note that CameraActivity itself is a specialized class provided by the OpenCV Android SDK, which inherits from the standard Android Activity class to provide built-in management for camera lifecycle and permissions.

package com.example.myhelloopencv;

import android.os.Bundle;
import android.util.Log;
import android.view.Menu;
import android.view.MenuItem;
import android.view.SurfaceView;
import android.view.WindowManager;
import android.widget.Toast;

import org.opencv.android.CameraActivity;
import org.opencv.android.CameraBridgeViewBase;
import org.opencv.android.OpenCVLoader;
import org.opencv.core.Mat;
import org.opencv.core.Point;
import org.opencv.core.Scalar;
import org.opencv.imgproc.Imgproc;

import java.util.Collections;
import java.util.List;

public class MyHelloOpenCVActivity extends CameraActivity implements CameraBridgeViewBase.CvCameraViewListener2 {
    private static final String TAG = "CVSample::Activity";
    private CameraBridgeViewBase mOpenCvCameraView;

    private static String mLabelMessage ;
    private static  double mCenterX, mCenterY;

    public MyHelloOpenCVActivity() {
        Log.i(TAG, "Instantiated new " + this.getClass());
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        Log.i(TAG, "called onCreate");
        super.onCreate(savedInstanceState);

        //! [ocv_loader_init]
        if (OpenCVLoader.initLocal()) {
            Log.i(TAG, "OpenCV loaded successfully");
        } else {
            Log.e(TAG, "OpenCV initialization failed!");
            (Toast.makeText(this, "OpenCV initialization failed!", Toast.LENGTH_LONG)).show();
            return;
        }
        //! [ocv_loader_init]

        //! [keep_screen]
        getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
        //! [keep_screen]

        setContentView(R.layout.activity_main);

        mOpenCvCameraView = (CameraBridgeViewBase) findViewById(R.id.camera_hellocv_java_surface_view);

        mOpenCvCameraView.setVisibility(SurfaceView.VISIBLE);

        mOpenCvCameraView.setCvCameraViewListener(this);
    }

    @Override
    public void onPause()
    {
        super.onPause();
        if (mOpenCvCameraView != null)
            mOpenCvCameraView.disableView();
    }

    @Override
    public void onResume()
    {
        super.onResume();
        if (mOpenCvCameraView != null)
            mOpenCvCameraView.enableView();
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        if (mOpenCvCameraView != null)
            mOpenCvCameraView.disableView();
    }

    @Override
    protected List<? extends CameraBridgeViewBase> getCameraViewList() {
        return Collections.singletonList(mOpenCvCameraView);
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        super.onCreateOptionsMenu(menu);
        getMenuInflater().inflate(R.menu.option_menu, menu);
        return true;
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        boolean retBool;

        int id = item.getItemId();
        if(id == R.id.normal_message)
        {
            mLabelMessage = "[Normal message]" + getString(R.string.message1);
            item.setChecked(true);
            retBool = true;
        }
        else if(id == R.id.cv_message1)
        {
            mLabelMessage = "[CV message1]" + getResources().getString(R.string.message2);
            item.setChecked(true);
            retBool = true;
        }
        else if(id == R.id.cv_message2)
        {
            mLabelMessage = "[CV message2]" + getResources().getString(R.string.message3);
            item.setChecked(true);
            retBool = true;
        }
        else
        {
            retBool = super.onOptionsItemSelected(item);
        }
        return retBool;
    }

    @Override
    public void onCameraViewStarted(int width, int height) {
        mCenterX =  (double) width /2;
        mCenterY =  (double) height /2;
    }

    @Override
    public void onCameraViewStopped() {

    }

    @Override
    public Mat onCameraFrame(CameraBridgeViewBase.CvCameraViewFrame inputFrame) {
        Mat matFrame = inputFrame.rgba();

        if(mLabelMessage != null)
        {
            Imgproc.putText(matFrame, mLabelMessage, new Point(mCenterX/4, mCenterY), Imgproc.FONT_HERSHEY_SIMPLEX, 2.2, new Scalar(0, 0, 0), 4);
            return matFrame;
        }
        else
            return  inputFrame.rgba();
    }
}

The core of our implementation focuses on the CameraBridgeViewBase.CvCameraViewListener2 interface. To handle the camera feed and process image data, we must implement the following three mandatory methods:

public interface CvCameraViewListener2 {
	public void onCameraViewStarted(int width, int height);
	public void onCameraViewStopped();
	public Mat onCameraFrame(CvCameraViewFrame inputFrame);
};

The naming convention of these methods is quite intuitive. For instance, onCameraViewStarted is triggered as soon as the camera function is activated. Conversely, when the camera is deactivated or the activity is destroyed, onCameraViewStopped is invoked to handle the shutdown. Finally, onCameraFrame is called continuously, frame-by-frame, during the camera’s active state. This entire lifecycle procedure is managed within the MyHelloOpenCVActivity class.

Define the CameraBridgeViewBase Class.
Attach the View during the onCreate() call.
Activate the Listener via setCvCameraViewListener().

public class MyHelloOpenCVActivity extends CameraActivity implements CameraBridgeViewBase.CvCameraViewListener2 {
    
    private CameraBridgeViewBase mOpenCvCameraView;

    ...

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ...
        mOpenCvCameraView = (CameraBridgeViewBase) findViewById(R.id.camera_hellocv_java_surface_view);

        mOpenCvCameraView.setVisibility(SurfaceView.VISIBLE);

        mOpenCvCameraView.setCvCameraViewListener(this);
    }

The instance of CameraBridgeViewBase must be strictly managed in synchronization with the lifecycle of MyHelloOpenCVActivity. Since the camera is a shared hardware resource, failing to pause or release it correctly when the activity moves to the background can lead to memory leaks, app crashes, or the inability for other applications to access the camera.

private CameraBridgeViewBase mOpenCvCameraView;

...


@Override
protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);

	...
	mOpenCvCameraView = (CameraBridgeViewBase) findViewById(R.id.camera_hellocv_java_surface_view);
}

@Override
public void onPause()
{
	super.onPause();
	if (mOpenCvCameraView != null)
		mOpenCvCameraView.disableView();
}

@Override
public void onResume()
{
	super.onResume();
	if (mOpenCvCameraView != null)
		mOpenCvCameraView.enableView();
}

@Override
public void onDestroy() {
	super.onDestroy();
	if (mOpenCvCameraView != null)
		mOpenCvCameraView.disableView();
}

8.4. Results

As the final result of our ‘Hello World’ OpenCV implementation, the GUI demonstrates a key distinction in how data is rendered. While the previous section focused on updating a standard TextView based on user selection, this final stage utilizes OpenCV to draw messages directly onto the camera frames. By manipulating the image matrix, the application overlays real-time information onto the video stream, showcasing the fundamental power of computer vision GUI processing.

In the next section, we will explore the various samples provided within the OpenCV Android SDK. Our goal is to identify a suitable reference project that can serve as a robust foundation or a functional substitute for our object inference application.

9. Object Detector App

Since we have already mastered building and deploying the OpenCV SDK samples onto Android devices, we can now evaluate which sample provides the best architecture for our Object Inference App. To ensure a seamless user experience, we have defined two key functional requirements:

Model Selection via Dynamic Menu: The application must feature a fixed menu with a drop-down list, allowing users to switch between different inference models (e.g., YOLO, Mask R-CNN, or MobileNet) on the fly.
Instantaneous Inference: Object detection must trigger immediately upon model selection, ensuring that the onCameraFrame logic begins processing the live feed using the newly loaded weights without requiring an app restart.

9.1. Camera Calibration Overview

The basic is done—how to build and run a simple app and a simple OpenCV app. It means we are now ready to make an app for object detection on a real Android device.

But at some point, we doubt that we must start from scratch—designing and building sources, layouts, and resources. This would spend too much time focusing on supplementary parts that are not even part of object detection.

Therefore, we are going to follow the simple way: building our app by customizing the samples provided by OpenCV that are already proven in practice. These are the conditions that meet our requirements:

Display bounding boxes when objects are detected.
Select any model from the menu.
Load a model into memory.
Render frame by frame if the camera is ready.
Recognize objects in the image source of the frame.

1. Class Diagram and Workflow

Our object detection diagram will be similar to the camera-calibration class diagram. In the case of camera calibration, the steps are:

Render an image source frame-by-frame when the camera is ready.
Run calibration on that image source continuously at the same time.

Based on this logic, we expect the calibration sample to cover our required functionalities:

Renders the image source when the camera is available.
Allows the user to select a model from the available options.
Triggers different behaviors depending on the selected option.
Detects objects in the image source using the selected inference model.

9.2 My Object Detecor

Our object detector, named my-object-detector, is designed to detect objects by separating them from the background and labeling the upper part of each detected object. This implementation is based on the source code of the camera-calibration sample.

1. Initial Version Setup

To begin, we need to isolate our project within the OpenCV SDK environment. Navigate to the samples folder: C:\DEV\Works\opencv-object-detector\OpenCV-android-sdk\samples

In Android Studio, open the settings.gradle file from the Project Files view. To focus exclusively on our app, disable all other sample projects by commenting out their include tags and add our project as follows:

rootProject.name = 'opencv_samples'
gradle.ext {
    // possible options: 'maven_central', 'maven_local', 'sdk_path'
    opencv_source = 'sdk_path'
}

if (gradle.opencv_source == 'maven_local') {
    gradle.ext {
        opencv_maven_path = '<path_to_maven_repo>'
    }
}

if (gradle.opencv_source == 'sdk_path') {
    def opencvsdk = '../'
    //def opencvsdk='/<path to OpenCV-android-sdk>'
    //println opencvsdk
    include ':opencv'
    project(':opencv').projectDir = new File(opencvsdk + '/sdk')
}
include ':my-object-detector'
//include ':15-puzzle'
//include ':face-detection'
//include ':qr-detection'
//include ':image-manipulations'
//include ':camera-calibration'
//include ':color-blob-detection'
//include ':mobilenet-objdetect'
//include ':video-recorder'
//include ':tutorial-1-camerapreview'
//include ':tutorial-2-mixedprocessing'
//include ':tutorial-3-cameracontrol'
//include ':tutorial-4-opencl'

2. Project Copy & Strategy Pattern

Next, copy the camera-calibration project to create my-object-detector.

Our custom object detector implements the Strategy Pattern. This helps the object detection via OnCameraFrameRender, which is implemented by the FrameRender abstract class.

public class OnCameraFrameRender {
    private final FrameRender mFrameRender;
    public OnCameraFrameRender(FrameRender frameRender) {
        mFrameRender = frameRender;
    }
    public Mat render(CvCameraViewFrame inputFrame) {
        return mFrameRender.render(inputFrame);
    }
}

3. Executing the Strategy

The system calls the render method of the concrete strategy class, passing the CvCameraViewFrame provided by OpenCV as the camera input.

For example, we can implement a Yolov3FrameRender class. Inside its render method, it utilizes a Yolov3Detector class to perform object inference using the CvCameraViewFrame object received from the camera input.

public Mat render(CameraBridgeViewBase.CvCameraViewFrame inputFrame) {
	Mat bgrFrame = inputFrame.rgba();

	Imgproc.cvtColor(bgrFrame, bgrFrame, Imgproc.COLOR_RGBA2BGR);
	Yolov3Detector.getInstance().setDetectorNet(mDetectorData);

	return Yolov3Detector.getInstance().detectObjectByYolov3(bgrFrame);
}

4. Class Diagram

Inspired by the calibration app, this class diagram illustrates the architecture of our mobile detector. The system invokes the appropriate object inference model by calling specific renderers based on user options. Each renderer then executes the inference model in memory and draws bounding boxes directly onto the main activity screen.

My concept of the Object Detector is as follows:

ObjectDetectionActivity extends CameraActivity and manages the user interaction GUI.
The application instantiates the render classes, which stand ready within OnCameraFrameRender.
This render loop receives DetectorNetData via its constructor, which in turn initializes and saves the detector classes using DnnModelRepository.
Whenever the FrameRender class invokes render(), the system seamlessly matches the user’s selected model with the proper detector class to execute object detection.

5. ObjectDetectionActivity

ObjectDetectionActivity serves as our main activity, handling user interactions and ultimately rendering the bounding boxes predicted by the object inference model. Consequently, the skeleton of this class must implement the CvCameraViewListener2 interface, as shown below:

public class ObjectDetectionActivity extends CameraActivity implements CvCameraViewListener2 {
    @Override
    public void onCreate(Bundle savedInstanceState) {
   
    }

    @Override
    public void onPause()
    {
    }

    @Override
    public void onResume()
    {
    }

    @Override
    protected List<? extends CameraBridgeViewBase> getCameraViewList() {
        return Collections.singletonList(mOpenCvCameraView);
    }

    public void onDestroy() {
        
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        return true;
    }

    @Override
    public boolean onPrepareOptionsMenu (Menu menu) {
        return true;
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        
        return true;
    }

    @Override
    public void onCameraViewStarted(int width, int height) {
    }

    @Override
    public void onCameraViewStopped() {
    }

    @Override
    public Mat onCameraFrame(CvCameraViewFrame inputFrame) {
    }

    @Override
    public boolean onTouch(View v, MotionEvent event) {
        return false;
    }
}

Our ObjectDetectionActivity class must implement the three methods of the CvCameraViewListener2 interface. These methods are triggered by callbacks from the CameraActivity class after it has internally handled essential pre-processing tasks, such as:

Converting Image Sources: Transforming the raw camera feed into a CvCameraViewFrame object for OpenCV processing.

Requesting Permissions: Ensuring the app has the necessary camera access.
Preparing Camera Conditions: Setting up the hardware, resolution, and focus.

public interface CvCameraViewListener2 {
	/**
	 * This method is invoked when camera preview has started. After this method is invoked
	 * the frames will start to be delivered to client via the onCameraFrame() callback.
	 * @param width -  the width of the frames that will be delivered
	 * @param height - the height of the frames that will be delivered
	 */
	public void onCameraViewStarted(int width, int height);

	/**
	 * This method is invoked when camera preview has been stopped for some reason.
	 * No frames will be delivered via onCameraFrame() callback after this method is called.
	 */
	public void onCameraViewStopped();

	/**
	 * This method is invoked when delivery of the frame needs to be done.
	 * The returned values - is a modified frame which needs to be displayed on the screen.
	 * TODO: pass the parameters specifying the format of the frame (BPP, YUV or RGB and etc)
	 */
	public Mat onCameraFrame(CvCameraViewFrame inputFrame);
};

9.3. Object Detection Process

The object detection workflow in our application follows a structured sequence to ensure real-time performance:

Result Rendering: The detected objects (bounding boxes and labels) are rendered on the screen.app, the CameraBridgeViewBase class of OpenCV can do for us by just calling enableView().

Camera Activation: The camera view must be active as soon as the app starts.
Model Selection: The user chooses a specific object detection model from the menu
Memory Loading: The selected model is loaded into memory to prepare for inference.
Real-time Inference: Object inference is executed frame-by-frame using the loaded model.

To ensure the camera activates automatically whenever the app runs, we utilize the CameraBridgeViewBase class from the OpenCV SDK. By simply calling enableView(), the class handles the underlying camera connection and start-up process for us.

@Override
public void onResume()
{
	super.onResume();
	if (mOpenCvCameraView != null) {
		mOpenCvCameraView.enableView();
	}
}

When a user selects a specific object detection model from the menu, the application executes a two-step procedure to ensure the inference engine and the UI are perfectly synchronized:

1. Initializing the Inference Model

First, the application identifies the chosen model (e.g., YOLO, SSD, or MobileNet) and loads the corresponding network configuration and weight files into memory. This step initializes the Inference Engine (such as OpenCV’s dnn module).

2. Choosing the Right Renderer

Once the model is loaded, the application must switch to the appropriate Renderer that fits the model’s specific output format. Since different models return detection data (bounding boxes, confidence scores, etc.) in different structures, a dedicated renderer (e.g., Yolov3FrameRender) is required to correctly interpret and draw the results on the screen.

@Override
public boolean onOptionsItemSelected(MenuItem item) {
	boolean retBool = false;

	mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_NORMAL);
	mOnCameraFrameRender = new OnCameraFrameRender(new PreviewFrameRender());
	int id = item.getItemId();
	if(id == R.id.normal)
	{
		... Do some normal work
		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.maskrcnn)
	{
		... Do some rcnn model work
		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov3)
	{
		... Do some yolo model work
		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov3_tiny)
	{
		... Do some yolo model work

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov7_tiny)
	{
		... Do some yolo model work

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.mobile_net)
	{
		... Do some mobile net model work

		item.setChecked(true);
		retBool = true;
	}
	else
	{
		retBool = super.onOptionsItemSelected(item);
	}
	return retBool;
}

Below is the mapping between each Render Class (Strategy) and its corresponding Model Files (Inference) as used in the selection process:

Option (Menu)	Render Class (Strategy)	Model Files (Configuration / Weights)
Mask-RCNN	MaskRCNNDetector	mask_rcnn_inception_v2_coco_2018_01_28.pbtxt / frozen_inference_graph.pb
MobileNet-SSD v3	MobileNetSSDDetector	ssd_mobilenet_v3_large_coco_2020_01_14.pbtxt / frozen_inference_graph_ssd.pb
Yolo v3	Yolov3Detector	yolov3.cfg / yolov3.weights yolov3-tiny.weights
Yolo v7 tiny	Yolov7Detector	yolov7.cfg / yolov7-tiny.weights

3. Loading the Model

Loading the model into memory is the most critical priority in our inference application. However, in the Android ecosystem, accessing the file system is restricted by the “Sandbox” security model. This means a user app is prohibited from directly accessing file paths without explicit permissions or proper context.

To load our model in the simplest yet safest way, we will package the model files within the assets folder. This folder is specifically designed for raw data and resources that need to be bundled with the application package (APK).

4. Why use the Assets folder?

Access: We can use the AssetManager to read these files and copy them to the app’s internal cache directory, providing a valid file path for the OpenCV dnn module.
Security: Files in assets are private to the application and do not require external storage permissions.
Convenience: The model files (e.g., .cfg, .weights, .pb) are bundled together during the build process, ensuring they are always available when the app is installed.

9.4. The Role of DetectorNetData

The DetectorNetData class is responsible for managing the model files required for inference. It handles the transition from static assets to accessible runtime files:

Reading from Assets: It accesses the raw model files (e.g., configurations and weights) stored within the application’s assets folder.
Writing to Internal Storage: Since the OpenCV DNN module requires a filesystem path to load models, DetectorNetData writes these files to a private directory that our detector app can safely access at runtime.

By utilizing this class, we ensure that the model files are securely extracted and ready for the inference engine without violating Android’s sandbox security policies.

public void preDetectorProcess(final Context ctx, final CvDetectorType detectorType) {
	setDetectorType(detectorType);

	if(detectorType == CvDetectorType.METHOD_MRCNN)
	{
		final String cfgFile = getMRcnnConfig(ctx);
		final String modelFile = getMRcnnModel(ctx);

		boolean isSetupCompleted = true;
		if(modelFile == null)
		{
			Log.i(TAG, "Config file path not found!!!!");
			isSetupCompleted = false;
		}

		if(cfgFile == null)
		{
			Log.i(TAG, "weightFile file path not found!!!!");
			isSetupCompleted = false;
		}

		if(isSetupCompleted)
		{
			DnnModelRepository.getInstance().unloadModel(detectorType.toString());
			setDnnNet(DnnModelRepository.getInstance().loadModel(detectorType, modelFile, cfgFile));
		}
	}
	else if(detectorType == CvDetectorType.METHOD_YOLOV3)
	{
		final String cfgFile = getYolov3Config(ctx);
		final String weightFile = getYolov3Weight(ctx);
		boolean isSetupCompleted = true;

		if(cfgFile == null)
		{
			Log.i(TAG, "Config file path not found!!!!");
			isSetupCompleted = false;
		}

		if(weightFile == null)
		{
			Log.i(TAG, "weightFile file path not found!!!!");
			isSetupCompleted = false;
		}

		if(isSetupCompleted)
		{
			DnnModelRepository.getInstance().unloadModel(detectorType.toString());
			setDnnNet(DnnModelRepository.getInstance().loadModel(detectorType, weightFile, cfgFile));
		}

	}
	else if(detectorType == CvDetectorType.METHOD_YOLOV3_TINY)
	{
		final String cfgFile = getYolov3TinyConfig(ctx);
		final String weightFile = getYolov3TinyWeight(ctx);
		boolean isSetupCompleted = true;

		if(cfgFile == null)
		{
			Log.i(TAG, "Config file path not found!!!!");
			isSetupCompleted = false;
		}

		if(weightFile == null)
		{
			Log.i(TAG, "weightFile file path not found!!!!");
			isSetupCompleted = false;
		}

		if(isSetupCompleted)
		{
			DnnModelRepository.getInstance().unloadModel(detectorType.toString());
			setDnnNet(DnnModelRepository.getInstance().loadModel(detectorType, weightFile, cfgFile));
		}

	}
	else if(detectorType == CvDetectorType.METHOD_YOLOV7_TINY)
	{
		final String cfgFile = getYolov7TinyConfig(ctx);
		final String weightFile = getYolov7TinyWeight(ctx);
		boolean isSetupCompleted = true;

		if(cfgFile == null)
		{
			Log.i(TAG, "Config file path not found!!!!");
			isSetupCompleted = false;
		}

		if(weightFile == null)
		{
			Log.i(TAG, "weightFile file path not found!!!!");
			isSetupCompleted = false;
		}

		if(isSetupCompleted)
		{
			DnnModelRepository.getInstance().unloadModel(detectorType.toString());
			setDnnNet(DnnModelRepository.getInstance().loadModel(detectorType, weightFile, cfgFile));
		}

	}
	else if(detectorType == CvDetectorType.METHOD_MOBNET)
	{
		final String cfgFile = getMBNetConfig(ctx);
		final String modelFile = getMBNetModel(ctx);

		boolean isSetupCompleted = true;
		if(modelFile == null)
		{
			Log.i(TAG, "Config file path not found!!!!");
			isSetupCompleted = false;
		}

		if(cfgFile == null)
		{
			Log.i(TAG, "weightFile file path not found!!!!");
			isSetupCompleted = false;
		}

		if(isSetupCompleted)
		{
			DnnModelRepository.getInstance().unloadModel(detectorType.toString());
			setDnnNet(DnnModelRepository.getInstance().loadModel(detectorType, modelFile, cfgFile));
		}
	}
	else if(detectorType == CvDetectorType.METHOD_NORMAL)
	{
		DnnModelRepository.getInstance().clearAll();
		return;
	}
	else if(detectorType == CvDetectorType.METHOD_UNKNWON)
	{
		DnnModelRepository.getInstance().clearAll();
		return;
	}

	if(dnnNet == null) return;

	setLabel(ctx, detectorType);
}

9.5. Managing Model Life Cycle

The DnnModelRepository class acts as a central hub for loading and unloading inference models. It relies on the following logic to ensure the model files are ready for the OpenCV DNN engine:

1. The `getSafeModelAssetPath()` Method

This is the core method that bridges the gap between the assets folder and the Android file system. Its execution flow is as follows:

Check Existence: It first checks if the model files already exist in the app’s local sandbox storage.
Conditional Copying: If the files are missing, it reads them from the assets folder and copies them to the internal storage.
Target Storage (getFilesDir()): It uses the getFilesDir() method of the Context class. This points to the app’s internal storage, which is:
- Secure: Protected by the Android Sandbox.
- Permission-Free: Does not require READ/WRITE_EXTERNAL_STORAGE permissions.
Path Return: Once the copy is verified, it returns the absolute path of the file, allowing the Dnn module to load the model successfully.

private String getSafeModelAssetPath(Context context, String fileName) {
	// 1. File object that is saved to the internal storage(no need to gain security permission)
	File destFile = new File(context.getFilesDir(), fileName);

	// 2. It returns its path immediately, if the file is already copied.
	if (destFile.exists()) {
		Log.d("OpenCV_Model", "The model is already existed.[" + fileName + "]");
		return destFile.getAbsolutePath();
	}

	// 3. It starts to copy from assets directory to the internal storage.
	try (InputStream is = context.getAssets().open(fileName);
		 FileOutputStream os = new FileOutputStream(destFile)) {


		byte[] buffer = new byte[1024 * 16]; // 16KB Buffer
		int length;
		int size = 0;
		while ((length = is.read(buffer)) > 0) {
			os.write(buffer, 0, length);
			size += length;
		}

		Log.d("OpenCV_Model", String.format("Model size[%d] Path[%s] ", size, destFile.getAbsolutePath()));
		return destFile.getAbsolutePath();

	} catch (IOException e) {
		Log.e("OpenCV_Model", "2.Error while copying: " + e.getMessage());
		return null;
	}
}

9.6. DnnModelRepository

The DnnModelRepository is implemented as a Singleton class to ensure efficient memory management and centralized access to inference models. Instead of reloading heavy models repeatedly, it maintains and reuses Net objects throughout the application’s lifecycle.

1. Key Responsibility: Object Reuse

By storing the loaded Net objects in internal storage (memory), the repository avoids the overhead of reading from the disk every time a frame needs to be processed. This is crucial for maintaining a high FPS in our real-time object detection app.

2. Main Methods: The Lifecycle Controllers

Clears the reference from memory to prevent memory leaks, especially when switching between different models (e.g., switching from YOLO to Mask R-CNN).

loadModel()

Uses getSafeModelAssetPath() to ensure model files exist in the sandbox.
Reads the files and initializes the OpenCV Net object.
Stores the initialized Net object in a cache (e.g., a HashMap or a member variable) for immediate reuse.

unloadModel()

Explicitly releases the resources held by the Net object.
Clears the reference from memory to prevent memory leaks, especially when switching between different models (e.g., switching from YOLO to Mask R-CNN).

3. Efficient Model Management via Map

In the loadModel() method, the Net object is created using the model files prepared in the sandbox. To optimize performance, these objects are stored in a Map<ModelType, Net>.

The Logic of the Map Object:

Key: The specific model type selected by the user (e.g., YOLO_V3, SSD).
Value: The fully initialized OpenCV Net object.

4. Conditional Assignment:

When loadModel() is called, the repository follows this workflow:

Check Key: It checks if the Map already contains the Net object for the requested model type.
Reuse: If it exists, the repository simply returns the existing object, avoiding expensive disk I/O and memory allocation.
Create & Save: Only if the object does not exist (null), it creates a new Net object using the model files and saves it to the Map for future use.

public Net loadModel(DetectorNetData.CvDetectorType modelType, String pbPath, String pbtxtPath) {
	String modelKey =modelType.toString();

	if(modelType == DetectorNetData.CvDetectorType.METHOD_MRCNN || modelType == DetectorNetData.CvDetectorType.METHOD_MOBNET)
	{
		if (!modelMap.containsKey(modelKey) || Objects.requireNonNull(modelMap.get(modelKey)).empty()) {
			Net net = Dnn.readNetFromTensorflow(pbPath, pbtxtPath);
			net.setPreferableBackend(Dnn.DNN_BACKEND_OPENCV);
			net.setPreferableTarget(Dnn.DNN_TARGET_CPU);
			modelMap.put(modelKey, net);
		}
		return modelMap.get(modelKey);
	}
	else if(modelType == DetectorNetData.CvDetectorType.METHOD_YOLOV3 ||
                modelType == DetectorNetData.CvDetectorType.METHOD_YOLOV3_TINY || 
                modelType == DetectorNetData.CvDetectorType.METHOD_YOLOV7_TINY)
	{
		if (!modelMap.containsKey(modelKey) || Objects.requireNonNull(modelMap.get(modelKey)).empty()) {
			Net net = Dnn.readNetFromDarknet(pbtxtPath, pbPath);
			net.setPreferableBackend(Dnn.DNN_BACKEND_OPENCV);
			net.setPreferableTarget(Dnn.DNN_TARGET_CPU);
			modelMap.put(modelKey, net);
		}
		return modelMap.get(modelKey);
	}

	return null;
}

5. Explicit Memory Release via Map Removal

Just as we store models for reuse, we must also provide a way to remove the Net objects from memory. By using the Model Type (Key), we can pinpoint and clear specific models from our internal Map.

The Unloading Process:

Identify Key: The system identifies the model that is no longer needed (e.g., when a user deselects a model or closes the detection session).
Remove from Map: The Net object is removed from the Map using its key.
Resource Cleanup: Once removed from the Map, the object becomes eligible for Garbage Collection. Since Net objects are native resources in OpenCV, explicitly calling net.release() (if available in the specific SDK version) before removal further ensures that native memory is freed immediately.

public void unloadModel(String modelKey) {
	if (modelMap.containsKey(modelKey)) {
		Net net = modelMap.get(modelKey);
		if (net != null) {
			net = null; // de-referencing 
		}
		modelMap.remove(modelKey);
		System.gc(); // hints (needs sometimes because of heavy native memory)
	}
}

6. GUI Layouts

Our object detection app is designed with a clean, functional interface that prioritizes the camera feed while providing easy access to model selection.

Key Components of the GUI:

Main Camera View:
- The center of the screen is dominated by the CameraBridgeViewBase.
- This is where the real-time frame processing happens. Once the user selects a model, the bounding boxes and labels are rendered directly on top of this view.
Top Action Bar / Menu:
- Located at the top of the screen, it contains the Model Selection Menu.
- When the user clicks the menu icon, a list of available models (YOLO v3, YOLO v7, SSD, Mask R-CNN) appears.
Status Overlays (Optional):
- Information such as FPS (Frames Per Second) or the name of the currently active model is often displayed in the corner to provide real-time feedback on performance.

9.7. Interaction Flow

Step 1: The user launches the app, and the camera activates automatically via enableView().
Step 2: The user taps the menu in the GUI.
Step 3: Selecting a model triggers the DnnModelRepository.loadModel() logic we discussed earlier.
Step 4: The UI immediately reflects the detection results as the new FrameRender starts drawing on the onCameraFrame.

detection_xml.png 교체

The menu on the left was created using onCreateOptionsMenu(), and its selection logic is handled by the onOptionsItemSelected() callback.

@Override
public boolean onCreateOptionsMenu(Menu menu) {
	super.onCreateOptionsMenu(menu);
	getMenuInflater().inflate(R.menu.detection, menu);
	return true;
}

The menu items consist of ‘Normal Mode’ as the default, with ‘YOLO’, ‘Mask R-CNN’, and ‘YOLO Tiny’ available as alternative detection models.

9.8. Object Detection Options

The application provides a variety of operational modes via the options menu. By default, the app starts in Normal Mode, but users can switch to specialized inference models depending on their needs:

Normal Mode (Default): Standard camera preview without object detection processing.
YOLO: The standard YOLO model, offering high accuracy for object detection.
Mask R-CNN: Advanced model that provides instance segmentation (detecting object shapes).
YOLO Tiny: A lightweight version of YOLO optimized for higher frame rates (FPS) on mobile devices.

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android" >
    <group android:checkableBehavior="single">
        <item android:id="@+id/normal_mode"
              android:title="@string/normal_mode"
              android:showAsAction="ifRoom|withText" />
        <item
            android:id="@+id/detect_mode"
            android:title="@string/default_mode">
              <menu>
                  <group android:checkableBehavior="single">
                      <item android:id="@+id/normal"
                          android:title="@string/normal"
                          android:checked="true" />
                      <item android:id="@+id/maskrcnn"
                            android:title="@string/maskrcnn" />
                      <item android:id="@+id/yolov3"
                            android:title="@string/yolov3" />
                      <item android:id="@+id/yolov3_tiny"
                          android:title="@string/yolov3_tiny" />
                      <item android:id="@+id/yolov7_tiny"
                          android:title="@string/yolov7_tiny" />
                      <item android:id="@+id/mobile_net"
                          android:title="@string/mobile_net" />
                  </group>
              </menu>
        </item>
    </group>
</menu>

The layout menu will be displayed on the real android device as follows:

The menu layout is rendered on the physical Android device as shown below, providing a seamless interface for switching between detection modes.

@Override
public boolean onOptionsItemSelected(MenuItem item) {
	boolean retBool = false;

	int id = item.getItemId();

	if(id == R.id.normal)
	{
		Log.d(TAG, "Normal["+item.getTitle()+"]");
		mOnCameraFrameRender =
				new OnCameraFrameRender(new PreviewFrameRender());
		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.maskrcnn)
	{
		Log.d(TAG, "Mask RCNN["+item.getTitle()+"]");
		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_MRCNN);
		MaskRCNNFrameRender maskRCNNFrameRender = new MaskRCNNFrameRender(mObjDetectorNet);
		mOnCameraFrameRender =
				new OnCameraFrameRender(maskRCNNFrameRender);

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov3)
	{
		Log.d(TAG, "Yolov3["+item.getTitle()+"]");

		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_YOLOV3);
		YoloFrameRender yolov3FrameRender = new YoloFrameRender(mObjDetectorNet);
		mOnCameraFrameRender =
			new OnCameraFrameRender(yolov3FrameRender);

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov3_tiny)
	{
		Log.d(TAG, "Yolov3_tiny["+item.getTitle()+"]");

		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_YOLOV3_TINY);
		YoloFrameRender yoloFrameRender = new YoloFrameRender(mObjDetectorNet);
		mOnCameraFrameRender =
				new OnCameraFrameRender(yoloFrameRender);

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.yolov7_tiny)
	{
		Log.d(TAG, "Yolov7_tiny["+item.getTitle()+"]");

		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_YOLOV7_TINY);
		YoloFrameRender yoloFrameRender = new YoloFrameRender(mObjDetectorNet);
		mOnCameraFrameRender =
				new OnCameraFrameRender(yoloFrameRender);

		item.setChecked(true);
		retBool = true;
	}
	else if(id == R.id.mobile_net)
	{
		Log.d(TAG, "MobileNet["+item.getTitle()+"]");

		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_MOBNET);
		MobileNetSSDFrameRender mobileNetSSDFrameRender = new MobileNetSSDFrameRender(mObjDetectorNet);
		mOnCameraFrameRender =
				new OnCameraFrameRender(mobileNetSSDFrameRender);

		item.setChecked(true);
		retBool = true;
	}
	else
	{
		mObjDetectorNet.preDetectorProcess(this, DetectorNetData.CvDetectorType.METHOD_NORMAL);
		mOnCameraFrameRender = new OnCameraFrameRender(new PreviewFrameRender());
		retBool = super.onOptionsItemSelected(item);
	}
	return retBool;
}

9.9. Final Results of Object Detector

Finally, we have successfully built our object detector, which runs inference properly whenever the user selects a detection option. With just a few minor modifications, you can easily test the latest object detection models on your own.

Model Type	Output
Mask-RCNN
MobileNet-SSD v3
Yolo v3
Yolo v3 tiny
Yolo v7 tiny

Mobile-optimized models run significantly faster than older alternatives, which are often too slow for practical use. Furthermore, model accuracy varies widely. While I question the value of unoptimized models that lack sufficient performance, our current object detector layout allows us to test new models in the near future with minimal effort.

10. Summary

In this series, we successfully developed a mobile application capable of real-time model switching and live object detection. You are now equipped to enhance this application by integrating custom-trained models or leveraging high-performance architectures to push the boundaries of your detection app.

11. References

12. Download Links

JDK (Java Development Kit) : https://jdk.java.net/17/
Android Studio : https://developer.android.com/studio?hl=en
Gradle: https://gradle.org/releases
OpenCV Android SDK : https://github.com/opencv/opencv/releases/tag/4.13.0

13. Download the source code

Download

You can download the app source code of this post here:

Hello World App

Hello OpenCV App

My Object Detector App

14. How to Download Models and Resources

Due to upload size limits, the required models and labels are not included directly in this section. Instead, you can find the appropriate download links back in Section 9.3: Object Detection Process. To run the Object Detector App successfully, simply download those necessary models and resources, then extract them directly into the assets folder within your source directory.

Tags

Building and testing a Modern Java 25 / Spring Boot 4.0.6 Backend: Docker, PostgreSQL, OpenAPI, Serenity BDD, Cucumber, and JUnit 6

Anatoly Krivitsky — Wed, 24 Jun 2026 09:08:30 +0000

Enterprise Java

Building and testing a Modern Java 25 / Spring Boot 4.0.6 Backend: Docker, PostgreSQL, OpenAPI, Serenity BDD, Cucumber, and JUnit 6

Abstract

This article walks through a compact but realistic backend application built with Java 25 and Spring Boot 4.0.6. The project uses PostgreSQL running in Docker, Gradle 9.5.1 as the build system, Eclipse 2026-03 as the IDE, springdoc OpenAPI/Swagger UI for interactive API documentation, and a test stack built around JUnit 6, Cucumber, and Serenity BDD. The purpose is not to teach every tool from first principles. Instead, the article provides a working integration baseline: a small book-catalog REST service that can be started, inspected through Swagger UI, tested through unit tests, and documented through Serenity reports. For developers who learn best by running real code and modifying it, this kind of baseline can be more useful than another isolated “hello world” example.

Technology baseline

Area	Technology used in the project
Language / runtime	Java 25
Application framework	Spring Boot 4.0.6
Build	Gradle 9.5.1, Groovy DSL, Java toolchains
Database	PostgreSQL 18.x running in Docker
API documentation	springdoc OpenAPI / Swagger UI
Testing	JUnit 6 / JUnit Jupiter, Cucumber, Serenity BDD, Serenity REST
IDE	Eclipse 2026-03
Application example	Book catalog REST API with create, read, update, delete, and search operations

Why another Spring Boot tutorial?

There is no shortage of Spring Boot examples. The problem is that many examples become outdated quickly. A tutorial written for Spring Boot 3.x, an older Gradle version, an older Docker Desktop release, or an older testing stack may still teach useful concepts, but it may also leave the reader solving version conflicts that the article never mentions.

That version drift matters. Modern backend development is less about a single framework and more about the collaboration between framework, runtime, build system, database, test tools, API documentation, local development infrastructure, and IDE support. If one component moves forward while the others are frozen in older assumptions, developers often spend hours on dependency alignment, package moves, plugin versions, and configuration details.

This article therefore takes a different angle. It demonstrates a small backend project where current versions work together. The goal is to provide a verified starting point rather than an encyclopedic treatment of every tool.

The application used in the example

The sample application is intentionally simple: a book catalog service backed by PostgreSQL. It is simple enough to understand quickly, but it is not merely a console example. It has a database schema, a JPA entity, record-based request and response DTOs, a repository, a transactional service layer, a REST controller, centralized exception handling, OpenAPI documentation, unit tests, Cucumber scenarios, and Serenity-generated reports.

The service exposes operations to list books, create a new book, retrieve a book by id, update an existing book, delete a book, search by author, and find a book by ISBN. This is enough surface area to demonstrate persistence, validation, error handling, documented REST endpoints, and several styles of automated testing.

The table used by the application is intentionally small but includes realistic constraints:

CREATE TABLE book (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    title VARCHAR(200) NOT NULL,
    author VARCHAR(120) NOT NULL,
    isbn VARCHAR(20) NOT NULL,
    published_date DATE,
    price NUMERIC(10, 2),
    stock_quantity INTEGER NOT NULL,
    description VARCHAR(1000),
    CONSTRAINT uk_book_isbn UNIQUE (isbn),
    CONSTRAINT ck_book_price_nonnegative CHECK (price IS NULL OR price >= 0),
    CONSTRAINT ck_book_stock_nonnegative CHECK (stock_quantity >= 0)
);

Starting PostgreSQL with Docker

The database runs in a Docker container so that the example does not depend on a manually installed local PostgreSQL server. This keeps the development environment reproducible and makes it easier to reset or recreate the database when experimenting.

A minimal development setup can start with pulling the PostgreSQL image and launching a named container. In real production environments, credentials should be injected through a secure mechanism rather than typed directly on the command line. For a local tutorial project, however, a direct command is sufficient to show the moving parts.

docker pull postgres:latest

docker run --name pg-akrivitsky   -e POSTGRES_USER=akrivitsky   -e POSTGRES_PASSWORD=your_password   -e POSTGRES_DB=swagger_demo   -p 5432:5432   -v pgdata_akrivitsky:/var/lib/postgresql   -d postgres:latest

The persistent volume is mapped to /var/lib/postgresql, which is the data directory location expected by the newer PostgreSQL Docker image used in this setup. After the container starts, the version can be verified with psql:

docker exec -it pg-akrivitsky psql -U akrivitsky -d swagger_demo
SELECT version();

Gradle and Java 25

The project is a Gradle build using the Groovy DSL. The important point is that the build declares Java 25 through the Gradle toolchain mechanism. This is cleaner than relying on whatever JDK happens to be first on the PATH.

The settings file can use the Foojay toolchain resolver convention plugin. Together with the toolchain declaration, this allows Gradle to resolve the requested JDK if it is not already installed in the local environment.

// settings.gradle
plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

rootProject.name = 'SpringBoot4FeaturesSwaggerSerenityPostgres'
include 'lib'

// lib/build.gradle
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

The build then applies the Spring Boot plugin, dependency management, Java, Eclipse, and Serenity plugin support. The exact dependency list is not complicated, but the versions are important because Spring Boot 4, springdoc 3.x, Serenity, Cucumber, and the JUnit platform must all cooperate.

plugins {
    id 'java'
    id 'eclipse'
    id 'org.springframework.boot' version '4.0.6'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'net.serenity-bdd.serenity-gradle-plugin' version '5.3.9'
}

ext {
    serenityVersion = '5.3.9'
    cucumberVersion = '7.21.1'
}

Spring Boot 4.0.6 project structure

The application follows a conventional layered structure. The root package contains the Spring Boot application class. Subpackages hold configuration, controller, DTO, entity, exception, repository, and service code. Tests are separated into ordinary unit and slice tests, Cucumber step definitions, a Cucumber runner, and direct Serenity REST tests.

This structure is not the only possible layout, but it is easy to understand and works well for a tutorial project. It also maps naturally to common enterprise development expectations: controller logic is separate from service logic, persistence is hidden behind Spring Data JPA repositories, and exception handling is centralized.

src/main/java/dev/anatoly/swaggerdemo
├── SwaggerDemoApplication.java
├── config/OpenApiConfig.java
├── controller/BookController.java
├── dto/BookCreateRequest.java
├── dto/BookUpdateRequest.java
├── dto/BookResponse.java
├── entity/Book.java
├── exception/GlobalExceptionHandler.java
├── exception/ResourceNotFoundException.java
├── repository/BookRepository.java
└── service/BookService.java

Modern Java style in the DTO layer

The request and response objects are implemented as Java records. Records are not new to Java 25, but they represent a concise and reliable style for immutable data carriers. In a REST application they are especially convenient because they avoid boilerplate getters, setters, equals, hashCode, and toString code.

Validation annotations can be applied directly to record components. springdoc can also read OpenAPI metadata from annotations placed on those components.

public record BookCreateRequest(
    @NotBlank
    @Schema(example = "Effective Java")
    String title,

    @NotBlank
    @Schema(example = "Joshua Bloch")
    String author,

    @NotBlank
    @ISBN
    @Schema(example = "9780134685991")
    String isbn,

    @PastOrPresent
    LocalDate publishedDate,

    @DecimalMin("0.00")
    BigDecimal price,

    @Min(0)
    Integer stockQuantity,

    String description
) {}

Repository and service layer

The repository extends JpaRepository and uses Spring Data derived queries for the two non-basic lookup methods. This keeps the persistence layer compact and lets Spring Data create the implementation automatically.

The service layer is transactional. Read operations can use read-only transactions, while create, update, and delete operations run in ordinary transactional context. Mapping between entity and record DTO is done manually to keep the example transparent and avoid reflection-heavy mapping frameworks.

public interface BookRepository extends JpaRepository<Book, Long> {
    Optional<Book> findByIsbn(String isbn);
    List<Book> findByAuthorContainingIgnoreCase(String author);
}

REST API and OpenAPI documentation

The REST controller exposes the book-catalog operations and annotates them with OpenAPI metadata. Swagger UI then becomes more than a static documentation page. It is also a convenient manual exploration tool: developers can inspect endpoints, send requests, view responses, and confirm that the application is connected to PostgreSQL.

In a production system, Swagger UI access should be controlled according to organizational security rules. For a local development baseline, it is very useful because it provides immediate feedback before the test suite is executed.

@RestController
@RequestMapping("/api/books")
@Tag(name = "Books", description = "CRUD operations for catalog entries")
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @GetMapping
    @Operation(summary = "List all books")
    public List<BookResponse> listBooks() {
        return bookService.findAll();
    }

    @PostMapping
    @Operation(summary = "Create a new book")
    public ResponseEntity<BookResponse> createBook(@Valid @RequestBody BookCreateRequest request) {
        BookResponse created = bookService.create(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }
}

Application configuration

The application.yaml file connects the Spring Boot application to the PostgreSQL container, enables SQL initialization, configures JPA validation against the schema, and exposes the OpenAPI/Swagger endpoints. One notable property is virtual thread support, enabled with a single Spring Boot configuration line.

Virtual threads are not required for this small example, but enabling them demonstrates how the project can use a modern Java runtime feature through Spring Boot configuration.

server:
  port: 8080

spring:
  threads:
    virtual:
      enabled: true
  datasource:
    url: jdbc:postgresql://localhost:5432/swagger_demo
    username: akrivitsky
    password: your_password
  jpa:
    hibernate:
      ddl-auto: validate
  sql:
    init:
      mode: always

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs

Error handling with ProblemDetail

Modern Spring applications do not need to invent a custom error object for every REST API. Spring supports ProblemDetail, which is aligned with the standardized problem-details response style. In the sample project, a global exception handler converts application exceptions and validation failures into structured error responses.

This approach keeps controller methods cleaner and gives API clients a predictable error-response shape.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        problem.setTitle("Resource not found");
        problem.setDetail(ex.getMessage());
        return problem;
    }
}

Testing strategy

The project deliberately uses more than one testing style because real projects rarely rely on one style only. The ordinary Gradle test task runs unit and Spring tests. Cucumber feature tests are placed behind a separate task so that they do not accidentally run during every ordinary test execution. Serenity is then used to generate human-readable reports.

This separation gives developers control. Fast unit tests can run frequently. Cucumber and Serenity acceptance tests can run when the application is available and when report generation is useful.

test {
    useJUnitPlatform {
        excludeEngines 'cucumber'
    }
}

task cucumberTest(type: Test) {
    useJUnitPlatform {
        includeEngines 'junit-platform-suite', 'cucumber'
    }
    systemProperty 'cucumber.features', 'classpath:features/books'
    systemProperty 'cucumber.glue', 'dev.anatoly.swaggerdemo.cucumber'
    filter {
        includeTestsMatching "*RunCucumberTest*"
    }
}

Cucumber plus Serenity BDD

Cucumber is useful when tests should read like business behavior. In this project, a feature file describes book search behavior in Given/When/Then form. Java step definitions execute those steps by calling the running REST API through Serenity REST.

The result is not only pass/fail automation. Serenity produces a report that documents the executed scenario, request, response, headers, body, and outcome. This can be valuable when test results must be understandable to people who are not reading Java source code.

Feature: Search books

  Scenario: Find books by author
    Given the book catalog service is running
    When I search books by author "Martin"
    Then the response status should be 200
    And the response should contain at least one book

Serenity REST without Gherkin

The project also demonstrates another style: direct JUnit 6 / JUnit Jupiter tests using Serenity REST, without .feature files. This is useful when the audience for the tests is mainly technical and when the extra Gherkin layer does not add much value.

In this style the test remains an ordinary Java test, but Serenity still captures the REST interaction and generates a rich HTML report.

@ExtendWith(SerenityJUnit5Extension.class)
class WhenManagingBooks {

    @Test
    void should_find_books_by_author() {
        SerenityRest.given()
            .queryParam("author", "Martin")
        .when()
            .get("http://localhost:8080/api/books/search/by-author")
        .then()
            .statusCode(200);
    }
}

Running the application

Once PostgreSQL is running, the application can be started from Eclipse by running the Spring Boot application class as a Java application. After startup, Swagger UI can be opened in the browser.

The Swagger UI page provides a convenient way to verify the endpoints manually. For example, you can create a new book by sending a JSON request to the POST /api/books endpoint and then confirm that the saved record appears in later GET responses.

http://localhost:8080/swagger-ui/index.html

# Cucumber + Serenity reports
gradlew :lib:clean :lib:cucumberTest :lib:aggregate --rerun-tasks

# Direct JUnit / Serenity REST report
gradlew :lib:clean :lib:test --tests "*WhenManagingBooks*" :lib:aggregate --rerun-tasks

What this project gives you

The practical value of the project is the integration baseline. It shows one combination of Spring Boot 4.0.6, Java 25, PostgreSQL in Docker, Gradle, OpenAPI documentation, and Serenity-based testing that works as a coherent unit.

That does not mean every production system should copy this project exactly. Production deployments require stricter secrets management, environment-specific configuration, observability, CI/CD hardening, infrastructure automation, and security review. The point is to start from a running, tested, documented example rather than from incompatible fragments.

Docker Compose or Kubernetes can be added later if the article is extended. For the present baseline, a single PostgreSQL container is enough to demonstrate local database infrastructure without making the article primarily about orchestration.

Lessons learned

First, version alignment is the hidden work in modern tutorials. Spring Boot, springdoc, Gradle, Java, Cucumber, Serenity, PostgreSQL, and the JUnit platform all evolve. A useful example must show versions that actually cooperate.

Second, API documentation and testing should not be afterthoughts. Swagger UI gives a fast manual feedback loop. Unit tests give development confidence. Cucumber and Serenity reports add readable evidence of API behavior.

Third, AI-assisted development can speed up the search for working configurations, but it does not remove the need to verify. In this project, every useful generated fragment still had to be compiled, run, tested, and corrected locally. That is the responsible version of a vibe-coding workflow: use AI as an accelerator, not as an authority.

Conclusion

A modern Java backend is rarely just Java code. It is a working relationship between the language, the framework, the build, the database, the local infrastructure, the documentation surface, and the test/reporting workflow.

This article presented a compact Spring Boot 4.0.6 / Java 25 project that connects those pieces in one place. The application is small, but the stack is representative of real enterprise development: PostgreSQL persistence, Docker-based local infrastructure, OpenAPI documentation, JUnit 6 tests, Cucumber scenarios, and Serenity BDD reporting.

For developers who prefer learning through a running project, this baseline can be cloned, inspected, tested, and modified. From there, it can grow into Docker Compose, Kubernetes, CI/CD pipelines, additional security controls, or a larger domain model.

Source code: https://github.com/akrivitsky7/springboot4-swagger-serenity-postgres-eclipse/tree/main

HTML UIs in Spring AI MCP Servers

Yatin Batra — Wed, 24 Jun 2026 08:22:00 +0000

Enterprise Java

HTML UIs in Spring AI MCP Servers

Modern AI applications are evolving beyond simple text interactions. With the introduction of the Model Context Protocol (MCP), developers can expose tools, resources, and prompts that AI agents can discover and invoke dynamically. While most MCP examples focus on APIs and tool execution, there are scenarios where returning rich HTML interfaces directly from MCP servers provides a much better user experience. In this article, we’ll explore how to build an MCP Server using Spring AI, expose an HTML-based UI through MCP resources, and test the server using MCP-compatible clients.

1. Overview

The Model Context Protocol (MCP) is an open standard that enables AI models to interact with external systems in a structured and secure manner. MCP servers can expose:

Tools for executing actions
Resources for retrieving content
Prompts for reusable AI interactions

One interesting use case is embedding HTML interfaces directly within MCP resources. Instead of returning plain text, the server can provide a complete HTML page that can be rendered by MCP-aware clients, dashboards, or agent platforms. Embedding HTML UIs within MCP resources enhances the user experience by enabling rich visual presentations, interactive dashboards, embedded reports and analytics, AI-generated custom interfaces, and improved usability for enterprise applications, making AI-powered systems more intuitive, engaging, and business-friendly.

2. Introduction to Spring AI and MCP Servers

2.1 What is Spring AI?

Spring AI is the Spring ecosystem’s framework for building AI-powered applications, providing abstractions for Large Language Models (LLMs), embeddings, vector databases, prompt engineering, AI agents, and the Model Context Protocol (MCP). It enables developers to build intelligent applications using familiar Spring Boot programming patterns while maintaining portability and flexibility across multiple AI providers.

2.2 What is an MCP Server?

An MCP (Model Context Protocol) Server exposes tools, resources, and other capabilities that AI models can dynamically discover and invoke through a standardized protocol, eliminating the need for hard-coded integrations. In a typical MCP architecture, an AI Assistant communicates with an MCP Client, which interacts with an MCP Server that provides access to various tools and resources. This architecture enables seamless integration between AI applications and external systems, with the MCP server acting as a bridge that connects AI models to enterprise services, business workflows, and data sources in a consistent and extensible manner.

3. Creating an MCP Server with Spring AI

3.1 Project Dependencies

Add the following Maven dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

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

This Maven configuration adds the core dependencies required to build a Spring AI MCP server. The spring-boot-starter dependency provides the foundational Spring Boot components, including auto-configuration, dependency management, and application startup support, while the spring-ai-starter-mcp-server-webmvc dependency adds Spring AI’s Model Context Protocol (MCP) server capabilities on top of Spring MVC, enabling developers to create MCP-compliant servers that can expose tools, resources, and prompts for discovery and invocation by AI clients and agents.

3.2 Application Configuration

Configure the MCP server:

spring:
  application:
    name: html-mcp-server

server:
  port: 8080

spring:
  ai:
    mcp:
      server:
        name: html-ui-server
        version: 1.0.0

This configuration defines the basic settings for the Spring Boot MCP server application. The spring.application.name property assigns the application name as html-mcp-server, while the server.port property configures the embedded web server to listen on port 8080. The spring.ai.mcp.server section configures the MCP server metadata by specifying a server name (html-ui-server) and version (1.0.0), allowing MCP clients to identify and interact with the server and its exposed capabilities through the Model Context Protocol.

3.3 Create an HTML Dashboard Resource

The following component exposes an HTML dashboard as an MCP resource.

package com.example.mcp.resource;

import org.springframework.stereotype.Component;

@Component
public class DashboardResource {

    public String getDashboardHtml() {
        return """
            <html>
            <head>
                <title>AI Dashboard</title>
                <style>
                    body {
                        font-family: Arial, sans-serif;
                        margin: 20px;
                    }

                    .card {
                        border: 1px solid #ddd;
                        padding: 20px;
                        margin: 10px 0;
                        border-radius: 8px;
                        width: 250px;
                    }

                    .metric {
                        font-size: 32px;
                        font-weight: bold;
                    }
                </style>
            </head>
            <body>
                <h1>Welcome to MCP Dashboard</h1>

                <div class='card'>
                    <div>Active Agents</div>
                    <div class='metric'>24</div>
                </div>

                <div class='card'>
                    <div>MCP Requests</div>
                    <div class='metric'>1204</div>
                </div>
            </body>
            </html>
            """;
    }
}

This class is responsible for generating the dashboard HTML and acts as the central source of the UI markup. It is annotated with @Component, which makes it a Spring-managed bean, and its getDashboardHtml() method returns the complete HTML page as a Java text block. The returned markup includes the page structure, title, embedded CSS styles, dashboard heading, and metric cards such as Active Agents and MCP Requests. By keeping the HTML generation in this dedicated class, the design separates UI construction from MCP tool logic, making the dashboard easier to maintain, reuse, and update in one place.

3.4 Create an MCP Tool

Spring AI allows MCP tools to be exposed using the @Tool annotation.

package com.example.mcp.tools;

import com.example.mcp.resource.DashboardResource;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;

@Service
public class DashboardTools {

    private final DashboardResource dashboardResource;

    public DashboardTools(DashboardResource dashboardResource) {
        this.dashboardResource = dashboardResource;
    }

    @Tool(description = "Returns an HTML dashboard")
    public String getDashboard() {
        return """
        {
          "contentType": "text/html",
          "content": %s
        }
        """.formatted(toJsonString(dashboardResource.getDashboardHtml()));
    }

    private String toJsonString(String html) {
        return "\"" + html
                .replace("\\", "\\\\")
                .replace("\"", "\\\"")
                .replace("\n", "\\n")
                .replace("\r", "") + "\"";
    }
}

This class is responsible for exposing the dashboard through MCP as a callable tool. It is annotated with @Service and receives DashboardResource through constructor injection, so it does not create the HTML itself. Instead, when the getDashboard() method is invoked by an MCP client, it calls dashboardResource.getDashboardHtml() to fetch the HTML generated in section 3.3, then wraps that HTML inside a JSON response with contentType set to text/html. This makes the flow explicit: section 3.3 is responsible for producing the dashboard HTML, while section 3.4 is responsible for publishing that HTML as an MCP tool response that clients can render directly.

3.5 Register Tool Callback Provider

package com.example.mcp.config;

import com.example.mcp.tools.DashboardTools;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ToolConfig {

    @Bean
    ToolCallbackProvider tools(
            DashboardTools dashboardTools) {

        return MethodToolCallbackProvider.builder()
                .toolObjects(dashboardTools)
                .build();
    }
}

This configuration class registers the application’s MCP tools with Spring AI so they can be discovered and invoked by MCP clients. The @Configuration annotation marks the class as a source of Spring bean definitions, while the tools() method creates a ToolCallbackProvider bean. Using MethodToolCallbackProvider.builder(), the configuration scans the supplied DashboardTools object for methods annotated with @Tool and automatically exposes them as MCP-compatible tools. This eliminates the need for manual tool registration and allows Spring AI to manage tool discovery, invocation, and metadata generation, making the MCP server’s capabilities available to AI assistants and clients through the Model Context Protocol.

3.6 Main Application

package com.example.mcp;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class HtmlMcpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(
            HtmlMcpServerApplication.class,
            args
        );
    }
}

This class serves as the entry point for the Spring Boot MCP server application. The @SpringBootApplication annotation combines component scanning, auto-configuration, and configuration support, allowing Spring Boot to automatically discover and configure application components such as MCP tools, resources, and configuration classes. The main() method invokes SpringApplication.run(), which initializes the Spring application context, starts the embedded web server, loads all registered beans, and activates the Spring AI MCP server infrastructure. Once the application starts successfully, MCP clients can connect to the server and access the exposed tools and resources, including the HTML dashboard functionality implemented in the application.

3.7 Testing the MCP Server

After completing the application setup and configuration, the next step is to start the Spring Boot MCP server. Spring Boot provides a simple command-line mechanism for building and launching the application, automatically initializing the embedded web server, loading all configured MCP tools and resources, and registering them with the Spring AI MCP framework.

mvn spring-boot:run

Executing this command compiles the project, resolves the required dependencies, and starts the application. Once the server is running successfully, MCP clients can connect to it, discover the available tools, invoke the HTML dashboard functionality, and interact with the resources exposed by the MCP server.

Started HtmlMcpServerApplication

MCP Server Started
Server Name: html-ui-server
Version: 1.0.0

Listening on port 8080

3.7.1 Verify Tool Discovery

Once the MCP server is running, the first step is to verify that the server is correctly exposing its registered tools. MCP clients can discover available capabilities by sending a tools/list request, which returns metadata about all tools published by the server. This allows clients and AI assistants to understand what functionality is available before invoking specific tools.

// ENDPOINT
http://localhost:8080/mcp

// REQUEST
{
  "method": "tools/list"
}

If the tool registration was successful, the server responds with a list of available tools along with their names and descriptions. In this example, the MCP server exposes a single tool named getDashboard, which returns an HTML dashboard.

{
  "tools": [
    {
      "name": "getDashboard",
      "description": "Returns an HTML dashboard"
    }
  ]
}

3.7.2 Invoke the Tool

After discovering the available tools, an MCP client can invoke a specific tool using the tools/call method. The request includes the tool name that should be executed by the MCP server.

// ENDPOINT
http://localhost:8080/mcp

// REQUEST
{
  "method": "tools/call",
  "params": {
    "name": "getDashboard"
  }
}

When the request is processed, the server executes the corresponding tool method and returns its output. In this case, the response contains HTML content with a MIME type of text/html, allowing MCP-compatible clients to render the dashboard directly instead of displaying plain text.

{
  "contentType": "text/html",
  "content": "<html>
<head>
    <title>AI Dashboard</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            margin: 20px;
        }

        .card {
            border: 1px solid #ddd;
            padding: 20px;
            margin: 10px 0;
            border-radius: 8px;
            width: 250px;
        }

        .metric {
            font-size: 32px;
            font-weight: bold;
        }
    </style>
</head>
<body>
    <h1>Welcome to MCP Dashboard</h1>

    <div class='card'>
        <div>Active Agents</div>
        <div class='metric'>24</div>
    </div>

    <div class='card'>
        <div>MCP Requests</div>
        <div class='metric'>1204</div>
    </div>
</body>
</html>"
}

The response contains HTML markup generated by the getDashboard() tool. Since the content type is set to text/html, MCP-compatible clients can render the response as a web page, displaying dashboard components such as metrics, reports, status indicators, and other visual elements. This demonstrates how MCP tools can return rich user interfaces rather than simple text responses, enabling AI-powered applications to deliver interactive and visually appealing experiences.

4. Conclusion

Spring AI significantly simplifies the development of MCP servers by providing native support for tool registration, resource exposure, and protocol integration within Spring Boot applications. Embedding HTML UIs inside MCP resources enables developers to deliver rich dashboards, reports, analytics views, and interactive business interfaces directly through MCP clients. As MCP adoption grows, combining Spring AI’s developer-friendly programming model with HTML-based interfaces offers a powerful approach for building next-generation AI applications that seamlessly blend conversational intelligence with traditional web experiences.

Tags

Event Sourcing vs Change Data Capture (CDC): Choosing the Right Pattern

Eleftheria Drosopoulou — Wed, 24 Jun 2026 06:04:00 +0000

Software Development

Event Sourcing vs Change Data Capture (CDC): Choosing the Right Pattern

Both patterns produce a stream of state changes — yet they sit at entirely different layers of your stack, solve different problems, and carry very different costs. Here is how to tell them apart and pick the right one.

At first glance, Event Sourcing and Change Data Capture (CDC) look like two names for the same idea: capture what changed, and send it somewhere useful. In practice, however, the two patterns differ in where they live, what guarantees they offer, and how much they will cost your team to introduce. Getting this choice wrong is expensive — Event Sourcing in particular rewrites the rules of how your application persists data, and rolling it back after the fact is rarely straightforward.

In this article, we will walk through both patterns clearly, compare them across the dimensions that actually matter in production, and end with a practical decision guide. Along the way, we will look at Java and Spring Boot examples using the tools most teams reach for: Debezium for CDC, and frameworks like Axon or EventStoreDB for Event Sourcing.

What Is Event Sourcing?

Event Sourcing is an application-level design pattern. Instead of persisting only the current state of an entity — the usual row in a relational table — the application records every change that happened to that entity as an immutable event. The current state is then derived by replaying those events in order.

Think about a bank account. In a traditional CRUD model, you store the current balance and overwrite it on every transaction. With Event Sourcing, you instead append events like MoneyDeposited(amount=500) and MoneyWithdrawn(amount=200). To find the current balance, you fold those events from the beginning — or from the latest snapshot.

// Axon Framework — a simple event-sourced aggregate in Spring Boot
@Aggregate
public class BankAccount {

    @AggregateIdentifier
    private String accountId;
    private BigDecimal balance;

    @CommandHandler
    public BankAccount(OpenAccountCommand cmd) {
        apply(new AccountOpenedEvent(cmd.getAccountId(), cmd.getInitialDeposit()));
    }

    @EventSourcingHandler
    public void on(AccountOpenedEvent event) {
        this.accountId = event.getAccountId();
        this.balance   = event.getInitialDeposit();
    }

    @CommandHandler
    public void handle(DepositMoneyCommand cmd) {
        apply(new MoneyDepositedEvent(accountId, cmd.getAmount()));
    }

    @EventSourcingHandler
    public void on(MoneyDepositedEvent event) {
        this.balance = this.balance.add(event.getAmount());
    }
}

Notice that the aggregate never calls save(). The events themselves are the source of truth, and the event store is the primary database. This is what distinguishes Event Sourcing from simply publishing domain events alongside a CRUD persist — in Event Sourcing the event is the persistence.

As the event log grows, replaying from the beginning becomes slow. The snapshot pattern periodically saves the current state so consumers can start from the latest snapshot and replay only subsequent events. Most Event Sourcing frameworks include this out of the box.

What Is Change Data Capture?

Change Data Capture is a database-level technique. It monitors the transaction log of an existing database — PostgreSQL’s WAL, MySQL’s binlog, MongoDB’s oplog — and emits a structured event for every row-level insert, update, or delete. Crucially, the application does not need to be aware of any of this. It keeps writing to its tables exactly as before, and the CDC connector reads the change events externally.

Debezium is the most widely adopted open-source CDC tool in the Java ecosystem. It runs as a Kafka Connect connector and streams change events to Kafka topics, which downstream services can then consume in real time.

# Debezium PostgreSQL connector configuration (connector.json)
# Deploy via Kafka Connect REST API:
# POST http://localhost:8083/connectors
{
  "name": "pg-orders-connector",
  "config": {
    "connector.class":              "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname":            "localhost",
    "database.port":                "5432",
    "database.user":                "debezium",
    "database.password":            "dbz",
    "database.dbname":              "shop",
    "topic.prefix":                 "shop",
    "table.include.list":           "public.orders",
    "plugin.name":                  "pgoutput"
  }
}

Once that connector is running, every change to the orders table is automatically published to the Kafka topic shop.public.orders as a structured event containing both the before and after state of the row. Downstream consumers — an analytics service, a search indexer, an audit log — subscribe to that topic and react accordingly.

A single business action — say, “transfer $100 from account A to account B” — may produce several CDC events: a debit on one row, a credit on another, a transfer record insert. CDC sees the rows; it does not inherently understand the business transaction that caused them.

The Fundamental Difference

The cleanest way to state the core distinction is this:

Event Sourcing

Events are written by the application
Events are the primary persistence
Current state is derived from events
Domain semantics are baked into event names
Requires redesigning your data model

Change Data Capture

Events are read from the database log
Database state is still primary
Events are derived from database writes
Events carry row-level, not domain-level, semantics
Zero application changes required

As Streamkap puts it well: in true Event Sourcing, events are the primary artifact and database state is derived. With CDC, database state is primary and events are derived. That reversal of cause and effect explains nearly every practical difference between the two.

Side-by-Side Comparison

Dimension	Event Sourcing	CDC (e.g. Debezium)
Where it lives	Application layer	Database / infrastructure layer
Application changes needed	Yes — significant redesign	No — transparent to app
Event semantics	Rich domain events (`OrderShipped`)	Raw data changes (`UPDATE orders SET status='shipped'`)
Full history replay	Yes — events are the store	Limited by log retention
Audit trail quality	Excellent — intent is captured	Good — data changes only
Retroactive migration	Very hard on existing systems	Easy to bolt on existing systems
Operational complexity	High	Medium
CQRS compatibility	Natural fit	Works well with Outbox pattern
Typical tooling (Java)	Axon, EventStoreDB, Eventuate	Debezium + Kafka Connect

The Outbox Pattern: Bridging Both Worlds

One of the most practically useful combinations is running CDC on top of an Outbox table. This is where the two patterns genuinely complement each other, and it is increasingly the recommended approach for teams who need domain event semantics without fully committing to an Event Sourcing data model.

The idea is straightforward: your application writes its domain events into a dedicated outbox table as part of the same database transaction that updates the primary state. A CDC connector then reads that outbox table and publishes the events to Kafka. The result is domain-semantic events with transactional guarantees — and no dual-write problem.

-- The outbox table in PostgreSQL
CREATE TABLE outbox_events (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    aggregate_id  VARCHAR(255) NOT NULL,
    event_type    VARCHAR(255) NOT NULL,
    payload       JSONB         NOT NULL,
    created_at    TIMESTAMPTZ   NOT NULL DEFAULT NOW()
);

-- In your Spring service: both writes in one transaction
@Transactional
public void shipOrder(Long orderId) {
    Order order = orderRepo.findById(orderId).orElseThrow();
    order.setStatus("SHIPPED");
    orderRepo.save(order);

    outboxRepo.save(new OutboxEvent(
        order.getId().toString(),
        "OrderShipped",
        "{\"orderId\":" + orderId + ",\"shippedAt\":\"" + Instant.now() + "\"}"
    ));
    // Debezium picks up the outbox row and publishes to Kafka automatically
}

Debezium even ships an Outbox Event Router transform that routes events to different Kafka topics based on the aggregate_id or event_type columns, so you do not end up with a single firehose topic for all events.

It gives you domain-semantic events and at-least-once delivery with no distributed transaction, no dual-write race condition, and no application-level retry logic. For most microservice architectures, this is simpler than full Event Sourcing while delivering most of the same downstream benefits.

Comparing Complexity Over Time

One chart worth looking at is how each approach’s operational complexity evolves as a system grows. Event Sourcing starts expensive and stays demanding; CDC starts cheap but can accumulate complexity as your schema and event consumer count scales.

Relative Operational Complexity by System Scale

Illustrative complexity scores (1–10) at five growth stages. Based on reported engineering effort across documented production cases.

When to Choose Event Sourcing

Event Sourcing is a strong fit when the history of intent is a first-class requirement — not just “what changed” but “why, in what sequence, and who requested it.” However, it imposes real costs, so the use case needs to justify the redesign.

Choose Event Sourcing when…

You need a complete, tamper-evident audit trail — legal, financial, or compliance scenarios where the sequence of decisions matters.
Your domain logic involves temporal queries: “what was the state of this entity on this date?”
You are building a new greenfield service and the team is comfortable with CQRS and event-driven design.
Business events carry rich semantic meaning that CDC row events cannot capture (ClaimApproved vs UPDATE claims SET approved=true).
You need the ability to correct past events and reproject read models — event replay is a first-class feature.

When to Choose CDC

CDC shines in integration and data propagation scenarios, especially when you need to connect systems that already exist and cannot be rewritten. Because it requires zero application changes, it is also the most pragmatic choice for teams that want event-driven integration without taking on architectural debt.

Choose CDC when…

You need to replicate data from an existing CRUD service to downstream consumers (analytics warehouse, search index, caching layer) without changing that service.
You are retrofitting event-driven patterns onto a legacy system.
Your team is comfortable with Kafka and Kafka Connect but not ready for a full Event Sourcing architecture.
Data synchronization and replication are the primary goals, and row-level semantics are sufficient.
You want to implement the Outbox pattern to guarantee event delivery without dual-write complexity.

When to Use Both Together

Use both when…

Event-sourced aggregates need to propagate their events to external systems — CDC on the event store’s projection tables bridges the gap.
A system has both greenfield event-sourced services and legacy CRUD services that must share a single event bus.
You want domain events from the Outbox pattern with CDC providing the reliable transport layer.

Tooling Landscape for Java Teams

Tool	Pattern	Spring Boot Integration	Notes
Debezium	CDC	Spring Cloud Stream, Kafka Connect	Most mature open-source CDC; supports PostgreSQL, MySQL, MongoDB, Oracle and more
Axon Framework	Event Sourcing	Native Spring Boot starter	Full CQRS + Event Sourcing framework; pairs with Axon Server as event store
EventStoreDB	Event Sourcing	Via Java client library	Purpose-built event store; strong projections support
Eventuate Tram	Outbox + CDC	Spring Boot starter available	Specifically designed around the Transactional Outbox pattern with CDC
Kafka + Custom Outbox	Outbox + CDC	Spring Kafka, spring-tx	Maximum control; higher setup cost

Adoption Trends: Where Teams Are Investing

Based on community signals — GitHub stars, conference talks, and job postings — it is clear that CDC and the Outbox pattern have significantly broader adoption among Java teams than full Event Sourcing. Event Sourcing remains the right choice in specific bounded contexts, but it is rarely the default starting point for new services.

Relative Adoption Signal Across Java Ecosystem (2024–2025)

Normalized index based on GitHub stars, conference talks, and StackOverflow activity. Higher = more community momentum.

A Quick Decision Tree

If you are still unsure which path to take, the following set of questions will usually narrow it down quickly:

Do you need to derive business intent from the events? If yes and the system is new → Event Sourcing. If yes and the system is existing → Outbox + CDC.
Are you integrating with existing services you cannot change? → CDC.
Is the audit trail a legal or compliance requirement? If intent matters → Event Sourcing. If data changes are sufficient → CDC.
Does your team have event-driven architecture experience? If not → start with CDC and the Outbox pattern; it is significantly easier to introduce.
Are you building a new greenfield bounded context where history replay is a first-class feature? → Event Sourcing is a strong candidate.

The engineers behind Debezium have written directly about this: CDC with the Outbox pattern is usually a better alternative to full Event Sourcing and is compatible with CQRS. Event Sourcing still has value in some use cases, but they encourage trying the Outbox approach first.

What We Learned

Event Sourcing and CDC are not competing solutions to the same problem — they operate at entirely different layers of a system. Event Sourcing is an application design pattern where events are the primary persistence artifact, giving you rich domain semantics, full replay capability, and a complete audit trail of intent. CDC is a database infrastructure technique that reads the transaction log and streams row-level changes to downstream consumers, requiring zero application changes and fitting naturally onto existing CRUD systems.

For most Java teams, CDC with the Transactional Outbox pattern is the pragmatic starting point: you get at-least-once event delivery, domain-semantic events, and no dual-write problem — without the significant architectural cost of fully embracing Event Sourcing. Event Sourcing earns its keep in greenfield bounded contexts where temporal queries, complete audit trails, and event replay are genuine requirements, not just aspirational ones. When in doubt, reach for Debezium and an Outbox table first, and layer Event Sourcing into specific aggregates only where the domain truly demands it.

Tags

Spring HATEOAS + OpenAPI 3.0: Why Links Don’t Appear in Swagger UI

Eleftheria Drosopoulou — Tue, 23 Jun 2026 15:49:00 +0000

Enterprise Java

Spring HATEOAS + OpenAPI 3.0: Why Links Don’t Appear in Swagger UI

You built a perfectly valid HAL response, opened Swagger, and the _links are simply… gone. Here is exactly why that happens and how to fix it for good.

If you have spent any time combining Spring HATEOAS with springdoc-openapi, you have almost certainly hit the wall: your REST endpoint returns a beautifully structured HAL payload at runtime, but Swagger UI shows something completely different — or worse, it shows the raw internals of EntityModel instead of your clean _links map. As a result, your API consumers get misleading documentation. So, let’s dig into why this happens and, more importantly, how to get past it.

The Problem in Plain Language

Before we jump into solutions, it is worth understanding what is actually going on under the hood. Spring HATEOAS serializes responses using custom Jackson modules that transform EntityModel<T> and CollectionModel<T> into the well-known HAL (Hypertext Application Language) format at runtime. The resulting JSON looks something like this:

{
  "id": 42,
  "name": "Laptop",
  "_links": {
    "self": { "href": "/api/products/42" },
    "category": { "href": "/api/categories/electronics" }
  }
}

That looks great in Postman or a browser. However, the springdoc schema generator runs at application startup — before any request is made — and it inspects the raw Java class structure. Since it does not invoke the Jackson serializers at that point, it sees EntityModel‘s internal field named links (a plain Java collection) rather than the HAL-mapped _links object. The gap between what the serializer produces and what the schema generator sees is the root cause of everything that follows.

springdoc reads class structure at startup. Spring HATEOAS serializes data at request time. These two worlds never directly talk to each other unless you wire them up.

The Three Most Common Symptoms

Depending on how your project is set up, the broken documentation typically shows up in one of three ways. Recognizing which one you are dealing with saves a lot of debugging time.

What Swagger Shows	What It Actually Means	Severity
`links` as an array of full `Link` objects	springdoc is reading the raw Java class, not HAL serialization	Misleading
`_links` shown as array instead of object/map	Schema type mismatch — HAL expects an object keyed by rel name	Wrong schema
No `_links` field at all	Missing HATEOAS module dependency or incorrect return type hint	Invisible

Additionally, you might also encounter _embedded showing up as content on CollectionModel responses, which breaks HAL consumers who rely on the underscore-prefixed convention. All of these issues share the same underlying cause, so fortunately they also share similar fixes.

Fix 1: Add the Correct Dependency

This one sounds obvious, but it catches a surprising number of teams. The standard springdoc-openapi-starter-webmvc-ui does not automatically activate HATEOAS-aware schema generation. You need to ensure you are also pulling in spring-boot-starter-hateoas, and more specifically that you are using the right springdoc starter for your context.

For a Spring Boot 3.x project using Spring MVC, your pom.xml should look like this:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.8.4</version>
</dependency>

When spring-boot-starter-hateoas is on the classpath, springdoc’s autoconfiguration detects it and activates OpenApiHateoasLinksCustomizer automatically — provided you are on springdoc 2.x. On version 1.x, you also needed a separate springdoc-openapi-hateoas artifact; that separate module was folded into the core starter in v2.

If you are still on Spring Boot 2 and springdoc 1.x, you explicitly need to add springdoc-openapi-hateoas as a separate dependency. Without it, HATEOAS schema support simply does not activate.

Fix 2: Return the Right Types from Your Controller

springdoc infers the schema entirely from the method return type. Consequently, if your controller returns ResponseEntity<?> with a wildcard, or if you are returning a raw domain object that you happen to wrap inside a EntityModel later, springdoc misses the HATEOAS wrapper entirely.

The fix is straightforward — always be explicit with your generics:

// Avoid — springdoc cannot infer the schema
@GetMapping("/products/{id}")
public ResponseEntity getProduct(@PathVariable Long id) {
    Product product = service.findById(id);
    return ResponseEntity.ok(EntityModel.of(product));
}

// Preferred — explicit type lets springdoc map the schema correctly
@GetMapping("/products/{id}")
public EntityModel<Product> getProduct(@PathVariable Long id) {
    Product product = service.findById(id);
    return EntityModel.of(product,
        linkTo(methodOn(ProductController.class).getProduct(id)).withSelfRel(),
        linkTo(methodOn(CategoryController.class).getCategory(product.getCategoryId())).withRel("category")
    );
}

Equally important: for collections, return CollectionModel<EntityModel<Product>> rather than List<EntityModel<Product>>. springdoc knows how to unwrap the nested generics and generate the correct _embedded structure when you are specific.

Annotating with @Operation and @ApiResponse

Sometimes the return type alone is not enough — especially when you use ResponseEntity for HTTP status control. In those cases, complement your method signature with a Swagger annotation to spell out exactly what the response looks like:

@Operation(summary = "Get a product by ID")
@ApiResponse(responseCode = "200",
    content = @Content(schema = @Schema(implementation = ProductEntityModel.class)))
@GetMapping("/products/{id}")
public ResponseEntity<EntityModel<Product>> getProduct(@PathVariable Long id) {
    // ...
}

This combination gives springdoc an unambiguous signal about the schema, so the generated documentation reliably reflects your actual HAL output.

Fix 3: Understand the _links vs links Naming Gap

Even after the above fixes, you may notice that Swagger still shows the field as links (no underscore) rather than _links. This is because, as reported in the springdoc issue tracker, the schema generator reads the Java field name rather than the HAL-serialized name.

springdoc 2.x with HATEOAS autoconfiguration should handle this automatically via its built-in OpenApiHateoasLinksCustomizer. However, if you still see plain links in the schema, you can register a customizer bean yourself to fix the field name:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenApiCustomizer hateoasLinksCustomizer() {
        return openApi -> openApi.getComponents()
            .getSchemas()
            .forEach((name, schema) -> {
                if (schema.getProperties() != null
                        && schema.getProperties().containsKey("links")) {
                    var linksSchema = schema.getProperties().remove("links");
                    schema.getProperties().put("_links", linksSchema);
                }
            });
    }
}

This walks the generated component schemas and renames the links property to _links everywhere it appears. As a result, your Swagger UI will finally mirror the actual HAL payload your API produces.

After the fix your Swagger schema should show _links as an object with string keys mapping to link objects — matching what HAL actually delivers at runtime.

How the Schema Should Look After Fixing

With all the above pieces in place, the OpenAPI schema for a EntityModel<Product> response should end up looking like this in the generated v3/api-docs output:

{
  "EntityModelProduct": {
    "type": "object",
    "properties": {
      "id": { "type": "integer", "format": "int64" },
      "name": { "type": "string" },
      "_links": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/Link"
        }
      }
    }
  },
  "Link": {
    "type": "object",
    "properties": {
      "href":      { "type": "string" },
      "templated": { "type": "boolean" }
    }
  }
}

Notice that _links is an object with additionalProperties referencing Link — not a flat array. That is the correct HAL representation and the one that will render properly in Swagger UI.

The Serialization Gap at a Glance

The chart below visualizes how the divergence between springdoc’s schema generation and Spring HATEOAS runtime serialization leads to documentation drift, and at which layer each fix operates.

Where Documentation Drift Happens

Comparison of what each layer produces vs. what Swagger receives — before and after fixes

Common Edge Cases to Watch Out For

PagedModel and pagination links

If you use PagedModel<EntityModel<T>>, springdoc should also show the pagination links (first, prev, next, last) in the schema. However, this only works when spring-boot-starter-hateoas is properly detected. If you do not see them, double-check that your return type uses PagedModel explicitly rather than Spring Data’s Page.

Custom RepresentationModel subclasses

When you extend RepresentationModel<T> directly to create a custom representation, springdoc may generate the _links field as an array instead of a map — especially on subtypes using @Schema(allOf = ...). This is a known issue tracked in the springdoc repository. The workaround is to annotate the _links property explicitly with @Schema to override the generated type:

public class ProductModel extends RepresentationModel<ProductModel> {

    private String name;
    private String sku;

    @Schema(description = "HAL links map",
            additionalPropertiesSchema = @Schema(ref = "#/components/schemas/Link"))
    @JsonProperty("_links")
    public Links getLinks() {
        return super.getLinks();
    }
}

HalConfiguration and single-link arrays

If you have configured HalConfiguration to render single links as arrays rather than objects, your runtime payload changes shape — and the default springdoc schema will be wrong again. In that case, you need a custom OpenApiCustomizer that also adjusts the _links additionalProperties to accept an array of Link.

Dependency Compatibility at a Glance

Getting the right dependency versions together is half the battle. The following table summarizes the tested combinations that produce correct HATEOAS documentation:

Spring Boot	springdoc-openapi	HATEOAS module needed?	Status
3.2.x – 3.5.x	2.3.x – 2.8.x	No separate module — built in	Fully supported
2.7.x	1.6.x – 1.8.x	Yes — `springdoc-openapi-hateoas`	Supported (EOL)
3.x with springfox	n/a (springfox)	springfox does not support HATEOAS well	Avoid
Any	Any	Missing `spring-boot-starter-hateoas`	Links invisible

A Realistic Adoption Timeline

To give you a sense of how teams typically progress from broken to fully fixed documentation, the chart below shows an approximate timeline of issue discovery and resolution effort based on real reports in the springdoc and Spring HATEOAS repositories.

Developer Hours to Full Resolution — Typical Progression

Averaged across reported GitHub issues and community posts. Each bar represents cumulative effort at that stage.

Quick Diagnostic Checklist

Before you reach for a custom OpenApiCustomizer, it is worth running through this quick list to rule out the simpler causes first. In most cases, one of the first three items is all you need.

Is spring-boot-starter-hateoas in your pom.xml or build.gradle?
Are you on springdoc 2.x (not springfox) with Spring Boot 3.x?
Does your controller return an explicit generic type like EntityModel<Product> rather than ResponseEntity<?>?
Have you checked /v3/api-docs directly (not just Swagger UI) to see the raw generated schema?
If using @Schema(subTypes), are your subtypes annotated correctly without shadowing _links?

The official springdoc documentation covers the HATEOAS integration in detail. The Spring HATEOAS reference guide explains how serializers and link discoverers work under the hood — both are worth a read if you are building a production-grade hypermedia API.

What We Learned

The root of the Spring HATEOAS + Swagger problem is a timing mismatch: springdoc reads your class structure at startup, while Spring HATEOAS transforms it with custom Jackson serializers at request time. As a result, the two worlds produce different schemas unless you explicitly bridge them.

Throughout this article, we walked through the three most common symptoms — wrong field names, array vs. object mismatches, and invisible links.

We then covered the exact fixes: adding spring-boot-starter-hateoas, using explicit generic return types in controllers, registering an OpenApiCustomizer to correct field names, and handling edge cases like PagedModel and custom RepresentationModel subclasses. With all these pieces in place, your Swagger UI documentation will accurately reflect what your HAL responses deliver at runtime — which is the whole point.

Tags

A Guide to Designing APIs for AI Agents in the Age of AI

Omozegie Aziegbe — Tue, 23 Jun 2026 12:41:31 +0000

Software Development

A Guide to Designing APIs for AI Agents in the Age of AI

AI agents are changing how modern software systems are designed and consumed. Unlike traditional applications that rely on predictable, human-driven interactions, AI agents operate autonomously, making decisions, calling APIs, chaining multiple steps, and adapting based on the responses they receive.

This shift introduces a new reality: APIs are no longer just consumed by frontend apps or backend services; they are increasingly consumed by intelligent systems that reason, iterate, and act without direct human input.

As a result, designing APIs for AI agents requires a different mindset. It is not just about exposing data or functionality, but about creating systems that are understandable, predictable, and usable by machines capable of independent decision-making. This article explores some principles and patterns for designing APIs that AI agents can use.

1. Design APIs as Composable Tools

AI agents interact with APIs as tools rather than static endpoints. This means each API should represent a single, clearly defined capability that can be combined with others to achieve more complex goals.

Instead of building large, multi-purpose endpoints, the focus should be on small, atomic operations such as searching for data, retrieving specific records, or performing a single action. These simpler building blocks make APIs easier for agents to understand and use correctly.

This modular approach allows agents to chain calls together dynamically. For example, an agent might search for products, retrieve details for a selected item, and then create an order—all using separate endpoints. Designing APIs this way improves flexibility, reduces ambiguity, and aligns with how agents naturally break down problems into smaller steps.

2. Build a Strong OpenAPI Contract for AI Agents

A well-structured OpenAPI specification is one of the most important foundations for building APIs that work effectively with AI agents. It serves as a machine-readable contract that clearly defines what your API can do, how it should be used, and what kind of responses it returns. For AI systems, this structure removes uncertainty and makes it much easier to interact with your services predictably.

AI systems rely on OpenAPI specifications to automatically discover available endpoints, understand required parameters and their data types, and validate both request and response structures before making calls. This reduces trial-and-error behavior and allows agents to plan their actions more effectively when interacting with your API.

To make your API truly effective, all request and response schemas should be explicitly defined, with no missing or loosely described fields. It is also important to maintain consistent naming conventions and data typing across all endpoints. A precise OpenAPI specification reduces guesswork and enables agents to interact with your API more consistently and with greater accuracy.

3. Use Clear and Consistent API Design

Consistency is very important when designing APIs for AI agents. Unlike humans, AI agents do not rely on intuition or guesswork. They depend on clear and repeatable patterns to understand how a system works.

To improve usability, APIs should use predictable naming conventions such as getUserOrders or searchProducts, maintain consistent field names across all endpoints, and avoid vague or overloaded terms. When APIs follow a consistent structure, agents can more easily generalise from one endpoint to another, improving their ability to explore and use the system effectively.

4. Introduce an MCP Server for Agent Integration

An MCP (Model Context Protocol) server provides a structured interface between AI agents and your APIs. Instead of exposing raw endpoints directly, it presents them as standardised tools that agents can easily understand and interact with consistently.

This approach comes with several important benefits. It simplifies integration with AI frameworks, centralizes context handling, enforces access control and validation, and improves overall system reliability. It also helps reduce complexity when multiple agents or tools are involved in the same workflow.

By introducing an MCP layer, you make your API more accessible, organized, and better aligned with how modern AI systems operate. It creates a cleaner separation between raw backend logic and agent-facing capabilities, making the system easier to scale and maintain.

5. Design for Multi-Step Workflows

AI agents rarely solve problems in a single API call. Instead, they operate in iterative loops where each response informs the next action. Your API should support this by:

returning identifiers for follow-up actions
including enough context in each response
ensuring endpoints can be chained logically

For example, a product search endpoint should return product IDs that can be used in a details endpoint. This enables agents to move seamlessly from one step to the next. Designing with workflows in mind ensures that your API supports real-world agent behavior rather than isolated interactions.

6. Use Well-Defined and Recoverable Error Responses

Errors are unavoidable when working with AI agents because they operate in dynamic and sometimes unpredictable ways. However, how your API handles these errors can greatly influence how well an agent performs and recovers from failures.

Instead of returning vague or generic error messages, your API should provide structured error codes, clear and human-readable explanations, and indicators that show whether the error can be recovered from. It is also helpful to include suggestions that guide the agent toward correcting its input or adjusting its approach.

For example, instead of returning a plain message like “Invalid input,” a better response would be a structured format such as:

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "The search query cannot be empty.",
    "recoverable": true,
    "suggestion": "Provide a keyword or product name in the query field."
  }
}

With this level of clarity, agents can respond more intelligently to failures. They can retry with improved inputs, switch to alternative actions, or adjust their workflow instead of stopping completely. Well-designed error handling transforms mistakes into useful feedback that helps the agent improve its decision-making process.

7. Guide AI Agents with Clear Workflow Documentation

Beyond documenting individual endpoints, it is also important to provide higher-level guidance that helps AI agents understand how to use your API in real-world scenarios. Instead of only explaining what each endpoint does, you should also describe how they work together as part of complete workflows.

Good documentation should include common usage patterns, typical sequences of API calls, and clear recommendations for what an agent should do next after each action. This helps create a logical flow that agents can follow, rather than forcing them to discover relationships between endpoints through trial and error.

For example, after an agent retrieves a list of items from a search endpoint, the documentation can suggest calling a detail endpoint to get more information about a specific item or proceeding directly to an action like creating an order. This kind of guidance reduces ambiguity, improves decision-making, and helps agents interact with your API more efficiently and accurately.

8. Write Clear Metadata for LLM Understanding

AI agents rely heavily on metadata and descriptions to understand when and how to use an API. Because of this, metadata is just as important as the API itself, as it helps agents interpret the purpose of each endpoint before making a call. Each endpoint should include a clear name, a concise but meaningful description, detailed parameter explanations, and a proper usage context.

Instead of vague descriptions, focus on clarity and intent. For example, rather than saying “Get products,” explain that the endpoint is used to search and retrieve products based on user queries or filters. Well-written metadata improves tool selection, reduces errors, and helps AI agents map user intent to the correct API call more accurately.

In addition to in-API metadata, you can provide a /llms.txt file as a lightweight documentation layer for AI systems, as described at https://llmstxt.org/. This file serves as a simple entry point that summarises your API, highlights key endpoints, and guides to help LLMs quickly understand your system.

9. Design for Reliability, Safety, and Evolution

AI agents can behave in unpredictable ways because they operate autonomously and may generate repeated calls, unexpected inputs, or unusual sequences of actions. For this reason, your API must be designed to be highly resilient and capable of handling these variations without breaking or producing inconsistent results.

To achieve this, endpoints should be made idempotent wherever possible so that repeated requests do not create unintended side effects. Inputs should be strictly validated to prevent invalid or malformed data from affecting system stability. In addition, implementing rate limiting and strong access control helps protect your system from overload or misuse, while detailed logging of interactions supports effective monitoring, debugging, and performance analysis.

Your API should also evolve safely and predictably over time. This means using proper versioning strategies, maintaining backward compatibility, and avoiding breaking changes that could disrupt existing agent workflows. A reliable and secure API ensures that AI agents can operate consistently at scale while maintaining stable performance and predictable behavior over time.

10. Conclusion

Designing APIs for AI agents requires a shift from traditional thinking to a more dynamic, machine-centred approach. Instead of building APIs solely for human developers, you are now designing systems that intelligent agents will explore, interpret, and use autonomously.

The most effective APIs are not just functional—they are structured, descriptive, predictable, and resilient. They provide clear guidance, support multi-step reasoning, and handle uncertainty gracefully.

As AI agents continue to grow in capability and adoption, the quality of your API design will play a critical role in how effectively they can interact with your systems. By applying these principles, you can build APIs that are not only usable but truly intelligent-ready.

This article explored how to design APIs for AI agents.

Tags

Java Code Geeks

Top 9 Role-Based Cloud Certifications for Solution Architects in 2026

1. AWS Certified Solutions Architect – Associate (SAA-C03)

2. AWS Certified Solutions Architect – Professional (SAP-C02)

3. Microsoft Certified: Azure Solutions Architect Expert (AZ-305)

4. Google Professional Cloud Architect (PCA)

Quick Comparison: The Big Three Architect Certs

5. AWS Certified Security – Specialty (SCS-C02)

6. HashiCorp Certified: Terraform Associate (004)

7. Certified Kubernetes Administrator (CKA)

8. AWS Certified Machine Learning – Specialty (MLS-C01)

9. CISSP – Certified Information Systems Security Professional

Choosing the Right Path for Your Stage

What We Learned

Thank you!

How to Wait for Dynamic Content in Selenium Without Delays

1. Why Waiting is Hard in JavaScript-Heavy Applications

2. Understanding Selenium Wait Strategies

3. Waiting for Document Ready State

4. Waiting for AJAX Requests (jQuery)

5. Wait for JavaScript Framework Stability

6. Wait for Visibility + Interactivity

7. Combining Multiple Wait Conditions

8. Conclusion

9. Download the Source Code

Thank you!

[FREE EBOOKS] How to Do More with Less, 90 Days to Level Up Your Leadership & Four More Best Selling Titles

How to Do More with Less: Future-Proofing Yourself in an AI-driven Economy ($28.00 Value) FREE for a Limited Time

90 Days to Level Up Your Leadership ($22.00 Value) FREE for a Limited Time

Cloud Security Fundamentals: Building the Foundations for Secure Cloud Platforms ($131.95 Value) FREE for a Limited Time

The Vibe Coding Playbook: Building Your Tech Business with AI ($35.00 Value) FREE for a Limited Time

The Wellbeing Centered Workplace: 10 Strategies Fuelling Business Growth & Performance ($30.00 Value) FREE for a Limited Time

The Persuasion Engine: How Any Business Can Use AI-Powered Neuromarketing to Understand and Win Customers ($28.00 Value) FREE for a Limited Time

Thank you!

GIS Map Service Introduction in Java

1. Introduction

2. GIS

3. Prerequisites

3.1. JDK

3.2. Maven

3.3. Geotools

3.4. GeoServer

4. Selecting GIS Data for the Honolulu Region

5. Download GIS Data

6. GeoServer Configuration

6.1. Logging into GeoServer

7. Loading Honolulu GIS Data

7.1. Loading Honolulu SHP Data

1. Workspace Creation

2. Data Store Configuration and Shapefile Registration

3. Publishing a Layer and Configuring Spatial Reference

4. Completion and Verification (Layer Preview)

8. Understanding Web Map Services

8.1. WMS(Web Map Service)

8.2. WFS(Web Feature Service)

8.3. WPS(Web Process Service)

8.4. WMTS(Web Map Tile Service)

9. Simple WMS Client Application

9.1. Configuring the Client Environment

1. Batch File Configuration

2. Executing the Batch File

3. Verifying the Maven Environment

9.2. Configuring the Client Development Environment

9.3. Establishing the Maven Source Directory Layout

10. Implementing the GeoServer WMS Client

10.1. The Main Class

10.2. The MainFrame Class

10.3. The GeoServerClient Class

10.4. The MapPanel Class

10.5. The WmsLayerInfo Class

10.6. Build and Execution

11. Conclusion

12. Download Links

13. Trouble Shooting

14. Download the source code

Thank you!

OpenCV Android Object Detector

Table Of Contents

1. Introduction

2. Objectives

10.2. The `MainFrame` Class

10.3. The `GeoServerClient` Class

10.4. The `MapPanel` Class

10.5. The `WmsLayerInfo` Class