Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 2. Getting Started

You can get starting creating custom RHAMT rules by walking through creating a rule or by reviewing the quickstarts.

2.1. Create Your First XML Rule
Copia collegamento

This section guides you through the process of creating and testing your first RHAMT XML-based rule. This assumes that you have already installed RHAMT. See the CLI Guide for installation instructions.

In this example, you will 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 /home/USER_NAME/migration-rules/rules
$ mkdir -p /home/USER_NAME/migration-rules/data
Copy to Clipboard Toggle word wrap

This directory structure will also be used to hold the generated RHAMT reports.

Create Data to Test the Rule

  1. Create a jboss-web.xml file in the /home/USER_NAME/migration-rules/data/ subdirectory.

  2. Copy in 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>
    Copy to Clipboard Toggle word wrap

Create the Rule

RHAMT XML-based rules use the following rule pattern: 

when(condition)
  perform(action)
otherwise(action)
Copy to Clipboard Toggle word wrap

Ruleset and rule XML elements are covered in more detail in the XML Rule Structure section. See Create a Basic XML Rule for additional details about creating XML rules with example syntax.

  1. Create an XML file in the /home/USER_NAME/migration-rules/rules/ subdirectory named JBoss5-web-class-loading.windup.xml. Copy in the following content. 

    <?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>
        <description>
            <!-- Ruleset Description -->
        </description>
        <dependencies>
            <!-- Ruleset Dependencies -->
        </dependencies>
        <sourceTechnology id="SOURCE_ID" versionRange="SOURCE_VERSION_RANGE"/>
        <targetTechnology id="TARGET_ID" versionRange="TARGET_VERSION_RANGE"/>
        <tag>Reviewed-2015-05-01</tag>
    </metadata>
    <rules>
        <rule id="UNIQUE_RULE_ID">
            <when>
                <!-- Test for a condition here -->
            </when>
            <perform>
                <!-- Perform an action -->
            </perform>
        </rule>
     </rules>
</ruleset>
    Copy to Clipboard Toggle word wrap
    Note

    RHAMT identifies files with the .windup.xml or .rhamt.xml extension as XML-based rules, so be sure to use this naming convention, otherwise the rule will not be evaluated!

  2. Add the unique identifier for the ruleset and rule.

    • Replace the UNIQUE_RULESET_ID with an appropriate ruleset ID, for example, JBoss5-web-class-loading.
    • Replace the UNIQUE_RULE_ID with an appropriate rule ID, for example, JBoss5-web-class-loading_001.

  3. Add the following ruleset add-on dependencies. 

    <dependencies>
  <addon id="org.jboss.windup.rules,windup-rules-javaee,3.0.0.Final"/>
  <addon id="org.jboss.windup.rules,windup-rules-java,3.0.0.Final"/>
</dependencies>
    Copy to Clipboard Toggle word wrap

  4. Add the source and target technologies.

    • Replace SOURCE_ID with eap.
    • Replace TARGET_ID with eap.

  5. Set the source and target technology versions.

    • Replace SOURCE_VERSION_RANGE with (4,5).
    • Replace TARGET_VERSION_RANGE with [6,).

    See the Apache Maven version range specification for help with this syntax.

  6. Complete the when condition.

    Because this rule tests for a match in an XML file, xmlfile is used to evaluate the files.

    To match on the class-loading element that is a child of jboss-web, use the xpath expression jboss-web/class-loading. 

    <when>
    <xmlfile matches="jboss-web/class-loading" />
</when>
    Copy to Clipboard Toggle word wrap

  7. Complete the perform action for this rule.

    • Add a classification with a descriptive title and a level of effort of 1.

    • Provide a hint with an informative message and a link to documentation that describes the migration details. 

      <perform>
    <iteration>
        <classification title="JBoss Web Application Descriptor" effort="1"/>
        <hint title="JBoss Web XML class-loading element is no longer valid">
          <message>
            The class-loading element is no longer valid in the jboss-web.xml file.
          </message>
          <link href="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"/>
        </hint>
    </iteration>
</perform>
      Copy to Clipboard Toggle word wrap

The rule is now complete and should look like the following example. 

<?xml version="1.0"?>
<ruleset id="JBoss5-web-class-loading"
    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 ruleset looks for the class-loading element in a jboss-web.xml file, which is no longer valid in JBoss EAP 6
        </description>
         <dependencies>
            <addon id="org.jboss.windup.rules,windup-rules-javaee,3.0.0.Final"/>
            <addon id="org.jboss.windup.rules,windup-rules-java,3.0.0.Final"/>
        </dependencies>
        <sourceTechnology id="eap" versionRange="(4,5)"/>
        <targetTechnology id="eap" versionRange="[6,)"/>
    </metadata>
    <rules>
        <rule id="JBoss5-web-class-loading_001">
            <when>
                <xmlfile matches="jboss-web/class-loading" />
            </when>
            <perform>
                <iteration>
                    <classification title="JBoss Web Application Descriptor" effort="1"/>
                    <hint title="JBoss Web XML class-loading element is no longer valid">
                      <message>
                        The class-loading element is no longer valid in the jboss-web.xml file.
                      </message>
                      <link href="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"/>
                    </hint>
                </iteration>
            </perform>
        </rule>
     </rules>
</ruleset>
Copy to Clipboard Toggle word wrap

Install the Rule

An RHAMT rule is installed by placing the rule into the appropriate directory. See Add the Rule to RHAMT for the possible locations to place a custom rule.

Copy the JBoss5-web-class-loading.windup.xml file to the RHAMT_HOME/rules/ directory. 

$ cp /home/USER_NAME/migration-rules/rules/JBoss5-web-class-loading.windup.xml RHAMT_HOME/rules/
Copy to Clipboard Toggle word wrap

Test the Rule

Open a terminal and execute the following command, passing the test file as an input argument and a directory for the output report. 

$ RHAMT_HOME/bin/rhamt-cli --sourceMode --input /home/USER_NAME/migration-rules/data --output /home/USER_NAME/migration-rules/reports --target eap:6
Copy to Clipboard Toggle word wrap

You should see the following result. 

Report created: /home/USER_NAME/migration-rules/reports/index.html
              Access it at this URL: file:///home/USER_NAME/migration-rules/reports/index.html
Copy to Clipboard Toggle word wrap

Review the Reports

Review the report to be sure that it provides the expected results. For a more detailed walkthrough of RHAMT reports, see the Review the Reports section of the RHAMT CLI Guide.

  1. Open /home/USER_NAME/migration-rules/reports/index.html in a web browser.

  2. Verify that the rule executed.

    1. From the main landing page, click the Rule providers execution overview link to open the Rule Providers Execution Overview.

    2. Find the JBoss5-web-class-loading_001 rule and verify that its Status? is Condition met and its Result? is success.

      Figure 2.1. Test Rule Execution

      Test Rule Execution
      View larger image
      Test Rule Execution

  3. Verify that the rule matched on the test data.

    1. From the main landing page, click on the name of the application or input folder, which is data in this example.
    2. Click on the Application Details report link.

    3. Click on the jboss-web.xml link to view the Source Report.

      You can see that the <class-loading> line is highlighted, and the hint from the custom rule is shown inline.

      Figure 2.2. Rule Match

      Rule Match
      View larger image
      Rule Match

      The top of the file lists the classifications for matching rules. You can use the link icon to view the details for that rule. Notice that in this example, the jboss-web.xml file matched on another rule (JBoss web application descriptor (jboss-web.xml)) that produced 1 story point. This, combined with the 1 story point from our custom rule, brings the total story points for this file to 2.

2.2. Review the Red Hat Application Migration Toolkit Quickstarts
Copia collegamento

The Red Hat Application Migration Toolkit quickstarts provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules.

You can download a ZIP file of the latest released version of the quickstarts. Or, if you prefer to work with the source code, you can fork and clone the windup-quickstarts project repository.

Each quickstart has a README.adoc file that contains instructions for that quickstart.

Download the Latest Quickstart ZIP

  1. Open a browser and navigate to https://github.com/windup/windup-quickstarts/releases.
  2. Click on the most recent release to download the ZIP file to your local file system.

Fork and Clone the Quickstart GitHub Project

You must have the git client installed on your machine.

  1. Click the Fork link on the Red Hat Application Migration Toolkit quickstart GitHub page to create the project in your own Git. The forked GitHub repository URL created by the fork should look like this: https://github.com/YOUR_USER_NAME/windup-quickstarts.git.

  2. Clone your Red Hat Application Migration Toolkit quickstart repository to your local file system: 

    $ git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
    Copy to Clipboard Toggle word wrap

  3. This creates and populates a windup-quickstarts directory on your local file system. Navigate to the newly created directory, for example 

    $ cd windup-quickstarts/
    Copy to Clipboard Toggle word wrap

  4. If you want to be able to retrieve the latest code updates, add the remote upstream repository so you can fetch any changes to the original forked repository. 

    $ git remote add upstream https://github.com/windup/windup-quickstarts.git
    Copy to Clipboard Toggle word wrap

  5. Get the latest files from the upstream repository. 

    $ git fetch upstream
    Copy to Clipboard Toggle word wrap
Torna in cima
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2025 Red Hat