XML rule structure

This section describes the basic structure of XML rules. All XML rules are defined as elements within rulesets. For more details, see the {ProductShortName} XML rule schema.

Rulesets

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

• <ruleset id="<UNIQUE_RULESET_ID>">: Defines this as an {ProductShortName} ruleset and gives it a unique 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 with the same ID from the core ruleset distributed with {ProductShortName}. Both the ruleset id and the rule id must match a rule within the core ruleset, or the rule will be ignored. In addition, the target technology in this ruleset must match one of the targets that you specified for running the analysis.

      This is false by default.

  • <rules>: A set of individual rules.

    • <rule id="<UNIQUE_RULE_ID>">: Defines the rule and gives it a unique ID. It is recommended 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 a ruleset.

      • <when>: The conditions to match on.

      • <perform>: The action to be performed when the rule condition is matched.

      • <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 in the rule definition.

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

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

Predefined rules

{ProductShortName} provides predefined rules for common migration requirements. These core {ProductShortName} rules are located in the {ProductShortName} installation at <{ProductShortName}_HOME>/rules/migration-core/.

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

<?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>