Good news: staying safe in Python’s world isn’t complicated. It’s just not obvious. Think of this as a friendly reminder to check the extension cable before plugging in another set of lights.

Pip Install vs. Mvn Install: A World of Difference

Java’s packaging has its flaws, but predictability isn’t one of them. Maven Central is curated. Group IDs enforce a namespace. When you fetch com.fasterxml.jackson.core:jackson-databind, you get that specific artefact from that particular organisation.

Python is radically different:

• A Flat Namespace: Package names are first-come, first-served on PyPI. Name collisions and typosquatting are primary attack vectors.
• A Trusting Resolver: The resolver is extremely trusting. It will often prioritise a higher version number from any available index, which is the core of dependency confusion attacks.

If you’re used to Java’s rules, Python’s model will trip you up. Please treat it with extreme care.

Be Suspicious of “pip install …”

Java developers might fall for an occasional fake install script; Python encourages them. The internet is full of “copy this pip install and trust me.” You shouldn’t accept that for a Maven dependency. Don’t accept it here.

If you see pip install my-cool-tool, ask the same questions you would for a new Maven dependency:

1. Who owns this package? (Check PyPI, GitHub activity, and developer reputation).
2. Does the name look close to something legitimate? (Guard against typosquatting: requests vs. requessts).
3. Is this the actual source, or a mirror?

Dependency Confusion in Python is embarrassingly easy. A malicious public package with the same name can hijack a private internal package called company-utils simply by having a higher version number. This is the default behaviour if not explicitly mitigated.

Your Checklist:

• Prefer explicit version pins. (e.g., requests==2.28.1).
• Prefer known sources. Use a private package registry like Artifactory or Nexus to proxy and cache PyPI, allowing your organisation to blacklist known bad packages and prioritise your internal packages. (It may sound like ‘corporate’, but it’s essential)
• Prefer tooling that uses a lock file.

Take Five Minutes to Learn Virtual Environments

You’ve probably ignored Python’s advice about virtual environments already. Don’t. This is the difference between a clean setup and a machine that slowly accumulates mysterious, conflicting modules.

A virtual environment gives you the isolation you take for granted in Java’s classpath model. Without it, you are installing every dependency into your system path.

Create one:

python3 -m venv .venv

source .venv/bin/activate

Now every pip install lives inside .venv, not your machine. This gives you reproducibility and enables cleaner scanners, policy checks, and SBOM generation.  (In fact, once you start using Python in more depth, you’ll realise you can’t live without this approach – so do the right thing and you’re future 2026 self will thank you)

Pin Your Dependencies. Really! Pin your dependencies.

In Java, you pin dependencies by default in your POM. Since transitive dependencies on Maven Central are immutable, you know the complete set upfront and permanently. In Python, if you don’t pin, you get drift. Packages can silently update, pulling in new transitive dependencies.

Most critically: Malicious actors publish higher-numbered versions to trick the resolver. If you use a loose constraint like package>=1.0.0, an attacker publishing package==99.99.99 can compromise your build.

• Use pip-tools, Poetry, or uv.
• Generate a lock file (your pom.xml equivalent).
• Add the lock file to source control.
• Use Hashes: Generate hashes for all dependencies. They are your final line of defence against tampered packages.

The Out-of-Support Trap: The Real Threat of Old Packages

Attackers don’t rely solely on brand-new exploits; they often compromise systems by manipulating developers (i.e., you) into installing old, vulnerable packages that are frequently out of support.

The workflow is:

1. Bad Actor publishes an old, vulnerable version (perhaps with malicious code added) or relies on an unmaintained package with a known CVE.
2. The vulnerable version is pulled in due to a loose dependency constraint (e.g., a sub-dependency requires old-library<2.0.0).
3. Your vulnerability scanner may catch the known CVE, but since the package is long out of support (its maintainers have moved on, or the version is too old), no patch exists.

The Cost:

• Vulnerability: You have a known exploit in your stack.
• Technical Debt: You now have to either fork and patch the unmaintained library yourself (probably a massive undertaking) or re-architect your application to use a different, supported library. You’ve essentially built a stack that’s immediately due for a costly rebuild.

Mitigation:

• Automated Scanners are Non-Negotiable: Use tools like Syft, Safety, Sonatype or Snyk to generate an SBOM and scan for known CVEs on every build.  (Do all security companies start with ‘S’?)
• Policy Checks: Block builds that rely on packages with severe, unpatched CVEs, or that use versions marked as “end-of-life” by the maintainer. Check for third-party maintainers too.  Not all open-source is abandoned. Sometimes it gets picked up and brushed down.
• Audit Your Transitives: The lock file is key. It lets you see the entire dependency graph, not just your direct requirements, and vet for ancient, risky components.
• Look for commercial support.  Strangely there are companies who work to keep you safe.  End-of-life support (not really what it sounds like) can often be found for those pesky out-of-support open source components you’ve just installed and now discovered need a fix.

Know What “Local Install” Actually Means

Python encourages local installs with instructions like pip install -e .. This installs the package “editable” from your working directory. While convenient for development, it means the installed code changes instantly whenever someone edits files on disk.

• Avoid in Production: This mutability is the last thing you want in a production flow. 
• Understand the Implications: Use editable installs only for local, feature-branch development, where mutability is a feature, not a bug.

If you don’t want to be on the leading edge, don’t do this!

Keep Your LLM Tools Contained

Many developers install Python only for LLMs. That’s fine, but keep those tools contained. LLM agents and model servers often run their own complex Python interpreters and download additional files.

• Isolation: Do not let your LLM workspace share a Python environment with your production scripts.
• Sandboxing: Do not run tools that download models or plugins without sandboxing (e.g., in a container or a dedicated VM).
• No curl | bash: Do not assume that “AI tool = harmless CLI.” Do not run shell-piped installers for model servers.  
• No curl | bash:  Hey, it’s the holidays, we can count things twice. Seriously, while pip install requirements.txt is a rich source of malware and compromised systems so is curl | bash.   Be very, very careful about using it to install software. Even if you think you trust the website or organisation involved.

Keep on the ‘nice’ list. 

Python gives you rope. Your established Java discipline is your best defence :

• Trust Nothing: Treat PyPI packages like third-party artefacts: verify their origin and security posture.
• Pin Everything: Go beyond version pinning to use lock files and dependency hashes.
• Automate Scans: Make SBOM generation and CVE scanning mandatory in your CI/CD pipeline.
• Environments as Cattle: Use virtual environments or containers, and frequently rebuild them to ensure a clean, reproducible state.

If you stick to these Java security principles, Python becomes far less chaotic and much more manageable.

Have a great holiday season and keep your software safe

The post Santa’s Python Pitfalls: A Java Developer’s Guide to Staying Safe This Christmas appeared first on JVM Advent.

What if you could embed native‑level capabilities into your Java applications, think of database engines, scripting runtimes, policy interpreters, even compilers and still remain pure Java, with no JNI, no native binaries, no concerns about OS or architecture compatibility? That is the promise of combining WebAssembly (Wasm) with the zero dependencies runtime Chicory.

The year 2025 feels like a turning point for this model. Chicory is no longer just an advanced exercise or a runtime prototype. It is powering a growing ecosystem of real‑world Java libraries. “Embed once, run anywhere” is no longer a slogan, it is becoming practical. In this post, we will explore why Chicory matters, what has been built upon it so far, and why you (as a Java developer or architect) should care today.

What is Chicory and why it matters

Chicory is a JVM‑native WebAssembly runtime. It allows you to run Wasm modules with zero native dependencies or JNI. As long as the JVM runs, the Wasm‑derived code runs.

Most existing Wasm runtimes (for example V8, Wasmtime, Wasmer, Wasmedge) are often written in C/C++/Rust. Embedding them in a Java application requires shipping native binaries for every supported platform, complicating distribution and deployment.

By contrast, Chicory eliminates that burden. You just depend on a JAR. This design brings structural advantages:

• Portability: if the JVM can run, the same Wasm module can run everywhere. No need to build per OS or architecture.
• Sandboxing and JVM integration: the Wasm module executes inside the JVM sandbox, on a managed isolated heap, preserving JVM memory safety, garbage collection, observability, tooling.
• Simplicity: no external native dependencies, no packaging matrix across OS/architecture, no JNI trouble.

Chicory re-imagines the classic “write once, run anywhere” Java promise. It extends it beyond Java bytecode, enabling WebAssembly modules that let you embed seamlessly powerful native features, while staying inside the JVM.

Chicory execution modes: flexibility for development and production

One of the strengths of Chicory is that it supports multiple ways of executing Wasm modules, letting you choose the trade‑off between portability and performance.

Here is an overview:

With the release of Chicory 1.4.0, the compiler (both runtime and build‑time) and the annotations system became stable.

More recently, Chicory 1.6.0 added support for the Java Platform Module System (JPMS), a directory‑backed runtime‑compiler cache (improving startup for repeated module loads), enhanced support for the Wasm “Threads” proposal(atomic fence instructions and atomic ops), increased Wasm spec conformance and verified compatibility with Java 25.

Thanks to this flexibility, libraries and applications can choose the mode that fits their use case: from dynamic scripting in dev to high‑performance embedded Wasm in production.

Real‑world “native‑free” tools built on Chicory

One of the strongest signals that the Wasm‑on‑JVM model is maturing is the growing number and quality of real libraries now using Chicory.

Here are some of the most notable:

QuickJs4j: a sandboxed JavaScript runtime for Java. QuickJS (originally a C engine) is compiled to WebAssembly, then Chicory compiles that Wasm into pure Java bytecode. The result is a small, self‑contained JAR runtime.

QuickJs4J’s is already powering the Microcks JavaScript dispatcher and Apicurio’s Registry custom artifact types.

SQLite4j: a pure‑Java SQLite JDBC driver. SQLite (originally written in C) is compiled to WebAssembly, then translated via Chicory to JVM bytecode. This allows embedding the full power of the most used lightweight SQL database inside Java without the need to ship native binaries.

Opa‑java‑wasm: is the WebAssembly-powered version of the policy engine Open Policy Agent (OPA), delivered for Java via Chicory. It powers in-process OPA policy evaluation removing the network calls required by more traditional integrations and, again, no native dependencies.

Beyond these, the “Who uses Chicory?” list includes many other use cases: user-defined functions for data engines, plugin systems, scripting inside data frameworks and more.

These are not toy examples. They deliver widely relevant capabilities: a JavaScript runtime, an embedded database and a policy engine. They show that Wasm + JVM is not just a thought experiment; it is already powering production‑ready tools.

Why this matters for Java developers and enterprises

For years, Java developers have accepted a painful tradeoff: whenever you needed to interact with libraries originally written in system programming languages, you ended up either rewriting the full thing or using JNI, FFI, native binaries, and OS/architecture‑specific builds. Packaging, deployment complexity, native-library hell became a recurring burden.

Chicory changes that math. With Wasm + Chicory + appropriate libraries, you can embed powerful functionality without leaving the JVM or shipping native dependencies.

New architectural patterns are emerging: plugin systems, embedded scripting engines, user-provided logic, sandboxed extensions, policy engines can now run within a JVM and with a controlled ABI surface.

For enterprise and cloud‑native applications, this significantly reduces operational complexity, simplifies deployment across environments and improves maintainability enabling wider code re-use.

Where things stand: momentum, community and next steps

The ecosystem around Chicory is gaining tangible momentum. With stable compiler support, modularity, improved performance, cache support, and a lot of emerging libraries and integrations, the year 2025 feels like the moment when this technology shifted from “experimental runtime” to a useful building block.

Now is a great time to try things out!
Try embedding a Wasm‑compiled module into your Java project using Chicory and help us shape the future of native‑free, polyglot tooling for the JVM.

Conclusion: reimagining “write once, run anywhere” for modern needs

Chicory re-imagines Java’s classic “write once, run anywhere” promise:extending it beyond Java bytecode to WebAssembly modules compiled into JVM bytecode. With Chicory, you can embed powerful, native‑level capabilities inside Java applications, while retaining the safety, portability and simplicity of pure Java.

If you are a Java developer or architect still wrestling with native dependencies or painfully shipping platform‑specific binaries perhaps it is time to look again. Chicory and the growing ecosystem of libraries around it shows that you can have your cake and eat it too.

Give it a try now. The future of native‑free, polyglot-powered Java tooling may depend on it.

The post Bring WebAssembly to the JVM. How Chicory Is Powering a New Generation of Java Libraries appeared first on JVM Advent.

What is Cursor Agent CLI in a Pipeline context?

In August 2025, Anysphere released Cursor Agent CLI, a new way to interact with frontier models but not coupled with a particular IDE. With this local development approach, the software engineer added a new way to enrich the development experience, but what happens if we use this product in a pipeline? In that case, we will add new capabilities.

Let’s review the following pipeline to understand the concept:

name: Run Cursor Agent on Demand

on:

  workflow_dispatch:

jobs:

  agent-on-demand:

    runs-on: ubuntu-latest
    timeout-minutes: 5

    permissions:

      contents: write

      pull-requests: write

    steps:

      - name: Checkout repository

        uses: actions/checkout@v6

        with:

          token: ${{ secrets.GITHUB_TOKEN }}

          fetch-depth: 0


      - name: Install Cursor CLI

        run: |

          curl https://cursor.com/install -fsS | bash

          echo "$HOME/.cursor/bin" >> $GITHUB_PATH


      - name: Run Cursor Agent

        env:

          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}

        run: |

          echo "=== User Prompt:===";

         PROMPT="Develop a classic Java class HelloWorld.java program that print Hello World in the console only"

          echo "$PROMPT";

          echo "=== Cursor Agent Execution:===";

          echo "";

          cursor-agent -p "$PROMPT" --model auto


      - name: Create PR with changes

        env:

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}

          GITHUB_REPOSITORY: ${{ github.repository }}

          GITHUB_ACTOR: ${{ github.actor }}

        run: |

          chmod +x .github/scripts/create-pr.sh

          .github/scripts/create-pr.sh

In a few lines of code, a pipeline is able to execute a task with the help of Frontier models and at the end of the process, submit a PR to be reviewed by the team.

Once you have a clear idea about how to start working with this product, let’s jump to the second product released, Cursor Cloud Agent.

What are Cursor Cloud Agents?

In October 2025, Cursor Cloud Agents was released, and it provides a collection of REST endpoints to handle the service. The different resources are organized into 3 categories:

• Agent Management (Launch, Follow up, Stop & Delete)
• Agent Information (Status, Conversation & List of Agents)
• General Information (Models, Repositories & API keys)

Using this service, you can delegate tasks to frontier models, but all operations run on Cursor cloud infrastructure, not in your pipelines like with Cursor Agent CLI.

As the service provides different REST endpoints, it is important to understand the minimum concepts to orchestrate tasks with them.

Understanding the lifecycle of a Cursor Cloud Agent request

Step 1: Launching a new AI Agent

When a user want to use this service, launch a HTTP POST request to provision a new cloud AI agent, the service will require the following information:

• A valid Github/Gitlab repository to operate with permissions
• A user prompt with the clear goal to be achieved
• An available frontier model to process your user prompt
• A Cursor API Key to authenticate the request and validate if the user has permissions to operate with the required Git repository.

Note: In this article we will put focus on Prompts based on Text plain, not images.

Once the User sends the request, the service will return a HTTP response with status code 201 indicating that the request was received and the service will be processed soon, an Agent-ID which is pretty useful to be used with other REST resources to track the progress and an Agent State, in this case, CREATING.

Note: You could track the whole process here in a visual way: https://cursor.com/agents 

What happens under the hood?

Once the service receives the request, it will provision an EC2 instance running in AWS region us-east-1 with the following features:

• OS: Linux Distro
• Cores: 4 cores
• Memory: 16GB
• Disk: 126GB HDD
• Java: Java 21

Inside this Linux container, the service will perform a git checkout operation of the git repository described in the request, and after that, it will start working on the details described in the user prompt.

As you can observe, the request receives a fast response, but the whole process is asynchronous. So how do you track the progress of your user prompt as it works on your repository?

Step 2: What is the status of my AI Agent?

An AI Agent has the following states:

• RUNNING
• FINISHED
• ERROR
• CREATING
• EXPIRED

If you remember from the first step, the AI Agent returned the state CREATING, and if everything goes well, the current state should now be RUNNING. But how do you know what the real status is? For that purpose, there exists a GET endpoint to receive the status from an Agent ID.

By calling the status endpoint periodically, the user/process can know when the AI Agent has changed the state to FINISHED.

Once the AI Agent is in a FINISHED state and the process has changed anything in the git repository, it will execute internally a git commit & git push to a feature branch and will create a PR to be reviewed.

Finally we have our lovely Hello World in the repository:

package info.jab.examples;

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

Step 3: Review the pull request

Once Cursor Cloud Agent reaches the goal specified in the user prompt, the service will create a PR in the repository to be reviewed by your team, independent of your Git branch strategy like Trunk-Based Development, Gitflow, or similar.

When to choose Cursor Agent CLI and when to choose Cursor Cloud Agents?

Exploring new technologies always has a cost. Let’s list a few factors to help in your decision-making:

• Complexity of the scenario to automate: If the scenario to delegate is easy, like a simple task or a sequence of operations, Cursor Agent CLI could be the first option. On the other hand, if you need to model a process that behaves like a state machine or a directed graph, Cursor Cloud Agents offer better options because they provide more granular control of the execution.
• Experience with AI agents in the team: If you are starting with AI Agents, Cursor Agent CLI could be the first option to run a pilot because it requires less effort to start and receive results.
• Pipeline capacity: Depending on the pipeline capacity, you might consider whether to run the operations in your pipelines or outside.
• Costs: Both products use the same subscription, so the cost structure is the same today.
• Tooling: Frontier models use tools to interact in the environments where they operate. Currently, Cursor Agent CLI has support for MCP, but this feature is not available in Cursor Cloud Agents. An important question might be: Why do you need MCP for everything? A CLI interface might be enough.
• Observability: If observability is a critical factor, Cursor Cloud Agents provides a specific endpoint to retrieve the internal agent conversation. This approach is useful for analysis in case of errors.

Until now, we have reviewed the way to execute user prompts by comparing 2 products, but in both cases, you can decouple the location of your prompts from the location of the execution. In the next sections, we will explore aspects of user prompts that will help you be more efficient and maintain them with less effort.

Developing great user prompts

Until now, we have only explained the output of the service—in the previous case, the creation of a Java class that writes to the terminal’s standard output. But how do you increase efficiency in the process? It’s simple: send a request with a user prompt that minimizes ambiguity to reach the defined goals.

An initial Hello World user prompt

You might think that a good user prompt could be:

Develop a classic Java class HelloWorld.java program
that prints "Hello World" in the console only.

And nothing more. But in practice, this idea—which apparently seems very easy—could be interpreted by frontier models in several ways, independent of which frontier model is used, because frontier models have non-deterministic behavior and may have doubts about:

• The location of the Java class
• The approach to compile the class (javac or using a build system)
• Whether they need to commit .class files
• Whether they need to use System.out.println or IO.println (Java 25+)

If you understand the potential problems on the frontier model side, let’s iterate on this user prompt.

Moving away from plain text user prompts

When you use modern IDEs with AI features and the frontier model doesn’t return the expected result, you continue the conversation, and after a few iterations, the result is as expected. But when using this kind of service running in your pipelines where you expect accurate results, you need to define restrictions and other details clearly to achieve your goals. So little by little, that user prompt will require some structure to operate accurately.

Encoding your User prompts in PML format

PML is the acronym for Prompt Markup Language, an XML Schema designed to help software engineers describe user prompts accurately.

Take a look at the evolution from plain text to PML with the new sections:

Text plain:

Develop a classic Java class HelloWorld.java program
that prints "Hello World" in the console only.

XML with PML Schema:

<?xml version="1.0" encoding="UTF-8"?>
<prompt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xsi:noNamespaceSchemaLocation="https://jabrena.github.io/pml/schemas/0.3.0/pml.xsd">

    <role>
        You are a Senior software engineer with extensive         experience in Java software development
    </role>

    <goal>
        Develop a classic Java class HelloWorld.java program
        that print "Hello World" in the console only
    </goal>

    <constraints>
        <constraint-list>
            <constraint>The develop the class in the Maven module `sandbox`</constraint>
            <constraint>The develop the class in the package info.jab.examples</constraint>
            <constraint>Do not create any test class</constraint>
            <constraint>Do not touch the build file (pom.xml)</constraint>
        </constraint-list>
    </constraints>

    <output-format>
        <output-format-list>
            <output-format-item>Don not explain anything</output-format-item>
        </output-format-list>
    </output-format>

    <safeguards>
        <safeguards-list>
            <safeguards-item>Build the solution with Maven Only</safeguards-item>
        </safeguards-list>
    </safeguards>

    <acceptance-criteria>
        <acceptance-criteria-list>
            <acceptance-criteria-item>The solution is compiled successfully with `./mvnw clean compile -pl sandbox`</acceptance-criteria-item>
            <acceptance-criteria-item>The solution only prints "Hello World" in the console</acceptance-criteria-item>
            <acceptance-criteria-item>Only commit java sources only and push the changes to the branch to create the PR</acceptance-criteria-item>
        </acceptance-criteria-list>
    </acceptance-criteria>
</prompt>

Although we have increased the number of lines, now the user prompt look robust and we have mitigated the ambiguity and now it has a better structure and it will be easier to maintain in the future with new refinements.

• User prompt
  • Role
  • Goal
  • Restrictions
  • Output format
  • Safeguards
  • Acceptance criteria

Once you have created the document, it can be validated with the XML Schema and later transformed to another format like Markdown.

Here is the result converted into Markdown:

## Role

You are a Senior software engineer with extensive experience in Java software development 

## Goal 

Develop a classic Java class HelloWorld.java program 
that print "Hello World" in the console only 

## Constraints 

- The develop the class in the Maven module `sandbox` 
- The develop the class in the package info.jab.examples 
- Do not invest time in planning 
- Do not create any test class 
- Do not touch the build file (pom.xml) 

## Output Format 

- Don not explain anything 

## Safeguards 

- Build the solution with Maven Only 

## Acceptance Criteria 

The goal will be achieved if the following criteria are met: 

- The solution is compiled successfully with `./mvnw clean compile -pl sandbox` 
- The solution only prints "Hello World" in the console 
- The solution is committed and pushed to the branch to create the PR 
- Only commit java sources only and push the changes to the branch to create the PR

Using XML as the source format for your user prompts, you could use the composability features that XML includes. On the other hand, when creating or updating PML files, you always create files with the same syntax, so your prompts will be homogeneous at scale.

What happen if something goes wrong?

Don’t be naive—even the most complex systems in the world, like nuclear plants, have incidents in different ways, so why wouldn’t this kind of integration have them too? Let’s explore different types of issues that your threat model plan should cover in your projects using this kind of technology.

Scenario: using Cursor Agent cli from a Pipeline

Imagine the scenario where you delegate a task to Cursor Agent CLI in the execution of your pipeline. What issues could happen?

Scenario: Using Cursor Agent CLi from the pipeline

Issues at Pipeline Level

• Third-party dependencies: If your pipeline is too complex, the global reliability may suffer. Review the chain of dependencies to simplify your pipeline and avoid runtime issues. Log runtime issues with third-party dependencies. Using a predefined Docker image could reduce the number of runtime issues.
• Unexpected files included in the PR: When frontier models try to resolve the goals described in the user prompt, they sometimes need to create scripts, extra files, or simply store files for analysis and debugging. Refine your user prompts to specify exactly what files and file extensions are valid; another alternative is to combine this with .gitignore files.

Issues at Cursor Agent CLI Level

• Cursor Agent CLI doesn’t make progress: This is rare, but you may not see execution progress due to different runtime issues. For such cases, it is important to define realistic timeouts for the pipeline step that involves this integration.
• Cursor Agent CLI enters a loop: Sometimes, if you send an unclear or unrealistic user prompt, the process may enter a loop. To avoid this, review your user prompts, and if this happens, define clear timeouts to reduce costs and finish the process sooner.

Scenario: Orchestrating Cursor Cloud Agent from a Pipeline

Imagine the scenario where you try to orchestrate an integration with the service Cursor Cloud Agent from a popular Pipeline. What issues could happen?

Scenario: Orchestrating Cursor Cloud Agents from the Pipeline

Issues at Pipeline level

• Third-party dependencies: If your pipeline is too complex, the global reliability may suffer. Review the chain of dependencies to simplify your pipeline and avoid runtime issues. Log runtime issues with third-party dependencies. Using a predefined Docker image build could reduce the number of runtime issues.
• The task related to Cursor Cloud Agent failed: It is not common, but the service can fail. In that case, I recommend logging the Agent ID returned from the launch operation (POST /v0/agents) and writing the internal conversation using the REST endpoint GET /v0/agents/{id}/conversation.
• I am not able to create more Cursor Cloud Agents: If you use the service and submit the PR, at the end of the process, you should delete the agent to release resources at the Cursor level—the resources are not infinite. Use the endpoint DELETE /v0/agents.

Issues at Cursor Cloud Agent level

• Cursor Cloud Agent finished with an ERROR state: Yes, it is not common, but sometimes it happens for different reasons. On the user side, for example, if you change a customized Cursor environment described in .cursor/environment.json and the associated Dockerfile, you could encounter this issue, but there could also be unknown runtime issues at the Cursor level. Logging the Agent ID and the conversation can be useful.
• Cursor Cloud Agent doesn’t make progress: This is rare, but you may not see execution progress due to different runtime issues. For such cases, it is important to define realistic timeouts for the pipeline step that involves this integration.
• Cursor Cloud Agent enters a loop: Sometimes, if you send an unclear or unrealistic user prompt, the process may enter a loop. To avoid this, review your user prompts, and if this happens, define clear timeouts to reduce costs and finish the process sooner.
• Cursor Cloud Agent includes files not requested in the PR: When frontier models try to resolve the goals described in the user prompt, they sometimes need to create scripts, extra files, or simply store files for analysis and debugging. Refine your user prompts to specify exactly what files and file extensions are valid; another alternative is to combine this with .gitignore files.

In general, it is a good practice to log the Agent ID for potential Cursor support and log the internal frontier model conversation for further analysis in order to improve the user prompt. Do not miss creating a threat model in your projects.

Real world scenarioS

If you have doubts about what scenarios could be used for this new cloud service, I’ll share a few scenarios that you might find interesting.

• Continuous documentation: Not everyone loves documenting solutions, and sometimes the documentation is outdated over time. You could use this service to update the documentation at different levels for the team, externally, or simply to train people.
• Continuous coding standard refactoring: People come and go on your team, and everyone has a different programming style. In Java, you can establish format rules with plugins like Spotless or similar, but there is no tooling to unify the programming paradigm or style. Google and other companies have published Java guides—why not refactor your software using your style? If you have good tests, you’re safe.
• Fix changes if a third party breaks the contract: Oh my god, that team changed the contract again, and the product owner didn’t estimate the task in the sprint. Okay, let’s monitor the contract—if something changes, let’s delegate the action to evaluate the level of change and determine if it’s acceptable, then adapt the anticorruption layer to the new change.
• Continuous Sonar cleanup: Oh my god, the Sonar gate is blocked again, and the product owner doesn’t allow us to release the product. Okay, let’s run the pipeline that retrieves the failing security hotspots and issues with blocker & high severity to be fixed today.
• Continuous profiling: Not everyone on the team has good skills to understand files like flamegraphs, thread dump files, GC logs, etc. But why not delegate that task to the service to discover new opportunities to improve your products?
• Simplify complexity: Periodically, you could run a pipeline that reviews the current implementation to simplify architecture, implementation, data types used, etc. Simple systems are maintained better.
• Empower people based on team issues: Periodically, issues reported in the ticket system or similar platforms could be a good source of ideas to train the squad and sharpen the axe.
• …
• Solve the Advent of Code 2025 with a scheduled pipeline every day.

https://adventofcode.com/2025

Creativity and your monthly budget mark the limit.

LIMITATIONS

This technology is awesome, but you should consider the following factors:

• Cognitive load: When adding these new virtual hands to your squad, you need to ensure that everyone is able to review the new PRs with quality. Apart from using this technology for delivery, review the new opportunities to strengthen the team based on the issues identified as input.
• Budget: This technology is not free. It is another input for your engineering manager in terms of cost and resources to maintain the prompts and pipelines.
• Resources: You could create several pipelines, but you need to calibrate with the current cadence of PR reviews to avoid saturating the process.

ExampleS in action

using cursor agent cli in action: Orchestrating Cursor Cloud Agent from a Pipeline

Review the following step to understand how to run a pipeline with Cursor Agent CLI using user prompts based on PML.

 - name: Run Cursor Agent
   env:
     CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
   run: |
     echo "=== User Prompt:===";
     jbang trust add https://github.com/jabrena/
     PROMPT=$(jbang pml-to-md.0.4.0-SNAPSHOT@jabrena convert pml-hello-world-java.xml)
     echo "$PROMPT";
     echo "=== Cursor Agent Execution:===";
     echo "";
     cursor-agent -p "$PROMPT" --model auto

In the previous example, the Cursor agent processes a user prompt in Markdown which was originally created in XML (using a PML schema).

Orchestrating Cursor Cloud Agent from a Pipeline

A picture is worth a thousand words. You can see a service that monitors Cursor Cloud Agent runtime at the following address: https://jabrena.github.io/cursor-cloud-agent-rest-api-status/ 

Cursor Cloud Agent REST API Status

Every hour, the service tests the execution to verify different aspects of the solution. After a month of running the service, I can assert that latencies are stable, and this fact is important when designing AI solutions that don’t require near real-time feedback. Further information about the pipeline here: https://github.com/jabrena/cursor-cloud-agent-rest-api-status/blob/main/.github/workflows/scheduled-ping-agent.yaml

Note: The service has been running for more than 1 month (30 × 24 × 4 samples stored). Under the hood, the pipeline uses Churrera CLI, an Open source Java CLI tool designed to orchestrate Cursor Cloud Agents and measure latencies.

Takeaways

• Cursor Agent CLI is a nice way to start using frontier models in pipelines.
• Cursor Cloud Agents is a nice way to use frontier models for parallel and complex scenarios because it offers an easy REST interface with fine-grained control over the process.
• Running a pilot in non-critical services could be a good way to understand the possibilities and train people.
• PML is a great way to write robust user prompts based on XML, which can be verified and transformed later to other hierarchical formats like Markdown.
• Decouple User prompts from Agent systems. It will be considered as another IT asset in the future.
• You can combine User prompts plus System prompts like Cursor rules or Claude Skills to enrich the final result.
• Both alternatives create pull requests, the team has the last word on accepting the new code added to the main/develop branch. This model is also compatible if you use Extreme Programming.
• Review your engineering processes to include a threat modeling task for new operations that include AI.
• Models can interact with the environment using CLI tools or MCP tools.
• You can assign the operation of these pipelines to junior profiles because these problems were modeled with user prompts, so the risk is very limited. However, there exists a nice opportunity to improve the solutions with ideas like adding functional programming patterns, improving the OOP design, improving performance based on multiple factors, etc.

References

• https://cursor.com/docs/cloud-agent
• https://cursor.com/docs/cloud-agent/api/endpoints 
• https://editor.swagger.io/?url=https://cursor.com/docs-static/cloud-agents-openapi.yaml
• https://cursor.com/agents
• https://github.com/jabrena/pml 
• https://github.com/jabrena/churrera-cli 
• https://github.com/jabrena/cursor-rules-java 
• https://github.com/jabrena/cursor-cloud-agent-rest-api-status 
• https://contextmapper.org/docs/examples/
• https://modelcontextprotocol.io/docs/getting-started/intro

The post Delegating Java tasks to Supervised AI Dev Pipelines appeared first on JVM Advent.

The post How to really measure LLMs for JVM Code? A Benchmarking guide for late 2025 appeared first on JVM Advent.

These migration challenges require significant effort even for a single application. The difficulty grows exponentially when a company needs to upgrade dozens of systems at once. And once the migration is complete, a new question arises: how can we keep applications consistently up to date without repeating the same painful process?

CONTEXT OF THE SITUATION

Imagine a team responsible for several microservices that use different versions of Java or Spring Boot. This happens because not all microservices change frequently; at some point, a problem occurs with a library they all use, and when someone tries to update the version, another problem arises, such as the new version not supporting all versions of Java.

To see this situation graphically, check the following table, which represents a possible scenario that could occur in any company:

With this problem in mind, the only alternative is to create a custom solution for each application that does not use the minimum version of Java that supports this library, but this could have many implications, such as performance issues and more time to fix the problem across all the microservices.

The Problems with Legacy Code

Legacy code does not always need to be updated. For example, a desktop application that operates in isolation and does not interact with external services may continue to function without requiring significant changes. In these scenarios, updates are optional.

However, in many other cases, applications must be updated for several reasons, mainly when they rely on outdated Java versions or obsolete dependencies. Running outdated software introduces risks and limitations that can directly affect stability, security, and maintainability.

Some of the risks associated with outdated code are:

• Security vulnerabilities: Older versions often contain unpatched exploits.

• Compatibility issues: Modern libraries, tools, and operating systems may no longer support obsolete versions.

• Performance inefficiencies: Newer versions frequently include optimizations that older releases lack.

HOW TO SOLVE THESE PROBLEMS?

The problem could be split into two situations: one is an application that contains legacy code and needs to be updated, and the other is an application that uses a relatively recent version of a language or framework but has some dependencies on older versions.

There is a set of tools or libraries to solve these problems, the most popular are:

• Renovate: Automates dependency updates and creates pull requests across many languages.

• OpenRewrite: Automatically refactors source code to migrate between Java versions or frameworks.

• Maven Versions Plugin: Detects and updates dependency versions in Maven projects without code changes.

• Dependabot: GitHub’s built-in tool that creates pull requests for outdated dependencies.

Let’s see in the following table a brief comparison of all of them:

Main differences	Reno vate	Open Rewrite	Maven plugin	Dependa Bot
It has good documentation.
Support multiple languages.
Refactoring the source code to a specific version.
Automates dependency updates.
It’s possible to generate pull/merge requests.
It has a large user community.

In this comparison, the best option for addressing migration problems is OpenRewrite. If you need to keep dependencies up to date, the winners could be Dependabot or Renovate. However, given the cost of these tools, the winner is the Maven Plugin.

This article uses a source from a GitHub repository; feel free to clone it and use it to learn about how to keep the application updated.

Solution #1: Leveraging OpenRewrite

OpenRewrite provides a comprehensive solution to code migration challenges with automated, reliable refactoring tools that streamline the process. The platform effectively highlights necessary code changes, implements consistent transformations, and significantly minimizes the manual effort required for application updates. By automating repetitive tasks and guiding developers through essential modifications, OpenRewrite improves the manageability of large-scale upgrades while reducing the risk of errors.

The migration process with OpenRewrite follows a precise, structured flow, offering a series of recipes that include the steps and resources needed at each stage. This tool is not limited to migrating Spring Boot or Java; it offers a comprehensive catalog of recipes for different languages and frameworks.

Let’s see how the process of migrating an application to Java 21 and Spring Boot 3.4 is. To do that, add the OpenRewrite plugin or dependency to your build system, along with the recipes to be used, as shown in the following code block.

<plugin>

     <groupId>org.openrewrite.maven</groupId>

     <artifactId>rewrite-maven-plugin</artifactId>

     <version>6.24.0</version>

     <configuration>

         <activeRecipes>

             <recipe>org.openrewrite.java.OrderImports</recipe>

       <recipe>org.openrewrite.java.migrate.UpgradeToJava21</recipe>

   <recipe>org.openrewrite.java.spring.boot3.SpringBootProperties_3_4</recipe>

         </activeRecipes>

     </configuration>

     <dependencies>

         <dependency>

             <groupId>org.openrewrite.recipe</groupId>

             <artifactId>rewrite-spring</artifactId>

             <version>6.19.0</version>

         </dependency>

         <dependency>

             <groupId>org.openrewrite.recipe</groupId>

             <artifactId>rewrite-migrate-java</artifactId>

             <version>3.9.0</version>

         </dependency>

    </dependencies>

</plugin>

As a recommendation, check the latest version of this plugin on the official webpage or a repository like this regularly.

The plugin only contains the core logic to execute the receipts that are necessary to include as external dependencies, as shown in the previous code block. Also, it’s possible to create custom receipts that are not part of the official library.

The next step after the modifications on the project is to execute the changes using the following command:

$ mvn rewrite:run

[INFO] Using active recipe(s) [org.openrewrite.java.OrderImports, org.openrewrite.java.migrate.UpgradeToJava21, org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_4]
[INFO] Using active styles(s) []
[INFO] Validating active recipes...
[INFO] Project [api-reservations] Resolving Poms...
[INFO] Project [api-reservations] Parsing source files
[WARNING] locking FileBasedConfig[/home/asacco/.config/jgit/config] failed after 5 retries
[INFO] Running recipe(s)...
[WARNING] Changes have been made to api-reservations/pom.xml by:
[WARNING] org.openrewrite.java.migrate.UpgradeToJava21
[WARNING] org.openrewrite.java.migrate.UpgradeBuildToJava21
[WARNING] org.openrewrite.java.migrate.UpgradeJavaVersion: {version=21}
[WARNING] org.openrewrite.maven.UpdateMavenProjectPropertyJavaVersion: {version=21}
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_4
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_1
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springframework.boot, artifactId=*, newVersion=3.1.x, overrideManagedVersion=false}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springdoc, artifactId=*, newVersion=2.2.x}
[WARNING] org.openrewrite.java.testing.mockito.Mockito4to5Only
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.mockito, artifactId=*, newVersion=5.x}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springframework.boot, artifactId=*, newVersion=3.2.x, overrideManagedVersion=false}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springdoc, artifactId=*, newVersion=2.5.x}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springframework.boot, artifactId=*, newVersion=3.3.x, overrideManagedVersion=false}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springdoc, artifactId=*, newVersion=2.6.x}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springframework.boot, artifactId=*, newVersion=3.4.x, overrideManagedVersion=false}
[WARNING] org.openrewrite.java.dependencies.UpgradeDependencyVersion: {groupId=org.springdoc, artifactId=*, newVersion=2.8.x}
[WARNING] Changes have been made to api-reservations/src/main/java/com/twa/reservations/connector/CatalogConnector.java by:
.....

If everything works as expected and the migration was successful, the changes to the POM file that add the openRewrite plugin will be removed.

Suppose it’s necessary to understand and see all the changes that could affect the application before doing so. In that case, another command shows that information by simulating execution and displaying the results.

$ mvn rewrite:dryRun
....
[INFO] Using active recipe(s) [org.openrewrite.java.OrderImports, org.openrewrite.java.migrate.UpgradeToJava21, org.openrewrite.java.spring.boot3.SpringBootProperties_3_4]
[INFO] Using active styles(s) []
[INFO] Validating active recipes...
[INFO] Project [api-reservations] Resolving Poms...
[INFO] Project [api-reservations] Parsing source files
....
[WARNING] These recipes would make changes to api-reservations/src/main/java/com/twa/reservations/controller/ReservationController.java:
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_4
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_1
[WARNING] org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_7
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_6
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_5
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_4
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_3
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_2
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_1
[WARNING] org.openrewrite.java.spring.boot2.UpgradeSpringBoot_2_0
[WARNING] org.openrewrite.java.spring.boot2.SpringBoot2BestPractices
[WARNING] org.openrewrite.java.spring.NoAutowiredOnConstructor
[WARNING] Patch file available:
[WARNING] /home/asacco/Code/Talks/out-with-the-old/api-reservations/target/rewrite/rewrite.patch
[WARNING] Estimate time saved: 20m
[WARNING] Run 'mvn rewrite:run' to apply the recipes.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20.671 s
[INFO] Finished at: 2025-12-01T15:22:34-03:00
[INFO] ------------------------------------------------------------------------

On the file rewrite.patch that was created in the target folder, all the changes that will be executed in the application will appear.

Solution #2: Dependency – Updates Versions

The versions-maven-plugin is a powerful Maven tool designed to help developers keep project dependencies, plugins, and parent versions up to date. With simple commands, it can identify outdated components, suggest the latest compatible versions, and even update itself pom.xml automatically. This reduces the manual effort required to track version changes and helps ensure applications remain secure, stable, and aligned with the latest improvements in their ecosystems.

The first step to use this plugin is to include it on the pom file like appears on the following block:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>versions-maven-plugin</artifactId>
    <version>2.18.0</version>
</plugin>

As a recommendation, check the latest version of this plugin on the official webpage or a repository like this regularly.

The next and last step is to run a command that checks all dependencies and the project and suggests which are outdated. The command and the output looks like the following:

$ mvn versions:display-dependency-updates
...
[INFO] --- versions:2.18.0:display-dependency-updates (default-cli) @ api-reservations ---
[INFO] The following dependencies in Dependency Management have newer versions:
[INFO] biz.aQute.bnd:biz.aQute.bnd.annotation ................ 7.0.0 -> 7.1.0
[INFO] co.elastic.clients:elasticsearch-java ................ 8.15.5 -> 9.2.1
[INFO] com.couchbase.client:java-client ..................... 3.7.9 -> 3.10.0
[INFO] com.datastax.oss:native-protocol ...................... 1.5.1 -> 1.5.2
[INFO] com.fasterxml.jackson.core:jackson-annotations ..... 2.18.5 -> 3.0-rc5
[INFO] com.fasterxml.jackson.core:jackson-core ............. 2.18.5 -> 2.20.1
[INFO] com.fasterxml.jackson.core:jackson-databind ......... 2.18.5 -> 2.20.1
[INFO] com.fasterxml.jackson.dataformat:jackson-dataformat-avro ...
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.970 s
[INFO] Finished at: 2025-12-01T16:43:32-03:00
[INFO] ------------------------------------------------------------------------

Consider that with this command, all the dependencies related to Spring Boot will appear; for example, they could be updated by simply incrementing the framework’s version. This scenario is a good candidate to use another approach which only show the version of the dependencies that are declared on the pom file. The command is quite similar to the previous one, but the output is entirely different, as shown in the following block.

$ mvn versions:display-property-updates
...
[INFO] The following version properties are referencing the newest available version:
[INFO] ${maven-failsafe-plugin.version} .............................. 3.5.4
[INFO] ${mockito.version} ........................................... 5.20.0
[INFO] The following version property updates are available:
[INFO] ${datafaker.version} ................................. 2.3.0 -> 2.5.3
[INFO] ${formatter-maven-plugin.version} .................. 2.23.0 -> 2.29.0
[INFO] ${instancio-junit.version} ........................... 5.2.1 -> 5.5.1
[INFO] ${junit-platform-launcher.version} ................ 1.8.2 -> 6.1.0-M1
[INFO] ${junit.version} ................................. 5.10.1 -> 6.1.0-M1
[INFO] ${mapstruct.version} ........................... 1.5.5.Final -> 1.6.3
[INFO] ${maven-compiler-plugin.version} ............. 3.14.1 -> 4.0.0-beta-3
[INFO] ${maven-enforcer-plugin.version} ..................... 3.4.1 -> 3.6.2
[INFO] ${maven-surefire-plugin.version} ..................... 3.1.2 -> 3.5.4
[INFO] ${spring-boot-starter.version} ...................... 3.4.12 -> 4.0.0
[INFO] ${springdoc-openapi-starter-webmvc-ui.version} ...... 2.8.14 -> 3.0.0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.970 s
[INFO] Finished at: 2025-12-01T16:43:32-03:00
[INFO] ------------------------------------------------------------------------

This plugin offers a series of other commands to check specific parts of the POM file, such as plugins, and many others, so it’s recommended to use the appropriate one depending on the context.

WHAT’S NEXT?

There are many resources for the evolution of a platform or application. The following is just a short list of resources:

• Modernizing Enterprise Java: A Concise Cloud Native Guide for Developers by Markus Eisele
• Building Evolutionary Architectures: Automated Software Governance by Neal Ford

Other resources could be great for understanding some concepts related to the evolution of a platform in depth:

• Software Architecture: The Hard Parts: Modern Trade-Off Analyses for Distributed Architectures by Neal Ford
• Refactoring: Improving the Design of Existing Code (2nd Edition) by Martin Fowler
• Software Developer To Software Architect by Mark Richards

Consider this just a small list of available resources. If something is unclear, find another video or resource.

CONCLUSION

There is no silver bullet for keeping an application permanently up to date, but combining the proper practices with the right tools can dramatically simplify the process. Tools such as OpenRewrite or the Maven Versions Plugin automate much of the Java and Spring Boot migration process. Still, they cannot fix everything, especially when a library does not support newer Java versions. For example, Orika, a widely used mapping library, does not support Java 17 or later, so developers must manually migrate to an alternative before they can benefit from automation.

Because of these limitations, maintaining a clean codebase, adopting a strong testing culture, and updating dependencies regularly are essential. By combining these practices with the tools discussed in this article, development teams can reduce migration risks and ensure that future upgrades become far less painful.

The post Out with the Old, In with the New: A Guide to Application Upkeep appeared first on JVM Advent.

Over the past year, the Java ecosystem has made significant strides in making Generative AI development enterprise-ready.

For Spring developers, SpringAI has emerged as the go-to toolkit for seamlessly integrating enterprise data and APIs with AI models.

Are you curious in developing enterprise grade AI applications with Spring AI? Then read on.

Setting up SpringAI

Loading documents and evaluating them with Generative AI is a fundamental use case that you will encounter when working with Large Language Models (LLMs) in the industry.

Therefore, to get started with SpringAI, we are using the practical example of summarizing Wikipedia articles with LLMs. We are going to create a springai-wikipedia-demo project that you can find on GitHub.

The project has been build with Spring Boot v3.5.8 running on Java 21. As key ingredients we are using the Anthropic API integration that uses the Claude models. To extract text from PDF documents we are using the Apache Tika document reader.

The key dependencies are:

implementation("org.springframework.boot:spring-boot-starter-webflux")
implementation("org.springframework.ai:spring-ai-starter-model-anthropic")
implementation("org.springframework.ai:spring-ai-tika-document-reader")

Note that we have added a dependency on spring-webflux. For SpringAI to work, we need the Netty Client on the classpath to carry out synchronous and reactive HTTP requests (using its RestClient and WebClient). So even if you only run SpringAI from the CLI, you also need to include a dependency to spring-webflux.

As said, we use Claude from Anthropic as LLM for demo purpose, but you can of course use any of your choice.

Note that you need to provide an Anthropic API key for the Claude Console as an environment variable to authenticate your requests to the model. See the application.properties file:

spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY:missing}

The Document reader infrastructure

One of the key abstractions when processing media content in SpringAI is the org.springframework.ai.document.Document interface. A Document contains the plain content and metadata about the document. The content can be textual, or optionally audio or video. The most important interface methods are:

String getText();
Media getMedia();
Map<String,Object> getMetadata();

The Document abstraction is closely tied to the context of Extract, Transform, Load (ETL) processes for Retrieval Augmented Generation (RAG). ETL is a three-step data integration process to collect data from various sources, clean and reshape it into a usable format, here a Document.

In simple terms, RAG is needed to feed your own private data to the LLM in order to take it into account when answering prompts. In the enterprise, this is of very high value. For privacy purposes, proprietary and open source LLMs won’t be trained on your specific company data.

In our example case, we are going to load five random articles of Wikipedia that have been saved as PDF. The articles have been placed in the resources folder:

├── application.properties
└── articles
    ├── 2023_Asia_Contents_Awards_&_Global_OTT_Awards.pdf
    ├── Anthony_Wonke.pdf
    ├── Chang_Tzi-chin.pdf
    ├── Indera_SC.pdf
    └── Neant-sur-Yvel.pdf

In the real world, you can imagine this content being Confluence docs, JIRA tickets, internal reports, literature and other kinds of publications that you want to provide to your LLM. You might want to let coworkers ask questions about your internal documentation. Or you want provide customers with answers about your products taking into account your own knowledge base.

To use the Tika document reader, we introduce a simple DocumentReader component; I am going to skip the import declarations in my examples:

package com.slissner.springai.infrastructure.document;

@Component
public class DocumentReader {
  public List<Document> loadText(final Resource resource) {
    final TikaDocumentReader tikaDocumentReader = new TikaDocumentReader(resource);
    return tikaDocumentReader.read();
  }
}

As you can see, SpringAI has nice abstractions. You just throw in some Resource reference, be it TXT, HTML, PDF, XLSX and so on, and the Tika Reader will answer with the appropriate Document.

Next, we are defining a repository reading the articles:

@Repository
public class ArticleRepository {

  private final DocumentReader documentReader;

  public ArticleRepository(final DocumentReader documentReader) {
    this.documentReader = documentReader;
  }

  private static final List<String> DOCUMENT_PATHS =
      Stream.of(
              "2023_Asia_Contents_Awards_&_Global_OTT_Awards.pdf",
              "Anthony_Wonke.pdf",
              "Chang_Tzi-chin.pdf",
              "Indera_SC.pdf",
              "Neant-sur-Yvel.pdf")
          .map(path -> "/articles/" + path)
          .toList();

  public List<Document> getAll() {
    return DOCUMENT_PATHS.stream()
        .map(ClassPathResource::new)
        .map(documentReader::loadText)
        .flatMap(Collection::stream)
        .toList();
  }
}

We simply load all articles with the List<Document> getAll() method, by first loading the classpath Resource and then sending it to the Tika reader.

Processing Documents with the ChatClient

As we can now load List<Document> from the PDFs, we can carry out a first prompt to let the LLM summarize the content of the first article in the list 2023_Asia_Contents_Awards_&_Global_OTT_Awards.pdf.

For this purpose, we have introduced the ArticleService application service. Note that we have not introduced yet a separate infrastructure class for the ChatClient. Our use case is so simple that we did not want to introduce a separate class for it.

package com.slissner.springai.application;

@Service
public class ArticleService {

  private final ChatClient chatClient;
  private final ArticleRepository articleRepository;

  public ArticleService(
      final ArticleRepository articleRepository, final ChatClient.Builder chatClientBuilder) {
    this.articleRepository = articleRepository;
    this.chatClient = chatClientBuilder.build();
  }

  public String summarizeArticles() {
    final List<Document> articles = articleRepository.getAll();

    // Use the first article as an example
    final Document articleContent = articles.getFirst();

    return chatClient
        .prompt()
        .user("Provide a summary of the following article:\n\n" + articleContent)
        .call()
        .content();
  }
}

We can now run the String summarizeArticles() application service method on the command line, with the following CommandLineRunner:

  @Bean
  public CommandLineRunner commandLineRunner(final ArticleService articleService) {
    return args -> {
      log.info("Okay, I am going to summarize articles...");

      final String summary = articleService.summarizeArticles();

      log.info("The summary is:");
      log.info(summary);
      log.info("Done!");
    };
  }

Great, that worked! Here is the answer from the LLM:

2025-11-28T16:26:02.457+01:00  INFO 4936 --- [springAI] [           main] c.slissner.springai.SpringAiApplication  : The summary is:
2025-11-28T16:26:02.457+01:00  INFO 4936 --- [springAI] [           main] c.slissner.springai.SpringAiApplication  : # 2023 Asia Contents Awards & Global OTT Awards Summary

The 2023 Asia Contents Awards & Global OTT Awards was held on October 8, 2023, at the BIFF Theater in Busan Cinema Center, South Korea. This event represents a rebranding and expansion of the previous Asia Contents Awards, now including global OTT (Over-The-Top) content and services.

[...]

The ChatClient offers a fluent API when communicating with the AI models.

chatClient
        .prompt()
        .user("Provide a summary of the following article:\n\n" + articleContent)
        .call()
        .content();

You declare to send a .prompt() to the model and its .user() input.

Note that we are passing the prompt here as a String text. You can also pass a Resource text handle. However, if you need full control over the user prompt, you can pass a well-defined Prompt to the ChatClientRequestSpec prompt(Prompt prompt) method. A Prompt gives you full control over the ChatOption such as the concrete model, max tokens or the temperature of the model.

Ultimately, the chat model can be synchronously called with the .call() method. There exists also a .stream() method that offers a reactive Flux<String> via calling the .content() method.

Memorizing Chat History with Advisors

So far, we have only sent a single prompt. What if we want to send a sequence of prompts, memorize the model answers and then run a final prompt on the memory?

For this purpose, SpringAI introduced the Advisors API. Think of the Advisors API as a plugin system for your AI calls.

Each advisor can intercept a request, add context, or modify the prompt before it reaches the model. Advisors are small middleware that automatically add missing context, such as previous messages or app-specific data, so the AI model always has what it needs.

The most common use cases are to add your own data to the conversation (see RAG); or to to add conversational history to the otherwise stateless chat model API.

Note that the SpringAI team warns that the order in which advisors are added to the advisor chain is crucial, like for other middleware. An advisor that has been added before another advisor to the advisor chain is executed first.

Interestingly, if you are having a look into the DefaultChatClient implementation, you can see that calling or streaming the chat model is realized bz just two Advisors that have been added at the end of the chain:

private BaseAdvisorChain buildAdvisorChain() {
    // At the stack bottom add the model call advisors.
    // They play the role of the last advisors in the advisor chain.
    this.advisors.add(ChatModelCallAdvisor.builder().chatModel(this.chatModel).build());
    this.advisors.add(ChatModelStreamAdvisor.builder().chatModel(this.chatModel).build());

    return DefaultAroundAdvisorChain.builder(this.observationRegistry)
        .observationConvention(this.advisorObservationConvention)
        .pushAll(this.advisors)
        .build();
}

Now, let’s enhance our current ArticleService implementation with the standard MessageChatMemoryAdvisor. First we need to inject a ChatMemory into our ArticleService:

@Service
public class ArticleService {

  private static final Logger log = LoggerFactory.getLogger(ArticleService.class);

    
  private final ArticleRepository articleRepository;
  private final ChatClient chatClient;
  private final ChatMemory chatMemory;

  public ArticleService(
      final ArticleRepository articleRepository,
      final ChatClient.Builder chatClientBuilder,
      final ChatMemory chatMemory) {
    this.articleRepository = articleRepository;
    this.chatClient = chatClientBuilder.build();
    this.chatMemory = chatMemory;
  }

As we have not declared any other bean, SpringAI will bind it with the default InMemoryChatMemoryRepository. There exists other ChatMemoryRepository implementations. For example, you can store your ChatMemory to a relational database with the help of a JdbcChatMemoryRepository.

This ChatMemory instance we are going to pass to our MessageChatMemoryAdvisor middleware:

  public String summarizeArticles() {
    final MessageChatMemoryAdvisor chatMemoryAdvisor =
        MessageChatMemoryAdvisor.builder(chatMemory).build();

    final List<Document> articles = articleRepository.getAll();

    articles.stream()
        .filter(article -> StringUtils.isNotBlank(article.getText()))
        // Max length of 8000 characters to avoid API limits
        .map(abbreviateArticleContent())
        .forEach(
            articleContent -> {
              try {
                log.info("Calling AI API with article. [id={}]", articleContent.id());

                chatClient
                    .prompt()
                    .advisors(chatMemoryAdvisor)
                    .user("Provide a summary of the following article:\n\n" + articleContent.text())
                    .call()
                    // We need to call .content() in order to actually retrieve the answer and store
                    // it
                    // in the chat memory.
                    .content();

                log.info(
                    "Successfully summarized article content with AI model. Sleeping now... [id={}]",
                    articleContent.id());

                // Sleep for 60 seconds after each API call to avoid rate limiting
                Thread.sleep(60000);

              } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("Thread was interrupted during sleep", e);
              }
            });

It is important that you call the .content() method and not only the .call() method.

Neither the .call() nor the .stream() method do actually trigger the AI model execution. Instead, they only instruct Spring AI whether to use synchronous or streaming calls. The actual terminal operations are .content(), .chatResponse(), and .responseEntity(). In our example, only by calling .content() method thus, we are actually storing the answers to the MessageChatMemoryAdvisor.

Furthermore, note the ugly Thread.sleep() call. The Anthropic API may return with a HTTP 429 error because of a 20,000 input tokens per minute rate limit. We circumvent this limit here with the help of the sleep. However, this gives you a first glimpse of the difficulties to scale AI model usage in a high data volume context, such as for enterprise applications.

With a final prompt, we will ask the AI to work with the previous answers. Let’s assume we build an editorial agent for a travel magazine. We want it to evaluate whether we can recommend arbitrary news articles as a travel destination.

    return chatClient
        .prompt()
        .advisors(chatMemoryAdvisor)
        .user(
            "Imagine you are a journalist in a news outlet. You work for a travel magazine that is based in Europe, "
                + "and thus its readers are European travelers. A colleague of yours has summarized five articles for "
                + "you. Now it is your turn to pick a subject out of these five articles and write a short travel "
                + "recommendation. The idea is that you write a single paragraph that praises a destination or activity "
                + "that you want to recommend to your readers."
                + "\n\n"
                + "Given the summaries provided, what is the most interesting topic?")
        .call()
        .content();

The idea here is that the LLM correctly picks the article about Néant-sur-Yvel, a village of a thousand inhabitants in Brittany, France.

Let’s run it through the model…

  @Bean
  public CommandLineRunner commandLineRunner(final ArticleService articleService) {
    return args -> {
      log.info("Okay, I am going to summarize articles and provide travel recommendations...");

      final String recommendation = articleService.summarizeArticles();

      log.info("The travel recommendation is:");
      log.info(recommendation);
      log.info("Done!");
    };
  }

And here comes its answer:

Tucked away in the enchanting landscape of Brittany, the commune of Néant-sur-Yvel offers discerning travelers a perfect escape from the well-trodden tourist paths of France. This picturesque village, nestled along the banks of the Yvel river, embodies authentic rural French charm that has remained largely undiscovered by mass tourism. With its medieval architecture, verdant countryside perfect for cycling and hiking, and proximity to the legendary Brocéliande Forest—steeped in Arthurian legends—Néant-sur-Yvel provides a genuine glimpse into traditional Breton life. The village makes an ideal base for exploring the wider Morbihan department, with its megalithic monuments and stunning coastline just a scenic drive away. Visit in late spring when the countryside bursts with wildflowers, and don't miss sampling local Breton specialties like galettes and cider in the village's unassuming but delightful eateries. For travelers seeking to experience the France that exists beyond the postcard views of Paris, Néant-sur-Yvel delivers an authentic slice of Brittany that will leave you enchanted.

With such a beautiful answer, who wouldn’t love to travel to Néant-sur-Yvel now?

Final word

The example has shown that Spring AI is a strong choice for enterprise AI applications. It offers a modular, modern, and well‑integrated feature set. However, scaling AI requires careful planning: token limits, API rate limits, and operational costs must all be considered. This is were the true challenge lies.

The post Getting Started with SpringAI appeared first on JVM Advent.

When the first technical solutions based on Artificial Intelligence began to be created, Python was the language and runtime platform of choice. It was not a total surprise as Python was the choice of the great majority of data scientists to analyse data, perform experiments and create AI models, so it was kind of natural that AI solutions were also based on Python and its rich ecosystem for data-intensive applications.

However, with the rise of Generative AI, organisations worldwide reconsider that approach given that the vast majority of GenAI-based solutions are just leveraging existing Large Language Models consumed “as a service” via web APIs. For doing that, Python does not have the same lead over the others. We must balance other key aspects of enterprise-grade solutions, such as resilience, scalability, observability, as well as the leverage of existing skills in the organisation. That means that other key languages and platforms can play a leading role in delivering and running GenAI-based solutions. Platforms such as Node.js, Go, and, of course, Java.

In Java we already have multiple valid approaches to be considered.In this article I will cover Langchain4j, one of the most popular choices in the Java ecosystem for building and running AI solutions at scale.

Why Langchain4j? Key outsdanding aspects are:

1. Framework-agnostic: As a library it imposes no constraints about how you design and build your solutions, so it can be easily integrated with any existing solution, either Spring-based, Jakarta-based, Quarkus-based, Micronaut-based, or with no framework at all.
2. Simple yet powerful API: Based on well-known patterns such as the Builder pattern, and with simple API constructs so its learning curve is simple and rewarding:
3. It works with both cloud-based “as a service” models such as OpenAI or Google Vertex, and with local/owned models via Ollama.

NOTE: The following examples are based on Langchain4j 0.36.2.

The first Langchain4j program

To demonstrate these concepts, let’s look at a “hello world” Langchain4j program.

The main interface that we need to learn about is ChatLanguageModel (from package dev.langchain4j.model.chat). This interface has the simple API that we need to send messages to an LLM and get its response. To instantiate specific models to interact with them we need the specific implementation depending on who provides them:

• For OpenAI, we leverage OpenAiChatModel from package dev.langchain4j.model.openai.OpenAiChatModel.
• For Vertex, we leverage VertexAiGeminiChatModel from package dev.langchain4j.model.vertexai.
• For Ollama, we leverage OllamaChatModel from package dev.langchain4j.model.ollama.OllamaChatModel.

As well as others. Every implementation of ChatLanguageModel has its own builder pattern to be able to add any specific configuration setting that is needed. Let’s see three brief examples of how this looks once we put it together:

OpenAI Hello World

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

class OpenAIHelloWorld {

    void main() {
        // OpenAI model
        ChatLanguageModel model = OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName("gpt-4o")
            .build();

        // the first prompt
        String message = "Hello world!";
        System.out.println("\n>>> " + message);

        String answer = model.generate(message);
        System.out.println(answer);
    }
}

As can be seen above, to connect with OpenAI services you must provide your own API key. You can also add explicitly the model that you want to be used.

Vertex Hello World

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.vertexai.VertexAiGeminiChatModel;

class VertexAIHelloWorld {
    void main() {
        // Vertex AI model
        ChatLanguageModel model = VertexAiGeminiChatModel.builder()
            .project(System.getenv("VERTEXAI_PROJECT_ID"))
            .location("us-central1")
            .modelName("gemini-2.5-flash")
            .build();

        // the first prompt
        String message = "Hello world!";
        System.out.println("\n>>> " + message);

        String answer = model.generate(message);
        System.out.println(answer);
    }
}

The pattern is similar to the previous but the settings that must be provided are different: the project id in Vertex, the cloud region and the model name.

Ollama Hello World

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.ollama.OllamaChatModel;

class OllamaGptOssHelloWorld {
    void main() {
        // gpt-oss:20b model running locally with Ollama
        ChatLanguageModel model = OllamaChatModel.builder()
            .baseUrl("http://localhost:11434")
            .modelName("gpt-oss:20b")
            .build();

        // the first prompt
        String message = "Hello world!";
        System.out.println("\n>>> " + message);

        String answer = model.generate(message);
        System.out.println(answer);

    }
}

Again, the pattern is similar. In this case we are running Ollama in the local computer and using the gpt-oss:20b model, quite competent and runnable in many personal computers.

Managing the context (a.k.a. short-term chat memory)

While the previous examples work, they lack a critical feature that any GenAI solution would need. The first important concept that we need to understand is how to manage the context of the conversation with the LLMs, also known as the short-term memory.

In essence, what we must do is to track the whole conversation with the LLM (a.k.a. “the chat”). After every interaction, the pair question and answer are saved to be sent with the next request payload, typically models expect that under a specific history entry in the request body in Json format. Fortunately, Langchain4j deals with those details and we just focus on keeping track of the conversation. The simplest way to do that is to use a in-memory store, as we can see in the following example:

ChatLanguageModelmodel = OllamaChatModel.builder()
    .baseUrl(baseUrl)
    .modelName(modelName)
    .timeout(Duration.ofSeconds(300))
    .temperature(0.0)
    .build();

// define context window
ChatMemory chatMemory = MessageWindowChatMemory.withMaxMessages(10);

// initial prompt with name and what I'm doing
String message = "Hello world! My name is Jorge and I'm writing this for Java Advent 2025.";
chatMemory.add(userMessage(message));

AiMessage answer = model.generate(chatMemory.messages()).content();
System.out.println(answer.text());
chatMemory.add(answer);

// ask for the name
message = "What is my name?";
chatMemory.add(userMessage(message));

answer = model.generate(chatMemory.messages()).content();
System.out.println(answer.text());
chatMemory.add(answer);

As can be seen in the example, the whole chat memory is passed to the model. As we keep adding every message and answer into the memory, the LLM will leverage the whole conversation (up to the limits of the memory or its own internal context window, whatever comes first) to come up with the best possible answer.

The static function userMessage from class dev.langchain4j.data.message.UserMessage helps to simplify keeping the history up to date by putting the user prompt in the right place.

Enriching answers with Retrieval Augmented Generation (RAG)

No matter how big is the LLM we use for our solutions it lacks something key: the business-specific data. Facts and figures, business processes, knowledge bases… Every bit and piece of internal information of the organisation that is therefore not part of the public data sets used to train LLMs.

If we want to create really useful GenAI-based solutions we need them to be aware of the potential user context: what do they need, what they must know.

// an embedding model good for simple documents
EmbeddingModel embModel = new AllMiniLmL6V2EmbeddingModel();

// an in-memory embedding store
EmbeddingStore<TextSegment> embStore = new InMemoryEmbeddingStore<>();

// load a PDF file from the classpath
Path path = Path.of(ClassLoader.getSystemResource("acme-know-how.pdf").toURI());

Document document = FileSystemDocumentLoader.loadDocument(path, new ApacheTikaDocumentParser());

DocumentSplitter splitter = DocumentSplitters.recursive(256, 0);

// ingest the document into the embedding store
EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
    .documentSplitter(splitter)
    .embeddingModel(embModel)
    .embeddingStore(embStore)
    .build();

ingestor.ingest(document);

Augmenting the Responses

No matter if the knowledge base is created at runtime or it is a persistence enterprise-grade vector search database, the abstraction needed to augment the response during retrieval are the same:

• ContentRetriever from
  package dev.langchain4j.rag.content.retriever: This is responsible to abstract the embedding store and model that will be used to look for the relevant data in the KB.
• AiServices from package dev.langchain4j.service.AiServices: This is a very convenient abstraction to create AI agents combining a given chat model and chat memory (as seen in the previous examples) with the content retriever.

The retrieval example with Langchain4j is quite straightforward:

// define the content retriever connecting everything together

ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
    .embeddingModel(embModel)
    .embeddingStore(embStore)
    .maxResults(1)
    .minScore(0.8)
    .build();
       
// llama3:8b model running locally with Ollama
ChatLanguageModel chatModel = OllamaChatModel.builder()
    .baseUrl("http://localhost:11434")
    .modelName("llama3:8b")
    .build();

// define context window
ChatMemory chatMemory = MessageWindowChatMemory.withMaxMessages(100);

Agent agent = AiServices.builder(Agent.class)
    .chatLanguageModel(chatModel)
    .chatMemory(chatMemory)
    .contentRetriever(retriever)
    .build();     

String message1 = "Could you summarize in 50 words the main concepts about the Java Platform?";

String answer1 = agent.answer(message1);

interface Agent {
    @SystemMessage("""
        You are an expert in information technologies
        and software engineering.
        """)
    String answer(String inputMessage);
}

The post Making Java a first-class AI citizen with Langchain4j appeared first on JVM Advent.

What is the Ahead-of-time cache in the jdk

JDK 24 introduced the Ahead-Of-Time (AOT) cache, a HotSpot JVM feature that stores classes after they are read, parsed, loaded, and linked. Creating an AOT cache is specific to an application, and you can reuse it in subsequent runs of that application to improve the time to the first functional unit of work (startup time).

To generate an AOT cache, you need to perform two steps:

1. Training by recording observations of the application in action. You can trigger a recording by setting an argument for the -XX:AOTMode option and giving a destination for the configuration file via -XX:AOTConfiguration:

   java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf 
        -cp app.jar com.example.App ...

   This step aims to answer questions like “Which classes does the application load and initialize?”, “Which methods become hot?” and store the results in a configuration file (app.aotconf).

2. Assembly that converts the observations from the configuration file into an AOT cache (app.aot).

   java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf 
        -XX:AOTCache=app.aot -cp app.jar

To benefit from a better startup time, run the application by pointing the -XX:AOTCache flag to the resulting AOT cache.

java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

The improved startup time is the result of shifting work, usually done just-in-time when the program runs, earlier to the second step, which creates the cache. Thereafter, the program starts up faster in the third phase because its classes are available from the cache immediately.

The three-step workflow (train+assemble+run) became available starting with JDK 24, via JEP 483: Ahead-of-Time Class Loading & Linking, the first feature merged from the research done by Project Leyden. A set of benchmarks prove the effectiveness of this feature and other Leyden performance-related ones, as displayed by Figure 1.

Figure 1: AOT Cache Benchmarks as of JDK 24

In JDK 25, the changes in JEP 515 – Ahead-of-Time Method Profiling enabled frequently executed method profiles to be part of the AOT cache. This addition improves application warm up by allowing the JIT to start generating native code immediately at application startup. The new AOT feature does not require you to add more constraints to your application execution; just use the existing AOT cache creation commands. Moreover, benchmarks showed improved startup time too (Figure 2).

Figure 2: AOT Cache Benchmarks as of JDK 25

JDK 25 also simplified the process for generating an AOT cache by making it possible to do it in a single step, through setting the argument for -XX:AOTCacheOutput flag:

# Training Run + Assembly Phase
java -XX:AOTCacheOutput=app.aot \
     -cp app.jar com.example.App ...

Upon passing -XX:AOTCacheOutput=[cache location], the JVM creates the cache on its shutdown. JEP 514 – Ahead-of-Time Command-Line Ergonomics introduced the two-step process for creating and using the AOT cache.

# Training Run + Assembly Phase
java -XX:AOTCacheOutput=app.aot \
     -cp app.jar com.example.App ...

# Deployment Run
java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

The two-step workflow may not work as expected in resource-constrained environments. The sub-invocation that creates the AOT cache uses its own Java heap with the same size as the heap used for the training run. As a result, the memory needed to complete the one-step AOT cache generation is double the heap size specified on the command line. For example, if the one-step workflow java -XX:AOTCacheOutput=... is accompanied by -Xms2g -Xmx2g, specifying a 2GB heap, then the environment needs 4GB to complete the workflow.

A division of steps, as in a three-phase workflow, may be a better choice if you intend to deploy an application to small cloud tenancies. In such cases, you could run the training on a small instance while creating the AOT cache on a larger one. That way, the training run reflects the deployment environment, while the AOT cache creation can leverage the additional CPU cores and memory of the large instance.

Regardless of which workflow you choose, let’s take a closer look at AOT cache requirements and how to set it up to serve your application needs best.

How to Craft the AOT Cache Your Application Needs

Training and production runs should produce consistent results, just faster in deployment runs. To achieve that, the assembly phase intermediates what happens between training and production runs (Figure 3).

Figure 3: Training / Assembly / Deployment

For consistent training runs and the subsequent ones, make sure that:

• Your JARs preserve their timestamp across training runs.
• Your training runs and the production one use the same JDK release for the same hardware architecture and operating system.
• Provide the classpath for your application as a list of JARs, without any directories, wildcards or nested JARs.
• Production run classpath must be a superset of the training one.
• Do not use use JVMTI agents that call the AddToBootstrapClassLoaderSearchand AddToSystemClassLoaderSearch APIs.

To check if your JVM is correctly configured to use the AOT cache, you can add the option -XX:AOTMode=on to the command line:

java -XX:AOTCache=app.aot -XX:AOTMode=on \
     -cp app.jar com.example.App ...

The JVM will report an error if the AOT cache does not exist or if your setup disregards any of the above requirements. Furthermore, the features introduced in JDK 24 and 25 did not support the Z Garbage Collector (ZGC). Yet, this limitation no longer applies as of JDK 26, with the introduction of JEP 516: Ahead-of-Time Object Caching with Any GC.

To ensure the AOT cache works effectively in production, the training run and all following runs must be essentially identical. Training runs are a way of observing what an application is doing across different runs and are primarily two types:

• integration tests, which run at build time
• production workloads, which require training in production.

Avoid loading unused classes during the training step and skip rich test frameworks to keep the AOT cache minimal. Mock external dependencies in training to load needed classes, but be aware that this may introduce extra cache entries.

AOT cache effectiveness depends on how closely the training run matches production behavior. If you rebuild the application or upgrade its JDK, you must regenerate the AOT cache. Otherwise, you risk crashes or undefined behavior (methods missing from cache).

In case you need to debug the performance of your application, run it with -Xlog:aot,class+path=info to monitor what it loads from cache.

Tips for Efficient Training Runs

There is a trade-off between performance and how easy it is to run the training. Using a production run for training is not always practical, especially for server applications, which can create log files, open network connections, access databases, etc. For such cases, it is better to make a synthetic training run that closely resembles actual production runs.

Aligning the training run to load the same classes as production helps to achieve an optimized startup time. To determine which classes are loaded by your training run, you can append the -verbose:class flag upon launching it. Or observe the loaded classes by enabling the jdk.ClassLoad JFR event and profiling your application with it:

# configure the event
jfr configure jdk.ClassLoad#enabled=true

# profile as soon as your application launches
java -XX:StartFlightRecording:settings=custom.jfc,duration=60s,filename=/tmp/AOT.jfr

# profile on a running application identified through llvmid
jcmd llvmid JFR.start settings=custom.jfc duration=60s filename=/tmp/AOT.jfr

On the recording file, you may check the loaded classes, but also which methods your application frequently uses by running the following jfr commands:

# print jdk.ClassLoad events from a recording file
jfr print --events "jdk.ClassLoad" /tmp/AOT.jfr

# view frequently executed methods
jfr view hot-methods /tmp/AOT.jfr

If you determine that there are methods frequently used but not detected by your training run, exercise them. You can work out the standard modes of your application using a temporary file directory, a local network configuration, and a mocked database, if needed.
Avoid loading unused classes during training and skip rich test frameworks to keep the AOT cache minimal. Instead, use smoke tests to cover typical startup paths; avoid extensive suites and stress/regression tests.

Takeways

To conclude, crafting an AOT cache for better performance requires you to look over:

• Cache validity or staleness; if you rebuild the application or upgrade the JDK, you must regenerate the AOT cache.
• Portability, as the AOT cache is JVM and platform-specific.
• Startup path coverage; the training run must cover typical application startup paths. If your training run is shallow, you will not warm up enough, and the benefits of the cache will be limited.
• Operational setup as both the application JAR and the AOT cache must run with least privilege and according to immutable infrastructure practices.

Application performance is an ongoing task because software evolves: new features are added, libraries change, workloads grow, and infrastructure shifts (e.g., to the cloud, container orchestration, etc.). Depending on those evolutions, your application performance goals evolve as well. Invest in training your application today and keep up with JDK releases to unlock available optimizations, as performance improves with each of them!

The post Run Into the New Year with Java’s Ahead-of-Time Cache Features appeared first on JVM Advent.

In the Java Advent of 2020, I published “Light up your Christmas lights with Java and Raspberry Pi“, using Java 11 and Pi4J V1.2. Wow, things have changed a lot: this article uses Java 25 and a snapshot of the soon-to-be-released Pi4J V4!

I became a contributor to Pi4J while working on my book “Getting Started with Java on the Raspberry Pi” around 2020. But even after many years of working on Pi4J’s code, I get puzzled when I dive deep into its sources. Please help me, do you understand what’s happening in this piece of code?

JNIEXPORT jobject JNICALL Java_com_pi4j_library_gpiod_internal_GpioD_c_1gpiod_1chip_1open
  (JNIEnv* env, jclass javaClass, jstring path) {
    struct gpiod_chip* chip;
    const char* nativeString = (*env)->GetStringUTFChars(env, path, NULL);
    chip = gpiod_chip_open(nativeString);
    (*env)->ReleaseStringUTFChars(env, path, nativeString);
    if(chip == NULL) {
      return NULL;
    }
    jclass cls = (*env)->FindClass(env, "java/lang/Long");
    jmethodID longConstructor = (*env)->GetMethodID(env, cls, "<init>", "(J)V");
    return (*env)->NewObject(env, cls, longConstructor, (jlong) (uintptr_t) chip);
}

It’s one of the “connection points” between Java and the native libraries to communicate with the GPIO pins. Using JNI and Java Native Access (JNA), Docker build environments are used to compile native libraries for use from Java. This complexity makes it easy for the end user to interact with Java, but difficult for the Pi4J developers to maintain and debug.

In this post, I’ll explain how the Foreign Function & Memory API (FFM API) has revolutionized how Java developers interact with native libraries and memory, significantly simplifying the Pi4J project. This article is based on a talk I gave at the Devoxx and JFall conferences about the history and evolution of this addition to OpenJDK.

A Quick History Lesson

My Java journey started 15 years ago when I switched from C# to Java and never looked back. That was right in the middle of Java’s 30-year history, and I’ve been following its evolution closely ever since. I even had the chance this year to talk to James Gosling, the “Father of Java”, for the Foojay Podcast.

In recent years, we have seen many evolutions in the Java language and virtual machine, such as improved switch-case, virtual threads, performance improvements, and more. One of the most significant recent developments has been Project Panama and the Foreign Function & Memory (FFM) API that emerged from it.

Foreign Function & Memory (FFM) API

The FFM API was officially released in Java 22 as a finalized feature. It represents years of work within Project Panama and has three main goals:

1. Memory safety: Safe access to off-heap memory while maintaining proper cleanup.
2. Easy interaction: Simple ways to call native libraries.
3. High performance: Matching or exceeding JNI’s performance.

The Problem With JNI

JNI has been around since Java 1.1, and while it works, it has a few critical drawbacks:

• Manual memory management with a steep learning curve.
• Complex implementation requiring C headers and compilation steps.
• Hard to use by design: As I learned from Simon Ritter, a Sun engineer once said, JNI was deliberately made difficult to discourage people from using it!

There were attempts to improve this situation with libraries such as JNA and Java Native Runtime (JNR), but they came with their own overhead and limitations.

How The FFM API Evolved

The development of the FFM API is a fascinating story that shows how OpenJDK evolves through careful iteration. The project was broken down into separate JEPs (JDK Enhancement Proposals), which started being delivered in Java 14. As you will see, most of the JEPs were incubator or preview features, which can only be used with the --enable-preview flag, as you can learn in this detailed explanation.

Foreign Memory Access API

As a first step, the OpenJDK team created a new API to access off-heap memory, enabling safe, efficient access to foreign memory. None of these were finalized, as they got integrated into OpenJDK as incubator features, preparing for something bigger.

• OpenJDK 14: JEP 370: Foreign-Memory Access API (Incubator)
• OpenJDK 15: JEP 383: Foreign-Memory Access API (Second Incubator)
• OpenJDK 16: JEP 393: Foreign-Memory Access API (Third Incubator)

Foreign Linker API

In the next step, statically typed pure-Java access to native code got integrated, again as an incubator feature.

• OpenJDK 16: JEP 389: Foreign Linker API (Incubator)

Foreign Function & Memory API

Finally, the FFM API was finalized in Java 22. It’s a combination of the two previous APIs, and it went through incubator and preview phases across multiple Java releases.

• OpenJDK 17: JEP 412: Foreign Function & Memory API (Incubator)
• OpenJDK 18: JEP 419: Foreign Function & Memory API (Second Incubator)
• OpenJDK 19: JEP 424: Foreign Function & Memory API (Preview)
• OpenJDK 20: JEP 434: Foreign Function & Memory API (Second Preview)
• OpenJDK 21: JEP 442: Foreign Function & Memory API (Third Preview)
• OpenJDK 22: JEP 454: Foreign Function & Memory API

This iterative approach allowed the OpenJDK team to gather community feedback and ensure the API was stable, performant, and truly useful.

Simple Code Examples

Let me show you how much simpler things have become with a few examples.

Accessing Memory Directly

Here’s a basic example of accessing memory directly:

void main() {
    // Open a confined Arena that manages off-heap memory
    // and will release it automatically.
    try (Arena arena = Arena.ofConfined()) {
        // Allocate 5 ints in the arena
        MemorySegment segment = arena
           .allocate(ValueLayout.JAVA_INT, 5);

        // Fill the segment with random values for each int.
        System.out.print("Setting values: ");
        for (int i = 0; i < 5; i++) {
            int randomValue = new Random().nextInt(100);
            segment.setAtIndex(ValueLayout.JAVA_INT, 
               i, randomValue);
            System.out.print(randomValue + " ");
        }
        System.out.println("");

        // Print the values back from memory.
        System.out.print("Reading values: ");
        for (int i = 0; i < 5; i++) {
            System.out.print(segment
              .getAtIndex(ValueLayout.JAVA_INT, i) + " ");
        }
        System.out.println("");
    }
}

Notice a few things about this code:

• I execute it with Java 25, which means I can use the new simplified main method introduced by JEP 512: Compact Source Files and Instance Main Methods. As a result, I don’t need to use a class and package, and a lot of the main method “clutter” is no longer needed in a simple example like this.
• The Arena manages memory cleanup automatically in the try block.
• The MemorySegment is a simple wrapper around a native memory address.
• No manual memory management is needed.

$ java ArenaDemo.java
Setting values: 16 7 27 50 80 
Reading values: 16 7 27 50 80

A more extended example is available here in FFMMemoryManagement.java, with a Java 11 example here Java11MemoryManagement.java illustrating how much more complex this was before the FFM API. The Java 11 version must be executed with JBang as described in the comments, to force the use of Java 11.

Calling Native Functions

To illustrate how to call a native library function, we’ll make the most complex String.length() implementation  A perfect example of how this can be done with FFM API within one simple-to-read method:

void main() throws Throwable {
    // The text we will use in the demo.
    var text = "Hello JVM Advent!";

    // Obtain a Linker that knows how to call
    // native (C) functions on this platform.
    Linker linker = Linker.nativeLinker();

    // Create a SymbolLookup that can find symbols
    // (like C functions) in the default native libraries.
    SymbolLookup lookup = linker.defaultLookup();

    // Create a MethodHandle to call the native C function
    MethodHandle strlen = linker.downcallHandle(
        // Look up the address of the `strlen` symbol,
        // or throw if it isn't found.
        lookup.find("strlen").orElseThrow(),
        // Describe the C function:
        // - returns long
        // - takes one pointer (address) argument
        FunctionDescriptor.of(ValueLayout.JAVA_LONG,
          ValueLayout.ADDRESS)
    );

    // Open a confined Arena that manages off-heap memory
    // and will release it automatically.
    try (Arena arena = Arena.ofConfined()) {
        // Allocate native memory for a C-style string
        // and copy "Hello World!" into it.
        MemorySegment str = arena.allocateFrom(text);

        // Call the native `strlen` function 
        // via the MethodHandle,
        // passing the string's memory address,
        // and cast the result to a long.
        long length = (long) strlen.invoke(str);

        // Print the result.
        System.out.println("Length with native library: " 
          + length);
    }

    System.out.println("Length with String.length(): " 
      + text.length());
}

No JNI headers, no C-compilation, just pure Java code!

$ java LinkerDemo.java

Length with native library: 17
Length with String.length(): 17

Also, for this example, you can find a more extended example here in FFMNativeCalls.java, with a Java 11 in Java11NativeCalls.java.

Performance Comparison Example

I like demos that have a visual output. So I created a simple benchmark that generates moving gradients, which involves many memory writes. In both Java 11 and 25, I try to refresh the gradient every 5 milliseconds.

The results speak for themselves (tested on a MaOS M2 with Azul Zulu 25):

$ jbang Java11PixelBuffer.java
[jbang] Building jar for Java11PixelBuffer.java...
Interval: 57 - Generated 250000 pixels
Interval: 56 - Generated 250000 pixels

$ java FFMPixelBuffer.java
Interval: 5 - Generated 250000 pixels
Interval: 5 - Generated 250000 pixels

• Java 11 approach using BufferedImage and arrays: ~50-60 milliseconds per frame.
• FFM API approach with direct memory access: ~5 milliseconds per frame.

That’s up to 11x performance improvement just by avoiding the overhead of Java object management!

Why the FFM API Matters for Raspberry Pi Projects

Let me first answer a more general question I get asked a lot: “Why Java on a Raspberry Pi?” The answer is simple: Java is the language that allows me to do everything. I can build user interfaces with JavaFX, make API calls to services, and leverage the extensive library ecosystem. When I started experimenting with Java on Raspberry Pi over five years ago, I didn’t want to learn a new language. I wanted to learn how to use and interact with electronic components, using the tools I already knew and loved.

This is where the Pi4J project comes in: it’s a Java library that lets you control the GPIO pins and electronic components connected to a Raspberry Pi. But here’s the catch: this library has always relied on native C/C++ code to communicate with the hardware. Until now, that meant dealing with the complexity of JNI and JNA.

Pi4J Architecture

Pi4J uses a plugin architecture in which different “providers” handle communication with GPIO pins. Previously, these providers relied on native libraries and JNI/JNA, which meant:

• Complex multi-layered code with up to 5 levels before executing GPIO operations.
• Need for Docker builds to compile native libraries.
• Cryptic JNI header generation and wizard-like C code.

These plugins get loaded dynamically at runtime, in the “black bar” in this architecture diagram:

The FFM Transformation

Pi4J now has an almost-ready FFM-based provider, which will be available in V4. The improvements are dramatic:

• Performance Benchmarks
  • Getting GPIO input state: 10x faster!.
  • SPI communication: Significant improvement, though less dramatic.
• Code Simplification
  • Direct Java-to-kernel communication.
  • No more complex JNI layers.
  • Readable, maintainable Java code.
  • No need for native library compilation with a complex Docker build process.

A Community Success Story

What makes this even better is that the FFM implementation came from the community. Nick Gritsenko (aka @DigitalSmile) had already created a Java 22 library for GPIO interaction using FFM. When I discovered his work, I asked if we could use it. But even better, he contributed it directly to Pi4J himself and made it fit perfectly into the plugin architecture! This resulted in a major pull request that’s now merged into the Pi4J V4 snapshot.

I’m very proud that this happens again and again. In the past, Alexander Liggesmeyer added support for the Raspberry Pi 5 with a new plugin. And at this moment, Stefan Haustein, Stephen More, Tom Aarts, and others are actively working on a new Pi4J drivers library and example implementations to make it much easier for everyone to create applications that interact with more complex electronic components, such as joysticks, LCD screens, LED strips, and more…

Beyond Raspberry Pi

The FFM-based implementation opens up exciting possibilities. Since it’s based on standard Linux kernel methods available in Debian, we believe Pi4J could potentially work on:

• Orange Pi boards and other Linux-based SBCs (Single Board Computers).
• RISC-V processors running Debian.

I’m looking forward to experimenting with these different hardware platforms! Maybe you’ll read more about that in next year’s JVM Advent…

Pi4J Examples Using the FFM API

I often demo with a CrowPi – a neat kit with a Raspberry Pi and pre-wired components in a single box. It’s great for learning because you can’t wire things incorrectly!

Here’s a simplified example using JBang to blink an RGB LED, using a snapshot build of Pi4J V4. Once this version is released, you can remove the line with //REPOS and update the version.

/// usr/bin/env jbang "$0" "$@" ; exit $?

//REPOS mavencentral,pi4j-snapshots=https://oss.sonatype.org/content/repositories/snapshots
//DEPS com.pi4j:pi4j-core:4.0.0-SNAPSHOT
//DEPS com.pi4j:pi4j-plugin-linuxfs:4.0.0-SNAPSHOT

import com.pi4j.Pi4J;
import com.pi4j.io.gpio.digital.*;

/**
 * Execute with `jbang Pi4JExample.java`
 */
void main() throws InterruptedException {
    var pi4j = Pi4J.newAutoContext();

    var red = pi4j.digitalOutput().create(17);
    var green = pi4j.digitalOutput().create(27);
    var blue = pi4j.digitalOutput().create(22);

    // Blink pattern
    for (int i = 0; i < 10; i++) {
        red.high();
        Thread.sleep(500);
        red.low();
        green.high();
        Thread.sleep(500);
        green.low();
        blue.high();
        Thread.sleep(500);
        blue.low();
    }
}

More examples like this, which can be executed with JBang, are available in the Pi4J JBang repository.

Important Notes

While working on the presentation about the FFM API and this article, I noticed a few points worth mentioning.

• Memory Safety Warning: When using FFM, you’re stepping outside the “safe JVM-managed garbage collector”. You’ll see a warning about enabling native access with a few of the examples from this article. This is intentional as the OpenJDK team wants to ensure developers understand they’re working with potentially dangerous operations. Use the --enable-native-access flag to acknowledge this and suppress the warning. This may change in future versions of OpenJDK.
• JEPs Are Worth Reading: If you’re curious about how Java evolves, I highly recommend reading the JDK Enhancement Proposals. They’re not just technical specifications! They’re well-written documents that explain the thinking behind design decisions, include examples, and provide deep insights from the architects of Java. Similarly, read more about the OpenJDK projects, for instance, by subscribing to their mailing list to follow what is happening within such a project.
• Keep Up With Java Releases: Java has a six-month release cycle, and every release is a good one! Each brings many bug fixes, improvements, and evolutions (from projects and JEPs). If you can update your systems, especially your development systems, you should! The FFM API was introduced in Java 22, but I learned at Devoxx that Java 24 brought significant performance improvements to the FFM implementation, without any API changes! This shows that the OpenJDK team continues to optimize and improve existing features.

Conclusion

The FFM API has been a significant improvement for developers working with native code in recent years. It removes the complexity of JNI while maintaining, and even improving, performance. It opens new possibilities for Java in embedded systems and hardware interfacing. It will also drive closer integration of Artificial Intelligence (AI), Machine Learning (ML), and Large-Language Model (LLM) development with Java.

Feel free to experiment and contribute. OpenJDK and other open source projects, like Pi4J, thrive on community involvement!

If you’re interested in Java on Raspberry Pi, check out:

• The Pi4J website.
• My blog posts on webtechie.be and Foojay.io.
• My ebook “Getting Started with Java on the Raspberry Pi“, which I keep updating with new Java versions, Pi4J improvements, etc.

Remember: We must thank OpenJDK and all its contributors for amazing features like the Garbage Collector, JIT compilation, Lambdas, Virtual Threads, and now the FFM API. Java keeps getting better, and that’s worth celebrating!

The post The FFM API: How OpenJDK Changed the Game for Native Interactions (And Made Pi4J Better!) appeared first on JVM Advent.

This year, as the world is now all going “agentic”, I was curious to learn more about agents and decided to start tinkering myself. I started a pet project with a basic idea:

“Could I generate a fully working optimization application purely from a simple problem description?”

Here’s where that curiosity led.

Basics: Framework

I like to approach pet projects in a way that they incorporate some ideas/frameworks/concepts I’ve played with before, while still challenging me to learn some new things.

There was no doubt in my mind about using Java, so I started looking for Java compatible agentic frameworks. I ran into Langchain4J Agentic, the Agent Development Kit and a few others. Since I had the most experience with Langchain4J already, that became my framework of choice.

I scoured through the docs to get a sense of what building an agent was like and then just got to work. I just needed 1 more thing: a benchmark / test scenario.

Let’s Sing!

I was looking for an example scenario. Something I would love to optimize that was also in my typical fashion:

• Silly (can’t be too serious when messing around with technology).
• Relatively simple (so everyone could understand it).
• Somewhat practical.

After talking to Wouter Bauweraerts from the Belgian Java Community (hi Wouter ), I settled on a karaoke bar scheduler. Yes. Karaoke.

Here’s the prompt I wanted the agent to digest:

I run a Karaoke bar. I have 2 stages and I want to schedule songs following these rules:

– Avoid having the same singer 2 times in a row
– Avoid having songs from the same artist 2 times in a row

A singer can sign up with a song. The duration of the performance depends on the lenght of the song.
I want to be able to create a clear clock of when the next song will start, so include timing.

Time to get to work on the agent!

(Note: All example prompts shown here are abbreviated. The real ones are as long as a 10 year old’s wishlist for Santa.)

Agent v0.1: Just an LLM prompt in disguise

The first version of my agent was pretty simple. Just take the input prompt, add a bit of information in the @SystemMessage and @UserMessage to steer the result a bit and hope for the best. After all, with all the hype, this was surely supposed to work? I even scoped it to only write the Timefold related code, not bothering with any sort of user interface.

Then I needed to choose the underlying LLM model. Langchain4j makes it trivial to change the LLM the Agent uses. As I was still in the exploratory phase, I decided to use a locally hosted LLM, qwen3:8b, which I run on my macbook using Ollama.

As I was patiently waiting for my brand new agent to give its very first result, I was already dreaming of what awesome result would come out of that writeCode method. As some of you might expect… it’s not that simple, unless the end result you wanted is a dumpster fire of mangled code.

Hey, at least it did output something! So let’s see how we can improve this.

Agent v0.2: Limiting scope even more

I felt I was asking too much from my single agent (or maybe this is just my human bias talking), so I decided to split it up into 2 separate coding agents: 1 for the Java domain code, 1 for the Java constraint stream code.

Constraint Streams is the syntax you use with Timefold to write constraints, such as the “Avoid having the same singer 2 times in a row” constraint.

The result was slightly better. The agents were more narrowly focussed and seemed able to keep it together. The output however is still nowhere near being workable. It was at least starting to look a bit more like workable Java code.

Agent v0.3: Better base model

Agents are only as good as their underlying model. Given that I’ve had more success with Claude and ChatGPT when asking similar coding questions, I felt it was time to replace the model used by my agent to Claude Sonnet 4.5 (20250929).

With this change in model I now have to start paying for my tokens. I started proceeding a bit more carefully and sometimes moved back to Ollama just for basic runs. Langchain4j makes this a 1 line code change .

Changing the model immediately brought my agent to life. The returned code at least looked like it was written by someone who had seen Java before. However, copy pasting the code into my IDE just showed how glaringly wrong it actually was. It’s the sort of code that would never pass a code-review… oh wait!

Agent v0.4: Review and Feedback

I had seen a subject header on the agentic langchain documentation about sub-agents and agentic workflows. So I decided to try it. Instead of a single “in and out” workflow, I added a Review agent, which reviews the written code, provides feedback and then puts the coding agent to work again with that feedback.

The cool thing is that we can actually give these agents tools to work with… and what better tool to give an agent which needs to write compilable code than an actual Java Compiler.

The resulting code was pretty ok and usually compiled just fine. But it did make some very obvious mistakes from a Timefold perspective (e.g. adding both @ShadowVariable and @PlanningVariable to a single field).

Agent v0.5: Avoiding the same mistakes (easyRAG)

To avoid these similar mistakes, I tried to give the agents a bit more information to work with by using RAG (Retrieval Augmented Generation). As I just wanted a simple solution here, I used the easyRAG features of Langchain4j. This allows me to just point to a directory which had some documentation included so the agent would be able to use the contained documents.

We have a lot of documentation for Timefold Solver, generated to pdf, it’s a good 400 pages. Not all of that is relevant for every agent, so I added some simplified documentation in different subdirectories for each of agents and then added those to the agent with a ContentRetriever.

I ran it a couple of times to see the impact these documents had. Whenever a new mistake seemed to become prevalent, I added more information to the relevant documents to improve the result.

This also led me to make a couple updates to our actual documentation. Turns out that if an LLM can’t understand your documentation humans will struggle with it as well.

At this point, it was getting slightly painful to see my API credits decline. With the subagents in a loop, this was burning through a lot of tokens, so I tried to figure out: how can I get a better result, without burning through so many tokens?

Agent v0.5: (Plant)UML to the rescue!

Upon inspection, I noticed a lot of the comments by the review agents were not about code details at all, but about the structure of the classes and the placement of the annotations Timefold Solver needs. When solving these problems myself, these are all things I’d add to a diagram before even opening my editor… so why not do the same here?

Instead of skipping directly to the code, I introduced 1 new agent. This “modelling” agent would “model” how the solution should look and format it in PlantUML. I gave this agent the documentation we have for modelling problems with Timefold Solver and explicitly asked it to add some details about design choices it made to the PlantUML diagram.

Now I not only made “thinking about the structure of our solution” way more explicit, I also have a reviewable asset that is passed between agents: the PlantUML diagram. As it turns out, PlantUML is an excellent format if you want to pass information about the structure of your classes between agents without giving it the entire codebase.

I adjusted the coding agents to accept the PlantUML diagram as input, so they did not get overloaded with residual information about the problem statement.

This massively improved consistency and reduced hallucinations. It now worked well enough that I ventured into the much harder part.

Agent v0.6: UI and Backend

Having a nice scheduling core is nice, hosting a Karaoke with hardcoded Java will probably not be very conductive for a great evening. So we still need a UI.

I don’t think that having GenAI scaffold an entire project is a good move here, so I looked into tools that would help me create a project structure.

In the Java world, one potential solution is to rely on JHipster and more specifically the JHipster Domain Language (JDL) . JDL allows you to describe a project: entities, relationships and some other properties.

These are all things we can let an LLM fill in, based on the PlantUML and the problem description. Then you can create a full application with a single command (jhipster import-jdl model.jdl), which I wrapped into a Tool so I can have an agent create the JDL and generate a simple application for my problem.

And now we have a fully working application (Angular + Spring Boot), including login screen, metrics and CRUD pages for every entity involved entity, all at a fraction of the token cost we’d have if we let GenAI do everything.

Conclusion

While I still have to resolve some gaps, like actually connecting Timefold Solver to the rest of the JHipster generated code and creating a better scheduling UI, I think I’ll stop this pet project here for now. For me, the real value of these tinkering projects isn’t what I end up building. It’s everything I learn while fumbling toward it.

Here are my main lessons.

• Having inspectable intermediate formats makes the development process much easier and the end result way more auditable.
• At the moment of writing, it’s still much better to have a human in the loop. Even tiny mistakes made in one of the first steps can lead to a failed result in the end. Being able to intervene and correct makes the whole thing so much easier than this “fully autonomous” thing I was trying.
• Better models = better results. We may not want to spend the money, but it did change my results from absolute garbage to something that quite often works. I was very happy with Langchain4J in this regard, I only needed to change 1 line of code to try a different model.
• Learning is still so reinvigorating! It’s been a while since I’ve felt a big jolt of love for a pet project but this one struck like a lightning bolt. Yes, it can get annoying sometimes to get GenAI to do what you want, but as a dad raising a small 2 year old kid, I have been trained to be patient and steer it in the right direction.

Happy Holidays!

The post Tinkering with a “hands-off” agent appeared first on JVM Advent.

• Requirements documents drift away from reality
• Diagrams do not match the current architecture
• Tests only cover part of the behavior
• Business logic hides deep in service classes

AI code generation tools can make this even worse if used without structure. They produce code fast, but the process behind the code remains the same.

Spec-Driven Development (SDD) solves this by starting from clear specifications instead of starting from code. AI then uses these specifications to generate consistent code, tests, and documentation.

The AI Unified Process (AIUP) is a practical way to apply SDD in real projects. It keeps requirements, code, and documentation in sync. In this article, we look at AIUP in the context of a full-stack Java application built with Spring Boot, jOOQ, and Vaadin.

From Code-Centered To Spec-Driven

In most teams, development is code-centered:

• A ticket is created
• A developer writes code
• Documentation and tests come later

This leads to long-term problems:

• You lose track of why a rule exists
• Business decisions hide in commit messages
• Refactoring becomes risky
• The architecture stops matching the documentation

Spec-Driven Development flips this:

1. You start with a clear specification.
2. This specification becomes the single source of truth.
3. AI generates code, tests, and diagrams from it.
4. Developers review and adjust the generated results.

When requirements change, you update the specification first, then regenerate.

The AI Unified Process (AIUP)

AIUP is an iterative process with a simple but powerful structure.
It is built on three core specification artifacts:

1. Requirements Catalog
2. Entity Model
3. System Use Cases

These artifacts are always updated in this order. Everything else flows from them.

1. Requirements Catalog

The Requirements Catalog is the foundation of AIUP.
It defines what the system must do and under which conditions.

It contains three types of requirements:

Functional Requirements

These describe what the system should do. In AIUP, they are usually written as user stories.

Examples:

• As a user, I want to create a customer with name and email.
• As an admin, I want to deactivate customers who have no open orders.
• As a sales agent, I want to see all active customers sorted by name.

Functional requirements describe user goals and expected behavior, not code.

Non-Functional Requirements

These describe qualities of the system, like:

• Performance
• Security
• Availability
• Logging
• Observability
• Scalability

Example:

• All write operations must be audited with a timestamp, user, and change details.

Constraints

These describe rules that must always be enforced.

Examples:

• Customer email must be unique.
• Only authenticated users may access customer data.
• Orders cannot be deleted once invoiced.

The Requirements Catalog is written in simple, precise language. It is reviewed frequently and kept under version control. Everything in AIUP starts with this catalog.

2. Entity Model

The Entity Model describes the domain data structure.
It answers:

Which concepts exist, and how do they relate?

The Entity Model is based on the Requirements Catalog. Functional requirements describe what users want to do. Constraints often describe the domain rules. From both, you extract stable domain objects.

For example, from the requirements above, you define:

Entities:

• Customer
• Order

Attributes:

• Customer: id, name, email, active
• Order: id, status, totalAmount, customerId

Relationships:

• Customer 1..* Order

The Entity Model lets AI generate:

• Database schema or migrations
• jOOQ meta model
• Domain classes and DTOs
• Validation rules
• Basic UI bindings in Vaadin

It ensures that back end, database, and UI use the same domain structure.

3. System Use Cases

AIUP uses only System Use Cases. There is no separation between business and system use cases.

A System Use Case describes how the system behaves when triggered by a user or external system. It defines:

• Actors
• Preconditions
• Steps
• Decision logic
• Postconditions
• Errors

System Use Cases transform requirements into explicit logic.

Example System Use Case: Deactivate Customer

Name: Deactivate Customer
Actor: Administrator
Preconditions:

• User is authenticated
• User has role ADMIN

Main Flow:

1. Load customer
2. Load related orders
3. Check for open orders
4. If open orders exist, return error
5. Set customer.active = false
6. Write audit entry

Postconditions:

• Customer is inactive
• Operation is logged

How AIUP Runs In Iterations

AIUP uses short iterations. Each cycle follows this sequence:

1. Update Requirements Catalog
2. Update Entity Model
3. Update System Use Cases
4. Generate code, diagrams, and tests with AI
5. Review and improve the generated output
6. Run tests
7. Refine the specifications

This creates a stable, controlled development loop.

Example: A Java Feature With AIUP

Imagine you add a “Deactivate Customer” feature. All documentation is code and under version control.
The example uses Markdown, but you could also use AsciiDoc to get a richer Markdown syntax.

Step 1: Requirements Catalog

| Category                  | Description                                                |
|---------------------------|------------------------------------------------------------|
| Functional requirement    | As an admin, I want to deactivate a customer who has no open orders. |
| Non-functional requirement| All write operations must be audited.                      |
| Constraint                | Customer email must be unique.    

Step 2: Entity Model

Entity: Customer with id, name, email, active  
Entity: Order with id, status, customerId  
Relation: Customer 1..* Order  
Rule: Status can be OPEN, COMPLETED, or CANCELLED

AI generates:

• Migration script for unique email
• jOOQ code
• Domain classes

Step 3: Use Cases

## UC-001: Deactivate Customer

**Name**  
Deactivate Customer

**Actor**  
Administrator

**Preconditions**  
- User is authenticated  
- User has role ADMIN

**Main Flow**  
1. Load customer  
2. Load related orders  
3. Check for open orders  
4. If open orders exist, return error  
5. Set customer.active = false  
6. Write audit entry

**Postconditions**  
- Customer is inactive  
- Operation is logged

AI generates:

• Vaadin UI
• Service method implementing logic
• jOOQ queries
• Unit, integration tests, and E2E tests

You review, adjust, and commit.

Why This Fits Full-Stack Java So Well

AIUP fits the Java ecosystem because:

• The Spring ecosystem is very mature
• jOOQ is built around generated code
• Vaadin UI components are superior
• Java is strongly typed
• Tests are easy to generate from System Use Cases

AIUP connects these elements with a straightforward process.

Benefits For Teams

• Clear Requirements
  Rules, constraints, and user stories are explicit.
• Consistent Architecture
  UI, Backend, and database reflect the same model.
• Faster Onboarding
  New developers read the specs instead of guessing
• Safer Use Of AI
  AI follows the spec and avoids random patterns.
• Higher Speed
  AI handles repetitive tasks
• Lower Risk
  System Use Cases generate strong test coverage.

AI Is A Partner, Not A Replacement

AIUP assumes a skilled development team. Developers still:

• Make architectural decisions
• Review the generated code
• Ensure security
• Ensure performance
• Adjust implementation details

AI accelerates work. Developers ensure correctness.

Conclusion

Spec-Driven Development with AIUP provides teams with a structured approach to using AI. AI can generate code, tests, and diagrams that stay consistent with the specification.

In a Java stack using Spring Boot, jOOQ, and Vaadin, this approach is a natural fit. It increases speed, improves quality, and keeps the system aligned with business needs.

To get started:

• Write the Requirements Catalog
• Define the Entity Model
• Add System Use Cases
• Let AI generate code and tests
• Review, refine, and repeat

This is how AIUP makes full-stack Java development faster, safer, and more consistent.

See it in Action

Two webinar recordings show how to work with the AIUP: Spec-driven Development and Spec-driven Testing

The post Spec-Driven Development in Practice: How AI Simplify Full-Stack Java appeared first on JVM Advent.

1. groupByUniqueKey(): Eclipse Collections offers a way to transform and collect the output in a map, where the key is the transformed value. The groupByUniqueKey() API ensures that the generated keys must each be unique, or else an exception is thrown. This is an easy way to create a map from a collection and guarantee that no keys are overridden.

   @Test
   public void groupByUniqueKey() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableMap<Integer, Integer> groupByUniqueKeyMap =
           list.groupByUniqueKey(
               each -> -1 * each); // Negate each integer
       
       MutableMap<Integer, Integer> expectedMap =
           Maps.mutable.of(
               -1, 1, //key, value pairs
               -2, 2,
               -3, 3,
               -4, 4);
       assertEquals(expectedMap, groupByUniqueKeyMap);
   }
   
   @Test
   public void groupByUniqueKey_throws() {
       MutableList list = Lists.mutable.of(1, 2, 2, 3);
       
       // Throws exception because the element 2 is a duplicate
       assertThrows(
               IllegalStateException.class,
               () -> list.groupByUniqueKey(each -> each));
   }
   

2. countByEach(): Eclipse Collections offers a way to count the number of occurrences of each value after transforming each element of a collection. The countByEach() API does it by iterating through the collection and applying the function to each element and then counting the number of occurrences of the transformed value. This API returns a Bag which is an optimized data structure for counting number of objects. This is similar to the countBy() API that I covered in the 2019 blog with the difference that in case of countByEach() the transformation function returns an Iterable

   @Test
   public void countByEach() {
       MutableList<Integer> list = Lists.mutable.of(1, 2, 3, 4);
   
       MutableBag<Integer> counts = list
           .countByEach(
               each -> Lists.mutable.of(each, each + 1));
   
       assertEquals(1, counts.occurrencesOf(1));
       assertEquals(2, counts.occurrencesOf(2));
       assertEquals(2, counts.occurrencesOf(3));
       assertEquals(2, counts.occurrencesOf(4));
       assertEquals(1, counts.occurrencesOf(5));
   }

3. sumBy*(): Eclipse Collections offers a way to group and sum elements of the collection using sumByInt(), sumByLong(), sumByDouble(), and sumByFloat() methods. A salient point to note is that the return types are up-casted i.e. sumByInt() returns a ObjectLongMap and sumByFloat() returns a ObjectDoubleMap. This avoids overflow issues in the results.

   // Common function to classify even and odd numbers
   Function<Integer, String> mappingFunction = each ->
       {
           if (each % 2 == 0) {
               return "EVEN";
           }
           return "ODD";
       };
   
   @Test
   public void sumByInt() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableObjectLongMap sumByInt = list.sumByInt(
               mappingFunction,
               each -> each);
   
       MutableObjectLongMap expected =
           ObjectLongMaps.mutable.of(
               "EVEN", 6L, //key, value pairs
               "ODD", 4L);
       assertEquals(expected, sumByInt);
   }
   
   @Test
   public void sumByLong() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableObjectLongMap sumByLong = list.sumByLong(
               mappingFunction,
               Integer::longValue);
   
       MutableObjectLongMap expected =
           ObjectLongMaps.mutable.of(
               "EVEN", 6L, //key, value pairs
               "ODD", 4L);
       assertEquals(expected, sumByLong);
   }
   
   @Test
   public void sumByDouble() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableObjectDoubleMap sumByDouble = list.sumByDouble(
               mappingFunction,
               Integer::doubleValue);
   
       MutableObjectDoubleMap expected =
           ObjectDoubleMaps.mutable.of(
               "EVEN", 6.0, //key, value pairs
               "ODD", 4.0);
       assertEquals(expected, sumByDouble);
   }
   
   @Test
   public void sumByFloat() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableObjectDoubleMap sumByFloat = list.sumByFloat(
               mappingFunction,
               Integer::floatValue);
   
       MutableObjectDoubleMap expected =
           ObjectDoubleMaps.mutable.of(
               "EVEN", 6.0, //key, value pairs
               "ODD", 4.0);
       assertEquals(expected, sumByFloat);
   }
   

4. aggregateBy(): Eclipse Collections offers a way to aggregate and group results into a map using a grouping function. Please note the API signature — the first input is the grouping function, second input is the zero value function, and the last input is the aggregation function. The code below shows how each of these inputs impacts the behavior.

   @Test
   public void aggregateBy() {
       MutableList list = Lists.mutable.of(1, 2, 3, 4);
       MutableMap<String, Integer> aggregateBy1 =
           list.aggregateBy(
               mappingFunction, () -> 0, Integer::sum);
   
       // Note that because the zero value is in this case 0,
       // the result is that
       // sum of even numbers is 0 + 2 + 4 = 6; 
       // sum of odd numbers is 0 + 1 + 3 = 4
       MutableMap<String, Integer> expected1 = Maps.mutable.of(
               "EVEN", 6,
               "ODD", 4);
   
       assertEquals(expected1, aggregateBy1);
   
       MutableMap<String, Integer> aggregateBy2 =
           list.aggregateBy(
               mappingFunction, () -> 10, Integer::sum);
   
       // Note that because the zero value is in this case 10,
       // the result is that 
       // sum of even numbers is 10 + 2 + 4 = 16; 
       // sum of odd numbers is 10 + 1 + 3 = 14
       MutableMap<String, Integer> expected2 = Maps.mutable.of(
               "EVEN", 16,
               "ODD", 14);
   
       assertEquals(expected2, aggregateBy2);
   
       MutableMap<String, Integer> aggregateBy3 =
           list.aggregateBy(
               mappingFunction, 
               () -> 0, 
               (before, each) -> before + each + 10);
   
       // Note that because the aggregation function adds 10 to
       // every computation, the computation becomes: 
       // for even numbers: 0 + (2 + 10) + (4 + 10) = 26; 
       // for odd numbers: 0 + (1 + 10) + (3 + 10) = 24
       MutableMap<String, Integer> expected3 = Maps.mutable.of(
               "EVEN", 26,
               "ODD", 24);
   
       assertEquals(expected3, aggregateBy3);
   }

The post Hidden Treasures of Eclipse Collections 2025 Edition appeared first on JVM Advent.

While these build tools continue to improve their own development practices, their use alone is not enough to ensure that your artifacts, build pipelines, compiler tool chains, and other working parts of your software supply chain are secure and resistant to tampering or attacks. The Supply-chain Levels for Software Artifacts project, or SLSA (pronounced “salsa”) is a it’s a security framework, a checklist of standards and controls to prevent tampering, improve integrity, and secure packages and infrastructure. In its landing page you’ll find the following description regarding places where potential attacks may occur

© 2025 The Linux Foundation

Yes, attacks may come from many places but also happen at many locations within the software supply chain.

We must take action at different locations, fortunately the previously mentioned build tools provide some support but we need a few more things. Do you recall the news that shocked the IT world in December 2021? That’s right, it was Log4Shell. Or the failed XZ Backdoor from 2024? These and many other attacks could have been prevented or have their impact lessened if specific techniques, additional metadata, and tools were also available and applied on time.

Let’s begin with the straight forward ones, then move on with more complex options. But before we do, I would like to remark that JReleaser, while not strictly a build tool but rather a release tool, provides support for all of the features we’ll cover. Onward.

Reproducible Artifacts

Reproducible artifacts come from Reproducible Builds, a software development practice where building the exact same source code with the same tools and instructions always results in a bit-for-bit identical binary output. If you happen to have a compatible reproducible environment (similar or identical OS, Java distribution, environment variables, etc) then you may rebuild a given codebase at an specific point of its history (say a tagged release) and obtain a bit-by-bit identical set of artifacts that may be compared at different build dates.

Luckily for many Java developers, Maven makes it quite easy to generate reproducible artifacts (JARs, ZIPs, TARs) by simply setting a fixed timestamp. Gradle offers similar capabilities although the value of the timestamp can’t be changed. JReleaser also lets you assemble reproducible archives with any of its assemblers.

For example, this repository contains a simple Helloworld project. Its build creates an executable JAR file, while its release configuration defines a binary distribution as a ZIP file. Here’s a short snippet of said configuration

assemble:
  javaArchive:
    helloworld:
      active: ALWAYS
      formats: [ ZIP ]
      fileSets:
        - input: '.'
          includes: [ 'LICENSE' ]
      mainJar:
        path: target/{{distributionName}}-{{projectVersion}}.jar

Invoking the assemble command results in archive containing the following entries:

Archive: java-archive/helloworld-1.0.0.zip
Length Date Time Name
--------- ---------- ----- ----
    11357 01-06-2025 19:30 helloworld-1.0.0/LICENSE
     4533 01-06-2025 19:30 helloworld-1.0.0/bin/helloworld
     1889 01-06-2025 19:30 helloworld-1.0.0/bin/helloworld.bat
     3777 01-06-2025 19:30 helloworld-1.0.0/lib/helloworld-1.0.0.jar
--------- -------
    21556 4 files

That timestamp may look arbitrary but its guaranteed to be reproducible, as it happens to match the tagged commit for that release, which is

commit eaa60a9314e3555db6e44da8442808d46f2fcd35
Author: Andres Almiray <aalmiray@gmail.com>
Date: Mon Jan 6 19:30:58 2025 +0100

Neat, isn’t it? Let’s continue.

Digital Signatures

Another way to add an extra layer of security is by providing digital signatures for a given set of artifacts. We’ve been using PGP for decades since its inception. Pretty much every build tool supports generating these kind of signatures with either explicit mechanism (plugins) or calling out to external commands (gnupg for example).

This works fine, except when it doesn’t, which is when key management comes into play. Some developers are lazy and set their keys to never expire, while some are too concerned that they rotate their keys quite often. No matter where you stand in the key management spectrum, it requires performing additional tasks as a burden. For this reason, a new idea emerged a bit more than a decade ago: Sigstore.

Sigstore provides an alternative for automating artifact signing and signature verification. While the signing tool was originally created for signing container images (hence the name cosign) and written in Go, nowadays there’s a Java API that enables Maven and Gradle support. JReleaser in turn also supports generating signatures for all artifacts to be released as either PGP or Sigstore, making it easier to provide such signatures as it doesn’t matter how those artifacts were built/assembled or which tool did it.

Enabling digital signatures for a release, whether with PGP or Sigstore, is quite easy with JReleaser, for example, the minimum configuration would be something similar to

signing:
  active: ALWAYS
  armored: true

Where’s the rest? Well, the values of the public & secret keys, as well as an associated passphrase (when required) may be supplied via environment variables, to keep these value as secrets.

SBOMs and SWID Tags

The next level of protection is comprised of additional metadata files that may be used to inspect an artifact for its set of dependencies, or in the case of an archive, for its contained files. By now I hope you’ve heard of SBOMs and how to procure them during a build. SBOMs have become more important these days as software vendors and makers will be required to provide them upon request, according to CRA and DORA.

Both Maven and Gradle provide plugins that generate SBOMs in different formats. You may also use Syft to create such files. These SBOMs should provide a list of all dependencies required for building the matching artifact, a JAR file in this case. But what about ZIPs and TARs, or other kind of archives? In this case JReleaser can generate SBOMs for all archives created via any of its assemblers.

Here’s a snippet showing how you can configure SBOM generation for artifacts using both cyclonedx and Syft. The resulting SBOMs will be packaged in a single ZIP and will be available to be uploaded as release assets

catalog:
  sbom:
    cyclonedx:
      active: ALWAYS
      pack:
       enabled: true
       name: '{{projectName}}-{{projectVersion}}-cyclonedx-sboms'
    syft:
      active: ALWAYS
      pack:
      enabled: true
      name: '{{projectName}}-{{projectVersion}}-syft-sboms'

You only need one format or the other, this particular example shows how easy is to configure either format.

Additionally to SBOMs there’s also SWID Tags, created by the National Institute of Standards and Technology (NIST). This format provides a thorough list of all entries found inside a given archive, with a checksum per entry. Computing both SBOMs and SWID Tags provides a level of redundancy as the same checksum values should appear in both files, making it harder for an attacker to fake values. Also, you may be contractually obligated to deliver such files depending on the type of projects and customers you may be working with. As far as I recall there’s a Maven plugin for generating SWID tags but no Gradle plugin.

Activating SWID tag generation for assembled archives is as easy as configuring the following snippet in your JReleaser configuration file

catalog:
  swid:
    swid-tag:
      active: ALWAYS

Now, adding SWID tag to a given assembly is done as follows

assemble:
  javaArchive:
    helloworld:
      active: ALWAYS
      formats: [ ZIP ]
      fileSets:
        - input: '.'
          includes: [ 'LICENSE' ]
      mainJar:
        path: target/{{distributionName}}-{{projectVersion}}.jar
      swid:
        tagRef: swid-tag

Notice the reference to swid-tag, which is the custom name that we defined in a previous snippet.

Attestation Files

Attestations bind some subject (a named artifact along with its digest) to a predicate (some assertion about that subject) using the in-toto format. Predicates consist of a type URI and a JSON object containing type-dependent parameters.

Attestation files are usually digitally signed, and guess what, this is where Sigstore appears again. Attestation providers also offer a command line tool that may be used to verify the signatures of the attestation files, as well as their contents.

If you happen to use GitHub (whether free or enterprise) then you have access to GitHub Attestations. Making use of this feature is straight forward and requires you to use the actions/attest action. There are a few ways to supply the list of files to be included for attestation, one of them is a checksums file. It so happens that JReleaser automatically calculates such a file when a release is performed, or when the checksum command is explicitly invoked. This makes it quite easy to combine it with the actions/attest action, like so

- name: Release
  uses: jreleaser/release-action@v2
  with:
    arguments: release
  env:
    # change this value to your own version number
    JRELEASER_PROJECT_VERSION: 1.2.3

- name: Attestations
  uses: actions/attest-build-provenance@v1
  with:
    subject-checksums: out/jreleaser/checksums/. checksums_sha256.txt
  predicate-type: 'https://example.com/predicate/v1'
  predicate: '{}'

The SLSA framework also provides its own attestation feature. You may run it directly from GitHub via the slsa-framework/slsa-github-generator, for which you’d need to configure more things depending on your build requirements. Luckily the SLSA team made things easier by enabling other tools to create their own sanctioned SLSA builders (BYOB), as explained in this link.

JReleaser is an early adopter of the BYOB feature, providing a seamless integration with GitHub Actions. The jreleaser/helloworld-java-slsa  repository showcases how this integration works. There is one thing to take into consideration, the SLSA builder must be provided with both build and release instructions, as they must happen within a controlled environment. I said earlier that JReleaser is a release tool, not a build tool, however it does allow custom commands to be invoked at certain stages of its execution. Thus if we’re able to supply build instructions that are guaranteed to be invoked before a release then we should be good to go. And that’s exactly what we can do.

The release configuration file in the helloworld-java-slsa repository has a section specifying the required build instructions, and that they should be invoked during the assemble step.

hooks:
  script:
    before:
      - run: './mvnw -ntp verify'
        condition: '"{{ Env.CI }}" == true'
        verbose: true
        filter:
          includes: ['assemble']

Now, the next bit of configuration is found in a GitHub Actions workflow such as this one

 release:
   name: Release
   needs: [ precheck ]
   permissions:
     contents: write
     id-token: write
     actions: read
     packages: write
   uses: jreleaser/jreleaser-slsa/.github/workflows/builder_slsa3_java.yml@v1.1.0
  with:
    project-version: ${{ needs.precheck.outputs.VERSION }}
    rekor-log-public: true
  secrets:
  github-token: ${{ secrets.GITHUB_TOKEN }}

This snippet defines specific permissions granted to the default GITHUB_TOKEN, such that the invoked trusted workflow (builder_slsa4_java.yml) can not access more than it shouldn’t. This trusted workflow will in turn invoke the SLSA generator and make sure that the attestation file is attached as a release asset. It all just happens automagically as seen in this release:

And tough this is a Java Advent entry, I would be remiss it I did not mention that JReleaser can be used with any kind of project independent of its source code, its not just for Java. Likewise, the SLSA support offered by JReleaser may be used with Go, Rust, and Zig, with additional languages coming later.

Summary

Securing your Software Supply Chain requires a paradigm shift, adapting build and releases processes, learning new tools and techniques. The build tools you’re already used to may provide answers to some of these concerns, while JReleaser provides additional support, specifically during the release portion of the chain.

The post Strengthening your Software Supply Chain appeared first on JVM Advent.

Recently, the TornadoVM team released gpullama3, a proof-of-concept demonstrating LLM inference on GPUs using pure Java. Let’s explore this together!

What is TornadoVM?

TornadoVM is a plugin for the OpenJDK that enables Java programs to automatically run on heterogeneous hardware (GPUs, FPGAs, and multi-core CPUs) using standard Java code annotated for parallel compute.

Under the hood, TornadoVM:

1. takes your Java bytecode
2. compiles it to GPU-specific kernels (via OpenCL, PTX, or SPIR-V)
3. manages data transfers between CPU and GPU memory
4. executes the computation on the GPU
5. returns the results back to your Java program

Transformer-based language models are computationally expensive but highly-parallelizable. At inference time, generating each token requires matrix multiplications across billions of parameters. GPUs excel at these operations because they can perform thousands of computations in parallel. Thus, TornadoVM is the perfect tool for this kind of workload.

Installing TornadoVM

Installing GPULlama3.java was surprisingly straightforward. Make sure you have your favorite flavor of JDK 21 installed. I use sdkman, so I made sure I had Temurin 21 installed:

sdk install java 21.0.9-tem

Then you’ll want to make sure you have installed cmake, a C/C++ toolchain, Python and pip. Now you can clone the repo:

git clone https://github.com/beehive-lab/GPULlama3.java

and follow the instructions on the README; for instance, on macOS/Linux:

# Enter the TornadoVM submodule directory
cd external/tornadovm

# Optional: Create and activate a Python virtual environment if needed
python3 -m venv venv
source ./venv/bin/activate

# Install TornadoVM with a supported JDK 21 and select the backends (--backend opencl,ptx).
# To see the compatible JDKs run: ./bin/tornadovm-installer --listJDKs
# For example, to install with OpenJDK 21 and build the OpenCL backend, run: 
./bin/tornadovm-installer --jdk jdk21 --backend opencl

# Source the TornadoVM environment variables
source setvars.sh

You can verify the installation was successful by running one example:

cd tornado-examples
mvn package
cd ..
tornado -cp tornado-examples/target/tornado-examples-1.1.2-dev-e1d2d12.jar uk.ac.manchester.tornado.examples.compute.MatrixVectorRowMajor

Of course, make sure you replace tornado-examples-1.1.2-dev-e1d2d12.jar with the right jar name! Your output should look something like this:

WARNING: Using incubator modules: jdk.incubator.vector
Matrix-Vector Multiplication Benchmark
======================================
Configuration:
- Input dimension (columns): 8192
- Output dimension (rows): 2048
- Local work group size: 32
- Backend: OPENCL
- DP4A benchmarks enabled: false
- Warmup iterations: 140
- Benchmark iterations: 120

Initializing data...
Setting up TornadoVM execution...
Warming up sequential implementation...
Benchmarking sequential implementation...
Warming up parallel implementation...
Benchmarking parallel implementation...
Validating results...
Validation PASSED ✓

Performance Results:
====================
Matrix size: 2048 x 8192
Sequential Implementation:
  Average time: 15.892 ms
  Min time: 15.673 ms
  Max time: 16.795 ms
  Performance: 2.11 GFLOP/s
Parallel Implementation (TornadoVM):
  Average time: 2.405 ms
  Min time: 2.030 ms
  Max time: 5.069 ms
  Performance: 13.95 GFLOP/s
Pure TornadoVM @Parallel Implementation (TornadoVM):
  Average time: 4.931 ms
  Min time: 3.745 ms
  Max time: 8.357 ms
  Performance: 6.81 GFLOP/s
Parallel Implementation FP16 (TornadoVM):
  Average time: 1.840 ms
  Min time: 1.575 ms
  Max time: 3.090 ms
  Performance: 18.24 GFLOP/s
Q8 Vectorized:
  Average time: 1.746 ms
  Min time: 1.459 ms
  Max time: 6.097 ms
  Performance: 19.22 GFLOP/s

Speedup: KernelContext vs Java 6.61x
Speedup: @Parallel vs Java 3.22x
Speedup: KernelContext vs @Parallel 2.05x
Speedup: Q8 Vectorized vs KernelContext 1.38x
Speedup: Q8 Vectorized vs KernelContext FP16 1.05x

Baby’s First GPU Kernel

Here’s a simple Example.java:

import uk.ac.manchester.tornado.api.annotations.*;
import uk.ac.manchester.tornado.api.*;
import uk.ac.manchester.tornado.api.enums.DataTransferMode;
import uk.ac.manchester.tornado.api.types.arrays.FloatArray;

public class Example {
    
    public static void vectorMul(FloatArray a, FloatArray b, FloatArray result) {
        for (@Parallel int i = 0; i < result.getSize(); i++) {
            result.set(i, a.get(i) * b.get(i));
        }
    }

    public static void main(String... args) {
        int size = 1024;
        
        var a = new FloatArray(size);
        var b = new FloatArray(size);
        var result = new FloatArray(size);
        
        for (int i = 0; i < size; i++) {
            a.set(i, i * 2.0f);
            b.set(i, i + 1.0f);
        }
        
        var taskGraph = new TaskGraph("multiply")
            .transferToDevice(DataTransferMode.FIRST_EXECUTION, a, b)
            .task("vectorMul", Example::vectorMul, a, b, result)
            .transferToHost(DataTransferMode.EVERY_EXECUTION, result);

        var snapshot = taskGraph.snapshot();
        new TornadoExecutionPlan(snapshot).execute();
        
        System.out.println("\nVector Multiplication Results (first 10):");
        for (int i = 0; i < 10; i++) {
            System.out.printf("result[%d] = %.2f (a[%d]=%.2f * b[%d]=%.2f)\n", 
                i, result.get(i), i, a.get(i), i, b.get(i));
        }
    }
}

The @Parallel annotation tells TornadoVM this loop can be parallelized. The TaskGraph API manages data movement and execution scheduling. You can compile it with the following (if you followed the installation guide correctly $TORNADO_SDK will point to the right path):

javac -g --enable-preview -source 21 -cp "$TORNADO_SDK/share/java/tornado/*" Example.java

Notice that -g is required for this to work correctly. Now you can run it with:

tornado Example

It will print the first 10 items in the resulting vector.

Playing with GPULlama3.java

The gpullama3 project demonstrates running a Llama 3 model entirely in Java with GPU acceleration. Assuming you are back at the root of the repo, continue with the setup procedure.

# Navigate back to the project root directory
cd ../../

# Source the project-specific environment paths -> this will ensure the correct paths are set for the project and the TornadoVM SDK
# Expect to see: [INFO] Environment configured for Llama3 with TornadoVM at: /home/YOUR_PATH_TO_TORNADOVM
source set_paths

# Build the project using Maven (skip tests for faster build)
# mvn clean package -DskipTests or just make
make

Now let’s download a compatible model using the HuggingFace CLI:

# download and install the hugging face CLI
pip install -U huggingface_hub

# download a model to ./models/
hf download beehive-lab/Llama-3.2-1B-Instruct-GGUF-FP16 --include '*.gguf' --local-dir models

Try it! Even on my poor MacBook Air with 8 GB RAM (provided I don’t have too many applications open) this returns:

❯ python llama-tornado --gpu --verbose-init --opencl --model models/Llama-3.2-1B-Instruct-FP16.gguf --prompt "tell me a joke"
WARNING: Using incubator modules: jdk.incubator.vector
Loading model weights in TornadoVM format (loading F16)

Starting TornadoVM initialization...
TornadoVM GPU execution plan creation: 1011.56 ms
Java to GPU JIT compiler warmup: 4994.25 ms
Transfer read-only weights to GPU: 13958.97 ms
Finished TornadoVM initialization...

Here's one:

What do you call a fake noodle?

(wait for it...)

An impasta!

Hope that made you laugh!


achieved tok/s: 3.00. Tokens: 42, seconds: 13.98

Disclaimer: even if you have better CPU/GPUs at your disposal, they are unlikely to affect the quality of the joke.

What just happened?

GPULlama3.java currently supports a few FP16 (16-bit floating point) and 8-bit quantized models:

• Llama 3.2 (1B) – FP16
• Llama 3.2 (3B) – FP16
• Llama 3 (8B) – FP16
• Mistral (7B) – FP16
• Qwen3 (0.6B) – FP16
• Qwen3 (1.7B) – FP16
• Qwen3 (4B) – FP16
• Qwen3 (8B) – FP16
• Phi-3-mini-4k – FP16
• Qwen2.5 (0.5B)
• Qwen2.5 (1.5B)
• DeepSeek-R1-Distill-Qwen (1.5B)

Depending on the model being selected, a different execution plan will be built. The execution plan corresponds to the model architecture. In our case, we picked the unquantized Llama 3.2 1B FP16. Let’s take a look at the setupTornadoForwardPlan() method in FP16LayerPlanner, used by LLama 3.2:

abstract class FP16LayerPlanner ... {
    ...
    protected final void setupTornadoForwardPlan() {
        List<ImmutableTaskGraph> allTaskGraphs = new ArrayList<>();
        GridScheduler masterScheduler = new GridScheduler();

        // 1. Activation layer (common to all models)
        allTaskGraphs.add(activationLayer.getImmutableTaskGraph());
        activationLayer.updateGridScheduler(masterScheduler);

        // 2. FFN layers (N transformer layers - model-specific)
        allTaskGraphs.addAll(ffnLayers.getFfnLayerTaskGraphs());
        ffnLayers.updateGridScheduler(masterScheduler);

        // 3. Logits layer (common to all models)
        allTaskGraphs.add(logitsLayer.getTaskGraph().snapshot());
        logitsLayer.updateGridScheduler(masterScheduler);

        // Cache for future retrievals
        this.immutableTaskGraphs = allTaskGraphs;
        this.gridScheduler = masterScheduler;
    }

}

In the Activation layer we mostly look up token embeddings and apply an initial normalization step, while the Logit layer is where we convert the model’s internal representation into token predictions. So let’s concentrate a bit more on the Feed-Forward Network layer (FFN), and in particular on the Attention implementation. The LlamaFP16FFNLayers#setupSingleFFNLayer method is a bit cryptic at a first glance; let’st start from its signature:

TaskGraph setupSingleFFNLayer(LlamaTornadoWeights weights, Configuration config, int layerIndex)

The method is building a TaskGraph, essentially describing the data flow of our GPU kernels. Let’s focus on QKV and attention, using Sebastian Raschka¹‘s excellent Python Notebook as a reference. The following is the architecture diagram of the Llama 3.2 1B model:

For obvious reasons of brevity, we aren’t going to explore this in detail, but we do want to take a look at the implementation of the attention heads. In particular, let’s take a look at how we compute the Query, Key, Value matrices (Q,K,V = project(x) in the Python version):

.task("qmatmul", 
        TransformerComputeKernelsLayered::matrixVectorGeneric, context, 
        state.wrapXb, state.wrapQ, 
        weights.wqLayered[layerIndex].asHalfFloatArray(), 
        config.dim(), config.dim(),
        LOCAL_WORK_GROUP_SIZE_ALLOC)
.task("kmatmul", 
        TransformerComputeKernelsLayered::matrixVectorGeneric, context, 
        state.wrapXb, state.wrapK, 
        weights.wkLayered[layerIndex].asHalfFloatArray(), 
        config.dim(), config.kvDim(),
        LOCAL_WORK_GROUP_SIZE_ALLOC)
.task("vmatmul", 
        TransformerComputeKernelsLayered::matrixVectorGeneric, context, 
        state.wrapXb, state.wrapV, 
        weights.wvLayered[layerIndex].asHalfFloatArray(), 
        config.dim(), config.kvDim(),
        LOCAL_WORK_GROUP_SIZE_ALLOC)

This is followed by the RoPE rescaling to encode token positions:

.task("rope", TransformerComputeKernelsLayered::ropeRotation, context, 
        state.positionHolder, 
        state.wrapQ, state.wrapK, 
        config.kvDim(), 
        config.headSize())

Now we are ready to compute attention. The generic version (there is also an NVidia-specific implementation) is:

unifiedLayer.task("parallel-attention", TransformerComputeKernelsLayered::processHeadsParallel, 
        state.wrapQ, state.wrapKeyCache, state.wrapValueCache, state.wrapXb,
        config.numberOfHeads(), config.headSize(), config.kvDim(), config.kvMul(),
             config.contextLength(), 
        state.positionHolder, state.wrapAtt, 
        layerIndex, config.contextLength());

Let’s drill down into TransformerComputeKernelsLayered::processHeadsParallel to see how that is performed. The following is one of the GPU kernels. It essentially computes:

You will notice that the method:

1. takes the Q,K (Query, Key) vectors that we computed earlier and it computes the attention score up to the current position pos (scaled by the square root of the head size), filling the wrapAtt vector
2. next, it applies softmax to the wrapAtt, turning the scores into attention weights (steps 2-4), accumulating partial results onto the same wrapAtt vector
3. finally (step 5) it computes a weighted sum of the Value vectors (value_cache) up to pos, using the calculated Attention Weights (wrapAtt). 

    /**
     * Computes attention for a single head. Implements scaled dot-product attention with softmax normalization.
     *
     * Steps: 1. Compute attention scores: Q·K / sqrt(head_size) 2. Apply softmax (with max subtraction for numerical stability) 3. Compute weighted sum of values
     *
     * @param allQ
     *         All query vectors
     * @param key_cache
     *         Cached keys
     * @param value_cache
     *         Cached values
     * @param allXb
     *         Output buffer
     * @param h
     *         Head index to process
     * @param headSize
     *         Dimension per head
     * @param kvDim
     *         Key/value dimension
     * @param kvMul
     *         Key multiplier for grouped attention
     * @param loff
     *         Layer offset in cache
     * @param pos
     *         Current position
     * @param wrapAtt
     *         Attention weights buffer
     */
    private static void processHeadTornado(FloatArray allQ, FloatArray key_cache, FloatArray value_cache, FloatArray allXb, int h, int headSize, int kvDim, int kvMul, long loff, int pos,
            FloatArray wrapAtt) {

        // Base index for this head's attention weights
        int headOffset = h * (pos + 1);

        // STEP 1: Calculate attention scores for all timesteps
        for (int t = 0; t <= pos; t++) {
            int kvHeadIdx = h / kvMul;
            int keyOffset = (int) (loff + t * kvDim + kvHeadIdx * headSize);

            float score = 0.0f;
            for (int i = 0; i < headSize; i++) {
                score += allQ.get(h * headSize + i) * key_cache.get(keyOffset + i);
            }
            score = score / TornadoMath.sqrt(headSize);

            // Store in attention buffer
            wrapAtt.set(headOffset + t, score);
        }

        // STEP 2: Find max score for softmax stability
        float maxScore = wrapAtt.get(headOffset);
        for (int t = 1; t <= pos; t++) {
            float val = wrapAtt.get(headOffset + t);
            if (val > maxScore) {
                maxScore = val;
            }
        }

        // STEP 3: Compute exponentials and sum
        float sum = 0.0f;
        for (int t = 0; t <= pos; t++) {
            int idx = headOffset + t;
            float expScore = TornadoMath.exp(wrapAtt.get(idx) - maxScore);
            wrapAtt.set(idx, expScore);
            sum += expScore;
        }

        // STEP 4: Normalize
        float normFactor = (sum > 0.0f) ? (1.0f / sum) : (1.0f / (pos + 1));
        for (int t = 0; t <= pos; t++) {
            int idx = headOffset + t;
            wrapAtt.set(idx, wrapAtt.get(idx) * normFactor);
        }

        // STEP 5: Compute weighted sum of values for each dimension
        for (int i = 0; i < headSize; i++) {
            float weightedSum = 0.0f;
            for (int t = 0; t <= pos; t++) {
                int kvHeadIdx = h / kvMul;
                int valueOffset = (int) (loff + t * kvDim + kvHeadIdx * headSize);
                weightedSum += wrapAtt.get(headOffset + t) * value_cache.get(valueOffset + i);
            }
            allXb.set(h * headSize + i, weightedSum);
        }
    }

After the attention mechanism computes relationships between tokens, the result is added to the original input, normalized, and passed through a feed-forward network. This process repeats across multiple layers before finally producing the next-token prediction (the logit layer).

Because it’s an autoregressive model, this entire process repeats for each token, using the previously generated sequence as input.

In short, TornadoVM handled GPU compilation and execution transparently, allowing a pure Java program to perform LLM inference!

Conclusions

We’ve completed our whirlwind tour of Llama3GPU.java and TornadoVM. If your head is still spinning, don’t worry, you’re not alone! It’s a lot to take in, but I hope this post has sparked your interest and inspired you to dig deeper: I know I will!

1. Sebastian Raschka is the author of Build a Large Language Model from Scratch ↩︎

The post A Glance at GPU Goodness in Java: LLM Inference with TornadoVM appeared first on JVM Advent.

The post Breaking keys and building trust: The JAVA way! appeared first on JVM Advent.

# Install the Quarkus CLI
curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio
‎

# Clone the starter repo (or download):
git clone https://github.com/ia3andy/the-code-site.git
cd the-code-site
‎ 

the-coder-site/
├── content/
│   ├── index.html                # Website index page and metadata
│   └── **                        # Articles and pages
├── public/images/                # Images for your site
├── web/
│   ├── *.js                      # Scripts (auto-bundled)
│   └── *.css                     # Styles (auto-bundled)
├── templates/
│   ├── layouts/
│   │   ├── default.html          # Base HTML structure
│   │   ├── post.html             # Layout for a blog post
│   │   └── page.html             # Layout for a page
│   └── partials/
│       ├── header.html           # Site header
│       └── footer.html           # Site footer
├── config/application.properties # Site config 
├── pom.xml                       # Quarkus setup (Roq, TailwindCSS)
└── ...                           # Gitignore, Maven Wrapper

Let’s start Quarkus Dev-Mode:

quarkus dev
‎ 

---
layout: default
title: Your Name
description: >-
  Personal blog - A programmer sharing thoughts on software development,
  Java, and web technologies.
greeting: Hi, I'm Your Name!
tagline: Just a coder
navigation:
  - title: Blog
    url: /
  - title: Tags
    url: /tags
  - title: About
    url: /about
paginate: posts
---

@theme {
    --font-sans: 'Atkinson Hyperlegible', system-ui, -apple-system, sans-serif;
    --color-primary: #7c2d12;
    --color-secondary: #9a3412;
    --color-tertiary: #ea580c;
    --color-surface: #fff7ed;
    --color-surface-2: #ffedd5;
    --color-surface-3: #fed7aa;
    --color-card: #ffffff;
    --color-card-border: #fdba74;
    --color-border: #fdba74;
    --color-border-strong: #fb923c;
    --color-code-bg: #fff7ed;
    --color-code-text: #c2410c;
    --color-pre-bg: #ffedd5;
    --color-pre-text: #7c2d12;
    --color-accent-300: #fdba74;
    --color-accent-400: #fb923c;
    --color-accent-500: #f97316;
    --color-accent-600: #ea580c;
    --color-accent-700: #c2410c;
}

alert('Hello Roq');
 

items:
  - title: Blog
    url: /
  - title: Tags
    url: /tags
  - title: About
    url: /about

- {#for item in site.data.navigation}
+ {#for item in cdi:navigation.items}

<h1 class="text-4xl font-bold tracking-tight sm:text-5xl">One template to rule them all </h1>
 

The post Discover Roq, the Quarkus Way for Static Site Generation in Java appeared first on JVM Advent.

Since Java 14, the Java switch and instanceof statements have been enhanced, in multiple phases, to support pattern matching and a “data-oriented” programming style. In this article, I explore when this programming style is beneficial, and why. I look at the sweet spot of perfect pattern usage, absolute antipatterns where it should not be used, no matter how many examples you see in blogs and conference presentations, and corner cases where the switch syntax clashes with legacy behavior.

Sealed Hierarchies and Records are Nice

Pattern matching is one of the shiny new objects in the Java language. Maybe not that new anymore—it started with Java 14. And maybe not that shiny. How many times have you used it in your code?

There may be a reason. Pattern matching works best with a sealed hierarchy of interfaces and record types. (If you want to show off, you can call them “algebraic data types”.) Everywhere that you have such a hierarchy, pattern matching is a natural tool.

How many such hierarchies do you have in your code base? Well, that may explain why you are not often reaching for that tool.

Some people argue that you should actively organize your data into such a form. This is sometimes called data-oriented programming, and it can be a good idea when it fits the problem domain. For examples with a business context, I can recommend this book by Chris Kiehl, currently in early access. He discusses real-life scenarios, such as

public sealed interface Lifecycle {
    record Pending() implements Lifecycle {}
    record Billed(String invoiceId) implements Lifecycle {}
    record Rejected(Reason reason) implements Lifecycle {}
    record InReview(ApprovalId approvalId) implements Lifecycle {}
}

Since these scenarios require a fair amount of domain knowledge, let me use a simple and familiar example: JSON values. There are four kinds of primitive values, and arrays and objects.

Make the leaves of the inheritance tree into records, or, if they only have finitely many instances, into enums. And all other types into sealed interfaces:

sealed interface JSONValue {}
sealed interface JSONPrimitive extends JSONValue {}

enum JSONBoolean implements JSONPrimitive { FALSE, TRUE; }
enum JSONNull implements JSONPrimitive { INSTANCE; }

record JSONNumber(double value) implements JSONPrimitive {}
record JSONString(String value) implements JSONPrimitive {}

record JSONArray(List<JSONValue> values) implements JSONValue {}
record JSONObject(Map<String, JSONValue> entries) implements JSONValue {}

Now we can use pattern matching:

static String quote(String s) {
    return "\"" + s.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
}

static String stringify(JSONValue j) {
    return switch (j) {
        case JSONNumber(var v) -> "" + v;
        case JSONString(var s) -> quote(s);
        case JSONBoolean.TRUE -> "true";
        case JSONBoolean.FALSE -> "false";
        case JSONNull.INSTANCE -> "null";
        case JSONArray(var values) ->
            values.stream()
            .map(this::stringify)
            .collect(Collectors.joining(",", "[", "]"));
        case JSONObject(var entries) ->
            entries.entrySet()
            .stream()
            .map(e -> quote(e.getKey()) + ":" + stringify(e.getValue()))
            .collect(Collectors.joining(",", "{", "}"));
    };
}

This is a switch expression. Each case yields a value (after the -> token). The expression switch (j) { ... } yields the value of the matching case. The return statement returns that value.

The value in parentheses in switch (j) is called the selector. In our case, the type of the selector j is the JSONValue interface.

Note the record patterns, such as:

    case JSONNumber(var v) -> "" + v;

If j is a JSONNumber, the variable v is set to the record component. The type of v is the component type, in this case double.

Also note that some cases are enum instances, such as case JSONBoolean.TRUE -> .... These are called constant patterns.

Finally, note that the switch is exhaustive. It covers all possible values for the selector. All switch expressions must be exhaustive. Because no matter what the selector, the expression must have a value.

Ok, not all values are covered. What if the selector j is null? Then a NullPointerExpression is thrown. If j is new JSONString(null), then s is null, also causing an NPE. That is just to be expected. Generally, null is exempted from exhaustiveness checking because it would be too exhausting to check for them, particularly in nested positions.

Why is pattern matching nice? The object-oriented alternative would have been to add a stringify method to all levels of the hierarchy:

• as an abstract or default method in each interface
• as a concrete method in each record or enum

That is easy enough to do—after all, it is a sealed hierarchy. But it has two drawbacks. First, only the owner of the hierarchy can add methods. And the logic of the action, here, stringification, is sprinkled over multiple classes.

By using an external method and pattern matching, the logic is all in one place. And anyone, not just the hierarchy owner, can go forth and pattern match. Without the need of a visitor pattern. This is good.

Future Niceness

Optional could have been declared as a sealed interface whose subtypes are a record Optional.Of and an enum Optional.Empty. Then you could use code like this:

var result = switch(stream.max(comparator)) { // Not actually
   case Optional.Of(x) -> x;
   case Optional.Empty.INSTANCE -> someDefault;
};

Of course, that is not how Optional actually works. But there are plans to make deconstruction work with arbitrary classes. Then you will be able to write something like this:

var result = switch(stream.max(comparator)) { // Maybe soon
   case Optional.of(x) -> x;
   case Optional.empty() -> someDefault;
};

The details are in flux, so I won’t belabor them. Once available, such “member patterns” (or whatever they will end up being called) will make pattern matching practical for a wider set of classes.

Naughty Fallthrough

The classic switch statement, which came to Java via C and C++, has a single raison d’être: to allow the compiler to construct a jump table.

If the labels fall in a compact range, the jump addresses can be in an array. Otherwise, the table is an array of pairs (label, address), sorted by label. Binary search finds the matching case.

As of Java 5, labels can also be strings. Then the jump table contains the hash, and each jump target checks if the string actually matches.

The jump table also explains the fallthrough behavior. After jumping to the code of the case, the program keeps running, until a break causes a jump to the end of the statement. Or, if there is no break, it keeps running with the instructions of the next case. Which is almost always unintended, and a common error. Stay away from it.

Java 14 gave us four forms of switch. The classic statement. A lovely new switch expression. And a switch statement without fallthrough. Also a switch expression with fallthrough—very naughty. That was only added in an effort to make the language more regular.

My advice: If you want a jump table, use the new switch statement without fallthrough. Simply use -> tokens instead of :, and drop the break statements.

switch (c) {
    case '0', '1', '2', '3', '4', '5', '6', '7', '8', '9' -> {
        ndigit[c-'0']++;
    }
    case ' ', '\n', '\t' -> {
        nwhite++;
    }
    default -> {
        nother++;
    }
}

If you want pattern matching, use a switch expression. For sure without fall-through.

Type Patterns

You have seen record patterns (matching a record and extracting its components), as well as the more general member patterns of the future.

Another pattern, called type pattern, checks whether the selector expression has a particular type. It then binds a variable to the type cast:

Object x = ...;
Object doubled = switch (x) {
    case String s -> s + s; // s is a String
    case Number n -> n.doubleValue() * 2; // n is a Number
    default -> List.of(x, x);
}

Of course, this example is completely artificial. When is the last time you had business logic that made type tests like this?

The blogosphere is full of examples like this, in order to illustrate the finer points of switch. Or to gleefully present puzzles that explore cruel conflicts between classic and modern syntax and semantics. Not that I would ever do such a thing.

It is not common to write code that starts with an Object and then narrows down the type. If that is important for you, go ahead and learn more about type patterns. But if you feel the need for the occasional instanceof, just stick with it.

In fact, instanceof has gotten better. A classic code snippet such as

if (x instanceof String) {
    String s = (String) x;
    Do something with s
}

is more easily expressed in modern Java as

if (x instanceof String s) {
    Do something with s
}

Primitive Patterns

The classic switch statement in Java 1.0 permitted selector types int, short, char, and byte. Why not long, float, double, or boolean? They aren’t all that useful with jump tables.

As of Java 25, the selector type can be any type, except for those four types. A proposal, now in its fourth preview, aims to remedy this anomaly. To make the language more regular.

If you just use constant case labels, this is unsurprising.

double x = ...;
String result = switch (x) { // JEP 530 allows selector of type double
    case 3.141592653589793 -> "π";
    case 1.4142135623730951 -> "√2";
    default -> "something else";
};

But there are also primitive patterns:

result = switch (x) {
    case int n when n % 2 == 0 -> "an even integer";
    case float _ -> "a float";
    default -> "something else";
};

The selector is a 64-bit double. The first case tests whether it actually represents a 32-bit int. The second case checks if fits into a 32-bit float without losing any bits of information. To fully understand the latter, you need to be familiar with the internals of the IEEE 754 floating-point standard.

What if you also toss in some wrapper types? Of course, I would never do this. Just kidding, I certainly would in the interest of creating yet another naughty puzzler. But Simon Ritter beat me to it:

int x = ...;
switch (x) {
    case Integer i -> System.out.println("int");
    case byte b -> System.out.println("byte");
}

This should not compile. After all, the second case can never happen, and pattern matching is generally good about flagging such dominance.

But it does compile. In this instance, poor switch is getting overwhelmed. There is so much historical baggage that must be respected. And sometimes the results are counterintuitive.

Do not mix primitive patterns and type patterns in the same switch. They do completely different things. A primitive pattern checks whether a value can be converted to a different type. A type pattern checks whether a value belongs to a different type.

The conversion tests can be useful, but in many practical situations, they work better with instanceof:

int x = ...;
if (x instanceof byte b) {
    out.write(b);
} else { // x is not between -128 and 127
    ...
}

Ok, maybe it’s not that useful. Normally you have bytes between 0 and 255. But that’s another story.

Project Valhalla promises to let us define our own types that act like primitive types, such as long double, short float, unsigned byte. It is not yet clear how pattern matching will work with those types, but I would not be surprised if it was complex and a fertile ground for nasty puzzlers.

Right now, there is a lot of noise about primitive patterns, because it is a new feature. But it is unlikely to impact many programmers. Except as pitfalls. Consider this:

JSONObject o = ...;
var result = switch (o) {
   case JSONNumber(int x) -> x;
   case JSONNull.INSTANCE -> 0;
   default -> throw new IllegalArgumentException();
};

Did the programmer really mean case JSONNumber(int x)? It is an easy mistake to accidentally write int instead of double. Before primitive patterns, the compiler rejected this. Now it has an exciting new meaning: Is o an instance of JSONNumber whose value component is actually an integer? This can be useful, of course, if intended. But what if it isn’t?

Tip: Get into the habit of always using var with record patterns. Then you don’t run into this issue.

Constant Patterns

In our sealed JSON hierarchy, we had a mixture of record patterns and enum constant patterns:

case JSONNumber(var v) -> "" + v;
case JSONBoolean.TRUE -> "true"; // a constant pattern

And that’s fine.

A classic jump table switch only has constant patterns. That’s fine to.

For now, constant patterns have an unfortunate limitation: they don’t nest.

record Point(int x, int y) {}
Point p = ...;
var result = switch (p) {
    case Point(0, _) -> "on x-axis"; // ERROR, can't nest constant pattern
    ...
}

You have to write:

var result = switch (p) {
    case Point(x, _) when x == 0 -> "on x-axis";
    ...
}

This limitation may get fixed at some point in the future.

Even with top-level constant patterns, the rules can get pretty arcane. For example, what is wrong with this?

Object x = ...;
String result = switch (x) {
   case "" -> "empty";
   case 0 -> "zero";
   case JSONNull.INSTANCE -> "null";
   default -> "something else";
};

You can only use string cases when the selector type is String, and integer cases when the selector type is int or Integer. Or short or char or byte. But not long, double, or float. Here the selector type is Object, so they are not allowed. Yet, with an Object selector, enum constants are ok.

You are unlikely to run into real-life switch expressions with Object or Integer selectors, so this too is more of an issue for puzzlers than real-life scenarios.

Conclusion

There is a lot going on with modern switch, and some usages are nicer than others.

The sweet spot is the “sealed hierarchies of records and enums” use case. For bragging rights, call it “algebraic data types”.

In the future, that convenience will be extended to other classes such as Optional.

For other type tests, prefer the modern form of instanceof over a switch with type patterns.

Also, if you want to convert between primitive types, try the new instanceof form first.

If you use jump tables, that’s totally fine. But refactor without fallthrough.

Blogs and puzzler presentations will delight in exploring the interactions between classic and “enhanced” switches, which can get arcane and complex. (Nobody could have predicted that.)

Don’t let that scare you away from using pattern matching. It is a truly useful feature, and it is well worth organizing appropriate parts of your code with pattern matching in mind.

The post Nice and Naughty Cases of Pattern Matching appeared first on JVM Advent.

Using Java’s Foreign Function & Memory (FFM) API, we’ll call the LLVM C API, generate a “Hello, World!” program, and even JIT-compile it to native code – all from Java.

The task is simple: create a program that simply prints “Hello, World!”. But we must do this from Java via LLVM.

What is LLVM?

The LLVM Project, a collection of modular compiler and toolchain technologies, began as a research project over 20 years ago at the University of Illinois. It has grown significantly, underpinning many compilers and tools like clang.

The core libraries provide a source & target independent optimizer along with code generation for a multitude of target machines. They are built around the LLVM IR, an intermediate representation, which we’ll generate & execute from Java.

Installing LLVM

To use the LLVM C API from Java, we’ll need LLVM’s shared libraries and headers installed locally. There is an automatic installation script available to easily install LLVM on Ubuntu/Debian systems, for example to install LLVM 20:

$ wget https://apt.llvm.org/llvm.sh
$ chmod +x llvm.sh
$ ./llvm.sh 20

Once we have LLVM installed we can use the LLVM tooling to execute textual-form LLVM IR and we’ll also be able to use the LLVM C API in Java via the FFM API.

LLVM IR

LLVM IR is a strongly-typed, SSA-based intermediate language. It abstracts away most machine-specific details, making it easier to represent high-level constructs in a compiler-friendly format. There are three equivalent representations of the IR: an in-memory format, a bitcode format for serialisation and a human readable assembly language representation.

The textual form of the LLVM IR for our “Hello, World!” looks like this:

@str = private constant [14 x i8] c"Hello, World!\00"

declare i32 @puts(ptr)

define i32 @main() {
  call i32 @puts(ptr @str)
  ret i32 0
}

Eventually, we’ll generate this via Java but, for now, if you save this in a file called helloworld.ll you can try executing it with the LLVM interpreter, lli:

$ lli helloworld.ll
Hello, World!

There are a few types of entities used in the helloworld.ll example:

• A global variable containing the string “Hello World!”
• A declaration of the external libc puts function
• A definition of the main function
• Instructions to call puts and return an integer exit code

You can dive deeper into the LLVM “Hello, World!” example here if you like before continuing to the next section, where we’ll start using the Java FFM API.

What is the Java FFM API?

The Foreign Function and Memory (FFM) API enables Java programs to interoperate with code and data outside the Java runtime. The API is a replacement for the older JNI API that enables Java programs to call native libraries in a safer way. The API can be used to call foreign functions and safely access foreign memory that is not managed by the JVM.

A companion to the FFM API is a tool named jextract that can automatically generate Java bindings from a C header file. jextract parses C header files and automatically generates the Java source code with method handles and type-safe FFM bindings.

We’ll use the jextract tool to generate bindings for the LLVM C API and those bindings will allow us to call the LLVM API from Java.

Getting started

First, let’s create a simple project to start. We’ll use maven to build our project but you can use another build tool if you like, it’s not important:

$ mvn archetype:generate -DgroupId=com.example -DartifactId=jvm-llvm-helloworld -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Once you have a project skeleton, update the pom.xml file to set the Java version >= 22:

 <properties>
    <maven.compiler.source>25</maven.compiler.source>
    <maven.compiler.target>25</maven.compiler.target>
 </properties>

Then build and run the program to check everything is OK:

$ mvn clean install
$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App
Hello World!

The maven generated sample already printed “Hello, World!” but that’s too easy! We’ll remove that and generate it via LLVM in the following sections.

Let’s now create the LLVM bindings using jextract so that we can use the LLVM API.

Creating LLVM bindings

We’ll use jextract to generate bindings from the LLVM C API header files. Make sure LLVM is available on your system (see Installing LLVM above) and you’ll also need to download jextract.

The following jextract command (on Linux) will create Java bindings for the specified LLVM C headers, placing the generated code into the com.example.llvm package within the src/main/java directory, with the main header class named LLVM.

$ jextract -l LLVM-20 -I /usr/include/llvm-c-20 \
     -I /usr/include/llvm-20 \
     -t com.example.llvm \
     --output src/main/java \
     --header-class-name LLVM \
     /usr/include/llvm-c-20/llvm-c/Core.h \
     /usr/include/llvm-c-20/llvm-c/Support.h \
     /usr/include/llvm-c-20/llvm-c/ExecutionEngine.h \
     /usr/include/llvm-c-20/llvm-c/Target.h \
     /usr/include/llvm-c-20/llvm-c/TargetMachine.h

To test the generated bindings, let’s print the LLVM version using the static method generated for LLVM version string constant: edit the sample’s App.java file to print the version using the following:

package com.example;

import static com.example.llvm.LLVM.LLVM_VERSION_STRING;

/**
 * LLVM Hello world!
 *
 */
public class App 
{
  public static void main(String[] args)
  {
    var version = LLVM_VERSION_STRING();
    System.out.println("LLVM version: " + version.getString(0));
  }
}

If you run this, you’ll see the LLVM version printed:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar --enable-native-access=ALL-UNNAMED com.example.App
LLVM version: 20.0.0

Note the use of --enable-native-access=ALL-UNNAMED to prevent warnings about native code access; I’ll omit this for brevity in later commands.

Memory Segments

The LLVM_VERSION_STRING method returns a MemorySegment rather than a Java String. In the FFM API, a MemorySegment represents a contiguous region of memory—either on or off the Java heap—enabling safe, structured access to native memory.

Let’s take a look at the implementation in the generated source file:

   public static MemorySegment LLVM_VERSION_STRING() {
    class Holder {
      static final MemorySegment LLVM_VERSION_STRING
         = LLVM.LIBRARY_ARENA.allocateFrom("20.0.0");
    }
    return Holder.LLVM_VERSION_STRING;
  }

This method allocates memory containing the version string that contains the version number. The allocated MemorySegment is returned from the method and to get the String back into Java-land we need to call getString(0) on the memory segment which reads a null-terminated string at the given offset (0), using the UTF-8 charset.

Memory segments are managed through arenas (such as the LLVM.LIBRARY_ARENA in the code above), which bridge Java’s managed heap and foreign memory spaces by applying familiar resource management patterns like try-with-resources.

Since we’ll need to allocate native memory, let’s declare an Arena:

 public static void main(String[] args)
 {
    try (Arena arena = Arena.ofConfined()) {
       // TODO
    }
 }

Creating an LLVM module

As a reminder, we need to recreate the following LLVM IR via the LLVM C API:

declare i32 @puts(ptr)

@str = constant [14 x i8] c"Hello, World!\00"

define i32 @main() {
  call i32 @puts(ptr @str)
  ret i32 0
}

Let’s start by creating an LLVM module – the container for all functions and globals – and print it so that we can run it through the LLVM interpreter:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // TODO: Fill in the module
            
  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeModule(module);
  }
}

If we execute this now, we’ll see an empty IR module:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App
; ModuleID = 'hello'
source_filename = "hello"

If you pass this output through the LLVM interpreter, you’ll see that it tries to execute the module but cannot find the entry point main function:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App | lli
Symbols not found: [ main ]

We now have an LLVM module, but it has no executable code – the interpreter rightly complains that main is missing; so let’s add the main function.

Adding a main function

The entry point to our program is the function named main which takes no parameters and returns an integer exit code, where a non-negative integer denotes success. We can add a function to the module using the LLVMAddFunction function, along with the LLVMFunctionType and LLVMInt32Type functions to create the function type. 

Notice that all of these functions return a MemorySegment and all 3 LLVMAddFunction parameters are MemorySegments.

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

    // TODO: Add the code

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeModule(module);
  }
}

If you execute this now you’ll see a declaration of the main function but it has no body so the LLVM interpreter will produce the same error:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App
; ModuleID = 'hello'
source_filename = "hello"

declare i32 @main()

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App|lli
Symbols not found: [ main ]

Next we’ll add some instructions to the body of the function.

Adding an entry basic block

In order to add code to a function we need to add at least 1 basic block – the entry block. A basic block is a sequence of instructions within a function that executes straight through from start to finish, with no branches in the middle. These blocks form the nodes of the Control-Flow Graph (CFG), and they connect to each other based on how control flows between them.

Basic blocks can be added to a function with the LLVMAppendBasicBlock function:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 
	  // TODO: Add the instructions

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeModule(module);
  }
}

If you run the program through lli now, you’ll see a different error:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App | lli
lli: <stdin>:6:1: error: expected instruction opcode
}

That makes sense, we don’t yet have any instructions in our function!

Building instructions

To add instructions, we first create an instruction builder using the LLVMCreateBuilder function. This gives us an LLVMBuilder that we can use to insert new instructions into a basic block.

We’ll also use the LLVMPositionBuilderAtEnd function to position the builder at the end of the entry block and LLVMBuildRet to build a return instruction:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

    // TODO: Call puts “Hello, World!”

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

If you run the program and pass the output through lli now, you’ll see nothing happen:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App | lli

Great news – the errors are gone! Checking the return code confirms the program exited successfully, returning 0.

$ echo $?
0

Try changing the 0 to some other number to confirm that the value is indeed coming from the exit code returned by the LLVM IR program!

Global variables

A global variable, defined at the top-level in LLVM IR, defines a region of memory with a fixed address that is allocated when the program is loaded, rather than dynamically at runtime. Globals can be declared as constant if their values will never change.

We’ll add the string “Hello, World!” to our LLVM program as a global constant.

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // TODO: Call puts “Hello, World!”

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

We don’t use the hello_str yet so running lli would produce the same as before, but you can see the string is now declared in the LLVM IR (prefixed with @ because it is a global, like the main function):

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App 
; ModuleID = 'hello'
source_filename = "hello"

@hello_str = private unnamed_addr constant [14 x i8] c"Hello, World!\00", align 1

define i32 @main() {
entry:
  ret i32 0
}

Let’s add the final instruction next – a call to puts to print the string.

Calling functions

Before we can call the libc puts function we must declare it in the module by first building the function type and then calling LLVMAddFunction to add it to the module:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // TODO: Call puts “Hello, World!”

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

Now that we’ve declared the function we can call it with the @hello_str global as a parameter using the LLVMBuildCall2 function:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // Create puts function call
    var callArgs = arena.allocate(ADDRESS, 1);
    callArgs.set(ADDRESS, 0, helloStr);
    LLVMBuildCall2(builder, putsType, putsFunc, callArgs, 1, arena.allocateFrom("puts"));

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

  	var llvmIrCharPtr = LLVMPrintModuleToString(module);

    try {
      System.out.println(llvmIrCharPtr.getString(0));
    } catch (Exception e) {
      System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    }

	   // Clean up LLVM resources
     LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

Running the program’s output through lli will finally display the expected result: “Hello, World!”:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App | lli
Hello, World!

Congratulations, you’ve successfully used the Java FFM API to call the LLVM C API to build an LLVM module that contains code to print “Hello, World!”.

Just-in-time (JIT) Compilation

So far, we’ve been printing LLVM IR and letting lli execute it. But LLVM also exposes a JIT compiler API, allowing us to generate and execute machine code in-memory. Let’s see how to JIT our “Hello, World!” directly from Java.

LLVM IR is target independent but once we start compiling to native code we must know which machine we are targeting. We’ll target x86 Linux in the following code; if you’re using ARM, Mac or Windows you’ll need to adjust the code for your machine.

The first step is to initialise and create an LLVM JIT compiler for the target machine:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // Create puts function call
    var callArgs = arena.allocate(ADDRESS, 1);
    callArgs.set(ADDRESS, 0, helloStr);
    LLVMBuildCall2(builder, putsType, putsFunc, callArgs, 1, arena.allocateFrom("puts"));

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

    // Initialize LLVM JIT + x86 Target
    LLVMLinkInMCJIT();
    LLVMInitializeX86Target();
    LLVMInitializeX86TargetInfo();
    LLVMInitializeX86TargetMC();
    LLVMInitializeX86AsmPrinter();
    LLVMInitializeX86AsmParser();

    // Create JIT execution engine
    var jitCompiler = arena.allocate(ADDRESS);
    var jitErrorMsgPtrPtr = arena.allocate(ADDRESS);
    LLVMCreateJITCompilerForModule(jitCompiler, module, /* optimization level = */ 2, jitErrorMsgPtrPtr);

    // Disable the IR printing now
  	// var llvmIrCharPtr = LLVMPrintModuleToString(module);
    //
    // try {
    //  System.out.println(llvmIrCharPtr.getString(0));
    // } catch (Exception e) {
    //   System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    // }

	   // Clean up LLVM resources
     // LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

LLVMCreateJITCompilerForModule sets up a JIT execution engine to compile an LLVM module to native machine code. LLVMCreateJITCompilerForModule will return a 1 upon failure and then we can check the error message string for more information but to simplify things we’ll ignore error handling for now. 

Requesting the address of the main function triggers its compilation – LLVM generates the machine code only when it’s first needed, hence the name Just-In-Time compilation. We can retrieve a pointer to the compiled function using LLVMGetPointerToGlobal:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // Create puts function call
    var callArgs = arena.allocate(ADDRESS, 1);
    callArgs.set(ADDRESS, 0, helloStr);
    LLVMBuildCall2(builder, putsType, putsFunc, callArgs, 1, arena.allocateFrom("puts"));

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

    // Initialize LLVM JIT + x86 Target
    LLVMLinkInMCJIT();
    LLVMInitializeX86Target();
    LLVMInitializeX86TargetInfo();
    LLVMInitializeX86TargetMC();
    LLVMInitializeX86AsmPrinter();
    LLVMInitializeX86AsmParser();

    // Create JIT execution engine
    var jitCompiler = arena.allocate(ADDRESS);
    var jitErrorMsgPtrPtr = arena.allocate(ADDRESS);
    LLVMCreateJITCompilerForModule(jitCompiler, module, /* optimization level = */ 2, jitErrorMsgPtrPtr);

    var executionEngine = jitCompiler.get(ADDRESS, 0);
    var addressOfMainFunc = LLVMGetPointerToGlobal(executionEngine, mainFunc);

    // Disable the IR printing now
  	// var llvmIrCharPtr = LLVMPrintModuleToString(module);
    //
    // try {
    //  System.out.println(llvmIrCharPtr.getString(0));
    // } catch (Exception e) {
    //   System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    // }

	   // Clean up LLVM resources
     // LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

Now that we’ve compiled the function, we need a way to invoke it from Java. To do this, we use the foreign linker to create a MethodHandle for the JIT-compiled main function. This handle acts as a callable reference to the native code:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // Create puts function call
    var callArgs = arena.allocate(ADDRESS, 1);
    callArgs.set(ADDRESS, 0, helloStr);
    LLVMBuildCall2(builder, putsType, putsFunc, callArgs, 1, arena.allocateFrom("puts"));

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

    // Initialize LLVM JIT + x86 Target
    LLVMLinkInMCJIT();
    LLVMInitializeX86Target();
    LLVMInitializeX86TargetInfo();
    LLVMInitializeX86TargetMC();
    LLVMInitializeX86AsmPrinter();
    LLVMInitializeX86AsmParser();

    // Create JIT execution engine
    var jitCompiler = arena.allocate(ADDRESS);
    var jitErrorMsgPtrPtr = arena.allocate(ADDRESS);
    LLVMCreateJITCompilerForModule(jitCompiler, module, /* optimization level = */ 2, jitErrorMsgPtrPtr);

    var executionEngine = jitCompiler.get(ADDRESS, 0);
    var addressOfMainFunc = LLVMGetPointerToGlobal(executionEngine, mainFunc);

    // Create method handle to the int main() function that
    // we just created and compiled.
    var functionHandle = Linker.nativeLinker().downcallHandle(
        addressOfMainFunc,
        FunctionDescriptor.of(/* returnType = */ JAVA_INT)
    );

    // Disable the IR printing now
  	// var llvmIrCharPtr = LLVMPrintModuleToString(module);
    //
    // try {
    //  System.out.println(llvmIrCharPtr.getString(0));
    // } catch (Exception e) {
    //   System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    // }

	   // Clean up LLVM resources
     // LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

The downcallHandle method tells Java how to interpret the native function’s signature – in this case, a function that takes no arguments and returns an int.

Now we can invoke the compiled native function directly from Java, just like a regular method call:

public static void main(String[] args)
{
  try (Arena arena = Arena.ofConfined()) {
    var module = LLVMModuleCreateWithName(arena.allocateFrom("hello"));
          
    // Create main function signature: int main()
    var int32Type = LLVMInt32Type();
    var mainType = LLVMFunctionType(int32Type, NULL, 0, 0);
    var mainName = arena.allocateFrom("main");
    var mainFunc = LLVMAddFunction(module, mainName, mainType);

	  var entry = LLVMAppendBasicBlock(mainFunc, arena.allocateFrom("entry"));
 	  var builder = LLVMCreateBuilder();
    LLVMPositionBuilderAtEnd(builder, entry);

	  // Create a global string constant containing "Hello, World!"
    var helloStr = 
           LLVMBuildGlobalStringPtr(builder,
                arena.allocateFrom("Hello, World!"),
                arena.allocateFrom("hello_str"));

    // Create puts function type: int puts(char*)
    var putsParamTypes = arena.allocate(ADDRESS, 1);
    var charPtrType = LLVMPointerType(LLVMInt8Type(), 0);
    putsParamTypes.set(ADDRESS, 0, charPtrType);
    var putsType = LLVMFunctionType(int32Type, putsParamTypes, 1, 0);
    // Add puts function to the module
    var putsFunc = LLVMAddFunction(module, arena.allocateFrom("puts"), putsType);

    // Create puts function call
    var callArgs = arena.allocate(ADDRESS, 1);
    callArgs.set(ADDRESS, 0, helloStr);
    LLVMBuildCall2(builder, putsType, putsFunc, callArgs, 1, arena.allocateFrom("puts"));

	  // Return 0
    LLVMBuildRet(builder, LLVMConstInt(int32Type, 0, 0));

    // Initialize LLVM JIT + x86 Target
    LLVMLinkInMCJIT();
    LLVMInitializeX86Target();
    LLVMInitializeX86TargetInfo();
    LLVMInitializeX86TargetMC();
    LLVMInitializeX86AsmPrinter();
    LLVMInitializeX86AsmParser();

    // Create JIT execution engine
    var jitCompiler = arena.allocate(ADDRESS);
    var jitErrorMsgPtrPtr = arena.allocate(ADDRESS);
    LLVMCreateJITCompilerForModule(jitCompiler, module, /* optimization level = */ 2, jitErrorMsgPtrPtr);

    var executionEngine = jitCompiler.get(ADDRESS, 0);
    var addressOfMainFunc = LLVMGetPointerToGlobal(executionEngine, mainFunc);

    // Create method handle to the int main() function that
    // we just created and compiled.
    var functionHandle = Linker.nativeLinker().downcallHandle(
        addressOfMainFunc,
        FunctionDescriptor.of(/* returnType = */ JAVA_INT)
    );

    // Execute the main function via the method handle.
    try {
      int result = (int) functionHandle.invoke();
      System.out.println("main() returned: " + result);
    } catch (Throwable e) {
      System.err.println("Error calling JIT function: " + e.getMessage());
    }

    // Disable the IR printing now
  	// var llvmIrCharPtr = LLVMPrintModuleToString(module);
    //
    // try {
    //  System.out.println(llvmIrCharPtr.getString(0));
    // } catch (Exception e) {
    //   System.err.println("Failed to write LLVM IR: failed to get error message: " + e.getMessage());
    // }

	   // Clean up LLVM resources
     // LLVMDisposeMessage(llvmIrCharPtr);
     LLVMDisposeBuilder(builder);
     LLVMDisposeModule(module);
  }
}

When functionHandle.invoke() runs, Java crosses into the native world and calls the machine code that was just compiled by the LLVM JIT compiler.

And that’s it, you can now run the Java application without the LLVM interpreter and see the resulting “Hello, World!”:

$ java -cp target/jvm-llvm-helloworld-1.0-SNAPSHOT.jar com.example.App 
Hello, World!

Congratulations, you’ve now JIT-compiled Hello World, with the help of Java’s FFM API calling LLVM’s C API.

Next steps

In this Java advent we built and executed native machine code from pure Java and a little help from LLVM – no JNI, no C glue, just memory segments, method handles, and a modern FFI. By the end, we had just a simple program that prints “Hello, World!” but it shows the potential of the Java FFM API and the things you can do when Java and native code work together.

Now see what else you can do, for example, try generating other instructions: print more text, do simple calculations, or even build tiny programs entirely in LLVM from Java.

The full code for this post is available on GitHub over here.

The post Java Hello World, LLVM Edition appeared first on JVM Advent.

Dependencies, transitivity, and version resolution

Before diving into the specifics of each stack, let’s describe the domain and the problems that come with it.

When developing any project above Hello World level, chances are you’ll face problems that others have faced before. If the problem is widespread, the probability is high that somebody was kind and civic-minded enough to have packaged the code that solves it, for others to re-use. Now you can use the package and focus on solving your core problem. It’s how industry builds most projects today, even if it brings other problems: you sit on the shoulders of giants.

Languages come with build tools that can add such packages to your project. Most of them refer to packages you add to your project as dependencies. In turn, projects’ dependencies can have their own dependencies: the latter are called transitive dependencies.

In the above diagram, C and D are transitive dependencies.

Transitive dependencies have issues on their own. The biggest one is when a transitive dependency is required from different paths, but in different versions. In the diagram below, A and B both depend on C, but on different versions of it.

Which version of C should the build tool include in your project? Java and Rust have different answers. Let’s describe them in turn.

Java transitive dependency version resolution

Reminder: Java code compiles to bytecode, which is then interpreted at runtime (and sometimes compiled to native code, but this is outside of our current problem space). I’ll first describe runtime dependency resolution and build time dependency resolution.

At runtime, the JVM offers the concept of a classpath. When having to load a class, the runtime searches through the configured classpath in order. Imagine the following class:

public static Main {
    public static void main(String[] args) {
        Class.forName("ch.frankel.Dep");
    }
}

Let’s compile it and execute it:

java -cp ./foo.jar:./bar.jar Main

The above will first look in the foo.jar for the ch.frankel.Dep class. If found, it stops there and loads the class, regardless of whether it might also be present in the bar.jar; if not, it looks further in the bar.jar class. If still not found, it fails with a ClassNotFoundException.

Java’s runtime dependency resolution mechanism is ordered and has a per class granularity. It applies whether you run a Java class and define the classpath on the command line as above, or whether you run a JAR that defines the classpath in its manifest.

Let’s change the above code to the following:

public static Main {
    public static void main(String[] args) {
        var dep = new ch.frankel.Dep();
    }
}

Because the new code references Dep directly, new code requires class resolution at compile-time. Classpath resolution works in the same way:

javac -cp ./foo.jar:./bar.jar Main

The compiler looks for Dep in foo.jar, then in bar.jar if not found. The above is what you learn at the beginning of your Java learning journey.

Afterwards, your unit of work is the Java Archive, known as the JAR, instead of the class. A JAR is a glorified ZIP archive, with an internal manifest that specifies its version.

Now, imagine that you’re a user of foo.jar. Developers of foo.jar set a specific classpath when compiling, possibly including other JARs. You’ll need this information to run your own command. How does a library developer pass this knowledge to downstream users?

The community came up with a few ideas to answer this question: The first response that stuck was Maven. Maven has the concept of POM, where you set your project’s metadata, as well as dependencies. Maven can easily resolve transitive dependencies because they also publish their POM, with their own dependencies. Hence, Maven can trace each dependency’s dependencies down to the leaf dependencies.

Now back to the problem statement: how does Maven resolve version conflicts? Which dependency version will Maven resolve for C, 1.0 or 2.0?

The documentation is clear: the nearest.

In the above diagram, the path to v1 has a distance of two, one to B, then one to C; meanwhile, the path to v2 has a distance of three, one to A, then one to D, then finally one to C. Thus, the shortest path points to v1.

However, in the initial diagram, both C versions are at the same distance from the root artifact. The documentation provides no answer. If you’re interested in it, it depends on the order of declaration of A and B in the POM! In summary, Maven returns a single version of a duplicated dependency to include it on the compile classpath.

If A can work with C v2.0 or B with C 1.0, great! If not, you’ll probably need to upgrade your version of A or downgrade your version of B, so that the resolved C version works with both. It’s a manual process that is painful–ask me how I know. Worse, you might find out there’s no C version that works with both A and B. Time to replace A or B.

Rust transitive dependency version resolution

Rust differs from Java in several aspects, but I think the following are the most relevant for the sake of our discussion:

• Rust has the same dependency tree at compile-time and at runtime
• It provides a build tool out of the box, Cargo
• Dependencies are resolved from source

Let’s examine them one by one.

Java compiles to _bytecode, then you run the latter. You need to set the classpath both at compilation time and at runtime. Compiling with a specific classpath and running with a different one can lead to errors. For example, imagine you compile with a class you depend on, but the class is absent at runtime. Or alternatively, it’s present, but in an incompatible version.

Contrary to this modular approach, Rust compiles to a unique native package the crate’s code and every dependency. Moreover, Rust provides its own build too, thus avoiding having to remember the quirks of different tools. I mentioned Maven, but other build tools likely have different rules to resolve the version in the use case above.

Finally, Java resolves dependencies from binaries: JARs. On the contrary, Rust resolves dependencies from sources. At build time, Cargo resolves the entire dependency tree, downloads all required sources, and compiles them in the correct order.

With this in mind, how does Rust resolve the version of the C dependency in the initial problem? The answer may seem strange if you come from a Java background, but Rust includes both. Indeed, in the above diagram, Rust will compile A with C v1.0 and compile B with C v2.0. Problem solved.

Conclusion

JVM languages, and Java in particular, offer both a compile-time classpath and a runtime classpath. It allows modularity and reusability, but opens the door to issues regarding classpath resolution. On the other hand, Rust builds your crate into a single self-contained binary, whether a library or an executable.

To go further:

• Maven – Introduction to the Dependency Mechanism
• Effective Rust – Item 25: Manage your dependency graph

Originally published at A Java Geek on September 14^th, 2025

The post Comparing transitive dependency version resolution in Rust and Java appeared first on JVM Advent.

That’s why Java on ARM is still pretty niche today: hardly any backend developer seriously considered it, because for years… there just wasn’t much to talk about. The journey both ARM processors and the broader JVM ecosystem had to go through to catch up with the needs of the server world has been long and bumpy, full of ugly bugs only discovered in production, hurriedly rolled-back patches, and tons of “invisible” work happening inside virtual machines, JIT compilers, and garbage collectors under the hood.

However, to understand why now Java on ARM is finally starting to make sense – and why it’s worth paying attention to – we first need to look at the evolution that the ARM architecture itself has undergone in recent years.

Although ARM has been with us for a long time and has powered phones, tablets, routers and millions of “smart” gadgets for years, it took two key events to really bring it into the halls of “serious” IT. First – Apple’s move to its own ARM chips in Macs. Overnight, a huge number of developers suddenly had ARM-based primary work machines on their desks, not just toy dev boards.

Second – the arrival of the Neoverse architecture, a family of ARM cores designed from scratch with data centers in mind, not smartphones.

To understand Neoverse, it’s worth starting with Cortex. It’s Cortex cores – in their various A, R and M variants – that sit inside most consumer electronics: from phones and tablets to Raspberry Pi boards. They’re designed under very strict constraints on power, cost and die area, so that SoC vendors can build cheap, energy-efficient chips for battery-powered devices. They’re perfect for the “a few strong cores + GPU + modem on one chip” scenario, but much less suited to servers with hundreds of watts of socket power, massive amounts of memory and full-blown enterprise requirements.

Neoverse is ARM’s answer to the question: “what should a server ARM look like if we stop thinking like phone designers?”. It’s a separate IP line, built from the ground up for infrastructure: high core counts (N1/N2/V2 scaling to hundreds of cores per board), large caches, mesh interconnects, a strong focus on memory bandwidth, virtualization, and RAS (Reliability, Availability, Serviceability) features. In other words – Neoverse is to data centers what Cortex is to smartphones: the basic building block partners like AWS, Ampere and others can use to build their own server CPUs without the compromises typical of mobile cores.

It’s Neoverse that really brought ARM into the cloud. The first generation of AWS Graviton was still built on the well-known Cortex-A72 cores and targeted rather “lighter” workloads. The later generations – Graviton2 on Neoverse N1, Graviton3 on Neoverse V1 and Graviton4 on Neoverse V2 – are fully-fledged, high-performance server processors that in many scenarios beat x86 in terms of price/performance and energy efficiency. In practice, this means that for a large chunk of use cases, “EC2 on ARM” is no longer a curiosity but starts becoming the default option.

The second pillar of this revolution are independent vendors such as Ampere with its Altra family of processors, also built on Neoverse N1. These are the chips that power, among others, ARM instances in Oracle Cloud and many other data centers. SoftBank’s acquisition of Ampere Computing for 6.5 billion dollars is a clear signal that ARM CPUs are no longer a niche experiment but a strategic piece of infrastructure for AI and cloud – especially given that SoftBank also controls ARM itself.

The end result is that a huge portion of new cloud-native workloads now land on ARM by default: microservices in Kubernetes, backend services, event-driven systems, application servers like Spring Boot or Quarkus. Hyperscalers are aggressively promoting ARM instances with attractive pricing, while managing to deliver 20–40% better price/performance and significant energy savings compared to classic x86.

For companies counting every watt and every dollar on their cloud bill, and at the same time building new services on top of containers and JVMs, the natural question is increasingly not “will ARM work?”, but “why are we still not using ARM instances?”.

And now it’s time to ask… why, exactly? Time to look back at the history of Java on ARM.

It’s 2011, Cambridge, UK. Andrew Haley (Red Hat) and Jon Masters (Chief ARM Architect at Red Hat) are sitting in a Thai pub called “The Wrestlers.” At some point Masters drops a bomb: 64-bit ARM (AArch64) is coming, and Red Hat wants to bring Red Hat Enterprise Linux to it. There’s just one tiny problem – there’s no Java on this platform. And without Java there is no enterprise. Haley hears an initial estimate: porting OpenJDK will take two experts about a year of work. The catch? Those experts… don’t exist yet. The team has to learn the ARM architecture on the fly, writing code against simulators before any real silicon ever shows up in a data center.

Long before we could talk about performance, we lived in the age of OpenJDK Zero. The idea was beautiful: write a JVM interpreter in pure C++, without a single line of assembly. That way Java would “run” on anything that had a GCC toolchain – from routers to exotic experimental chips. Reality was brutal: performance was awful. Zero had no JIT (Just-In-Time) compiler, so bytecode was interpreted instruction by instruction. It was like pushing a sports car up a hill – technically it moved, but no one wanted to run that on production.

The real breakthrough came with JEP 237, roughly around Java 9. That’s when engineers from Red Hat and Linaro rolled up their sleeves and aimed for a full-blown port with C1 and C2 compilers that truly “understand” ARM. The biggest challenge was changing the mental model. x86 (CISC) is brute force: complex instructions that do many things at once. ARM (RISC) is precision and simplicity, but with a different geometry of power. C2 had to learn how to use 31 general-purpose registers (x86 only has 16). That’s a massive difference – the JVM can keep most “hot” variables directly in CPU registers instead of constantly spilling them out to memory and loading them back, which dramatically changes the performance profile of the whole application.

However, the performance gain happens in intrinsics in JEP 315, where the JVM replaces selected Java methods with hand-written assembly. That’s where we saw both the biggest wins and the most painful failures. On the success side, you have cryptographic instructions (AES) from ARMv8 – suddenly GCM encryption in TLS sped up by 3.5–5x on Graviton2. Similarly, operations on strings (like String.indexOf) started using NEON vector instructions and stopped being such an obvious hotspot in many services. But there were dead ends, too: the attempt to speed up String.equals using NEON turned out to be worth it only for long strings; for the short ones that dominate typical business systems, the overhead of preparing vector registers simply killed the gain. Result: the code ended up in the “rolled back / Won’t Fix” bucket. Even more spectacular was the bug in the Math.log intrinsic (JDK-8210858): for extreme values, logarithms on ARM stopped being monotonic and produced different results than on Intel. In finance or scientific computing, that’s not a “minor discrepancy” – that’s a red alert. In the end, the intrinsic was removed – correctness beat performance.

Today, when you run Java 21 on AWS Graviton4 or Google Axion, you’re benefiting from more than a decade of those experiments and missteps. Latency-sensitive workloads on ARM64 have improved by several hundred percent compared to baseline Java 8. A modern GC helps a lot (the generational ZGC loves ARM tricks like TBI – Top Byte Ignore), as do well-tuned intrinsics and native support for SVE2 vectors. Then there’s the character of the CPUs themselves: Ampere Altra, Graviton and friends don’t have Hyper-Threading, so one Java thread is one physical core. The garbage collector doesn’t have to fight your business code for ALUs, which translates into much calmer latency tails – on ARM, tail latency is often noticeably flatter and more predictable than on x86.

The history of Java on ARM is, at its core, a story about how hardware is useless without brutally hard work on the software side. We’ve gone from a slow interpreter in pure C++, through logarithms that calculated “a bit differently,” all the way to virtual machines that, on chips like Google Axion, can squeeze out up to +150% performance in AI workloads compared to the latest Intels.

And while I know there are lies, bigger lies and benchmarks…

…if you’re sticking to x86 purely out of habit, you’re probably burning money. But before you rush to move production to ARM, do one thing: update your JDK. Java 8 on ARM works, but it’s like driving a Ferrari with the handbrake on. The real fun starts with Java 17, and ideally 21 – that’s where you finally see why someone spent all those years grinding away at the AArch64 port.

So if you look for the good business reason to migrate a new Java – I found you one . Of course, if you crave the change – not everybody’s do.

The post Beyond x86: Java on ARM in 2025 appeared first on JVM Advent.

However, high test coverage does not guarantee low risk in production. A test may execute a line of code without actually verifying the outcome. A test may instantiate an object but never check all of its significant attributes. Coverage shows what code ran—not whether the tests would catch a fundamental defect.

This raises an important question: how can we measure not only how much code is tested, but how practical those tests really are?

context of the situation

Imagine a team responsible for several microservices. The team is recognized as one of the best, with strong code coverage and consistent promotion of good practices, such as using Sonar to detect problems and creating integration tests to verify interactions between the application and external resources, such as databases.

One day, a new feature was deployed to production—just a slight change in a few classes. Nothing that appeared risky, considering the large number of existing tests. However, a few minutes later, a significant issue surfaced, affecting the entire platform rather than just the application involved.

Seconds after the problem appeared, someone on the team analyzed the code, detected the issue, and fixed it. During the investigation, it became clear that the tests were not reliable, as they neither failed before nor after the changes.

The following is the test that caused the problem:

@Test
public void should_return_a_country() {
    when(countryRepository.findByCode("AR"))
         .thenReturn(getCountryModel());

    CountryDTO response = countryService.getCountryByCode("AR");
}

The test calls a method but overlooks crucial attributes, potentially causing errors in other applications.

What’s mutation testing?

Mutation testing is a technique for evaluating the effectiveness of a test suite by introducing small, controlled changes into the code and verifying whether the tests detect them. Instead of measuring only which lines of code are executed, mutation testing focuses on the quality of assertions and the ability of tests to catch meaningful defects.

CORE CONCEPTS

The heart of this technique implies a set of concepts:

• Mutants:  A mutation is a minor, controlled modification made to source code. Examples include flipping a boolean condition, replacing an arithmetic operator, or removing a method call.
• Goal: Check if the existing tests can detect these changes. If a test fails when a mutant is introduced, it indicates that the test suite is sensitive enough to detect behavioral differences, a sign of strong, practical tests.

After the creation of the mutants and executing all the tests, each mutation could stay in two states:

• Killed: When at least one test fails after a change, it indicates that the test suite has effectively detected a behavioral difference.
• Survived: A mutant survives when all tests pass despite the injected modification. Typically, this happens when an assertion is weak or when test cases are missing.

mUTATION SCORE

Mutation testing provides a percentage indicating how practical the tests are. To calculate this, it’s necessary to use the following formula:

Mutation Testing Score

The way to interpret the percentage is:

• High scores (e.g., 80–95%) often suggest strong test coverage with meaningful assertions.

• Medium scores highlight opportunities to improve tests or simplify logic.

• Low scores (below ~50%) usually indicate insufficient or weak tests that may not protect against regressions.

It’s important to note that a high mutation test score does not mean the application is bug-free.

Types of Mutations

Mutation testing tools create various modifications, known as mutations, that simulate potential defects in the code. While the specific mutation operators can differ based on the programming language or library used, they generally fall into three main categories: Decision mutations, Statement mutations, and Value mutations. Each category focuses on different aspects of the program’s behavior, helping assess how effectively the test suite validates the code’s logic, control flow, and data integrity.

Let’s see a brief explanation about each of them:

• Decision Mutations: Modify the conditions that control program flow. These mutations focus on expressions found in if, switch, while, for, and boolean-returning operations. 
• Statement Mutations: Work by adding, removing, or altering entire statements. They test whether the test suite can detect situations where part of the logic disappears or behaves differently.
• Value Mutations: Value mutations target constants, literals, return values, and field assignments. They simulate defects caused by incorrect data produced or used by the program.

How to IMPLEMENT IT ON AN APPLICATION?

To implement mutation testing in a JVM ecosystem, several libraries are available, such as Pitest, Major, and MuJava. The first option is the best because it is actively maintained, highly performant, integrates seamlessly with Maven, Gradle, JUnit, and TestNG, supports incremental analysis with extensive configuration options, generates clear HTML reports of killed and surviving mutants, and even provides plugins for SonarQube and other tools.

This article uses a source from a GitHub repository; feel free to clone it and use it to learn about mutation testing.

To use this library, you first need to add the dependency to your application. The following block represents how to do it on a Maven project:

<!-- Mutation Test -->
<plugin>
    <groupId>org.pitest</groupId>
    <artifactId>pitest-maven</artifactId>
    <version>${pitest-maven.version}</version>

    <configuration>
        <outputFormats>
            <outputFormat>HTML</outputFormat>
            <outputFormat>XML</outputFormat>
        </outputFormats>
        <targetClasses>
            <param>com.twa.flights.api.catalog.*</param>
        </targetClasses>
        <targetTests>
            <param>com.twa.flights.api.catalog.*</param>
        </targetTests>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.pitest</groupId>
            <artifactId>pitest-junit5-plugin</artifactId>
            <version>${pitest-junit5-plugin.version}</version>
        </dependency>
    </dependencies>
</plugin>

As a recommendation, check the latest version of this library on the official webpage or a repository like this regularly.

Pitest allows users to export execution results in multiple formats, including HTML, CSV, and XML. The relevance of each format depends on the report’s purpose. For example, the HTML format is ideal for those who want a simple view of execution results, including the number of mutations used. In contrast, the XML format helps integrate this information with other tools, such as Sonar, which can display mutation execution results.

On this tool, it’s possible to indicate in the same way that appears on the previous code block, which packages or test classes will be mutated, and it’s possible to indicate the same about which package of the source code will suffer modifications.

Executing mutation testing implies just running a command like the following:

$ mvn clean package org.pitest:pitest-maven:mutationCoverage
[INFO] --- pitest:1.7.6:mutationCoverage (default-cli) @ api-catalog ---
[INFO] Root dir is : /home/asacco/Code/testing-your-test/api-catalog
[INFO] Found plugin : Default csv report plugin
[INFO] Found plugin : Default xml report plugin
[INFO] Found plugin : Default html report plugin
......
[INFO] Found shared classpath plugin : Default mutation engine
[INFO] Found shared classpath plugin : JUnit 5 test framework support
[INFO] Found shared classpath plugin : JUnit plugin
[INFO] Available mutators : EXPERIMENTAL_ARGUMENT_PROPAGATION,FALSE_RETURNS,TRUE_RETURNS,CONDITIONALS_BOUNDARY,CONSTRUCTOR_CALLS,EMPTY_RETURNS,INCREMENTS,INLINE_CONSTS,INVERT_NEGS,MATH,NEGATE_CONDITIONALS,NON_VOID_METHOD_CALLS,NULL_RETURNS,PRIMITIVE_RETURNS,REMOVE_CONDITIONALS_EQUAL_IF,REMOVE_CONDITIONALS_EQUAL_ELSE,REMOVE_CONDITIONALS_ORDER_IF,REMOVE_CONDITIONALS_ORDER_ELSE,RETURN_VALS,VOID_METHOD_CALLS,EXPERIMENTAL_BIG_DECIMAL,EXPERIMENTAL_BIG_INTEGER,EXPERIMENTAL_MEMBER_VARIABLE,EXPERIMENTAL_NAKED_RECEIVER,REMOVE_INCREMENTS,EXPERIMENTAL_RETURN_VALUES_MUTATOR,EXPERIMENTAL_SWITCH,EXPERIMENTAL_BIG_DECIMAL,EXPERIMENTAL_BIG_INTEGER
......
......
================================================================================
- Timings
================================================================================
> pre-scan for mutations : < 1 second
> scan classpath : < 1 second
> coverage and dependency analysis : < 1 second
> build mutation tests : < 1 second
> run mutation analysis : 4 seconds
--------------------------------------------------------------------------------
> Total : 5 seconds
--------------------------------------------------------------------------------
================================================================================
- Statistics
================================================================================
>> Line Coverage: 63/195 (32%)
>> Generated 64 mutations Killed 7 (11%)
>> Mutations with no coverage 54. Test strength 70%
>> Ran 15 tests (0.23 tests per mutation)
Enhanced functionality available at https://www.arcmutate.com/
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.757 s
[INFO] Finished at: 2025-11-27T10:07:37-03:00
[INFO] ------------------------------------------------------------------------

Execution time may vary depending on the size of the source code and the available resources on the machine where these tests are running.

To see the HTML report graphically, open the target folder and look for the pit-reports folder. The report will look like the following image:

Mutation Testing: General Overview

To reduce execution time, you can use historical execution data to detect changes in code and tests. In concrete terms, the command implies adding only one parameter, as shown in the following block.

$ mvn clean package org.pitest:pitest-maven:mutationCoverage -DwithHistory
......
.....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.689 s
[INFO] Finished at: 2025-11-27T10:21:54-03:00
[INFO] ------------------------------------------------------------------------

The execution time passes from 9,7 to 5,6 seconds in a small project with a few classes. The approach is beneficial when the applications have a lot of code and tests.

A critical aspect of mutation testing is the ability to use multiple mutation engines. An engine is responsible for modifying the source code; in some cases, changing all the logic inside a method or a class, rather than just adjusting the method’s parameters or its response. By default, Pitest uses Gregor, which introduces modifications to the different sentences of a technique, but it’s possible to use Descartes, which reduces the modifications. To use it, it’s necessary to introduce some changes, like the following:

<!-- Mutation Test -->
<plugin>
    <groupId>org.pitest</groupId>
    <artifactId>pitest-maven</artifactId>
    <version>${pitest-maven.version}</version>

    <configuration>
       <outputFormats>
          <outputFormat>HTML</outputFormat>
          <outputFormat>XML</outputFormat>
       </outputFormats>
       <targetClasses>
          <param>com.twa.flights.api.catalog.*</param>
       </targetClasses>
       <targetTests>
          <param>com.twa.flights.api.catalog.*</param>
       </targetTests>
       <mutationEngine>descartes</mutationEngine>
    </configuration>
    <dependencies>
       <dependency>
          <groupId>org.pitest</groupId>
          <artifactId>pitest-junit5-plugin</artifactId>
          <version>${pitest-junit5-plugin.version}</version>
       </dependency>
       <dependency>
          <groupId>eu.stamp-project</groupId>
          <artifactId>descartes</artifactId>
          <version>1.3.2</version>
       </dependency>
    </dependencies>
</plugin>

As a recommendation, check the latest version of this library, as new versions are released at regular intervals.

What are THE Challenges and costs?

Introducing mutation testing into an existing application is not free of challenges, as it requires understanding its limitations and trade-offs. With this in mind, it’s crucial to set realistic expectations for this type of testing. Some of the most relevant issues are:

• Execution time: Creating mutations and executing tests takes time because it involves generating source code variations and running tests to validate their effects. In large applications with hundreds of tests or large codebases, this could increase drastically. In some cases, this situation could be a barrier to implementing this type of testing in a CI pipeline.
• Flaky or unstable tests: In some cases, tests pass or fail sporadically due to issues with concurrent access to external resources. These scenarios could affect mutation execution, leading to false positives, so it’s essential to either exclude these tests or find a way to mitigate the problem.

• Resource consumption: In addition to the time required to execute the tests and create the mutation, there are other resource-related issues, such as CPU and memory usage. This can affect not only the pipeline running mutation tests but also other jobs running in the same CI environment. The big challenge here is to reduce resource consumption, limit mutations, or shorten the execution time of each pipeline.
• Complex configuration: Most tools or libraries offer many parameters to achieve the best configuration for each application. The first attempts to use these tools could lead to unrealistic expectations about the performance and results that are achievable. Finding the right balance between performance, accuracy, and execution time often requires several iterations.

None of these issues invalidates the benefits of mutation testing, but it’s essential to develop a plan to mitigate or reduce their impact.

WHICH STRATEGIES EXIST for Adopting IT?

Adopting a new technique or tool involves several considerations, especially in an existing application with many classes and tests. There is no magic formula for implementing mutation testing without pain, but there are different approaches to reduce the problems to a low level. Some of the most relevant strategies are:

• Start small: This approach focuses on familiarizing with the tool and scanning just one package, module, or critical flow to identify potential implementation issues. It’s beneficial when there are too many unit tests on the application.
• Focus on high-risk code first: The critical code or flows are what anyone on a team or company wants to know whether it works or not. Adding mutation testing to a few classes that represent those flows can be implemented with minimal impact. Once everything is in order, we can incrementally update the configuration to scan more packages.
• Limiting the scope: At some point, execution time becomes a critical factor, so a possible approach is to limit the number or types of mutations that can be created. It could be a good starting point: only include the most relevant mutator during execution, and measure the impact before including all the mutations.
• Restrict execution: These tests may take longer to deploy, so a possible approach is to restrict their use locally or in the principal pipeline, which uses them to deploy to some productive environments.

It is possible to use one of these strategies or combine them to achieve better results, but in all cases, the choice depends on the size of the application and the number of unit tests.

WHAT’S NEXT?

There are many resources on unit testing and mutation testing. The following is just a short list of resources:

• Latent Mutants: A large-scale study on the Interplay between mutation testing and software evolution by Jeongju Sohn
• Practical Mutation Testing at Scale: A view from Google
• Mutation Testing in Evolving Systems: Studying the Relevance of Mutants to Code Evolution by Milos Ojdanic
• Does mutation testing improve testing practices? by Goran Petrovic

Other resources could be great for understanding some concepts related to testing in depth:

• Testing Web APIs by Mark Winteringham
• Unit Testing Principles, Practices, and Patterns by Vladimir Khorikov
• Software Testing with Generative AI by Mark Winteringham

Consider this just a small list of available resources. If something is unclear, find another video or resource.

CONCLUSION

Creating tests for an application does not guarantee that nothing will go wrong, and mutation testing is not a silver bullet that can detect every possible issue. However, it provides a valuable and objective way to evaluate how practical existing tests really are.

A practical approach is to adopt it gradually: start with a small number of packages or a limited mutation scope, measure the effect on the build and pipeline, and then expand its use as appropriate.

Used pragmatically, mutation testing can significantly improve test quality and increase confidence in the application’s behavior without overwhelming the development process.

The post Test Your Test appeared first on JVM Advent.

“If the output comes, the job is done.”

I bundled everything into one giant file — controllers, logic, database access.I didn’t understand why Spring insisted on layers or why DI, IoC, and annotations were so important. The project structure looked overwhelming, and everything felt abstract.

Everything changed the day I decided to trace my first Spring Boot request and watch how a simple API call traveled through the system. Suddenly, what looked like scattered pieces turned into a well-designed, meaningful architecture. It didn’t just teach me Spring Boot — it changed the way I think about writing software.

What I Used to Think Backend Development Was

In the beginning, this was my reality:

• All classes dumped into one package
• Endless, congested code inside one file
• No idea what executes, what doesn’t, or why
• Maven structure felt unnecessary
• Layers didn’t make sense
• Annotations were intimidating
• No understanding of why Service existed between Controller and Repository

It was like trying to build a house without knowing what bricks, beams, or foundations were.

The Turning Point: Tracing My First Request

One day, I opened my console logs and started following the journey of an incoming request:

• It first hit the Controller
• Then passed into the Service
• Then reached the Repository
• Finally touched the Database
• And then returned the response through the same layers

That visual flow — even just in the logs — changed everything for me.

I realized:

• DI reduces tight coupling
• IoC manages object lifecycles so you don’t
• Layers exist to protect and organize the system
• Spring Boot is powerful because of its structure, not despite it

Architecture became a living system, not a theory.

Controller → Service → Repository: The Flow That Made Everything Click

Controller — The Entry Point

The controller receives the request, interacts with the service, and returns the appropriate response or view.

@Controller
@RequestMapping("/employees")
public class EmployeeController {

    private EmployeeService employeeService;

    public EmployeeController(EmployeeService theEmployeeService) {
        employeeService = theEmployeeService;
    }

    @GetMapping("/list")
    public String listEmployees(Model theModel) {
        List<Employee> theEmployees = employeeService.findAll();
        theModel.addAttribute("employees", theEmployees);
        return "employees/list-employees";
    }
}

Controllers should be small and focused — no business logic inside them.

Service — The Logic Layer

This is where business decisions happen. It protects the repository from being accessed directly.

public interface EmployeeService {
    List<Employee> findAll();
    Employee findById(int theId);
    void save(Employee theEmployee);
    void deleteById(int theId);
    boolean existsByEmailId(Employee theEmployee);
}

Implementation:

@Service
public class EmployeeServiceImpl implements EmployeeService {

    private EmployeeRepository employeeRepository;

    @Autowired
    public EmployeeServiceImpl(EmployeeRepository theEmployeeRepository) {
        employeeRepository = theEmployeeRepository;
    }

    @Override
    public List<Employee> findAll() {
        return employeeRepository.findAllByOrderByLastNameAsc();
    }
}

The service layer keeps your application clean, secure, and maintainable.

Repository — Where Database Interactions Happen

With Spring Data JPA, repositories become incredibly simple:

public interface EmployeeRepository extends JpaRepository<Employee, Integer> {
    boolean existsByEmail(String email);
    List<Employee> findAllByOrderByLastNameAsc();
}

The framework generates most queries automatically.

Entity — Mapping Java Objects to Database Tables

Entities act as a bridge between the database and your Java application.

@Entity
@Table(name="employee")
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;

    @NotBlank
    private String firstName;

    @NotBlank
    private String lastName;

    @NotBlank
    private String email;

    // constructors, getters, setters
}

Spring (plus Jackson) takes care of converting between JSON Java Database.

When MVC Finally Made Sense

Moving into full MVC with Thymeleaf gave me clarity:

• Controllers handle the request
• Services handle business logic
• Repositories handle persistence
• Templates display the data

The project structure stopped looking like a burden and became something I respected. The flow felt natural and powerful.

A Simple CRUD Example That Made It Real

The moment everything clicked was when I saw this flow in my own CRUD app:

• Client hits GET /employees/list
• Controller asks Service for data
• Service queries the Repository
• Repository returns data from the database
• Controller adds data to Model
• Thymeleaf displays it on the page

Suddenly the architecture wasn’t an academic concept — it was working in front of me.

Here is the GitHub repository of the CRUD app I used in this article:

**https://github.com/MAffanG/employee-crud-api**

What This Taught Me About Coding

Understanding the request flow transformed everything about my approach:

• I no longer chase outputs — I chase clarity
• I think in terms of architecture, not hacks
• Debugging became easier and faster
• My code became cleaner and more intentional
• I finally felt like a backend developer, not someone just trying things until they work

This experience didn’t just teach me Spring Boot — it changed the way I respect software design as a whole.

The post How Understanding Request Flow in Spring Boot Changed the Way I Code appeared first on JVM Advent.

The choice of Quarkus as a modern cloud-native framework in this article is not random: the framework already provides a huge ecosystem of extension and is being active used in more and more modern Java applicaations. And it really brings developer joy with all nice goodies like fast dev mode with hot reload, dev UI, dev services, unified configuration to name a few essential ones.

In this brief article we will discuss how the Quarkus LangChain4j extensions simplifies further use of the library and how we can use it to build an agentic application.

So why a separate extension for LangChain4j ?

There are several primary reasons to have a separate extension:

• the Quarkus architecture makes heavy use of build time optimizations including the extension mechanism so that extensions can be optimized for build time optimizations and native-image builds
• better integration using CDI beans (Quarkus uses a deicated dependency injection mechanism called ArC as a CDI implementation) in the form of a additional @AiService annotation for autodiscovery of AI services
• type-safe configuration for LangChain4j as supported by Quarkus using specific configuration classes for LangChain4j allowing user to define configuration such as:

quarkus.langchain4j.openai.api-key
quarkus.langchain4j.chat-model

• integration with Quarkus dev mode (i.e. for hot reload of configuration, Dev UI extension);
• sensible default observability configuration, including one for OpenTelemetry and tracing of calls to LLMs

All of this sounds really great, not only a simple plugin for Quarkus but a highly optimized and simplified use of the LangChain4j framework !

Now let’s just demonstrate how we can quick start using it with a practical example: a simple agentic healthcare application that given a description of medical conditions gives a prediction on which physician should be visited within a target hospital. The hospital stores an information in form of a table that maps a specific disease to a doctor that most expertise in that disease within the hospital. Let’s call it DocPredict.

DocPredict: THE High-Level Architecture

So straight to the point, let’s define how our simple healthcare assistant looks like from a high level perspective and build it:

Ideally if we want to build a complex frontend we would prefer to implement the DocPredict Web application using a modern favascript framework like React, Vue.js or AngularJS but in our case we will use a server-side rendering engine called Qute provided by Quarkus. Our service will interact with an OpenAI model to make the proper prediction based on a supplied definition and then try to map the respose to a proper doctor based on the existing hospital database. To not overcomplicate matters the database will be simply a CSV file with disease -> doctor pairs.

DocPredict: The code

To quickly bootstrap our initial application we can navigate to https://code.quarkus.io/ and supply proper configuration which is as simple as providing the basic Maven configuration and adding the following extensions:

• REST
• REST Jackson
• SmallRye OpenAPI (for Swagger)
• LangChain4j OpenAI
• Qute Web (for server-side templates)

Then download the generated application, unzip it and import it as a Maven project in your favourite IDE. In addition add the following library (we will use it to parse the CSV file with disease -> doctor records):

<dependency>
<groupId>com.opencsv</groupId>
<artifactId>opencsv</artifactId>
<version>5.7.1</version>
</dependency>

Next generate an OpenAI key from https://platform.openai.com/api-keys if you don’t have one already and add it to the application.properties file of the project as follows:

quarkus.langchain4j.chat-model.provider=openai
quarkus.langchain4j.openai.api-key=<key>

If we have multiple providers on the classpath (i.e. OpenPI and Gemini) we need to specify explicitly in the configuration which provider we want to use. In case you don’t have an API credit with a credit for OpenAI (unless you use a trial account with small initial credit) you can use a the free DeepSeek model via the OpenRouter platform for example: https://openrouter.ai/ Generate an API key there and use it as follows (the DeepSeek API is compatible with OpenAI):

quarkus.langchain4j.openai.api-key=<openrouter_api_key>

quarkus.langchain4j.openai.base-url=https://openrouter.ai/api/v1

quarkus.langchain4j.openai.model=deepseek/deepseek-r1:free

In the src/main/resources folder let’s create a doctors.csv file with the following content:

 

package com.javaadvent.docpredict;

 

public class PredictionRequest {

private String symptoms;

public String getSymptoms() {

return symptoms;

}

public void setSymptoms(String symptoms) {

this.symptoms = symptoms;

}

}

 

Finally let’s make this a bit more convenient by adding a simple UI around it using Quarkus Qute template engine.

Create the following templates under src/main/resources/templates:

index.qute.html

<!DOCTYPE html>

<html>

<head>

<title>DocPredict</title>

</head>

<body>

<h1>Enter your symptoms</h1>

<form id=“symptomsForm“>

<input type=“text“ name=“symptoms“ placeholder=“Your symptoms“ required>

<button type=“submit“>Suggest specialist</button>

</form>

<div id=“prediction“></div>

<script>

const form = document.getElementById(‘symptomsForm’);

const resultDiv = document.getElementById(‘prediction’);

form.addEventListener(‘submit’, async (e) => {

e.preventDefault(); // prevent full page reload

const formData = new FormData(form);

const response = await fetch(‘/index/submit’, {

method: ‘POST’,

body: new URLSearchParams(formData)

});

// insert HTML fragment into page

const html = await response.text();

resultDiv.innerHTML = html;

});

</script>

</body>

</html>

prediction.qute.html
<p>{doctor} !</p>

Add the following endpoint to handle the template rendering:

And there we go once we navigate to http://localhost:8080/indexlocalhost:8080/index:

Summary

As you can see it is quite straight-forward to get started with Quarkus LangChain4j extension and furthermore you can start more complex capabilities in your application like RAG, context memory, tool support etc.

The post Quarkus LangChain4j extension from grounds up appeared first on JVM Advent.

This year feels particularly special for me. I spent most of the past months writing and publishing Applied AI for Enterprise Java Development, a book that tries to make sense of this AI wave from a developer’s point of view. Not the hype, not the hand-waving, but the real work we do when we integrate LLMs into production systems. It’s been a year of experiments, late-night debugging, mistakes, surprises, and quite a few breakthroughs. And now, opening this Advent Calendar, I can’t help but see how far the Java ecosystem has already come.

Java developers didn’t sit back and wait for AI to “happen to them.”

We did what we always do: we tested, we validated, we measured, we built frameworks, we added structure, and we created patterns that teams can actually use in the real world. Today, Quarkus, LangChain4j, and the broader Java ecosystem make it possible to build AI-infused systems without giving up the reliability and discipline we depend on.

And that’s why I’m thrilled to start this calendar with you.

For the next 24 days, you’ll see creative ideas, deep dives, practical guides, experiments, and some truly unexpected topics. And all for them written by people who care about this craft as much as you do.

So grab your favorite hot drink, take a breath, and enjoy the first door of the 2025 Java Advent Calendar.

There’s a lot of good stuff waiting behind the others.

Models as Services. The Simplest Pattern Still Matters

The official LangChain4j tutorials start with the simplest possible shape: a chat model that you call like a remote service. That’s intentional. It reinforces the pattern Java developers already understand: the model is an external dependency with its own behavior, latency, and failure modes.

Here is the Quarkus version of the official chat example (adapted from the “Chat with LangChain4j” and “AI Services” tutorials):

import dev.langchain4j.service.AiService;

@AiService
public interface Assistant {
    String chat(String message);
}

Quarkus wires the model for you through configuration:

# application.properties
quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini

You inject it exactly like you inject any other CDI bean:

@Path("/chat")
public class ChatResource {

    @Inject
    Assistant assistant;

    @GET
    public String chat(@QueryParam("q") String q) {
        return assistant.chat(q);
    }
}

This example looks trivial, but it captures a foundational rule:

the model is not embedded; the model is a service.

And this is where Java already shines: retries, timeouts, circuit breakers, metrics, structured logs. All of those all apply cleanly to LLM calls.

Practical Retrieval-Augmented Generation 

The official LangChain4j RAG tutorial shows the basic pattern:

• 1.Split documents into text segments
• 2.Embed those segments
• 3.Store them in an embedding store
• 4.At query time:
  • embed the question
  • retrieve relevant segments
  • combine into a prompt
  • send to the model

Here is the Quarkus version of that exact flow:

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.model.embedding.EmbeddingModel;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
public class RagService {

    @Inject
    EmbeddingStore<TextSegment> store;

    @Inject
    EmbeddingModel embeddingModel;

    public String buildPrompt(String question) {

        // 1. Embed the question
        Embedding queryEmbedding = embeddingModel.embed(question).content();

        // 2. Retrieve relevant context
        var matches = store.findRelevant(queryEmbedding, 3);

        // 3. Combine retrieved text into a simple prompt
        StringBuilder sb = new StringBuilder();

        for (var match : matches) {
            sb.append(match.embedded().text()).append("\n\n");
        }

        sb.append("Question: ").append(question);
        return sb.toString();
    }

}

And the usage in a resource:

@Path("/help")

public class HelpResource {

    @Inject
    RagService rag;

    @Inject
    Assistant assistant;

    @GET
    public String help(@QueryParam("q") String question) {
        String prompt = rag.buildPrompt(question);
        return assistant.chat(prompt);
    }

}

This pattern is simple retrieval, simple prompt construction, no ceremony.

And importantly: you now have a deterministic pipeline around the model. That pipeline is what you test, observe, and control.

Guardrails Safeguarding Input and Output

LangChain4j provides two clear mechanisms:

• @InputGuardrails
• @OutputGuardrails

Both integrate directly with Quarkus.

Here’s the Quarkus version:

Input Guardrail

import dev.langchain4j.guardrail.InputGuardrail;

public class NoEmptyInputGuardrail implements InputGuardrail {

    @Override
    public void validate(String input) {
        if (input == null || input.isBlank()) {
            throw new IllegalArgumentException("Input must not be empty");
        }
    }
}

Output Guardrail

import dev.langchain4j.guardrail.OutputGuardrail;

public class JsonMustContainSummary implements OutputGuardrail<String> {

    @Override
    public void validate(String output) {
        if (!output.contains("summary")) {
            throw new IllegalStateException("Model output missing 'summary' field");
        }
    }
}

Wiring them into the AI service

@AiService

public interface StructuredAssistant {

    @InputGuardrails(NoEmptyInputGuardrail.class)
    @OutputGuardrails(JsonMustContainSummary.class)
    String answer(String question);

}

And Quarkus adds configuration-driven retries:

quarkus.langchain4j.guardrails.max-retries=2

Guardrails feel like an entirely new concept for many Java developers, but the structure is familiar: It’s validation, just on the other side of the API boundary.

Testing & Evaluation 

If  we think about Testing in general, and merge this with requirements coming in for large language models, we need to think about:

• testing deterministic components
• testing guardrails
• testing model interaction in a black-box fashion
• using curated prompt sets
• evaluating output structure, not exact wording

Here is a Quarkus version :

Testing Guardrails

@QuarkusTest

public class GuardrailTest {

    @Inject
    StructuredAssistant assistant;

    @Test
    void emptyInputShouldBeRejected() {
        assertThrows(IllegalArgumentException.class, () -> {
            assistant.answer(" ");
        });
    }

}

Testing RAG logic (deterministic)

@QuarkusTest

public class RagTest {

    @Inject
    RagService rag;

    @Inject
    EmbeddingStore<TextSegment> store;

    @Test
    void retrievalShouldReturnRelevantText() {
        store.add(TextSegment.from("Java 21 is the current LTS release."),
                  EmbeddingModel.miniLm().embed("Java").content());

        String prompt = rag.buildPrompt("What is the current Java LTS?");
        assertTrue(prompt.contains("Java 21"));
    }

}

Opaque-box testing of the assistant

@QuarkusTest

public class AssistantIT {

    @Inject
    Assistant assistant;

    @Test
    void modelShouldProduceNonEmptyAnswer() {

        String response = assistant.chat("Hello!");
        assertFalse(response.isBlank());
    }

}

Don’t test phrasing; test structure and expectations!

This keeps tests stable while still verifying quality and behavior.

A Festive Opening for the 24 Days Ahead

That brings us to why this article exists: to open another year of the Java Advent Calendar.

December has a special rhythm in the Java community. The year is winding down, code freezes are happening, and teams start reflecting on what actually mattered. And into that atmosphere comes a wave of articles. 24 voices, 24 perspectives, 24 stories from across our ecosystem.

• Some will dive deep into AI.
• Some will explore the core of the JVM.
• Some will share practical lessons from the year’s real-world battles.
• Some will remind us why Java continues to thrive, evolve, and surprise us.

This opening post is just the prologue.

Over the next three weeks, you’ll see what people across the community are experimenting with, breaking, fixing, and learning. You’ll see new tools, new techniques, old wisdom rediscovered, and perhaps a few things you’ll want to try during the quieter days between the holidays.

Whatever this season means to you, whether it’s festive, reflective, or simply a much-needed breather, I hope these articles offer inspiration and maybe a spark for your next project. Java has always been about community, and the Advent Calendar remains one of the warmest reminders of that.

So let’s open the first door together.

Twenty-three more to go.

Let’s enjoy the season, and write some good Java along the way.

The post Lighting the Way: Java, AI, and a Season of New Ideas appeared first on JVM Advent.