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.{*} . matchesSource STRING An exact regex to match. This is useful to distinguish hard-coded strings. 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. from VARIABLE_NAME Begin the search query with the filtered result from a search identified by its as VARIABLE_NAME. in PATH_FILTER Filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. 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: 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. xpathResultMatch XPATH_RESULT_STRING Return results that match the given regex. 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. in PATH_FILTER Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. from VARIABLE_NAME Begin the search query with the filtered result from a search identified by its as VARIABLE_NAME. public-id PUBLIC_ID The DTD public-id regex. 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 windup:matches() Match a XPath expression against a string, possibly containing MTR parameterization placeholders. 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 <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 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. from VARIABLE_NAME Begin the search query with the filtered result from a search identified by its as VARIABLE_NAME. 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 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. from VARIABLE_NAME Begin the search query with the filtered result from a search identified by its as VARIABLE_NAME. Example: 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.*\.jarUSD</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 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 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. effort BYTE The level of effort assigned to this resource. 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 . of VARIABLE_NAME Create a new classification for the given reference. 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> 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. title STRING A title for the link. 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. 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 . in VARIABLE_NAME Create a new Hint in the FileLocationModel resolved by the given variable. effort BYTE The level of effort assigned to this resource. 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. of STRING Create a new transformation for the given reference. extension STRING Sets the extension for this XSLTTransformation. This attribute is required. template STRING Sets the XSL template. This attribute is required. 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"/> 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. 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. 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. USD{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\ .

Commands:
<?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>
when(condition) perform(action) otherwise(action)
<?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>
<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>
<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>
references="weblogic.apache.xml.{*}"
matchesSource="log4j.logger"
as="MyEjbRule"
from="MyEjbRule"
in="{*}File1"
<location>IMPORT</location>
<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>
<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>
matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']"
<xmlfile matches="//foo/text()" xpathResultMatch="Text from foo."/>
as="MyEjbRule"
in="{*}File1"
from="MyEjbRule"
public-id="public"
matches="windup:matches(//foo/@class, '{javaclassname}')"
<namespace prefix="abc" uri="http://maven.apache.org/POM/4.0.0"/>
<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>
as="MyEjbRule"
from="MyEjbRule"
as="MyEjbRule"
from="MyEjbRule"
<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>
<rule id="embedded-cache-libraries-01000"> <when> <graph-query discriminator="JarArchiveModel"> <property name="fileName" searchType="regex">.*ehcache.*\.jarUSD</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>
as="MyEjbRule"
from="MyEjbRule"
<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>
<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>
title="JBoss Seam Components"
effort="2"
category-id="mandatory"
of="MySeamRule"
<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>
<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>
href="https://access.redhat.com/articles/1249423"
title="Migrate WebLogic Proprietary Servlet Annotations"
<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>
title="JBoss Seam Component Hint"
category-id="mandatory"
in="Foo"
effort="2"
<message>EJB 2.0 is deprecated</message>
<link href="http://docs.oracle.com/javaee/6/api/" title="Java Platform, Enterprise Edition 6 API 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>
title="XSLT Transformed Output"
of="testVariable_instance"
extension="-result.html"
template="simpleXSLT.xsl"
<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> </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>
message="Proprietary code found."
<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>
over="jboss-app"
<rule id="generic-catchall-00600"> <when> <javaclass references="org.apache.{subpackage}.{*}"> </javaclass> </when> <perform> </perform> <where param="subpackage"> <matches pattern="(activeio|activemq)" /> </where> </rule>