Windup Documentation

View on GitHub

Creating your first YAML rule

This section guides you through the process of creating and testing your first {ProductShortName} YAML-based rule. This assumes that you have already installed {ProductShortName}. See Installing and running the CLI in the CLI Guide for installation instructions.

In this example, you will create a rule to discover instances where an application defines a jboss-web.xml file containing a <class-loading> element and to provide a link to the documentation that describes how to migrate the code.

Creating a YAML file for the rule

  • Create a YAML file for your first rule.

$ mkdir /home/<USER>/rule.yaml

Creating data to test the rule

  1. Create jboss-web.xml and pom.xml files in a directory:

    mkdir /home/<USER>/data/
touch /home/<USER>/data/jboss-web.xml
touch /home/<USER>/data/pom.xml

  2. In the jboss-web.xml file you created, paste the following content:

    <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 4.2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_2.dtd">
<jboss-web>
    <class-loading java2ClassLoadingCompliance="false">
        <loader-repository>
            seam.jboss.org:loader=@projectName@
            <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
        </loader-repository>
    </class-loading>
</jboss-web>

  3. In the pom.xml file you created, paste the following content:

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

  <groupId>test</groupId>
  <artifactId>test</artifactId>
  <version>1.1.0-SNAPSHOT</version>

  <properties>
	<maven.compiler.source>1.7</maven.compiler.source>
	<maven.compiler.target>1.7</maven.compiler.target>
  </properties>

  <dependencies>
  </dependencies>
</project>

Creating the rule

MTA YAML-based rules use the following rule pattern:

when(condition)
  perform(action)
Procedure

  • In the rule.yaml file you created, paste the following contents:

    - ruleID: <UNIQUE_RULE_ID> (1)
  description: <DESCRIPTION> (2)
  when:
    <CONDITION(S)> (3)
  message: <MESSAGE> (4)
  labels: <LABELS> (5)
  effort: <EFFORT> (6)
  links:
  - <LINKS> (7)

    1. Unique ID for your rule. For example, jboss5-web-class-loading.

    2. Text description of the rule.

    3. Complete the when block specifying one or more conditions:

      1. Use the builtin provider’s XML capability because this rule checks for a match in an XML file.

      2. To match on the class-loading element that is a child of jboss-web, use the XPath expression jboss-web/web-loading as an XML query. In this case, you need just one condition:

        when:
  builtin.xml:
    xpath: jboss-web/class-loading

    4. Helpful message explaining the migration issue. The message is generated in the report when the rule matches. For example:

      message: The class-loading element is no longer valid in the jboss-web.xml file.

    5. List of string labels for the rule.

    6. Number of expected story points to fix this issue.

    7. One or more hyperlinks pointing to documentation around the migration issues that you find.

      links:
- url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6
  title: Create or Modify Files That Control Class Loading in JBoss EAP 6

      The rule is now complete and looks similar to the following:

      - ruleID: jboss5-web-class-loading
  description: Find class loading element in JBoss XML file.
  when:
    builtin.xml:
      xpath: jboss-web/class-loading
  message: The class-loading element is no longer valid in the jboss-web.xml file.
  effort: 3
  links:
  - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6
    title: Create or Modify Files That Control Class Loading in JBoss EAP 6

Installing the rule

Procedure

  • Point the CLI to the rule file you created :

    –rules /home/<USER>/rules.yaml

Testing the rule

Procedure

  • To test the rule, point the input to the test data you created and pass the rule using the rules option in MTA CLI:

mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rules.yaml

Reviewing the report

Review the report to be sure that it provides the expected results.

Procedure

  1. Once the analysis is complete, the command outputs the path to the HTML report:

    INFO[0066] Static report created. Access it at this URL:  URL="file:/home/<USER>/output/static-report/index.html"

    Open /home/<USER_NAME>/output/static-report/index.html in a web browser.

  2. Navigate to the Issues tab in the left menu.

  3. Verify that the rule is executed:

    1. In the Issues table, type JBoss XML in the search bar.

    2. Verify that the issue with the title Find class loading element in JBoss XML file is present in the table.

  4. Click the jboss-web.xml link to open the affected file.