diff --git a/docs/cli-guide/master.adoc b/docs/cli-guide/master.adoc index 503288d9ec..14c138294f 100644 --- a/docs/cli-guide/master.adoc +++ b/docs/cli-guide/master.adoc @@ -53,25 +53,25 @@ include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] include::topics/access-report.adoc[leveloffset=+2] // Review the Reports -include::topics/review-reports.adoc[leveloffset=+1] +include::topics/mta-review-reports.adoc[leveloffset=+1] // Export the Report in CSV Format -include::topics/csv-export.adoc[leveloffset=+1] +// include::topics/csv-export.adoc[leveloffset=+1] // Mavenize Your Application -include::topics/mavenize.adoc[leveloffset=+1] +// include::topics/mavenize.adoc[leveloffset=+1] // Optimize {ProductShortName} Performance -include::topics/optimize-performance.adoc[leveloffset=+1] +include::topics/mta-optimize-performance.adoc[leveloffset=+1] // Configure {ProductShortName} to Exclude Files and Packages -include::topics/exclude-files-and-packages.adoc[leveloffset=+2] +// include::topics/mta-exclude-files-and-packages.adoc[leveloffset=+2] [appendix] == Reference material // {ProductShortName} Command-line Arguments -include::topics/cli-args.adoc[leveloffset=+2] +include::topics/mta-cli-args.adoc[leveloffset=+2] // Added in 4.3.0: list of supported Tech Tags include::topics/tech-tags.adoc[leveloffset=+2] diff --git a/docs/topics/mta-cli-args.adoc b/docs/topics/mta-cli-args.adoc new file mode 100644 index 0000000000..7b840c0f61 --- /dev/null +++ b/docs/topics/mta-cli-args.adoc @@ -0,0 +1,213 @@ +// 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, for example when executing from a script, you must use the following arguments: + +* `--overwrite` +* `--input` +* `--target` +==== + + +.{ProductShortName} CLI arguments +[cols="40%,60%a",options="header",] +|==== +|Argument |Description +|--analyze-known-libraries | 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. +==== + +|--help |Display the {ProductShortName} help message. +|--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. +| --list-sources +| list rules for available migration sources +|--list-sources | Flag to list all available source technologies. +|--list-targets| Flag to list all available target technologies. +|--output |Specify the path to the directory to output the report information generated by {ProductShortName}. + +[IMPORTANT] +==== +Do not overwrite a report output directory that contains important information. +==== +| --rules stringArray | Filename or directory containing rule files +| --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. +|--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 `--list-targets` argument to list all available targets. +|==== + +[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}"] +== Analyze application source code + +Usage: `{mta-cli} analyze [flags]` + +The following flags are available: + +.{ProductShortName} Analyze application +[cols="40%,60%a",options="header",] +|==== +|Flag |Description + +| --analyze-known-libraries +| analyze known open-source libraries + +| -h, --help +| help for analyze + +| -i, --input string +| path to application source code or a binary + +| --json-output +| create analysis and dependency output as json + +| --list-sources +| list rules for available migration sources + +| --list-targets +| list rules for available migration targets + +| -l, --label-selector string +| run rules based on specified label selector expression + +| --maven-settings string +| path to a custom maven settings file to use + +| --overwrite +| overwrite output directory + +| --skip-static-report +| do not generate static report + +| -m, --mode string +| analysis mode" `full` (default) or `source-only` + +| -o, --output string | path to the directory for analysis output + +| --rules stringArray | filename or directory containing rule files + +| --skip-static-report +| do not generate static report + +| -s, --source string +| source technology to consider for analysis. To specify multiple sources, repeat the parameter: --source --source etc. + +| -t, --target string +| target technology to consider for analysis. To specify multiple targets, repeat the parameter: --target --target etc. +|==== + +[id="cli-input-file-type-arguments-global-flags_{context}"] +=== Global flags + +.{ProductShortName} Analyze application +[cols="40%,60%a",options="header",] +|==== + +|Flag +|Description + +| --log-level uint32 +| log level (default 4) + +| --no-cleanup +| do not cleanup temporary resources +|==== + + + +[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 +---- + +* The `--output` argument is mandatory. If omitted, an error is returned: ++ +[source,options="nowrap",subs="attributes+"] +---- +Error: required flag(s) "output" not set +---- + +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 `--list-sources` 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 eap5`. + +[WARNING] +==== +When migrating to JBoss EAP, be sure to specify the version, for example, `eap6`. 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 provide a target, mta-cli analyzes the input based on the source and discovery rules. Use the `--list-targets` 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 eap7`. + +[WARNING] +==== +When migrating to JBoss EAP, be sure to specify the version in the target, for example, `eap6`. 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+"] +---- +---- + +* 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. + +//// diff --git a/docs/topics/mta-exclude-files-and-packages.adoc b/docs/topics/mta-exclude-files-and-packages.adoc new file mode 100644 index 0000000000..9a7c988c13 --- /dev/null +++ b/docs/topics/mta-exclude-files-and-packages.adoc @@ -0,0 +1,18 @@ +// 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="ignored-locations_{context}"] +== Searching locations for exclusion + +{ProductShortName} searches the following locations: + +* `~/.{LC_PSN}/ignore/` +* `~/.windup/ignore/` +* `<{ProductShortName}_HOME>/ignore/` + diff --git a/docs/topics/mta-optimize-performance.adoc b/docs/topics/mta-optimize-performance.adoc new file mode 100644 index 0000000000..092890868b --- /dev/null +++ b/docs/topics/mta-optimize-performance.adoc @@ -0,0 +1,28 @@ +// 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. +* 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/mta-review-reports.adoc b/docs/topics/mta-review-reports.adoc new file mode 100644 index 0000000000..5db1889498 --- /dev/null +++ b/docs/topics/mta-review-reports.adoc @@ -0,0 +1,242 @@ +// 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/{mta-cli} --input /home/username/{mta-cli}-source/test-files/jee-example-app-1.0.0.ear/ --output /home/username/{mta-cli}-reports/jee-example-app-1.0.0.ear-report --target eap6 --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] + +=== 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/mta-web-configuring-and-running-an-application-analysis.adoc b/docs/topics/mta-web-configuring-and-running-an-application-analysis.adoc index 1202d962a8..b79f460c93 100644 --- a/docs/topics/mta-web-configuring-and-running-an-application-analysis.adoc +++ b/docs/topics/mta-web-configuring-and-running-an-application-analysis.adoc @@ -75,13 +75,8 @@ Attaching custom rules is optional if you have already attached a migration targ * Target * Source(s) * Excluded rules tags: Rules with these tags are not processed. Add or delete as needed. -* Enable transaction report: Select the checkbox to generate a DIVA report that displays the call stack, which executes operations on relational database tables. * Enable automated tagging: Select the checkbox to automatically attach tags to the application. This checkbox is selected by default. -+ -[NOTE] -==== -The Transactions report 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. -==== + + [NOTE] ====