Red Hat SummitAppendix A. Reference Material
A.1. Maven plugin Arguments
The following is a detailed description of the available MTA Maven plugin arguments.
| Argument | Description |
|---|---|
| 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 generate a Tattletale report for each application. |
| 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. See the Input File Argument Tables for details. |
| exportCSV |
Flag to export the report data to a CSV file on your local file system. MTA creates the file in the directory specified by the |
| 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 |
| keepWorkDirs | Flag to instruct MTA to not delete temporary working files, such as the graph database and unzipped archives. This is useful for debugging purposes. |
| packages | A list of the packages to be evaluated by MTA. This argument is required. See Select Packages for more information. |
| 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 MTA. This argument defaults to |
| overwrite |
Flag to force delete the existing output directory specified by 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 |
| sourceMode |
Flag to indicate that the application to be evaluated contains source files rather than compiled binaries. Defaults to |
| targetTechnologies |
A list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the |
| userIgnorePath | Specify a location for MTA to identify files that should be ignored. |
| userRulesDirectory |
Specify a location for MTA to look for custom MTA rules. The value can be a directory containing ruleset files or a single ruleset file. The ruleset files must use the |
| windupHome | An optional argument that points to the root of an extracted MTA CLI. By referencing a local installation of the CLI, the Maven plugin has direct access to all of the indexes, resulting in a performance increase. |
| windupVersion | Specify the version of MTA. |
A.1.1. Specify 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
<inputDirectory>INPUT_ARCHIVE_OR_DIRECTORY</inputDirectory>
<inputDirectory>INPUT_ARCHIVE_OR_DIRECTORY</inputDirectory>
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
--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
--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.
A.1.2. Specify the Output Directory
Specify the path to the directory to output the report information generated by MTA.
Usage
<outputDirectory>OUTPUT_REPORT_DIRECTORY</outputDirectory>
<outputDirectory>OUTPUT_REPORT_DIRECTORY</outputDirectory>-
If omitted, the report will be generated in the
{project.build.directory}/windup-reportdirectory. -
If the output directory exists, it will be overwritten based on the value of the
overwriteargument. This argument defaults totrue, and causes MTA to delete and recreate the directory.
A.1.3. Set 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
<sourceTechnologies>
<source>eap:6</source>
</sourceTechnologies>
<sourceTechnologies>
<source>eap:6</source>
</sourceTechnologies>
The sourceTechnologies argument now provides version support, which follows the Maven version range syntax. This instructs MTA to only run the rulesets matching the specified versions. For example, <source>eap:5</source>.
A.1.4. Set 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
<targetTechnologies> <target>eap:7</target> </targetTechnologies>
<targetTechnologies>
<target>eap:7</target>
</targetTechnologies>
The targetTechnologies argument now provides version support, which follows the Maven version range syntax. This instructs MTA to only run the rulesets matching the specified versions. For example, <target>eap:7</target>.
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 Supported Migration Paths in the MTA Getting Started Guide for which JBoss EAP version is appropriate for your source platform.
A.1.5. Select Packages
A list of the packages to be evaluated by MTA. It is highly recommended to use this argument.
Usage
<packages> <package>PACKAGE_1</package> <package>PACKAGE_2</package> </packages>
<packages>
<package>PACKAGE_1</package>
<package>PACKAGE_2</package>
</packages>In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The
PACKAGE_Nargument is a package prefix; all subpackages will be scanned. For example, to scan the packagescom.mycustomappandcom.myotherapp, use the following snippet in yourpom.xml.Copy to Clipboard Copied! Toggle word wrap Toggle overflow <packages> <package>com.mycustomapp</package> <package>com.myotherapp</package> </packages>
<packages> <package>com.mycustomapp</package> <package>com.myotherapp</package> </packages>-
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.
A.2. Rule Story Points
A.2.1. 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.
Migration Toolkit for Applications 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.
A.2.2. 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 MTA uses when estimating the level of effort required for a rule.
| 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. |
A.2.3. Task Severity
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 indicate whether a task must be completed or can be postponed.
- 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 the optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after migration is completed. An example of this would be the upgrade of EJB 2.x code to EJB 3.
For more information on categorizing tasks, see Using Custom Rule Categories in the Rules Development Guide.
A.3. Additional Resources
A.3.1. Get Involved
To help make Migration Toolkit for Applications 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 MTA 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 migration areas.
- Try Migration Toolkit for Applications on your application. Be sure to report any issues you encounter.
Contribute to the Migration Toolkit for Applications rules repository.
- Write a Migration Toolkit for Applications rule to identify or automate a migration process.
- Create a test for the new rule.
- Details are provided in the Rules Development Guide.
Contribute to the project source code.
- Create a core rule.
- Improve MTA performance or efficiency.
- See the Core Development Guide for information about how to configure your environment and set up the project.
Any level of involvement is greatly appreciated!
A.3.2. Important Links
- MTA forums: https://developer.jboss.org/en/windup
MTA JIRA issue trackers
- Core MTA: https://issues.jboss.org/browse/WINDUP
- MTA Rules: https://issues.jboss.org/browse/WINDUPRULE
- MTA mailing list: jboss-migration-feedback@redhat.com
- MTA on Twitter: @JBossWindup
-
MTA IRC channel: Server FreeNode (
irc.freenode.net), channel#windup(transcripts).
A.3.3. Known MTA Issues
You can review known issues for MTA here: Open MTA issues.
A.3.4. Report Issues with MTA
Migration Toolkit for Applications uses JIRA as its issue tracking system. If you encounter an issue executing MTA, please file a JIRA Issue.
If you do not have one already, you must sign up for a JIRA account in order to create a JIRA issue.
A.3.4.1. Create a JIRA Issue
Open a browser and navigate to the JIRA Create Issue page.
If you have not yet logged in, click the Log In link at the top right side of the page and enter your credentials.
Choose the following options and click the Next button.
Project
For core MTA issues, choose Red Hat Application Migration Toolkit (WINDUP).
For issues with MTA rules, choose: Red Hat Application Migration Toolkit rules (WINDUPRULE).
- Issue Type: Bug
On the next screen complete the following fields.
- Summary: Enter a brief description of the problem or issue.
- Environment: Provide the details of your operating system, version of Java, and any other pertinent information.
- Description: Provide a detailed description of the issue. Be sure to include logs and exceptions traces.
- Attachment: If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the MTA development team, attach it to the issue using the browse button.
- Click the Create button to create the JIRA issue.
Revised on 2020-07-27 15:01:48 UTC
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}