Red Hat SummitWindup Rules Development Guide
Create Custom Rules for Windup
Abstract
Chapter 1. Introduction
This guide is for engineers, consultants, and others who plan to create custom XML-based rules for Windup.
If you are new to Windup, it is recommended that you start with the Windup User Guide. It provides detailed information about system requirements and detailed instructions on how to install and execute Windup. It also contains tips to optimize performance and provides links to other sources of information about Windup.
If you would like to contribute to the Windup source code base or provide Java-based rule add-ons, see the Windup Wiki.
Chapter 2. Get Started
2.1. Create Your First XML Rule
Overview
This topic guides you through the process of creating and testing your first Windup XML-based rule.
Windup XML-base rules use the following familiar rule pattern:
when(condition)
perform(action)
otherwise(action)
when(condition)
perform(action)
otherwise(action)Ruleset and Rule XML elements are covered in more detail here: XML Rule Construction.
Additional details about creating XML rules, with example syntax, can be found here: Create a Basic XML Rule.
As you create your first rule, refer to the Rules Schema for valid XML syntax.
Rule Example Description
In this example, you write a rule to discover instances where an application defines a jboss-web.xml file containing a <class-loading> element and provide a link to the documentation that describes how to migrate the code.
Create the Directory Structure for the Rule
Create a directory structure to contain your first rule and the data file to use for testing.
mkdir -p migration-rules/rules mkdir -p migration-rules/data
$ mkdir -p migration-rules/rules $ mkdir -p migration-rules/dataCopy to Clipboard Copied! Toggle word wrap Toggle overflow - This directory structure will also be used to hold the generated Windup reports.
Create Data to Test the Rule
-
Use your favorite editor or IDE to create a
jboss-web.xmlfile in the~/migration-rules/data/subdirectory. Copy in the following content.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Create the Rule
Use your favorite editor or IDE to create an XML file in the
~/migration-rules/rules/subdirectory namedJBoss5-web-class-loading.windup.xml. Copy in the following content.Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteWindup identifies files with the
.windup.xmlextension as XML-based rules, so be sure to use this naming convention, otherwise the rule will not be evaluated!Add the unique identifier for the ruleset and rule.
-
Replace the
UNIQUE_RULESET_IDwith the file name: "JBoss5-web-class-loading" -
Replace the
UNIQUE_RULE_IDwith the ruleset ID appended with '_001': "JBoss5-web-class-loading_001"
-
Replace the
Add the following ruleset addon dependencies.
<addon id="org.jboss.windup.rules,windup-rules-javaee,2.5.0.Final"/> <addon id="org.jboss.windup.rules,windup-rules-java,2.5.0.Final"/>
<addon id="org.jboss.windup.rules,windup-rules-javaee,2.5.0.Final"/> <addon id="org.jboss.windup.rules,windup-rules-java,2.5.0.Final"/>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add the source and target technologies.
-
Replace the sourceTechnology
SOURCE_IDwith: "eap" -
Replace the targetTechnology
TARGET_IDwith: "eap" -
Replace the sourceTechnology
VERSION_RANGEwith: "(4,5)" -
Replace the targetTechnology
VERSION_RANGEwith: "[6,)"
-
Replace the sourceTechnology
Complete the
whencondition.-
Because this rule finds
jboss-web.xmlfiles containing theclass-loadingelement, we usexmlfileto evaluate the files. To match on the
class-loadingelement that is a child ofjboss-web, use the xpath expression "jboss-web/class-loading".<when> <xmlfile matches="jboss-web/class-loading" /> </when><when> <xmlfile matches="jboss-web/class-loading" /> </when>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Because this rule finds
Complete the
performaction for this rule.- Add a classification and descriptive title.
- Assign a level of effort of "1" to this task.
Provide a hint with an informative message and a link to documentation that describes the migration details.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
The rule is now complete and should look like the following example.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Install the Rule
A Windup rule is installed simply by copying the rule to the appropriate folder.
Copy the JBoss5-web-class-loading.windup.xml file to your ${user.home}/.windup/rules/ directory.
For Linux or Mac: ~/.windup/rules/ For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" or "\Users\USER_NAME\.windup\rules\"
For Linux or Mac: ~/.windup/rules/
For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" or "\Users\USER_NAME\.windup\rules\"Test the Rule
- Open a terminal and navigate to the WINDUP_HOME directory.
Type the following command to test the rule in Windup, passing the test file as an input argument and a directory for the output report.
For Linux: bin/windup --sourceMode --input ~/migration-rules/data --output ~/migration-rules/reports --source eap --target eap For Windows: bin\windup.bat --sourceMode --input migration-rules\data --output migration-rules\reports --source eap --target eap
For Linux: bin/windup --sourceMode --input ~/migration-rules/data --output ~/migration-rules/reports --source eap --target eap For Windows: bin\windup.bat --sourceMode --input migration-rules\data --output migration-rules\reports --source eap --target eapCopy to Clipboard Copied! Toggle word wrap Toggle overflow You should see this result.
***SUCCESS*** Windup report created: /home/your-username/migration-rules/reports/index.html Access it at this URL: file:///home/your-username/migration-rules/reports/index.html***SUCCESS*** Windup report created: /home/your-username/migration-rules/reports/index.html Access it at this URL: file:///home/your-username/migration-rules/reports/index.htmlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Review the Reports
Access the report at ~/migration-rules/reports/index.html to be sure it provides the expected results.
The Overview page displays the Name of the input folder, "data", along with the Effort of "1 Story Points".
Application List
Click on the "data" link under the
Namecolumn to see the Report Index page and review the migration summary.ReportIndex
Click on the Application Details link to view the application report. This report displays a link for the name of the file, "jboss-web.xml", along with warnings and 1 Story Points.
Application Details Report
Drill down into Source Report file detail by clicking on the jboss-web.xml file link. This report provides information about the file and summarizes the story points. It also highlights the
<class-loading>line in thejboss-web.xmlfile, provides the message "The class-loading element is no longer valid in the jboss-web.xml file.", and provides a link to the Create or Modify Files That Control Class Loading in JBoss EAP 6 topic in the JBoss EAP 6 Migration Guide. Click on the link to be sure the link is valid.
- Return to the Overview Page and click on the "All Rule" link to view the Rule Provider Executions report. Find the 'JBoss5-web-class-loading' rule in the report and verify that the Status shows "Condition met" and the Result shows "success".
Chapter 3. Create and Test XML Rules
3.1. XML Rule Construction
This section describes the basic construction of XML rules. All XML rules are defined as elements within rulesets.
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 a Windup 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>true|false</overrideRules>: Indicates that rules in this ruleset override rules with the same ID from the core ruleset distributed with Windup. 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>: Contains the 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 condition or conditions to match on. For a detailed description of the elements allowed in a
<when>, see XML Rule - When Condition Syntax. -
<perform>: The action to be performed when the rule condition is matched. For a detailed description of the elements allowed in a
<perform>, see XML Rule - Perform Action Syntax. -
<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>: Matches on a string pattern.
-
<when>: The condition or conditions to match on. For a detailed description of the elements allowed in a
- <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
Windup provides some predefined rules for common migration requirements, for example, mapping files extensions to a particular file type. The following is an example of the predefined "XmlFileMappings" rule.
3.2. Create a Basic XML Rule
You can create a Windup rule using Java, XML, or Groovy. This topic describes how to create a rule using XML.
3.2.1. Prerequisites
- You should have already installed Windup. Installation instruction are provided in the Windup User Guide.
Before you begin, you may also want to be familiar with the following documentation:
- Windup rules are based on the ocpsoft rewrite project. You can find more information about ocpsoft rewrite here: http://ocpsoft.org/rewrite/
- The JavaDoc for the Windup API is located here: http://windup.github.io/windup/docs/latest/javadoc/
- The XML rule schema is located here: http://windup.jboss.org/schema/windup-jboss-ruleset.xsd
3.2.2. File Naming Convention for XML Rules
You must name the file containing an XML rule with the .windup.xml extension. Windup identifies files with this extension as XML-base rules, so be sure to use this naming convention, otherwise the rule will not be evaluated!
3.2.3. Basic XML Rule Template
XML rules consist of conditions and actions and follow the familiar "if/then/else" construct:
when(condition)
perform(action)
otherwise(action)
when(condition)
perform(action)
otherwise(action)The following is the basic syntax for XML rules.
3.2.4. Create 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. For more information about ruleset metadata, see XML Rule Construction.
Example:
3.2.5. Create the Rule
Individual rules are contained within a <rules> element and consist of one or more conditions and actions.
3.2.5.1. Create the Rule When Condition
The XML rule <when> element tests for a condition. The following is a list of valid <when> conditions.
| Element | Description |
|---|---|
| <true> | Always match. |
| <or> <and> <not> | These are the standard logical operators. |
| <javaclass> | Test for a match in a Java class. |
| <javaclass-ignore> | Exclude javaclass which you would like to ignore in processing discovery. |
| <xmlfile> | Test for a match in an XML file. |
| <project> | Test for project characteristics, such as dependencies. |
| <filecontent> | Find strings or text within files, for example, properties files. |
| <file-mapping> | Define file names to internal stored File model. |
| <package-mapping> | Define package names to organization or libraries. |
The specific syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file, a project, or file content and is described in more detail here: XML Rule - When Condition Syntax
3.2.5.2. Create the Rule 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 lineitem reporting. The following is a list of valid <peform> actions.
| Element | Description |
|---|---|
| <classification> | This operation adds metadata that is intended to apply to the entire file. For example, if the Java Class is a JMS Message Listener, you might want to add a Classification with the title "JMS Message Listener". Information that would apply to the entire file would go here. Also, if an effort level is set, that information would apply to the entire file. |
| <link> | Provides an HTML link to additional information or documentation that provides more information about the migration task. |
| <hint> | This operation adds metadata to a line within the file. For example, if the rule were set to apply to all instances of "javax.jms.TextMessage.setText(java.lang.String)" this would highlight every instance of that method call. This is frequently used when there is detailed information to attach that applies at the line level. Each time this operation is fired, the effort level will be added. In our example, if the effort level were 3 and there were 4 instances of "javax.jms.TextMessage.setText(java.lang.String)", then this would add 9 total story points. Whether or not to apply effort at this level or in a classification depends upon the amount of effort required during the migration. |
| <xslt> | Specify how to transform an XML file. |
| <lineitem> | This provides a high level message that will appear in the application overview page. |
| <iteration> | Specify to iterate over an implicit or explicit variable defined within the rule. |
The syntax is described in more detail here: XML Rule - Perform Action Syntax.
3.3. XML Rule - When Condition 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.
3.3.1. Syntax
3.3.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.
3.3.1.2. Construct a Element
3.3.1.2.1. Element Attributes
| Attribute Name | Type | Description |
|---|---|---|
| references | CLASS_NAME | The package or class name to match on. Wildcard characters can be used. Tip
For performance reasons, you should not start the reference with wildcard characters. For example, use Example: references="weblogic.apache.xml.{*}"
|
| matchesSource | STRING | An exact regex to match. This is useful to distinguish hard-coded strings. Example: 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 Example: as="MyEjbRule" |
| from | VARIABLE_NAME |
Begin the search query with the filtered result from a previous search identified by its Example: from="MyEjbRule" |
| in | PATH_FILTER | Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. (Optional) Example: in="{*}File1"
|
3.3.1.2.2. 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. Example: <location>IMPORT</location> |
| <annotation-literal> | Match on literal values inside of annotations.
The below example would match on <javaclass references="org.package.MyAnnotation">
<location>ANNOTATION</location>
<annotation-literal name="myvalue" pattern="test"/>
</javaclass>
Note that in this case, the |
| <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 |
| <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
Note that in this case, the |
3.3.2. Syntax
3.3.2.1. Summary
Use the <xmlfile> element to find information in XML files. For a better understanding of the <xmlfile> condition, see the XmlFile JavaDoc.
The following is an example of a rule that tests for an XML file.
3.3.2.2. Construct an Element
3.3.2.2.1. Element Attributes
| Attribute Name | Type | Description |
|---|---|---|
| matches | XPATH | Match on an XML file condition. (Optional) Example: matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']" |
| xpathResultMatch | XPATH_RESULT_STRING | Return results that match the given regex. (Optional) Example: <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 Example: as="MyEjbRule" |
| in | PATH_FILTER | Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used. (Optional) Example: in="{*}File1"
|
| from | VARIABLE_NAME |
Begin the search query with the filtered result from a previous search identified by its Example: from="MyEjbRule" |
| public-id | PUBLIC_ID | The DTD public-id regex. (Optional) Example: public-id="public" |
3.3.2.2.2. Element: matches - Advanced usage: Custom Windup XPath 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 |
|---|---|
|
| Match a XPath expression against a string, possibly containing Windup parameterization placeholders. Example: matches="windup:matches(//foo/@class, '{javaclassname}'"
This will match all |
3.3.2.2.3. Child Elements
| Child Element | Description |
|---|---|
| <namespace> |
The namespace referenced in XML files. This element contains 2 optional attributes: The Example: <namespace prefix="abc" uri="http://maven.apache.org/POM/4.0.0"/> |
3.3.3. Syntax
3.3.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.
3.3.3.2. Construct a Element
3.3.3.2.1. 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.3.2.2. Child Elements
| Child Element | Description |
|---|---|
| <artifact> |
Subcondition used within |
3.3.3.2.3. Element Attributes
| Attribute Name | Type | Description |
|---|---|---|
| groupId | PROJECT_GROUP_ID |
Match on the project |
| artifactId | PROJECT_ARTIFACT_ID |
Match on the project |
| fromVersion | FROM_VERSION |
Specify the lower version bound of the artifact. For example |
| toVersion | TO_VERSION |
Specify the upper version bound of the artifact. For example |
3.3.4. Syntax
3.3.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.4.2. Construct a Element
3.3.4.2.1. Element Attributes
| Attribute Name | Type | Description |
|---|---|---|
| pattern | String | Match the file contents against the provided parameterized string. |
| 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 Example: as="MyEjbRule" |
| from | VARIABLE_NAME |
Begin the search query with the filtered result from a previous search identified by its Example: from="MyEjbRule" |
3.3.5. Syntax
3.3.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.5.2. Construct a Element
3.3.5.2.1. Element Attributes
| Attribute Name | Type | Description |
|---|---|---|
| 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 Example: as="MyEjbRule" |
| from | VARIABLE_NAME |
Begin the search query with the filtered result from a previous search identified by its Example: from="MyEjbRule" |
3.4. XML Rule - Perform Action 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.
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 rule perform actions.
3.4.1. Classification Syntax
3.4.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.
Example:
3.4.1.2. classification Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| title | STRING | Title this resource using the specified string. Example: title="JBoss Seam Components" |
| effort | BYTE | The level of effort assigned to this resource. (Optional) Example: effort="2" |
| severity | STRING | Whether this classification is "mandatory" or "optional". (Optional) Example: severity="mandatory" |
| of | VARIABLE_NAME | Create a new classification for the given reference. (Optional) Example: of="MySeamRule" |
3.4.1.3. classification Element: Child Elements
| Child Element | Description |
|---|---|
| <link> | Provides a link URI and text title for additional information. Example: <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. Example: <tag>Seam3</tag> |
| <description> | Description of this resource Example: <description>JBoss Seam components must be replaced</description> |
3.4.2. Link Syntax
3.4.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.
Example:
3.4.2.2. link Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| href | URI | The URI for the referenced link. Example: href="https://access.redhat.com/articles/1249423" |
| title | STRING | A title for the link. Example: title="Migrate WebLogic Proprietary Servlet Annotations" |
3.4.3. Hint Syntax
3.4.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.
Example:
3.4.3.2. hint Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| title | STRING | Title this hint using the specified string. Title is a required attribute. Example: title="JBoss Seam Component Hint" |
| severity | STRING | Whether this hint is "mandatory" or "optional". (Optional) Example: severity="mandatory" |
| in | VARIABLE_NAME | Create a new Hint in the FileLocationModel resolved by the given variable. (Optional) Example: in="Foo" |
| effort | BYTE | The level of effort assigned to this resource. (Optional) Example: effort="2" |
3.4.3.3. hint Element: Child Elements
| Child Element | Description |
|---|---|
| <message> | A message describing the migration hint. Example: <message>EJB 2.0 is deprecated</message> |
| <link> | Identify or classify links to informational content. See the section on Link Syntax for details. Example: <link href="http://docs.oracle.com/javaee/6/api/" title="Java Platform, Enterprise Edition 6 API Specification" /> |
| <tag> |
Define a custom tag for this Example: <tag>Needs review</tag> |
3.4.4. XSLT Syntax
3.4.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.
Example:
3.4.4.2. xslt Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| of | STRING | Create a new transformation for the given reference. (Optional) Example: of="testVariable_instance" |
| title | STRING | Sets the title for this XSLTTransformation in the report. Example: title="XSLT Transformed Output" |
| extension | STRING | Sets the extension for this XSLTTransformation. Example: extension="-result.html" |
| template | STRING | Sets the XSL template. Example: template="simpleXSLT.xsl" |
| effort | BYTE | The level of effort required for the transformation. (Optional) |
3.4.4.3. xslt Element: Child Elements
| Child Element | Description |
|---|---|
| <xslt-parameter> | Specify XSLTTransformation parameters as property value pairs Example: <xslt-parameter property="title" value="EJB Transformation"/> |
3.4.5. Lineitem Syntax
3.4.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.
Example:
3.4.5.2. lineitem Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| message | STRING | A lineitem message Example: message="Proprietary code found." |
3.4.6. Iteration Syntax
3.4.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.
Example:
3.4.6.2. iteration Element: Attributes
| Attribute Name | Type | Description |
|---|---|---|
| over | VARIABLE_NAME | Iterate over the condition identified by this VARIABLE_NAME. Example: over="jboss-app" |
3.4.6.3. iteration Element: Child Elements
| Child Element | Description |
|---|---|
| <iteration> |
Child elements include a |
3.5. Test an XML Rule in Windup
3.5.1. Add the Rule to Windup
A Windup rule is installed simply by copying the rule to the appropriate Windup folder. Windup scans for rules, which are files that end with either *.windup.groovy or .windup.xml, in the following locations:
-
Copy the rule to a directory specified by the
--userRulesDirectoryargument on the Windup command line. - Copy the rule to the WINDUP_HOME/rules/ directory. WINDUP_HOME is the directory where you install and run the Windup executable.
Copy the rule to the
${user.home}/.windup/rules/directory. This directory is created by Windup the first time it is executed and contains rules, add-ons, and the Windup log.For Linux or Mac: ~/.windup/rules/ For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" -or- "\Users\USER_NAME\.windup\rules\"
For Linux or Mac: ~/.windup/rules/ For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" -or- "\Users\USER_NAME\.windup\rules\"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.5.2. Test the XML Rule
Test the XML rule against your application file by running Windup in a terminal.
The command uses this syntax:
WINDUP_HOME/bin/windup [--sourceMode] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
WINDUP_HOME/bin/windup [--sourceMode] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_NCopy to Clipboard Copied! Toggle word wrap Toggle overflow You should see the following result:
***SUCCESS*** Windup report created: OUTPUT_REPORT_DIRECTORY/index.html
***SUCCESS*** Windup report created: OUTPUT_REPORT_DIRECTORY/index.htmlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
3.5.3. Additional Resources
- More examples of how to run Windup are located in the Windup User Guide.
- Working examples of XML-based rules can be found on GitHub in the Windup source code GitHub repository and the Windup quickstarts GitHub repository or latest release ZIP download.
3.6. Overriding Rules
You can override core rules distributed with Windup or even custom-written rules. For example, you might want to change the matching conditions, effort, or hint text for a rule. This is done by making a custom copy of the original rule, marking it as a rule override, and making the necessary adjustments. You can also disable a rule in this same manner.
3.6.1. Override a Rule
You can override a rule using the following steps.
Copy the XML file that contains the rule you want to override to the custom rules directory.
Custom rules can be placed in either
WINDUP_HOME/rules,${user.home}/.windup/rules/, or the directory specified by the--userRulesDirectorycommand-line argument.Edit the XML file and only keep the
<rule>elements for the rules that you want to override.Note that the rules from the original ruleset that are not overridden in the new ruleset will be executed as normal.
- Ensure that you keep the same rule and ruleset IDs. When you copy the original rule XML, this ensures that the IDs match.
-
Add the
<overrideRules>true</overrideRules>entry to the ruleset metadata. Make the adjustments to the rule as necessary.
You can change anything in the rule definition. This rule will override the entire original rule.
The below is an example of an overridden rule. Notice the <overrideRules>true</overrideRules> element in the ruleset metadata. The rule and ruleset IDs match the original. This rule override simply changed the effort needed from a 1 to a 3.
When you run Windup, this rule will now be used in place of the original rule with the matching rule ID. You can verify that the new rule was used by viewing the contents of the Rule Provider Executions Report.
3.6.2. Disable a Rule
To disable a rule, follow the same steps as above to override a rule, except just provide an empty <rule> element.
Chapter 4. Additional Resources
4.1. Review the Existing Windup XML Rules
Windup XML-based rules are located on GitHub at the following location: https://github.com/windup/windup-rulesets/tree/master/rules.
Instructions to fork and clone the Windup rulesets repository to your local machine are provided on the Wiki.
Rules are grouped by target platform and function. When you create a new rule, it is helpful to find a rule that is similar to the one you need and use it as a starting template.
New rules are continually added, so it is a good idea to check back frequently to review the updates.
4.2. Important Links
- Windup wiki: https://github.com/windup/windup/wiki
- Windup Javadoc: http://windup.github.io/windup/docs/latest/javadoc
- Windup forums: https://developer.jboss.org/en/windup
Windup JIRA issue trackers
- Core Windup: https://issues.jboss.org/browse/WINDUP
- Windup Rules: https://issues.jboss.org/browse/WINDUPRULE
Windup Mailing Lists
- Windup Users: windup-users@lists.jboss.org
- Windup Developers: windup-dev@lists.jboss.org
- Windup Commits: windup-commits@lists.jboss.org
- Windup on Twitter: @JBossWindup
-
Windup IRC channel: Server FreeNode (
irc.freenode.net), channel#windup(transcripts)
Chapter 5. Appendix
5.1. Rule Story Points
5.1.1. What are Story Points?
Story Points are an abstract metric commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change.
Windup uses story points to express the level of effort needed to migrate particular application constructs, and in a sum, the application as a whole. It does not necessarily translate to man-hours, but the value should be consistent across tasks.
5.1.2. How Story Points are Estimated in Rules
Estimating the level of effort for the story points for a rule can be tricky. The following are the general guidelines Windup uses when estimating the level of effort required for a rule.
| Level of Effort | Story Points | Description |
|---|---|---|
| Information | 0 | An informational warning with very low or no priority for migration. |
| Trivial | 1 | The migration is a trivial change or a simple library swap with no or minimal API changes. |
| Complex | 3 | The changes required for the migration task are complex, but have a documented solution. |
| Redesign | 5 | The migration task requires a redesign or a complete library change, with significant API changes. |
| Rearchitecture | 7 | The migration requires a complete rearchitecture of the component or subsystem. |
| Unknown | 13 | The migration solution is not known and may need a complete rewrite. |
5.1.3. Task Severity
In addition to the level of effort, migration tasks can be assigned a severity that indicates whether the task must be completed or can be postponed.
- Mandatory
- The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform.
- Optional
- If the migration task is not completed, the application should work, but the results may not be the optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after migration is completed. An example of this would be the upgrade of EJB 2.x code to EJB 3.
5.2. About the WINDUP_HOME Variable
This documentation uses the WINDUP_HOME replaceable value to denote the path to the Windup distribution. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation.
- If you download and install the latest distribution of Windup from the JBoss Nexus repository, WINDUP_HOME refers to the windup-distribution-2.5.0-Final folder extracted from the downloaded ZIP file.
- If you build Windup from GitHub source, WINDUP_HOME refers to the windup-distribution-2.5.0-Final folder extracted from the windup-distribution/target/windup-distribution-2.5.0-Final.zip file.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}