Skip to content

Commit 604f3d8

Browse files
emirmxemirmx
committed
Document Java migration tool
1 parent a469722 commit 604f3d8

2 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎content/en/docs/refguide/java-programming/java-migration-tool.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: "Java Migration Tool"
3+
url: /refguide/java-migration-tool/
4+
weight: 47
5+
description: "Describes the Java Migration Tool CLI for automatically rewriting deprecated Mendix Java API calls."
6+
---
7+
8+
## Introduction
9+
10+
The **Java Migration Tool** (`jmt`) is a command-line utility that automatically rewrites deprecated Mendix Java API calls.
11+
12+
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.
13+
14+
## Installation {#installation}
15+
16+
Download the tool from Mendix CDN: https://cdn.mendix.com/mendix-java-migration-tool/jmt-1.0.0.jar
17+
18+
## Basic Usage {#basic-usage}
19+
20+
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.
21+
22+
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.
23+
24+
The following example rewrites all Java files in `javasource/` to the target Studio Pro version:
25+
26+
```cmd
27+
"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"
28+
```
29+
30+
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).
31+
32+
## Commands {#commands}
33+
34+
Run the tool with `java -jar jmt-1.0.0.jar <COMMAND> [OPTIONS]`.
35+
36+
| Command | Description |
37+
|---------|-------------|
38+
| `version` | Display the tool version |
39+
| `recipes` | List all available migration recipes |
40+
| `rewrite <PATHS>` | Rewrite Java files at the given paths (files or directories) |
41+
42+
## Options {#options}
43+
44+
**Global:**
45+
46+
* `-h, --help` – show usage information
47+
48+
**`recipes` command:**
49+
50+
* `-o, --output <FORMAT>` – output format: `text` (default) or `json`
51+
52+
**`rewrite` command:**
53+
54+
* `-t, --to-version <VERSION>` – *(required)* target Studio Pro version, for example `11.2.0`
55+
* `-n, --dry-run` – preview changes without writing files
56+
* `-o, --output <FORMAT>` – output format: `text` (default) or `json`
57+
* `-p, --project-root <PATH>` – root of the Mendix project; enables classpath resolution via `javasource/`, `vendorlib/`, and `userlib/`
58+
* `-s, --studio-pro <PATH>` – Studio Pro installation directory; enables Mendix public Java API resolution via the runtime bundles
59+
60+
{{% alert color="warning" %}}
61+
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.
62+
63+
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.
64+
{{% /alert %}}
65+
66+
## Examples {#examples}
67+
68+
```bash
69+
# List available recipes
70+
java -jar jmt-1.0.0.jar recipes
71+
72+
# Apply with full project context for accurate type resolution
73+
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 \
74+
-p /path/to/mendix-project \
75+
-s "/path/to/Studio Pro 11.2.0"
76+
77+
# Preview changes without writing (dry run)
78+
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 -n
79+
80+
# Apply all applicable recipes to the javasource directory
81+
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0
82+
83+
# Machine-readable output for CI/CD integration
84+
java -jar jmt-1.0.0.jar rewrite javasource/ -t 11.2.0 -o json
85+
```
86+
87+
## Output Formats {#output-formats}
88+
89+
**Text** (default) — human-readable summary:
90+
91+
```
92+
[REWRITE] Target version: 11.2.0
93+
Applied recipes:
94+
- Replace IMendixObject.getMember(...) (available from: 10.18)
95+
96+
Changed: javasource/myfirstmodule/actions/MyAction.java
97+
Replace IMendixObject.getMember(...): 2
98+
99+
Files processed: 1
100+
Files changed: 1
101+
Total changes: 2
102+
```
103+
104+
**JSON** — machine-readable, suitable for CI/CD pipelines:
105+
106+
```json
107+
{
108+
"status": "success",
109+
"dryRun": false,
110+
"filesProcessed": 1,
111+
"filesChanged": 1,
112+
"totalChanges": 2,
113+
"files": [
114+
{
115+
"file": "javasource/myfirstmodule/actions/MyAction.java",
116+
"changes": [
117+
{
118+
"recipe": "Replace IMendixObject.getMember(IContext, String) with IMendixObject.getMember(String)",
119+
"count": 2
120+
}
121+
]
122+
}
123+
],
124+
"warnings": []
125+
}
126+
```
127+
128+
## Read More
129+
130+
* [Java Programming](/refguide/java-programming/)
131+
* [Update Assistant (Beta)](/refguide/update-assistant/)
132+
* [Java Version Migration](/refguide/java-version-migration/)

‎content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ This dialog box shows the following information:
6464

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

67+
## Fixing Deprecations {#fixing-deprecations}
68+
69+
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.
70+
6771
## Read More
6872

6973
* [View Menu](/refguide/view-menu/)

0 commit comments

Comments
 (0)