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 within rulesets. For more details, see the MTR 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 basic structure of the <ruleset> element.

<ruleset id="<UNIQUE_RULESET_ID>">: Defines this as an MTR 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 MTR. 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.

3.1.2. Predefined rules

MTR provides predefined rules for common migration requirements. These core MTR rules are located in the MTR installation at <MTR_HOME>/rules/migration-core/.

The following is an example of a core MTR 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>

3.2. Creating a basic XML rule

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

3.2.1. Creating a basic XML rule template

MTR XML rules consist of conditions and actions and use the following rule pattern:

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

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

Important

The XML file name must include the .windup.xml extension. Otherwise, MTR does not evaluate the new rule.

<?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 about the rule including a description,
         source technology, target technology, and any
         add-on dependencies -->
  </metadata>
<rules>
    <rule id="unique-ruleset-id-01000">
        <when>
            <!-- Test a condition... -->
        </when>
        <perform>
            <!-- Perform this action when condition is satisfied -->
        </perform>
        <otherwise>
            <!-- Perform this action when condition is not satisfied -->
        </otherwise>
    </rule>
  <rules>
</ruleset>

3.2.2. Creating the ruleset metadata

The XML ruleset metadata element provides additional information about the ruleset such as a description, the source and target technologies, and add-on dependencies. The metadata also allows for specification of tags, which allow you to provide additional information about a ruleset.

<metadata> example

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

3.2.3. Creating a rule

Individual rules are contained within the <rules> element. They comprise one or more when conditions and perform actions.

See the XML rule schema for valid rule syntax.

3.2.3.1. Creating a `<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 that you would like to ignore in processing discovery.
<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.

The specific syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file, a project, or file content.

3.2.3.2. Creating a `<perform>` action

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

Element	Description
<classification>	This operation adds metadata that you want to apply to the entire file. For example, if the Java Class is a JMS Message Listener, you can add a Classification with the title "JMS Message Listener" that includes information that applies to the entire file. You can also set an effort level for the entire file.
<hint>	This operation adds metadata to a line within the file. This provides a hint or inline information 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 is displayed in the application overview page.
<link>	This provides an HTML link to additional information or documentation about the migration task.
<xslt>	This specifies how to transform an XML file.

3.3. XML rule syntax

3.3.1. `<when>` syntax

Conditions allowed in the when portion of a rule must extend GraphOperation and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding 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
<graph-query> condition syntax
<dependency> condition syntax

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

3.3.1.1. <javaclass> syntax

3.3.1.1.1. Summary

Use the <javaclass> element to find imports, methods, variable declarations, annotations, class implementations, 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>

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 characters can be used. This attribute is required. Note For performance reasons, you should not start the reference with wildcard characters. For example, 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-coded strings. This attribute is required. matchesSource="log4j.logger"
as	VARIABLE_NAME	A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. as="MyEjbRule"
from	VARIABLE_NAME	Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. from="MyEjbRule"
in	PATH_FILTER	Filter input files matching this regex (regular expression) naming pattern. 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 to annotations, field and variable declarations, imports, and methods. For the complete list of valid values, see the JavaDoc for TypeReferenceLocation. <location>IMPORT</location>
<annotation-literal>	Match on literal values inside of annotations. The following example matches on `@MyAnnotation(myvalue="test")`. <javaclass references="org.package.MyAnnotation"> <location>ANNOTATION</location> <annotation-literal name="myvalue" pattern="test"/> </javaclass> Note that in this case, the `<javaclass>` refers to an annotation (`@MyAnnotation`), so the top-level annotation filter, `<annotation-literal>` must specify the `name` attribute. If the `<javaclass>` referred to a class that is annotated, then the top-level annotation filter used would be `<annotation-type>`.
<annotation-type>	Match on a particular annotation type. You can supply subconditions to be matched against the annotation elements. The below example would match on a `Calendar` field declaration annotated with `@MyAnnotation(myvalue="test")`. <javaclass references="java.util.Calendar"> <location>FIELD_DECLARATION</location> <annotation-type pattern="org.package.MyAnnotation"> <annotation-literal name="myvalue" pattern="test"/> </annotation-type> </javaclass>
<annotation-list>	Match on an item in an array within an annotation. If an array index is not specified, the condition will be matched if it applies to any item in the array. You can supply subconditions to be matched against this element. The below example would match on `@MyAnnotation(mylist={"one","two"})`. <javaclass references="org.package.MyAnnotation" > <location>ANNOTATION</location> <annotation-list name="mylist"> <annotation-literal pattern="two"/> </annotation-list> </javaclass> Note that in this case, the `<javaclass>` refers to an annotation (`@MyAnnotation`), so the top-level annotation filter, `<annotation-list>` must specify the `name` attribute. If the `<javaclass>` referred to a class that is annotated, then the top-level annotation filter used would be `<annotation-type>`.

3.3.1.2. <xmlfile> syntax

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 JavaDoc for the XmlFile class.

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

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

3.3.1.2.2. Construct an <xmlfile> element

3.3.1.2.2.1. <xmlfile> element attributes

Attribute name	Type	Description
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	VARIABLE_NAME	A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. as="MyEjbRule"
in	PATH_FILTER	Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. in="{*}File1"
from	VARIABLE_NAME	Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. 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 side effects, like setting the matched value on the rule variables stack.

Function Description

Function	Description
`windup:matches()`	Match a XPath expression against a string, possibly containing MTR parameterization placeholders. matches="windup:matches(//foo/@class, '{javaclassname}')" This will match all `<foo/>` elements with a `class` attribute and store their value into `javaclassname` parameter for each iteration.

windup:matches()

Match a XPath expression against a string, possibly containing MTR parameterization placeholders.

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

This will match all <foo/> elements with a class attribute and store their value into javaclassname parameter for each iteration.

3.3.1.2.2.3. <xmlfile> child elements

Child element Description

Child element	Description
<namespace>	The namespace referenced in XML files. This element contains two optional attributes: The `prefix` and the `uri`. <namespace prefix="abc" uri="http://maven.apache.org/POM/4.0.0"/>

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

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

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 better understanding 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.Final and 2.2.0.Final.

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

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 this condition to query for dependencies of the project. It does not have any attributes itself.

3.3.1.3.2.2. <project> child elements

Child element	Description
<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

Attribute name	Type	Description
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`.

It is possible to qualify the element within the POM file that contains the artifact that the rule is searching for. This is achieved using the optional <location> element. The example below shows a rule that is searching for an artifact within the <plugins> element of the POM file.

The valid list of locations is as follows:

DEPENDENCY_MANAGEMENT
DEPENDENCIES
PLUGIN_MANAGEMENT
PLUGINS
PARENT

3.3.1.4. <filecontent> syntax

3.3.1.4.1. Summary

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

3.3.1.4.2. Construct a <filecontent> element

3.3.1.4.2.1. <filecontent> element attributes

Attribute name	Type	Description
pattern	String	Match the file contents against the provided parameterized string. This attribute is required.
filename	String	Match the file names against the provided parameterized string.
as	VARIABLE_NAME	A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. as="MyEjbRule"
from	VARIABLE_NAME	Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. 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 for the File class.

3.3.1.5.2. Construct a <file> element

3.3.1.5.2.1. <file> element attributes

Attribute name Type Description

Attribute name	Type	Description
filename	String	Match the file names against the provided parameterized string. This attribute is required.
as	VARIABLE_NAME	A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. as="MyEjbRule"
from	VARIABLE_NAME	Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. Example: from="MyEjbRule"

filename

String

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

VARIABLE_NAME

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

as="MyEjbRule"

from

VARIABLE_NAME

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

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 is primarily used to prevent firing if a hint already exists, or to implement rules for default execution when no other conditions apply. For a better understanding of the <has-hint> condition, see the JavaDoc for the HasHint class.

The following is an example of a rule that checks to see if a hint exists for an IBM JMS destination message, 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>
  <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 child elements.

3.3.1.6.2.1. <has-hint> element attributes

Attribute name	Type	Description
message	String	An optional argument allowing you to match the hint against the provided 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 is primarily used to prevent firing if a classification already exists, or to implement rules for default execution 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 not have any child elements.

3.3.1.7.2.1. <has-classification> element attributes

Attribute name	Type	Description
title	String	An optional title to match the classification against.

3.3.1.8. <graph-query> syntax

3.3.1.8.1. Summary

Use the <graph-query> element to search the generated graph for any elements. This element is primarily used to search for specific archives. For a better understanding of the <graph-query> condition, see the JavaDoc for the QueryHandler class.

The following is an example of a rule that tests to determine if any ehcache packages are found.

<rule id="embedded-cache-libraries-01000">
    <when>
        <graph-query discriminator="JarArchiveModel">
            <property name="fileName" searchType="regex">.*ehcache.*\.jar$</property>
        </graph-query>
    </when>
    <perform>
        <classification title="Caching - Ehcache embedded library" category-id="cloud-mandatory" effort="5">
            <description>
                The application embeds an Ehcache library.

                Cloud readiness issue as potential state information that is not persisted to a backing service.
            </description>
        </classification>
        <technology-tag level="INFORMATIONAL">Ehcache (embedded)</technology-tag>
    </perform>
</rule>

3.3.1.8.2. Construct a <graph-query>

3.3.1.8.2.1. <graph-query> element attributes

Attribute Name Type Description

Attribute Name	Type	Description
discriminator	MODEL_TYPE	The type of model to use for searching. This can be any valid model; however, it is recommended to use the `JarArchiveModel` for examining archives. This attribute is required.
as	VARIABLE_NAME	A variable name assigned to the rule so that it can be used as a reference in later processing. See the `from` attribute below. as="MyEjbRule"
from	VARIABLE_NAME	Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. from="MyEjbRule"

discriminator

MODEL_TYPE

The type of model to use for searching. This can be any valid model; however, it is recommended to use the JarArchiveModel for examining archives. This attribute is required.

VARIABLE_NAME

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

as="MyEjbRule"

from

VARIABLE_NAME

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

from="MyEjbRule"

3.3.1.8.2.2. <graph-query> properties

Property Name	Type	Description
name	String	The name of the attribute to match against within the chosen model. When using any file-based models, it is recommended to match on `fileName`. This attribute is required.
type	property-type	Defines the expected type of property, either `STRING` or `BOOLEAN`.
searchType	property-search-type	Defines how the condition is matched. If set to `equals`, then an exact match must be made. If using `regex`, then regular expressions can be used.

3.3.1.9. <dependency> syntax

3.3.1.9.1. Summary

Use the <dependency> element to search dependencies defined within the application’s POM file to determine whether they are supported by the target runtime.

The following is an example of a rule that checks for all artifacts belonging to the org.springframework.boot group that have a version up to, and including, 1.6.0.

<rule id="springboot-00001">
    <!-- rule condition, when it could be fired -->
    <when>
        <dependency groupId="org.springframework.boot" artifactId="{*}" toVersion="1.6.0" />
    </when>
    <!-- rule operation, what to do if it is fired -->
    <perform>
        <hint title="Unsupported version of Spring Boot" effort="3" category-id="mandatory">
            <message>Spring Boot has to be updated to Spring Boot 2.0 before being able to be migrated to a version supported by Red Hat Runtimes</message>
            <link href="https://access.redhat.com/articles/3349341" title="RHOAR Spring Boot Supported Configurations" />
            <link href="https://access.redhat.com/articles/3348731" title="RHOAR Component Details Overview" />
            <link href="https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide" title="Spring Boot 2.0 Migration Guide" />
        </hint>
    </perform>
</rule>

3.3.2. `<perform>` syntax

Operations available in the perform section of the rule include the classification of application resources, 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 related Java classes are provided for a better understanding of how they behave.

You can view the complete XML rule schema.

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

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 the rule. It provides a title that is displayed in the report, a level of effort, and it can also provide links to additional 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 application deployment descriptor file.

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

3.3.2.1.2. <classification> element attributes

Attribute name	Type	Description
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"
category-id	STRING	A reference to a category as defined in `MTR_HOME/rules/migration-core/core.windup.categories.xml`. The default categories are `mandatory`, `optional`, `potential`, and `information`. category-id="mandatory"
of	VARIABLE_NAME	Create a new classification for the given reference. of="MySeamRule"

3.3.2.1.3. <classification> child elements

Child element	Description
<link>	Provides a link URI and text title for additional information. <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>	Provides additional custom information for the classification. <tag>Seam3</tag>
<description>	Description of this resource <description>JBoss Seam components must be replaced</description>

Child element

Description

<link>

Provides a link URI and text title for additional information.

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

Provides additional custom information for the classification.

<tag>Seam3</tag>

Description of this resource

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

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 a better understanding of the <link> action, see the JavaDoc for the Link class.

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

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

3.3.2.2.2. <link> element attributes

Attribute Name	Type	Description
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"

Attribute Name

Type

Description

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 of code. 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="WebLogicWebServiceRules_8jyqn">
    <when>
        <javaclass 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>

3.3.2.3.2. <hint> element attributes

Attribute name	Type	Description
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 `MTR_HOME/rules/migration-core/core.windup.categories.xml`. The default categories are `mandatory`, `optional`, `potential`, and `information`. category-id="mandatory"
in	VARIABLE_NAME	Create a new Hint in the FileLocationModel resolved by the given variable. in="Foo"
effort	BYTE	The level of effort assigned to this resource. effort="2"

3.3.2.3.3. <hint> child elements

Child element	Description
<message>	A message describing the migration hint. <message>EJB 2.0 is deprecated</message>
<link>	Identify or classify links to informational content. <link href="http://docs.oracle.com/javaee/6/api/" title="Java Platform, Enterprise Edition 6 API Specification" />
<tag>	Define a custom tag for this `hint`. <tag>Needs review</tag>
<quickfix>	Contains information to be used by the MTR plugin to perform quick fixes when the rule condition is met. <quickfix name="slink-qf" type="REPLACE"> <replacement>h:link</replacement> <search>s:link</search> </quickfix>

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.

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

3.3.2.4.2. <xslt> element attributes

Attribute Name	Type	Description
title	STRING	Sets the title for this XSLTTransformation in the report. This attribute 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 is required. 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

Child element	Description
<xslt-parameter>	Specify XSLTTransformation parameters as property value pairs <xslt-parameter property="title" value="EJB Transformation"/>

Child element

Description

<xslt-parameter>

Specify XSLTTransformation parameters as property value pairs

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

3.3.2.5. <lineitem> syntax

3.3.2.5.1. Summary

The <lineitem> element is used to provide general migration requirements for the application, such as the need to replace deprecated libraries or the need to resolve potential class loading issues. This information 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.

<rule id="weblogic_servlet_annotation_1000">
    <when>
        <javaclass references="weblogic.servlet.annotation.WLServlet" as="default">
            <location>ANNOTATION</location>
        </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>

3.3.2.5.2. <lineitem> element attributes

Attribute Name	Type	Description
message	STRING	A lineitem message. message="Proprietary code found."

Attribute Name

Type

Description

message

STRING

A lineitem message.

message="Proprietary code found."

3.3.2.6. <iteration> syntax

3.3.2.6.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.

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

3.3.2.6.2. <iteration> element attributes

Attribute name	Type	Description
over	VARIABLE_NAME	Iterate over the condition identified by this VARIABLE_NAME. over="jboss-app"

Attribute name

Type

Description

over

VARIABLE_NAME

Iterate over the condition identified by this VARIABLE_NAME.

over="jboss-app"

3.3.2.6.3. <iteration> child elements

Child Element	Description
<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 attribute and supply the pattern using the <matches> element. This parameter can then be referenced elsewhere in the rule definition using the syntax {<PARAM_NAME>}.

You can view the complete XML rule schema.

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

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

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

3.4. Adding a rule to the Migration Toolkit for Runtimes

A Migration Toolkit for Runtimes rule is installed by copying the rule to the appropriate MTR folder. MTR scans for rules, which are files with the .windup.xml extension in the following locations:

Directory specified by the --userRulesDirectory argument on the MTR command line.
<MTR_HOME>/rules/ directory. <MTR_HOME> is the directory where you install and run the Migration Toolkit for Runtimes executable.
${user.home}/.mtr/rules/ directory. This directory is created by MTR the first time it is run. it contains rules, add-ons, and the MTR log.
Note
In a Windows operating system, the rules are located in \Documents and Settings\<USER_NAME>\.mtr\rules\ or \Users\<USER_NAME>\.mtr\rules\.

Chapter 3. Creating XML rules

3.1. XML rule structure

3.1.1. Rulesets

3.1.2. Predefined rules

3.2. Creating a basic XML rule

3.2.1. Creating a basic XML rule template

3.2.2. Creating the ruleset metadata

3.2.3. Creating a rule

3.2.3.1. Creating a <when> condition

3.2.3.2. Creating a <perform> action

3.3. XML rule syntax

3.3.1. <when> syntax

3.3.1.1. <javaclass> syntax

3.3.1.1.1. Summary

3.3.1.1.2. Construct a <javaclass> element

3.3.1.1.2.1. <javaclass> element attributes

3.3.1.1.2.2. <javaclass> child elements

3.3.1.2. <xmlfile> syntax

3.3.1.2.1. Summary

3.3.1.2.2. Construct an <xmlfile> element

3.3.1.2.2.1. <xmlfile> element attributes

3.3.1.2.2.2. <xmlfile> matches custom functions

3.3.1.2.2.3. <xmlfile> child elements

3.3.1.3. <project> syntax

3.3.1.3.1. Summary

3.3.1.3.2. Construct a <project> element

3.3.1.3.2.1. <project> element attributes

3.3.1.3.2.2. <project> child elements

3.3.1.3.2.3. <artifact> element attributes

3.3.1.4. <filecontent> syntax

3.3.1.4.1. Summary

3.3.1.4.2. Construct a <filecontent> element

3.3.1.4.2.1. <filecontent> element attributes

3.3.1.5. <file> syntax

3.3.1.5.1. Summary

3.3.1.5.2. Construct a <file> element

3.3.1.5.2.1. <file> element attributes

3.3.1.6. <has-hint> syntax

3.3.1.6.1. Summary

3.3.1.6.2. Construct a <has-hint>

3.3.1.6.2.1. <has-hint> element attributes

3.3.1.7. <has-classification> syntax

3.3.1.7.1. Summary

3.3.1.7.2. Construct a <has-classification>

3.3.1.7.2.1. <has-classification> element attributes

3.3.1.8. <graph-query> syntax

3.3.1.8.1. Summary

3.3.1.8.2. Construct a <graph-query>

3.3.1.8.2.1. <graph-query> element attributes

3.3.1.8.2.2. <graph-query> properties

3.3.1.9. <dependency> syntax

3.3.1.9.1. Summary

3.3.2. <perform> syntax

3.3.2.1. <classification> syntax

3.3.2.1.1. Summary

3.3.2.1.2. <classification> element attributes

3.3.2.1.3. <classification> child elements

3.3.2.2. <link> syntax

3.3.2.2.1. Summary

3.3.2.2.2. <link> element attributes

3.3.2.3. <hint> syntax

3.3.2.3.1. Summary

3.3.2.3.2. <hint> element attributes

3.3.2.3.3. <hint> child elements

3.3.2.4. <xslt> syntax

3.3.2.4.1. Summary

3.3.2.4.2. <xslt> element attributes

3.3.2.4.3. <xslt> child elements

3.3.2.5. <lineitem> syntax

3.3.2.5.1. Summary

3.3.2.5.2. <lineitem> element attributes

3.3.2.6. <iteration> syntax

3.3.2.6.1. Summary

3.3.2.6.2. <iteration> element attributes

3.3.2.6.3. <iteration> child elements

3.3.3. <where> syntax

3.4. Adding a rule to the Migration Toolkit for Runtimes

Learn

Try, buy, & sell

Communities

3.2.3.1. Creating a `<when>` condition

3.2.3.2. Creating a `<perform>` action

3.3.1. `<when>` syntax

3.3.1.2.2.2. <xmlfile> `matches` custom functions

3.3.2. `<perform>` syntax

3.3.3. `<where>` syntax