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 MTA 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 MTA 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 MTA. Both the ruleset id and the rule id must match a rule within the core ruleset or the rule will be ignored. 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 a organization name.

3.1.2. Predefined rules

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

The following is an example of a core MTA 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 MTA XML rule. This assumes that you already have MTA installed. See the MTA CLI Guide for installation instructions.

3.2.1. Creating a basic XML rule template

MTA 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 or .mta.xml extension. Otherwise, MTA 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.

ElementDescription

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

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

ElementDescription

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

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 ElementDescription

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

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.

FunctionDescription

windup:matches()

Match a XPath expression against a string, possibly containing MTA 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 elementDescription

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

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 elementDescription

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

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

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 nameTypeDescription

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 nameTypeDescription

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"

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 nameTypeDescription

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 nameTypeDescription

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 NameTypeDescription

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"
3.3.1.8.2.2. <graph-query> properties
Property NameTypeDescription

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 nameTypeDescription

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

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

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 nameTypeDescription

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

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

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 elementDescription

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

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 nameTypeDescription

over

VARIABLE_NAME

Iterate over the condition identified by this VARIABLE_NAME.

over="jboss-app"
3.3.2.6.3. <iteration> child elements
Child ElementDescription

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

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

  • Directory specified by the --userRulesDirectory argument on the MTA command line.
  • <MTA_HOME>/rules/ directory. <MTA_HOME> is the directory where you install and run the Migration Toolkit for Applications executable.
  • ${user.home}/.mta/rules/ directory. This directory is created by MTA the first time it is run. it contains rules, add-ons, and the MTA log.

    Note

    In a Windows operating system, the rules are located in \Documents and Settings\<USER_NAME>\.mta\rules\ or \Users\<USER_NAME>\.mta\rules\.