Red Hat Application Migration Toolkit 4.0 Rules ......Red Hat Application Migration Toolkit 4.0...

Red Hat Application Migration Toolkit4.0

Rules Development Guide

Simplify Migration of Java Applications

Last Updated: 2018-04-04

Red Hat Application Migration Toolkit 4.0 Rules Development Guide

Simplify Migration of Java Applications

Legal Notice

Copyright © 2018 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative CommonsAttribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA isavailable athttp://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you mustprovide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinitylogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and othercountries.

Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.

Java ® is a registered trademark of Oracle and/or its affiliates.

XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United Statesand/or other countries.

MySQL ® is a registered trademark of MySQL AB in the United States, the European Union andother countries.

Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related toor endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marksor trademarks/service marks of the OpenStack Foundation, in the United States and other countriesand are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed orsponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

This guide describes how to create custom XML rules for the Red Hat Application Migration Toolkit.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of Contents

CHAPTER 1. INTRODUCTION1.1. ABOUT THE RULES DEVELOPMENT GUIDE

1.1.1. Use of RHAMT_HOME in This Guide1.2. RHAMT RULES

CHAPTER 2. GETTING STARTED2.1. CREATE YOUR FIRST XML RULE

Create the Directory Structure for the RuleCreate Data to Test the RuleCreate the RuleInstall the RuleTest the RuleReview the Reports

2.2. REVIEW THE RED HAT APPLICATION MIGRATION TOOLKIT QUICKSTARTSDownload the Latest Quickstart ZIPFork and Clone the Quickstart GitHub Project

CHAPTER 3. CREATING XML RULES3.1. XML RULE STRUCTURE

3.1.1. Rulesets3.1.2. Predefined Rules

3.2. CREATE A BASIC XML RULE3.2.1. Create the Basic XML Rule Template3.2.2. Create the Ruleset Metadata3.2.3. Create the Rule

3.2.3.1. Create the Rule When Condition3.2.3.2. Create the Rule Perform Action

3.3. XML RULE SYNTAX3.3.1. When Condition Syntax

3.3.1.1. <javaclass> Syntax3.3.1.1.1. Summary3.3.1.1.2. Construct a <javaclass> Element

3.3.1.1.2.1. <javaclass> Element Attributes3.3.1.1.2.2. <javaclass> Child Elements

3.3.1.2. <xmlfile> Syntax3.3.1.2.1. Summary3.3.1.2.2. Construct an <xmlfile> Element

3.3.1.2.2.1. <xmlfile> Element Attributes3.3.1.2.2.2. <xmlfile> matches Custom Functions3.3.1.2.2.3. <xmlfile> Child Elements

3.3.1.3. <project> Syntax3.3.1.3.1. Summary3.3.1.3.2. Construct a <project> Element

3.3.1.3.2.1. <project> Element Attributes3.3.1.3.2.2. <project> Child Elements3.3.1.3.2.3. <artifact> Element Attributes

3.3.1.4. <filecontent> Syntax3.3.1.4.1. Summary3.3.1.4.2. Construct a <filecontent> Element

3.3.1.4.2.1. <filecontent> Element Attributes3.3.1.5. <file> Syntax

3.3.1.5.1. Summary

5555

6666699

10111111

1313131414151516161717181818191919202121212222222223232323232324242424

Table of Contents

1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3.1.5.2. Construct a <file> Element3.3.1.5.2.1. <file> Element Attributes

3.3.1.6. <has-hint> Syntax3.3.1.6.1. Summary3.3.1.6.2. Construct a <has-hint>

3.3.1.6.2.1. <has-hint> Element Attributes3.3.1.7. <has-classification> Syntax

3.3.1.7.1. Summary3.3.1.7.2. Construct a <has-classification>

3.3.1.7.2.1. <has-classification> Element Attributes3.3.2. Perform Action Syntax

3.3.2.1. <classification> Syntax3.3.2.1.1. Summary3.3.2.1.2. <classification> Element Attributes3.3.2.1.3. <classification> Child Elements

3.3.2.2. <link> Syntax3.3.2.2.1. Summary3.3.2.2.2. <link> Element Attributes

3.3.2.3. <hint> Syntax3.3.2.3.1. Summary3.3.2.3.2. <hint> Element Attributes3.3.2.3.3. <hint> Child Elements

3.3.2.4. <xslt> Syntax3.3.2.4.1. Summary3.3.2.4.2. <xslt> Element Attributes3.3.2.4.3. <xslt> Child Elements

3.3.2.4.3.1. <lineitem> Syntax3.3.2.4.4. Summary3.3.2.4.5. <lineitem> Element Attributes

3.3.2.5. <iteration> Syntax3.3.2.5.1. Summary3.3.2.5.2. <iteration> Element Attributes3.3.2.5.3. <iteration> Child Elements

3.3.3. Where Syntax

CHAPTER 4. TESTING XML RULES4.1. ADD THE RULE TO RED HAT APPLICATION MIGRATION TOOLKIT4.2. TEST THE XML RULE

CHAPTER 5. OVERRIDING RULES5.1. OVERRIDE A RULE5.2. DISABLE A RULE

CHAPTER 6. USING CUSTOM RULE CATEGORIESAdd a Custom CategoryAssign a Rule to a Custom Category

APPENDIX A. REFERENCE MATERIALA.1. RULE STORY POINTS

A.1.1. What are Story Points?A.1.2. How Story Points are Estimated in RulesA.1.3. Task Severity

A.2. ADDITIONAL RESOURCESA.2.1. Review the Existing RHAMT XML Rules

24242525262626262626262727272828282929293030313131323232333333343434

353535

363637

383838

40404040404141


2

A.2.2. Important Links 41

Table of Contents

3


4

CHAPTER 1. INTRODUCTION

1.1. ABOUT THE RULES DEVELOPMENT GUIDE

This guide is for engineers, consultants, and others who want to create custom XML-based rules for RedHat Application Migration Toolkit (RHAMT) tools.

If you are new to RHAMT, it is recommended that you start with the Getting Started Guide for anoverview of Red Hat Application Migration Toolkit features and system requirements. It is alsorecommended that you review the CLI Guide, which provides detailed instructions on how to install andexecute the CLI.

If you would like to contribute to the RHAMT source code base or provide Java-based rule add-ons, seethe Core Development Guide.

1.1.1. Use of RHAMT_HOME in This Guide

This guide uses the RHAMT_HOME replaceable variable to denote the path to your RHAMT installation.The installation directory is the rhamt-cli-4.0.1.Final directory where you extracted the RHAMTZIP distribution.

When you encounter RHAMT_HOME in this guide, be sure to replace it with the actual path to yourRHAMT installation.

1.2. RHAMT RULES

Red Hat Application Migration Toolkit (RHAMT) contains rule-based migration tools that analyze theAPIs, technologies, and architectures used by the applications you plan to migrate. In fact, the RHAMTanalysis process is implemented using RHAMT rules. RHAMT uses rules internally to extract files fromarchives, decompile files, scan and classify file types, analyze XML and other file content, analyze theapplication code, and build the reports.

RHAMT builds a data model based on the rule execution results and stores component data andrelationships in a graph database, which can then be queried and updated as needed by the migrationrules and for reporting purposes.

RHAMT rules use the following rule pattern:

when(condition) perform(action)otherwise(action)

RHAMT provides a comprehensive set of standard migration rules out-of-the-box. Because applicationsmay contain custom libraries or components, RHAMT allows you to write your own rules to identify use ofcomponents or software that may not be covered by the existing ruleset.

CHAPTER 1. INTRODUCTION

5

https://access.redhat.com/documentation/en-us/red_hat_application_migration_toolkit/4.0/html-single/cli_guide


https://github.com/windup/windup/wiki/Core-Development-Guide

CHAPTER 2. GETTING STARTEDYou can get starting creating custom RHAMT rules by walking through creating a rule or by reviewing thequickstarts.

2.1. CREATE YOUR FIRST XML RULE

This section guides you through the process of creating and testing your first RHAMT XML-based rule.This assumes that you have already installed RHAMT. See the CLI Guide 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 <class-loading> element and provide a link to the documentation thatdescribes how to migrate the code.

Create the Directory Structure for the RuleCreate a directory structure to contain your first rule and the data file to use for testing.

$ mkdir -p /home/USER_NAME/migration-rules/rules$ mkdir -p /home/USER_NAME/migration-rules/data

This directory structure will also be used to hold the generated RHAMT reports.

Create Data to Test the Rule

1. Create a jboss-web.xml file in the /home/USER_NAME/migration-rules/data/subdirectory.

2. Copy in the following content.

Create the RuleRHAMT XML-based rules use the following rule pattern:


Ruleset and rule XML elements are covered in more detail in the XML Rule Structure section. SeeCreate a Basic XML Rule for additional details about creating XML rules with example syntax.

1. Create an XML file in the /home/USER_NAME/migration-rules/rules/ subdirectorynamed JBoss5-web-class-loading.windup.xml. Copy in the following content.

<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 4.2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_2.dtd"><jboss-web> <class-loading java2ClassLoadingCompliance="false"> <loader-repository> seam.jboss.org:loader=@projectName@ <loader-repository-config>java2ParentDelegation=false</loader-repository-config> </loader-repository> </class-loading></jboss-web>


6


NOTE

RHAMT identifies files with the .windup.xml or .rhamt.xml extension asXML-based rules, so be sure to use this naming convention, otherwise the rulewill not be evaluated!

2. Add the unique identifier for the ruleset and rule.

Replace the UNIQUE_RULESET_ID with an appropriate ruleset ID, for example, JBoss5-web-class-loading.

Replace the UNIQUE_RULE_ID with an appropriate rule ID, for example, JBoss5-web-class-loading_001.

3. Add the following ruleset add-on dependencies.

<?xml version="1.0"?><ruleset id="UNIQUE_RULESET_ID" xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata> <description>  </description> <dependencies>  </dependencies> <sourceTechnology id="SOURCE_ID" versionRange="SOURCE_VERSION_RANGE"/> <targetTechnology id="TARGET_ID" versionRange="TARGET_VERSION_RANGE"/> <tag>Reviewed-2015-05-01</tag> </metadata> <rules> <rule id="UNIQUE_RULE_ID"> <when>  </when> <perform>  </perform> </rule> </rules></ruleset>

<dependencies> <addon id="org.jboss.windup.rules,windup-rules-javaee,3.0.0.Final"/> <addon id="org.jboss.windup.rules,windup-rules-java,3.0.0.Final"/></dependencies>

CHAPTER 2. GETTING STARTED

7

4. Add the source and target technologies.

Replace SOURCE_ID with eap.

Replace TARGET_ID with eap.

5. Set the source and target technology versions.

Replace SOURCE_VERSION_RANGE with (4,5).

Replace TARGET_VERSION_RANGE with [6,).

See the Apache Maven version range specification for help with this syntax.

6. 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 xpathexpression jboss-web/class-loading.

7. 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 themigration details.

The rule is now complete and should look like the following example.

<when> <xmlfile matches="jboss-web/class-loading" /></when>

<perform> <iteration> <classification title="JBoss Web Application Descriptor" effort="1"/> <hint title="JBoss Web XML class-loading element is no longer valid"> <message> The class-loading element is no longer valid in the jboss-web.xml file. </message> <link href="https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6" title="Create or Modify Files That Control Class Loading in JBoss EAP 6"/> </hint> </iteration></perform>

<?xml version="1.0"?><ruleset id="JBoss5-web-class-loading"


8

http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html

Install the RuleAn RHAMT rule is installed by placing the rule into the appropriate directory. See Add the Rule toRHAMT for the possible locations to place a custom rule.

Copy the JBoss5-web-class-loading.windup.xml file to the RHAMT_HOME/rules/ directory.

$ cp /home/USER_NAME/migration-rules/rules/JBoss5-web-class-loading.windup.xml RHAMT_HOME/rules/

Test the Rule

xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata> <description> This ruleset looks for the class-loading element in a jboss-web.xml file, which is no longer valid in JBoss EAP 6 </description> <dependencies> <addon id="org.jboss.windup.rules,windup-rules-javaee,3.0.0.Final"/> <addon id="org.jboss.windup.rules,windup-rules-java,3.0.0.Final"/> </dependencies> <sourceTechnology id="eap" versionRange="(4,5)"/> <targetTechnology id="eap" versionRange="[6,)"/> </metadata> <rules> <rule id="JBoss5-web-class-loading_001"> <when> <xmlfile matches="jboss-web/class-loading" /> </when> <perform> <iteration> <classification title="JBoss Web Application Descriptor" effort="1"/> <hint title="JBoss Web XML class-loading element is no longer valid"> <message> The class-loading element is no longer valid in the jboss-web.xml file. </message> <link href="https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6" title="Create or Modify Files That Control Class Loading in JBoss EAP 6"/> </hint> </iteration> </perform> </rule> </rules></ruleset>


9

Open a terminal and execute the following command, passing the test file as an input argument and adirectory for the output report.

$ RHAMT_HOME/bin/rhamt-cli --sourceMode --input /home/USER_NAME/migration-rules/data --output /home/USER_NAME/migration-rules/reports --target eap:6

You should see the following result.

Report created: /home/USER_NAME/migration-rules/reports/index.html Access it at this URL: file:///home/USER_NAME/migration-rules/reports/index.html

Review the ReportsReview the report to be sure that it provides the expected results. For a more detailed walkthrough ofRHAMT reports, see the Review the Reports section of the RHAMT CLI Guide.

1. Open /home/USER_NAME/migration-rules/reports/index.html in a web browser.

2. Verify that the rule executed.

a. From the main landing page, click the Rule providers execution overview link to open theRule Providers Execution Overview.

b. Find the JBoss5-web-class-loading_001 rule and verify that its Status? is Condition met and its Result? is success.

Figure 2.1. Test Rule Execution

3. Verify that the rule matched on the test data.

a. From the main landing page, click on the name of the application or input folder, which is data in this example.

b. Click on the Application Details report link.

c. Click on the jboss-web.xml link to view the Source Report.You can see that the <class-loading> line is highlighted, and the hint from the customrule is shown inline.


10

https://access.redhat.com/documentation/en-us/red_hat_application_migration_toolkit/4.0/html-single/cli_guide#review_reports

Figure 2.2. Rule Match

The top of the file lists the classifications for matching rules. You can use the link icon toview the details for that rule. Notice that in this example, the jboss-web.xml file matchedon another rule (JBoss web application descriptor (jboss-web.xml)) thatproduced 1 story point. This, combined with the 1 story point from our custom rule, bringsthe total story points for this file to 2.

2.2. REVIEW THE RED HAT APPLICATION MIGRATION TOOLKITQUICKSTARTS

The Red Hat Application Migration Toolkit quickstarts provide working examples of how to create customJava-based rule add-ons and XML rules. You can use them as a starting point for creating your owncustom rules.

You can download a ZIP file of the latest released version of the quickstarts. Or, if you prefer to work withthe source code, you can fork and clone the windup-quickstarts project repository.

Each quickstart has a README.adoc file that contains instructions for that quickstart.

Download the Latest Quickstart ZIP

1. Open a browser and navigate to https://github.com/windup/windup-quickstarts/releases.

2. Click on the most recent release to download the ZIP file to your local file system.

Fork and Clone the Quickstart GitHub ProjectYou must have the git client installed on your machine.


11

https://github.com/windup/windup-quickstarts/releases

http://git-scm.com/

1. Click the Fork link on the Red Hat Application Migration Toolkit quickstart GitHub page to createthe project in your own Git. The forked GitHub repository URL created by the fork should looklike this: https://github.com/YOUR_USER_NAME/windup-quickstarts.git.

2. Clone your Red Hat Application Migration Toolkit quickstart repository to your local file system:

$ git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git

3. This creates and populates a windup-quickstarts directory on your local file system.Navigate to the newly created directory, for example

$ cd windup-quickstarts/

4. If you want to be able to retrieve the latest code updates, add the remote upstream repositoryso you can fetch any changes to the original forked repository.

$ git remote add upstream https://github.com/windup/windup-quickstarts.git

5. Get the latest files from the upstream repository.

$ git fetch upstream


12

https://github.com/windup/windup-quickstarts/

CHAPTER 3. CREATING XML RULES

3.1. XML RULE STRUCTURE

This section describes the basic structure of XML rules. All XML rules are defined as elements withinrulesets. For more details, see the RHAMT XML rule schema.

3.1.1. Rulesets

A ruleset is a group of one or more rules that targets a specific area of migration. This is the basicstructure of the <ruleset> element.

<ruleset id="UNIQUE_RULESET_ID">: Defines this as an RHAMT ruleset and gives it aunique ruleset ID.

<metadata>: The metadata about the ruleset.

<description>: The description of the ruleset.

<dependencies/>: The rule add-ons required by this ruleset.

<sourceTechnology/>: The source technology.

<targetTechnology/>: The target technology.

<overrideRules/>: Setting to true indicates that rules in this ruleset override rules withthe same ID from the core ruleset distributed with RHAMT. Both the ruleset id and therule id must match a rule within the core ruleset or the rule will be ignored. This is falseby default.

<rules>: A set of individual rules.

<rule id="UNIQUE_RULE_ID">: Defines the rule and gives it a unique ID. It isrecommended to include the ruleset ID as part of the rule ID, for example, UNIQUE_RULESET_ID_UNIQUE_RULE_ID. One or more rules can be defined for aruleset.

<when>: The conditions to match on. For a detailed description of the elementsallowed in a <when>, see When Condition Syntax.

<perform>: The action to be performed when the rule condition is matched. For adetailed description of the elements allowed in a <perform>, see Perform ActionSyntax.

<otherwise>: The action to be performed when the rule condition is not matched.This element takes the same child elements as the <perform> element.

<where>: A string pattern defined as a parameter, which can be used elsewhere inthe rule definition. For more information, see Where Syntax.

<file-mapping/>: Maps an extension to a graph type.

<package-mapping/>: Maps from a package pattern (regular expression) to aorganization name.


13

http://windup.jboss.org/schema/windup-jboss-ruleset.xsd

3.1.2. Predefined Rules

RHAMT provides predefined rules for common migration requirements. These core RHAMT rules arelocated in the RHAMT installation at RHAMT_HOME/rules/migration-core/.

The following is an example of a core RHAMT rule that matches on a proprietary utility class.

3.2. CREATE A BASIC XML RULE

<?xml version="1.0"?><ruleset xmlns="http://windup.jboss.org/schema/jboss-ruleset" id="weblogic" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd">

<metadata> <description> This ruleset provides analysis of WebLogic proprietary classes and constructs that may require individual attention when migrating to JBoss EAP 6+. </description> <dependencies> <addon id="org.jboss.windup.rules,windup-rules-javaee,2.0.1.Final" /> <addon id="org.jboss.windup.rules,windup-rules-java,2.0.0.Final" /> </dependencies> <sourceTechnology id="weblogic" /> <targetTechnology id="eap" versionRange="[6,)" /> <tag>reviewed-2015-06-02</tag> <tag>weblogic</tag> </metadata> <rules> ... <rule id="weblogic-02000"> <when> <javaclass references="weblogic.utils.StringUtils.{*}" /> </when> <perform> <hint title="WebLogic StringUtils usage" effort="1" category-id="mandatory"> <message>Replace with the `StringUtils` class from Apache Commons.</message> <link href="https://commons.apache.org/proper/commons-lang/" title="Apache Commons Lang" /> <tag>weblogic</tag> </hint> </perform> </rule> ... </rules></ruleset>


14

This section describes how to create an RHAMT XML rule. This assumes that you already have RHAMTinstalled. See the RHAMT CLI Guide for installation instructions.

3.2.1. Create the Basic XML Rule Template

RHAMT XML rules consist of conditions and actions and use the following rule pattern.


Create a file with the following contents, which is the basic syntax for XML rules.

IMPORTANT

The RHAMT XML rule file must use the .windup.xml or .rhamt.xml extension,otherwise the rule will not be evaluated.

3.2.2. Create the Ruleset Metadata

The XML ruleset metadata element provides additional information about the ruleset such as adescription, the source and target technologies, and add-on dependencies. The metadata also allows forspecification of tags, which allow you to provide additional information about a ruleset. For moreinformation about ruleset metadata, see XML Rule Structure.

Example Rule <metadata>

<?xml version="1.0"?><ruleset id="unique-ruleset-id" xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata>  </metadata> <rules> <rule id="unique-ruleset-id-01000"> <when>  </when> <perform>  </perform> <otherwise>  </otherwise> </rule> <rules></ruleset>


15


3.2.3. Create the Rule

Individual rules are contained within the <rules> element and consist of one or more when conditionsand perform actions.

See the XML rule schema for valid rule syntax.

3.2.3.1. Create the Rule When Condition

The XML rule <when> element tests for a condition. The following is a list of valid <when> conditions.

Element Description

<and> The standard logical and operator.

<filecontent> Find strings or text within files, for example, properties files.

<file-mapping> Define file names to internal stored File model.

<javaclass> Test for a match in a Java class.

<javaclass-ignore> Exclude javaclass which you would like to ignore in processing discovery.

<ruleset id="unique-ruleset-id" xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata> <description> This is the description. </description> <dependencies> <addon id="org.jboss.windup.rules,windup-rules-javaee,2.0.1.Final"/> <addon id="org.jboss.windup.rules,windup-rules-java,2.0.0.Final"/> </dependencies> <sourceTechnology id="weblogic" versionRange="(10,12]"/> <sourceTechnology id="ejb" versionRange="(2,3]"/> <targetTechnology id="eap" versionRange="(5,6]"/> <targetTechnology id="ejb" versionRange="(2,3]"/> <tag>require-stateless</tag> <tag>require-nofilesystem-io</tag> <executeAfter>AfterRulesetId</executeAfter> <executeBefore>BeforeRulesetId</executeBefore> </metadata> <rules> ... </rules></ruleset>


16


<not> The standard logical not operator.

<or> The standard logical or operator.

<package-mapping>

Define package names to organization or libraries.

<project> Test for project characteristics, such as dependencies.

<true> Always match.

<xmlfile> Test for a match in an XML file.

Element Description

The specific syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file,a project, or file content. This is described in more detail in When Condition Syntax.

3.2.3.2. Create the Rule Perform Action

The XML rule <perform> element performs the action when the condition is met. Operations allowed inthis section of the rule include the classification of application resources, in-line hints for migration steps,links to migration information, and project lineitem reporting. The following is a list of valid <perform>actions.

Element Description

<classification> This operation adds metadata that is intended to apply to the entire file. For example, ifthe Java Class is a JMS Message Listener, you might want to add a Classification withthe title "JMS Message Listener". Information that would apply to the entire file would gohere. Also, if an effort level is set, that information would apply to the entire file.

<hint> This operation adds metadata to a line within the file. This provides a hint or inlineinformation about how to migrate a section of code.

<iteration> This specifies to iterate over an implicit or explicit variable defined within the rule.

<lineitem> This provides a high-level message that will appear in the application overview page.

<link> This provides an HTML link to additional information or documentation that providesmore information about the migration task.

<xslt> This specifies how to transform an XML file.

The syntax is described in more detail in Perform Action Syntax.

3.3. XML RULE SYNTAX


17

3.3.1. When Condition Syntax

Conditions allowed in the when portion of a rule must extend GraphOperation and currently includeevaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled afterthe Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a betterunderstanding 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.

<javaclass> condition syntax

<xmlfile> condition syntax

<project> condition syntax

<filecontent> condition syntax

<file> condition syntax

<has-hint> condition syntax

<has-classification> condition syntax

By default, if more than one when rule condition is provided, then all conditions must be met for the ruleto match.

3.3.1.1. <javaclass> Syntax

3.3.1.1.1. Summary

Use the <javaclass> element to find imports, methods, variable declarations, annotations, classimplementations, and other items related to Java classes. For a better understanding of the <javaclass> condition, see the JavaDoc for the JavaClass class.

The following is an example of a rule that tests for WebLogic-specific Apache XML packages.

<rule id="weblogic-03000"> <when> <javaclass references="weblogic.apache.xml.{*}" /> </when> <perform> <hint title="WebLogic Specific Apache XML Package" effort="1" category-id="mandatory"> <message> Code using this package should be replaced with code using the org.apache.xml package from [Apache Xerces](http://xerces.apache.org/). </message> </hint> </perform></rule>


18

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/GraphOperation.html


http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/java/condition/JavaClass.html

3.3.1.1.2. Construct a <javaclass> Element

3.3.1.1.2.1. <javaclass> Element Attributes

Attribute Name Type Description

references CLASS_NAME The package or class name to match on. Wildcard characterscan be used. This attribute is required.

NOTE

For performance reasons, you should not startthe reference with wildcard characters. Forexample, use weblogic.apache.xml.{*}instead of {web}.apache.xml.{*}.

references="weblogic.apache.xml.{*}"

matchesSource STRING An exact regex to match. This is useful to distinguish hard-codedstrings. This attribute is required.

matchesSource="log4j.logger"

as VARIABLE_NAME A variable name assigned to the rule so that it can be used as areference in later processing. See the from attribute below.

as="MyEjbRule"

from VARIABLE_NAME Begin the search query with the filtered result from a previoussearch identified by its as VARIABLE_NAME.

from="MyEjbRule"

in PATH_FILTER Filter input files matching this regex (regular expression) namingpattern. Wildcard characters can be used.

in="{*}File1"

3.3.1.1.2.2. <javaclass> Child Elements

Child Element Description

<location> The location where the reference was found in a Java class. Location can refer toannotations, field and variable declarations, imports, and methods. For the complete listof valid values, see the JavaDoc for TypeReferenceLocation.

<location>IMPORT</location>


19

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/ast/java/data/TypeReferenceLocation.html

<annotation-literal>

Match on literal values inside of annotations.

The below example would match on @MyAnnotation(myvalue="test").

Note that in this case, the <javaclass> refers to an annotation (@MyAnnotation),so the top-level annotation filter, <annotation-literal> must specify the nameattribute. If the <javaclass> referred to a class that is annotated, then the top-levelannotation filter used would be <annotation-type>.

<annotation-type> Match on a particular annotation type. You can supply subconditions to be matchedagainst the annotation elements.

The below example would match on a Calendar field declaration annotated with @MyAnnotation(myvalue="test").

<annotation-list> Match on an item in an array within an annotation. If an array index is not specified, thecondition will be matched if it applies to any item in the array. You can supplysubconditions to be matched against this element.

The below example would match on @MyAnnotation(mylist={"one","two"}).

Note that in this case, the <javaclass> refers to an annotation (@MyAnnotation),so the top-level annotation filter, <annotation-list> must specify the nameattribute. If the <javaclass> referred to a class that is annotated, then the top-levelannotation filter used would be <annotation-type>.


3.3.1.2. <xmlfile> Syntax

<javaclass references="org.package.MyAnnotation"> <location>ANNOTATION</location> <annotation-literal name="myvalue" pattern="test"/></javaclass>

<javaclass references="java.util.Calendar"> <location>FIELD_DECLARATION</location> <annotation-type pattern="org.package.MyAnnotation"> <annotation-literal name="myvalue" pattern="test"/> </annotation-type></javaclass>

<javaclass references="org.package.MyAnnotation" > <location>ANNOTATION</location> <annotation-list name="mylist"> <annotation-literal pattern="two"/> </annotation-list></javaclass>


20

3.3.1.2.1. Summary

Use the <xmlfile> element to find information in XML files. For a better understanding of the <xmlfile> condition, see the XmlFile JavaDoc.

The following is an example of a rule that tests for an XML file.

3.3.1.2.2. Construct an <xmlfile> Element

3.3.1.2.2.1. <xmlfile> Element Attributes


matches XPATH Match on an XML file condition.

matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']"

xpathResultMatch XPATH_RESULT_STRING

Return results that match the given regex.

<xmlfile matches="//foo/text()" xpathResultMatch="Text from foo."/>


as="MyEjbRule"

in PATH_FILTER Used to filter input files matching this regex (regular expression)naming pattern. Wildcard characters can be used.

in="{*}File1"

<rule id="UNIQUE_RULE_ID"> <when> <xmlfile matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']"> <namespace prefix="w" uri="http://java.sun.com/xml/ns/javaee"/> </xmlfile> </when> <perform> <hint title="Title for Hint from XML"> <message>Container Auth</message> </hint> <xslt description="Example XSLT Conversion" extension="-converted-example.xml" template="/exampleconversion.xsl"/> </perform></rule>


21

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/xml/condition/XmlFile.html


from="MyEjbRule"

public-id PUBLIC_ID The DTD public-id regex.

public-id="public"


3.3.1.2.2.2. <xmlfile> matches Custom Functions

The matches attribute may use several built-in custom XPath functions, which may have useful sideeffects, like setting the matched value on the rule variables stack.

Function Description

windup:matches() Match a XPath expression against a string, possiblycontaining RHAMT parameterization placeholders.

matches="windup:matches(//foo/@class, '{javaclassname}'"

This will match all <foo/> elements with a classattribute and store their value into javaclassnameparameter for each iteration.

3.3.1.2.2.3. <xmlfile> Child Elements


<namespace> The namespace referenced in XML files. This element contains two optional attributes:The prefix and the uri.

3.3.1.3. <project> Syntax

3.3.1.3.1. Summary

Use the <project> element to query the Maven POM file for the project characteristics. For a betterunderstanding of the <project> condition, see the JavaDoc for the Project class.

The following is an example of a rule that checks for a JUnit dependency version between 2.0.0.Finaland 2.2.0.Final.

<namespace prefix="abc" uri="http://maven.apache.org/POM/4.0.0"/>


22

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/project/condition/Project.html

3.3.1.3.2. Construct a <project> Element

3.3.1.3.2.1. <project> Element Attributes

The <project> element is used to match against the project’s Maven POM file. You can use thiscondition to query for dependencies of the project. It does not have any attributes itself.

3.3.1.3.2.2. <project> Child Elements


<artifact> Subcondition used within <project> to query against project dependencies. The <artifact> element attributes are described below.

3.3.1.3.2.3. <artifact> Element Attributes


groupId PROJECT_GROUP_ID

Match on the project <groupId> of the dependency.

artifactId PROJECT_ARTIFACT_ID

Match on the project <artifactId> 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.

3.3.1.4. <filecontent> Syntax

3.3.1.4.1. Summary

<rule id="UNIQUE_RULE_ID"> <when> <project> <artifact groupId="junit" artifactId="junit" fromVersion="2.0.0.Final" toVersion="2.2.0.Final"/> </project> </when> <perform> <lineitem message="The project uses junit with the version between 2.0.0.Final and 2.2.0.Final"/> </perform></rule>


23

Use the <filecontent> element to find strings or text within files, for example, a line in a Propertiesfile. For a better understanding of the <filecontent> condition, see the JavaDoc for the FileContentclass.

3.3.1.4.2. Construct a <filecontent> Element

3.3.1.4.2.1. <filecontent> Element Attributes


pattern String Match the file contents against the provided parameterizedstring. This attribute is required.

filename String Match the file names against the provided parameterized string.


as="MyEjbRule"


from="MyEjbRule"

3.3.1.5. <file> Syntax

3.3.1.5.1. Summary

Use the <file> 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 <file> condition, see the JavaDoc forthe File class.

3.3.1.5.2. Construct a <file> Element

3.3.1.5.2.1. <file> Element Attributes


filename String Match the file names against the provided parameterized string.This attribute is required.


as="MyEjbRule"


24

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/files/condition/FileContent.html

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/files/condition/File.html


Example:

from="MyEjbRule"


3.3.1.6. <has-hint> Syntax

3.3.1.6.1. Summary

Use the <has-hint> element to test whether a file or line has a hint already associated with it. It isprimarily used to prevent firing if a hint already exists, or to implement rules for default execution whenno other conditions apply. For a better understanding of the <has-hint> condition, see the JavaDoc forthe HasHint class.

The following is an example of a rule that checks to see if a hint exists for an IBM JMS destinationmessage, and if not includes it.

<rule id="websphere-jms-eap7-03000"> <when> <javaclass references="{package}.{prefix}{type}Message" /> </when> <perform> <iteration> <when> <not> <has-hint /> </not> </when> <perform> <hint title="IBM JMS destination message" effort="1" category-id="mandatory"> <message> 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`. </message> <link href="https://docs.oracle.com/javaee/7/tutorial/jms-concepts003.htm#sthref2271" title="Java EE 7 JMS Tutorial - Message API" /> <tag>jms</tag> <tag>websphere</tag> </hint> </perform> </iteration> </perform> <where param="type"> <matches pattern="(Text|Stream|Object|Map|Bytes)?" /> </where>


25

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/HasHint.html

<where param="prefix"> <matches pattern="(JMS|MQe|MQ)" /> </where> <where param="package"> <matches pattern="com.ibm(\..*)?\.jms" /> </where></rule>

3.3.1.6.2. Construct a <has-hint>

The <has-hint> element is used to determine if a hint exists for a file or line. It does not have any childelements.

3.3.1.6.2.1. <has-hint> Element Attributes


message String An optional argument allowing you to match the hint against theprovided message string.

3.3.1.7. <has-classification> Syntax

3.3.1.7.1. Summary

Use the <has-classification> element to test whether a file or line has a classification. It isprimarily used to prevent firing if a classification already exists, or to implement rules for defaultexecution when no other conditions apply. For a better understanding of the <has-classification>condition, see the JavaDoc for the HasClassification class.

3.3.1.7.2. Construct a <has-classification>

The has-classification element is used to determine if a specified classification exists. It does nothave any child elements.

3.3.1.7.2.1. <has-classification> Element Attributes


title String An optional title to match the classification against.

3.3.2. Perform Action Syntax

Operations available in the perform section of the rule include the classification of applicationresources, in-line hints for migration steps, links to migration information, and project lineitem reporting.Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the relatedJava classes are provided for a better understanding of how they behave.



26

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/HasClassification.html


The following sections describe the more common XML rule perform actions.

<classification> Syntax

<link> Syntax

<hint> Syntax

<xslt> Syntax

<lineitem> Syntax

<iteration> Syntax

3.3.2.1. <classification> Syntax

3.3.2.1.1. Summary

The <classification> element is used to identify or classify application resources that match therule. It provides a title that is displayed in the report, a level of effort, and it can also provide links toadditional information about how to migrate this resource classification. For a better understanding of the<classification> action, see the JavaDoc for the Classification class.

The following is an example of a rule that classifies a resource as a WebLogic EAR applicationdeployment descriptor file.

3.3.2.1.2. <classification> Element Attributes


title STRING The title given to this resource. This attribute is required.

title="JBoss Seam Components"

effort BYTE The level of effort assigned to this resource.

effort="2"

<rule id="XmlWebLogicRules_10vvyf"> <when> <xmlfile as="default" matches="/*[local-name()='weblogic-application']"></xmlfile> </when> <perform> <iteration> <classification title="Weblogic EAR Application Descriptor" effort="3"/> </iteration> </perform></rule>


27

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/classification/Classification.html

category-id STRING A reference to a category as defined in RHAMT_HOME/rules/migration-core/core.windup.categories.xml. The defaultcategories are mandatory, optional, and potential.

category-id="mandatory"

of VARIABLE_NAME Create a new classification for the given reference.

of="MySeamRule"


3.3.2.1.3. <classification> Child Elements


<link> Provides a link URI and text title for additional information.

<tag> Provides additional custom information for the classification.

<description> Description of this resource

3.3.2.2. <link> Syntax

3.3.2.2.1. Summary

The <link> element is used in classifications or hints to provide links to informational content. For abetter understanding of the <link> action, see the JavaDoc for the Link class.

<classification title="Websphere Startup Service" effort="4"> <link href="http://docs.oracle.com/javaee/6/api/javax/ejb/Singleton.html" title="EJB3.1 Singleton Bean"/> <link href="http://docs.oracle.com/javaee/6/api/javax/ejb/Startup.html" title="EJB3.1 Startup Bean"/></classification>

<tag>Seam3</tag>

<description>JBoss Seam components must be replaced</description>


28

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/Link.html

The following is an example of a rule that creates links to additional information.

3.3.2.2.2. <link> Element Attributes


href URI The URI for the referenced link.

href="https://access.redhat.com/articles/1249423"

title STRING A title for the link.

title="Migrate WebLogic Proprietary Servlet Annotations"

3.3.2.3. <hint> Syntax

3.3.2.3.1. Summary

The <hint> element is used to provide a hint or inline information about how to migrate a section ofcode. For a better understanding of the <hint> action, see the JavaDoc for the Hint class.

The following is an example of a rule that creates a hint.

<rule id="SeamToCDIRules_2fmb"> <when> <javaclass references="org.jboss.seam.{*}" as="default"/> </when> <perform> <iteration> <classification title="SEAM Component" effort="1"> <link href="http://www.seamframework.org/Seam3/Seam2ToSeam3MigrationNotes" title="Seam 2 to Seam 3 Migration Notes"/> <link href="http://docs.jboss.org/weld/reference/latest/en-US/html/example.html" title="JSF Web Application Example"/> <link href="http://docs.jboss.org/weld/reference/latest/en-US/html/contexts.html" title="JBoss Context Documentation"/> <link href="http://www.andygibson.net/blog/tutorial/cdi-conversations-part-2/" title="CDI Conversations Blog Post"/> </classification> </iteration> </perform></rule>

<rule id="WebLogicWebServiceRules_8jyqn"> <when> <javaclass


29

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/Hint.html

3.3.2.3.2. <hint> Element Attributes


title STRING Title this hint using the specified string. This attribute is required.

title="JBoss Seam Component Hint"

category-id STRING A reference to a category as defined in RHAMT_HOME/rules/migration-core/core.windup.categories.xml. The defaultcategories are mandatory, optional, and potential.

category-id="mandatory"

in VARIABLE_NAME Create a new Hint in the FileLocationModel resolved by thegiven variable.

in="Foo"

effort BYTE The level of effort assigned to this resource.

effort="2"

3.3.2.3.3. <hint> Child Elements


references="weblogic.wsee.connection.transport.http.HttpTransportInfo.setUsername({*})" as="default"> <location>METHOD</location> </javaclass> </when> <perform> <iteration> <hint title="Proprietary web-service" category-id="mandatory" effort="3"> <message>Replace proprietary web-service authentication with JAX-WS standards.</message> <link href="http://java-x.blogspot.com/2009/03/invoking-web-services-through-proxy.html" title="JAX-WS Proxy Password Example"/> </hint> </iteration> </perform></rule>


30

<message> A message describing the migration hint.

<link> Identify or classify links to informational content. See the section on <link> Syntax fordetails.

<tag> Define a custom tag for this hint.

<quickfix> Contains information to be used by the Eclipse plugin to perform quick fixes when therule condition is met.


3.3.2.4. <xslt> Syntax

3.3.2.4.1. Summary

The <xslt> element specifies how to transform an XML file. For a better understanding of the <xslt>action, see the JavaDoc for the XSLTTransformation class.

The following is an example of rule that defines an XSLT action.

3.3.2.4.2. <xslt> Element Attributes

<message>EJB 2.0 is deprecated</message>

<link href="http://docs.oracle.com/javaee/6/api/" title="Java Platform, Enterprise Edition 6API Specification" />

<tag>Needs review</tag>

<quickfix name="slink-qf" type="REPLACE"> <replacement>h:link</replacement> <search>s:link</search></quickfix>

<rule id="XmlWebLogicRules_6bcvk"> <when> <xmlfile as="default" matches="/weblogic-ejb-jar"/> </when> <perform> <iteration> <classification title="Weblogic EJB XML" effort="3"/> <xslt title="JBoss EJB Descriptor (Windup-Generated)" template="transformations/xslt/weblogic-ejb-to-jboss.xsl" extension="-jboss.xml"/> </iteration> </perform></rule>


31

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/xml/operation/xslt/XSLTTransformation.html


title STRING Sets the title for this XSLTTransformation in the report. Thisattribute is required.

title="XSLT Transformed Output"

of STRING Create a new transformation for the given reference.

of="testVariable_instance"

extension STRING Sets the extension for this XSLTTransformation. This attribute isrequired.

extension="-result.html"

template STRING Sets the XSL template. This attribute is required.

template="simpleXSLT.xsl"

effort BYTE The level of effort required for the transformation.

3.3.2.4.3. <xslt> Child Elements


<xslt-parameter> Specify XSLTTransformation parameters as property value pairs

3.3.2.4.3.1. <lineitem> Syntax

3.3.2.4.4. Summary

The <lineitem> element is used to provide general migration requirements for the application, such asthe need to replace deprecated libraries or the need to resolve potential class loading issues. Thisinformation is displayed on the project or application overview page. For a better understanding of the <lineitem> action, see the JavaDoc for the LineItem class.

The following is an example of a rule that creates a lineitem message.

<xslt-parameter property="title" value="EJB Transformation"/>

<rule id="weblogic_servlet_annotation_1000"> <when> <javaclass references="weblogic.servlet.annotation.WLServlet" as="default"> <location>ANNOTATION</location>


32

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/project/operation/LineItem.html

3.3.2.4.5. <lineitem> Element Attributes


message STRING A lineitem message.

message="Proprietary code found."

3.3.2.5. <iteration> Syntax

3.3.2.5.1. Summary

The <iteration> element specifies to iterate over an implicit or explicit variable defined within the rule.For a better understanding of the <iteration> action, see the JavaDoc for the Iteration class.

The following is an example of a rule that performs an iteration.

</javaclass> </when> <perform> <hint effort="1"> <message>Replace the proprietary WebLogic @WLServlet annotation with the Java EE 6 standard @WebServlet annotation.</message> <link href="https://access.redhat.com/articles/1249423" title="Migrate WebLogic Proprietary Servlet Annotations" /> <lineitem message="Proprietary WebLogic @WLServlet annotation found in file."/> </hint> </perform></rule>

<rule id="jboss-eap5-xml-19000"> <when> <xmlfile as="jboss-app" matches="/jboss-app"/> <xmlfile as="jboss-app-no-DTD" matches="/jboss-app" public-id=""/> </when> <perform> <iteration over="jboss-app"> <classification title="JBoss application Descriptor" effort="5"/> </iteration> <iteration over="jboss-app-no-DTD"> <classification title="JBoss application descriptor with missing DTD" effort="5"/> </iteration> <iteration over="jboss-app-no-DTD"> <xslt title="JBoss application descriptor - JBoss 5 (Windup-generated)" template="transformations/xslt/jboss-app-to-jboss5.xsl" extension="-jboss5.xml"/> </iteration> </perform></rule>


33

http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/Iteration.html

3.3.2.5.2. <iteration> Element Attributes


over VARIABLE_NAME Iterate over the condition identified by this VARIABLE_NAME.

over="jboss-app"

3.3.2.5.3. <iteration> Child Elements


<iteration> Child elements include a when condition, along with the actions iteration, classification, hint, xslt, lineitem, and otherwise.

3.3.3. Where 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 <where> element to define a parameter. Specify the parameter name using the param attributeand supply the pattern using the <matches> element. This parameter can then be referenced elsewherein the rule definition using the syntax {PARAM_NAME}.


The following example rule defines a parameter named subpackage that specifies a pattern of (activeio|activemq).

The pattern defined by subpackage will then be substituted in the <javaclass> referencesattribute. This causes the rule to match on org.apache.activeio.* and org.apache.activemq.*packages.

<rule id="generic-catchall-00600"> <when> <javaclass references="org.apache.{subpackage}.{*}"> </javaclass> </when> <perform> ... </perform> <where param="subpackage"> <matches pattern="(activeio|activemq)" /> </where></rule>


34


CHAPTER 4. TESTING XML RULES

4.1. ADD THE RULE TO RED HAT APPLICATION MIGRATION TOOLKIT

A Red Hat Application Migration Toolkit rule is installed by copying the rule to the appropriate RHAMTfolder. RHAMT scans for rules, which are files that end with .windup.xml or .rhamt.xml, in thefollowing locations.

The directory specified by the --userRulesDirectory argument on the RHAMT commandline.

The RHAMT_HOME/rules/ directory. RHAMT_HOME is the directory where you install and run theRed Hat Application Migration Toolkit executable.

The ${user.home}/.rhamt/rules/ directory. This directory is created by RHAMT the firsttime it is executed and contains rules, add-ons, and the RHAMT log.

NOTE

For Windows, this directory would be \Documents and Settings\USER_NAME\.rhamt\rules\ or \Users\USER_NAME\.rhamt\rules\.

4.2. TEST THE XML RULE

Test the XML rule against your application file by running RHAMT in a terminal.

$ RHAMT_HOME/bin/rhamt-cli [--sourceMode] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N

You should see the following result:

Report created: OUTPUT_REPORT_DIRECTORY/index.html Access it at this URL: file:///OUTPUT_REPORT_DIRECTORY/index.html

More examples of how to run RHAMT are located in the Red Hat Application Migration Toolkit CLI Guide.

CHAPTER 4. TESTING XML RULES

35


CHAPTER 5. OVERRIDING RULESYou can override core rules distributed with RHAMT or even custom-written rules. For example, youmight want to change the matching conditions, effort, or hint text for a rule. This is done by making acustom copy of the original rule, marking it as a rule override, and making the necessary adjustments.You can also disable a rule in this same manner.

5.1. OVERRIDE A RULE

You can override a rule using the following steps.

1. Copy the XML file that contains the rule you want to override to the custom rules directory.Custom rules can be placed in either RHAMT_HOME/rules, ${user.home}/.rhamt/rules/,or the directory specified by the --userRulesDirectory command-line argument.

2. Edit the XML file and only keep the <rule> elements for the rules that you want to override.Note that the rules from the original ruleset that are not overridden in the new ruleset will beexecuted as normal.

3. Ensure that you keep the same rule and ruleset IDs. When you copy the original rule XML, thisensures that the IDs match.

4. Add the <overrideRules>true</overrideRules> entry to the ruleset metadata.

5. Make the adjustments to the rule as necessary.You can change anything in the rule definition. This rule will override the entire original rule.

The below is an example of an overridden rule. Notice the <overrideRules>true</overrideRules> element in the ruleset metadata. The rule and rulesetIDs match the original. This rule override changed the effort needed from a 1 to a 3.

<?xml version="1.0"?><ruleset id="weblogic" xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata> ... <overrideRules>true</overrideRules> </metadata> <rules> <rule id="weblogic-02000" xmlns="http://windup.jboss.org/schema/jboss-ruleset"> <when> <javaclass references="weblogic.utils.StringUtils.{*}"/> </when> <perform> <hint effort="3" category-id="mandatory" title="WebLogic StringUtils Usage"> <message>Replace with the StringUtils class from Apache Commons.</message> <link href="https://commons.apache.org/proper/commons-lang/" title="Apache Commons Lang"/>


36

When you run RHAMT, this rule will now be used in place of the original rule with the matching rule ID.You can verify that the new rule was used by viewing the contents of the Rule Provider ExecutionsOverview.

5.2. DISABLE A RULE

To disable a rule, follow the same steps as above to override a rule, except provide an empty <rule>element.

<tag>weblogic</tag> </hint> </perform> </rule> </rules></ruleset>

<?xml version="1.0"?><ruleset id="weblogic" xmlns="http://windup.jboss.org/schema/jboss-ruleset" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://windup.jboss.org/schema/jboss-ruleset http://windup.jboss.org/schema/jboss-ruleset/windup-jboss-ruleset.xsd"> <metadata> ... <overrideRules>true</overrideRules> </metadata> <rules> <rule id="weblogic-02000" xmlns="http://windup.jboss.org/schema/jboss-ruleset">  </rule> </rules></ruleset>

CHAPTER 5. OVERRIDING RULES

37

CHAPTER 6. USING CUSTOM RULE CATEGORIESA new category field was added in RHAMT 3.0 that replaces the concept of the severity field in RHAMTrules. The default categories are the same that were available in the severity field: mandatory, optional, and potential. However, you can now add your own custom rule categories and assignRHAMT rules to them.

IMPORTANT

Although RHAMT can still process rules that use the legacy severity field, it isrecommended to update your custom rules to use the new category-id field.

Add a Custom Category

1. Edit the rule category file, which is located at RHAMT_HOME/rules/migration-core/core.windup.categories.xml.

2. Add a new <category> element and fill in the following fields:

id: The ID that RHAMT rules will use to reference the category.

priority: The sorting priority compared to other categories. The category with the lowestvalue is displayed first.

name: The display name of the category.

description: The description of how the category is intended to be used.

Example Custom Rule Category

This category is now ready to be referenced by RHAMT rules.

Assign a Rule to a Custom CategoryIn your RHAMT rule, use the custom category’s id value in the rule’s category-id field.

Example Rule Using a Custom Rule Category

<?xml version="1.0"?><categories> ... <category id="custom-category" priority="20000"> <name>Custom Category</name> <description>This is a custom category.</description> </category></categories>

<rule id="rule-id"> <when> ... </when> <perform> <hint title="Rule Title" effort="1" category-id="custom-category"> <message>Hint message.</message>


38

Now when you run RHAMT and this rule’s condition is met, incidents identified by this rule will use yourcustom category. The custom category can be seen in the RHAMT report in places such as thedashboard and Issues report.

Figure 6.1. Custom Category on the Dashboard

</hint> </perform> </rule>

CHAPTER 6. USING CUSTOM RULE CATEGORIES

39

APPENDIX A. REFERENCE MATERIAL

A.1. RULE STORY POINTS

A.1.1. What are Story Points?

Story points are an abstract metric commonly used in Agile software development to estimate the levelof effort needed to implement a feature or change.

Red Hat Application Migration Toolkit uses story points to express the level of effort needed to migrateparticular 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.1.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 generalguidelines RHAMT 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 formigration.

Trivial 1 The migration is a trivial change or a simple library swap with noor minimal API changes.

Complex 3 The changes required for the migration task are complex, buthave a documented solution.

Redesign 5 The migration task requires a redesign or a complete librarychange, with significant API changes.

Rearchitecture 7 The migration requires a complete rearchitecture of thecomponent or subsystem.

Unknown 13 The migration solution is not known and may need a completerewrite.

A.1.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 resultingapplication will not build or run successfully. Examples include replacement of proprietary APIs thatare not supported in the target platform.

Optional


40

If the migration task is not completed, the application should work, but the results may not be theoptimal. If the change is not made at the time of migration, it is recommended to put it on the schedulesoon 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.

A.2. ADDITIONAL RESOURCES

A.2.1. Review the Existing RHAMT XML Rules

RHAMT XML-based rules are located on GitHub at the following location:https://github.com/windup/windup-rulesets/tree/master/rules-reviewed.

Instructions to fork and clone the RHAMT rulesets repository to your local machine are provided on theWiki.

Rules are grouped by target platform and function. When you create a new rule, it is helpful to find a rulethat 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.

A.2.2. Important Links

RHAMT Javadoc: http://windup.github.io/windup/docs/latest/javadoc

RHAMT forums: https://developer.jboss.org/en/windup

RHAMT JIRA issue trackers

Core RHAMT: https://issues.jboss.org/browse/WINDUP

RHAMT Rules: https://issues.jboss.org/browse/WINDUPRULE

RHAMT mailing list: [email protected]

RHAMT on Twitter: @JBossWindup

RHAMT IRC channel: Server FreeNode (irc.freenode.net), channel #windup (transcripts)

Revised on 2018-04-04 12:21:18 EDT

APPENDIX A. REFERENCE MATERIAL

41

https://github.com/windup/windup-rulesets/tree/master/rules-reviewed

https://github.com/windup/windup/wiki/Dev-Get-the-Source-Code#fork-and-clone-the-windup-rulesets-repository

http://windup.github.io/windup/docs/latest/javadoc

https://developer.jboss.org/en/windup

https://issues.jboss.org/browse/WINDUP

https://issues.jboss.org/browse/WINDUPRULE

mailto:[email protected]

https://twitter.com/jbosswindup

http://transcripts.jboss.org/channel/irc.freenode.org/%23windup/index.html

Date post:	11-Mar-2020
Category:	Documents
Upload:	others
View:	25 times
Download:	0 times