Visit Azul.com Support

Prerequisites and Scope

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

Prerequisites

To use the Azul Payara AI Upgrade Assistant, you need:

  • An active Azul Payara Enterprise subscription and a separate AI entitlement (at no extra cost).

  • A Maven or Gradle project containing a Jakarta EE application.

  • Java 17 or newer to run the tool. Maven is only needed when you run the tool as a Maven plugin. The jar, the web page started from the jar, and the Claude Code integration do not need Maven.

  • The build tool for your project (Maven, Gradle or Ant), so the tool can compile your application. The tool declares no minimum version of Maven or Gradle. The advisor scan was tested with Maven 3.3.+. For Gradle, the tool edits build.gradle and build.gradle.kts as plain text and only runs your project’s own Gradle for the compile check.

  • For the AI agent: an API key for a supported LLM provider, or access to a self-hosted model. See Choosing an LLM.

Only the AI agent uses an LLM. Detection and the advisors with recipes need no API key.

Note
 You do not need Azul Payara Server installed, and your project does not need any Payara dependency, to run the tool.

What Is Supported

  • Applications written against standard Jakarta EE APIs and Payara APIs.

  • Maven, Gradle and Ant projects. The tool compiles with the project’s own build tool (using the Maven wrapper mvnw when present). Dependency changes are written for Maven pom.xml files only.

  • Applications deployed to Azul Payara Server.

  • The migration paths listed in Supported Migrations.

Project Layout and Build Tool Detection

The tool looks only at the root of the project (migration.dir) to detect the build tool. It checks in this order and takes the first match:

  1. Gradle: settings.gradle, settings.gradle.kts, build.gradle or build.gradle.kts.

  2. Maven: pom.xml.

  3. Ant: build.xml.

If none of these exists, the tool falls back to Maven.

You cannot override the detection. If the wrong build tool is detected, point -Dmigration.dir at the right folder, or remove the stray build file. For example, a leftover build.gradle next to a pom.xml makes the tool treat the project as Gradle.

Multi-module and non-standard layouts: the scan covers every file under migration.dir that git does not ignore, whatever the module structure. It skips target/, node_modules/ and directories whose name starts with a dot.

Narrowing the scan: the filters work by file type only, not by module or folder, and neither accepts a path.

  • -Dmigration.includeExtensions=java,xml processes only those file types. It takes priority over the exclude list.

  • -Dmigration.excludeExtensions=jsp,properties skips those file types. It is ignored when an include list is set.

What Is Not Supported

Area Details

Vendor-proprietary APIs

APIs from other vendors are not translated. Applications that depend materially on them will produce a partial result. The advisors report usage of removed or changed Jakarta EE and javax APIs, but not usage of proprietary vendor APIs. Check your code for them yourself before you run the AI agent.

Application deployment

The tool compiles your upgraded application but does not deploy it. It cannot verify behavior that depends on a running application.

Azul Payara Micro applications

Not supported in this release.

MicroProfile upgrades

Not supported in this release.

Other build systems

Build systems other than Maven, Gradle and Ant are not supported.

Projects already on Jakarta EE 11

There is nothing to upgrade.

A Clean Compile Is Not a Tested Application

The tool stops when your project compiles cleanly and the advisor finds nothing left to fix. A project that compiles can still behave differently at runtime. Always run your own test suite and test the application on a target server before using the upgraded code in production.

Invocation

The tool is one jar that you can run as a Maven plugin, with java -jar, from a web page, or from Claude Code. Run the jar for projects without a pom.xml. See Getting Started.