User-defined Rules in the Migration Toolkit for Application Binaries
The Migration Toolkit for Application Binaries (binary scanner) is a command-line tool used to analyze application binaries. The binary scanner produces a comprehensive report on how an application can be migrated to another Java SE version, Java EE version, or application platform. This tool uses XML defined rules to detect problems in your application for a future migration. As of release 21.0.0.3 users can write their own XML rules for detecting specific scenarios in an application. This is a guide on how to create user-defined rules to run alongside the rules included in the binary scanner. All the example rules and associated files in this blog can be found on Github.
What is a User-defined Rule?
A user-defined rule is an XML file written by the user utilizing the framework provided by the binary scanner tool to detect a problem scenario in an application to be shown in the generated detailed analysis report. These rules can fall under different types listed in the User-Defined Rules documentation. A few of the more commonly used types are:
|
Rule Type
|
Description
|
|
DetectClass
|
Used to detect the usage of any Java class
|
|
DetectElement
|
Used to detect an XML element
|
|
DetectFile
|
Used to detect the existence of a file
|
|
DetectPackage
|
Used to detect the usage of a Java package
|
|
DetectMethod
|
Used to detect the usage of a Java class method
|
|
DetectMultipleCriteria
|
Used to combine multiple detections in one rule; if any of the detections match, the whole rule will match
|
The following example uses DetectMultipleCriteria to encapsulate two DetectMethod rules. This means if either TreeMap.put() or TreeSet.add() are used in an application they will be flagged by this rule.
In the same folder as the binary scanner, you will find a user-rules directory. In this folder there are schema files for the user-defined rule and rule list files that can be used to check the syntax of your rules as you write them.
Be Careful!
The user-defined rules are very powerful. In order to get the most useful results, ensure that you are looking for scenarios that are as specific as possible. Otherwise you can get thousands of results, which is more than you probably want to look through and will result in a large report.
TreeMap.put() and TreeSet.add() are commonly used methods and if this rule requires a change only in one place the report doesn't need every instance of this method being used. Due to this, flagOnce="true" was added to my rule. This allows the tool to flag one occurrence of the issue in the archive to limit the noise in the report. The flagOncePerFile="true" option is also available for limiting the flags per file.
How to Use User-defined Rules?
User-defined rule XML files are used by including them in an XML list file and pointing to the directory that contains that list using --userRuleLocation parameter in your migration command. The following shows an example of an XML list file:
In this list each <rule> element must have fileName set to the rules file name. For each <rule> listed specifying attributes help, severity, devCost, instanceCost, and complexity are an option but not required. The help and severity attributes are directly visible in the binary scanner HTML reports. The devCost, instanceCost, and complexity are written to the JSON report and are shown in Transformation Advisor. For more information on these attributes you can visit User-Defined Rules in IBM Docs.
For now, let's focus on the help attribute. Each rule can be written in conjunction with a help file which describes the issue that was found during an application scan. If the user-defined rule is flagged its HTML help will be attached to the report next to a listing of the locations where it was flagged within the application.
Here is the created directory structure of the DetectTreeMapPutAndTreeSetAdd user-defined rule:
Now that a list XML, rule XML, and HTML help file are created it's time to run a scan including the newly written rule and its supporting files.
java -jar wamt/binaryAppScanner.jar wamt/app/TestTreeMapAndSet.war --all --userRuleLocation=wamt/user-rules/
Looks like the rule ran successfully! In running this scan other rules included with-in the tool executed. Currently, those rules don't relate to the intended scan. The --userRulesOnly parameter can be used to avoid running rules in the binary scanner that aren't written by the user. --userRulesOnly must be used with --userRuleLocation and cannot be used individually.
java -jar wamt/binaryAppScanner.jar wamt/app/TestTreeMapAndSet.war --all --userRuleLocation=wamt/user-rules/ --userRulesOnly
Why Write User-defined Rules?
This new way of interacting with the WebSphere Application Migration Toolkit for Application Binaries opens up many possibilities for the end user. The power the toolkit provides may now be used in more ways than ever before. Maybe your company wants to make sure everyone is using the latest version of a library or utility jar? Maybe you need to scan some applications for certain security compliance constraints? Maybe you want to make sure that applications stop using older versions of Java EE deployment descriptors? This functionality could even be useful outside of a migration effort - the binary scanner can be added to your CI/CD pipelines to ensure that certain conditions are being met with every build. Whatever is needed to ensure you have the complete view of your applications, the possibilities are now endless!
See the IBM Developer learning path Modernizing applications to use WebSphere Liberty to discover all the application modernization tools available with WebSphere Hybrid Edition.
Also, check out the other articles in this app modernization blog series.