Windup

Getting started with JBoss Windup

Windup is a a rule-based migration tool which can be used to simply the migration from other major application servers (Weblogic and Websphere) to JBoss EAP/WildFly and to upgrade existing server installations to newer releases. You can run Windup either against the source code of the application or the compiled archive.

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. In the end, HTML reports will be produced that will assist you in the assessment of your migration plan.

Getting started with Windup:

Start by downloading Windup from http://windup.jboss.org/download.html . Next navigate to the _WINDUP_HOME/bin_ directory.

Execute the windup script and specify the appropriate arguments. For example, if you were supposed to check the demo application provided by the windup team, then you would execute the following command:

$ ./windup --input /path/jee-example-app-1.0.0.ear --output /path/report --target eap

TIP: Windup is able to generate its reports out of a packaged application. You can, however, also use the *--sourceMode* argument to run Windup against application source code.

You will see the list of artifacts that have been migrated from the following picture:

jboss windup tutorial

Click on it and you will be redirected to the *Report Index* which provides summary information about findings from the migration analysis, as well as links to additional reports with detailed information.

jboss windup tutorial

This is the list of Report sections which will be available (depending on the content of your application):

Migration Issues Provides a concise summary of all issues that require attention.
Application Details: Provides a detailed overview of all resources found within the application that may need attention during the migration.
Unparsable Shows all files that Windup could not parse in the expected format. For instance, a file with a `.xml` or `.wsdl` suffix is assumed to be an XML file. If the XML parser fails, the issue is reported here and also where the individual file is listed.
Dependencies Displays all Java-packaged dependencies found within the application.
Remote Services Displays all remote services references that were found within the application.
EJBs Contains a list of EJBs found within the application.
JBPM Contains all of the JBPM-related resources that were discovered during analysis.
JPA Contains details on all JPA-related resources that were found in the application.
Hibernate Contains details on all Hibernate-related resources that were found in the application..Server Resources: Displays all server resources (for example, JNDI resources) in the input application.
Spring Beans Contains a list of Spring beans found during the analysis.
Hard-coded IP Addresses: Provides a list of all hard-coded IP addresses that were found in the application.
Ignored Files: Lists the files found in the application that, based on certain rules and Windup configuration, were not processed. See the `--userIgnorePath` option for more information.
About Describes the current version of Windup and provides helpful links for further assistance.

For example, as the demo application is a Weblogic based application, you will see a large list of migration steps which need to be analyzed with concrete suggestions and an evaluation of the complexity of the migration:

jboss windup tutorial

Migrating applications to newer versions of the application server

Windup is not worth using just for migration from other application servers but you can use it as well to upgrade to newer versions of JBoss/WildFly. For example, if you were to migrate an application from JBoss EAP 6 to JBoss EAP 7, then you can use the target [Server]:[Release] option.

As a proof of concept, when running Windup with the following arguments, we will be able to generate a report for our application, named _javaee6-ejb-server-basic.jar_ which has been written for a Java EE 6 application server such as JBoss EAP 6. Passing as argument the new server distribution (eap:7) we will be able to generate a report for the upgrade:

$ ./windup --input javaee6-ejb-server-basic.jar --output /home/francesco/jboss/windup-distribution-2.7.0.Final/bin/report --target eap:7 

As you can see from the migration report, in this case, most of the effort in this application will be adapting the Clustering policies, by removing the *@Clustered* annotation which has been deprecated in EAP 7:

jboss windup tutorial

Restricting the migration to a set of packages

Depending on the size of the application and the hardware the migration process, Windup could potentially require a considerable amount of time. For this reason it is recommended to specify one or more packages to evaluate. For example, if you want to evaluate just the following set of packages, include the *--packages* option which will cut reduce the amount of time needed to generate your reports:
$ ./windup --input /path/to/javaee6-ejb-server-basic.jar  --output /path/to/output --target eap --packages com.acme org.apache

Creating Maven projects out of a compiled artifact

Windup is not just about migration but it is a great source of hacks. For example, you can create a full Maven project from a compiled project. This is a great option if you need a project starting point with all the necessary dependencies and APIs for your application. In order to do that, simply add the *--mavenize* flag to the windup shell, as in the following example:

$ ./windup --input javaee6-ejb-server-basic.jar --output /home/francesco/jboss/windup-distribution-2.7.0.Final/bin/report --target eap:7 --mavenize
$ tree mavenized/
mavenized/
└── ejb-3-1-example-application
    ├── ejb-3-1-example-application-bom
    │   └── pom.xml
    ├── javaee6-ejb-server-basic-jar
    │   └── pom.xml
    └── pom.xml

As you can see, the following resources have been automatically created:

  • A root POM file. This is the _pom.xml_ file at the top-level directory.
  • .A Bill of Materials (BOM) file. The purpose of this BOM is to have the versions of third-party dependencies used by the project defined in one place.
  • One or more application POM files. Each module has its POM file in a directory named after the archive.

This tutorial is an extract from JBoss.org Hacks book available here: http://www.itbuzzpress.com/ebooks/jboss-org-hacks.html

Follow us on Twitter