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..b5dc58218af --- /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 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. + +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..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,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 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. + ## Read More * [View Menu](/refguide/view-menu/)