If you've been following this migration series of blogs (analysis report, inventory report, and evaluation report) at this point you are probably a lot more familiar with our WebSphere Application Migration Toolkit for Application Binaries and what it can do. Along the way, in your migration journey, it's possible that you ran into some scenarios where you wanted to tweak the tool a bit to achieve a specific task. Or maybe you ran into some issues during your use which up until now you didn't know how to get around. Here I will show you some tips and tricks that will hopefully help to improve your experience. The options mentioned here as well as a few more can also be viewed by specifying --help <action> where <action> is either --all, --analyze, --inventory, --evaluate, or --generateConfig.
Limiting the Packages in a Scan
As you have been using the tool to generate different reports you may have noticed the following message saying that various packages were excluded from your scan.
INFO: CWMIG11001I: The following packages are excluded from the scan by default: ch.qos,com.fasterxml,com.ibm,com.informix,com.lowagie,com.mchange,com.meterware,com.microsoft,com.sun,com.sybase,freemarker,groovy,java,javax,net,oracle,org,sqlj,sun,twitter4j,_ibmjsp. Use the --includePackages or --excludePackages options to override the default scanned packages.
Those are typically third-party packages that are likely not owned by your application and you would likely not have the ability to change. Therefore there would be no reason for the tool to scan those files and recommend any changes there. Excluding those packages ensures that all the information provided to you in the migration reports is relevant to your migration effort. However, you may run into a situation where you know that the utility jars in your application are making use of packages the tool is not already excluding by default. Making use of the --excludePackages=<comma-separated list of package names> option will enable you to specify the packages you would like to exclude from the scan. Note that when you use this option in your scan the tool will no longer exclude any of the packages you saw it exclude earlier. If you want to exclude packages in addition to what was already being excluded, you will want to use the option as such:
java -jar binaryAppScanner.jar <binaryInputPath> --all --excludePackages=ch.qos,com.fasterxml,com.ibm,com.informix,com.lowagie,com.mchange,com.meterware,com.microsoft,com.sun,com.sybase,freemarker,groovy,java,javax,net,oracle,org,sqlj,sun,twitter4j,_ibmjsp,<additional packages>
If you are very familiar with your application and what packages you own within it you could specify those packages in the --includePackages=<comma-separated list of package names> option and the tool will only scan those packages and exclude everything else. It may be possible that you own some packages that are similar in name to the third-party packages your application contains. Using include and exclude packages together as such --includePackages=com.packages.mine --excludePackages=com.packages.mine.except.this the tool will scan everything within the packages you include except for the ones you excluded. Note that when using include and exclude packages where there are overlaps, exclude packages will have higher priority.
Excluding Files From a Scan
With an option like --excludePackages you may be asking yourself why you would ever need to exclude anything else outside of packages and the class files they contain. The reason is usually due to very large and most likely not so useful XML files(50+ MB) which can take a while to process. You can exclude these files by specifying --excludeFiles="<regular expression of file patterns to exclude>". For example, --excludeFiles=".*/directory/LargeXMLFileName.xml". But wait! How would you know if a file like this was the source of your slow scans? The next section will help you track down those perpetrators.
Show Debug and Verbose Messages
After performing some scans on some smaller applications to get a feel for things. You're starting to get a hang of this. You're feeling ready to bring out your biggest applications. You eagerly type out your command and hit enter waiting to get your migration report.... Some minutes have passed by and the smile you had going into this has started fading as you watch the "Scanning Files.." message waiting for the next dot to appear to indicate that the tool has not fallen asleep on you. "Maybe my application broke the tool," you're thinking. Rest assured that is not the case. The tool is still scanning your application and will provide the migration report you are seeking. Most likely what is happening is that you have one or more very large files the tool is working to parse. Specifying the --debug option in your scan will generate a trace file that will include live information on what is going on within your scan. This information can help you identify files that may be stalling the scan which could then be excluded by using the --excludeFiles option. In the event that you do actually find an issue with the tool itself, you could also use this option to gather the information you would include in your support ticket. This option supports custom arguments to adjust the information that is presented in the trace if feel the need to refine the output a bit to your liking. The following syntax can be used: --debug="*=all|finest|fine".
Generate All Reports in One Scan
I'm sure you are already familiar with the --all action and the Consolidated Report it generates which combines the content for all the individual actions (Inventory, Analysis, Evaluation, and Config) into one report. But maybe you prefer to have each of the sections separated into their own respective reports which you can go through individually. Is that too much to ask for? We don't think so. Specifying --all-separate-reports will do just that while saving you from having to run a scan for those 4 reports and waiting for the tool to scan your application 4 different times.
Generate HTML and JSON Report in One Scan
If you value the readability of the HTML reports but also value the straight-to-the-point nature of the JSON reports covered in Cindy's blog on getting more from your migration data, you don't have to choose one or the other. The tool will happily serve you both within the same scan if you specify --format=html,json as an option in your scan. "Interesting, with --all-separate-reports, I can get 4 reports in one run, and with --format=html,json I can get each report in 2 formats. So if I use the 2 together will I get 8 reports in one run", you may be thinking to yourself. Yes... well almost. Since the --generateConfig option will never give you anything other than an XML output apart from when you run --all you will only receive 7 outputs when using those 2 options together. But who can argue with 7? Ask 9 and see how that worked out for him.
Scanning Apps Across Different Directories
You're probably already aware that if you run a scan against a directory that contains multiple applications you will receive a report for each of those applications. This capability is helpful if you don't want to manually kick off a scan for each application. But what if you don't have the ability (or willpower--I'm not judging) to put your applications in one directory to scan. I'm pleased to inform you that by specifying multiple binaryInputPaths in your scan as such /path1 /path2 --all-separate-reports --format=html,json you don't have to move anything.
Auto Detecting Shared Libraries
If you've run an Inventory or Config scan pointing the tool to an application contained within your WebSphere traditional environment, the tool has likely already made you aware of this capability.
INFO: CWMIG12093I: Shared libraries are in use by this app. To scan these libraries for configuration or inventory resources, rerun the scan with the --detectSharedLibraries parameter.
If your application makes use of shared libraries but you don't know where those libraries are contained, specifying the --detectSharedLibraries option in your scan will enable the tool to find and scan those shared libraries for you, ensuring the report has all the information it needs to properly advise you. Note that in order to use this option your binaryInputPath must only contain one application. Also, be aware that using this option to include shared libraries in your scan can significantly increase your scan time depending on the size of the shared libraries your application uses.
Pointing to Specific Shared Libraries
If you want to handpick the shared libraries to point the tool to when performing your inventory or config scan, you can achieve this by specifying --sharedLibraries="paths to shared libraries". You might want to do this if you know some of the shared libraries configured to your application contains files that will only serve to slow down your scan. Or if the tool was not able to find the shared libraries used because a config path was not able to be resolved.
Specifying Config Path
What's that? Your deployed application is not stored in the standard WebSphere traditional configuration location so for that reason, the tool was not able to migrate your config and detect your shared libraries? No worries--you're not out of luck just yet. You can manually point the tool to your configuration path by specifying --configLocation="path to a WebSphere traditional profile directory".
Name Reports or Specify Output Path
If you are tired of the build-up of reports within the directory containing the binaryScanner.jar you can use --output="path to a file or directory for the generated file" to specify an output directory that may better house your reports. This option can also be used to specify an alternative name for your report if the default naming convention is not to your liking. For example, --analyze --output=MyReport.html. Note that the ability to rename your reports is only possible if the tool is expected to output 1 report.
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.