From 604f3d8358eae531af54d7be41a2467de53996bc Mon Sep 17 00:00:00 2001 From: Emir Uner Date: Tue, 16 Jun 2026 14:23:34 +0200 Subject: [PATCH 1/4] Document Java migration tool --- .../java-programming/java-migration-tool.md | 132 ++++++++++++++++++ .../menus/view-menu/update-assistant.md | 4 + 2 files changed, 136 insertions(+) create mode 100644 content/en/docs/refguide/java-programming/java-migration-tool.md diff --git a/content/en/docs/refguide/java-programming/java-migration-tool.md b/content/en/docs/refguide/java-programming/java-migration-tool.md new file mode 100644 index 00000000000..9893b48c7cf --- /dev/null +++ b/content/en/docs/refguide/java-programming/java-migration-tool.md @@ -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 Mendix Java API calls." +--- + +## Introduction + +The **Java Migration Tool** (`jmt`) is a command-line utility that automatically rewrites deprecated 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. + +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 [OPTIONS]`. + +| Command | Description | +|---------|-------------| +| `version` | Display the tool version | +| `recipes` | List all available migration recipes | +| `rewrite ` | Rewrite Java files at the given paths (files or directories) | + +## Options {#options} + +**Global:** + +* `-h, --help` – show usage information + +**`recipes` command:** + +* `-o, --output ` – output format: `text` (default) or `json` + +**`rewrite` command:** + +* `-t, --to-version ` – *(required)* target Studio Pro version, for example `11.2.0` +* `-n, --dry-run` – preview changes without writing files +* `-o, --output ` – output format: `text` (default) or `json` +* `-p, --project-root ` – root of the Mendix project; enables classpath resolution via `javasource/`, `vendorlib/`, and `userlib/` +* `-s, --studio-pro ` – 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. + +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: + +``` +[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: + +```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/) diff --git a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md index ab5ade95a47..83784cf4bd9 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md @@ -64,6 +64,10 @@ This dialog box shows the following information: The highlighted code helps you locate the deprecated call in the file and update it. +## Fixing Deprecations {#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. + ## Read More * [View Menu](/refguide/view-menu/) From cf2a2dbdd85f847d78c2c434f50949febd3107ae Mon Sep 17 00:00:00 2001 From: Emir Uner Date: Tue, 23 Jun 2026 16:34:45 +0200 Subject: [PATCH 2/4] Review comments --- .../en/docs/refguide/java-programming/java-migration-tool.md | 4 ++-- .../refguide/modeling/menus/view-menu/update-assistant.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/refguide/java-programming/java-migration-tool.md b/content/en/docs/refguide/java-programming/java-migration-tool.md index 9893b48c7cf..b5dc58218af 100644 --- a/content/en/docs/refguide/java-programming/java-migration-tool.md +++ b/content/en/docs/refguide/java-programming/java-migration-tool.md @@ -2,12 +2,12 @@ title: "Java Migration Tool" url: /refguide/java-migration-tool/ weight: 47 -description: "Describes the Java Migration Tool CLI for automatically rewriting deprecated Mendix Java API calls." +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 Mendix Java API calls. +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. diff --git a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md index 83784cf4bd9..9bf3f9bd829 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md @@ -64,7 +64,7 @@ This dialog box shows the following information: The highlighted code helps you locate the deprecated call in the file and update it. -## Fixing Deprecations {#fixing-deprecations} +## 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. From 5d4d14b3dff453a94357dc57e9c00f8279996152 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 2 Jul 2026 13:22:45 +0200 Subject: [PATCH 3/4] Review Update Assitant --- .../docs/refguide/modeling/menus/view-menu/update-assistant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md index 9bf3f9bd829..97c0a31adf4 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md @@ -66,7 +66,7 @@ The highlighted code helps you locate the deprecated call in the file and update ## 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. +Use the [Java Migration Tool](/refguide/java-migration-tool/), a command-line utility that rewrites deprecated Mendix Java API calls, in your app's source files. Use the **Update Assistant** pane to identify what needs fixing, then run the tool to apply the changes. ## Read More From d85842a7f4625dc4f4079e98363f74784bbbe2ee Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Fri, 3 Jul 2026 17:48:12 +0200 Subject: [PATCH 4/4] Proofread --- .../java-programming/java-migration-tool.md | 38 ++++++++++++------- .../menus/view-menu/update-assistant.md | 2 +- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/content/en/docs/refguide/java-programming/java-migration-tool.md b/content/en/docs/refguide/java-programming/java-migration-tool.md index b5dc58218af..0f6347a1dbb 100644 --- a/content/en/docs/refguide/java-programming/java-migration-tool.md +++ b/content/en/docs/refguide/java-programming/java-migration-tool.md @@ -17,11 +17,16 @@ Download the tool from Mendix CDN: https://cdn.mendix.com/mendix-java-migration- ## 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. +Run the tool from a command prompt. Use the same Java version that the version of Studio Pro you are migrating to uses. You can find the Java installation path in Studio Pro's preferences. -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 the `javasource/` folder of your app to the target Studio Pro version: -The following example rewrites all Java files in `javasource/` to the target Studio Pro version: +This example assumes: + +* The Java executable is saved to `C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot\bin\java` +* `jmt-1.0.0.jar` is saved to the current folder +* Mendix 11.11.0 is installed at `C:\Program Files\Mendix\11.11.0` +* Your app folder is `C:\Users\YourName\Mendix\MyApp` ```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" @@ -33,38 +38,43 @@ Replace the paths and version number with the actual values for your installatio Run the tool with `java -jar jmt-1.0.0.jar [OPTIONS]`. +* If Java is on your `PATH`, call `java` directly. If not, provide the full path to the `java` executable. +* Run the command from the folder where you saved `jmt-1.0.0.jar`, or specify its full path in the command. + | Command | Description | |---------|-------------| | `version` | Display the tool version | | `recipes` | List all available migration recipes | -| `rewrite ` | Rewrite Java files at the given paths (files or directories) | +| `rewrite ` | Rewrite Java files that are in the given paths (files or folders) | ## Options {#options} -**Global:** +### Global * `-h, --help` – show usage information -**`recipes` command:** +### `recipes` Command * `-o, --output ` – output format: `text` (default) or `json` -**`rewrite` command:** +### `rewrite` Command * `-t, --to-version ` – *(required)* target Studio Pro version, for example `11.2.0` * `-n, --dry-run` – preview changes without writing files * `-o, --output ` – output format: `text` (default) or `json` -* `-p, --project-root ` – root of the Mendix project; enables classpath resolution via `javasource/`, `vendorlib/`, and `userlib/` -* `-s, --studio-pro ` – Studio Pro installation directory; enables Mendix public Java API resolution via the runtime bundles +* `-p, --project-root ` – root of the Mendix project. This enables classpath resolution via `javasource/`, `vendorlib/`, and `userlib/` +* `-s, --studio-pro ` – Studio Pro installation folder. This 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. +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 be applied. 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} +### Commands + ```bash # List available recipes java -jar jmt-1.0.0.jar recipes @@ -77,16 +87,16 @@ java -jar jmt-1.0.0.jar rewrite javasource/ -t 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 +# Apply all applicable recipes to the javasource folder 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} +### Output Formats {#output-formats} -**Text** (default) — human-readable summary: +**Text** (default) – human-readable summary: ``` [REWRITE] Target version: 11.2.0 @@ -101,7 +111,7 @@ Files changed: 1 Total changes: 2 ``` -**JSON** — machine-readable, suitable for CI/CD pipelines: +**JSON** – machine-readable, suitable for CI/CD pipelines: ```json { diff --git a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md index 97c0a31adf4..5487277c5f1 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/update-assistant.md @@ -66,7 +66,7 @@ The highlighted code helps you locate the deprecated call in the file and update ## Fixing Mendix Java API Deprecations and Removals {#fixing-deprecations} -Use the [Java Migration Tool](/refguide/java-migration-tool/), a command-line utility that rewrites deprecated Mendix Java API calls, in your app's source files. Use the **Update Assistant** pane to identify what needs fixing, then run the tool to apply the changes. +You can use the [Java Migration Tool](/refguide/java-migration-tool/), a command-line utility to rewrite deprecated and removed Mendix Java API calls in your app's source files. Use the **Update Assistant** pane to identify what needs fixing, then run the tool to apply the changes. ## Read More