Windup User Guide

Overview

Windup is an extensible and customizable rule-based tool that helps simplify migration of Java applications.

Windup examines application artifacts, including project source directories and applications archives, then produces an HTML report that highlights areas needing changes. Windup can be used to migrate Java applications from previous versions of Red Hat JBoss Enterprise Application Platform or from other containers, such as Oracle® WebLogic Server or IBM® WebSphere® Application Server.

How Does Windup Simplify Migration?

Windup looks for common resources and highlights technologies and known trouble spots when migrating applications. The goal is to provide a high-level view into the technologies used by the application and provide a detailed report organizations can use to estimate, document, and migrate enterprise applications to Java EE and JBoss EAP.

Windup supports application migration from several platforms to Red Hat JBoss Enterprise Application Platform (JBoss EAP). See the below table for which JBoss EAP version is currently supported by Windup for direct migration from your source platform.

You will specify the source and target technologies by passing the --source and --target arguments to the Windup command.

$ WINDUP_HOME/bin/windup --source weblogic --target eap:6 --input /path/to/application.war

$ WINDUP_HOME/bin/windup --source eap:6 --target eap:7 --input /path/to/application.war

See Execute Windup for more information on running Windup.

Windup is a rule-based migration tool that analyzes the APIs, technologies, and architectures used by the applications you plan to migrate. In fact, the Windup tool executes its own core set of rules through all phases of the migration process. It uses rules to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports.

Windup builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

Windup rules use the following rule pattern:

when(condition)
  perform(action)
otherwise(action)

Windup provides a comprehensive set of standard migration rules out-of-the-box. Because applications may contain custom libraries or components, Windup allows you to write your own rules to identify use of components or software that may not be covered by the existing ruleset. If you plan to write your own custom rules, see the Windup Rules Development Guide for detailed instructions.

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.

When you execute Windup, the report is generated in the OUTPUT_REPORT_DIRECTORY that you specify using the --output argument in the command line. This output directory contains the following files and subdirectories:

OUTPUT_REPORT_DIRECTORY/
├── index.html          // Landing page for the report
├── EXPORT_FILE.csv     // Optional export of data in CSV format
├── archives/           // Archives extracted from the application
├── mavenized/          // Optional Maven project structure
├── reports/            // Generated HTML reports
├── stats/              // Performance statistics

Use a browser to open the index.html file located in the report output directory. See the Review the Reports section for information on navigating the Windup reports.

Access these reports from the report landing page by clicking the Archives shared by multiple applications link. Note that this link is only available if there are applicable shared archives.

Figure 3.7. Archives Shared by Multiple Applications

This allows you to view the detailed reports for all archives that are shared across multiple applications.

Access this report from the report landing page by clicking the All Rules link.

This report provides the list of rules that executed when running the Windup migration command against the application.

Figure 3.8. Rule Provider Report

Access this report from the report landing page by clicking the Windup FreeMarker methods link.

This report lists all the registered functions and directives that were used to build the report. It is useful if you plan to build your own custom report or for debugging purposes.

Figure 3.9. FreeMarker Functions and Directives

Access this feedback form from the report landing page by clicking the Send feedback link.

This form allows you to rate the product, talk about what you like and suggestions for improvements.

Figure 3.10. Send Feedback Form

To export the report into a CSV file, run Windup with --exportCSV argument. The CSV file will be created in the directory specified by the --output argument.

For more information or to resolve any issues, check the help for your spreadsheet software.

The CSV formatted output file contains the following data fields:

You can generate a Maven project structure for the provided application by passing in the --mavenize flag when executing Windup.

The following example runs Windup using the jee-example-app-1.0.0.ear test application.

$ WINDUP_HOME/bin/windup --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output --target eap:6 --packages com.acme org.apache --mavenize

This generates the Maven project structure in the /path/to/output/mavenized directory.

You can also use the --mavenizeGroupId option to specify the <groupId> to be used for the POM files. If unspecified, Windup will attempt to identify an appropriate <groupId> for the application, or will simply default to com.mycompany.mavenized.

The /path/to/output/mavenized/APPLICATION_NAME/ directory will contain the following items:

The example jee-example-app-1.0.0.ear application is an EAR archive that contains a WAR and several JARs. There is a separate directory created for each of these artifacts. Below is the Maven project structure created for this application.

/path/to/output/mavenized/jee-example-app/
    jee-example-app-bom/pom.xml
    jee-example-app-ear/pom.xml
    jee-example-services2-jar/pom.xml
    jee-example-services-jar/pom.xml
    jee-example-web-war/pom.xml
    pom.xml

Review each of the generated files and customize as appropriate for your project. To learn more about Maven POM files, see the Introduction to the POM section of the Apache Maven documentation.

Root POM File

The root POM file for the jee-example-app-1.0.0.ear application can be found at /path/to/output/mavenized/jee-example-app/pom.xml. This file identifies the directories for all of the project modules.

The following modules are listed in the root POM for the example jee-example-app-1.0.0.ear application.

<modules>
  <module>jee-example-app-bom</module>
  <module>jee-example-services2-jar</module>
  <module>jee-example-services-jar</module>
  <module>jee-example-web-war</module>
  <module>jee-example-app-ear</module>
</modules>

The root POM is also configured to use the Red Hat JBoss Enterprise Application Platform Maven repository to download project dependencies.

BOM File

The Bill of Materials (BOM) file is generated in the directory ending in -bom. For the example jee-example-app-1.0.0.ear application, the BOM file can be found at /path/to/output/mavenized/jee-example-app/jee-example-app-bom/pom.xml. The purpose of this BOM is to have the versions of third-party dependencies used by the project defined in one place. For more information on using a BOM, see the Introduction to the Dependency Mechanism section of the Apache Maven documentation.

The following dependencies are listed in the BOM for the example jee-example-app-1.0.0.ear application

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.6</version>
    </dependency>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.5</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Application POM Files

Each application module that can be mavenized has a separate directory containing its POM file. The directory name contains the name of the archive and ends in a -jar, -war, or -ear suffix, depending on the archive type.

Each application POM file lists that module’s dependencies, including:

For example, the POM file for the jee-example-app-1.0.0.ear EAR, /path/to/output/mavenized/jee-example-app/jee-example-app-ear/pom.xml, lists the following dependencies.

<dependencies>
  <dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.6</version>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-web-war</artifactId>
    <version>1.0</version>
    <type>war</type>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-services-jar</artifactId>
    <version>1.0</version>
  </dependency>
  <dependency>
    <groupId>org.jboss.seam</groupId>
    <artifactId>jee-example-services2-jar</artifactId>
    <version>1.0</version>
  </dependency>
</dependencies>

The Windup 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 play around with the source code, you can fork and clone the windup-quickstarts project repository.

To help us make Windup cover most application constructs and server configurations, including yours, you can help with any of the following items.

Any level of involvement is greatly appreciated!

You can review known issues for Windup here: Open Windup issues

Windup uses JIRA as its issue tracking system. If you encounter an issue executing Windup, please file a JIRA Issue.