How It Works

Table of Contents

Why Not Just Ask an AI Chat to Migrate?
Kinds of Findings
What the Tool Runs
The AI Agent Loop
Changes Made Without AI
Reports
Git Checkpoints
Interactive Mode
Data Handling

Need help?

Schedule a consultation with an Azul performance expert.

Why Not Just Ask an AI Chat to Migrate?

Pasting source code into a general-purpose AI chat is a single request and response. The model infers what changed from its training data, which can lead to inconsistent results, removed APIs that were not removed, and missed deprecations. It does not know about Payara-specific APIs, and it stops when it runs out of context rather than when the work is done.

The Azul Payara AI Upgrade Assistant works differently:

Grounded in static analysis. The advisors know the API changes across Jakarta EE versions. Before the AI agent changes any code, the advisors have produced an exact inventory of findings. The agent does not guess what needs to change.
Iterative and verified. The tool compiles your project after the edits, reads compiler errors, and corrects them.
Repeatable. The stopping condition is objective: the advisors find nothing left to fix and the project compiles, or the round limit is reached.
Payara-aware. The tool maps to standard Jakarta EE APIs and Payara APIs.

Kinds of Findings

Every finding is handled in one of four ways:

Kind What happens

Kind	What happens
`RECIPE`	Fixed automatically and exactly. For example, renaming `javax.servlet` imports to `jakarta.servlet`. No AI is used, so it costs no tokens and cannot hallucinate.
`GUIDED_RECIPE`	Needs one judgement call, after which a recipe makes the edit across the project. The question is put to the AI agent, or to you when you use the tool from Claude Code.
`AI`	Needs judgement. Fixed by the AI agent, or by you following the advice in the report.
`MANUAL`	Only a human can do it, such as a server setting or an `asadmin` command. The report gives the steps with your project’s real values filled in.

RECIPE

Fixed automatically and exactly. For example, renaming javax.servlet imports to jakarta.servlet. No AI is used, so it costs no tokens and cannot hallucinate.

GUIDED_RECIPE

Needs one judgement call, after which a recipe makes the edit across the project. The question is put to the AI agent, or to you when you use the tool from Claude Code.

AI

Needs judgement. Fixed by the AI agent, or by you following the advice in the report.

MANUAL

Only a human can do it, such as a server setting or an asadmin command. The report gives the steps with your project’s real values filled in.

Each finding names the file and line, describes what was found, and gives the advisor’s recommended change as Fix.

What the Tool Runs

You choose how far the tool goes:

Stage	Description
Detection only	Reports which technologies your project uses and which advisors apply. Changes nothing.
Advisors and recipes	The default. Scans the project, builds a plan and applies the automatic fixes. No AI is used.
AI agent	Does the above, then runs an agentic loop on the findings that the recipes cannot fix.

Stage

Description

Detection only

Reports which technologies your project uses and which advisors apply. Changes nothing.

Advisors and recipes

The default. Scans the project, builds a plan and applies the automatic fixes. No AI is used.

AI agent

Does the above, then runs an agentic loop on the findings that the recipes cannot fix.

Use migration.apply=false for a dry run that only reports and never edits a file. Use it to estimate the effort of an upgrade before you commit to it.

The AI Agent Loop

When the agent is enabled, the tool runs this loop:

Perceive: The advisors analyze the current state of the project and return structured findings.
Act: The AI agent reads the affected files in batches, and writes corrected versions following the advisor’s Fix text.
Verify: The project is compiled. If compilation fails, the agent reads the compiler error, corrects the file, and tries again.
Repeat: The advisors run again on the updated project. If findings remain, another round starts.

The loop ends when nothing is left to fix, or when the maximum number of rounds is reached. The default is 5 rounds (migration.maxRounds), followed by up to 5 extra rounds to fix compile errors (migration.compilerFixRounds). The batch size adapts to how fast your model answers, so a slow model gets smaller batches. If a request is cut off, the rest is retried in the next round.

If the rounds run out and the project still does not compile, the tool does not abort and does not roll anything back. The changes made so far stay in your project, and the pipeline checks record a failed Final Compile Check. Fix the remaining compile errors yourself, or run the tool again, because each run starts from the current state of your code.

Changes Made Without AI

The recipes refactor and upgrade code systematically across the whole project, without AI. They cover:

Namespace migration: javax. to jakarta. in Java source, XML descriptors, persistence.xml, web.xml and JSTL taglib URIs.
Dependency and platform upgrades: Jakarta EE 10 and 11 platform versions, Jersey, PrimeFaces, Mojarra, OmniFaces and EclipseLink.
API modernization: renaming or replacing removed and deprecated methods in Servlet, JSP, JPA, JAX-RS, EJB and Jakarta Authentication.
Framework migration: JSF managed beans and scopes to CDI, with @ManagedBean to @Named, @ManagedProperty to @Inject, and @Context to @Inject.

Besides the recipes, some changes are applied directly, such as updating the Jakarta EE platform version in your pom.xml and creating a missing beans.xml.

Reports

Every run keeps its results in .migration/migrate-N/ inside your project. The newest run is always in .migration/latest/.

File What it is

File	What it is
`audit-report.html`	The main report. Open it in any browser, also offline. It shows what was found, what was fixed, what remains, and whether the project still compiles.
`audit-report.md` and `audit-report.json`	The same results, to paste into an issue or use in a CI check.
`migration-plan.md`	Every finding the advisors raised, before any fix.
`post-migration-checklist.md`	Steps a person must do on a real server (for example `asadmin` commands), with your values filled in.
`migration.log`	The full log.

audit-report.html

The main report. Open it in any browser, also offline. It shows what was found, what was fixed, what remains, and whether the project still compiles.

audit-report.md and audit-report.json

The same results, to paste into an issue or use in a CI check.

migration-plan.md

Every finding the advisors raised, before any fix.

post-migration-checklist.md

Steps a person must do on a real server (for example asadmin commands), with your values filled in.

migration.log

The full log.

The report shows two statuses: Migration (did the run finish, or was it stopped) and Compilation (does the migrated project build). Each item ends as:

Fixed: the change was made.
Guide: the fix is an administration step, and the report gives the exact steps for your project.
Skipped: the tool could not do it. The report names what blocked it and what to do next.

Add .migration/ to your .gitignore. The tool never commits it, but it does not ignore it for you.

To list past runs with their reports, plans and logs, use the view goal.

Git Checkpoints

By default the tool commits to git after each recipe pass and each agent round, with a message starting with "Migration checkpoint:". Every step can be reviewed or undone. This needs a clean git repository (no staged or unstaged changes). Set migration.gitCommit=false to turn it off.

Interactive Mode

In interactive mode, you review each file change before it is written. See Getting Started.

Data Handling

The tool runs on your own machine against your own source tree. When you use the AI agent, your source code is sent to the LLM provider that you configure. Review your provider’s data handling, retention and IP terms before use. If your source code may not leave your control, use a self-hosted model.

The tool does not send telemetry to Azul.