Skip to content

Document Java migration tool #11385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emirmx wants to merge 2 commits into
base: development
Choose a base branch
from
+136 −0
Open

Document Java migration tool #11385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
604f3d8
Document Java migration tool
emirmx Jun 16, 2026
cf2a2db
Review comments
emirmx Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 132 additions & 0 deletions content/en/docs/refguide/java-programming/java-migration-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
---
title: "Java Migration Tool"
url: /refguide/java-migration-tool/
weight: 47
description: "Describes the Java Migration Tool CLI for automatically rewriting deprecated and removed Mendix Java API calls."
---

## Introduction

The **Java Migration Tool** (`jmt`) is a command-line utility that automatically rewrites deprecated and removed Mendix Java API calls.

The tool complements the [Update Assistant (Beta)](/refguide/update-assistant/) pane: use the pane to identify deprecations, and the CLI to apply the fixes automatically.

## Installation {#installation}

Download the tool from Mendix CDN: https://cdn.mendix.com/mendix-java-migration-tool/jmt-1.0.0.jar

## Basic Usage {#basic-usage}

Run the tool from a Command Prompt. Use the same Java version that Studio Pro uses — you can find the Java installation path in Studio Pro's preferences.

Check failure on line 20 in content/en/docs/refguide/java-programming/java-migration-tool.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.", "location": {"path": "content/en/docs/refguide/java-programming/java-migration-tool.md", "range": {"start": {"line": 20, "column": 83}}}, "severity": "ERROR"}

If Java is on your `PATH`, call `java` directly. If not, provide the full path to the `java` executable. Similarly, either run the command from the directory where you saved `jmt-1.0.0.jar`, or specify its full path in the command.

The following example rewrites all Java files in `javasource/` to the target Studio Pro version:

```cmd
"C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot\bin\java" -jar jmt-1.0.0.jar rewrite --to-version 11.11 --studio-pro "C:\Program Files\Mendix\11.11.0" --project-root "C:\Users\YourName\Mendix\MyApp"
```

Replace the paths and version number with the actual values for your installation. For all available commands and options, see [Commands](#commands) and [Options](#options).

## Commands {#commands}

Run the tool with `java -jar jmt-1.0.0.jar <COMMAND> [OPTIONS]`.

| Command | Description |
|---------|-------------|
| `version` | Display the tool version |
| `recipes` | List all available migration recipes |
| `rewrite <PATHS>` | Rewrite Java files at the given paths (files or directories) |

## Options {#options}

**Global:**

* `-h, --help` – show usage information

**`recipes` command:**

* `-o, --output <FORMAT>` – output format: `text` (default) or `json`

**`rewrite` command:**

* `-t, --to-version <VERSION>` – *(required)* target Studio Pro version, for example `11.2.0`
* `-n, --dry-run` – preview changes without writing files
* `-o, --output <FORMAT>` – output format: `text` (default) or `json`
* `-p, --project-root <PATH>` – root of the Mendix project; enables classpath resolution via `javasource/`, `vendorlib/`, and `userlib/`
* `-s, --studio-pro <PATH>` – Studio Pro installation directory; enables Mendix public Java API resolution via the runtime bundles

{{% alert color="warning" %}}
Using `-p` and `-s` is strongly recommended. The tool relies on type binding resolution to apply recipes correctly — for example, it only rewrites `getMember` calls when it can confirm the receiver is an `IMendixObject`. Without these options, type information may be incomplete and recipes may not apply.

Check failure on line 61 in content/en/docs/refguide/java-programming/java-migration-tool.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.", "location": {"path": "content/en/docs/refguide/java-programming/java-migration-tool.md", "range": {"start": {"line": 61, "column": 115}}}, "severity": "ERROR"}

For the same reason, the Java code in your project must be error-free as much as possible before running the tool. Missing imports, unresolved types, or variables declared without a fully qualified type name can prevent a recipe from recognizing a valid call site.
{{% /alert %}}

## Examples {#examples}

```bash
# List available recipes
java -jar jmt-1.0.0.jar recipes

# Apply with full project context for accurate type resolution
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 \
-p /path/to/mendix-project \
-s "/path/to/Studio Pro 11.2.0"

# Preview changes without writing (dry run)
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 -n

# Apply all applicable recipes to the javasource directory
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0

# Machine-readable output for CI/CD integration
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 -o json
```

## Output Formats {#output-formats}

**Text** (default) — human-readable summary:

Check failure on line 89 in content/en/docs/refguide/java-programming/java-migration-tool.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.", "location": {"path": "content/en/docs/refguide/java-programming/java-migration-tool.md", "range": {"start": {"line": 89, "column": 19}}}, "severity": "ERROR"}

```
[REWRITE] Target version: 11.2.0
Applied recipes:
- Replace IMendixObject.getMember(...) (available from: 10.18)

Changed: javasource/myfirstmodule/actions/MyAction.java
Replace IMendixObject.getMember(...): 2

Files processed: 1
Files changed: 1
Total changes: 2
```

**JSON** — machine-readable, suitable for CI/CD pipelines:

Check failure on line 104 in content/en/docs/refguide/java-programming/java-migration-tool.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.", "location": {"path": "content/en/docs/refguide/java-programming/java-migration-tool.md", "range": {"start": {"line": 104, "column": 9}}}, "severity": "ERROR"}

```json
{
"status": "success",
"dryRun": false,
"filesProcessed": 1,
"filesChanged": 1,
"totalChanges": 2,
"files": [
{
"file": "javasource/myfirstmodule/actions/MyAction.java",
"changes": [
{
"recipe": "Replace IMendixObject.getMember(IContext, String) with IMendixObject.getMember(String)",
"count": 2
}
]
}
],
"warnings": []
}
```

## Read More

* [Java Programming](/refguide/java-programming/)
* [Update Assistant (Beta)](/refguide/update-assistant/)
* [Java Version Migration](/refguide/java-version-migration/)
4 changes: 4 additions & 0 deletions content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@

The highlighted code helps you locate the deprecated call in the file and update it.

## Fixing Mendix Java API Deprecations and Removals {#fixing-deprecations}

You can use the [Java Migration Tool](/refguide/java-migration-tool/) — a command-line utility that rewrites deprecated Mendix Java API calls in your project's source files. Use the Update Assistant pane to identify what needs fixing, then run the tool to apply the changes.

Check failure on line 69 in content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro or number range, use an en dash (–) instead.", "location": {"path": "content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md", "range": {"start": {"line": 69, "column": 70}}}, "severity": "ERROR"}

## Read More

* [View Menu](/refguide/view-menu/)
Expand Down
Loading