diff --git a/docs/cli-guide-mtr/master.adoc b/docs/cli-guide-mtr/master.adoc index 6cf8f8f759..dea9ddae0d 100644 --- a/docs/cli-guide-mtr/master.adoc +++ b/docs/cli-guide-mtr/master.adoc @@ -17,67 +17,67 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the {UserCLIBookName} -include::topics/about-cli-guide.adoc[leveloffset=+2] +include::topics/mtr-about-cli-guide.adoc[leveloffset=+2] // About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] // About the {CLINameTitle} -include::topics/about-cli.adoc[leveloffset=+2] +include::topics/mtr-about-cli.adoc[leveloffset=+2] == Installing and Running the CLI // Install the CLI -include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2] +include::topics/mtr-installing-web-console-or-cli-tool.adoc[leveloffset=+2] // Run the CLI include::topics/cli-run.adoc[leveloffset=+2] // Use OpenRewrite recipes -include::topics/using-openrewrite-recipes.adoc[leveloffset=+3] +include::topics/mtr-using-openrewrite-recipes.adoc[leveloffset=+3] // Available OpenRewrite recipes -include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] +include::topics/mtr-available-openrewrite-recipes.adoc[leveloffset=+4] // Access the Report -include::topics/access-report.adoc[leveloffset=+2] +include::topics/mtr-access-report.adoc[leveloffset=+2] // Review the Reports -include::topics/review-reports.adoc[leveloffset=+1] +include::topics/mtr-review-reports.adoc[leveloffset=+1] // Export the Report in CSV Format -include::topics/csv-export.adoc[leveloffset=+1] +include::topics/mtr-csv-export.adoc[leveloffset=+1] // Mavenize Your Application -include::topics/mavenize.adoc[leveloffset=+1] +include::topics/mtr-mavenize.adoc[leveloffset=+1] // Optimize {ProductShortName} Performance -include::topics/optimize-performance.adoc[leveloffset=+1] +include::topics/mtr-optimize-performance.adoc[leveloffset=+1] // Configure {ProductShortName} to Exclude Files and Packages -include::topics/exclude-files-and-packages.adoc[leveloffset=+2] +include::topics/mtr-exclude-files-and-packages.adoc[leveloffset=+2] [appendix] == Reference material // {ProductShortName} Command-line Arguments -include::topics/cli-args.adoc[leveloffset=+2] +include::topics/mtr-cli-args.adoc[leveloffset=+2] // Added in 4.3.0: list of supported Tech Tags -include::topics/tech-tags.adoc[leveloffset=+2] +include::topics/mtr-tech-tags.adoc[leveloffset=+2] // Rule Story Points -include::topics/about-story-points.adoc[leveloffset=+2] +include::topics/mtr-about-story-points.adoc[leveloffset=+2] For more information on categorizing tasks, see link:{ProductDocRulesGuideURL}/rule_categories_rules-development-guide#rule_categories_rules-development-guide[Using custom rule categories]. === Additional Resources // Get Involved -include::topics/get-involved.adoc[leveloffset=+3] +include::topics/mtr-get-involved.adoc[leveloffset=+3] // Important Links -include::topics/important-links.adoc[leveloffset=+3] +include::topics/mtr-important-links.adoc[leveloffset=+3] // Report Issues with {ProductShortName} diff --git a/docs/eclipse-code-ready-studio-guide-mtr/master.adoc b/docs/eclipse-code-ready-studio-guide-mtr/master.adoc index 952b930153..403ce3d0a1 100644 --- a/docs/eclipse-code-ready-studio-guide-mtr/master.adoc +++ b/docs/eclipse-code-ready-studio-guide-mtr/master.adoc @@ -21,29 +21,29 @@ include::topics/making-open-source-more-inclusive.adoc[] [id="introduction_{context}"] == Introduction -include::topics/about-ide-addons.adoc[leveloffset=+2] -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-about-ide-addons.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] [id="installing-plugin_{context}"] == Installing and configuring the {PluginName} You can install the {PluginName} and configure it to use the {ProductShortName} CLI for analysis execution. -include::topics/eclipse-installing-plugin.adoc[leveloffset=+2] +include::topics/mtr-eclipse-installing-plugin.adoc[leveloffset=+2] -include::topics/eclipse-configuring-plugin-for-cli.adoc[leveloffset=+2] +include::topics/mtr-eclipse-configuring-plugin-for-cli.adoc[leveloffset=+2] -include::topics/eclipse-accessing-tools.adoc[leveloffset=+1] +include::topics/mtr-eclipse-accessing-tools.adoc[leveloffset=+1] [id="analyzing-projects-with-plugin_{context}"] == Analyzing your projects with the {PluginName} You can analyze your projects with the {PluginName} by creating a run configuration, running an analysis, and then reviewing and resolving migration issues detected by the {PluginName}. -include::topics/eclipse-configuring-run.adoc[leveloffset=+2] -include::topics/eclipse-analyzing-projects.adoc[leveloffset=+2] -include::topics/eclipse-reviewing-issues.adoc[leveloffset=+2] -include::topics/eclipse-resolving-issues.adoc[leveloffset=+2] +include::topics/mtr-eclipse-configuring-run.adoc[leveloffset=+2] +include::topics/mtr-eclipse-analyzing-projects.adoc[leveloffset=+2] +include::topics/mtr-eclipse-reviewing-issues.adoc[leveloffset=+2] +include::topics/mtr-eclipse-resolving-issues.adoc[leveloffset=+2] // TODO: Uncomment when uninstalling works and this is ready // include::topics/plugin-uninstall.adoc[leveloffset=+1] @@ -55,9 +55,9 @@ The {PluginName} comes with a core set of *System* rules for analyzing projects You can create and import custom rulesets. -include::topics/eclipse-viewing-rules.adoc[leveloffset=+2] -include::topics/eclipse-creating-custom-ruleset.adoc[leveloffset=+2] -include::topics/eclipse-importing-custom-ruleset.adoc[leveloffset=+2] -include::topics/eclipse-submitting-ruleset.adoc[leveloffset=+2] +include::topics/mtr-eclipse-viewing-rules.adoc[leveloffset=+2] +include::topics/mtr-eclipse-creating-custom-ruleset.adoc[leveloffset=+2] +include::topics/mtr-eclipse-importing-custom-ruleset.adoc[leveloffset=+2] +include::topics/mtr-eclipse-submitting-ruleset.adoc[leveloffset=+2] :!eclipse-code-ready-studio-guide: diff --git a/docs/getting-started-guide-mtr/master.adoc b/docs/getting-started-guide-mtr/master.adoc index d44eb7bd7b..ca82b2e5c5 100644 --- a/docs/getting-started-guide-mtr/master.adoc +++ b/docs/getting-started-guide-mtr/master.adoc @@ -17,21 +17,21 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the {IntroToMTABookName} -include::topics/about-the-intro-to-mta-guide.adoc[leveloffset=+2] +include::topics/mtr-about-the-intro-to-mta-guide.adoc[leveloffset=+2] // About the Toolkit -include::topics/what-is-the-toolkit.adoc[leveloffset=+1] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+1] // Windup Features -include::topics/features.adoc[leveloffset=+2] +include::topics/mtr-features.adoc[leveloffset=+2] // Windup Rules -include::topics/about-rules.adoc[leveloffset=+2] +include::topics/mtr-about-rules.adoc[leveloffset=+2] == Supported configurations // Supported Migration Paths -include::topics/migration-paths.adoc[leveloffset=+2] +include::topics/mtr-migration-paths.adoc[leveloffset=+2] // Prerequisites == Prerequisites @@ -40,45 +40,45 @@ include::topics/snippet_jdk-hardware-mac-prerequisites.adoc[] // At a later date, we may wish to add the following section, once it is revised: For tips on how to optimize performance, see link:{ProductDocUserGuideURL}#optimize_performance[Optimizing {ProductShortName} performance] in {ProductShortName} _{UserCLIBookName}_. // About the Tools -include::topics/about-tools.adoc[leveloffset=+1] +include::topics/mtr-about-tools.adoc[leveloffset=+1] // About the {CLIName} -include::topics/about-cli.adoc[leveloffset=+2] +include::topics/mtr-about-cli.adoc[leveloffset=+2] // About the {WebNameTitle} -include::topics/about-the-web-console.adoc[leveloffset=+2] +include::topics/mtr-about-the-web-console.adoc[leveloffset=+2] // About the {PluginNameTitle} -include::topics/eclipse-about-plugin.adoc[leveloffset=+2] +include::topics/mtr-eclipse-about-plugin.adoc[leveloffset=+2] // About the VS Code extension -include::topics/about-vscode-extension.adoc[leveloffset=+2] +include::topics/mtr-about-vscode-extension.adoc[leveloffset=+2] // About the {MavenNameTitle} -include::topics/about-maven.adoc[leveloffset=+2] +include::topics/mtr-about-maven.adoc[leveloffset=+2] == Planning your application migration // Goals of Assessing a Migration -include::topics/migration-goals.adoc[leveloffset=+2] +include::topics/mtr-migration-goals.adoc[leveloffset=+2] // Red Hat's Application Migration Approach -include::topics/migration-approach.adoc[leveloffset=+2] +include::topics/mtr-migration-approach.adoc[leveloffset=+2] // Best Practices -include::topics/migration-best-practices.adoc[leveloffset=+3] +include::topics/mtr-migration-best-practices.adoc[leveloffset=+3] // Migration Methodology -include::topics/migration-methodology.adoc[leveloffset=+3] +include::topics/mtr-migration-methodology.adoc[leveloffset=+3] // Discover Phase -include::topics/method-discover.adoc[leveloffset=+4] +include::topics/mtr-method-discover.adoc[leveloffset=+4] // Design Phase -include::topics/method-design.adoc[leveloffset=+4] +include::topics/mtr-method-design.adoc[leveloffset=+4] // Deploy Phase -include::topics/method-deploy.adoc[leveloffset=+4] +include::topics/mtr-method-deploy.adoc[leveloffset=+4] [appendix] == Reference material @@ -86,10 +86,10 @@ include::topics/method-deploy.adoc[leveloffset=+4] === Additional resources // Get Involved -include::topics/get-involved.adoc[leveloffset=+3] +include::topics/mtr-get-involved.adoc[leveloffset=+3] // Important Links -include::topics/important-links.adoc[leveloffset=+3] +include::topics/mtr-important-links.adoc[leveloffset=+3] ==== Reporting issues diff --git a/docs/intellij-idea-plugin-guide-mtr/master.adoc b/docs/intellij-idea-plugin-guide-mtr/master.adoc index 9fa5e167f6..7c4c60810e 100644 --- a/docs/intellij-idea-plugin-guide-mtr/master.adoc +++ b/docs/intellij-idea-plugin-guide-mtr/master.adoc @@ -20,28 +20,28 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the IntelliJ IDEA plugin -include::topics/about-ide-addons.adoc[leveloffset=+2] +include::topics/mtr-about-ide-addons.adoc[leveloffset=+2] // About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] // Install the plugin -include::topics/installing-intellij-idea-plugin.adoc[leveloffset=+1] +include::topics/mtr-installing-intellij-idea-plugin.adoc[leveloffset=+1] [id="analyzing-projects-with-idea-plugin"] == Analyzing your projects with the {ProductShortName} plugin You can analyze your projects with the {ProductShortName} plugin by creating a run configuration and running an analysis. -include::topics/intellij-idea-plugin-run-configuration.adoc[leveloffset=+2] +include::topics/mtr-intellij-idea-plugin-run-configuration.adoc[leveloffset=+2] [id="reviewing-and-resolving-migration-issues"] == Reviewing and resolving migration issues You can review and resolve migration issues identified by the {ProductShortName} plugin in the left pane. -include::topics/intellij-idea-plugin-reviewing-issues.adoc[leveloffset=+2] +include::topics/mtr-intellij-idea-plugin-reviewing-issues.adoc[leveloffset=+2] -include::topics/intellij-idea-plugin-resolving-issues.adoc[leveloffset=+2] +include::topics/mtr-intellij-idea-plugin-resolving-issues.adoc[leveloffset=+2] :!idea-plugin: diff --git a/docs/maven-guide-mtr/master.adoc b/docs/maven-guide-mtr/master.adoc index 79372f3cc1..7cfc1a015b 100644 --- a/docs/maven-guide-mtr/master.adoc +++ b/docs/maven-guide-mtr/master.adoc @@ -16,49 +16,49 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the {MavenBookName} -include::topics/about-maven-guide.adoc[leveloffset=+2] +include::topics/mtr-about-maven-guide.adoc[leveloffset=+2] // About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] // About {MavenNameTitle} -include::topics/about-maven.adoc[leveloffset=+2] +include::topics/mtr-about-maven.adoc[leveloffset=+2] == Getting started // Run the {MavenNameTitle} -include::topics/maven-run.adoc[leveloffset=+2] +include::topics/mtr-maven-run.adoc[leveloffset=+2] // Run the {MavenNameTitle} with Multiple Modules -include::topics/maven-multi-module.adoc[leveloffset=+2] +include::topics/mtr-maven-multi-module.adoc[leveloffset=+2] // Access the Report -include::topics/maven-access-reports.adoc[leveloffset=+2] +include::topics/mtr-maven-access-reports.adoc[leveloffset=+2] // Export the Report in CSV Format -include::topics/csv-export.adoc[leveloffset=+1] +include::topics/mtr-csv-export.adoc[leveloffset=+1] [appendix] == Reference material // {MavenNameTitle} Arguments -include::topics/maven-arguments.adoc[leveloffset=+2] +include::topics/mtr-maven-arguments.adoc[leveloffset=+2] // Default `logging.properties` in {MavenShortName} -include::topics/maven-logging-properties.adoc[leveloffset=+2] +include::topics/mtr-maven-logging-properties.adoc[leveloffset=+2] // Rule Story Points -include::topics/about-story-points.adoc[leveloffset=+2] +include::topics/mtr-about-story-points.adoc[leveloffset=+2] For more information on categorizing tasks, see link:{ProductDocRulesGuideURL}/rule_categories_rules-development-guide#rule_categories_rules-development-guide[Using custom rule categories]. === Additional resources // Get Involved -include::topics/get-involved.adoc[leveloffset=+3] +include::topics/mtr-get-involved.adoc[leveloffset=+3] // Important Links -include::topics/important-links.adoc[leveloffset=+3] +include::topics/mtr-important-links.adoc[leveloffset=+3] // Report Issues with {ProductShortName} diff --git a/docs/plugin-guide-mtr/master.adoc b/docs/plugin-guide-mtr/master.adoc deleted file mode 100644 index d597a2a5c8..0000000000 --- a/docs/plugin-guide-mtr/master.adoc +++ /dev/null @@ -1,84 +0,0 @@ -:toc: -:toclevels: 4 -:numbered: -:mtr: -include::topics/templates/document-attributes.adoc[] - -:imagesdir: topics/images -:context: plugin-guide -:plugin-guide: -:_content-type: ASSEMBLY -= {PluginBookName} - -//Inclusive language statement -include::topics/making-open-source-more-inclusive.adoc[] - -== Introduction - -// About the IDE Plugin Guide -include::topics/plugin-intro.adoc[leveloffset=+2] - -// About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] - -// About the {PluginNameTitle} -include::topics/about-plugin.adoc[leveloffset=+2] - -// Install the IDE Plugin -include::topics/installing-plugin.adoc[leveloffset=+1] -:!plugin-guide: - -:context: disconnected -:disconnected: -include::topics/installing-plugin.adoc[leveloffset=+1] -:!disconnected: - -:context: plugin-guide -:plugin-guide: -// Access {ProductShortName} IDE Tools -include::topics/plugin-access-mta-tools.adoc[leveloffset=+1] - -// Plugin Components -include::topics/plugin-components.adoc[leveloffset=+2] - -// Using the plugin - -== Using the {ProductShortName} {PluginName} -include::topics/plugin-identify-resolve-issues.adoc[leveloffset=+2] - -// Review ProductShortName} Issues -include::topics/plugin-review-issues.adoc[leveloffset=+3] - -// Resolve ProductShortName} Issues -include::topics/plugin-resolve-issues.adoc[leveloffset=+3] - -// TODO: Uncomment when uninstalling works and this is ready -// include::topics/plugin-uninstall.adoc[leveloffset=+1] - -// Add Custom Rules -include::topics/plugin-use-custom-rules.adoc[leveloffset=+1] - -// Browse Rules -include::topics/plugin-view-rules.adoc[leveloffset=+2] - -// Import a Custom Ruleset -include::topics/plugin-import-custom-ruleset.adoc[leveloffset=+2] - -// Create a Custom Ruleset -include::topics/plugin-create-custom-ruleset.adoc[leveloffset=+2] - -// Submit a Custom Ruleset -include::topics/eclipse-submit-ruleset.adoc[leveloffset=+2] - -//[appendix] -// == Reference material -// -//include::topics/plugin-icon-legend.adoc[leveloffset=+2] - - -// ********************************** -// * Appendix: Revision Information * -// ********************************** -include::topics/templates/revision-info.adoc[] - -:!plugin-guide: diff --git a/docs/plugin-guide-mtr/topics b/docs/plugin-guide-mtr/topics deleted file mode 120000 index 5983d9292c..0000000000 --- a/docs/plugin-guide-mtr/topics +++ /dev/null @@ -1 +0,0 @@ -../topics \ No newline at end of file diff --git a/docs/rules-development-guide-mtr/master.adoc b/docs/rules-development-guide-mtr/master.adoc index 95799e15fb..fa12cd065d 100644 --- a/docs/rules-development-guide-mtr/master.adoc +++ b/docs/rules-development-guide-mtr/master.adoc @@ -18,89 +18,89 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the Rules Development Guide -include::topics/rules-guide-intro.adoc[leveloffset=+2] +include::topics/mtr-rules-guide-intro.adoc[leveloffset=+2] // Use of <{ProductShortName}_HOME> in this Guide -include::topics/about-home-var.adoc[leveloffset=+3] +include::topics/mtr-about-home-var.adoc[leveloffset=+3] // {ProductShortName} Rules -include::topics/about-rules.adoc[leveloffset=+2] +include::topics/mtr-about-rules.adoc[leveloffset=+2] // Getting Started -include::topics/getting-started-rules.adoc[leveloffset=+1] +include::topics/mtr-getting-started-rules.adoc[leveloffset=+1] // Create Your First XML Rule -include::topics/create-first-xml-rule.adoc[leveloffset=+2] +include::topics/mtr-create-first-xml-rule.adoc[leveloffset=+2] // Review the Quickstarts -include::topics/review-quickstarts.adoc[leveloffset=+2] +include::topics/mtr-review-quickstarts.adoc[leveloffset=+2] [id="creating-xml-rules_{context}"] == Creating XML rules // XML Rule Structure -include::topics/xml-rule-syntax.adoc[leveloffset=+2] +include::topics/mtr-xml-rule-syntax.adoc[leveloffset=+2] // Create a Basic XML Rule -include::topics/create-basic-xml-rule.adoc[leveloffset=+2] +include::topics/mtr-create-basic-xml-rule.adoc[leveloffset=+2] [id="xml-rules-syntax-mtr_{context}"] === XML rule syntax // When Condition Syntax -include::topics/xml-rule-when-syntax.adoc[leveloffset=+3] +include::topics/mtr-xml-rule-when-syntax.adoc[leveloffset=+3] // Perform Action Syntax -include::topics/xml-rule-perform-syntax.adoc[leveloffset=+3] +include::topics/mtr-xml-rule-perform-syntax.adoc[leveloffset=+3] // Where Syntax -include::topics/where-syntax.adoc[leveloffset=+3] +include::topics/mtr-where-syntax.adoc[leveloffset=+3] // Add the Rule to {ProductName} -include::topics/add-rule-to-mtr.adoc[leveloffset=+2] +include::topics/mtr-add-rule-to-mtr.adoc[leveloffset=+2] // Testing XML Rules -include::topics/testing-rules.adoc[leveloffset=+1] +include::topics/mtr-testing-rules.adoc[leveloffset=+1] // Manually Test the XML Rule -include::topics/manually-test-rules.adoc[leveloffset=+2] +include::topics/mtr-manually-test-rules.adoc[leveloffset=+2] // Test the Rules Using JUnit -include::topics/rules-testing-junit.adoc[leveloffset=+2] +include::topics/mtr-rules-testing-junit.adoc[leveloffset=+2] // About the validation report -include::topics/validation-report.adoc[leveloffset=+2] +include::topics/mtr-validation-report.adoc[leveloffset=+2] // creating a Validation Report -include::topics/validation-report-understanding.adoc[leveloffset=+3] +include::topics/mtr-validation-report-understanding.adoc[leveloffset=+3] // Reported Errors when Running the Validation Report -include::topics/validation-report-errors.adoc[leveloffset=+3] +include::topics/mtr-validation-report-errors.adoc[leveloffset=+3] // Overriding Rules -include::topics/overriding-rules.adoc[leveloffset=+1] +include::topics/mtr-overriding-rules.adoc[leveloffset=+1] // Using Custom Rule Categories -include::topics/rule-categories.adoc[leveloffset=+1] +include::topics/mtr-rule-categories.adoc[leveloffset=+1] [appendix] == Reference material // Rule Story Points -include::topics/about-story-points.adoc[leveloffset=+2] +include::topics/mtr-about-story-points.adoc[leveloffset=+2] For more information on categorizing tasks, see xref:rule-categories_{context}[Using custom rule categories]. === Additional resources // Review the Existing {ProductShortName} XML Rules -include::topics/review-existing-rules.adoc[leveloffset=+3] +include::topics/mtr-review-existing-rules.adoc[leveloffset=+3] // Fork and Clone the Ruleset GitHub Project -include::topics/fork-ruleset-repo.adoc[leveloffset=+4] +include::topics/mtr-fork-ruleset-repo.adoc[leveloffset=+4] // Important Links -include::topics/rules-important-links.adoc[leveloffset=+3] +include::topics/mtr-rules-important-links.adoc[leveloffset=+3] // ********************************** // * Appendix: Revision Information * diff --git a/docs/topics/mtr-about-cli-guide.adoc b/docs/topics/mtr-about-cli-guide.adoc new file mode 100644 index 0000000000..b88bec028a --- /dev/null +++ b/docs/topics/mtr-about-cli-guide.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: CONCEPT +[id="about-cli-guide_{context}"] += About the {UserCLIBookName} + +This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate Java applications or other components. It describes how to install and run the {CLIName}, review the generated reports, and take advantage of additional features. diff --git a/docs/topics/mtr-about-cli.adoc b/docs/topics/mtr-about-cli.adoc new file mode 100644 index 0000000000..fd491fccde --- /dev/null +++ b/docs/topics/mtr-about-cli.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="about-cli_{context}"] += About the {CLINameTitle} + +The {CLIName} is a command-line tool in the {ProductName} that allows you to assess and prioritize migration and modernization efforts for applications. It provides numerous reports that highlight the analysis without the overhead of the other tools. The {CLIName} includes a wide array of customization options, and allows you to finely tune {ProductShortName} analysis options or integrate with external automation tools. + +ifndef::cli-guide[] +For more information about using the {CLIName}, see the {ProductShortName} link:{ProductDocUserGuideURL}[_{UserCLIBookName}_]. +endif::cli-guide[] diff --git a/docs/topics/mtr-about-console-guide.adoc b/docs/topics/mtr-about-console-guide.adoc new file mode 100644 index 0000000000..86ae96732d --- /dev/null +++ b/docs/topics/mtr-about-console-guide.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: CONCEPT +[id="about-console-guide_{context}"] += About the {WebNameTitle} + +This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate or modernize Java applications or other components. It describes how to install and use the {WebName} to manage migration or modernization projects and analyze applications. diff --git a/docs/topics/mtr-about-home-var.adoc b/docs/topics/mtr-about-home-var.adoc new file mode 100644 index 0000000000..48aad906d8 --- /dev/null +++ b/docs/topics/mtr-about-home-var.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: CONCEPT +[id="about-home-var_{context}"] += Use of `<{ProductShortName}_HOME>` in this guide + +This guide uses the `<{ProductShortName}_HOME>` replaceable variable to denote the path to your {ProductShortName} installation. The installation directory is the `{ProductDistribution}` directory where you extracted the {ProductShortName} `.zip` file. + +[NOTE] +==== +If you are installing on a Windows operating system: + +. Extract the `.zip` file to a folder named `{LC_PSN}` to avoid a `Path too long` error. Alternatively, extract the file with link:https://www.7-zip.org/download.html[7-Zip] to a folder of any name you choose. +. If a *Confirm file replace* window is displayed during extraction, click *Yes to all*. +==== + +When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation. diff --git a/docs/topics/mtr-about-ide-addons.adoc b/docs/topics/mtr-about-ide-addons.adoc new file mode 100644 index 0000000000..d074c4ac6a --- /dev/null +++ b/docs/topics/mtr-about-ide-addons.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// +// * docs/getting-started-guide-guide/master.adoc + +:_content-type: CONCEPT +[id="getting-started-about-ide-addons_{context}"] += About the IDE Addons + +You can migrate and modernize applications by using the {ProductName} ({ProductShortName}) addons for: + +* Eclipse +* Visual Studio Code, Visual Studio Codespaces, and Eclipse Che +* IntelliJ IDEA, both the Community and Ultimate versions + +Each addon analyzes your projects using customizable rulesets, marks issues in the source code, provides guidance to fix the issues, and offers automatic code replacement, if possible. diff --git a/docs/topics/mtr-about-maven-guide.adoc b/docs/topics/mtr-about-maven-guide.adoc new file mode 100644 index 0000000000..e24791f6ba --- /dev/null +++ b/docs/topics/mtr-about-maven-guide.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: CONCEPT +[id="about-maven-guide_{context}"] += About the {MavenBookName} + +This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate Java applications or other components. It describes how to install and run the {MavenName}, review the generated reports, and take advantage of additional features. diff --git a/docs/topics/mtr-about-maven.adoc b/docs/topics/mtr-about-maven.adoc new file mode 100644 index 0000000000..5892b0aed5 --- /dev/null +++ b/docs/topics/mtr-about-maven.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: CONCEPT +[id="about-maven_{context}"] += About the {MavenNameTitle} + +The {MavenName} for the {ProductName} integrates into the Maven build process, allowing developers to continuously evaluate migration and modernization efforts with each iteration of source code. It provides numerous reports that highlight the analysis results, and is designed for developers who want updates with each build. diff --git a/docs/topics/mtr-about-rules.adoc b/docs/topics/mtr-about-rules.adoc new file mode 100644 index 0000000000..19058a305e --- /dev/null +++ b/docs/topics/mtr-about-rules.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="about-rules_{context}"] += About {ProductShortName} rules + +The {ProductName} ({ProductShortName}) contains rule-based migration tools that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. In fact, the {ProductShortName} analysis process is implemented using {ProductShortName} rules. {ProductShortName} uses rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports. + +{ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes. + +{ProductShortName} rules use the following rule pattern: + +---- +when(condition) + perform(action) +otherwise(action) +---- + +{ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box. Because applications may contain custom libraries or components, {ProductShortName} allows you to write your own rules to identify use of components or software that may not be covered by the existing ruleset. + +ifndef::rules-development-guide[] +If you plan to write your own custom rules, see the {ProductDocRulesGuideURL}[_{RulesDevBookName}_] for detailed instructions. +endif::rules-development-guide[] diff --git a/docs/topics/mtr-about-story-points.adoc b/docs/topics/mtr-about-story-points.adoc new file mode 100644 index 0000000000..e53e3f8993 --- /dev/null +++ b/docs/topics/mtr-about-story-points.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc +// * docs/rules-development-guide/master.adoc + +:_content-type: CONCEPT +[id="about-story-points_{context}"] += About rule story points + +== What are story points? + +_Story points_ are an abstract metric commonly used in Agile software development to estimate the _level of effort_ needed to implement a feature or change. + +The {ProductName} uses story points to express the level of effort needed to migrate particular application constructs, and the application as a whole. It does not necessarily translate to man-hours, but the value should be consistent across tasks. + +== How story points are estimated in rules + +Estimating the level of effort for the story points for a rule can be tricky. The following are the general guidelines {ProductShortName} uses when estimating the level of effort required for a rule. + +[cols="25%,15%,60%", options="header"] +|==== +|Level of Effort +|Story Points +|Description + +|Information +|0 +|An informational warning with very low or no priority for migration. + +|Trivial +|1 +|The migration is a trivial change or a simple library swap with no or minimal API changes. + +|Complex +|3 +|The changes required for the migration task are complex, but have a documented solution. + +|Redesign +|5 +|The migration task requires a redesign or a complete library change, with significant API changes. + +|Rearchitecture +|7 +|The migration requires a complete rearchitecture of the component or subsystem. + +|Unknown +|13 +|The migration solution is not known and may need a complete rewrite. +|==== + +== Task category + +In addition to the level of effort, you can categorize migration tasks to indicate the severity of the task. The following categories are used to group issues to help prioritize the migration effort. + +Mandatory:: The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform. + +Optional:: If the migration task is not completed, the application should work, but the results may not be optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after your migration is completed. An example of this would be the upgrade of EJB 2.x code to EJB 3. + +Potential:: The task should be examined during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of this would be migrating a third-party proprietary type where there is no directly compatible type. + +Information:: The task is included to inform you of the existence of certain files. These may need to be examined or modified as part of the modernization effort, but changes are typically not required. An example of this would be the presence of a logging dependency or a Maven `pom.xml`. diff --git a/docs/topics/mtr-about-the-intro-to-mta-guide.adoc b/docs/topics/mtr-about-the-intro-to-mta-guide.adoc new file mode 100644 index 0000000000..d1143086b6 --- /dev/null +++ b/docs/topics/mtr-about-the-intro-to-mta-guide.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="about-the-intro-to-mta-guide_{context}"] += About the {IntroToMTABookName} + +This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate Java applications or other components. It provides an overview of the {ProductName} and how to get started using the tools to plan and run your migration. diff --git a/docs/topics/mtr-about-the-web-console.adoc b/docs/topics/mtr-about-the-web-console.adoc new file mode 100644 index 0000000000..26f2cac3b5 --- /dev/null +++ b/docs/topics/mtr-about-the-web-console.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: CONCEPT +[id="about-the-web-console_{context}"] += About the {WebName} + +The {WebName} for the {ProductName} allows a team of users to assess and prioritize migration and modernization efforts for a large number of applications. It allows you to group applications into projects for analysis and provides numerous reports that highlight the results. + diff --git a/docs/topics/mtr-about-tools.adoc b/docs/topics/mtr-about-tools.adoc new file mode 100644 index 0000000000..12e19208c4 --- /dev/null +++ b/docs/topics/mtr-about-tools.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: CONCEPT +[id="about-tools_{context}"] += About the tools + +The {ProductName} ({ProductShortName}) provides several tools to assist you in the various stages of your migration and modernization efforts. Review the details of each tool to determine which one is right for your project. + +ifdef::mta[] +* User interface +endif::[] + +ifdef::mtr[] +* Web console +endif::[] + +* {ProductName} Operator +* CLI +* IDE addons for: +** Eclipse +** Visual Studio Code, Visual Studio Codespaces, and Eclipse Che +** IntelliJ IDEA +* {MavenName} diff --git a/docs/topics/mtr-about-vscode-extension.adoc b/docs/topics/mtr-about-vscode-extension.adoc new file mode 100644 index 0000000000..c09579b7e7 --- /dev/null +++ b/docs/topics/mtr-about-vscode-extension.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * docs/vs-code-extension-guide/master.adoc + +:_content-type: CONCEPT +[id='about-vscode-extension_{context}'] += About the {ProductShortName} extension for Visual Studio Code + +The {ProductName} ({ProductShortName}) extension for Visual Studio Code helps you migrate and modernize applications. + +The {ProductShortName} extension is also compatible with Visual Studio Codespaces, the Microsoft cloud-hosted development environment. + +The {ProductShortName} extension analyzes your projects using customizable rulesets, marks issues in the source code, provides guidance to fix the issues, and offers automatic code replacement, if possible. + +ifdef::getting-started-guide[] +For more information about using the {ProductShortName} extension, see the {ProductShortName} link:{ProductDocVscGuideURL}[_Visual Studio Code Extension Guide_]. +endif::[] diff --git a/docs/topics/mtr-access-report.adoc b/docs/topics/mtr-access-report.adoc new file mode 100644 index 0000000000..1b223b9572 --- /dev/null +++ b/docs/topics/mtr-access-report.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="access-report_{context}"] += Accessing reports + +When you run the {ProductName}, a report is generated in the `` that you specify using the `--output` argument in the command line. + +The output directory contains the following files and subdirectories: + +---- +/ +├── index.html // Landing page for the report +├── .csv // Optional export of data in CSV format +├── archives/ // Archives extracted from the application +├── mavenized/ // Optional Maven project structure +├── reports/ // Generated HTML reports +├── stats/ // Performance statistics +---- + +.Procedure + +. Obtain the path of the `index.html` file of your report from the output that appears after you run {ProductShortName}: ++ +---- +Report created: /index.html + Access it at this URL: file:////index.html +---- + +. Open the `index.html` file by using a browser. ++ +The generated report is displayed. diff --git a/docs/topics/mtr-add-rule-to-mtr.adoc b/docs/topics/mtr-add-rule-to-mtr.adoc new file mode 100644 index 0000000000..6d8b57c435 --- /dev/null +++ b/docs/topics/mtr-add-rule-to-mtr.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="add-rule-to-mtr_{context}"] += Adding a rule to the {ProductName} + +A {ProductName} rule is installed by copying the rule to the appropriate {ProductShortName} folder. {ProductShortName} scans for rules, which are files with the `.windup.xml` extension in the following locations: + +* Directory specified by the `--userRulesDirectory` argument on the {ProductShortName} command line. +* `<{ProductShortName}_HOME>/rules/` directory. `<{ProductShortName}_HOME>` is the directory where you install and run the {ProductName} executable. +* `${user.home}/.{LC_PSN}/rules/` directory. This directory is created by {ProductShortName} the first time it is run. it contains rules, add-ons, and the {ProductShortName} log. ++ +[NOTE] +==== +In a Windows operating system, the rules are located in `\Documents and Settings\\.{LC_PSN}\rules\` or `\Users\\.{LC_PSN}\rules\`. +==== diff --git a/docs/topics/mtr-available-openrewrite-recipes.adoc b/docs/topics/mtr-available-openrewrite-recipes.adoc new file mode 100644 index 0000000000..00d9de7332 --- /dev/null +++ b/docs/topics/mtr-available-openrewrite-recipes.adoc @@ -0,0 +1,38 @@ +// Module included in the following module: +// +// * docs/cli-guide-mtr/master.adoc + +[id=available-openrewrite-recipes_{context}] += Available OpenRewrite recipes + +.Available OpenRewrite recipes +[cols="22%,26%,26%,26%", options="header"] +|==== +|Migration path +|Purpose +|rewrite.configLocation +|activeRecipes + +|Java EE to Jakarta EE +|Replace import of `javax` packages with equivalent `jakarta` packages + +Replace `javax` artifacts, declared within `pom.xml` files, with the `jakarta` equivalents + +|`/rules/openrewrite/jakarta \ /javax/imports/rewrite.yml` +|`org.jboss.windup.JavaxToJakarta` + +|Java EE to Jakarta EE +|Rename bootstrapping files +|`/rules/openrewrite/jakarta \ /javax/bootstrapping/rewrite.yml` +|`org.jboss.windup.jakarta.javax. \ BootstrappingFiles` + +|Java EE to Jakarta EE +|Transform `persistence.xml` configuration +|`/rules/openrewrite/jakarta \ /javax/xml/rewrite.yml` +|`org.jboss.windup.javax-jakarta. \ PersistenceXML` + +|Spring Boot to Quarkus +|Replace `spring.jpa.hibernate.ddl-auto` property within files matching `application*.properties` +|`/rules/openrewrite/quarkus \ /springboot/properties/rewrite.yml` +|`org.jboss.windup.sb-quarkus.Properties` +|==== diff --git a/docs/topics/mtr-cli-args.adoc b/docs/topics/mtr-cli-args.adoc new file mode 100644 index 0000000000..7ce82c095b --- /dev/null +++ b/docs/topics/mtr-cli-args.adoc @@ -0,0 +1,210 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: REFERENCE +[id="cli-args_{context}"] += About {ProductShortName} command-line arguments + +The following is a detailed description of the available {ProductShortName} command line arguments. + +[NOTE] +==== +To run the {ProductShortName} command without prompting, for example when executing from a script, you must use the following arguments: + +* `--batchMode` +* `--overwrite` +* `--input` +* `--target` +==== + +.{ProductShortName} CLI arguments +[cols="40%,60%a",options="header",] +|==== +|Argument |Description +|--additionalClassPath |A space-delimited list of additional JAR files or directories to add to the class path so that they are available for decompilation or other analysis. +|--addonDir |Add the specified directory as a custom add-on repository. +|--analyzeKnownLibraries | Flag to analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code. + +[NOTE] +==== +This option may result in a longer execution time and a large number of migration issues being reported. +==== + +|--batchMode |Flag to specify that {ProductShortName} should be run in a non-interactive mode without prompting for confirmation. This mode takes the default values for any parameters not passed in to the command line. +|--debug |Flag to run {ProductShortName} in debug mode. +|--disableTattletale | Flag to disable generation of the Tattletale report. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored and the Tattletale report will still be generated. +|--discoverPackages |Flag to list all available packages in the input binary application. +|--enableClassNotFoundAnalysis |Flag to enable analysis of Java files that are not available on the class path. This should not be used if some classes will be unavailable at analysis time. +|--enableCompatibleFilesReport |Flag to enable generation of the Compatible Files report. Due to processing all files without found issues, this report may take a long time for large applications. +|--enableTattletale |Flag to enable generation of a Tattletale report for each application. This option is enabled by default when `eap` is in the included target. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored and the Tattletale report will still be generated. +|--enableTransactionAnalysis |[Technology Preview] Flag to enable generation of a Transactions report that displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks, such as Hibernate. + +[NOTE] +==== +enableTransactionAnalysis is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them +in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +==== + +|--excludePackages |A space-delimited list of packages to exclude from evaluation. For example, entering `com.mycompany.commonutilities` excludes all classes whose package names begin with `com.mycompany.commonutilities`. +|--excludeTags |A space-delimited list of tags to exclude. When specified, rules with these tags will not be processed. To see the full list of tags, use the `--listTags` argument. +|--explodedApp |Flag to indicate that the provided input directory contains source files for a single application. +|--exportCSV |Flag to export the report data to a CSV file on your local file system. {ProductShortName} creates the file in the directory specified by the `--output` argument. The CSV file can be imported into a spreadsheet program for data manipulation and analysis. +|--exportSummary |Flag to instruct {ProductShortName} to generate an `analysisSummary.json` export file in the output directory. The file contains analysis summary information for each application analyzed, including the number of incidents and story points by category, and all of the technology tags associated with the analyzed applications. +|--exportZipReport |This argument creates a `reports.zip` file in the output folder. The file contains the analysis output, typically, the reports. If requested, it can also contain the CSV export files. +|--help |Display the {ProductShortName} help message. +|--immutableAddonDir |Add the specified directory as a custom read-only add-on repository. +|--includeTags| A space-delimited list of tags to use. When specified, only rules with these tags will be processed. To see the full list of tags, use the `--listTags` argument. +|--input |A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required. +|--install |Specify add-ons to install. The syntax is `:[:]`. For example, `--install core-addon-x` or `--install org.example.addon:example:1.0.0`. +|--keepWorkDirs| Flag to instruct {ProductShortName} to not delete temporary working files, such as the graph database and extracted archive files. This is useful for debugging purposes. +|--legacyReports| Flag to instruct {ProductShortName} to generate the old format reports instead of the new format reports. +|--list| Flag to list installed add-ons. +|--listSourceTechnologies| Flag to list all available source technologies. +|--listTags| Flag to list all available tags. +|--listTargetTechnologies| Flag to list all available target technologies. +|--mavenize| Flag to create a Maven project directory structure based on the structure and content of the application. This creates `pom.xml` files using the appropriate Java EE API and the correct dependencies between project modules. See also the `--mavenizeGroupId` option. +|--mavenizeGroupId| When used with the `--mavenize` option, all generated `pom.xml` files will use the provided value for their ``. If this argument is omitted, {ProductShortName} will attempt to determine an appropriate `` based on the application, or will default to `com.mycompany.mavenized`. +|--online |Flag to allow network access for features that require it. Currently only validating XML schemas against external resources relies on Internet access. Note that this comes with a performance penalty. +|--output |Specify the path to the directory to output the report information generated by {ProductShortName}. +|--overwrite |Flag to force delete the existing output directory specified by `--output`. If you do not specify this argument and the `--output` directory exists, you are prompted to choose whether to overwrite the contents. + +[IMPORTANT] +==== +Do not overwrite a report output directory that contains important information. +==== + +|--packages| A space-delimited list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument. +|--remove |Remove the specified add-ons. The syntax is `:[:]`. For example, `--remove core-addon-x` or `--remove org.example.addon:example:1.0.0`. +|--skipReports |Flag to indicate that HTML reports should not be generated. A common use of this argument is when exporting report data to a CSV file using `--exportCSV`. +|--source |A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources. +|--sourceMode |Flag to indicate that the application to be evaluated contains source files rather than compiled binaries. The sourceMode argument has been deprecated. There is no longer the need to specify it. {ProductShortName} can intuitively process any inputs that are presented to it. In addition, project source folders can be analyzed with binary inputs within the same analysis execution. +|--target |A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. Use the `--listTargetTechnologies` argument to list all available targets. +|--userIgnorePath |Specify a location, in addition to `${user.home}/.{LC_PSN}/ignore/`, for {ProductShortName} to identify files that should be ignored. +|--userLabelsDirectory |Specify a location for {ProductShortName} to look for custom Target Runtime Labels. The value can be a directory containing label files or a single label file. The Target Runtime Label files must use the [x-]`.windup.label.xml` suffix. The shipped Target Runtime Labels are defined within `${ProductShortName}_HOME/rules/migration-core/core.windup.label.xml`. +|--userRulesDirectory |Specify a location, in addition to `<{ProductShortName}_HOME>/rules/` and `${user.home}/.{LC_PSN}/rules/`, for {ProductShortName} to look for custom {ProductShortName} rules. The value can be a directory containing ruleset files or a single ruleset file. The ruleset files must use the [x-]`.windup.xml` suffix. +|--version |Display the {ProductShortName} version. +|--skipSourceCodeReports |This option skips generating a _Source code report_ when generating the application analysis report. Use this advanced option when concerned about source code information appearing in the application analysis. +|==== + +[id="cli-input-argument_{context}"] +== Specifying the input + +A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required. + +.Usage +[source,options="nowrap",subs="attributes+"] +---- +--input [...] +---- + +[id="cli-input-file-type-arguments_{context}"] + +Depending on whether the input file type provided to the `--input` argument is a file or directory, it will be evaluated as follows depending on the additional arguments provided. + +Directory:: ++ +[cols="1,1,1",options="header"] +|==== +| --explodedApp +| --sourceMode +| Neither Argument + +| The directory is evaluated as a single application. +| The directory is evaluated as a single application. +| Each subdirectory is evaluated as an application. +|==== + +File:: ++ +[cols="1,1,1",options="header"] +|==== +| --explodedApp +| --sourceMode +| Neither Argument + +| Argument is ignored; the file is evaluated as a single application. +| The file is evaluated as a compressed project. +| The file is evaluated as a single application. +|==== + +[id="cli-output-argument_{context}"] +== Specifying the output directory + +Specify the path to the directory to output the report information generated by {ProductShortName}. + +.Usage +[source,options="nowrap",subs="attributes+"] +---- +--output +---- + +* If omitted, the report will be generated in an `.report` directory. +* If the output directory exists, you will be prompted with the following (with a default of N). ++ +[source,options="nowrap",subs="attributes+"] +---- +Overwrite all contents of "/home/username/" (anything already in the directory will be deleted)? [y,N] +---- + +However, if you specify the `--overwrite` argument, {ProductShortName} will proceed to delete and recreate the directory. See the description of this argument for more information. + +[id="cli-source-argument_{context}"] +== Setting the source technology + +A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources. + +.Usage +[source,options="nowrap",subs="attributes+"] +---- +--source +---- + +The `--source` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--source eap:5`. + +[WARNING] +==== +When migrating to JBoss EAP, be sure to specify the version, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path. + +See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version. +==== + +[id="cli-target-argument_{context}"] +== Setting the target technology + +A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. If you do not specify this option, you are prompted to select a target. Use the `--listTargetTechnologies` argument to list all available targets. + +.Usage +[source,options="nowrap",subs="attributes+"] +---- +--target +---- + + +The `--target` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--target eap:7`. + +[WARNING] +==== +When migrating to JBoss EAP, be sure to specify the version in the target, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path. + +See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version. +==== + +[id="cli-packages-argument_{context}"] +== Selecting packages + +A space-delimited list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument. + +.Usage +[source,options="nowrap",subs="attributes+"] +---- +--packages +---- + +* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The `` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use `--packages com.mycustomapp com.myotherapp` argument on the command line. +* While you can provide package names for standard Java EE third party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. + +[WARNING] +==== +If you omit the `--packages` argument, every package in the application is scanned, which can impact performance. +==== diff --git a/docs/topics/mtr-configuring-web-console-authentication-for-linux-windows-macos.adoc b/docs/topics/mtr-configuring-web-console-authentication-for-linux-windows-macos.adoc new file mode 100644 index 0000000000..1757320e25 --- /dev/null +++ b/docs/topics/mtr-configuring-web-console-authentication-for-linux-windows-macos.adoc @@ -0,0 +1,104 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="configuring-web-console-authentication-for-linux-windows-macos_{context}"] += Configuring authentication for the {WebName} on Linux, Windows, or macOS + +You can configure the {WebName} to require authentication for access. To enable authentication, you have to install Red Hat Single Sign-On (SSO). + +[discrete] +[id="enabling-authentication_{context}"] +== Enabling authentication + +.Procedure + +. Adjust the port number that the Red Hat SSO server opens to avoid conflicts with the port that the {WebName} uses by entering the following: ++ +** For Linux and macOS: ++ +---- +$ ./standalone.sh -Djboss.socket.binding.port-offset= +---- +** For Windows: ++ +---- +> ...\bin\standalone.bat -Djboss.socket.binding.port-offset= +---- + +. Open the Red Hat SSO administration console from `\http://localhost:8180`: +* Username: `admin` +* Password: `admin` +. Add a realm named *windup*. +. In the realm, create a client named *windup-web*. +. Check that *Access Type* is set to `public`. +. Set *Valid Redirect URIs* to `\http://localhost:8080/windup-ui/*`. +. Set *Web Origins* to `+*+` and click *Save*. +. Create a role named *user*. +. Create a user with any name. +. Set the credentials of the user, disable *Temporary*, and assign the role "user" to the user. +. Switch the {WebName} to *Authentication required* mode by doing the following: +.. Export the following ENV variables: +** For Linux and macOS: ++ +---- +export SSO_AUTH_SERVER_URL=http://localhost:8180/auth +export SSO_REALM=windup +export SSO_SSL_REQUIRED=EXTERNAL +export SSO_CLIENT_ID=windup-web +---- +** For Windows: ++ +---- +set SSO_AUTH_SERVER_URL=http://localhost:8180/auth +set SSO_REALM=windup +set SSO_SSL_REQUIRED=EXTERNAL +set SSO_CLIENT_ID=windup-web +---- ++ +[NOTE] +==== +Environment variables that are set by the `set` command in CMD are local, available to the current CMD session only. Use the Windows Control Panel to permanently set the environment variables. +==== + +.. Run the following script: +** For Linux and macOS: ++ +---- +$ /switch_to_authentication_required.sh +---- +** For Windows: ++ +---- +C:\\switch_to_authentication_required.bat +---- +. Start the {WebName} by entering the following: +** For Linux and macOS: ++ +---- +$ /run_windup.sh +---- +** For Windows: ++ +---- +C:\\run_windup.bat +---- +. Open the browser at `\http://localhost:8080/windup-ui`. + +[discrete] +[id="disabling-authentication_{context}"] +== Disabling authentication + +.Procedure +. Run the following script: +** For Linux and macOS: ++ +---- +$ /switch_to_automatic_authentication.sh +---- +** For Windows: ++ +---- +C:\\switch_to_automatic_authentication.bat +---- diff --git a/docs/topics/mtr-create-basic-xml-rule.adoc b/docs/topics/mtr-create-basic-xml-rule.adoc new file mode 100644 index 0000000000..db709832fe --- /dev/null +++ b/docs/topics/mtr-create-basic-xml-rule.adoc @@ -0,0 +1,173 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="create-basic-xml-rule_{context}"] += Creating a basic XML rule + +This section describes how to create an {ProductShortName} XML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions. + +== Creating a basic XML rule template + +{ProductShortName} XML rules consist of _conditions_ and _actions_ and use the following rule pattern: + +[source,terminal,subs="attributes+"] +---- +when(condition) + perform(action) +otherwise(action) +---- + +Create a file with the following contents, which is the basic syntax for XML rules. + +[IMPORTANT] +==== +The XML file name must include the `.windup.xml` extension. Otherwise, {ProductShortName} does not evaluate the new rule. +==== + +[source,xml,subs="attributes+"] +---- + + + + + + + + + + + + + + + + + + + +---- + +== Creating the ruleset metadata + +The XML ruleset `metadata` element provides additional information about the ruleset such as a description, the source and target technologies, and add-on dependencies. The metadata also allows for specification of tags, which allow you to provide additional information about a ruleset. + +.`` example + +[source,xml,subs="attributes+"] +---- + + + + This is the description. + + + + + + + + + + require-stateless + require-nofilesystem-io + AfterRulesetId + BeforeRulesetId + + + ... + + +---- + +== Creating a rule + +Individual rules are contained within the `` element. They comprise one or more `when` conditions and perform actions. + +See the link:http://windup.jboss.org/schema/windup-jboss-ruleset.xsd[XML rule schema] for valid rule syntax. + +[id="create-when-condition_{context}"] +=== Creating a `` condition + +The XML rule `` element tests for a condition. The following is a list of valid `` conditions. + +[cols="1,4", options="header"] +|==== +|Element +|Description + +| +|The standard logical _and_ operator. + +| +|Find strings or text within files, for example, properties files. + +| +|Define file names to internal stored File model. + +| +|Test for a match in a Java class. + +| +|Exclude javaclass that you would like to ignore in processing discovery. + +| +|The standard logical _not_ operator. + +| +|The standard logical _or_ operator. + +| +|Define package names to organization or libraries. + +| +|Test for project characteristics, such as dependencies. + +| +|Always match. + +| +|Test for a match in an XML file. + +|==== + +The specific syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file, a project, or file content. + +[id="create-perform-action_{context}"] +=== Creating a `` action + +The XML rule `` element performs the action when the condition is met. Operations allowed in this section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project line item reporting. The following is a list of valid `` actions. + +[cols="1,4", options="header"] +|==== +|Element +|Description + +| +|This operation adds metadata that you want to apply to the entire file. For example, if the Java Class is a JMS Message Listener, you can add a Classification with the title "JMS Message Listener" that includes information that applies to the entire file. You can also set an effort level for the entire file. + +| +|This operation adds metadata to a line within the file. This provides a hint or inline information about how to migrate a section of code. + +| +|This specifies to iterate over an implicit or explicit variable defined within the rule. + +| +|This provides a high-level message that is displayed in the application overview page. + +| +|This provides an HTML link to additional information or documentation about the migration task. + +| +|This specifies how to transform an XML file. + +|==== diff --git a/docs/topics/mtr-create-first-xml-rule.adoc b/docs/topics/mtr-create-first-xml-rule.adoc new file mode 100644 index 0000000000..ebad527be8 --- /dev/null +++ b/docs/topics/mtr-create-first-xml-rule.adoc @@ -0,0 +1,252 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="create-first-xml-rule_{context}"] += Creating your first XML rule + +This section guides you through the process of creating and testing your first {ProductShortName} XML-based rule. This assumes that you have already installed {ProductShortName}. See link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_ for installation instructions. + +In this example, you will write a rule to discover instances where an application defines a `jboss-web.xml` file containing a `` element and provide a link to the documentation that describes how to migrate the code. + +[id="creating-directory-structure-for-the-rule_{context}"] +== Creating the directory structure for the rule + +Create a directory structure to contain your first rule and the data file to use for testing. + +[options="nowrap",subs="attributes+"] +---- +$ mkdir -p /home//migration-rules/rules +$ mkdir -p /home//migration-rules/data +---- + +This directory structure will also be used to hold the generated {ProductShortName} reports. + +[id="mta-creating-data-to-test-the-rule_{context}"] +== Creating data to test the rule + +. Create a `jboss-web.xml` file in the `/home//migration-rules/data/` subdirectory. +. Copy in the following content. ++ +[source,xml,subs="attributes+"] +---- + + + + + seam.jboss.org:loader=@projectName@ + java2ParentDelegation=false + + + +---- + +[id="creating-the-rule_{context}"] +== Creating the rule + +{ProductShortName} XML-based rules use the following rule pattern: + +---- +when(condition) + perform(action) +otherwise(action) +---- + +.Procedure + +. In the `/home//migration-rules/rules/` directory, create a file named `JBoss5-web-class-loading.windup.xml` that contains the following content: ++ +[source,xml,subs="attributes+"] +---- + + + + + + + + + + + + Reviewed-2015-05-01 + + + + + + + + + + + + +---- ++ +[NOTE] +==== +The XML file name must include the `.windup.xml` extension. Otherwise, {ProductShortName} does not evaluate the new rule. +==== + +. Add a unique identifier for the ruleset and rule: + +* Replace `` with an appropriate ruleset ID, for example, `JBoss5-web-class-loading`. +* Replace `` with an appropriate rule ID, for example, `JBoss5-web-class-loading_001`. + +. Add the following ruleset add-on dependencies: ++ +[source,xml,subs="attributes+"] +---- + + + + +---- + +. Add the source and target technologies: + +* Replace `` with `eap`. +* Replace `` with `eap`. + +. Set the source and target technology versions. ++ +* Replace `` with `(4,5)`. +* Replace `` with `(6,)`. + ++ +See the Apache Maven link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[version range specification] for more information. + +. Complete the `when` condition. Because this rule tests for a match in an XML file, `xmlfile` is used to evaluate the files. ++ +To match on the `class-loading` element that is a child of `jboss-web`, use the xpath expression `jboss-web/class-loading`. ++ +[source,xml,subs="attributes+"] +---- + + + +---- +. Complete the `perform` action for this rule. ++ +* Add a classification with a descriptive title and a level of effort of `1`. +* Provide a hint with an informative message and a link to documentation that describes the migration details. ++ +[source,xml,subs="attributes+"] +---- + + + + + + The class-loading element is no longer valid in the jboss-web.xml file. + + + + + +---- + +The rule is now complete and should look like the following example. + +[source,xml,subs="attributes+"] +---- + + + + + This ruleset looks for the class-loading element in a jboss-web.xml file, which is no longer valid in JBoss EAP 6 + + + + + + + + + + + + + + + + + + + The class-loading element is no longer valid in the jboss-web.xml file. + + + + + + + + +---- +[] + +[id="mta-installing-rule-in-directory_{context}"] +== Installing the rule + +An {ProductShortName} rule is installed by placing the rule into the appropriate directory. + +Copy the `JBoss5-web-class-loading.windup.xml` file to the `<{ProductShortName}_HOME>/rules/` directory. + +[source,options="nowrap",subs="attributes+"] +---- +$ cp /home//migration-rules/rules/JBoss5-web-class-loading.windup.xml <{ProductShortName}_HOME>/rules/ +---- +[] + +[id="mta-testing-the-rule_{context}"] +== Testing the rule + +Open a terminal and run the following command, passing the test file as an input argument and a directory for the output report. + +[options="nowrap",subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/bin/windup-cli --sourceMode --input /home//migration-rules/data --output /home//migration-rules/reports --target eap:6 +---- + +You should see the following result. + +[options="nowrap",subs="attributes+"] +---- +Report created: /home//migration-rules/reports/index.html + Access it at this URL: file:///home//migration-rules/reports/index.html +---- +[] +[id="mta-reviewing-the-report_{context}"] +== Reviewing the reports + +Review the report to be sure that it provides the expected results. For a more detailed walkthrough of {ProductShortName} reports, see the link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] section of the {ProductShortName} _{UserCLIBookName}_. + +. Open `/home//migration-rules/reports/index.html` in a web browser. +. Verify that the rule ran successfully. +.. From the main landing page, click the *Rule providers execution overview* link to open the Rule Providers Execution Overview. ++ +.. Find the `JBoss5-web-class-loading_001` rule and verify that its *Status?* is `Condition met` and its *Result?* is `success`. ++ +.Test rule execution +image::executed-test-rule.png[Test rule execution] +. Verify that the rule matches the test data: + +.. From the main landing page, click the name of the application or input folder, which is `data` in this example. +.. Click the *Application Details* report link. +.. Click the *jboss-web.xml* link to view the *Source Report*. ++ +You can see that the `` line is highlighted, and the hint from the custom rule is shown inline. ++ +.Rule match +image::test-rule-details.png[Rule match] ++ +// TODO: Consider updating with test data/rule combo that won't match on any of the other existing rules. +The top of the file lists the classifications for matching rules. You can use the link icon to view the details for that rule. Notice that in this example, the `jboss-web.xml` file matched on another rule (`JBoss web application descriptor (jboss-web.xml)`) that produced `1` story point. This story point, combined with the `1` story point from our custom rule, brings the total story points for this file to `2`. diff --git a/docs/topics/mtr-csv-export.adoc b/docs/topics/mtr-csv-export.adoc new file mode 100644 index 0000000000..f73eac308b --- /dev/null +++ b/docs/topics/mtr-csv-export.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc + +:_content-type: PROCEDURE +[id="csv-export_{context}"] += Exporting the report in CSV format + +{ProductName} ({ProductShortName}) provides the ability to export the report data, including the classifications and hints, to a flat file on your local file system. The export function currently supports the CSV file format, which presents the report data as fields separated by commas (`,`). + +The CSV file can be imported and manipulated by spreadsheet software such as Microsoft Excel, OpenOffice Calc, or LibreOffice Calc. Spreadsheet software provides the ability to sort, analyze, evaluate, and manage the result data from an {ProductShortName} report. + +[id="export-the-report_{context}"] +== Exporting the report + +ifdef::cli-guide[] +To export the report as a CSV file, run {ProductShortName} with the `--exportCSV` argument. A CSV file is created in the directory specified by the `--output` argument for each application analyzed. + +All discovered issues, spanning all the analyzed applications, are included in the `AllIssues.csv` file that is exported to the root directory of the report. +endif::cli-guide[] + +ifdef::maven-guide[] +To export the report as a CSV file, run {ProductShortName} with the `exportCSV` argument set to `true`. + +A CSV file is created in the directory specified by the `--output` argument for each application analyzed. All discovered issues, spanning all the analyzed applications, are included in `AllIssues.csv` file. + +The CSV files are exported to the directory specified by the `outputDirectory` argument. +endif::maven-guide[] + +ifdef::cli-guide[] +[discrete] +=== Accessing the report from the application report + +If you have exported the CSV report, you can download all of the CSV issues in the Issues Report. To download these issues, click *Download All Issues CSV* in the Issues Report. + +.Issues report with CSV download +image::4-1-issues-report-with-csv-download.png[Issues report with CSV download] +endif::cli-guide[] + +== Importing the CSV file into a spreadsheet program + +. Launch the spreadsheet software, for example, Microsoft Excel. +. Choose *File* -> *Open*. +. Browse to the CSV exported file and select it. +. The data is now ready to analyze in the spreadsheet software. + +== About the CSV data structure + +The CSV formatted output file contains the following data fields: + +Rule Id:: The ID of the rule that generated the given item. +Problem type:: _hint_ or _classification_ +Title:: The title of the _classification_ or _hint_. This field summarizes the issue for the given item. +Description:: The detailed description of the issue for the given item. +Links:: URLs that provide additional information about the issue. A link consists of two attributes: the link and a description of the link. +Application:: The name of the application for which this item was generated. +File Name:: The name of the file for the given item. +File Path:: The file path for the given item. +Line:: The line number of the file for the given item. +Story points:: The number of story points, which represent the level of effort, assigned to the given item. diff --git a/docs/topics/mtr-eclipse-about-plugin.adoc b/docs/topics/mtr-eclipse-about-plugin.adoc new file mode 100644 index 0000000000..8efbddd60c --- /dev/null +++ b/docs/topics/mtr-eclipse-about-plugin.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: CONCEPT +[id="eclipse-about-plugin_{context}"] += About the {PluginName} for Eclipse + +The {ProductName} ({ProductShortName}) plugin for Eclipse helps you migrate and modernize applications. + +The {PluginName} analyzes your projects using customizable rulesets, marks migration issues in the source code, provides guidance to fix the issues, and offers automatic code replacement, or Quick Fixes, if possible. + +ifdef::eclipse-code-ready-studio-guide[] +For information about a similar extension for Visual Studio Code, see the link:{ProductDocVscGuideURL}[_Visual Studio Code Extension Guide_]. +endif::[] + +ifdef::getting-started-guide[] +For more information on using the {PluginName}, see the {ProductShortName} link:{EclipseCrsGuideURL}[_{EclipseCrsGuideTitle}_]. +endif::[] diff --git a/docs/topics/mtr-eclipse-accessing-tools.adoc b/docs/topics/mtr-eclipse-accessing-tools.adoc new file mode 100644 index 0000000000..379dbcf2ca --- /dev/null +++ b/docs/topics/mtr-eclipse-accessing-tools.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-accessing-tools_{context}"] += Accessing the {ProductShortName} tools + +You can access the {PluginName} tools in the *{ProductShortName}* perspective. + +.Prerequisites + +* You must restart the Eclipse IDE after installing the {PluginName}. + +.Procedure + +. Click *Window* -> *Perspective* -> *Open Perspective* -> *Other*. +. Select *{ProductShortName}* and click *OK*. ++ +The following components are displayed: + +* *Issue Explorer* displays the migration issues identified by the {PluginName}. +* *{ProductShortName} Server* is a separate process that analyzes projects, flags migration issues, and generates reports. ++ +You can start, stop, and view the status of the {ProductShortName} server in the *Issue Explorer*. + +* *Issue Details* displays detailed information about a selected issue, including the hint, severity, and any additional resources. +* *{ProductShortName} Report* is an HTML report generated by the {PluginName}. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies. ++ +[NOTE] +==== +The report is not generated by default. You must select the *Generate Report* option in the run configuration. +==== diff --git a/docs/topics/mtr-eclipse-analyzing-projects.adoc b/docs/topics/mtr-eclipse-analyzing-projects.adoc new file mode 100644 index 0000000000..9dbf8a6a17 --- /dev/null +++ b/docs/topics/mtr-eclipse-analyzing-projects.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-analyzing-projects_{context}"] += Analyzing projects + +You can analyze your projects by running the {PluginName} with a saved run configuration. + +.Procedure + +. In the *{ProductShortName}* perspective, click the *Run* button (image:run_exc.png[Run button]) and select a run configuration. ++ +The {PluginName} analyzes your projects. The *Issue Explorer* displays migration issues that are detected with the ruleset. + +. When you have finished analyzing your projects, stop the {ProductShortName} server in the *Issue Explorer* to conserve memory. diff --git a/docs/topics/mtr-eclipse-configuring-plugin-for-cli.adoc b/docs/topics/mtr-eclipse-configuring-plugin-for-cli.adoc new file mode 100644 index 0000000000..b7193ef330 --- /dev/null +++ b/docs/topics/mtr-eclipse-configuring-plugin-for-cli.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE + +[id="eclipse-configuring-plugin-for-cli_{context}"] += Configuring the {PluginName} to use the {ProductShortName} CLI for analysis execution + +You can configure the {PluginName} to use the {ProductShortName} CLI for analysis execution. + +.Prerequisites + +* You have downloaded the {ProductShortName} CLI from the Developers Website or Customer Portal and installed it locally. + +.Procedure + +. Click the *Configure MTR* icon to open the configuration settings. +. Populate the CLI field with the path to the parent directory of the CLI. +. Click *Apply*. diff --git a/docs/topics/mtr-eclipse-configuring-run.adoc b/docs/topics/mtr-eclipse-configuring-run.adoc new file mode 100644 index 0000000000..57e5d1df34 --- /dev/null +++ b/docs/topics/mtr-eclipse-configuring-run.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-configuring-run_{context}"] += Creating a run configuration + +You can create a run configuration in the *Issue Explorer*. A run configuration specifies the project to analyze, migration path, and additional options. + +You can create multiple run configurations. Each run configuration must have a unique name. + +.Prerequisite + +* You must import your projects into the Eclipse IDE. + +.Procedure + +. In the *Issue Explorer*, click the {ProductShortName} icon (image:Product_Icon-Migration_Toolkit-RGB.png[{ProductShortName} button]) to create a run configuration. +. On the *Input* tab, complete the following fields: +.. Select a migration path. +.. Beside the *Projects* field, click *Add* and select one or more projects. +.. Beside the *Packages* field, click *Add* and select one or more the packages. ++ +[NOTE] +==== +Specifying the packages for analysis reduces the run time. If you do not select any packages, all packages in the project are scanned. +==== + +. On the *Options* tab, you can select *Generate Report* to generate an HTML report. The report is displayed in the *Report* tab and saved as a file. ++ +Other options are displayed. See link:{ProductDocUserGuideURL}#cli-args_cli-guide[About {ProductShortName} command-line arguments] in the _{UserCLIBookName}_ for details. + +. On the *Rules* tab, you can select custom rulesets that you have imported or created for the {PluginName}. +. Click *Run* to start the analysis. diff --git a/docs/topics/mtr-eclipse-creating-custom-ruleset.adoc b/docs/topics/mtr-eclipse-creating-custom-ruleset.adoc new file mode 100644 index 0000000000..acfae9d2bc --- /dev/null +++ b/docs/topics/mtr-eclipse-creating-custom-ruleset.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-creating-custom-ruleset_{context}"] += Creating a custom ruleset + +You can create a custom ruleset in the *{ProductShortName}* perspective. + +See the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_] to learn more about creating custom XML rules. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Create Ruleset icon (image:repository-new.gif[Create ruleset icon]). +. Select a project and a directory for the ruleset. +. Enter the file name. ++ +[NOTE] +==== +The file must have the extension `.windup.xml`. +==== + +. Enter a ruleset ID, for example, `my-ruleset-id`. +. Optional: Select *Generate quickstart template* to add basic rule templates to the file. +. Click *Finish*. +. The ruleset file opens in an editor and you can add and edit rules in the file. +. Click the *Source* tab to edit the XML source of the ruleset file. + +You can select the new ruleset when you create a run configuration. diff --git a/docs/topics/mtr-eclipse-importing-custom-ruleset.adoc b/docs/topics/mtr-eclipse-importing-custom-ruleset.adoc new file mode 100644 index 0000000000..02b2aab0e5 --- /dev/null +++ b/docs/topics/mtr-eclipse-importing-custom-ruleset.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-importing-custom-ruleset_{context}"] += Importing a custom ruleset + +You can import a custom ruleset into the {PluginName} to analyze your projects. + +.Prerequisites + +* Custom ruleset file with a `.windup.xml` extension. ++ +See the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_] for information about creating rulesets. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Import Ruleset icon (image:import-repository.png[Import ruleset icon]). +. Browse to and select the XML rule file to import. ++ +The custom ruleset is displayed when you expand *Custom* on the *Rulesets* tab. diff --git a/docs/topics/mtr-eclipse-installing-plugin.adoc b/docs/topics/mtr-eclipse-installing-plugin.adoc new file mode 100644 index 0000000000..6442cafe5c --- /dev/null +++ b/docs/topics/mtr-eclipse-installing-plugin.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE + +[id="eclipse-installing-plugin_{context}"] += Installing in a connected environment + +You need a connected environment to install the {PluginName}. + +The {PluginName} has been tested with the Eclipse IDE for Java Enterprise Developers 2023-03. + +.Prerequisites + +include::snippet_jdk-hardware-mac-prerequisites.adoc[leveloffset=0] + +* link:https://www.eclipse.org/downloads/packages/release/2023-03/r/eclipse-ide-java-developers[Eclipse IDE for Java Enterprise Developers 2023-03] +* JBoss Tools, installed from the link:https://marketplace.eclipse.org/content/jboss-tools[Eclipse Marketplace] +* link:http://download.eclipse.org/mylyn/releases/latest[Mylyn SDK and frameworks], installed with Eclipse + +[NOTE] +==== +Eclipse is pre-configured for Java 17, and the plugin operates directly with Java 17. + +You can also run the plugin with Java 11, which requires setting the JRE version to Java 11 when creating up a new Eclipse project or importing an existing one. See step 6 below. +==== + +.Procedure + +. Launch Eclipse. +. From the menu bar, select *Help* -> *Install New Software*. +. Next to the *Work with* field, click *Add*. +. In the *Name* field, enter `{ProductShortName}`. +. In the *Location* field, enter +ifdef::mtr[] +`https://marketplace.eclipse.org/content/migration-toolkit-runtimes-mtr` and click *OK*. +endif::[] +ifdef::mta[] +`https://marketplace.eclipse.org/content/migration-toolkit-applications-mta` and click *OK*. +endif::[] +. Select the Java version to use. +** If using Java 11, in the *JRE* list, select *JavaSE 11*. +** If using Java 17, leave the *JRE* selection unchanged. + +[start=7] +. Select all the *JBoss Tools - {ProductShortName}* check boxes and click *Next*. +. Review the installation details and click *Next*. +. Accept the terms of the license agreement and click *Finish*. +. Restart Eclipse. diff --git a/docs/topics/mtr-eclipse-resolving-issues.adoc b/docs/topics/mtr-eclipse-resolving-issues.adoc new file mode 100644 index 0000000000..98f3faca57 --- /dev/null +++ b/docs/topics/mtr-eclipse-resolving-issues.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-resolving-issues_{context}"] += Resolving issues + +You can resolve issues detected by the {PluginName} by performing one of the following actions: + +* You can double-click the issue to open it in an editor and edit the source code. ++ +The issue displays a Stale icon (image:stale_issue.gif[Stale]) until the next time you run the {PluginName}. +* You can right-click the issue and select *Mark as Fixed*. +* If the issue displays a Quick Fix icon (image:quickfix_error.png[Mandatory with quick fix] image:quickfix_info.png[Optional with quick fix] image:quickfix_warning.png[Warning with quick fix]), you can right-click the issue and select *Preview Quick Fix* and then *Apply Quick Fix*. diff --git a/docs/topics/mtr-eclipse-reviewing-issues.adoc b/docs/topics/mtr-eclipse-reviewing-issues.adoc new file mode 100644 index 0000000000..02f828e265 --- /dev/null +++ b/docs/topics/mtr-eclipse-reviewing-issues.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-reviewing-issues_{context}"] += Reviewing issues + +You can review issues identified by the {PluginName}. + +.Procedure + +. Click *Window* -> *Show View* -> *Issue Explorer*. +. Optional: Filter the issues by clicking the Options menu {kebab}, selecting *Group By* and an option. ++ +image::mta_group_by.png[Issue Explorer "Group By" options] + +. Right-click and select *Issue Details* to view information about the issue, including its severity and how to address it. ++ +The following icons indicate the severity and state of an issue: ++ +.Issue icons +[cols="20%a,80%",options="header",] +|==== +|Icon |Description +|image::error.png[Mandatory] |The issue must be fixed for a successful migration. +|image::info.gif[Optional] |The issue is optional to fix for migration. +|image::warning.png[Warning] |The issue might need to be addressed during migration. +|image::fixedIssue.gif[Resolved] |The issue was resolved. +|image::stale_issue.gif[Stale] |The issue is stale. The code marked as an issue was modified since the last time that {ProductShortName} identified it as an issue. +|image::quickfix_error.png[Mandatory with quick fix] |A quick fix is available for this issue, which is mandatory to fix for a successful migration. +|image::quickfix_info.png[Optional with quick fix] |A quick fix is available for this issue, which is optional to fix for migration. +|image::quickfix_warning.png[Warning with quick fix] |A quick fix is available for this issue, which may potentially be an issue during migration. +|==== + +. Double-click an issue to open the associated line of code in an editor. diff --git a/docs/topics/mtr-eclipse-submit-ruleset.adoc b/docs/topics/mtr-eclipse-submit-ruleset.adoc new file mode 100644 index 0000000000..74216132ab --- /dev/null +++ b/docs/topics/mtr-eclipse-submit-ruleset.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-submitting-ruleset_{context}"] += Submitting a custom ruleset + +You can submit your custom ruleset for inclusion in the official {ProductShortName} rule repository. This allows your custom rules to be reviewed and included in subsequent releases of {ProductShortName}. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Arrow icon (image:plugin-dropdown.png[Dropdown]) and select *Submit Ruleset*. +. Complete the following fields: + +* *Summary*: Describe the purpose of the rule. This becomes the title of the submission. +* *Code Sample*: Enter an example of the source code that the rule should run against. +* *Description*: Enter a brief description of the rule. + +. Click *Choose Files* and select the ruleset file. +. Click *Submit*. diff --git a/docs/topics/mtr-eclipse-submitting-ruleset.adoc b/docs/topics/mtr-eclipse-submitting-ruleset.adoc new file mode 100644 index 0000000000..74216132ab --- /dev/null +++ b/docs/topics/mtr-eclipse-submitting-ruleset.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-submitting-ruleset_{context}"] += Submitting a custom ruleset + +You can submit your custom ruleset for inclusion in the official {ProductShortName} rule repository. This allows your custom rules to be reviewed and included in subsequent releases of {ProductShortName}. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Arrow icon (image:plugin-dropdown.png[Dropdown]) and select *Submit Ruleset*. +. Complete the following fields: + +* *Summary*: Describe the purpose of the rule. This becomes the title of the submission. +* *Code Sample*: Enter an example of the source code that the rule should run against. +* *Description*: Enter a brief description of the rule. + +. Click *Choose Files* and select the ruleset file. +. Click *Submit*. diff --git a/docs/topics/mtr-eclipse-viewing-rules.adoc b/docs/topics/mtr-eclipse-viewing-rules.adoc new file mode 100644 index 0000000000..49e8a1690f --- /dev/null +++ b/docs/topics/mtr-eclipse-viewing-rules.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="plugin-viewing-rules_{context}"] += Viewing rules + +You can view system and custom rules, if any, for the {PluginName}. + +.Prerequisites + +* To view system rules, the {ProductShortName} server must be running. + +.Procedure + +. Click the *Rulesets* tab. +. Expand *System* to view system rulesets or *Custom* to view custom rulesets. +. Expand a ruleset. +. Double-click a rule to open it in a viewer. +. Click the *Source* tab to view the XML source of the rule. diff --git a/docs/topics/mtr-exclude-files-and-packages.adoc b/docs/topics/mtr-exclude-files-and-packages.adoc new file mode 100644 index 0000000000..da001c4b9a --- /dev/null +++ b/docs/topics/mtr-exclude-files-and-packages.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="exclude-files-and-packages_{context}"] += Configuring {ProductShortName} to exclude packages and files + +[id="exclude-packages_{context}"] +== Excluding packages + +You can exclude packages during decompilation and analysis to increase performance. References to these packages remain in the application's source code but excluding them avoids the decompilation and analysis of proprietary classes. + +Any packages that match the defined value are excluded. For example, you can use `com.acme` to exclude both `com.acme.example` and `com.acme.roadrunner`. + +You can exclude packages by either of the following methods: + +* Using the `--excludePackages` argument. +* Specifying the packages in a file contained within one of the ignored locations. Each package should be included on a separate line, and the file must end in `.package-ignore.txt`. For example, see `<{ProductShortName}_HOME>/ignore/proprietary.package-ignore.txt`. + +[id="exclude-files_{context}"] +== Excluding files + +{ProductShortName} can exclude specific files, such as included libraries or dependencies, during scanning and report generation. Excluded files are defined in a file with the `.{LC_PSN}-ignore.txt` or `.windup-ignore.txt` extension within one of the ignored locations. + +These files contain a regex string detailing the name to exclude, with one file listed per line. For example, you can exclude the library `ant.jar` and any Java source files beginning with `Example` with a file containing the following: + +---- +.*ant.jar +.*Example.*\.java +---- + +[id="ignored-locations_{context}"] +== Searching locations for exclusion + +{ProductShortName} searches the following locations: + +* `~/.{LC_PSN}/ignore/` +* `~/.windup/ignore/` +* `<{ProductShortName}_HOME>/ignore/` +* Any files and folders specified by the `--userIgnorePath` argument + +Each of these files must conform to the rules specified for excluding packages or files, depending on the type of content to be excluded. diff --git a/docs/topics/mtr-features.adoc b/docs/topics/mtr-features.adoc new file mode 100644 index 0000000000..7bf0626270 --- /dev/null +++ b/docs/topics/mtr-features.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="features_{context}"] += {ProductShortName} Features + +The {ProductName} ({ProductShortName}) provides a number of capabilities to assist with planning and executing migration projects. + +Planning and work estimation:: +{ProductShortName} assists project managers by detailing the type of work and estimation of effort to complete the tasks. Level of effort is represented in {ProductShortName} reports as story points. Actual estimates will be based on the skills required and the classification of migration work needed. + +Identifying migration issues and providing solutions:: +{ProductShortName} identifies migration issues and highlights specific points in the code where an issue occurs. {ProductShortName} suggests code changes and provides additional resources to help engineers resolve the specific issue. + +Detailed reporting:: +{ProductShortName} produces numerous reports to give both high-level views of the migration effort and details of specific migration tasks. You can view migration issues across all applications, charts and summary information about issues in an application, a breakdown of issues by module in the application, reports of technologies used, and dependencies on other applications and services. You can also examine source files to see the line of code where an issue occurs. See the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for more information on the available {ProductShortName} reports. + +Built-in rules and migration paths:: +{ProductShortName} comes with a core set of rules to provide migration assistance for several common migration paths. These rules identify the use of proprietary functionality from other application servers or deprecated subsystems from previous versions of JBoss EAP. {ProductShortName} also contains rules to identify common migration issues, such as hard-coded IP addresses and JNDI lookups. + +Rule extensibility and customization:: +{ProductShortName} provides the ability to create powerful and complex rules. You can expand upon the core set of rules provided by {ProductShortName} and create rules to identify additional issues that are important for your migration project. You can also override core rules and create custom rule categories. See the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_] for more information on customizing {ProductShortName} rules. + +Ability to analyze source code or application archives:: +{ProductShortName} can evaluate application archives or source code, and can evaluate multiple applications together. It can identify archives that are shared across multiple applications, which can help with more accurate effort estimation. diff --git a/docs/topics/mtr-fork-ruleset-repo.adoc b/docs/topics/mtr-fork-ruleset-repo.adoc new file mode 100644 index 0000000000..bf4ef9abbe --- /dev/null +++ b/docs/topics/mtr-fork-ruleset-repo.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="fork-ruleset-repo_{context}"] += Forking and cloning the {ProductName} XML rules + +The {ProductName} `windup-rulesets` repository provides working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. + +You must have the link:http://git-scm.com/[`git`] client installed on your machine. + +. Click the `Fork` link on the https://github.com/windup/windup-rulesets/[{ProductName} Rulesets] GitHub page to create the project in your own Git. The forked GitHub repository URL created by the fork should look like this: `\https://github.com//windup-rulesets.git`. +. Clone your {ProductName} rulesets repository to your local file system: ++ +[options="nowrap",subs="attributes+"] +---- +$ git clone https://github.com//windup-rulesets.git +---- +. This creates and populates a `windup-rulesets` directory on your local file system. Navigate to the newly created directory, for example ++ +[options="nowrap"] +---- +$ cd windup-rulesets/ +---- +. If you want to be able to retrieve the latest code updates, add the remote `upstream` repository so you can fetch any changes to the original forked repository. ++ +[options="nowrap"] +---- +$ git remote add upstream https://github.com/windup/windup-rulesets.git +---- +. Get the latest files from the `upstream` repository. ++ +[options="nowrap"] +---- +$ git fetch upstream +---- diff --git a/docs/topics/mtr-get-involved.adoc b/docs/topics/mtr-get-involved.adoc new file mode 100644 index 0000000000..3552b3a10d --- /dev/null +++ b/docs/topics/mtr-get-involved.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc + +:_content-type: CONCEPT +[id="get-involved_{context}"] += Getting involved + +To help the {ProductName} cover most application constructs and server configurations, including yours, you can help with any of the following items. + +* Send an email to jboss-migration-feedback@redhat.com and let us know what {ProductShortName} migration rules should cover. +* Provide example applications to test migration rules. +* Identify application components and problem areas that may be difficult to migrate. +** Write a short description of these problem migration areas. +** Write a brief overview describing how to solve the problem in migration areas. +* Try {ProductName} on your application. Be sure to report any issues you encounter. +* Contribute to the {ProductName} rules repository. +** Write a {ProductName} rule to identify or automate a migration process. +** Create a test for the new rule. +** Details are provided in the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_]. +* Contribute to the project source code. +** Create a core rule. +** Improve {ProductShortName} performance or efficiency. + +Any level of involvement is greatly appreciated! diff --git a/docs/topics/mtr-getting-started-rules.adoc b/docs/topics/mtr-getting-started-rules.adoc new file mode 100644 index 0000000000..4d07bb6814 --- /dev/null +++ b/docs/topics/mtr-getting-started-rules.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="getting-started-rules_{context}"] += Getting started with rules + +You can get started creating custom {ProductShortName} rules by creating a rule or by reviewing the quickstarts. diff --git a/docs/topics/mtr-important-links.adoc b/docs/topics/mtr-important-links.adoc new file mode 100644 index 0000000000..593b1328ff --- /dev/null +++ b/docs/topics/mtr-important-links.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc + +:_content-type: REFERENCE +[id="important-links_{context}"] += Resources + +* {ProductShortName} forums: https://developer.jboss.org/en/windup +* Jira issue tracker: {JiraWindupURL} +* {ProductShortName} mailing list: jboss-migration-feedback@redhat.com diff --git a/docs/topics/mtr-installing-intellij-idea-plugin.adoc b/docs/topics/mtr-installing-intellij-idea-plugin.adoc new file mode 100644 index 0000000000..f865f94a26 --- /dev/null +++ b/docs/topics/mtr-installing-intellij-idea-plugin.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +:_content-type: PROCEDURE +[id="intellij-idea-plugin-extension_{context}"] += Installing the {ProductShortName} plugin for IntelliJ IDEA + +You can install the {ProductShortName} plugin in the Ultimate and the Community Edition releases of IntelliJ IDEA. + +.Prerequisites +include::snippet_jdk-hardware-mac-prerequisites.adoc[] + +* The latest version of `{LC_PSN}-cli` from the link:{DevDownloadPageURL}[{ProductShortName} download page] + +.Procedure + +. In IntelliJ IDEA, click the *Plugins* tab on the Welcome screen. +. Enter `{ProductName}` in the Search field on the *Marketplace* tab. +. Select the *{ProductName} ({ProductShortName}) by Red Hat* plugin and click *Install*. ++ +The plugin is listed on the *Installed* tab. diff --git a/docs/topics/mtr-installing-plugin.adoc b/docs/topics/mtr-installing-plugin.adoc new file mode 100644 index 0000000000..6442cafe5c --- /dev/null +++ b/docs/topics/mtr-installing-plugin.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE + +[id="eclipse-installing-plugin_{context}"] += Installing in a connected environment + +You need a connected environment to install the {PluginName}. + +The {PluginName} has been tested with the Eclipse IDE for Java Enterprise Developers 2023-03. + +.Prerequisites + +include::snippet_jdk-hardware-mac-prerequisites.adoc[leveloffset=0] + +* link:https://www.eclipse.org/downloads/packages/release/2023-03/r/eclipse-ide-java-developers[Eclipse IDE for Java Enterprise Developers 2023-03] +* JBoss Tools, installed from the link:https://marketplace.eclipse.org/content/jboss-tools[Eclipse Marketplace] +* link:http://download.eclipse.org/mylyn/releases/latest[Mylyn SDK and frameworks], installed with Eclipse + +[NOTE] +==== +Eclipse is pre-configured for Java 17, and the plugin operates directly with Java 17. + +You can also run the plugin with Java 11, which requires setting the JRE version to Java 11 when creating up a new Eclipse project or importing an existing one. See step 6 below. +==== + +.Procedure + +. Launch Eclipse. +. From the menu bar, select *Help* -> *Install New Software*. +. Next to the *Work with* field, click *Add*. +. In the *Name* field, enter `{ProductShortName}`. +. In the *Location* field, enter +ifdef::mtr[] +`https://marketplace.eclipse.org/content/migration-toolkit-runtimes-mtr` and click *OK*. +endif::[] +ifdef::mta[] +`https://marketplace.eclipse.org/content/migration-toolkit-applications-mta` and click *OK*. +endif::[] +. Select the Java version to use. +** If using Java 11, in the *JRE* list, select *JavaSE 11*. +** If using Java 17, leave the *JRE* selection unchanged. + +[start=7] +. Select all the *JBoss Tools - {ProductShortName}* check boxes and click *Next*. +. Review the installation details and click *Next*. +. Accept the terms of the license agreement and click *Finish*. +. Restart Eclipse. diff --git a/docs/topics/mtr-installing-vs-code-extension.adoc b/docs/topics/mtr-installing-vs-code-extension.adoc new file mode 100644 index 0000000000..0b10fd0496 --- /dev/null +++ b/docs/topics/mtr-installing-vs-code-extension.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="installing-vs-code-extension_{context}"] += Installing the {ProductShortName} extension for Visual Studio Code + +You can install the {ProductShortName} extension for Visual Studio Code (VS Code). + +.Prerequisites +include::snippet_jdk-hardware-mac-prerequisites.adoc[] + +.Procedure + +. Set the environmental variable `JAVA_HOME`: ++ +[source, terminal,subs="attributes+"] +---- +$ export JAVA_HOME=jdk11 +---- + +. In VS Code, click the *Extensions* icon on the Activity bar to open the *Extensions* view. +. Enter `{ProductName}` in the Search field. +. Select the *{ProductName}* extension and click *Install*. ++ +The {ProductShortName} extension icon (image:vs_extension_icon.png[{ProductShortName} code extension]) is displayed on the Activity bar. diff --git a/docs/topics/mtr-installing-web-console-on-openshift.adoc b/docs/topics/mtr-installing-web-console-on-openshift.adoc new file mode 100644 index 0000000000..fd9f937c6a --- /dev/null +++ b/docs/topics/mtr-installing-web-console-on-openshift.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="installing-web-console-on-openshift_{context}"] += Installing the {WebName} on {ocp-short} 4.11 and later + +You can install the {WebName} on {ocp-short} 4.11 and later versions with the {ProductName} Operator. + +.Prerequisites + +* 6 vCPUs, 8 GB RAM, and 40 GB persistent storage. +* One or more projects in which you can install the {WebName}. ++ +[IMPORTANT] +==== +Do not install the {WebName} in a default project. +==== + +* `cluster-admin` privileges to install the {DocInfoProductName} Operator. +* `project-admin-user` privileges to install the {WebName} application in a project. + +.Configuring Red Hat Single Sign-on (SSO) + +You must decide at installation time whether the {WebName} requires authentication. If it does, you must first install and configure Red Hat SSO and input some RH SSO settings when instantiating the MTR Operator. + +[NOTE] +==== +Authentication can not be added or removed after installation. +==== + +. Open the Red Hat SSO administration console. +. Add a realm named *windup*. +. In the realm, create a client named *windup-web*. +. Check that *Access Type* is set to `public`. Set *Valid Redirect URIs* and *Web Origins* to `\*`. Click *Save*. ++ +Note that after the {ProductShortName} operator has been instantiated, the *Valid Redirect URIs* and *Web Origins* fields have to be set to the secure-mtr-web-console route. +. Create a role named *user*. +. Create a user with any name. +. Set the credentials of the user, disable *Temporary*, and assign the role "user" to the user. + +.Installing the {ProductShortName} Operator + +. Log in to the OpenShift web console as a user with `cluster-admin` privileges. +. Click *Operators* -> *OperatorHub*. +. Use the *Search by keyword* field to locate the *{DocInfoProductName}* Operator. +. Click *Install*. +. Select a project from the *Installed Namespace* list and click *Install*. +. Click *Operators* -> *Installed Operators* to verify that the Operator is installed. + +.Installing the {WebName} application + +. Log in to the OpenShift web console as a user with `project-admin-user` privileges. +. Switch to the *Migration* perspective and click *+Add*. +. In the *Add* view, click *Operator Backed*. +. Click the *{DocInfoProductName}* Operator. +. Click *Create*. +. Review the application settings. If the {WebName} requires authentication, input the RH SSO settings and click *Create*. +. In the *Topology* view, click the `mtr-web-console` application and then click the *Resources* tab. +. If authentication is required, set the RH SSO *Valid Redirect URIs* and *Web Origins* fields to the secure-mtr-web-console route. +. Click the `secure-mtr-web-console` route to open the {WebName} in a new browser window. diff --git a/docs/topics/mtr-installing-web-console-or-cli-tool.adoc b/docs/topics/mtr-installing-web-console-or-cli-tool.adoc new file mode 100644 index 0000000000..7a5ae48a0f --- /dev/null +++ b/docs/topics/mtr-installing-web-console-or-cli-tool.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +ifdef::cli-guide[] +[id="installing-web-console-or-cli-tool_{context}"] += Installing the {CLINameTitle} + +You can install the {CLINameTitle} on Linux, Windows, or macOS operating systems. +endif::[] +ifdef::web-console-guide[] + +[id="installing-web-console-linux-win-mac_{context}"] += Installing the {WebName} on Linux, Windows, or macOS + +You can install the {WebName} on Linux, Windows, or macOS operating systems and access the {WebName} in a browser. + +The {WebName} has been tested with Chrome and Firefox. +endif::[] + +.Prerequisites +include::snippet_jdk-hardware-mac-prerequisites.adoc[] + +.Procedure + +ifdef::cli-guide[] +. Navigate to the link:{DevDownloadPageURL}[{ProductShortName} Download page] and download the `Migration Toolkit CLI` file. +endif::[] +ifdef::web-console-guide[] +. Navigate to the link:{DevDownloadPageURL}[{ProductShortName} Download page] and download the {WebName} `Local install & OpenShift` file. +endif::[] + +. Extract the `.zip` file to a directory of your choice. ++ +[NOTE] +==== +If you are installing on a Windows operating system: + +. Extract the `.zip` file to a folder named `LC_PSN` to avoid a `Path too long` error. Alternatively, extract the file with link:https://www.7-zip.org/download.html[7-Zip] to a folder of any name you choose. +. If a *Confirm file replace* window is displayed during extraction, click *Yes to all*. +==== ++ +When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation. + + +ifdef::web-console-guide[] +. By default, no authentication is required. If you wish to enable authentication, do this before starting the web console. +. Start the {WebName}: + +* Linux or macOS operating system: ++ +[source,terminal,subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/run_windup.sh +---- + +* Windows operating system: ++ +[source,terminal,subs="attributes+"] +---- +C:\<{ProductShortName}_HOME>\run_windup.bat +---- ++ +. Open a browser and navigate to `\http://localhost:8080/windup-ui`. ++ +If authentication is not configured, the Projects screen is displayed in your browser. ++ +.{ProductShortName} Projects screen +image::mtr_web_console.png[web console projects screen] +endif::[] diff --git a/docs/topics/mtr-intellij-idea-plugin-resolving-issues.adoc b/docs/topics/mtr-intellij-idea-plugin-resolving-issues.adoc new file mode 100644 index 0000000000..8e26f9ba0e --- /dev/null +++ b/docs/topics/mtr-intellij-idea-plugin-resolving-issues.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-resolving-issues_{context}"] += Resolving issues + +You can resolve issues by doing one of the following: + +* Using a _Quick Fix_ to fix a code snippet that has a hint +* Editing the code of a file that appears in a classification + +== Using a Quick Fix + +You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. Quick Fixes are available for many issues displayed in the *Hints* section of the *Results* directory. + +.Procedure + +. In the left pane, click a hint that has an error indicator. ++ +Any Quick Fixes are displayed as child folders with the Quick Fix icon (image:intellij-idea-info.png[Quickfix]) on their left side. +. Right-click a Quick Fix and select *Preview Quick Fix*. ++ +The current code and the suggested change are displayed in the *Preview Quick Fix* window. +. To accept the suggested fix, click *Apply Quick Fix*. +. Optional: Right-click the issue and select *Mark As Complete*. ++ +A green check (image:intellij-idea-ok.png[Complete]) is displayed by the hint, replacing the error indicator. + +== Editing the code of a file + +You can directly edit a file displayed in the *Classifications* section of the *Results* directory. These files do not have any Quick Fixes. + +.Procedure + +. In the left pane, click the file you want to edit. +. Make any changes needed to the code and save the file. +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. ++ +If you select *Mark as Complete*, a green check (image:intellij-idea-ok.png[Complete]) is displayed by the hint, replacing the error indicator. diff --git a/docs/topics/mtr-intellij-idea-plugin-reviewing-issues.adoc b/docs/topics/mtr-intellij-idea-plugin-reviewing-issues.adoc new file mode 100644 index 0000000000..ee8359d40e --- /dev/null +++ b/docs/topics/mtr-intellij-idea-plugin-reviewing-issues.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-reviewing-issues_{context}"] += Reviewing issues + +You can use the {ProductShortName} plugin icons to prioritize issues based on their severity. You can see which issues have a _Quick Fix_ automatic code replacement and which do not. + +The results of an analysis are displayed in a directory format, showing the _hints_ and _classifications_ for each application analyzed. + +A _hint_ is a read-only snippet of code that contains a single issue that you should or must address before you can modernize or migrate an application. Often a Quick Fix is suggested, which you can accept or ignore. + +A _classification_ is a file that has an issue but does not have any suggested Quick Fixes. You can edit a classification. + +.Procedure + +. In the {ProductName} view, select a run configuration directory in the left pane. ++ +. Click *Results*. ++ +The modules and applications of the run configuration are displayed, with hints and classifications beneath each application. + +. Prioritize issues based on the following icons, which are displayed next to each hint: + +** image:intellij-idea-mandatory.png[Mandatory] : You must fix this issue in order to migrate or modernize the application. +** image:intellij-idea-potential.png[Warning] : You might need to fix this issue in order to migrate or modernize the application + +. Optional: To learn more about a hint, right-click it and select *Show More Details*. diff --git a/docs/topics/mtr-intellij-idea-plugin-run-configuration.adoc b/docs/topics/mtr-intellij-idea-plugin-run-configuration.adoc new file mode 100644 index 0000000000..d55317f083 --- /dev/null +++ b/docs/topics/mtr-intellij-idea-plugin-run-configuration.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-run-configuration_{context}"] += Creating a run configuration + +You can create multiple run configurations to run against each project you import to IntelliJ IDEA. + +.Procedure + +. In the *Projects* view, click the project you want to analyze. +. On the left side of the screen, click the *{ProductName}* tab. ++ +If this is your first configuration, the run configuration panel is displayed on the right. + +. If this is not your first configuration, right-click configuration in the list and select *New configuration*. ++ +The run configuration panel is displayed on the right. + +. Complete the following configuration fields: + +** *cli*: Enter the path to the cli executable. For example: `$HOME/{LC_PSN}-cli-{ProductDistributionVersion}/bin/windup-cli`. +** *Input*: Click *Add* and enter the input file or directory. +** *Target*: Select one or more target migration paths. ++ +[NOTE] +==== +The location shown in the *Output* is set by the plugin. +==== + +. In the list of configurations, right-click the new configuration and select *Run Analysis*. ++ +The *Console ({ProductShortName})* terminal emulator opens, displaying information about the progress of the analysis. ++ +When the analysis is completed, you can click either *Report* or *Results* below the name of the configuration file you ran. + +** *Reports* opens the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. + +** *Results* opens a directory displaying hints (issues) per application. diff --git a/docs/topics/mtr-manually-test-rules.adoc b/docs/topics/mtr-manually-test-rules.adoc new file mode 100644 index 0000000000..64a13377e1 --- /dev/null +++ b/docs/topics/mtr-manually-test-rules.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="manually-test-rules_{context}"] += Manually testing an XML rule + +You can run an XML rule against your application file to test it: + +[source,terminal,subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/bin/windup-cli [--sourceMode] --input --output --target --packages +---- + +You should see the following result: + +[options="nowrap",subs="attributes+"] +---- +Report created: /index.html + Access it at this URL: file:////index.html +---- + +More examples of how to run {ProductShortName} are located in the {ProductName} {ProductDocUserGuideURL}[_{UserCLIBookName}_]. diff --git a/docs/topics/mtr-maven-access-reports.adoc b/docs/topics/mtr-maven-access-reports.adoc new file mode 100644 index 0000000000..363569dbe2 --- /dev/null +++ b/docs/topics/mtr-maven-access-reports.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: REFERENCE +[id="maven-access-reports_{context}"] += Accessing the report + +When you run {ProductName}, the report is generated in the `OUTPUT_REPORT_DIRECTORY` that you specify using the `outputDirectory` argument in the `pom.xml`. Upon completion of the build, you will see the following message in the build log. + +[options="nowrap",subs="attributes+"] +---- +Windup report created: /index.html +---- + +The output directory contains the following files and subdirectories: + +[options="nowrap",subs="attributes+"] +---- +/ +├── index.html // Landing page for the report +├── .csv // Optional export of data in CSV format +├── graph/ // Generated graphs used for indexing +├── reports/ // Generated HTML reports +├── stats/ // Performance statistics +---- + +See the link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] section of the {ProductShortName} _{UserCLIBookName}_ for information on the {ProductShortName} reports and how to use them to assess your migration or modernization effort. diff --git a/docs/topics/mtr-maven-arguments.adoc b/docs/topics/mtr-maven-arguments.adoc new file mode 100644 index 0000000000..e219729b4c --- /dev/null +++ b/docs/topics/mtr-maven-arguments.adoc @@ -0,0 +1,189 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: REFERENCE +[id="maven-arguments_{context}"] += About {MavenNameTitle} arguments + +The following is a detailed description of the available {ProductShortName} {MavenName} arguments. + +.{ProductShortName} {MavenName} arguments +[cols="40%,60%a",options="header"] +|==== +|Argument |Description +|analyzeKnownLibraries | Flag to analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code. + +[NOTE] +==== +This option may result in a longer execution time and a large number of migration issues being reported. +==== + +|customLoggingPropertiesFile |An absolute path to a `logging.properties` file that contains a `java.util.logging.LogManager` logging configuration. If the specified path is invalid, or the option is not specified, then the logging reverts to using the `logging.properties` file included with the {MavenName}. +|disableTattletale | Flag to disable generation of the Tattletale report. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored, and the Tattletale report will still be generated. +|enableCompatibleFilesReport |Flag to enable generation of the Compatible Files report. Due to processing all files without found issues, this report may take a long time for large applications. +|enableTattletale |Flag to enable generation of a Tattletale report for each application. This option is enabled by default when `eap` is in the included target. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored, and the Tattletale report will still be generated. +|enableTransactionAnalysis |[Technology Preview] Flag to enable generation of a Transactions report that displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks such as Hibernate. + +[NOTE] +==== +enableTransactionAnalysis is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them +in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +==== + +|excludePackages |A list of packages to exclude from evaluation. For example, entering "com.mycompany.commonutilities" would exclude all classes whose package name begins with "com.mycompany.commonutilities". +|excludeTags |A list of tags to exclude. When specified, rules with these tags will not be processed. +|explodedApps |Flag to indicate that the provided input directory contains source files for a single application. +|exportCSV |Flag to export the report data to a CSV file on your local file system. {ProductShortName} creates the file in the directory specified by the `outputDirectory` argument. The CSV file can be imported into a spreadsheet program for data manipulation and analysis. +|includeTags |A list of tags to use. When specified, only rules with these tags will be processed. +|inputDirectory |Specify the path to the directory containing the applications to be analyzed. This argument defaults to `{project.basedir}/src/main/`. +|keepWorkDirs |Flag to instruct {ProductShortName} to not delete temporary working files, such as the graph database and unzipped archives. This is useful for debugging purposes. +|legacyReports |Flag to instruct {ProductShortName} to generate the old format reports instead of the new format reports. +|packages |A list of the packages to be evaluated by {ProductShortName}. This argument is required. +|offlineMode |Flag to operate in offline mode, disabling network access features, such as scheme validation. Used to improve performance. +|outputDirectory |Specify the path to the directory to output the report information generated by {ProductShortName}. This argument defaults to `{project.build.directory}/windup-report`. +|overwrite |Flag to force delete the existing output directory specified by `outputDirectory`. Defaults to `true`. + +[WARNING] +==== +Be careful not to specify a report output directory that contains important information! +==== + +|sourceTechnologies |A list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `targetTechnologies` argument, helps to determine which rulesets are used. +|sourceMode |Flag to indicate that the application to be evaluated contains source files rather than compiled binaries. Defaults to `true`. +|targetTechnologies |A list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `sourceTechnologies` argument, helps to determine which rulesets are used. +|userIgnorePath |Specify a location for {ProductShortName} to identify files that should be ignored. +|userRulesDirectory |Specify a location for {ProductShortName} to look for custom {ProductShortName} rules. The value can be a directory containing ruleset files or a single ruleset file. The ruleset files must use the [x-]`.windup.xml` suffix. +|windupHome |An optional argument that points to the root of an extracted {ProductShortName} {CLIName}. By referencing a local installation of the {CLIName}, the {MavenName} has direct access to all of the indexes, resulting in a performance increase. +|windupVersion |Specify the version of {ProductShortName} to run. By default, this is the {MavenName}'s build version. +|==== + +[id="maven-input-argument_{context}"] +== Specifying the input directory + +A path to the file or directory containing one or more applications to be analyzed. This defaults to `{project.basedir}/src/main/`. + +.Usage + +[source,xml,subs="attributes+"] +---- + + + +---- + +[id="maven-input-file-type-arguments_{context}"] +== Evaluating an input file + +Depending on whether the input file type provided to the `inputDirectory` argument is a file or directory, it will be evaluated as follows depending on the additional arguments provided. + +Directory:: ++ +[cols="1,1,1",options="header"] +|==== +| --explodedApp +| --sourceMode +| Neither Argument + +| The directory is evaluated as a single application. +| The directory is evaluated as a single application. +| Each subdirectory is evaluated as an application. +|==== + +File:: ++ +[cols="1,1,1",options="header"] +|==== +| --explodedApp +| --sourceMode +| Neither Argument + +| Argument is ignored; the file is evaluated as a single application. +| The file is evaluated as a compressed project. +| The file is evaluated as a single application. +|==== + +[id="maven-output-argument_{context}"] +== Specifying the output directory + +Specify the path to the directory to output the report information generated by {ProductShortName}. + +.Usage +[source,xml,subs="attributes+"] +---- + + + +---- + +* If omitted, the report will be generated in the `{project.build.directory}/windup-report` directory. +* If the output directory exists, it will be overwritten based on the value of the `overwrite` argument. This argument defaults to `true`, and causes {ProductShortName} to delete and recreate the directory. + +[id="maven-source-argument_{context}"] +== Setting the source technology + +A list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `targetTechnologies` argument, helps to determine which rulesets are used. + +.Usage +[source,xml,subs="attributes+"] +---- + + eap:6 + +---- + +The `sourceTechnologies` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `eap:5`. + +[id="maven-target-argument_{context}"] +== Setting the target argument + +A list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `sourceTechnologies` argument, helps to determine which rulesets are used. This argument is required + +.Usage +[source,xml,subs="attributes+"] +---- + + eap:7 + +---- + +The `targetTechnologies` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven Version Range Specification]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `eap:7`. + +[WARNING] +==== +When migrating to JBoss EAP, be sure to specify the version in the target, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path. + +See link:{ProductDocIntroToMTAGuideURL}/index#supported_configurations[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version. +==== + +[id="maven-packages-argument_{context}"] +== Selecting packages + +A list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument. + +.Usage + +[source,xml,subs="attributes+"] +---- + + + + + + + + +---- + +* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The `` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use the following snippet in your `pom.xml`. ++ +[source,xml,subs="attributes+"] +---- + + com.mycustomapp + com.myotherapp + +---- +* While you can provide package names for standard Java EE third party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. + +// WARNING: If you omit the `packages` argument, every package in the application is scanned, which can impact performance. It is best to provide this argument with one or more packages. diff --git a/docs/topics/mtr-maven-logging-properties.adoc b/docs/topics/mtr-maven-logging-properties.adoc new file mode 100644 index 0000000000..b660036fef --- /dev/null +++ b/docs/topics/mtr-maven-logging-properties.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: REFERENCE +[id="maven-logging-properties_{context}"] += Default logging properties + +The default `logging.properties` file included with the {MavenName} is provided below. This configuration omits many extraneous messages while allowing you to view the progress of the {MavenName}. + + +.Default `logging.properties` file +---- +# Licensed under the Eclipse Public License version 1.0, available at +# http://www.eclipse.org/legal/epl-v10.html +# + +# Additional loggers to configure (the root logger is always configured) +#loggers= +handlers=java.util.logging.ConsoleHandler +.level=INFO +#java.util.logging.ConsoleHandler.level=INFO + +#loggers=org.jboss.forge,org.jboss.weld,org.xnio,org.jboss.forge,org.ocpsoft.rewrite,org.jboss.windup.graph.GraphModelScanner,org.jboss.windup.reporting.xml.ClassificationHandler,org.jboss.windup.graph.GraphTyp$ +org.jboss.forge.level=SEVERE +org.janusgraph.level=SEVERE +org.janusgraph.diskstorage.berkeleyje.BerkeleyJEKeyValueStore.level=SEVERE +org.janusgraph.diskstorage.berkeleyje.level=SEVERE +org.jboss.weld.level=SEVERE +org.xnio.level=SEVERE +org.jboss.forge.level=SEVERE +org.ocpsoft.rewrite.level=SEVERE +org.jboss.windup.graph.GraphModelScanner.level=SEVERE +org.jboss.windup.reporting.xml.ClassificationHandler.level=SEVERE +org.jboss.windup.graph.GraphTypeManager.level=SEVERE +org.jboss.windup.graph.GraphContextImpl.level=SEVERE +org.jboss.windup.rules.files.FileMapping.level=SEVERE +org.jboss.windup.exec.level=SEVERE +org.jboss.windup.config.level=SEVERE +com.thinkaurelius.level=SEVERE +org.jboss.windup=INFO +---- diff --git a/docs/topics/mtr-maven-multi-module.adoc b/docs/topics/mtr-maven-multi-module.adoc new file mode 100644 index 0000000000..2b7952b70c --- /dev/null +++ b/docs/topics/mtr-maven-multi-module.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: PROCEDURE +[id="maven-multi-module_{context}"] += Running the {MavenNameTitle} with multiple modules + +To use the {MavenName} in a project with multiple modules, place the configuration inside the parent's `pom.xml`. The {MavenName} will generate a single report that contains the analysis for the parent and any child modules. + +NOTE: It is strongly recommended to set `inherited` to false in multi-module projects; otherwise, the {MavenName} will run when each child is compiled, resulting in multiple executions of the {MavenName} against the child modules. Setting `inherited` to false results in each project being analyzed a single time and drastically decreased run times. + +To run the {MavenName} in a project with multiple modules, perform the following steps. + +. Include the following plugin inside the parent project's `pom.xml`. The following is a sample `pom.xml` for a parent module. ++ +[source,xml,options="nowrap",subs="attributes+"] +---- + + org.jboss.windup.plugin + {LC_PSN}-maven-plugin + {ProductDistributionVersion} + false + + + run-windup + package + + windup + + + + + ${project.basedir} + eap:7 <1> + >/PATH/TO/{CLIName}/< + + +---- +<1> Specify a migration target. At least one migration target must be supplied within the configuration. ++ +This `pom.xml` file differs from the default in the following attributes: ++ +* `inherited`: Defined at the plugin level, this attribute indicates whether or not this configuration should be used in child modules. Set to `false` for performance improvements. +* `input`: Specifies the path to the directory containing the projects to be analyzed. This attribute defaults to `{project.basedir}/src/main`, and should be defined if the parent project does not have source code to analyze. +* `windupHome`: A path to an extracted copy of the {ProductShortName} {CLIName}. This attribute is optional, but is recommended as a performance improvement. ++ +The above example demonstrates a set of recommended arguments. + +. Build the parent project. During the build process, the {MavenName} runs against all children in the project without further configuration. ++ +[source,terminal,subs="attributes+"] +---- +$ mvn clean install +---- + +. Once completed, you can access the generated reports. This report contains the analysis for the parent and all children. diff --git a/docs/topics/mtr-maven-run.adoc b/docs/topics/mtr-maven-run.adoc new file mode 100644 index 0000000000..df09040a92 --- /dev/null +++ b/docs/topics/mtr-maven-run.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * docs/maven-guide/master.adoc + +:_content-type: PROCEDURE +[id="maven-run_{context}"] += Running the {MavenNameTitle} + +The {MavenName} is run by including a reference to the plugin inside your application's `pom.xml` file. When the application is built, the {MavenName} is run and generates the reports for analysis. + +.Prerequisites +* Java Development Kit (JDK) installed. ++ +{ProductShortName} supports the following JDKs: + +** OpenJDK 11 +** Oracle JDK 11 + +* 8 GB RAM +* macOS installation: the value of `maxproc` must be `2048` or greater. +* The Maven `settings.xml` file https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.4/html-single/development_guide/index#configure_the_jboss_eap_maven_repository_using_the_maven_settings[configured] to direct Maven to use the JBoss EAP Maven repository. + + +* To run the {MavenName} on OpenJDK 17 or Oracle JDK17, you first need to set MAVEN_OPTS on the command line by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +export MAVEN_OPTS="--add-modules=java.se --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED" +---- + +.Procedure + +. Add the following `` to your application's `pom.xml` file: ++ +[source,xml,options="nowrap",subs="attributes+"] +---- +[...] + + org.jboss.windup.plugin + {LC_PSN}-maven-plugin + {ProductDistributionVersion} + + + run-windup + package + + windup + + + + + eap:7 <1> + + +[...] +---- +<1> Specify a migration target. At least one migration target must be supplied within the configuration. + +. Add `--add-modules=java.se` to the `MAVEN_OPTS` environment variable. ++ +[source,terminal,subs="attributes+"] +---- +export MAVEN_OPTS=--add-modules=java.se +---- + +. Build the project: ++ +[source,terminal,subs="attributes+"] +---- +$ mvn clean install +---- ++ +You can access the generated reports. diff --git a/docs/topics/mtr-mavenize.adoc b/docs/topics/mtr-mavenize.adoc new file mode 100644 index 0000000000..d5d3d63e04 --- /dev/null +++ b/docs/topics/mtr-mavenize.adoc @@ -0,0 +1,143 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="mavenize_{context}"] += Mavenizing your application + +{ProductShortName} provides the ability to generate an Apache Maven project structure based on the application provided. This will create a directory structure with the necessary Maven Project Object Model (POM) files that specify the appropriate dependencies. + +Note that this feature is not intended to create a final solution for your project. It is meant to give you a starting point and identify the necessary dependencies and APIs for your application. Your project may require further customization. + +== Generating the Maven project structure + +You can generate a Maven project structure for the provided application by passing in the `--mavenize` flag when executing {ProductShortName}. + +The following example runs {ProductShortName} using the link:https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] test application: + +[source,options="nowrap",subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/bin/windup-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output --target eap:6 --packages com.acme org.apache --mavenize +---- + +This generates the Maven project structure in the `/path/to/output/mavenized` directory. + +NOTE: You can only use the `--mavenize` option when providing a compiled application for the `--input` argument. This feature is not available when running {ProductShortName} against source code. + +You can also use the `--mavenizeGroupId` option to specify the `` to be used for the POM files. If unspecified, {ProductShortName} will attempt to identify an appropriate `` for the application, or will default to `com.mycompany.mavenized`. + +== Reviewing the Maven project structure + +The `/path/to/output/mavenized//` directory contains the following items: + +* A root `POM` file. This is the `pom.xml` file at the top-level directory. +* A BOM file. This is the `POM` file in the directory ending with `-bom`. +* One or more application `POM` files. Each module has its `POM` file in a directory named after the archive. + +The example `jee-example-app-1.0.0.ear` application is an EAR archive that contains a WAR and several JARs. There is a separate directory created for each of these artifacts. Below is the Maven project structure created for this application. + +[source,terminal,subs="attributes+"] +---- +/path/to/output/mavenized/jee-example-app/ + jee-example-app-bom/pom.xml + jee-example-app-ear/pom.xml + jee-example-services2-jar/pom.xml + jee-example-services-jar/pom.xml + jee-example-web-war/pom.xml + pom.xml +---- + +Review each of the generated files and customize as appropriate for your project. To learn more about Maven POM files, see the link:https://maven.apache.org/guides/introduction/introduction-to-the-pom.html[Introduction to the POM] section of the Apache Maven documentation. + +[id="root-pom-file_{context}"] +[discrete] +=== Root POM file + +The root POM file for the `jee-example-app-1.0.0.ear` application can be found at `/path/to/output/mavenized/jee-example-app/pom.xml`. This file identifies the directories for all of the project modules. + +The following modules are listed in the root POM for the example `jee-example-app-1.0.0.ear` application. + +// TODO: These modules were manually reversed so that the order was more appropriate. The order may be fixed in a future Windup JIRA. +[source,xml,subs="attributes+"] +---- + + jee-example-app-bom + jee-example-services2-jar + jee-example-services-jar + jee-example-web-war + jee-example-app-ear + +---- + +NOTE: Be sure to reorder the list of modules if necessary so that they are listed in an appropriate build order for your project. + +The root POM is also configured to use the link:https://maven.repository.redhat.com/[Red Hat JBoss Enterprise Application Platform Maven repository] to download project dependencies. + + +[id="bom-file_{context}"] +[discrete] +=== BOM file + +The Bill of Materials (BOM) file is generated in the directory ending in `-bom`. For the example `jee-example-app-1.0.0.ear` application, the BOM file can be found at `/path/to/output/mavenized/jee-example-app/jee-example-app-bom/pom.xml`. The purpose of this BOM is to have the versions of third-party dependencies used by the project defined in one place. For more information on using a BOM, see the link:https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Introduction to the dependency mechanism] section of the Apache Maven documentation. + +The following dependencies are listed in the BOM for the example `jee-example-app-1.0.0.ear` application + +[source,xml,subs="attributes+"] +---- + + + + log4j + log4j + 1.2.6 + + + commons-lang + commons-lang + 2.5 + + + +---- + +[id="app-pom-files_{context}"] +[discrete] +=== Application POM files + +Each application module that can be mavenized has a separate directory containing its POM file. The directory name contains the name of the archive and ends in a `-jar`, `-war`, or `-ear` suffix, depending on the archive type. + +Each application POM file lists that module's dependencies, including: + +* Third-party libraries +* Java EE APIs +* Application submodules + +For example, the POM file for the `jee-example-app-1.0.0.ear` EAR, `/path/to/output/mavenized/jee-example-app/jee-example-app-ear/pom.xml`, lists the following dependencies. + +[source,xml,subs="attributes+"] +---- + + + log4j + log4j + 1.2.6 + + + org.jboss.seam + jee-example-web-war + 1.0 + war + + + org.jboss.seam + jee-example-services-jar + 1.0 + + + org.jboss.seam + jee-example-services2-jar + 1.0 + + +---- diff --git a/docs/topics/mtr-method-deploy.adoc b/docs/topics/mtr-method-deploy.adoc new file mode 100644 index 0000000000..fd751cbc50 --- /dev/null +++ b/docs/topics/mtr-method-deploy.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="method-deploy_{context}"] += Deploy phase + +.Red Hat migration methodology: Deploy phase +image::RHAMT_AMM_Methodology_446947_0617_ECE_Deploy.png[Red Hat migration methodology: Deploy] + +The _Deploy_ phase is when you run the plan created in the Design phase. In this phase, you scale the overall transformation process to complete the plan and bring all applications to their new production environment. + +The plan is run in iterations to deliver value incrementally. With each iteration, you continuously validate against the plan and document findings to improve the next sprint. + +The use of the {ProductName} {PluginName} increases speed in each iteration. It can be used with Eclipse, and marks migration issues directly in the source code, provides inline hints, and offers code change suggestions. See the link:{EclipseCrsGuideURL}[_{EclipseCrsGuideTitle}_] for information on how to use the {PluginName}. diff --git a/docs/topics/mtr-method-design.adoc b/docs/topics/mtr-method-design.adoc new file mode 100644 index 0000000000..2c04134db7 --- /dev/null +++ b/docs/topics/mtr-method-design.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="method-design_{context}"] += Design phase + +.Red Hat migration methodology: Design phase +image::RHAMT_AMM_Methodology_446947_0617_ECE_Design.png[Red Hat migration methodology: Design] + +The _Design_ phase is when you identify all risks, define a strategy and target architecture, prove the technology, and build the business case. This phase consists of the following steps: + +Assess:: ++ +Examine the existing infrastructure, architecture, technologies, and applications. Identify dependencies, knowledge, processes, and lifecycles. Define the desired infrastructure, architecture, technologies, and applications. Determine the feasibility and potential risks. Draft a plan and provide rough estimates. ++ +Analyzing applications using the {ProductName} {WebName} or {CLIName} helps to determine dependencies, potential risks, and relative effort. See the link:{ProductDocWebConsoleGuideURL}[_{WebConsoleBookName}_] or link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for information on how to use these tools. + +Prove:: ++ +Solve and document the identified technical risks, for example, high risk items and issues with unknown effort. Build and shape the new platform infrastructure. Refine the estimates based on the outcomes. + +Pilot:: ++ +Choose a small set of representative applications to transform. Finalize the target platform infrastructure as necessary. Update the documentation as the process is fine-tuned. This pilot consists of one or several iterations of the migration execution, which is scaled during the Deploy phase. ++ +Use the {ProductName} {PluginName} to accelerate the code migration. See the link:{EclipseCrsGuideURL}[_{EclipseCrsGuideTitle}_] for information on how to use the {PluginName}. + +Plan:: ++ +Based on the outcomes of the previous steps, sharpen the estimates and refine the project plan. Define the rollout strategy to be used in the Deploy phase to complete the migration. Prepare and schedule the relevant link:https://www.redhat.com/en/services/training[technical enablement courses]. diff --git a/docs/topics/mtr-method-discover.adoc b/docs/topics/mtr-method-discover.adoc new file mode 100644 index 0000000000..bdd6ce619d --- /dev/null +++ b/docs/topics/mtr-method-discover.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="method-discover_{context}"] += Discover phase + +.Red Hat migration methodology: Discover phase +image::RHAMT_AMM_Methodology_446947_0617_ECE_Discover.png[Red Hat Migration Methodology: Discover] + +The _Discover_ phase is when you gather all stakeholders and decision-makers together to understand the current state and business drivers, and to determine the migration or modernization needs. + +In this phase, you can do the following: + +* Explore technologies and discuss potential approaches. +* Identify the existing pain points, concerns, requirements, and some potential challenges. +* Define the high-level business priorities, and scope the assessment. +* Determine in what ways you want to modernize your application development and delivery to allow you to innovate more rapidly. + +Typically, this can be covered in a day in a workshop with Red Hat experts. diff --git a/docs/topics/mtr-migration-approach.adoc b/docs/topics/mtr-migration-approach.adoc new file mode 100644 index 0000000000..c1636bc926 --- /dev/null +++ b/docs/topics/mtr-migration-approach.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="migration-approach_{context}"] += Red Hat's application migration approach + +Red Hat has defined a strategy to make large-scale application migrations to Red Hat JBoss Middleware quantifiable, less costly, less risky, and easier to complete. + +Migrating from proprietary or outdated middleware platforms to Red Hat JBoss Middleware gives you lightweight, modular, and cloud-ready middleware with a supporting application infrastructure to make teams more productive. JBoss Middleware and other Red Hat technologies also provide great opportunities to modernize your application development and delivery, allowing you to innovate more quickly. diff --git a/docs/topics/mtr-migration-best-practices.adoc b/docs/topics/mtr-migration-best-practices.adoc new file mode 100644 index 0000000000..2fe3249495 --- /dev/null +++ b/docs/topics/mtr-migration-best-practices.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="migration-best-practices_{context}"] += Best practices + +Red Hat recommends the following practices when planning and executing a migration or modernization: + +* Create a centralized collaboration platform for information sharing. ++ +Comprehensive and accessible documentation is important so that knowledge can be easily shared and to ensure that effort is not duplicated by solving the same issue twice. It is recommended to document the following items: ++ +** A step-by-step guide for migrating or modernizing an application from scratch. +** A collection of solutions to known and encountered issues. +** Information about the new platform. +** A record of the changes made to specific pilot projects. + +* Reuse, automate, and standardize as much as possible. ++ +Consider reusing existing components instead of creating new ones. Automate processes related to the application lifecycle, such as builds, configuration, deployment, and tests. Standardize and document software packaging format, configuration management, libraries, and dependencies. + +* Use a proven and repeatable methodology. ++ +The recommendation is to follow a practical approach and make as few changes as possible to get a functionally identical application. + +* Involve Red Hat technical expertise early for the chosen Red Hat Middleware components. ++ +This is crucial to make your migrations and modernizations low risk, predictable, and efficient. Contact Red Hat Consulting for assistance. diff --git a/docs/topics/mtr-migration-goals.adoc b/docs/topics/mtr-migration-goals.adoc new file mode 100644 index 0000000000..6a4844b1bc --- /dev/null +++ b/docs/topics/mtr-migration-goals.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="migration-goals_{context}"] += Goals of assessing a migration + +Many organizations are faced with the challenges of keeping their existing business operations running, while also trying to innovate. There are typically increased expectations to deliver new functionality faster and to reduce cost. + +When assessing a migration or modernization effort, it is important to address the challenges that are specific to your organization. Common challenges that organizations face are limited budgets, lack of in-house skills, perceived risks, no known predictable process, and accurate effort estimation in a timely manner. + +In general, the goals when assessing a large-scale middleware migration or modernization effort are the following: + +* Predicting the level of effort and cost +* Scheduling application migrations and handling conflicts +* Identifying all potential risks at a code, infrastructure, process, or knowledge level +* Predicting the return on investment to make the business case +* Identifying and mitigating risks to the business +* Minimizing disruption to existing business operations + +Red Hat has developed a strategy to minimize risk and make application migration and modernizations more efficient. diff --git a/docs/topics/mtr-migration-methodology.adoc b/docs/topics/mtr-migration-methodology.adoc new file mode 100644 index 0000000000..df47d49f9a --- /dev/null +++ b/docs/topics/mtr-migration-methodology.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="migration-methodology_{context}"] += Methodology + +Red Hat's recommended methodology is a proven, scalable approach that helps you to incrementally plan and conduct a migration or modernization. + +.Red Hat migration methodology +image::RHAMT_AMM_Methodology_446947_0517_ECE.png[Red Hat migration methodology] + +The approach consists of the following phases: + +Discover:: Explore the technologies and identify concerns, organization requirements and challenges. Discuss options and potential approaches. + +Design:: Identify and mitigate the biggest risks from an application, infrastructure, process, and knowledge perspective. Establish a strategy for the solution. Prove the technology and build the business case. + +Deploy:: Scale the modernization or migration iteratively by executing the previously defined strategy according to a well-defined delivery model. diff --git a/docs/topics/mtr-migration-paths.adoc b/docs/topics/mtr-migration-paths.adoc new file mode 100644 index 0000000000..9380954c9b --- /dev/null +++ b/docs/topics/mtr-migration-paths.adoc @@ -0,0 +1,129 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc + +:_content-type: CONCEPT +[id="migration-paths_{context}"] += Supported migration paths + +The {ProductName} ({ProductShortName}) supports migrations from third-party enterprise application servers, such as Oracle WebLogic Server, to JBoss Enterprise Application Platform (JBoss EAP) and upgrades to the latest release of JBoss EAP. + +{ProductShortName} provides a comprehensive set of rules to assess the suitability of your applications for containerization and deployment on Red Hat OpenShift Container Platform (RHOCP). You can run an {ProductShortName} analysis to assess your applications' suitability for migration to multiple target platforms. + +The following table describes the migration paths most commonly supported. + +.Supported migration paths: Source platform ⇒ target +[cols="2,^1,^1,^1,^1,^1,^1,^1,^1",options="^,header"] +|==== + +|Source platform{nbsp}⇒ +|JBoss EAP{nbsp}6 +|JBoss EAP{nbsp}7 +|RHOCP +|OpenJDK 8,{nbsp}11,{nbsp}&{nbsp}17 +|Apache Camel{nbsp}3 +|Spring Boot on Red{nbsp}Hat Runtimes +|Quarkus +|Azure + +|Oracle WebLogic Server +|{icon-check} +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- +|- + + +|IBM WebSphere Application Server +|{icon-check} +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- +|- + +|JBoss EAP 4 +|{icon-check} +|{icon-x} footnoteref:[note2,Although {ProductShortName} does not currently provide rules for this migration path, Red Hat Consulting can assist with migration from any source platform to JBoss EAP 7.] +|{icon-check} +|{icon-check} +|- +|- +|- +|- + +|JBoss EAP 5 +|{icon-check} +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- +|- + +|JBoss EAP 6 +|N/A +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- +|- + +|JBoss EAP 7 +|N/A +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- +|{icon-check} + +|Oracle JDK +|- +|- +|{icon-check} +|{icon-check} +|- +|- +|- +|- + +|Apache Camel 2 +|- +|- +|{icon-check} +|{icon-check} +|{icon-check} +|- +|- +|- + +|Spring Boot +|- +|- +|{icon-check} +|{icon-check} +|- +|{icon-check} +|{icon-check} +|{icon-check} + +|Java application +|- +|- +|{icon-check} +|{icon-check} +|- +|- +|- +|- +|==== diff --git a/docs/topics/mtr-optimize-performance.adoc b/docs/topics/mtr-optimize-performance.adoc new file mode 100644 index 0000000000..0342261d95 --- /dev/null +++ b/docs/topics/mtr-optimize-performance.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: CONCEPT +[id="optimize-performance_{context}"] += Optimizing {ProductShortName} performance + +{ProductShortName} performance depends on a number of factors, including hardware configuration, the number and types of files in the application, the size and number of applications to be evaluated, and whether the application contains source or compiled code. For example, a file that is larger than 10 MB may need a lot of time to process. + +In general, {ProductShortName} spends about 40% of the time decompiling classes, 40% of the time executing rules, and the remainder of the time processing other tasks and generating reports. This section describes what you can do to improve the performance of {ProductShortName}. + +== Deploying and running the application + +Try these suggestions first before upgrading hardware. + +* If possible, run {ProductShortName} against the source code instead of the archives. This eliminates the need to decompile additional JARs and archives. +* Specify a comma-separated list of the packages to be evaluated by {ProductShortName} using the `--packages` argument on the `<{ProductShortName}_HOME>/bin/{LC_PSN}-cli` command line. If you omit this argument, {ProductShortName} will decompile everything, which has a big impact on performance. +* Specify the `--excludeTags` argument where possible to exclude them from processing. +* Avoid decompiling and analyzing any unnecessary packages and files, such as proprietary packages or included dependencies. +* Increase your ulimit when analyzing large applications. See link:https://access.redhat.com/solutions/60746[this Red Hat Knowledgebase article] for instructions on how to do this for Red Hat Enterprise Linux. +* If you have access to a server that has better resources than your laptop or desktop machine, you may want to consider running {ProductShortName} on that server. + +== Upgrading hardware + +If the application and command-line suggestions above do not improve performance, you may need to upgrade your hardware. + +* If you have access to a server that has better resources than your laptop/desktop, then you may want to consider running {ProductShortName} on that server. +* Very large applications that require decompilation have large memory requirements. 8 GB RAM is recommended. This allows 3 - 4 GB RAM for use by the JVM. +* An upgrade from a single or dual-core to a quad-core CPU processor provides better performance. +* Disk space and fragmentation can impact performance. A fast disk, especially a solid-state drive (SSD), with greater than 4 GB of defragmented disk space should improve performance. diff --git a/docs/topics/mtr-overriding-rules.adoc b/docs/topics/mtr-overriding-rules.adoc new file mode 100644 index 0000000000..6abcbf86c0 --- /dev/null +++ b/docs/topics/mtr-overriding-rules.adoc @@ -0,0 +1,100 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="overriding-rules_{context}"] += Overriding rules + +You can override core rules distributed with {ProductShortName} or even custom rules. For example, you can change the matching conditions, effort, or hint text for a rule. This is done by making a copy of the original rule, marking it as a rule override, and making the necessary adjustments. + +You can disable a rule by creating a rule override with an empty `` element. + +== Overriding a rule + +You can override a core or custom rule. + +.Procedure + +. Copy the XML file that contains the rule you want to override to the custom rules directory. ++ +Custom rules can be placed in `<{ProductShortName}_HOME>/rules`, `${user.home}/.{LC_PSN}/rules/`, or a directory specified by the `--userRulesDirectory` command-line argument. + +. Edit the XML file so that it contains only the `` elements for the rules that you want to override. ++ +[NOTE] +==== +Rules from the original ruleset that are not overridden by the new ruleset are run as normal. +==== + +. Ensure that you keep the same rule and ruleset IDs. When you copy the original rule XML, this ensures that the IDs match. + +. Ensure that the target technology in the override ruleset matches one of the targets that you specified for running the analysis. + +. Add the `true` element to the ruleset metadata. + +. Update the rule definition. ++ +You can change anything in the rule definition. The new rule overrides the original rule in its entirety. + +The following rule override example changes the `effort` of the `weblogic-02000` rule in the `weblogic` ruleset from `1` to `3`: + +.Rule override definition example +[source,xml,subs="attributes+"] +---- + + <1> + + ... + true <2> + + + <3> + + + + + <4> + Replace with the StringUtils class from Apache Commons. + + weblogic + + + + + +---- +<1> Ensure that the `ruleset id` matches the original `ruleset id`. +<2> Add `true` to the `` section. +<3> Ensure that the `rule id` matches the original `rule id`. +<4> Updated `effort`. + +When you run {ProductShortName}, this rule overrides the original rule with the same rule ID. You can verify that the new rule was used by viewing the contents of the Rule Provider Executions Overview. + +== Disabling a rule + +To disable a rule, create a rule override definition with an empty `` element according to the following example: + +.Rule override definition example to disable a rule +[source,xml,subs="attributes+"] +---- + + + + ... + true + + + + <1> + + + +---- +<1> The `` element is empty so that the `weblogic-02000` rule in the `weblogic` ruleset is disabled. diff --git a/docs/topics/mtr-plugin-components.adoc b/docs/topics/mtr-plugin-components.adoc new file mode 100644 index 0000000000..fc98ae3944 --- /dev/null +++ b/docs/topics/mtr-plugin-components.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: CONCEPT +[id="plugin-components_{context}"] += About {PluginName} components + +The following components are available in the {ProductShortName} perspective when using the {PluginName} to analyze projects. + +Issue Explorer:: This view allows you to explore the {ProductShortName} issues for projects that have been analyzed. ++ +If this view is not visible in the {ProductShortName} perspective, you can open it by selecting *Window* -> *Show View* -> *Issue Explorer*. + +{ProductShortName} Server:: The {ProductShortName} server is a separate process that runs the {ProductShortName} analysis, flags the migration issues, and generates the reports. ++ +You can start, stop, and view the status of the {ProductShortName} server from *Issue Explorer*. + +Issue Details:: This view shows detailed information about the selected {ProductShortName} issue, including the hint, severity, and any additional resources. ++ +If this view is not visible in the {ProductShortName} perspective, you can open it by selecting *Window* -> *Show View* -> *Issue Details*. + +{ProductShortName} Report:: This view shows the HTML reports that are generated when {ProductShortName} is executed. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies. ++ +Note that the {ProductShortName} run configuration used must have the *Generate Report* option selected in order for {ProductShortName} reports to be generated. ++ +If this view is not visible in the {ProductShortName} perspective, you can open it by selecting *Window* -> *Show View* -> *{ProductShortName} Report*. diff --git a/docs/topics/mtr-plugin-intro.adoc b/docs/topics/mtr-plugin-intro.adoc new file mode 100644 index 0000000000..a0ea8547d3 --- /dev/null +++ b/docs/topics/mtr-plugin-intro.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * docs/plugin-guide/master.adoc + +:_content-type: CONCEPT +[id="plugin-intro_{context}"] += About the {PluginBookName} + +This guide is for engineers, consultants, and others who want to use the {PluginName} for the {ProductName} ({ProductShortName}) to assist with migrating applications. + + diff --git a/docs/topics/mtr-proc_web-downloading-logs-cli.adoc b/docs/topics/mtr-proc_web-downloading-logs-cli.adoc new file mode 100644 index 0000000000..d7050240ab --- /dev/null +++ b/docs/topics/mtr-proc_web-downloading-logs-cli.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="proc_web-downloading-logs-cli_{context}"] += Downloading logs using the CLI +[role="_abstract"] + +You can download pod logs using the CLI. + +.Procedure + +. Obtain the pod names: ++ +---- +$ oc get pods -n +---- ++ +The output resembles the following: ++ +[source,terminal,subs="attributes+"] +---- +NAME READY STATUS RESTARTS AGE +eap-builder-1-build 0/1 Completed 0 1d +{LC_PSN}-postgresql-1-hfbdn 1/1 Running 0 1d +{LC_PSN}-sso-1-build 0/1 Completed 0 1d +{LC_PSN}-web-console-1-build 0/1 Completed 0 1d +{LC_PSN}-web-console-1-vt7s5 1/1 Running 1 1d +sso-1-wjl2n 1/1 Running 1 1d +---- + +. Use `oc logs` to examine the pod log: ++ +---- +$ oc logs +---- ++ +[NOTE] +==== +You can redirect the output to obtain a copy of the current log: +---- +$ oc logs > ./.log +---- +==== diff --git a/docs/topics/mtr-review-existing-rules.adoc b/docs/topics/mtr-review-existing-rules.adoc new file mode 100644 index 0000000000..4172e0a90c --- /dev/null +++ b/docs/topics/mtr-review-existing-rules.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="review-existing-rules_{context}"] += Reviewing existing {ProductShortName} XML rules + +{ProductShortName} XML-based rules are located on GitHub at the following location: link:https://github.com/windup/windup-rulesets/tree/master/rules/rules-reviewed[https://github.com/windup/windup-rulesets/tree/master/rules/rules-reviewed]. + +You can fork and clone the {ProductShortName} XML rules on your local machine. + +Rules are grouped by target platform and function. When you create a new rule, it is helpful to find a rule that is similar to the one you need and use it as a starting template. + +New rules are continually added, so it is a good idea to check back frequently to review the updates. diff --git a/docs/topics/mtr-review-quickstarts.adoc b/docs/topics/mtr-review-quickstarts.adoc new file mode 100644 index 0000000000..5f823d721d --- /dev/null +++ b/docs/topics/mtr-review-quickstarts.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="review-quickstarts_{context}"] += Reviewing the {ProductName} quickstarts + +The {ProductName} quickstarts provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. + +Each quickstart has a `README.adoc` file that contains instructions for that quickstart. + +You can download a `.zip` file of the latest version of the quickstarts. If you prefer to work with the source code, you can fork and clone the `windup-quickstarts` project repository. + +[id="download_quickstart_zip_{context}"] +== Downloading the latest quickstart + +You can download the latest release of a quickstart. + +.Procedure + +. Launch a browser and navigate to link:https://github.com/windup/windup-quickstarts/releases[https://github.com/windup/windup-quickstarts/releases]. +. Click the latest release to download the `.zip` file to your local file system. +. Extract the archive files to a local directory. ++ +You can review the quickstart `README.adoc` file. + +[id="use-quickstart-github-project_{context}"] +== Forking and cloning the quickstart GitHub project + +You can fork and clone the Quickstart Github project on your local machine. + +.Prerequisites + +* You must have link:http://git-scm.com/[`git`] client installed. + +.Procedure + +. Click *Fork* on the https://github.com/windup/windup-quickstarts/[{ProductName} quickstart] GitHub page to create the project in your own Git. The forked GitHub repository URL should look like this: `\https://github.com//windup-quickstarts.git`. + +. Clone the {ProductName} quickstart repository to your local file system: ++ +---- +$ git clone https://github.com//windup-quickstarts.git +---- ++ +This creates a `windup-quickstarts` directory on your local file system. + +. Navigate to the newly created directory: ++ +---- +$ cd windup-quickstarts/ +---- + +. To retrieve the latest code updates, add the remote `upstream` repository so that you can fetch changes to the original forked repository: ++ +---- +$ git remote add upstream https://github.com/windup/windup-quickstarts.git +---- + +. Download the latest files from the `upstream` repository: ++ +---- +$ git fetch upstream +---- diff --git a/docs/topics/mtr-review-reports.adoc b/docs/topics/mtr-review-reports.adoc new file mode 100644 index 0000000000..abef7a926a --- /dev/null +++ b/docs/topics/mtr-review-reports.adoc @@ -0,0 +1,257 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="review-reports_{context}"] += Reviewing the reports + +The report examples shown in the following sections are a result of analyzing the `com.acme` and `org.apache` packages in the https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] example application, which is located in the {ProductShortName} GitHub source repository. + +ifdef::cli-guide[] +The report was generated using the following command. + +[options="nowrap",subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/bin/windup-cli --input /home/username/windup-cli-source/test-files/jee-example-app-1.0.0.ear/ --output /home/username/windup-cli-reports/jee-example-app-1.0.0.ear-report --target eap:6 --packages com.acme org.apache +---- +endif::cli-guide[] + +Use a browser to open the `index.html` file located in the report output directory. This opens a landing page that lists the applications that were processed. Each row contains a high-level overview of the story points, number of incidents, and technologies encountered in that application. + +.Application list +image::3-1-applications.png[Application list] + +NOTE: The incidents and estimated story points change as new rules are added to {ProductShortName}. The values here may not match what you see when you test this application. + +The following table lists all of the reports and pages that can be accessed from this main {ProductShortName} landing page. Click the name of the application, *jee-example-app-1.0.0.ear*, to view the application report. + +[cols="30%,70%", options="header"] +|==== +| Page +| How to Access + +|Application +| Click the name of the application. + +| Technologies report +| Click the *Technologies* link at the top of the page. + +| Archives shared by multiple applications +| Click the *Archives shared by multiple applications* link. Note that this link is only available when there are shared archives across multiple applications. + +| Rule providers execution overview +| Click the *Rule providers execution overview* link at the bottom of the page. +|==== + +Note that if an application shares archives with other analyzed applications, you will see a breakdown of how many story points are from shared archives and how many are unique to this application. + +.Shared archives +image::3-2-shared-archives.png[Shared archives] + +Information about the archives that are shared among applications can be found in the Archives Shared by Multiple Applications reports. + +[id="review-application-report_{context}"] +== Application report + +=== Dashboard + +Access this report from the report landing page by clicking on the application name in the *Application List*. + +The dashboard gives an overview of the entire application migration effort. It summarizes: + +* The incidents and story points by category +* The incidents and story points by level of effort of the suggested changes +* The incidents by package + +.Dashboard +image::3-3-dashboard.png[Dashboard] + +The top navigation bar lists the various reports that contain additional details about the migration of this application. Note that only those reports that are applicable to the current application will be available. + +[cols="30%,70%", options="header"] +|==== +| Report +| Description + +| Issues +| Provides a concise summary of all issues that require attention. + +| Application details +| Provides a detailed overview of all resources found within the application that may need attention during the migration. + +| Technologies +| Displays all embedded libraries grouped by functionality, allowing you to quickly view the technologies used in each application. + +| Dependencies +| Displays all Java-packaged dependencies found within the application. + +| Unparsable +| Shows all files that {ProductShortName} could not parse in the expected format. For instance, a file with a `.xml` or `.wsdl` suffix is assumed to be an XML file. If the XML parser fails, the issue is reported here and also where the individual file is listed. + +| Remote services +| Displays all remote services references that were found within the application. + +| EJBs +| Contains a list of EJBs found within the application. + +| JBPM +| Contains all of the JBPM-related resources that were discovered during analysis. + +| JPA +| Contains details on all JPA-related resources that were found in the application. + +| Hibernate +| Contains details on all Hibernate-related resources that were found in the application. + +| Server resources +| Displays all server resources (for example, JNDI resources) in the input application. + +| Spring Beans +| Contains a list of Spring Beans found during the analysis. + +| Hard-coded IP addresses +| Provides a list of all hard-coded IP addresses that were found in the application. + +| Ignored files +ifdef::cli-guide[] +| Lists the files found in the application that, based on certain rules and {ProductShortName} configuration, were not processed. See the `--userIgnorePath` option for more information. +endif::[] +ifdef::maven-guide[] +| Lists the files found in the application that, based on certain rules and {ProductShortName} configuration, were not processed. See the `userIgnorePath` option for more information. +endif::[] + +| About +| Describes the current version of {ProductShortName} and provides helpful links for further assistance. +|==== + +[id="issues-report_{context}"] +=== Issues report + +Access this report from the dashboard by clicking the *Issues* link. + +This report includes details about every issue that was raised by the selected migration paths. The following information is provided for each issue encountered: + +* A title to summarize the issue. +* The total number of incidents, or times the issue was encountered. +* The rule story points to resolve a single instance of the issue. +* The estimated level of effort to resolve the issue. +* The total story points to resolve every instance encountered. This is calculated by multiplying the number of incidents found by the story points per incident. + +.Issues report +image::3-4-issues-report.png[Issues report] + +Each reported issue may be expanded, by clicking on the title, to obtain additional details. The following information is provided. + +* A list of files where the incidents occurred, along with the number of incidents within each file. If the file is a Java source file, then clicking the filename will direct you to the corresponding Source report. +* A detailed description of the issue. This description outlines the problem, provides any known solutions, and references supporting documentation regarding either the issue or resolution. +* A direct link, entitled *Show Rule*, to the rule that generated the issue. + +.Expanded issue +image::3-5-expanded-issue.png[Expanded rule in the issues report] + +Issues are sorted into four categories by default. Information on these categories is available at ask Category. + +=== Application details report + +Access this report from the dashboard by clicking the *Application Details* link. + +The report lists the story points, the Java incidents by package, and a count of the occurrences of the technologies found in the application. Next is a display of application messages generated during the migration process. Finally, there is a breakdown of this information for each archive analyzed during the process. + +.Application Details report +image::3-6-application-details-report.png[Application Details report] + +Expand the `jee-example-app-1.0.0.ear/jee-example-services.jar` to review the story points, Java incidents by package, and a count of the occurrences of the technologies found in this archive. This summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns. + +[cols="1,3", options="header"] +|==== +| Column Name +| Description + +| Name +| The name of the file being analyzed. + +| Technology +| The type of file being analyzed, for example, *Decompiled Java File* or *Properties*. + +| Issues +| Warnings about areas of code that need review or changes. + +| Story Points +a| Level of effort required to migrate the file. +|==== + +Note that if an archive is duplicated several times in an application, it will be listed just once in the report and will be tagged with `[Included multiple times]`. + +.Duplicate archive in an application +image::3-7-duplicate-archive-in-application.png[Duplicate archive] + +The story points for archives that are duplicated within an application will be counted only once in the total story point count for that application. + +[id="technology-report-application_{context}"] +=== Technologies report + +Access this report from the dashboard by clicking the *Technologies* link. + +The report lists the occurrences of technologies, grouped by function, in the analyzed application. It is an overview of the technologies found in the application, and is designed to assist users in quickly understanding each application's purpose. + +The image below shows the technologies used in the `jee-example-app`. + +.Technologies in an application +image::3-8-technologies-in-application.png[Technology report Application view] + +=== Transactions report + +A Transactions report displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks, such as Hibernate. + +ifdef::mta[] +The image below shows an example of a Transactions report. + +.Transactions report +image::transaction-report.png[Transactions report] +endif::[] + +ifdef::mtr[] +The image below shows an example of a Transactions report. + +.Transactions report +image::3-9-transaction-report-mtr.png[Transactions report] +endif::[] +=== Source report + +The Source report displays the migration issues in the context of the source file in which they were discovered. + +.Source report +image::3-10-source-report.png[Source Report] + +[id="technology-report_{context}"] +== Technologies report + +Access this report from the report landing page by clicking the *Technologies* link. + +This report provides an aggregate listing of the technologies used, grouped by function, for the analyzed applications. It shows how the technologies are distributed, and is typically reviewed after analyzing a large number of applications to group the applications and identify patterns. It also shows the size, number of libraries, and story point totals of each application. + +Clicking any of the headers, such as *Markup*, sorts the results in descending order. Selecting the same header again will resort the results in ascending order. The currently selected header is identified in bold, next to a directional arrow, indicating the direction of the sort. + +.Technologies used across multiple applications +image::3-11-technologies-used-across-multiple-applications.png[Technologies used across multiple applications] + +[id="shared-archives_{context}"] +== Archives shared by multiple applications + +Access these reports from the report landing page by clicking the *Archives shared by multiple applications* link. Note that this link is only available if there are applicable shared archives. + +.Archives shared by multiple applications +image::3-12-archives-shared-by-multiple-applications.png[Archives shared by multiple applications] + +This allows you to view the detailed reports for all archives that are shared across multiple applications. + +[id="review-rule-providers-execution-overview_{context}"] +== Rule providers execution overview + +Access this report from the report landing page by clicking the *Rule providers execution overview* link. + +This report provides the list of rules that ran when running the {ProductShortName} migration command against the application. + +.Rule providers execution overview +image::3-13-rule-providers-execution-overview.png[Rule Provider Execution Overview] diff --git a/docs/topics/mtr-rule-categories.adoc b/docs/topics/mtr-rule-categories.adoc new file mode 100644 index 0000000000..ff79564b4d --- /dev/null +++ b/docs/topics/mtr-rule-categories.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="rule-categories_{context}"] += Using custom rule categories + +You can create custom rule categories and assign {ProductShortName} rules to them. + +[NOTE] +==== +Although {ProductShortName} processes rules with the legacy `severity` field, you must update your custom rules to use the new `category-id` field. +==== + +[id="add_custom_category_{context}"] +== Adding a custom category + +You can add a custom category to the rule category file. + +.Procedure + +. Edit the rule category file, which is located at `<{ProductShortName}_HOME>/rules/migration-core/core.windup.categories.xml`. + +. Add a new `` element and fill in the following parameters: ++ +* `id`: The ID that {ProductShortName} rules use to reference the category. +* `priority`: The sorting priority relative to other categories. The category with the lowest value is displayed first. +* `name`: The display name of the category. +* `description`: The description of the category. ++ +.Custom rule category example +[source,xml,subs="attributes+"] +---- + + + ... + + Custom Category + This is a custom category. + + +---- ++ +This category is ready to be referenced by {ProductShortName} rules. + +[id="assign_custom_category_{context}"] +== Assigning a rule to a custom category + +You can assign a rule to your new custom category. + +.Procedure + +In your {ProductShortName} rule, update the `category-id` field as in the following example. + +[source,xml,subs="attributes+"] +---- + + + ... + + + + Hint message. + + + +---- + +If this rule condition is met, incidents identified by this rule use your custom category. The custom category is displayed on the dashboard and in the Issues report. + +.Custom category on the dashboard +image::custom_rule_category.png[Custom rule category on the Dashboard] diff --git a/docs/topics/mtr-rules-guide-intro.adoc b/docs/topics/mtr-rules-guide-intro.adoc new file mode 100644 index 0000000000..9c1317210c --- /dev/null +++ b/docs/topics/mtr-rules-guide-intro.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: CONCEPT +[id="rules-guide-intro_{context}"] += About the {RulesDevBookName} + +This guide is for engineers, consultants, and others who want to create custom XML-based rules for {ProductFullName} tools. + +For more information, see the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. diff --git a/docs/topics/mtr-rules-important-links.adoc b/docs/topics/mtr-rules-important-links.adoc new file mode 100644 index 0000000000..35db891e97 --- /dev/null +++ b/docs/topics/mtr-rules-important-links.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: REFERENCE +[id="rules-important-links_{context}"] += Additional resources + +* {ProductShortName} Javadoc: http://windup.github.io/windup/docs/latest/javadoc +* {ProductShortName} Jira issue tracker: {JiraWindupURL} +* {ProductShortName} mailing list: windup-eng@redhat.com diff --git a/docs/topics/mtr-rules-testing-junit.adoc b/docs/topics/mtr-rules-testing-junit.adoc new file mode 100644 index 0000000000..0a728eb933 --- /dev/null +++ b/docs/topics/mtr-rules-testing-junit.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="rules-testng-junit_{context}"] += Testing the rules by using JUnit + +Once a test rule has been created, it can be analyzed as part of a JUnit test to confirm that the rule meets all criteria for execution. The `WindupRulesMultipleTests` class in the {ProductShortName} rules repository is designed to test multiple rules simultaneously, and provides feedback on any missing requirements. + +.Prerequisites + +* Fork and clone the {ProductShortName} XML rules. The location of this repository will be referred to as . +* Create a test XML rule. + +.Creating the JUnit test configuration + +The following instructions detail creating a JUnit test using Eclipse. When using a different IDE, it is recommended to consult your IDE's documentation for instructions on creating a JUnit test. + +. Import the {ProductShortName} rulesets repository into your IDE. +. Copy the custom rules, along with the corresponding tests and data, into `/rules-reviewed//`. This should create the following directory structure. ++ +.Directory structure +[source,options="nowrap",subs="attributes+"] +---- +├── *rules-reviewed/* _(Root directory of the rules found within the project)_ +│ ├── */* _(Directory to contain the newly developed rule and tests)_ +│ │ ├── *.windup.xml* _(Custom rule)_ +│ │ ├── *tests/* _(Directory that contains any test rules and data)_ +│ │ │ ├── *.windup.test.xml* _(Test rule)_ +│ │ │ └── *data/* _(Optional directory to contain test rule data)_ +---- + +. Select *Run* from the top menu bar. +. Select *Run Configurations...* from the drop down that appears. +. Right-click *JUnit* from the options on the left side and select *New*. +. Enter the following: ++ +** *Name*: A name for your JUnit test, such as `WindupRulesMultipleTests`. +** *Project*: Ensure this is set to `windup-rulesets`. +** *Test class*: Set this to `org.jboss.windup.rules.tests.WindupRulesMultipleTests`. ++ +image::junit-test.png[] + +. Select the *Arguments* tab, and add the `-DrunTestsMatching=` VM argument. For instance, if your rule name was `community-rules`, then you would add `-DrunTestsMatching=community-rules` as seen in the following image. ++ +image::junit-test-arguments.png[] + +. Click *Run* in the bottom right corner to begin the test. ++ +When the execution completes, the results are available for analysis. If all tests passed, then the test rule is correctly formatted. If all tests did not pass, it is recommended to address each of the issues raised in the test failures. diff --git a/docs/topics/mtr-tech-tags.adoc b/docs/topics/mtr-tech-tags.adoc new file mode 100644 index 0000000000..f690811706 --- /dev/null +++ b/docs/topics/mtr-tech-tags.adoc @@ -0,0 +1,386 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: REFERENCE +[id="tech-tags_{context}"] += Supported technology tags + +The following technology tags are supported in {ProductShortName} {ProductVersion}: + +* 0MQ Client +* 3scale +* Acegi Security +* AcrIS Security +* ActiveMQ library +* Airframe +* Airlift Log Manager +* AKKA JTA +* Akka Testkit +* Amazon SQS Client +* AMQP Client +* Anakia +* AngularFaces +* ANTLR StringTemplate +* AOP Alliance +* Apache Accumulo Client +* Apache Aries +* Apache Commons JCS +* Apache Commons Validator +* Apache Flume +* Apache Geronimo +* Apache Hadoop +* Apache HBase Client +* Apache Ignite +* Apache Karaf +* Apache Mahout +* Apache Meecrowave JTA +* Apache Sirona JTA +* Apache Synapse +* Apache Tapestry +* Apiman +* Applet +* Arquillian +* AspectJ +* Atomikos JTA +* Avalon Logkit +* Axion Driver +* Axis +* Axis2 +* BabbageFaces +* Bean Validation +* BeanInject +* Blaze +* Blitz4j +* BootsFaces +* Bouncy Castle +* ButterFaces +* Cache API +* Cactus +* Camel +* Camel Messaging Client +* Camunda +* Cassandra Client +* CDI +* Cfg Engine +* Chunk Templates +* Cloudera +* Coherence +* Common Annotations +* Composite Logging +* Composite Logging JCL +* Concordion +* CSS +* Cucumber +* Dagger +* DbUnit +* Demoiselle JTA +* Derby Driver +* Drools +* DVSL +* Dynacache +* EAR Deployment +* Easy Rules +* EasyMock +* Eclipse RCP +* EclipseLink +* Ehcache +* EJB +* EJB XML +* Elasticsearch +* Entity Bean +* EtlUnit +* Eureka +* Everit JTA +* Evo JTA +* Feign +* File system Logging +* FormLayoutMaker +* FreeMarker +* Geronimo JTA +* GFC Logging +* GIN +* GlassFish JTA +* Google Guice +* Grails +* Grapht DI +* Guava Testing +* GWT +* H2 Driver +* Hamcrest +* Handlebars +* HavaRunner +* Hazelcast +* Hdiv +* Hibernate +* Hibernate Cfg +* Hibernate Mapping +* Hibernate OGM +* HighFaces +* HornetQ Client +* HSQLDB Driver +* HTTP Client +* HttpUnit +* ICEfaces +* Ickenham +* Ignite JTA +* Ikasan +* iLog +* Infinispan +* Injekt for Kotlin +* Iroh +* Istio +* Jamon +* Jasypt +* Java EE Batch +* Java EE Batch API +* Java EE JACC +* Java EE JAXB +* Java EE JAXR +* Java EE JSON-P +* Java Transaction API +* JavaFX +* JavaScript +* Javax Inject +* JAX-RS +* JAX-WS +* JayWire +* JBehave +* JBoss Cache +* JBoss EJB XML +* JBoss logging +* JBoss Transactions +* JBoss Web XML +* JBossMQ Client +* JBPM +* JCA +* Jcabi Log +* JCache +* JCunit +* JDBC +* JDBC datasources +* JDBC XA datasources +* Jersey +* Jetbrick Template +* Jetty +* JFreeChart +* JFunk +* JGoodies +* JMock +* JMockit +* JMS Connection Factory +* JMS Queue +* JMS Topic +* JMustache +* JNA +* JNI +* JNLP +* JPA entities +* JPA Matchers +* JPA named queries +* JPA XML +* JSecurity +* JSF +* JSF Page +* JSilver +* JSON-B +* JSP Page +* JSTL +* JTA +* Jukito +* JUnit +* Ka DI +* Keyczar +* Kibana +* KLogger +* Kodein +* Kotlin Logging +* KouInject +* KumuluzEE JTA +* LevelDB Client +* Liferay +* LiferayFaces +* Lift JTA +* Log.io +* Log4J +* Log4s +* Logback +* Logging Utils +* Logstash +* Lumberjack +* Macros +* Magicgrouplayout +* Mail +* Management EJB +* MapR +* MckoiSQLDB Driver +* Memcached +* Message (MDB) +* Micro DI +* Micrometer +* Microsoft SQL Driver +* MiGLayout +* MinLog +* Mixer +* Mockito +* MongoDB Client +* Monolog +* Morphia +* MRules +* Mule +* Mule Functional Test Framework +* MultithreadedTC +* Mycontainer JTA +* MyFaces +* MySQL Driver +* Narayana Arjuna +* Needle +* Neo4j +* NLOG4J +* Nuxeo JTA/JCA +* OACC +* OAUTH +* OCPsoft Logging Utils +* OmniFaces +* OpenFaces +* OpenPojo +* OpenSAML +* OpenWS +* OPS4J Pax Logging Service +* Oracle ADF +* Oracle DB Driver +* Oracle Forms +* Orion EJB XML +* Orion Web XML +* Oscache +* OTR4J +* OW2 JTA +* OW2 Log Util +* OWASP CSRF Guard +* OWASP ESAPI +* Peaberry +* Pega +* Persistence units +* Petals EIP +* PicketBox +* PicketLink +* PicoContainer +* Play +* Play Test +* Plexus Container +* Polyforms DI +* Portlet +* PostgreSQL Driver +* PowerMock +* PrimeFaces +* Properties +* Qpid Client +* RabbitMQ Client +* RandomizedTesting Runner +* Resource Adapter +* REST Assured +* Restito +* RichFaces +* RMI +* RocketMQ Client +* Rythm Template Engine +* SAML +* Santuario +* Scalate +* Scaldi +* Scribe +* Seam +* Security Realm +* ServiceMix +* Servlet +* ShiftOne +* Shiro +* Silk DI +* SLF4J +* Snippetory Template Engine +* SNMP4J +* Socket handler logging +* Spark +* Specsy +* Spock +* Spring +* Spring Batch +* Spring Boot +* Spring Boot Actuator +* Spring Boot Cache +* Spring Boot Flo +* Spring Cloud Config +* Spring Cloud Function +* Spring Data +* Spring Data JPA +* spring DI +* Spring Integration +* Spring JMX +* Spring Messaging Client +* Spring MVC +* Spring Properties +* Spring Scheduled +* Spring Security +* Spring Shell +* Spring Test +* Spring Transactions +* Spring Web +* SQLite Driver +* SSL +* Standard Widget Toolkit (SWT) +* Stateful (SFSB) +* Stateless (SLSB) +* Sticky Configured +* Stripes +* Struts +* SubCut +* Swagger +* SwarmCache +* Swing +* SwitchYard +* Syringe +* Talend ESB +* Teiid +* TensorFlow +* Test Interface +* TestNG +* Thymeleaf +* TieFaces +* tinylog +* Tomcat +* Tornado Inject +* Trimou +* Trunk JGuard +* Twirl +* Twitter Util Logging +* UberFire +* Unirest +* Unitils +* Vaadin +* Velocity +* Vlad +* Water Template Engine +* Web Services Metadata +* Web Session +* Web XML File +* WebLogic Web XML +* Webmacro +* WebSocket +* WebSphere EJB +* WebSphere EJB Ext +* WebSphere Web XML +* WebSphere WS Binding +* WebSphere WS Extension +* Weka +* Weld +* WF Core JTA +* Wicket +* Winter +* WSDL +* WSO2 +* WSS4J +* XACML +* XFire +* XMLUnit +* Zbus Client +* Zipkin diff --git a/docs/topics/mtr-using-openrewrite-recipes.adoc b/docs/topics/mtr-using-openrewrite-recipes.adoc new file mode 100644 index 0000000000..edede93f41 --- /dev/null +++ b/docs/topics/mtr-using-openrewrite-recipes.adoc @@ -0,0 +1,59 @@ +// Module included in the following module: +// +// * docs/cli-guide-mtr/master.adoc + +[id=using-openrewrite-recipes_{context}] += Using OpenRewrite recipes + +[IMPORTANT] +==== +OpenRewrite recipe support is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +See link:{KBArticleTechnologyPreview}[Technology Preview features support scope] on the Red Hat Customer Portal for information about the support scope for Technology Preview features. +==== + +You can refactor the source code of Java applications by using link:https://docs.openrewrite.org/[OpenRewrite] recipes with the {ProductShortName} CLI. + +For example, the OpenRewrite recipe `org.jboss.windup.JavaxToJakarta` renames imported `javax` packages to their `jakarta` equivalents. + +.Procedure + +. Run `windup-cli`, specifying the recipe name, the path to the configuration file, and the application: ++ +[source,terminal,subs="attributes+"] +---- +$ ./windup-cli --openrewrite --input \ + "-Drewrite.configLocation=" \ + "-DactiveRecipes=" --goal dryRun +---- + +* `"-DactiveRecipes="`: Specify the OpenRewrite recipe, for example, `org.jboss.windup.JavaxToJakarta`. + +* `--input`: Specify the application to be refactored. The application must be the top of the source code project containing a Maven Project Object Model (POM) XML file, `pom.xml`. + +* `-Drewrite.configLocation=` : The location of the `rewrite.yaml` configuration file to use. + The shipped `rewrite.yaml` configuration files are located in your +`<{ProductShortName}_HOME>/rules/openrewrite` subfolder, for example,`" -Drewrite.configLocation=<{ProductShortName}_HOME>/rules/openrewrite/jakarta/javax/imports/rewrite.yaml"`. + +* `"-DactiveRecipes="`: Specify the OpenRewrite recipe, for example, `org.jboss.windup.JavaxToJakarta`. ++ +You can include more than one recipe by specifying each in the `activeRecipes` parameter. For example, to include the recipes `org.jboss.windup.JavaxInjectToJakartaInject` and `org.jboss.windup.JavaxEjbToJakartaEjb"`, enter the following for `"-DactiveRecipes="`: ++ +[source, terminal,subs="attributes+"] +---- + "-DactiveRecipes=org.jboss.windup.JavaxInjectToJakartaInject, \ + org.jboss.windup.JavaxEjbToJakartaEjb" +---- + +* `--goal`: Optional: The OpenRewrite Maven goal to run. +** `dryRun` : The script returns a list of proposed changes. Ignore the `"Run 'mvn rewrite:run' to apply the recipes"` message. +** `run`: The script applies the changes. + +. Run `windup-cli` with `--goal run` to apply the recipe: ++ +[source,terminal,subs="attributes+"] +---- +$ ./windup-cli --openrewrite --input \ + "-Drewrite.configLocation=" \ + "-DactiveRecipes=" --goal run +---- diff --git a/docs/topics/mtr-validation-report-errors.adoc b/docs/topics/mtr-validation-report-errors.adoc new file mode 100644 index 0000000000..92b9d03350 --- /dev/null +++ b/docs/topics/mtr-validation-report-errors.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: PROCEDURE +[id="validation-report-understanding_{context}"] += Creating a validation report + +You can create a validation report for your custom rules. + +.Prerequisites + +* You must fork and clone the {ProductShortName} XML rules. +* You must have one or more test XML rules to validate. + +.Procedure + +. Navigate to the local `windup-rulesets` repository. + +. Create a directory for your custom rules and tests: `windup-rulesets/rules-reviewed/myTests`. + +. Copy your custom rules and tests to the `windup-rulesets/rules-reviewed/` directory. + +. Run the following command from the root directory of the `windup-rulesets` repository: ++ +---- +$ mvn -Dtest=WindupRulesMultipleTests -DrunTestsMatching= clean :report <1> <2> +---- +<1> Specify the directory containing your custom rules and tests. If you omit the `-DrunTestsMatching` argument, the validation report will include all the tests and take much longer to generate. +<2> Specify your report name. ++ +The validation report is created in the `windup-rulesets/target/site/` repository. diff --git a/docs/topics/mtr-validation-report.adoc b/docs/topics/mtr-validation-report.adoc new file mode 100644 index 0000000000..02cc3f30fb --- /dev/null +++ b/docs/topics/mtr-validation-report.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: CONCEPT +[id="validation-report_{context}"] += About validation reports + +Validation reports provide details about test rules and failures and contain the following sections: + +* *Summary* ++ +This section contains the total number of tests run and reports the number of errors and failures. It displays the total success rate and the time taken, in seconds, for the report to be generated. + +* *Package List* ++ +This section contains the number of tests executed for each package and reports the number of errors and failures. It displays the success rate and the time taken, in seconds, for each package to be analyzed. ++ +A single package named `org.jboss.windup.rules.tests` is displayed unless additional test cases have been defined. + +* *Test Cases* ++ +This section describes the test cases. Each failure includes a *Details* section that can be expanded to show the stack trace for the assertion, including a human-readable line indicating the source of the error. diff --git a/docs/topics/mtr-vs-code-extension-interface.adoc b/docs/topics/mtr-vs-code-extension-interface.adoc new file mode 100644 index 0000000000..514c9894fc --- /dev/null +++ b/docs/topics/mtr-vs-code-extension-interface.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: CONCEPT +[id="vs-code-extension-interface_{context}"] += {ProductShortName} extension interface + + + +The interface of the {ProductName} ({ProductShortName}) extension is designed to make it easier for you to find information and perform actions: + +* In the left pane, you can see a directory tree named *Analysis Results* with a report icon at its top. You can click the icon to open the {ProductShortName} report in your browser. Beneath the report icon are the other elements of the tree: the applications analyzed by {ProductShortName}, the rulesets used, and the issues discovered by the analysis. +* In the upper right pane, you can configure an analysis. +* In the lower right pane, you can see the settings of the configuration, including source, target, and advanced options. You can view the progress of an analysis in this pane. When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. + +.{ProductShortName} extension interface + +image::mtr-extension-interface.png[{ProductShortName} extension interface] + diff --git a/docs/topics/mtr-vs-code-extension-resolving-issues.adoc b/docs/topics/mtr-vs-code-extension-resolving-issues.adoc new file mode 100644 index 0000000000..152a4c6930 --- /dev/null +++ b/docs/topics/mtr-vs-code-extension-resolving-issues.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-resolving-issues_{context}"] += Resolving issues + +You can resolve issues by doing one of the following: + +* Using a _Quick Fix_ automatic code replacement +* Editing the code of a file with a hint + +You can keep track of resolved issues by using the *Delete* or *Mark as Complete* options. Files marked deleted or completed will be analyzed again the next time you analyze a project that contains them. + +== Using a Quick Fix + +You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. + +.Procedure + +. In the left pane, right-click an issue that has the Quick Fix icon (image:vs_optional.png[Optional or Quick Fix]) and select *Preview Quick Fix*. +. To accept the suggested fix, right-click the issue again and select *Apply Quick Fix.* +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. + +== Editing the code of a file + +You can edit the file of a project imported to VS Code. + +.Procedure + +. In the left pane, right-click an issue and select *Open Code*. +. Make any changes needed to the code and save the file. +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. diff --git a/docs/topics/mtr-vs-code-extension-reviewing-issues.adoc b/docs/topics/mtr-vs-code-extension-reviewing-issues.adoc new file mode 100644 index 0000000000..a9ccedab14 --- /dev/null +++ b/docs/topics/mtr-vs-code-extension-reviewing-issues.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-reviewing-issues_{context}"] += Reviewing issues + +You can use the {ProductShortName} extension icons to prioritize issues based on their severity. You can also see which issues have a _Quick Fix_ automatic code replacement. + +.Procedure + +. Select a run configuration directory on the left pane. +. Expand its folders to view the *Hints* generated for each application file. +. Select a hint to view the source code. +. Right-click a hint and select *View Details* to view the Rule ID and other information. +. Prioritize issues based on the following icons, which are displayed next to each hint: + +** image:vs_mandatory.png[Mandatory] : The issue must be fixed for a successful migration. +** image:vs_potential.png[Warning] : The issue might need to be addressed during migration. +** image:vs_optional.png[Optional or Quick Fix] : The issue is optional to fix for migration. This icon is also used to indicate any Quick Fixes available for an issue. diff --git a/docs/topics/mtr-vs-code-extension-run-configuration.adoc b/docs/topics/mtr-vs-code-extension-run-configuration.adoc new file mode 100644 index 0000000000..699367d22b --- /dev/null +++ b/docs/topics/mtr-vs-code-extension-run-configuration.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-run-configuration_{context}"] += Configuring a run configuration + +You can configure multiple run configurations to run against each project you import to VS Code. + +.Prerequisites + +* `windup-cli` executable installed. You can download the `windup-cli` executable from link:{DevDownloadPageURL}[{LC_PSN} download]. + +.Procedure + +. In *Extensions* view, click the {ProductName} icon (image:vs_extension_icon.png[{ProductShortName} code extension]) on the Activity bar. +. Click the *+* (plus sign) next to *{ProductName}* to add a run configuration. +. Complete the following configuration fields: + +** *Name*: Enter a meaningful name for the analysis configuration or accept the default. +** *cli*: Enter the path to the cli executable. For example: `$HOME/{LC_PSN}-cli-{ProductDistributionVersion}/bin/windup-cli`. +** *Input*: Set to the path of the project that you have open within your IDE by clicking *Add* and doing one of the following: + +*** Enter the input file or directory and press Enter. +*** Click *Open File Explorer* and select the directory. + +** *Target*: Select one or more target migration paths. + +. Right-click the run configuration and select *Run*. ++ +When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. diff --git a/docs/topics/mtr-web-adding-global-custom-labels.adoc b/docs/topics/mtr-web-adding-global-custom-labels.adoc new file mode 100644 index 0000000000..36e7fe26e4 --- /dev/null +++ b/docs/topics/mtr-web-adding-global-custom-labels.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-adding-global-custom-labels_{context}"] += Adding global custom labels + +{ProductShortName} includes a preconfigured set of global labels, which apply to all projects. + +You can define your own custom global labels. + +.Procedure + +. In the {WebName}, click *Labels configuration*. +. Click *Add label*. +. To upload a labelset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*. ++ +A labelset file must have a `.windup.label.xml` extension. The uploaded file is stored on the {ProductShortName} server. ++ +. To register the server path of a labelset file, click the *Server path* tab, enter the *Labels* path, and click *Save*. ++ +Registering the server path ensures that the {ProductShortName} server always uses the latest version of the labelset files. ++ +The *Custom labels* list displays the labels. diff --git a/docs/topics/mtr-web-adding-global-custom-rules.adoc b/docs/topics/mtr-web-adding-global-custom-rules.adoc new file mode 100644 index 0000000000..75e16e8dd9 --- /dev/null +++ b/docs/topics/mtr-web-adding-global-custom-rules.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-adding-global-custom-rules_{context}"] += Adding global custom rules + +{ProductShortName} includes a preconfigured set of global rules, which apply to all projects. + +You can define your own custom global rules. + +For information on writing custom {ProductShortName} rules, see the {ProductShortName} link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_]. + +.Procedure + +. In the {WebName}, click *Rules configuration*. +. Click *Add rules*. +. To upload a ruleset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*. ++ +A ruleset file must have a `.windup.xml` extension. The uploaded file is stored on the {ProductShortName} server. ++ +. To register the server path of a ruleset file, click the *Server path* tab, enter the *Rules* path, and click *Save*. ++ +Registering the server path ensures that the {ProductShortName} server always uses the latest version of the ruleset files. ++ +The *Custom rules* list displays the rules. diff --git a/docs/topics/mtr-web-create-project.adoc b/docs/topics/mtr-web-create-project.adoc new file mode 100644 index 0000000000..d5b47e4cf4 --- /dev/null +++ b/docs/topics/mtr-web-create-project.adoc @@ -0,0 +1,108 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-create-project_{context}"] += Creating a project + +You can create a project in the {WebName} with the *Create project* wizard. + +.Procedure + +. In the {WebName}, click *Projects*. +. Click *Create project*. +. Enter a unique name for the project, an optional description, and click *Next*. ++ +. To upload applications, click the *Upload* tab, click *Browse*, select the application files you want to upload, and click *Close*. ++ +Uploading applications stores them directly on the {ProductShortName} server. + +. To register a server path, click the *Server path* tab and enter the *Server-side path* of the application in the field. ++ +Registering the server path of an application ensures that {ProductShortName} always uses the latest version. +. Click *Next*. +. Click one or more transformation targets. ++ +image::web-console-transformation-targets.png[Transformation targets] +. Click *Next*. +. Select packages and click *>* to include them in the analysis. +. Click *Next*. ++ +. If you want to add a custom rule, click *Add rule*. ++ +See the link:{ProductDocRulesGuideURL}[{RulesDevBookName}] for more information. + +* To upload a ruleset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*. ++ +A ruleset file must have a `.windup.xml` extension. The uploaded file is stored on the {ProductShortName} server. ++ +* To register the server path of a ruleset file, click the *Server path* tab, enter the *Rules* path, and click *Save*. ++ +Registering the server path ensures that the {ProductShortName} server always uses the latest version of the ruleset files. ++ +. Click *Next*. ++ +. If you want to add a custom label, click *Add label*. +* To upload a labelset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*. ++ +A labelset file must have a `.windup.label.xml` extension. The uploaded file is stored on the {ProductShortName} server. ++ +* To register a server path, click the *Server path* tab, enter the *Labels path* of the label files in the field, and click *Save*. ++ +Registering the server path ensures that the {ProductShortName} server always uses the latest version of the labelset files. ++ +. Click *Next*. ++ +. Review the following *Advanced options* and make any necessary changes: + +* *Target* +* *Source* +* *Exclude tags*: Rules with these tags are not processed. +* *Additional classpath*: Enter a space-delimited list of additional `.jar` files or directories so that they are available for decompilation or other analysis. +* *Application name* +* *Mavenize group ID* +* *Ignore path*: Enter a path for files to exclude from analysis. +* *Export CSV*: Exports the report data as a CSV file. +* *Export Summary*: Generates an `analysisSummary.json` export file in the output directory. The file contains analysis summary information for each application analyzed, including the number of incidents and story points by category, and all of the technology tags associated with the analyzed applications. +* *Export reports zip*: Creates a `reports.zip` file in the output folder. The file contains the analysis output, typically, the reports. If requested, it can also contain the CSV export files. +* *Disable Tattletale*: Disables generation of a Tattletale report for each application. +* *Class Not Found analysis*: Enables analysis of Java files that are not available on the class path. ++ +[NOTE] +==== +This option should not be used if some classes are unavailable for analysis. +==== + +* *Compatible Files report*: Generating a Compatible Files report might take a long time for large applications. +* *Exploded app*: The input directory contains the unpackaged source files of an application. +* *Keep work dirs*: Retains temporary files, for example, the graph database or extracted archive files, for debugging purposes. +* *Skip reports*: HTML reports are not generated. Must be enabled if you enabled *Export CSV*. +* *Allow network access*: Validates any XML files within the analyzed applications against their schema. ++ +[NOTE] +==== +This option might reduce performance. +==== +* *Mavenize*: Creates a Maven project directory structure based on the structure and content of the application. +* *Source mode*: Indicates that the application files are raw source files, not compiled binaries. The sourceMode argument has been deprecated. There is no longer the need to specify it. MTR can intuitively process any inputs that are presented to it. In addition, project source folders can be analyzed with binary inputs within the same analysis execution. +* *Analyze known libraries*: Analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code. ++ +[NOTE] +==== +This option might result in a longer execution time and a large number of migration issues being reported. +==== +* *Transaction analysis*: [Tech Preview] Generates a Transactions report that displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks, such as Hibernate. ++ +[NOTE] +==== +Transaction analysis is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them +in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +==== +* *Skip source code reports:* Adding this option skips generating a _Source code report_ when generating the application analysis report. Use this advanced option when concerned about source code information appearing in the application analysis. + +. Click *Next*. ++ +. Review your project and click *Save* or *Save and run*. ++ +The project is displayed in the *Projects* screen. diff --git a/docs/topics/mtr-web-openshift-insufficient-resources.adoc b/docs/topics/mtr-web-openshift-insufficient-resources.adoc new file mode 100644 index 0000000000..106b028d1e --- /dev/null +++ b/docs/topics/mtr-web-openshift-insufficient-resources.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-openshift-insufficient-resources_{context}"] += Resolving insufficient resources + +The following conditions indicate insufficient resources: + + * The `{LC_PSN}-web-console` pod is not running and the following error is displayed on the *Events* tab of the *Pod Details* screen in the OpenShift console: ++ +[source,terminal,subs="attributes+"] +---- +0/9 nodes are available: 4 Insufficient cpu, 4 MatchNodeSelector, 9 Insufficient memory. +---- + +* The `{LC_PSN}-web-console-deploy`, `{LC_PSN}-web-console-executor-deploy`, and `{LC_PSN}-web-console-postgresql-deploy` pods time out and the following error is displayed in the logs: ++ +[source,terminal,subs="attributes+"] +---- +error: update acceptor rejected {LC_PSN}-web-console-executor-1: Pods for rc '{LC_PSN}/{LC_PSN}-web-console-executor-1' took longer than 600 seconds to become available +---- + +.Procedure + +. Install and run the link:{OpenShiftDocsURL}/nodes/clusters/nodes-cluster-resource-levels.html[cluster capacity tool] to determine how many pods you can schedule. + +. Change the load on the cluster resources by performing one of the following actions: + +* Increase the link:{OpenShiftDocsURL}/nodes/clusters/nodes-cluster-limit-ranges.html[limit ranges] or the link:{OpenShiftDocsURL}/applications/quotas/quotas-setting-per-project.html[resource quotas] of your project. +* Reduce the requested resources of your project. The {WebName} requires a minimum of 4 vCPUs and 8 GB RAM. +* Run fewer jobs. + +. Redeploy the {WebName}. diff --git a/docs/topics/mtr-web-openshift-no-route-to-host-error.adoc b/docs/topics/mtr-web-openshift-no-route-to-host-error.adoc new file mode 100644 index 0000000000..77a97d5e53 --- /dev/null +++ b/docs/topics/mtr-web-openshift-no-route-to-host-error.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: REFERENCE +[id="web-openshift-no-route-to-host-error_{context}"] += `No route to host` error + +The `No route to host` error in the `{LC_PSN}-web-console-executor` log indicates that the `{LC_PSN}-web-console-executor` pod cannot connect to the `{LC_PSN}-web-console` pod: + +[source,terminal,subs="attributes+"] +---- +13:44:03,501 SEVERE [org.jboss.windup.web.messaging.executor.ExecutorBootstrap] (main) Could not start messaging listener due to: Failed to connect to any server. Servers tried: [http-remoting://192.0.2.4:8080 (java.net.NoRouteToHostException: No route to host)]: javax.naming.CommunicationException: Failed to connect to any server. Servers tried: [http-remoting://192.0.2.4:8080 (java.net.NoRouteToHostException: No route to host)] +---- + +This error occurs because the `{LC_PSN}-web-console-executor` pod starts running before the `{LC_PSN}-web-console` pod. + +Check the `{LC_PSN}-web-console-executor` log after the `{LC_PSN}-web-console` pod has been running for a few minutes. diff --git a/docs/topics/mtr-web-review-reports.adoc b/docs/topics/mtr-web-review-reports.adoc new file mode 100644 index 0000000000..803cd462c6 --- /dev/null +++ b/docs/topics/mtr-web-review-reports.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-review-reports_{context}"] += Reviewing reports + +The {ProductShortName} {WebName} provides a set of detailed reports that can help you decide if you need to make any changes to your applications. You access these reports from the *Analysis results* screen. + +The reports are described in detail in link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. + +.Procedure +. In the {WebName}, click *Analysis results*. +. Click the *Reports* icon {reports} beside the analysis you want to investigate. ++ +The *All applications* screen of the reports is displayed. ++ +image::3-1-applications.png[Analysis logs screen] diff --git a/docs/topics/mtr-web-running-saved-analysis.adoc b/docs/topics/mtr-web-running-saved-analysis.adoc new file mode 100644 index 0000000000..835b7e63b0 --- /dev/null +++ b/docs/topics/mtr-web-running-saved-analysis.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-running-saved-analysis_{context}"] += Running a saved analysis + +You can run a saved analysis. + +.Procedure + +. In the {WebName}, click *Analysis results*. +. Select a project. +. Click *Run analysis*. + +A progress bar displays the progress of your analysis. diff --git a/docs/topics/mtr-web-updating-an-analysis.adoc b/docs/topics/mtr-web-updating-an-analysis.adoc new file mode 100644 index 0000000000..6b351558eb --- /dev/null +++ b/docs/topics/mtr-web-updating-an-analysis.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-updating-an-analysis_{context}"] += Updating an analysis configuration + +You can update an analysis configuration, for example, with a different transformation target, advanced option, or a custom rule. Then you can run the updated analysis in your project. + +.Procedure + +. In the {WebName}, click *Analysis configuration*. ++ +image::3-5-analysis-configuration-mtr-1-2.png[Analysis configuration screen] +. Select a *Project*. +. Click the appropriate tabs and make your changes. +. Click *Save* or *Save and run*. ++ +The project is displayed in the *Projects* screen. diff --git a/docs/topics/mtr-web-view-results.adoc b/docs/topics/mtr-web-view-results.adoc new file mode 100644 index 0000000000..81be04d029 --- /dev/null +++ b/docs/topics/mtr-web-view-results.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * docs/web-console-guide/master.adoc + +:_content-type: PROCEDURE +[id="web-view-results_{context}"] += Viewing analysis results + +The results of all analyses are grouped and listed by project on the *Analysis results* screen. + +.Procedure + +. In the {WebName}, click *Analysis results*. +. Select a project from the list. + ++ +image::AnalysisResults1.png[Analysis results screen] ++ +The Analysis Reports can be accessed via the Reports bar chart icon or by the Reports action on the right-hand side of the screen. +. Click on the number of the analysis you want to review to see details of the analysis configuration settings and the analysis execution statistics. ++ +The results are displayed in the *Results* screen, which contains two tabs: *Details* and *Logs*. + +The *Details* tab displays important details of the analysis, such as status, start date, duration, and configuration settings. + +.Analysis details screen +image::AnalysisResults2.png[Analysis details screen] + +The *Logs* tab displays the logs generated during the analysis. + +.Analysis logs screen +image::AnalysisLogs.png[Analysis logs screen] diff --git a/docs/topics/mtr-what-is-the-toolkit.adoc b/docs/topics/mtr-what-is-the-toolkit.adoc new file mode 100644 index 0000000000..21d95fbc03 --- /dev/null +++ b/docs/topics/mtr-what-is-the-toolkit.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * docs/getting-started-guide/master.adoc +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc +// * docs/eclipse-code-ready-studio-guide/master.adoc +// * docs/web-console-guide/master.adoc + +[[about_mta]] +:_content-type: CONCEPT +[id="what-is-the-toolkit_{context}"] += About the {ProductName} + +[discrete] +== What is the {ProductName}? + +The {ProductName} ({ProductShortName}) is an extensible and customizable rule-based tool that simplifies the migration and modernization of Java applications. + +{ProductShortName} examines application artifacts, including project source directories and application archives, and then produces an HTML report highlighting areas needing changes. {ProductShortName} supports many migration paths, including the following examples: + +* Upgrading to the latest release of Red Hat JBoss Enterprise Application Platform +* Migrating from Oracle WebLogic or IBM WebSphere Application Server to Red Hat JBoss Enterprise Application Platform +* Containerizing applications and making them cloud-ready +* Migrating from Java Spring Boot to Quarkus +* Updating from Oracle JDK to OpenJDK +* Upgrading from OpenJDK 8 to OpenJDK 11 +* Upgrading from OpenJDK11 to OpenJDK 17 +* Migrating EAP Java applications to Azure +* Migrating Spring Boot Java applications to Azure + +For more information about use cases and migration paths, see the link:https://developers.redhat.com/products/{LC_PSN}/use-cases[{ProductShortName} for developers] web page. + +[discrete] +== How does the {ProductName} simplify migration? + +The {ProductName} looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application. + +{ProductShortName} generates a detailed report evaluating a migration or modernization path. This report can help you to estimate the effort required for large-scale projects and to reduce the work involved. + +ifndef::getting-started-guide[] +[discrete] +== How do I learn more? + +See the link:{ProductDocIntroToMTAGuideURL}[Introduction to the {DocInfoProductName}] to learn more about the features, supported configurations, system requirements, and available tools in the {ProductName}. +endif::getting-started-guide[] diff --git a/docs/topics/mtr-where-syntax.adoc b/docs/topics/mtr-where-syntax.adoc new file mode 100644 index 0000000000..bd2e2beb14 --- /dev/null +++ b/docs/topics/mtr-where-syntax.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: REFERENCE +[id="where-syntax_{context}"] += `` syntax + +You can define parameters that specify a matching pattern to be used in other elements of an XML rule. This can help simplify the patterns for complex matching expressions. + +Use the `` element to define a parameter. Specify the parameter name using the `param` attribute and supply the pattern using the `` element. This parameter can then be referenced elsewhere in the rule definition using the syntax `{}`. + +You can view the link:http://windup.jboss.org/schema/windup-jboss-ruleset.xsd[complete XML rule schema]. + +The following example rule defines a parameter named `subpackage` that specifies a pattern of `(activeio|activemq)`. + +[source,xml,subs="attributes+"] +---- + + + + + + + ... + + + + + +---- + +The pattern defined by `subpackage` will then be substituted in the `` `references` attribute. This causes the rule to match on [x-]`org.apache.activeio.*` and `org.apache.activemq.*` packages. diff --git a/docs/topics/mtr-xml-rule-perform-syntax.adoc b/docs/topics/mtr-xml-rule-perform-syntax.adoc new file mode 100644 index 0000000000..aca564a7c0 --- /dev/null +++ b/docs/topics/mtr-xml-rule-perform-syntax.adoc @@ -0,0 +1,672 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: REFERENCE +[id="xml-rule-when-syntax_{context}"] += `` syntax + +Conditions allowed in the `when` portion of a rule must extend http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/GraphOperation.html[GraphOperation] and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave. + +The complete XML rule schema is located here: http://windup.jboss.org/schema/windup-jboss-ruleset.xsd. + +The following sections describe the more common XML `when` rule conditions. + +* condition syntax +* condition syntax +* condition syntax +* condition syntax +* condition syntax +* condition syntax +* condition syntax +* condition syntax +* condition syntax + +By default, if more than one `when` rule condition is provided, then all conditions must be met for the rule to match. + +[id="javaclass-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to find imports, methods, variable declarations, annotations, class implementations, and other items related to Java classes. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/java/condition/JavaClass.html[JavaClass] class. + +The following is an example of a rule that tests for WebLogic-specific Apache XML packages: + +[source,xml,subs="attributes+"] +---- + + + + + + + + Code using this package should be replaced with code using the org.apache.xml package from [Apache + Xerces](http://xerces.apache.org/). + + + + +---- + +=== Construct a element + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|references +|CLASS_NAME +a|The package or class name to match on. Wildcard characters can be used. This attribute is required. + +NOTE: For performance reasons, you should not start the reference with wildcard characters. For example, use [x-]`weblogic.apache.xml.{*}` instead of [x-]`{web}.apache.xml.{*}`. + +[options="nowrap"] +---- +references="weblogic.apache.xml.{*}" +---- +|matchesSource +|STRING +a|An exact regex to match. This is useful to distinguish hard-coded strings. This attribute is required. + +[options="nowrap"] +---- +matchesSource="log4j.logger" +---- + +|as +|VARIABLE_NAME +a|A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. + +[options="nowrap"] +---- +as="MyEjbRule" +---- + +|from +|VARIABLE_NAME +a|Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. + +[options="nowrap"] +---- +from="MyEjbRule" +---- + +|in +|PATH_FILTER +a|Filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. + +[options="nowrap"] +---- +in="{*}File1" +---- + +|==== + +==== child elements + +[cols="1,4", options="header"] +|==== +|Child Element +|Description + +| +a|The location where the reference was found in a Java class. Location can refer to annotations, field and variable declarations, imports, and methods. For the complete list of valid values, see the JavaDoc for http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/ast/java/data/TypeReferenceLocation.html[TypeReferenceLocation]. + +[source,xml,subs="attributes+"] +---- +IMPORT +---- + +| +a|Match on literal values inside of annotations. + +The following example matches on `@MyAnnotation(myvalue="test")`. + +[source,xml,subs="attributes+"] +---- + + ANNOTATION + + +---- + +Note that in this case, the `` refers to an annotation (`@MyAnnotation`), so the top-level annotation filter, `` must specify the `name` attribute. If the `` referred to a class that is annotated, then the top-level annotation filter used would be ``. + +| +a|Match on a particular annotation type. You can supply subconditions to be matched against the annotation elements. + +The below example would match on a `Calendar` field declaration annotated with `@MyAnnotation(myvalue="test")`. + +[source,xml,subs="attributes+"] +---- + + FIELD_DECLARATION + + + + +---- + +| +a|Match on an item in an array within an annotation. If an array index is not specified, the condition will be matched if it applies to any item in the array. You can supply subconditions to be matched against this element. + +The below example would match on `@MyAnnotation(mylist={"one","two"})`. + +[source,xml,subs="attributes+"] +---- + + ANNOTATION + + + + +---- + +Note that in this case, the `` refers to an annotation (`@MyAnnotation`), so the top-level annotation filter, `` must specify the `name` attribute. If the `` referred to a class that is annotated, then the top-level annotation filter used would be ``. + +|==== + +[id="xmlfile-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to find information in XML files. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/xml/condition/XmlFile.html[XmlFile] class. + +The following is an example of a rule that tests for an XML file: + +---- + + + + + + + + + Container Auth + + + + +---- + +=== Construct an element + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|matches +|XPATH +a|Match on an XML file condition. + +[options="nowrap"] +---- +matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']" +---- + +|xpathResultMatch +|XPATH_RESULT_STRING +a|Return results that match the given regex. + +[options="nowrap"] +---- + +---- + +|as +|VARIABLE_NAME +a|A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. + +[options="nowrap"] +---- +as="MyEjbRule" +---- + +|in +|PATH_FILTER +a|Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. + +[options="nowrap"] +---- +in="{*}File1" +---- + +|from +|VARIABLE_NAME +a|Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. + +[options="nowrap"] +---- +from="MyEjbRule" +---- + +|public-id +|PUBLIC_ID +a|The DTD public-id regex. + +[options="nowrap"] +---- +public-id="public" +---- + +|==== + +==== `matches` custom functions + +The `matches` attribute may use several built-in custom XPath functions, +which may have useful side effects, like setting the matched value on the rule variables stack. + +[cols="1,1", options="header"] +|==== +|Function +|Description + +|`windup:matches()` +a|Match a XPath expression against a string, possibly containing {ProductShortName} parameterization placeholders. + +[options="nowrap"] +---- +matches="windup:matches(//foo/@class, '{javaclassname}')" +---- +This will match all `` elements with a `class` attribute and store their value into `javaclassname` parameter for each iteration. + +|==== + +==== child elements + +[cols="1,4", options="header"] +|==== +|Child element +|Description + +| +a|The namespace referenced in XML files. This element contains two optional attributes: The `prefix` and the `uri`. + +[source,xml,subs="attributes+"] +---- + +---- + +|==== + +[id="project-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to query the Maven POM file for the project characteristics. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/project/condition/Project.html[Project] class. + +The following is an example of a rule that checks for a JUnit dependency version between 2.0.0.Final and 2.2.0.Final. +[source,xml,subs="attributes+"] +---- + + + + + + + + + + +---- + +=== Construct a element + +==== element attributes + +The `` element is used to match against the project's Maven POM file. You can use this condition to query for dependencies of the project. It does not have any attributes itself. + +==== child elements + +[cols="1,4", options="header"] +|==== +|Child element +|Description + +| +a|Subcondition used within `` to query against project dependencies. The `` element attributes are described below. +|==== + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|groupId +|PROJECT_GROUP_ID +|Match on the project `` of the dependency. + +|artifactId +|PROJECT_ARTIFACT_ID +|Match on the project `` of the dependency. + +|fromVersion +|FROM_VERSION +|Specify the lower version bound of the artifact. For example `2.0.0.Final`. + +|toVersion +|TO_VERSION +|Specify the upper version bound of the artifact. For example `2.2.0.Final`. +|==== + +It is possible to qualify the element within the POM file that contains the artifact that the rule is searching for. +This is achieved using the optional `` element. +The example below shows a rule that is searching for an artifact within the `` element of the POM file. + +image::search_for_artifact.png[rule searching for artifact] + +The valid list of locations is as follows: + +* DEPENDENCY_MANAGEMENT +* DEPENDENCIES +* PLUGIN_MANAGEMENT +* PLUGINS +* PARENT + +[id="filecontent-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to find strings or text within files, for example, a line in a Properties file. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/files/condition/FileContent.html[FileContent] class. + +=== Construct a element + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|pattern +|String +|Match the file contents against the provided parameterized string. This attribute is required. + +|filename +|String +|Match the file names against the provided parameterized string. + +|as +|VARIABLE_NAME +a|A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. + +[options="nowrap"] +---- +as="MyEjbRule" +---- + +|from +|VARIABLE_NAME +a|Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. + +[options="nowrap"] +---- +from="MyEjbRule" +---- + +|==== + + +[id="file-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to find the existence of files with a specific name, for example, an `ibm-webservices-ext.xmi` file. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/files/condition/File.html[File] class. + +=== Construct a element + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|filename +|String +|Match the file names against the provided parameterized string. This attribute is required. + +|as +|VARIABLE_NAME +a|A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. + +[options="nowrap"] +---- +as="MyEjbRule" +---- + +|from +|VARIABLE_NAME +a|Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. + +_Example:_ + +[options="nowrap"] +---- +from="MyEjbRule" +---- + +|==== + +[id="has-hint-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to test whether a file or line has a hint already associated with it. It is primarily used to prevent firing if a hint already exists, or to implement rules for default execution when no other conditions apply. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/HasHint.html[HasHint] class. + +The following is an example of a rule that checks to see if a hint exists for an IBM JMS destination message, and if not, includes it. + +[source,xml,subs="attributes+"] +---- + + + + + + + + + + + + + + + JMS `{package}.{prefix}{type}Message` messages represent the actual data passed through JMS destinations. This reference should be + replaced with the Java EE standard API `javax.jms.{type}Message`. + + + jms + websphere + + + + + + + + + + + + + + +---- + +=== Construct a + +The `` element is used to determine if a hint exists for a file or line. It does not have any child elements. + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|message +|String +|An optional argument allowing you to match the hint against the provided message string. +|==== + +[id="has-classification-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to test whether a file or line has a classification. It is primarily used to prevent firing if a classification already exists, or to implement rules for default execution when no other conditions apply. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/HasClassification.html[HasClassification] class. + +=== Construct a + +The `has-classification` element is used to determine if a specified classification exists. It does not have any child elements. + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute name +|Type +|Description + +|title +|String +|An optional title to match the classification against. +|==== + +[id="graph-query-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to search the generated graph for any elements. This element is primarily used to search for specific archives. For a better understanding of the `` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/parser/xml/when/QueryHandler.html[QueryHandler] class. + +The following is an example of a rule that tests to determine if any `ehcache` packages are found. + +[source,xml,subs="attributes+"] +---- + + + + .*ehcache.*\.jar$ + + + + + + The application embeds an Ehcache library. + + Cloud readiness issue as potential state information that is not persisted to a backing service. + + + Ehcache (embedded) + + +---- + +=== Construct a + +==== element attributes + +[cols="1,1,3", options="header"] +|==== +|Attribute Name +|Type +|Description + +|discriminator +|MODEL_TYPE +|The type of model to use for searching. This can be any valid model; however, it is recommended to use the `JarArchiveModel` for examining archives. This attribute is required. + +|as +|VARIABLE_NAME +a|A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. + +[source,terminal,subs="attributes+"] +---- +as="MyEjbRule" +---- + +|from +|VARIABLE_NAME +a|Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. + +[source,terminal,subs="attributes+"] +---- +from="MyEjbRule" +---- +|==== + +==== properties + +[cols="1,1,3", options="header"] +|==== +|Property Name +|Type +|Description + +|name +|String +|The name of the attribute to match against within the chosen model. When using any file-based models, it is recommended to match on `fileName`. This attribute is required. + +|type +|property-type +|Defines the expected type of property, either `STRING` or `BOOLEAN`. + +|searchType +|property-search-type +|Defines how the condition is matched. If set to `equals`, then an exact match must be made. If using `regex`, then regular expressions can be used. + +|==== + +[id="dependency-syntax_{context}"] +== syntax + +=== Summary + +Use the `` element to search dependencies defined within the application's POM file to determine whether they are supported by the target runtime. + +The following is an example of a rule that checks for all artifacts belonging to the `org.springframework.boot` group that have a version up to, and including, 1.6.0. + +[source,xml,subs="attributes+"] +---- + + + + + + + + + Spring Boot has to be updated to Spring Boot 2.0 before being able to be migrated to a version supported by Red Hat Runtimes + + + + + + +---- diff --git a/docs/topics/mtr-xml-rule-syntax.adoc b/docs/topics/mtr-xml-rule-syntax.adoc new file mode 100644 index 0000000000..1e9bfd2e7f --- /dev/null +++ b/docs/topics/mtr-xml-rule-syntax.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_content-type: REFERENCE +[id="xml-rule-syntax_{context}"] += XML rule structure + +This section describes the basic structure of XML rules. All XML rules are defined as elements within rulesets. For more details, see the link:http://windup.jboss.org/schema/windup-jboss-ruleset.xsd[{ProductShortName} XML rule schema]. + +== Rulesets + +A ruleset is a group of one or more rules that targets a specific area of migration. This is the basic structure of the `` element. + +* ****: Defines this as an {ProductShortName} ruleset and gives it a unique ruleset ID. +** ****: The metadata about the ruleset. +*** ****: The description of the ruleset. +*** ****: The rule add-ons required by this ruleset. +*** ** **: The source technology. +*** ** **: The target technology. +*** ** **: Setting to `true` indicates that rules in this ruleset override rules with the same ID from the core ruleset distributed with {ProductShortName}. Both the ruleset id and the rule id must match a rule within the core ruleset, or the rule will be ignored. In addition, the target technology in this ruleset must match one of the targets that you specified for running the analysis. ++ +This is `false` by default. +** ****: A set of individual rules. +*** ****: Defines the rule and gives it a unique ID. It is recommended to include the ruleset ID as part of the rule ID, for example, ``. One or more rules can be defined for a ruleset. +**** ****: The conditions to match on. +**** ****: The action to be performed when the rule condition is matched. +**** ****: The action to be performed when the rule condition is not matched. This element takes the same child elements as the `` element. +**** ****: A string pattern defined as a parameter, which can be used elsewhere in the rule definition. +*** ****: Maps an extension to a graph type. +*** ****: Maps from a package pattern (regular expression) to an organization name. + +== Predefined rules + +{ProductShortName} provides predefined rules for common migration requirements. These core {ProductShortName} rules are located in the {ProductShortName} installation at `<{ProductShortName}_HOME>/rules/migration-core/`. + +The following is an example of a core {ProductShortName} rule that matches on a proprietary utility class. + +[source,xml,subs="attributes+"] +---- + + + + + + This ruleset provides analysis of WebLogic proprietary classes and constructs that may require individual attention when migrating to JBoss EAP 6+. + + + + + + + + reviewed-2015-06-02 + weblogic + + + ... + + + + + + + Replace with the `StringUtils` class from Apache Commons. + + weblogic + + + + ... + + +---- diff --git a/docs/vs-code-extension-guide-mtr/master.adoc b/docs/vs-code-extension-guide-mtr/master.adoc index 5342c6f1eb..182671c1cd 100644 --- a/docs/vs-code-extension-guide-mtr/master.adoc +++ b/docs/vs-code-extension-guide-mtr/master.adoc @@ -18,31 +18,31 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the VS Code extension -include::topics/about-ide-addons.adoc[leveloffset=+2] +include::topics/mtr-about-ide-addons.adoc[leveloffset=+2] // About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] // Install the extension -include::topics/installing-vs-code-extension.adoc[leveloffset=+1] +include::topics/mtr-installing-vs-code-extension.adoc[leveloffset=+1] [id="analyzing-projects-with-vs-code-extension_{context}"] == Analyzing your projects with the {ProductShortName} extension You can analyze your projects with the {ProductShortName} extension by creating a run configuration and running an analysis. -include::topics/vs-code-extension-interface.adoc[leveloffset=+2] +include::topics/mtr-vs-code-extension-interface.adoc[leveloffset=+2] -include::topics/vs-code-extension-run-configuration.adoc[leveloffset=+2] +include::topics/mtr-vs-code-extension-run-configuration.adoc[leveloffset=+2] [id="reviewing-and-resolving-issues-with-vs-code-extension_{context}"] == Reviewing and resolving migration issues You can review and resolve migration issues identified by the {ProductShortName} extension in the left pane. -include::topics/vs-code-extension-reviewing-issues.adoc[leveloffset=+2] +include::topics/mtr-vs-code-extension-reviewing-issues.adoc[leveloffset=+2] -include::topics/vs-code-extension-resolving-issues.adoc[leveloffset=+2] +include::topics/mtr-vs-code-extension-resolving-issues.adoc[leveloffset=+2] :!vsc-extension-guide: diff --git a/docs/web-console-guide-mtr/master.adoc b/docs/web-console-guide-mtr/master.adoc index 963b4679f8..bc82f10b7b 100644 --- a/docs/web-console-guide-mtr/master.adoc +++ b/docs/web-console-guide-mtr/master.adoc @@ -16,22 +16,22 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the {WebConsoleBookName} -include::topics/about-console-guide.adoc[leveloffset=+2] +include::topics/mtr-about-console-guide.adoc[leveloffset=+2] // About {ProductName} -include::topics/what-is-the-toolkit.adoc[leveloffset=+2] +include::topics/mtr-what-is-the-toolkit.adoc[leveloffset=+2] // About the {WebName} -include::topics/about-the-web-console.adoc[leveloffset=+2] +include::topics/mtr-about-the-web-console.adoc[leveloffset=+2] == Installing the {WebName} You can install the {WebName} on Linux, Windows, macOS, or {ocp-full}. // Installing on Linux, Windows, macOS -include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2] +include::topics/mtr-installing-web-console-or-cli-tool.adoc[leveloffset=+2] // Installing on OCP -include::topics/installing-web-console-on-openshift.adoc[leveloffset=+2] +include::topics/mtr-installing-web-console-on-openshift.adoc[leveloffset=+2] ==== Troubleshooting a {WebName} installation on OpenShift @@ -41,9 +41,9 @@ This section describes how to troubleshoot a {WebName} installation on OpenShift include::topics/proc_web-downloading-logs-console.adoc[leveloffset=+4] //Downloading logs with the CLI -include::topics/proc_web-downloading-logs-cli.adoc[leveloffset=+4] -include::topics/web-openshift-no-route-to-host-error.adoc[leveloffset=+4] -include::topics/web-openshift-insufficient-resources.adoc[leveloffset=+4] +include::topics/mtr-proc_web-downloading-logs-cli.adoc[leveloffset=+4] +include::topics/mtr-web-openshift-no-route-to-host-error.adoc[leveloffset=+4] +include::topics/mtr-web-openshift-insufficient-resources.adoc[leveloffset=+4] // Reporting issues @@ -60,28 +60,28 @@ Each project groups the applications for a specific analysis, which you can conf The analysis process generates reports that describe the readiness of your applications for migration or modernization. // Creating a project -include::topics/web-create-project.adoc[leveloffset=+2] +include::topics/mtr-web-create-project.adoc[leveloffset=+2] // Running a saved analysis -include::topics/web-running-saved-analysis.adoc[leveloffset=+2] +include::topics/mtr-web-running-saved-analysis.adoc[leveloffset=+2] // Viewing the Results of an Analysis -include::topics/web-view-results.adoc[leveloffset=+2] +include::topics/mtr-web-view-results.adoc[leveloffset=+2] // Review the Reports -include::topics/web-review-reports.adoc[leveloffset=+2] +include::topics/mtr-web-review-reports.adoc[leveloffset=+2] //Reconfigure Analysis -include::topics/web-updating-an-analysis.adoc[leveloffset=+2] +include::topics/mtr-web-updating-an-analysis.adoc[leveloffset=+2] // Using Custom Rules -include::topics/web-adding-global-custom-rules.adoc[leveloffset=+2] +include::topics/mtr-web-adding-global-custom-rules.adoc[leveloffset=+2] // Using Custom Labels -include::topics/web-adding-global-custom-labels.adoc[leveloffset=+2] +include::topics/mtr-web-adding-global-custom-labels.adoc[leveloffset=+2] // Require Authentication for {ProductWebName} -include::topics/configuring-web-console-authentication-for-linux-windows-macos.adoc[leveloffset=+1] +include::topics/mtr-configuring-web-console-authentication-for-linux-windows-macos.adoc[leveloffset=+1] // TODO: eventually add steps for reverting back to no auth required