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 that describes how to migrate the code.

Create the Directory Structure for the Rule

Create 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

Create the Rule

RHAMT XML-based rules use the following rule pattern:

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

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

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

<?xml version="1.0"?>
<ruleset id="JBoss5-web-class-loading"
    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>

Install the Rule

An RHAMT rule is installed by placing the rule into the appropriate directory. See Add the Rule to RHAMT 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

Open a terminal and execute the following command, passing the test file as an input argument and a directory 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 Reports

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

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

You can download a ZIP file of the latest released version of the quickstarts. Or, if you prefer to work with the 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

Fork and Clone the Quickstart GitHub Project

You must have the git client installed on your machine.