From 609bd4010d4b536c7044aab0f94a5930c13fcd4a Mon Sep 17 00:00:00 2001 From: Sande Gilda Date: Fri, 12 Dec 2014 12:33:15 -0500 Subject: [PATCH] Add RulesDevelopmentGuide and update UserGuide --- About-the-WINDUP_HOME-Variable.adoc | 5 +- CONTRIBUTING.adoc | 23 - CONTRIBUTING.md | 59 + Dev-Debugging-and-Profiling.adoc | 63 + Dev-Troubleshoot-Windup-Issues.adoc | 21 + Dev-Windup-Architectural-Components.adoc | 4 +- Execute-Windup.adoc | 10 +- Features-of-Windup-2.0.adoc | 5 +- Get-Involved.adoc | 33 +- Glossary.adoc | 1 + Install-Windup.adoc | 5 +- Install-and-Configure-Maven.adoc | 84 + Known-Issues.adoc | 13 + ....adoc => Migration-Planning-Guide.asciidoc | 0 Report-Issues-with-Windup.adoc | 1 + Report-an-Issue-with-Windup.adoc | 34 - Review-the-Report.adoc | 7 +- Review-the-Windup-Quickstarts.adoc | 1 + Rules-Basic-Rule-Execution-Flow-Patterns.adoc | 121 + ...Create-a-Basic-Java-based-Rule-Add-on.adoc | 306 ++ Rules-Create-a-Basic-XML-Rule.adoc | 119 + Rules-Create-an-Advanced-Ruleset.adoc | 18 + Rules-Development-Guide.asciidoc | 65 + Rules-Java-based-Rule-Structure.adoc | 135 + Rules-Rule-Execution-Lifecycle.adoc | 100 + Rules-Rule-Story-Points.adoc | 21 + User-Guide.adoc | 13 - User-Guide.asciidoc | 32 + What-is-Windup.adoc | 1 + Windup-Processing-Overview.adoc | 10 +- Windup-Rules-Development-Guide.adoc | 87 + Windup-User-Guide.adoc | 12 +- WindupRulesDevelopmentGuide.html | 3420 +++++++++++++++++ WindupUserGuide.html | 427 +- 34 files changed, 5029 insertions(+), 227 deletions(-) delete mode 100644 CONTRIBUTING.adoc create mode 100644 CONTRIBUTING.md create mode 100644 Dev-Debugging-and-Profiling.adoc create mode 100644 Dev-Troubleshoot-Windup-Issues.adoc create mode 100644 Install-and-Configure-Maven.adoc create mode 100644 Known-Issues.adoc rename Migration-Planning-Guide.adoc => Migration-Planning-Guide.asciidoc (100%) delete mode 100644 Report-an-Issue-with-Windup.adoc create mode 100644 Rules-Basic-Rule-Execution-Flow-Patterns.adoc create mode 100644 Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc create mode 100644 Rules-Create-a-Basic-XML-Rule.adoc create mode 100644 Rules-Create-an-Advanced-Ruleset.adoc create mode 100644 Rules-Development-Guide.asciidoc create mode 100644 Rules-Java-based-Rule-Structure.adoc create mode 100644 Rules-Rule-Execution-Lifecycle.adoc create mode 100644 Rules-Rule-Story-Points.adoc delete mode 100644 User-Guide.adoc create mode 100644 User-Guide.asciidoc create mode 100644 Windup-Rules-Development-Guide.adoc create mode 100644 WindupRulesDevelopmentGuide.html diff --git a/About-the-WINDUP_HOME-Variable.adoc b/About-the-WINDUP_HOME-Variable.adoc index 617f13480a..cec0ebb543 100644 --- a/About-the-WINDUP_HOME-Variable.adoc +++ b/About-the-WINDUP_HOME-Variable.adoc @@ -1,6 +1,7 @@ +[[About-the-WINDUP_HOME-Variable]] === 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 link:Install-Windup[download and install] the latest distribution of Windup from the JBoss Nexus repository, `WINDUP_HOME` refers to the `windup-distribution-2.0.0.VERSION` folder extracted from the downloaded ZIP file. -* If you link:Dev:-Execute-Windup-Built-from-Source[build Windup from source], `WINDUP_HOME` refers to the `windup-distribution-2.0.0-` folder extracted from the Windup source `dist/target/windup-distribution-2.0.0-VERSION.zip` file. \ No newline at end of file +* If you download and install the latest distribution of Windup from the JBoss Nexus repository, `WINDUP_HOME` refers to the `windup-distribution-2.0.0.VERSION` folder extracted from the downloaded ZIP file. +* If you build Windup from GitHub source, `WINDUP_HOME` refers to the `windup-distribution-2.0.0-` folder extracted from the Windup source `dist/target/windup-distribution-2.0.0-VERSION.zip` file. \ No newline at end of file diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 3196426c95..0000000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,23 +0,0 @@ -=== Build the Windup Guides - -. Install Ascidoctor -+ --------- -gem install sciidoctor --------- - -. Grab the latest changes from the Windup Wiki site - -** Copy any updated pages from the Windup Wiki -** Rename the extension from .asciidoc to .adoc -** Find any internal `link:` macros in the page -*** Make sure the linked page is added with an `include:` in the Guide template. -*** Replace the `link:` macros with an '`xref:` - - -. Build the HTML version of the guide -+ --------- -asciidoctor -dbook -a toc -o WindupUserGuide.html Windup-User-Guide.adoc --------- - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..e1f046ba96 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Windup Documentation Contributing Guide + +## Wiki Asciidoc Syntax Guidelines + +The following guidelines make the transition from the Windup Wiki pages to the Windup documentation GitHub smoother. + +* Be sure to add a level 3 page heading for each page. When compiled in a book, the Guide name is the top level, chapters are level 2, and the page is level 3. + + === Build Windup from Source + +* At the beginning of each new Wiki page, add an anchor with the exact page name, including the dashes. This is needed when the pages are combined into a book. + + [[Dev-Build-Windup-from-Source]] + === Build Windup from Source + +* Wiki generates anchors using dashes for spaces. AsciiDoctor generates a leading underscore and underscores for spaces. When referring to another section within the same page, do not use the `<>` syntax. It does not generate correctly for the documentation books. Instead, create an anchor and use the 'xref:' syntax to provide the link. + + Create the anchor at the top of the page: + + [_windup_command_examples] + ==== Windup Command Examples + + Then use the `xref` to create the link. Note, the Wiki generates the name with dashes (-) for spaces. + + See xref:windup-command-examples[Windup Command Examples] for more information. + + Because Asciidoctor generates a leading underscore and underscores for spaces, we need to modify the `xref:` text when the documentation is copied to windup-documenation. + + See xref:_windup_command_examples[Windup Command Examples] for more information. + +## Build the Windup Guides + +* Install Ascidoctor + + gem install sciidoctor + +* Grab the latest changes from the Windup Wiki site + + * Copy any updated pages from the Windup Wiki and replace the `.asciidoc` extension with `.adoc` + + cp ../windup.wiki/Features-of-Windup-2.0.asciidoc Features-of-Windup-2.0.adoc + + * Find the internal `link:` macros in pages that link to other pages. + + * Make sure each linked page is added with an `include:` in the Guide template. + + * Make sure the wiki page is copied and added to this GitHub. + + * Replace the `link:` macros with a `xref:` macros. + + * Find the internal `xref:` macros. Add a leading underscore and replace the dashes with underscores. + + Old: See xref:windup-command-examples[Windup Command Examples] for more information. + New: See xref:_windup_command_examples[Windup Command Examples] for more information. + +* Build the HTML version of the guide + + asciidoctor -dbook -a toc -o WindupUserGuide.html Windup-User-Guide.adoc + diff --git a/Dev-Debugging-and-Profiling.adoc b/Dev-Debugging-and-Profiling.adoc new file mode 100644 index 0000000000..0aa8801601 --- /dev/null +++ b/Dev-Debugging-and-Profiling.adoc @@ -0,0 +1,63 @@ +[[Dev-Debugging-and-Profiling]] +=== Debugging and Profiling + +==== Debug the Windup Distribution Runtime + +You can debug the Windup distribution using one of the following approaches. + +. Pass the `--debug` argument on the command line when you execute Windup. ++ +-------- +For Linux: WINDUP_HOME/bin $ ./windup --debug +For Windows: C:\WINDUP_HOME\bin> windup --debug +-------- + +. Configure the `FORGE_OPTS` for debugging. ++ +-------- +export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000" +-------- + +==== Debug a Test Using NetBeans + +Click the `Debug Test File` button, or choose `Menu` → `Debug` → `Debug Test File`. + +==== Profile a Test Using NetBeans + +. Profiling requires a lot of memory, so be sure to increase the NetBeans memory settings. +* Open the `NETBEANS_HOME/etc/netbeans.conf` file +* Find the line with `netbeans_default_options=` +* Add the following option ++ +-------- +-J-Xmx5200m -J-XX:MaxPermSize=1024m +-------- +* Restart NetBeans. + +. Click `Menu > Profile > Profile Test File`. +. In the resulting dialog, enter the following. ++ +-------- +exec.args=-Djboss.modules.system.pkgs=org.netbeans +-------- + +==== Profile Forge Runtime Using YourKit + + +. Download and unzip http://www.yourkit.com/[YourKit]. Be sure to get the trial license. +. Configure the `FORGE_OPTS` for Yourkit: ++ +-------- +export YOURKIT_HOME=/home/ondra/sw/prog/YourKit-b14092 +export FORGE_OPTS="-Djboss.modules.system.pkgs=com.yourkit -agentpath:$YOURKIT_HOME/bin/linux-x86-64/libyjpagent.so=sampling,onexit=snapshot,delay=0" +-------- + +. Run `forge`. For details, see http://forge.jboss.org/1.x/docs/using/profiling-forge.html[Profiling +Forge], but skip the first 2 points that direct you to copy the YourKit module and JAR into the Forge installation. Forge 2 already contains the YourKit module and JAR>. + +. Run `windup-analyze-app`. ++ +--------------------------- +forge -e windup-migrate-app +--------------------------- + diff --git a/Dev-Troubleshoot-Windup-Issues.adoc b/Dev-Troubleshoot-Windup-Issues.adoc new file mode 100644 index 0000000000..b6adc9d375 --- /dev/null +++ b/Dev-Troubleshoot-Windup-Issues.adoc @@ -0,0 +1,21 @@ +[Dev-Troubleshoot-Windup-Issues] +=== Troubleshoot Windup Issues + +==== Logging + +Logging is currently broken and will not be fixed any time soon. + +See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-73[WINDUP-73] for the current status. + +==== Debugging Exceptions + +Exceptions in Surefire reports are broken due to the way Forge wraps +exceptions and the way Surefire handles them. You need to +debug or rewrap exceptions using `TestUtil.rewrap(ex)`. + +See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-197[WINDUP-197] for the current status.. + +==== Classloading Problems + +Configuring dependencies in a Forge-based project can be a little tricky. +See xref:Dev-Dependencies[Dependencies] for some hints. diff --git a/Dev-Windup-Architectural-Components.adoc b/Dev-Windup-Architectural-Components.adoc index b5b33757f9..0e221f4810 100644 --- a/Dev-Windup-Architectural-Components.adoc +++ b/Dev-Windup-Architectural-Components.adoc @@ -10,7 +10,7 @@ familiar with them. Forge is an open source, extendable, rapid application development tool for creating Java EE applications using Maven. For more information -about Forge, see: http://forge.jboss.org/[JBoss Forge]. +about Forge 2, see: http://forge.jboss.org/[JBoss Forge]. ==== Forge Furnace @@ -36,7 +36,7 @@ a collection of annotated Java Interfaces. For more information, see: https://github.com/tinkerpop/frames/wiki[TinkerPop Frames]. Windup includes several Frames extensions, which are documented here: -link:./Dev:-Frames-extensions[Frames Extensions]. +xref:Dev-Frames-extensions[Frames Extensions]. ==== Gremlin diff --git a/Execute-Windup.adoc b/Execute-Windup.adoc index f05ca23ef1..27358e6931 100644 --- a/Execute-Windup.adoc +++ b/Execute-Windup.adoc @@ -1,3 +1,4 @@ +[[Execute-Windup]] === Execute Windup These instructions are for users who run Windup using the tool extracted from the ZIP download. @@ -16,9 +17,7 @@ Before you begin, you must gather the following information. * While you can provide package names for standard Java EE 3rd party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. * If you omit the `--packages` argument, every package in the application is scanned, resulting in very slow performance. It is best to provide the argument with one or more packages. -IMPORTANT: There is currently a bug in the parser that does not resolve the tilde (~) in a path name correctly. For now, you must fully spell out the complete path name when it is passed as an argument in the Windup command line. For example, use `/home/username/path-to-file` rather than `~/path-to-file`. For details, see https://issues.jboss.org/browse/WINDUP-305. - -==== Run Windup +==== Start Windup . Open a terminal and navigate to the `WINDUP_HOME/bin` directory @@ -71,7 +70,7 @@ Where: NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists, it is deleted and recreated by Windup, so be careful not to specify a directory that contains important information! + -See <> below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository. +See xref:_windup_command_examples[Windup Command Examples] below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository. . You should see the following result upon completion of the command: + @@ -95,7 +94,7 @@ The following subdirectories in the `OUTPUT_REPORT_DIRECTORY` contain the suppor stats/ index.html -. For details on how to evaluate the report data, see xref:_review_the_report[Review the Report]. +. For details on how to evaluate the report data, see xref:Review-the-Report[Review the Report]. ==== Windup Help @@ -103,6 +102,7 @@ To see the list of available parameters for the `windup-migrate-app` command, ex man windup-migrate-app +[_windup_command_examples] ==== Windup Command Examples The following Windup command examples report against applications located in the https://github.com/windup/windup/tree/master/test-files[Windup source test-files] directory. diff --git a/Features-of-Windup-2.0.adoc b/Features-of-Windup-2.0.adoc index 66613db92b..8373e0fc20 100644 --- a/Features-of-Windup-2.0.adoc +++ b/Features-of-Windup-2.0.adoc @@ -1,8 +1,9 @@ -= Features of Windup 2.0 +[[Features-of-Windup-2.0]] +=== Features of Windup 2.0 [horizontal] -Shared Data Model:: Windup 2.0 creates a shared data model graph that provides the following benefits: +Shared Data Model:: Windup 2.0 creates a shared data model graph that provides the following benefits. * It enables complex rule interaction, allowing rules to pass findings to other rules. * It enables 3rd-party plug-ins to interact with other plugins, rules and reports. diff --git a/Get-Involved.adoc b/Get-Involved.adoc index ebe8ac8b59..df805e4bfe 100644 --- a/Get-Involved.adoc +++ b/Get-Involved.adoc @@ -1,10 +1,11 @@ -= Get Involved +[[Get-Involved]] +=== Get Involved -== How can you help? +==== How can you help? To help us make Windup cover most application constructs and server configurations, including yours, you can help with any of the following items. Some items require only a few minutes of your time! -* link:mailto:windup-users@redhat.com[Let us know] what Windup migration rules should cover. +* mailto:windup-users@redhat.com[Let us know] what Windup migration rules should cover. * Provide example applications to test migration rules. * Identify application components and problem areas that may be difficult to migrate. ** Write a short description of these problem migration areas. @@ -12,31 +13,11 @@ To help us make Windup cover most application constructs and server configuratio * link:Execute-Windup[Try Windup] on your application. Be sure to link:Report-Issues-with-Windup[report any issues] you encounter. * Write an Windup rule to automate the migration process. ** Create a test for the new rule. -* You can <>. -* You can also <>. +* You can contribute Windup rules. For details, see the _Windup Rules Development Guide_. +* You can also contribute to the project source code. See the _Windup Core Development Guide_ for information about how to configure your environment and set up the project. -Any level of involvement is greatly appreciated. +Any level of involvement is greatly appreciated! -== Contribute Windup Rules -Check back later for details about how to contribute rules to the Windup -project. - -For more information about how to contribute rules to the Windup -project, see the link:Rules-Development-Guide[Rules Development Guide]. - -== Contribute to the Project Source Code - -The Windup project source code is located in this GitHub repository: -https://github.com/windup/windup. - -* For instructions on how to fork and clone the Windup source code, see -link:./Dev:-Get-the-Windup-Source-Code[Get the Windup Source Code]. -* For instructions on how to build Windup, see -link:./Dev:-Build-Windup-from-Source[Build Windup from Source] - -For more information about how to develop code for the Windup -project, see the -link:Dev:-Windup-Development-Guide[Windup Development Guide]. diff --git a/Glossary.adoc b/Glossary.adoc index f5e14aac8f..30ef66a0b9 100644 --- a/Glossary.adoc +++ b/Glossary.adoc @@ -1,3 +1,4 @@ +[[Glossary]] === Glossary of Terms Used in Windup ==== Rules Terms diff --git a/Install-Windup.adoc b/Install-Windup.adoc index fb076c196d..52b9fedb12 100644 --- a/Install-Windup.adoc +++ b/Install-Windup.adoc @@ -1,6 +1,7 @@ +[[Install-Windup]] === Install Windup -. Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.jboss.windup&a=windup-distribution&v=2.0.0.Beta5&e=zip&c=offline[windup-distribution-2.0.0.Beta5]. +. Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution/2.0.0.Beta6/[windup-distribution-2.0.0.Beta6]. . Extract the ZIP file in to a directory of your choice. -NOTE: The documentation uses the replaceable value `WINDUP_HOME` to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable]. +NOTE: The documentation uses the replaceable value `WINDUP_HOME` to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable]. diff --git a/Install-and-Configure-Maven.adoc b/Install-and-Configure-Maven.adoc new file mode 100644 index 0000000000..f74f4102bd --- /dev/null +++ b/Install-and-Configure-Maven.adoc @@ -0,0 +1,84 @@ +[[Install-and-Configure-Maven]] +=== Install and Configure Maven + +==== Download and Install Maven + +If you plan to use Eclipse Luna (4.4) to build Windup, you can skip this +step. This version of Eclipse embeds Maven 3.2.1 so you do not need to +install it separately. Skip to the section entitled xref:_configure_maven_to_build_windup[Configure Maven to Build Windup]. + +If you plan to run Maven using the command line or plan to use Red Hat +JBoss Developer Studio 7.1.1 or an older version of Eclipse, you must +install Maven 3.1.1. or later. + +. Go to http://maven.apache.org/download.html[Apache Maven Project - +Download Maven] and download the latest distribution for your operating +system. +. See the Maven documentation for information on how to download and +install Apache Maven for your operating system. + +==== Configure the Maven Installation in Your IDE + +JBoss Developer Studio 7.1.1 is built upon Eclipse Kepler (4.3), which +embeds Maven 3.0.4. If you plan to use JBoss Developer Studio 7.1.1 or +an Eclipse version earier than Eclipse Luna (4.4), you must replace the +embedded 3.0.4 version of Maven with this newer version. + +. From the menu, choose `Window` --> `Preferences`. +. Expand `Maven` and click on `Installations`. +. Uncheck `Embedded (3.0.4/1.4.0.20130531-2315)` +. Click `Add` and navigate to your Maven install directory. Select it +and click `OK`. +. Make sure the new external Maven installation is checked and click +`OK` to return to JBoss Developer Studio. + +_Note: If you use another IDE, refer to the product documentation to +update the Maven installation._ + +[_configure_maven_to_build_windup] +==== Configure Maven to Build Windup + +Windup uses artifacts located in the +http://repository.jboss.org/nexus/content/groups/public/[JBoss Nexus] +repository. You must configure Maven to use this repository before you +build Windup. + +. Open your `${user.home}/.m2/settings.xml` file for editing. +. Copy the following `jboss-nexus-repository` profile XML prior to the +ending `` element. ++ +------------------------------------------------------------------------- + + jboss-nexus-repository + + + jboss-nexus-repository + http://repository.jboss.org/nexus/content/groups/public/ + + true + + + true + + + + + + jboss-nexus-plugin-repository + http://repository.jboss.org/nexus/content/groups/public/ + + true + + + true + + + + +------------------------------------------------------------------------- +. Copy the following XML prior to the ending `` +element to make the profile active. ++ +---------------------------------------------------------- + jboss-nexus-repository +---------------------------------------------------------- diff --git a/Known-Issues.adoc b/Known-Issues.adoc new file mode 100644 index 0000000000..3cfa4f4006 --- /dev/null +++ b/Known-Issues.adoc @@ -0,0 +1,13 @@ +[[Known-Issues]] +=== Known Issues + +The following is a list of currently known issues. + +* https://issues.jboss.org/browse/WINDUP-73[WINDUP-73] +** If you do not see expected log messages, resort to `System.out.println()` for logging. +** You may see too much logging, especially from Forge. This is to be expected. + +* https://issues.jboss.org/browse/WINDUP-197[WINDUP-197] +** Exceptions in Surefire reports are broken due to the way Forge wraps exceptions and the way Surefire handles them. +** You need to debug or rewrap exceptions using TestUtil.rewrap(ex). + diff --git a/Migration-Planning-Guide.adoc b/Migration-Planning-Guide.asciidoc similarity index 100% rename from Migration-Planning-Guide.adoc rename to Migration-Planning-Guide.asciidoc diff --git a/Report-Issues-with-Windup.adoc b/Report-Issues-with-Windup.adoc index 57d0c75f0e..c4b9dfc666 100644 --- a/Report-Issues-with-Windup.adoc +++ b/Report-Issues-with-Windup.adoc @@ -1,3 +1,4 @@ +[[Report-Issues-with-Windup]] === Report Issues with Windup Windup uses JIRA as its issue tracking system. If you encounter an issue executing Windup, please file a Windup JIRA Issue. diff --git a/Report-an-Issue-with-Windup.adoc b/Report-an-Issue-with-Windup.adoc deleted file mode 100644 index cce61a5444..0000000000 --- a/Report-an-Issue-with-Windup.adoc +++ /dev/null @@ -1,34 +0,0 @@ -= Report an Issue with Windup - -Windup uses JIRA as its issue tracking system. If you encounter an issue executing Windup, please file a Windup JIRA Issue. - -== Create a JIRA Account - -If you do not yet have a JIRA account, create one using the following procedure. - -1. Open a browser to the following URL: https://issues.jboss.org/secure/Dashboard.jspa -2. Click the _Sign Up_ link in the top right side of the page. -3. Enter your email address and click the `Confirm address` button. -4. Follow the instructions sent to your email address. - -== Create a JIRA Issue - -1. Open a browser to the following URL: https://issues.jboss.org/secure/CreateIssue!default.jspa. - -* If you have not yet logged in, click the _Log In_ link at the top right side of the page. -* Enter your credentials and click the `LOGIN` button. -* You are then redirected back to the *Create Issue* page. - -2. Choose the following options and click the `Next` button. - -* *Project*: _Windup_ -* *Issue Type*: _Bug_ - -3. On the next screen complete the following fields: - -* *Summary*: Enter a brief description of the problem or issue. -* *Environment*: Provide the details of your operating system, version of Java, and any other pertinent information. -* *Description*: Provide a detailed description of the issue. Be sure to include logs and exceptions traces. - -4. Click the `Create` button to create the JIRA issue. -5. If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the Windup development team, attach it to the issue by choosing `More -> Attach Files`. You are provided with an option to restrict visibility to JBoss employees. \ No newline at end of file diff --git a/Review-the-Report.adoc b/Review-the-Report.adoc index 3460941113..22340300e0 100644 --- a/Review-the-Report.adoc +++ b/Review-the-Report.adoc @@ -1,3 +1,4 @@ +[[Review-the-Report]] === Review the Report ==== About the Report @@ -22,7 +23,7 @@ image:images/report-index-page.png[Report Index Page, 500] Click on the link under the *Name* column to view the Windup application report page. -==== Review the Report +==== Report Sections ===== Application Report Page @@ -35,7 +36,7 @@ The following is an example of a Windup Application Report. image:images/report-javaee-ear-summary.png[Report Summary Page, 500] -====== Archive Analysis Sections +===== Archive Analysis Sections Each archive summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns. @@ -94,7 +95,7 @@ The `OUTPUT_REPORT_DIRECTORY/reports/ruleproviders.html` page provides the list ===== Individual File Analysis Reports -You can directly access the the link:Review-the-Report#file-analysis-pages[file analysis report pages] described above by browsing for them by name in the `OUTPUT_REPORT_DIRECTORY/reports/` directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name. +You can directly access the the xref:Review-the-Report#file-analysis-pages[file analysis report pages] described above by browsing for them by name in the `OUTPUT_REPORT_DIRECTORY/reports/` directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name. image:images/report-directory-file-list.png[Report Directory File List, 500] diff --git a/Review-the-Windup-Quickstarts.adoc b/Review-the-Windup-Quickstarts.adoc index 55f720d887..6eb1a15c20 100644 --- a/Review-the-Windup-Quickstarts.adoc +++ b/Review-the-Windup-Quickstarts.adoc @@ -1,3 +1,4 @@ +[[Review-the-Windup-Quickstarts]] === Review the Windup Quickstarts The Windup quickstarts provide working examples of how to create custom Java-based rule addons and XML rules. You can use them as a starting point for creating your own custom rules. The quickstarts are available on GitHub here: https://github.com/windup/windup-quickstarts diff --git a/Rules-Basic-Rule-Execution-Flow-Patterns.adoc b/Rules-Basic-Rule-Execution-Flow-Patterns.adoc new file mode 100644 index 0000000000..9ea0213287 --- /dev/null +++ b/Rules-Basic-Rule-Execution-Flow-Patterns.adoc @@ -0,0 +1,121 @@ +[[Rules-Basic-Rule-Execution-Flow-Patterns]] +=== Basic Rule Execution Flow Patterns + +SGILDA: TODO - Need some links to github to the respective example files. + +==== operation(); - single operation + +When no iteration or condition is needed. + +Example: [CopyJavaConfigToGraphRuleProvider](rules-java/src/main/java/org/jboss/windup/rules/apps/java/config/CopyJavaConfigToGraphRuleProvider.java) + +[source,java] +-------- +return ConfigurationBuilder.begin() + .addRule() + .perform(new GraphOperation(){ + @Override + public void perform(GraphRewrite event, EvaluationContext context){ + ... + } + }); +-------- + + +==== if( ... ){ operation(); } - single conditional operation + + +[source,java] +-------- +return ConfigurationBuilder.begin() + .addRule() + .when( ... ) + .perform(new GraphOperation(){ + @Override + public void perform(GraphRewrite event, EvaluationContext context){ + ... + } + }); +-------- + + +==== for( FooModel.class ){ ... } - Single iteration + +For simple iterations, `IteratingRuleProvider` can be used, which makes the `perform` a bit less verbose: + +[source,java] +-------- +public class ComputeArchivesSHA512 extends IteratingRuleProvider +{ + public ConditionBuilder when() { + return Query.find(ArchiveModel.class); + } + + // @formatter:off + public void perform( GraphRewrite event, EvaluationContext context, ArchiveModel archive ){ + try( InputStream is = archive.asInputStream() ){ + String hash = DigestUtils.sha512Hex(is); + archive.asVertex().setProperty(KEY_SHA512, hash); + } + catch( IOException e ){ + throw new WindupException("Failed to read archive: " + archive.getFilePath() + + "\n Due to: " + e.getMessage(), e); + } + } + // @formatter:on + + @Override public String toStringPerform() { return this.getClass().getSimpleName(); } +} +-------- + + +==== if( ... ){ for( ... ) } - conditional iteration + +[source,java] +-------- +return ConfigurationBuilder.begin() + .addRule() + .when( + new GraphCondition(){ ... } + ).perform( + Iteration.over(ArchiveModel.class) + .perform( ... ) + ) +-------- + + + +==== for( ... ){ if( ... ){ ... } } - iteration with a condition + +[source,java] +-------- +return ConfigurationBuilder.begin() +.addRule() + .when( + // Stores all ArchiveModel's into variables stack, under that type. + Query.find(ArchiveModel.class) + ).perform( + Iteration.over(ArchiveModel.class) // Picks up ArchiveModel's from the varstack. + .when(new AbstractIterationFilter(){ + @Override + public boolean evaluate(GraphRewrite event, EvaluationContext context, ArchiveModel payload) + { + return payload.getProjectModel() == null; + } + @Override + public String toString() + { + return "ProjectModel == null"; + } + }) + .perform( ... ) +-------- + + + +==== for( ... ){ for( ... ) { ... } } - nested iterations + +[source,java] +-------- + +-------- diff --git a/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc b/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc new file mode 100644 index 0000000000..0727acbcb0 --- /dev/null +++ b/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc @@ -0,0 +1,306 @@ +[[Rules-Create-a-Basic-Java-based-Rule-Add-on]] +=== Create a Basic Java-based Rule Add-on + +You can create a rule using Java or XML. This topic describes how to create a rule add-on using Java. + +==== Prerequisites + +* You must xref:Install-Windup[Install Windup]. +* Be sure you xref:Install-and-Configure-Maven[Install and Configure Maven]. +* Before you begin, may want 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/javadoc/latest/ + +NOTE: Working examples of Java-based rules can be found in the Windup quickstarts GitHub repository located here: https://github.com/windup/windup-quickstarts + +==== Create a Rule Add-on + + +===== Create a Maven Project + +Create a new Maven Java Project. These instructions will refer to the project folder location with the *replaceable* variable 'RULE_PROJECT_HOME'. Modify the project `pom.xml` file as follows + +1. Add the following properties: ++ +[source,xml] +---- + + UTF-8 + 1.7 + 1.7 + 2.0.0.Beta3 + 2.12.1.Final + +---- + +2. Add a dependency management section for the Windup BOM. ++ +[source,xml] +---- + + + + + org.jboss.windup + windup-bom + ${version.windup} + pom + import + + + +---- + +3. Add a `` section to include Windup, rulesets, and test dependencies required by your rule add-on. Windup is a Forge/Furnace based application and has a modular design, so the dependencies will vary depending on the Windup APIs used by the rule. For more information on Windup dependencies, see xref:Dev-Dependencies[Windup Dependencies]. ++ +The following are examples of some dependencies you may need for your rule add-on. ++ +[source,xml] +---- + + + org.jboss.windup.graph + windup-graph + forge-addon + provided + + + org.jboss.windup.config + windup-config + forge-addon + provided + + + org.jboss.windup.ext + windup-config-groovy + forge-addon + provided + + + org.jboss.windup.utils + utils + forge-addon + provided + + + org.jboss.windup.reporting + windup-reporting + forge-addon + provided + + + + + org.jboss.windup.rules.apps + rules-java + forge-addon + provided + + + org.jboss.forge.furnace.container + cdi-api + provided + + + org.jboss.forge.furnace.container + cdi + forge-addon + provided + + + + + org.jboss.forge.furnace.test + furnace-test-harness + test + + + org.jboss.forge.furnace.test + arquillian-furnace-classpath + test + + + junit + junit + 4.11 + jar + + + + org.jboss.windup.exec + windup-exec + forge-addon + test + + +---- + +4. Add the `` section to make it a Forge add-on. ++ +[source,xml] +---- + + + + org.jboss.forge.furnace + furnace-maven-plugin + ${version.furnace} + + + generate-dot + prepare-package + generate-dot + true + + + + + maven-jar-plugin + + + create-forge-addon + package + jar + + forge-addon + + + + + +---- + +===== Create the Java RuleProvider + +1. Within your Maven project, create a Java class that extends the `WindupRuleProvider` class. It is suggested that you end the name of the class with `RuleProvider`. For example: ++ +[source,xml] +---- +public class MyCustomRuleProvider extends WindupRuleProvider +{ +} +---- + +2. If the rule provider must run in a phase other than the default `MIGRATION_RULES` phase, override the phase using the `getPhase()` method. For example, you may want the rule provider to perform a task during the initial *DISCOVERY* phase, for example, to ignore files with a specific name or extension. ++ +[source,java] +---- + @Override + public RulePhase getPhase() { + return RulePhase.DISCOVERY; + } +---- +For more information about rule phases, see xref:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecycles]. + +3. To control the order in which the rule is executed, implement the `getExecuteBefore()` or `getExecuteAfter()` method. ++ +[source,java] +---- +List> executeBeforeList = new ArrayList<>(); + +@Override +public List> getExecuteBefore() +{ + return executeBeforeList.add(RuleToFireBefore.class); +} +---- ++ +[source,java] +---- +List> executeAfterList = new ArrayList<>(); + +@Override +public List> getExecuteAfter() +{ + return executeAfterList.add(RuleToFireAfter.class); +} +---- + +4. Finally, add the rule or rules to the rule provider. + +* High-level Conditions and Operations ++ +The following is a specific high-level rule which uses high-level conditions (`JavaClass`) and operations (`Classification`). See the documentation of those conditions and operations for the details. ++ +[source,java] +---- +@Override +public Configuration getConfiguration(GraphContext context) +{ + return ConfigurationBuilder.begin() + .addRule() + .when( + JavaClass.references("weblogic.servlet.annotation.WLServlet").at(TypeReferenceLocation.ANNOTATION) + ) + .perform( + Classification.as("WebLogic @WLServlet") + .with(Link.to("Java EE 6 @WebServlet", "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/index.html")) + .withEffort(0) + .and(Hint.withText("Migrate to Java EE 6 @WebServlet.").withEffort(8)) + ); +} +---- ++ +For more examples of rule providers, see the +https://github.com/windup/windup/blob/master/rules/app/java-ee/src/main/java/org/jboss/windup/rules/apps/legacy/java/BaseConfig.java#L53[BaseConfig.java] +rule. +* Low-level Conditions and Operations ++ +As you can see, the conditions and operations above are Java-specific. +They come with the `Java Basic` ruleset. The list of existing rulesets +will be part of the project documentation. Each ruleset will be +accompanied with a documentation for its `Condition`s and `Operation`s +(and also `Model`s). ++ +These high-level elements provided by rulesets may cover majority of +cases, but not all. Then, you will need to dive into the mid-level +Windup building elements. +* Mid-level Conditions and Operations + + +==== Install the Java-based Rule Add-on + +The easiest and fastest way to build the rule add-on, install it into the local Maven repository, and install it into Windup as a rule add-on is to use the Windup `addon-build-and-install` command. + +* If you have not started Windup, follow the instructions to xref:Execute-Windup[Execute Windup]. +* At the Windup console prompt, enter the `addon-build-and-install` command: + + addon-build-and-install --projectRoot RULE_PROJECT_HOME + +* You should see the following result. + + ***SUCCESS*** Addon MyCustomRuleProvider:::2.0.0.VERSION was installed successfully. + +==== Test the Java-based Rule Add-on + +Test the Java-based rule add-on against your application file by running the `windup-migrate-app` command in the Windup console prompt. + +The command uses this syntax: + + windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N + +You should see the following result: + + ***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html + +For more information and examples of how to run Windup, see: xref:Execute-Windup[Execute Windup] + +==== Review the Output Report + +1. Open OUTPUT_REPORT_DIRECTORY /index.html file in a browser. +2. You are presented with an Overview page containing the application profiles. +3. Click on the application link to review the detail page. Check to be sure the warning messages, links, and story points match what you expect to see. + + +TBD. + +* Models +** https://github.com/tinkerpop/frames/wiki[Frames] +** xref:Rules-Windup-Models[Windup Models] +* Rules +** http://ocpsoft.org/rewrite/[OCPSoft Rewrite] +** Conditions, Operations +*** Variables +** Inter-rule action +** xref:Rules:-Rules-Execution-Lifecycle[Inter-rule dependency] +*** Short IDs - https://issues.jboss.org/browse/WINDUP-217[WINDUP-216] diff --git a/Rules-Create-a-Basic-XML-Rule.adoc b/Rules-Create-a-Basic-XML-Rule.adoc new file mode 100644 index 0000000000..1931116c16 --- /dev/null +++ b/Rules-Create-a-Basic-XML-Rule.adoc @@ -0,0 +1,119 @@ +[[Rules-Create-a-Basic-XML-Rule]] +=== Create a Basic XML Rule + +You can create a rule addon using Java or a rule using XML or Groovy. This topic describes how to create a rule using XML. + +==== Prerequisites + +* You should have already xref:Install-Windup[installed Windup]. +* 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/javadoc/latest/ + +NOTE: Working examples of XML-based rules can be found in the Windup quickstarts GitHub repository located here: https://github.com/windup/windup-quickstarts + +==== Create a Rule + +The following is an example of an XML rule. + + + + + + DISCOVERY + + + + + + METHOD_PARAMETER + + + + + Message from XML Rule + + + + + + + + + + + + + + + + + Container Auth + + + + + + + + + + + +===== Create the XML Rule + +**Note:** Windup only analyzes XML files with names ending in `.windup.xml`. Be sure to name XML-based rules using this naming convention! + +The XML rule consists of the following level elements: + +* ****: This element defines this as a Windup rule. +* ****: This element specifies when the ruleset should execute. See xref:Rules-Rules-Execution-Lifecycle#rule-phases[Rule Phases in the Rule Execution Lifecyle] for more information. +* ****: element contains the individual rules. +** ****: This element is a child of the **rules** element. One or more rules can be defined for a ruleset. Each `rule` contains the following elements. +*** ****: This element defines the condition to match on. +**** **** +***** ****: The location where the reference was found in a Java source file. See the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/rules/apps/java/scan/ast/TypeReferenceLocation.html[Enum TypeReferenceLocation] Javadoc for valid values. +*** ****: This element is invoked when the condition is met. +**** ****: This child element of **perform** is used to create a `hint` +***** ****: +***** ****: +**** ****: This specifies how to transform the the specified XML file +**** ****: This child element of **perform** is used to log a message. It takes the attribute **message** to define the text message. +*** The **** element is invoked when the condition is not met. + +==== Add the Rule to Windup + +A Windup rule is installed simply by copying the rule to the appropriate Windup folder. Windup scans for rules in the following locations: + + +WINDUP_HOME/rules/:: This is the Windup folder where you run the Windup executable. See xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] for details. + +${user.home}/.windup/rules/:: This folder is created by Windup the first time you execute Windup. ++ +-------- +For Linux or Mac: ~/.windup/rules/ +For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" -or- "\Users\USER_NAME\.windup\rules\" +-------- + +==== Test the XML Rule + +NOTE: If you have not started Windup, follow the instructions to xref:Execute-Windup[Execute Windup]. + +Test the XML rule against your application file by running the `windup-migrate-app` command in the Windup console prompt. + +The command uses this syntax: + +-------- +windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N +-------- + +You should see the following result: + +-------- +***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html +-------- +For more information and examples of how to run Windup, see: xref:-Execute-Windup[Execute Windup] + + diff --git a/Rules-Create-an-Advanced-Ruleset.adoc b/Rules-Create-an-Advanced-Ruleset.adoc new file mode 100644 index 0000000000..3e3a52f0dc --- /dev/null +++ b/Rules-Create-an-Advanced-Ruleset.adoc @@ -0,0 +1,18 @@ +[[Rules-Create-an-Advanced-Ruleset]] +=== Create an Advanced Ruleset + +DRAFT + +1. Create the Forge add-on + +* xref:Rules-Create-a-Basic-Java-based-Rule-Add-on[Create a Basic Java-based Rule Add-on] + +2. Add the dependencies you need + +3. Create the service with your functionality, if needed + +4. Create the rules + (Add a the LINK) + +5. Add the information to the report + (Add a the LINK) diff --git a/Rules-Development-Guide.asciidoc b/Rules-Development-Guide.asciidoc new file mode 100644 index 0000000000..4c3b8301e5 --- /dev/null +++ b/Rules-Development-Guide.asciidoc @@ -0,0 +1,65 @@ += Rules Development Guide + +This guide is for engineers, consultants, or others who plan to create +rules for Windup 2.0. + +== Overview + +* link:What-is-Windup[What is Windup?] +* link:Features-of-Windup-2.0[Features of Windup 2.0] +* link:Get-Involved[Get Involved] +* link:Report-Issues-with-Windup[Report Issues with Windup] +* link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] + +== Get Started + +* link:Install-Windup[Install Windup] +* link:Execute-Windup[Execute Windup] +* link:Review-the-Report[Review the Report] + +== Configure Your System for Java-based Rules + +If you plan to create Java-based rule addons, you must also do the following. + +* link:Install-and-Configure-Maven[Install and Configure Maven] +* link:http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons. + +== Understand the Rule Processing + +* link:Windup-Processing-Overview[Windup Processing Overview] +* link:Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle] +* link:Rules-Rule-Story-Points[Rule Story Points] + +== Create and Test Java Rule Addons + +* link:Rules-Java-based-Rule-Structure[Java-based Rule Structure] +* link:Rules-Basic-Rule-Execution-Flow-Patterns[Basic Rule Execution Flow Patterns] +* link:Rules-Create-a-Basic-Java-based-Rule-Add-on[Create a Basic Java-based Rule Add-on] +* link:Rules-Create-an-Advanced-Ruleset[Create an Advanced Ruleset] + +== Create and Test XML Rules + +* link:Rules-Create-a-Basic-XML-Rule[Create a Basic XML Rule] + +== Review the Report + +* link:Review-the-Report[Review the Report] + +== External Rule Examples + +* link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] + +== Debugging and Troubleshooting + +* link:Dev-Debugging-and-Profiling[Debugging and Profiling] +* link:Dev-Troubleshoot-Windup-Issues[Troubleshoot Windup Issues] + +== Additional Help + +* link:Report-Issues-with-Windup[Report Issues with Windup] +* link:Glossary[Glossary of Terms] + +== Appendix + +* link:Dev-Windup-Architectural-Components[Windup Architectural Components] + diff --git a/Rules-Java-based-Rule-Structure.adoc b/Rules-Java-based-Rule-Structure.adoc new file mode 100644 index 0000000000..a69258360c --- /dev/null +++ b/Rules-Java-based-Rule-Structure.adoc @@ -0,0 +1,135 @@ +[[Rules-Java-based-Rule-Structure]] +=== Java-based Rule Structure + +TODO: +* Add a how-to for compound rules, nested rules, rules over multiple sources, negative queries (not matched by anything). +// - xref:Rules-Story-Points[How to estimate the migration effort with Story +Points] https://issues.jboss.org/browse/WINDUP-255[WINDUP-255] + +==== Windup Rule Provider + +Windup rules are based on http://ocpsoft.org/rewrite/[OCPsoft Rewrite], an open source routing and URL rewriting solution for Servlets, Java Web Frameworks, and Java EE. The *rewrite* framework allows you to create rule providers and rules in an easy to read format. + +Windup rule add-ons must extend the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/WindupRuleProvider.html[WindupRuleProvider] class. + +* If the rule should run in a phase other than the default http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#MIGRATION_PHASE[MIGRATION_PHASE], you must implement the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/WindupRuleProvider.html#getPhase%28%29[getPhase()] method and specify in which Windup lifecycle phase the rule should be executed. For more information about rule phases, see xref:./Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle]. + +* Rules are added using the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/WindupRuleProvider.html[getConfiguration(GraphContext context)] method. This method is inherited from the http://ocpsoft.org/rewrite/[OCPsoft Rewrite] interface org.ocpsoft.rewrite.config.ConfigurationProvider. Rules are discussed in more detail later. + +* If other rules must execute after or before the rules in this provider, you must provide the list of WindupRuleProvider classes using the *getExecuteAfter()* or *getExecuteAfter()* methods. + +The following is an example of a simple Java-based rule add-on. + +[source,java] +---- +public class ExampleRuleProvider extends WindupRuleProvider +{ + @Override public RulePhase getPhase(){ + return RulePhase.DISCOVERY; + } + + // @formatter:off + @Override + public Configuration getConfiguration(GraphContext context) + { + return ConfigurationBuilder.begin() + .addRule() + .when( + // Some implementation of GraphCondition. + Query.find(...).... + ) + .perform( + ... + ); + } + // @formatter:on + // (@formatter:off/on prevents Eclipse from formatting the rules.) +} +---- + +==== Add Rule Code Structure + +Like most rule-based frameworks, Windup rules consist of the following: + +* Condition: This is the *when(condition)* that determines if the rule should execute. +* Operation: This defines what to *perform()* if the condition is met. + +Rules consist of the _when_ part, the _perform_, the _otherwise_ part, +and some others, all of which are optional. + +===== when() + +In the `.when()` part, the rule typically queries the graph, using the +`Query` API. Results of the query are put on variables stack +(`Variables`), many times indirectly through the querying API. + +Other way to fill a when part is subclassing the `GraphCondition`. +Actually, `Query` also implements it, and is only a convenient way to +create a condition. + +Last noticable but important feature is the ability to use +https://github.com/tinkerpop/gremlin/wiki[Gremlin] queries. See +http://gremlindocs.com/[Gremlin docs] for reference manual. + +===== perform() + +In the `.perform()` part, the rule typically scans the items of interest +(Java files, XML files, querying services, ...), processes them, and +writes the findings into the graph. + +For that, various operations are available. These are subclasses of +`GraphOperation`. You can also implement your own. See +Rules-Operations[Rules Operations] for more info. Again, there are +several convenient implementations for constructs like iteration +(`Iteration`). + +====== Iteration + + +[source,java] +---- +.perform( + Iteration.over(XmlMetaFacetModel.class, "xmlModels").as("xml") + .when(...) + .perform( + new AbstractIterationOperation(XmlMetaFacetModel.class, "xml"){ + public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel xmlFacetModel) + { + } + }) + .otherwise( + new AbstractIterationOperation(XmlMetaFacetModel.class, "xml"){ + public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel payload) + { ... } + }) + .endIteration() +---- + +====== Nested iterations + +TODO + +====== otherwise + +Windup rules inherit the rule constructs from OCP Rewrite. For example, +`.otherwise()` Gives you a chance to perform something in case the +conditions in `.when()` return false (e.g. they do not match anything). +For more information, see http://ocpsoft.org/rewrite/[OCP Rewrite web]. + +===== Metadata + +Rules can specify metadata. Currently, the only appearing in some rules, +and not actually used, is `RuleMetadata.CATEGORY`. + +[source,java] +---- +.withMetadata(RuleMetadata.CATEGORY, "Basic") +---- + +`.withMetadata()` is basically putting key/value to a +`Map`. + +==== Available utilities + +For a list of what key services and constructs can be used in the rule, +see xref:Rules-Available-Utilities[Available Rules Utilities]. \ No newline at end of file diff --git a/Rules-Rule-Execution-Lifecycle.adoc b/Rules-Rule-Execution-Lifecycle.adoc new file mode 100644 index 0000000000..00abbad424 --- /dev/null +++ b/Rules-Rule-Execution-Lifecycle.adoc @@ -0,0 +1,100 @@ +[[Rules-Rule-Execution-Lifecycle]] +=== Rule Execution Lifecycle + +==== Rule Lifecycle + +Windup executes each rule in a single threaded mode. The following +sections describe the phases of rule execution and how rules may specify +that one or more other rules must be executed before or after they are +run. + +For graphical overview of rule processing, see +https://docs.google.com/drawings/d/1IMnds3Qu8Wwcf7_mr7NJ9a3YgtcGJ7dejl09EhWl7Vc/edit[this +diagram]. + +==== Rule Phases + +By default, a rule runs during the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#MIGRATION_RULES[MIGRATION_RULES] phase. However, a +rule may require certain processing or actions to occur before the it +executes, such as the extraction of archives and scanning of java or XML +files. + +Rule phases provide an way for rule authors to specify and control in +which phase of the rule lifecycle the rule should execute. This is done +by overriding the `WindupRuleProvider.getPhase()` method. The following +example specifies this rule should execute during the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#INITIAL_ANALYSIS[INITIAL_ANALYSIS] +rule phase. + +[source,java] +---- +@Override +public RulePhase getPhase() { + return RulePhase.INITIAL_ANALYSIS; +} +---- + +The following is the list of rule phases as defined in the `RulePhase` +enum class. Note that there are also `PRE_` processing and `POST_` +processing phases for each of the following rule phases. + +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#DISCOVERY[DISCOVERY]:: +This phase is called during resource discovery. Static files are scanned +by their basic properties, for example, the name, extension, location, +and fully qualified Java class name. Archives are unzipped in this +phase. Typically, any rule that only puts data into the graph is +executed during this phase. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#INITIAL_ANALYSIS[INITIAL_ANALYSIS]:: +This phase is called to perform a basic analysis of the files content. +It extracts all method names from class files, extracts metadata, such +as the XML namespace and root element, from XML files. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#COMPOSITION[COMPOSITION]:: +This phase is called to perform high-level composition operations on the +graph. For example, it may link items found in XML files to the related +Java classes or references to server resources in Java classes. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#MIGRATION_RULES[MIGRATION_RULES]:: +This is the default phase for all rules unless overridden. +During this phase, migration rules attach data to the graph associated +with migration. This could include: - Hints to migrators for manual +migration - Automated migration of schemas or source segments - +Blacklists to indicate vendor specific APIs. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#REPORT_GENERATION[REPORT_GENERATION]:: +During this phase, reporting visitors produce report data in the graph +that will later be used by the report rendering phase. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#REPORT_RENDERING[REPORT_RENDERING]:: +This is the phase that renders the report. +http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html#FINALIZE[FINALIZE]:: +This phase is called to clean up resources and close streams. + +For more information about rule phases, see the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/RulePhase.html[RulePhase Javadoc]. + +==== Execute Before and Execute After + +A rule may specify that one or more rules must be executed before it is +run. In this case, all named rules will be fired in the order specified +before executing the the current rule. + +[source,java] +---- +List> executeBeforeList = new ArrayList<>(); + +@Override +public List> getExecuteBefore() +{ + return executeBeforeList.add(RuleToFireBefore.class); +} +---- + +A rule may also specify that one or more rules must be executed after it +is run. In this case, all named rules will be fired in the order +specified after executing the the current rule. + +[source,java] +---- +List> executeAfterList = new ArrayList<>(); + +@Override +public List> getExecuteAfter() +{ + return executeAfterList.add(RuleToFireAfter.class); +} +---- \ No newline at end of file diff --git a/Rules-Rule-Story-Points.adoc b/Rules-Rule-Story-Points.adoc new file mode 100644 index 0000000000..09909eddf8 --- /dev/null +++ b/Rules-Rule-Story-Points.adoc @@ -0,0 +1,21 @@ +[[Rules-Rule-Story-Points]] +=== Rule Story Points + +==== What are Story Points? + +Story points are an abstract metric used in Scrum methodology to estimate the level of effort for various tasks. They are based on a http://scrummethodology.com/scrum-effort-estimation-and-story-points/[modified Fibonacci sequence]. In a similar manner, 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. + +==== How to Estimate Story Points in a Rule + +TODO: TBD. + +This could contain relative examples like: + +* Pure copy'n'paste - when we know for sure it will need no migration: 0 +* When we don't know if it will need a migration: Could depend on number of unknown imports, size +of the file, ... +* Changing parameter name, or value units: 2. +* Porting one web page (or similar concept) from one web framework to +the other: Could depend on complexity, e.g. number of components. E.g. +20 per component. +* Porting MyBatis to JPA: 20 per query. \ No newline at end of file diff --git a/User-Guide.adoc b/User-Guide.adoc deleted file mode 100644 index 789b3fde44..0000000000 --- a/User-Guide.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Windup User Guide - -This guide is for engineers, consultants, or others who plan to use -Windup 2.0 to migrate Java applications or other components. - -* link:What-is-Windup[What is Windup?] -* link:Windup-Processing-Overview[Windup Processing Overview] -* link:Install-Windup[Install Windup] -* link:Execute-Windup[Execute Windup] -* link:Review-the-Report[Review the Report] -* link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] -* link:Report-Issues-with-Windup[Report Issues with Windup] -* link:Glossary[Glossary of Terms] diff --git a/User-Guide.asciidoc b/User-Guide.asciidoc new file mode 100644 index 0000000000..4ec5d7b3bd --- /dev/null +++ b/User-Guide.asciidoc @@ -0,0 +1,32 @@ += Windup User Guide + +:toc: +:toclevels: 4 + +== Overview + +This guide is for engineers, consultants, and others who plan to use +Windup 2.0 to migrate Java applications or other components. + +* link:What-is-Windup[What is Windup?] +* link:Features-of-Windup-2.0[Features of Windup 2.0] +* link:Windup-Processing-Overview[Windup Processing Overview] +* link:Get-Involved[Get Involved] +* link:Report-Issues-with-Windup[Report Issues with Windup] +* link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] + +== Run Windup + +* link:Install-Windup[Install Windup] +* link:Execute-Windup[Execute Windup] +* link:Review-the-Report[Review the Report] + +== Additional Resources + +* link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] +* link:Known-Issues[Known Issues] +* link:Glossary[Glossary of Terms] + +== Appendix + +* link:Dev-Windup-Architectural-Components[Windup Architectural Components] diff --git a/What-is-Windup.adoc b/What-is-Windup.adoc index cc75d12ab1..128372d70f 100644 --- a/What-is-Windup.adoc +++ b/What-is-Windup.adoc @@ -1,3 +1,4 @@ +[[What-is-Windup]] === What is Windup? image:images/windup-logo-wiki-header.jpg[Windup Logo] diff --git a/Windup-Processing-Overview.adoc b/Windup-Processing-Overview.adoc index 84a5878d6f..e540898e62 100644 --- a/Windup-Processing-Overview.adoc +++ b/Windup-Processing-Overview.adoc @@ -1,3 +1,4 @@ +[[Windup-Processing-Overview]] === Windup Processing Overview Windup is a rule-based migration tool that allows you to write customized rules to analyze the APIs, technologies, and architectures used by the applications you plan to migrate. The Windup tool also executes its own core rules through all phases of the migration process. @@ -14,12 +15,7 @@ For more information about the graph database components, see xref:Dev-Windup-Ar The next step in the process is the execution of the migration rules. In this phase, the rules typically do not execute against the application input files. Instead, they execute against the graph database model. Windup rules are independent and decoupled and they communicate with each other using the graph database model. Rules query the graph database to obtain information needed to test the rule condition. They also update the data model with information based on the result of the rule execution. This allows rules to easily interact with other rules and enables the creation of very complex rules. -The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup's architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the Windup Rules Development Guide. -//// -*Comment* block -* link:Rules-Development-Guide#create-and-test-java-rule-addons[Create and Test Java Rule Addons] -* link:Rules-Development-Guide#create-and-test-xml-rules[Create and Test XML Rules] -//// +The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup's architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the _Windup Rules Development Guide_. ==== Generate Findings Based on the Rule Execution Results @@ -27,7 +23,7 @@ The final step in the process is to pull data from the graph database model to g By default, Windup generates the following reports at the end of the application migration process. The reports are located in the `reports/` subdirectory of the output report path specified when you execute Windup: -* Application Report: This report provides a summary of the total estimated effort, or link:Glossary#reporting[story points], that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder. +* Application Report: This report provides a summary of the total estimated effort, or xref:Rules-Rule-Story-Points[story points], that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder. * RuleProvider report: This is a detailed listing of the rule providers that fired when running Windup and whether any errors occurred. * Additional reports are generated that provide detailed line-by-line migration tips for individual files. diff --git a/Windup-Rules-Development-Guide.adoc b/Windup-Rules-Development-Guide.adoc new file mode 100644 index 0000000000..584755ea4b --- /dev/null +++ b/Windup-Rules-Development-Guide.adoc @@ -0,0 +1,87 @@ += Windup User Guide + +:toc: +:toclevels: 4 + + +== Overview + +This guide is for engineers, consultants, and others who plan to use +Windup 2.0 to migrate Java applications or other components. + + +include::What-is-Windup.adoc[tabsize=4] + +include::Features-of-Windup-2.0.adoc[tabsize=4] + +include::Windup-Processing-Overview.adoc[tabsize=4] + +include::Get-Involved.adoc[tabsize=4] + +include::Report-Issues-with-Windup.adoc[tabsize=4] + +include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] + + +== Get Started + +include::Install-Windup.adoc[tabsize=4] + +include::Execute-Windup.adoc[tabsize=4] + +include::Review-the-Report.adoc[tabsize=4] + + +== Configure Your System for Java-based Rules + +If you plan to create Java-based rule addons, you must also do the following. + +include::Install-and-Configure-Maven.adoc[tabsize=4] + +include::http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons. + +== Understand the Rule Processing + +include::Windup-Processing-Overview.adoc[tabsize=4] +include::Rules-Rule-Execution-Lifecycle.adoc[tabsize=4] +include::Rules-Rule-Story-Points.adoc[tabsize=4] + +== Create and Test Java Rule Addons + +include::Rules-Java-based-Rule-Structure.adoc[tabsize=4] +include::Rules-Basic-Rule-Execution-Flow-Patterns.adoc[tabsize=4] +include::Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc[tabsize=4] +include::Rules-Create-an-Advanced-Ruleset.adoc[tabsize=4] + +== Create and Test XML Rules + +include::Rules-Create-a-Basic-XML-Rule.adoc[tabsize=4] + +== Review the Report + +include::Review-the-Report.adoc[tabsize=4] + +== External Rule Examples + +include::Review-the-Windup-Quickstarts.adoc[tabsize=4] + +== Debugging and Troubleshooting + +include::Dev-Debugging-and-Profiling.adoc[tabsize=4] +include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] + + +== Additional Resources + +include::Review-the-Windup-Quickstarts.adoc[tabsize=4] + +include::Known-Issues.adoc[tabsize=4] + +include::Glossary.adoc[tabsize=4] + +== Appendix + +include::Dev-Windup-Architectural-Components.adoc[tabsize=4] + + + diff --git a/Windup-User-Guide.adoc b/Windup-User-Guide.adoc index ff9d493955..bc1e7c886b 100644 --- a/Windup-User-Guide.adoc +++ b/Windup-User-Guide.adoc @@ -6,15 +6,23 @@ == Overview -This guide is for engineers, consultants, or others who plan to use +This guide is for engineers, consultants, and others who plan to use Windup 2.0 to migrate Java applications or other components. + include::What-is-Windup.adoc[tabsize=4] +include::Features-of-Windup-2.0.adoc[tabsize=4] + include::Windup-Processing-Overview.adoc[tabsize=4] +include::Get-Involved.adoc[tabsize=4] + +include::Report-Issues-with-Windup.adoc[tabsize=4] + include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] + == Run Windup include::Install-Windup.adoc[tabsize=4] @@ -27,7 +35,7 @@ include::Review-the-Report.adoc[tabsize=4] include::Review-the-Windup-Quickstarts.adoc[tabsize=4] -include::Report-Issues-with-Windup.adoc[tabsize=4] +include::Known-Issues.adoc[Known Issues] include::Glossary.adoc[tabsize=4] diff --git a/WindupRulesDevelopmentGuide.html b/WindupRulesDevelopmentGuide.html new file mode 100644 index 0000000000..0cd5618bd2 --- /dev/null +++ b/WindupRulesDevelopmentGuide.html @@ -0,0 +1,3420 @@ + + + + + + + +Windup User Guide + + + + + +
+
+

Overview

+
+
+

This guide is for engineers, consultants, and others who plan to use +Windup 2.0 to migrate Java applications or other components.

+
+
+

What is Windup?

+
+

Windup Logo

+
+
+
+

JBoss Windup is a rule-based tool to simplify application migrations. Running from +a Forge environment, the tool examines EAR, WAR, and +JAR deployments (or a project source directory) and produces an HTML report detailing the inner workings of +the Java application to simplify migration efforts. It seeks to make +migrating from other containers to JBoss EAP a piece of cake.

+
+
+

Windup 2.0 vs. Windup 0.7.x

+
+

Windup 2.0 aims to deliver the same functionality as legacy Windup, however, the internal architecture and rule structure is very different and allows for the creation of much more complex rules.

+
+
+
+

How Does Windup Simplify Migration?

+
+

Windup looks for common resources and highlight technologies and known “trouble +spots” in migrating applications. The goal of Windup is to provide a +high level view into relevant technologies in use within the +application, and provide a consumable report for organizations to +estimate, document, and migrate enterprise applications to Java EE and JBoss EAP.

+
+
+

These are some of the of the areas targetted by Windup rulesets:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + +
RulesetDescription

Java Interrogator

Reads compiled Java files, determines if blacklisted classes are imported, and if so, continues to profile the resource.

JSP Interrogator

Reads JSP files, extracts the JSP imports and taglibs, and continues to +profile the resource

XML Interrogator

Reads XML files into a DOM objects and continues to profile the resource.

+
+
+

Follow Windup on Twitter!

+
+

Follow Windup on Twitter @JBossWindup for updates and more!

+
+
+
+
+

Features of Windup 2.0

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+Shared Data Model + +

Windup 2.0 creates a shared data model graph that provides the following benefits.

+
+
    +
  • +

    It enables complex rule interaction, allowing rules to pass findings to other rules.

    +
    • +
  • +

    It enables 3rd-party plug-ins to interact with other plugins, rules and reports.

    +
    • +
  • +

    The data graph organizes the findings to be searchable and queryable.

    +
    • +
+
+
+Extensibility + +

Windup 2.0 can be extended by developers, users, and 3rd-parties.

+
+
    +
  • +

    It provides a plug-in API to inject other applications into Windup.

    +
    • +
  • +

    It enables 3rd-parties to create simple POJO plug-ins that can interact with the data graph.

    +
    • +
  • +

    Means we don’t have to invent everything. Users with domain knowledge can implement their own rules.

    +
    • +
+
+
+Better Rules + +

Windup 2.0 provides more powerful and complex rules.

+
+
    +
  • +

    XML-based rules are simple to write and and easy to implement.

    +
    • +
  • +

    Java-based rule addons are based on ocpsoft rewrite and provide greater flexibility and power creating when rules.

    +
    • +
  • +

    Rules can now be nested to handle more complex situations. This means you can nest simple statements rather than use complex XPATH or REGEX expressions. +*Rules can be linked using and/or statements

    +
    • +
+
+
+Automation + +

Windup 2.0 has the ability to automate some of the migration processes.

+
+
    +
  • +

    Windup is integrated with Forge 2.0, meaning it can generate projects, libraries, and configuration files.

    +
    • +
  • +

    Rules can create Forge inputs and put them into the data graph.

    +
    • +
  • +

    During the automation phase, the data graph inputs can be processed to generate a new project.

    +
    • +
+
+
+Work Estimation + +

Estimates for the level of effort is based on the skills required and the classification of migration work needed.

+
+
    +
  • +

    Lift and Shift - The code or file is standards-based and can be ported to the new environment with no changes.

    +
    • +
  • +

    Mapped - There is a standard mapping algorithm to port the code or file to the new environment.

    +
    • +
  • +

    Custom – The code or file must be rewritten or modified to work in the new environment.

    +
    • +
+
+
+Better Reporting + +

Windup 2.0 reports are now targeted for specific audiences.

+
+
    +
  • +

    IT Management - Applications are ranked by cost of migration.

    +
    • +
  • +

    Project Management - Reports detail the type of work and estimation of effort to complete the tasks.

    +
    • +
  • +

    Developers - An Eclipse plug-in provides hints and suggested code changes within the IDE.

    +
    • +
+
+
+
+
+
+

Windup Processing Overview

+
+

Windup is a rule-based migration tool that allows you to write customized rules to analyze the APIs, technologies, and architectures used by the applications you plan to migrate. The Windup tool also executes its own core rules through all phases of the migration process.

+
+
+

The following is a high level conceptual overview of what happens within Windup when you execute the tool against your application or archive.

+
+
+

Discovery Phase

+
+

Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing 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.

+
+
+

For more information about the graph database components, see Windup Architectural Components.

+
+
+
+

Application Migration

+
+

The next step in the process is the execution of the migration rules. In this phase, the rules typically do not execute against the application input files. Instead, they execute against the graph database model. Windup rules are independent and decoupled and they communicate with each other using the graph database model. Rules query the graph database to obtain information needed to test the rule condition. They also update the data model with information based on the result of the rule execution. This allows rules to easily interact with other rules and enables the creation of very complex rules.

+
+
+

The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup’s architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the Windup Rules Development Guide.

+
+
+
+

Generate Findings Based on the Rule Execution Results

+
+

The final step in the process is to pull data from the graph database model to generate of reports and optionally generate scripts. Again, Windup uses rules to generate the final output.

+
+
+

By default, Windup generates the following reports at the end of the application migration process. The reports are located in the reports/ subdirectory of the output report path specified when you execute Windup:

+
+
+
    +
  • +

    Application Report: This report provides a summary of the total estimated effort, or story points, that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder.

    +
    • +
  • +

    RuleProvider report: This is a detailed listing of the rule providers that fired when running Windup and whether any errors occurred.

    +
    • +
  • +

    Additional reports are generated that provide detailed line-by-line migration tips for individual files.

    +
    • +
+
+
+

Windup can also generate scripts to automate migration processes based on the findings. For example, some configuration files are easily mapped and can be automatically generated as part of the migration process.

+
+
+
+
+

Get Involved

+
+

How can you help?

+
+

To help us make Windup cover most application constructs and server configurations, including yours, you can help with any of the following items. Some items require only a few minutes of your time!

+
+
+
    +
  • +

    Let us know what Windup migration rules should cover.

    +
    • +
  • +

    Provide example applications to test migration rules.

    +
    • +
  • +

    Identify application components and problem areas that may be difficult to migrate.

    +
    +
      +
    • +

      Write a short description of these problem migration areas.

      +
      • +
    • +

      Write a brief guide describing how to solve the problem migration areas.

      +
      • +
    +
    +
    • +
  • +

    Try Windup on your application. Be sure to report any issues you encounter.

    +
    • +
  • +

    Write an Windup rule to automate the migration process.

    +
    +
      +
    • +

      Create a test for the new rule.

      +
      • +
    +
    +
    • +
  • +

    You can contribute Windup rules. For details, see the Windup Rules Development Guide.

    +
    • +
  • +

    You can also contribute to the project source code. See the Windup Core Development Guide for information about how to configure your environment and set up the project.

    +
    • +
+
+
+

Any level of involvement is greatly appreciated!

+
+
+
+
+

Report Issues with Windup

+
+

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

+
+
+

Create a JIRA Account

+
+

If you do not yet have a JIRA account, create one using the following procedure.

+
+
+
    +
  1. +

    Open a browser to the following URL: https://issues.jboss.org/secure/Dashboard.jspa

    +
    2. +
  2. +

    Click the Sign Up link in the top right side of the page.

    +
    3. +
  3. +

    Enter your email address and click the Confirm address button.

    +
    4. +
  4. +

    Follow the instructions sent to your email address.

    +
    5. +
+
+
+
+

Create a JIRA Issue

+
+
    +
  1. +

    Open a browser to the following URL: https://issues.jboss.org/secure/CreateIssue!default.jspa.

    +
    +
      +
    • +

      If you have not yet logged in, click the Log In link at the top right side of the page.

      +
      • +
    • +

      Enter your credentials and click the LOGIN button.

      +
      • +
    • +

      You are then redirected back to the Create Issue page.

      +
      • +
    +
    +
    2. +
  2. +

    Choose the following options and click the Next button.

    +
    +
      +
    • +

      Project: Windup

      +
      • +
    • +

      Issue Type: Bug

      +
      • +
    +
    +
    3. +
  3. +

    On the next screen complete the following fields:

    +
    +
      +
    • +

      Summary: Enter a brief description of the problem or issue.

      +
      • +
    • +

      Environment: Provide the details of your operating system, version of Java, and any other pertinent information.

      +
      • +
    • +

      Description: Provide a detailed description of the issue. Be sure to include logs and exceptions traces.

      +
      • +
    +
    +
    4. +
  4. +

    Click the Create button to create the JIRA issue.

    +
    5. +
  5. +

    If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the Windup development team, attach it to the issue by choosing More → Attach Files. You are provided with an option to restrict visibility to JBoss employees.

    +
    6. +
+
+
+
+
+

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.0.0.VERSION folder extracted from the downloaded ZIP file.

    +
    • +
  • +

    If you build Windup from GitHub source, WINDUP_HOME refers to the windup-distribution-2.0.0-<version> folder extracted from the Windup source dist/target/windup-distribution-2.0.0-VERSION.zip file.

    +
    • +
+
+
+
+
+
+

Get Started

+
+
+

Install Windup

+
+
    +
  1. +

    Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently windup-distribution-2.0.0.Beta6.

    +
    2. +
  2. +

    Extract the ZIP file in to a directory of your choice.

    +
    3. +
+
+
+ + + + + +
+
Note
+		 +The documentation uses the replaceable value WINDUP_HOME to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see About the WINDUP_HOME Variable. +
+
+
+
+

Execute Windup

+
+

These instructions are for users who run Windup using the tool extracted from the ZIP download.

+
+
+

Prerequisites

+
+

Before you begin, you must gather the following information.

+
+
+
    +
  1. +

    Windup requires that you specify the fully qualified path of the application archive or folder you plan to migrate. This is passed using the --input argument on the command line.

    +
    2. +
  2. +

    You must also specify the fully qualified path to a folder that will contain the resulting report information. If the folder does not exist, it is created by Windup. This path is passed using the --output argument on the command line.

    +
    3. +
  3. +

    You must also provide a list of the application packages to be evaluated.

    +
    +
      +
    • +

      In most cases, you are interested only in evaluating the custom application class packages and not the standard Java EE or 3rd party packages. For example, if the MyCustomApp application uses the package com.mycustomapp, you provide that package using the --packages argument on the command line. It is not necessary to provide the standard Java EE packages, like java.util or javax.ejb.

      +
      • +
    • +

      While you can provide package names for standard Java EE 3rd party software like org.apache, it is usually best not to include them as they should not impact the migration effort.

      +
      • +
    • +

      If you omit the --packages argument, every package in the application is scanned, resulting in very slow performance. It is best to provide the argument with one or more packages.

      +
      • +
    +
    +
    4. +
+
+
+
+

Start Windup

+
+
    +
  1. +

    Open a terminal and navigate to the WINDUP_HOME/bin directory

    +
    2. +
  2. +

    Type the following command to start Windup:

    +
    +
    +
    For Linux:    WINDUP_HOME/bin $ ./windup
+For Windows:  C:\WINDUP_HOME\bin> windup
    +
    +
    +
    3. +
  3. +

    You are presented with the following prompt.

    +
    +
    +
    Using Windup at /home/username/windup-distribution-2.0.0.Beta4
+
+ _       ___           __
+| |     / (_)___  ____/ /_  ______
+| | /| / / / __ \/ __  / / / / __ \
+| |/ |/ / / / / / /_/ / /_/ / /_/ /
+|__/|__/_/_/ /_/\__,_/\__,_/ .___/
+                          /_/
+
+JBoss Windup, version [ 2.0.0.Beta4 ] - JBoss, by Red Hat, Inc. [ http://windup.jboss.org ]
+
+[windup-distribution-2.0.0.Beta4]$
    +
    +
    +
    4. +
  4. +

    The syntax to evaluate an application using the Windup tool requires that you specify the location of the input archive or source code folder, the location of a folder to contain the output reporting information, and the application packages to evaluate. To evaluate an application archive, use the following syntax:

    +
    +
    +
    windup-migrate-app --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
    +
    +
    +
    +

    To run Windup against application source code, you must add the --sourceMode true argument:

    +
    +
    +
    +
    windup-migrate-app --sourceMode true --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
    +
    +
    +
    +

    Where:

    +
    +
    +

    INPUT_ARCHIVE_OR_FOLDER is the fully qualified application archive or source path

    +
    +
    +

    OUTPUT_REPORT_DIRECTORY is the fully qualified path to the folder that will contain the the report information produced by Windup.

    +
    +
    +

    PACKAGE_1, PACKAGE_2, PACKAGE_N are the packages to be evaluated by Windup.

    +
    +
    + + + + + +
    +
    Note
    +    		 +If the OUTPUT_REPORT_DIRECTORY directory exists, it is deleted and recreated by Windup, so be careful not to specify a directory that contains important information! +
    +
    +
    +

    See Windup Command Examples below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository.

    +
    +
    5. +
  5. +

    You should see the following result upon completion of the command:

    +
    +
    +
    ***SUCCESS*** Windup execution successful!
    +
    +
    +
    6. +
  6. +

    To exit Windup, type:

    +
    +
    +
    exit
    +
    +
    +
    7. +
  7. +

    Open the OUTPUT_REPORT_DIRECTORY/index.html file in a browser to access the report. +The following subdirectories in the OUTPUT_REPORT_DIRECTORY contain the supporting information for the report:

    +
    +
    +
    OUTPUT_REPORT_DIRECTORY/
+    graph/
+    renderedGraph/
+    reports/
+    stats/
+    index.html
    +
    +
    +
    8. +
  8. +

    For details on how to evaluate the report data, see Review the Report.

    +
    9. +
+
+
+
+

Windup Help

+
+

To see the list of available parameters for the windup-migrate-app command, execute the following command in the Windup prompt:

+
+
+
+
man windup-migrate-app
+
+
+
+
+

Windup Command Examples

+
+

The following Windup command examples report against applications located in the Windup source test-files directory.

+
+
+
Source Code Example
+
+

The following command runs against the seam-booking-5.2 application source code. It evaluates all org.jboss.seam packages and creates a folder named 'seam-booking-report' in the /home/username/windup-reports/ directory to contain the reporting output.

+
+
+
+
windup-migrate-app --sourceMode true --input /home/username/windup-source/test-files/seam-booking-5.2/ --output /home/username/windup-reports/seam-booking-report --packages org.jboss.seam
+
+
+
+
+
Archive Example
+
+

The following command runs against the jee-example-app-1.0.0.ear EAR archive. It evaluates all com.acme and org.apache packages and creates a folder named 'jee-example-app-1.0.0.ear-report' in the /home/username/windup-reports/ directory to contain the reporting output.

+
+
+
+
windup-migrate-app --input /home/username/windup-source/test-files/jee-example-app-1.0.0.ear/ --output /home/username/windup-reports/jee-example-app-1.0.0.ear-report --packages com.acme org.apache
+
+
+
+
+
Windup Quickstart Examples
+
+

For more concrete examples, see the Windup quickstarts located on GitHub here: https://github.com/windup/windup-quickstarts. If you prefer, you can download the 2.0.0.Alpha1 release ZIP or TAR distribution of the quickstarts.

+
+
+

The quickstarts provide examples of Java-based and XML-based rule addons you can run and test using Windup. The README instructions provide a step-by-step guide to run the quickstart example. You can also look through the code examples and use them as a starting point for creating your own rule addons.

+
+
+
+
+
+

Review the Report

+
+

About the Report

+
+

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

+
+
+
    +
  • +

    index.html: This is the landing page for the report.

    +
    • +
  • +

    archives/: Contains the archives extracted from the application

    +
    • +
  • +

    graph/: Contains binary graph database files

    +
    • +
  • +

    reports/: This directory contains the generated HTML report files

    +
    • +
  • +

    stats/: Contains Windup performance statistics

    +
    • +
+
+
+

The examples below use the test-files/jee-example-app-1.0.0.ear located in the Windup GitHub source repository for input and specify the com.acme and org.apache package name prefixes to scan. For example:

+
+
+
+
windup-migrate-app --input /home/username/windup-source/test-files/jee-example-app-1.0.0.ear/ --output /home/username/windup-reports/jee-example-app-1.0.0.ear-report --packages com.acme org.apache
+
+
+
+
+

Open the Report

+
+

Use your favorite browser to open the index.html file located in the output report directory. You should see something like the following:

+
+
+

Report Index Page

+
+
+

Click on the link under the Name column to view the Windup application report page.

+
+
+
+

Report Sections

+
+
Application Report Page
+
+

The first section of the application report page summarizes the migration effort. It provides the total Story Points and a graphically displays the effort by technology. A Story Point is a term commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

+
+
+
    +
  • +

    The migration of the JEE Example App EAR is assigned a total of 42 story points. A pie chart shows the breakdown of story points by package.

    +
    • +
  • +

    This is followed by a section for each of the archives contained in the EAR. It provides the total of the story points assigned to the archive and lists the files contained in archive along with the warnings and story point assigned to each file.

    +
    • +
+
+
+

The following is an example of a Windup Application Report.

+
+
+

Report Summary Page

+
+
+
+
Archive Analysis Sections
+
+

Each archive summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns.

+
+
+
+
Name
+
+

The name of the file being analyzed

+
+
Technology
+
+

The type of file being analyzed. For example:

+
+
    +
  • +

    Java Source

    +
    • +
  • +

    Decompiled Java File

    +
    • +
  • +

    Manifest

    +
    • +
  • +

    Properties

    +
    • +
  • +

    EJB XML

    +
    • +
  • +

    Spring XML

    +
    • +
  • +

    Web XML

    +
    • +
  • +

    Hibernate Cfg

    +
    • +
  • +

    Hibernate Mapping

    +
    • +
+
+
+
Issues
+
+

Warnings about areas of code that need review or changes.

+
+
Estimated Story Points
+
+

Level of effort required for migrating the file.

+
+
+
+
+

The following is an example of the archive analysis summary section of a Windup Report. In this example, it’s the analysis of the WINDUP_SOURCE/test-files/jee-example-app-1.0.0.ear/jee-example-services.jar.

+
+
+

Report Archive Page

+
+
+
+
File Analysis Pages
+
+

The analysis of the jee-example-services.jar lists the files in the JAR and the warnings and story points assigned to each one. Notice the com.acme.anvil.listener.AnvilWebLifecycleListener file has 5 warnings and is assigned 7 story points. Click on the file to see the detail.

+
+
+
    +
  • +

    The Information section provides a summary of the story points and notes that the file was decompiled by Windup.

    +
    • +
  • +

    This is followed by the file source code listing. Warnings appear in the file at the point where migration is required.

    +
    • +
+
+
+

In this example, warnings appear at the import of weblogic.application.ApplicationLifecycleEvent and report that the class is proprietary to WebLogic and must be removed.

+
+
+

File Detail - Part 1

+
+
+

Later in the code, warnings appear for the creation of the InitialContext and for the object name when registering and unregistering an MBeans

+
+
+

File Detail - Part 2

+
+
+
+
+

Additional Reports

+
+

Explore the Windup OUTPUT_REPORT_DIRECTORY/reports folder to find additional reporting information.

+
+
+
Rule Provider Execution Report
+
+

The OUTPUT_REPORT_DIRECTORY/reports/ruleproviders.html page provides the list of rule providers that executed when running the Windup migration command against the application.

+
+
+

RuleProvider Report

+
+
+
+
Rule Provider Execution Report
+
+

The OUTPUT_REPORT_DIRECTORY/reports/ruleproviders.html page provides the list of rule providers that executed when running the Windup migration command against the application.

+
+
+
+
Individual File Analysis Reports
+
+

You can directly access the the file analysis report pages described above by browsing for them by name in the OUTPUT_REPORT_DIRECTORY/reports/ directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name.

+
+
+

Report Directory File List

+
+
+
+
+
+
+
+

Configure Your System for Java-based Rules

+
+
+

If you plan to create Java-based rule addons, you must also do the following.

+
+
+

Install and Configure Maven

+
+

Download and Install Maven

+
+

If you plan to use Eclipse Luna (4.4) to build Windup, you can skip this +step. This version of Eclipse embeds Maven 3.2.1 so you do not need to +install it separately. Skip to the section entitled Configure Maven to Build Windup.

+
+
+

If you plan to run Maven using the command line or plan to use Red Hat +JBoss Developer Studio 7.1.1 or an older version of Eclipse, you must +install Maven 3.1.1. or later.

+
+
+
    +
  1. +

    Go to Apache Maven Project - +Download Maven and download the latest distribution for your operating +system.

    +
    2. +
  2. +

    See the Maven documentation for information on how to download and +install Apache Maven for your operating system.

    +
    3. +
+
+
+
+

Configure the Maven Installation in Your IDE

+
+

JBoss Developer Studio 7.1.1 is built upon Eclipse Kepler (4.3), which +embeds Maven 3.0.4. If you plan to use JBoss Developer Studio 7.1.1 or +an Eclipse version earier than Eclipse Luna (4.4), you must replace the +embedded 3.0.4 version of Maven with this newer version.

+
+
+
    +
  1. +

    From the menu, choose Window -→ Preferences.

    +
    2. +
  2. +

    Expand Maven and click on Installations.

    +
    3. +
  3. +

    Uncheck Embedded (3.0.4/1.4.0.20130531-2315)

    +
    4. +
  4. +

    Click Add and navigate to your Maven install directory. Select it +and click OK.

    +
    5. +
  5. +

    Make sure the new external Maven installation is checked and click +OK to return to JBoss Developer Studio.

    +
    6. +
+
+
+

Note: If you use another IDE, refer to the product documentation to +update the Maven installation.

+
+
+
+

Configure Maven to Build Windup

+
+

Windup uses artifacts located in the +JBoss Nexus +repository. You must configure Maven to use this repository before you +build Windup.

+
+
+
    +
  1. +

    Open your ${user.home}/.m2/settings.xml file for editing.

    +
    2. +
  2. +

    Copy the following jboss-nexus-repository profile XML prior to the +ending </profiles> element.

    +
    +
    +
    <profile>
+  <id>jboss-nexus-repository</id>
+  <repositories>
+    <repository>
+      <id>jboss-nexus-repository</id>
+      <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+      <releases>
+        <enabled>true</enabled>
+      </releases>
+      <snapshots>
+        <enabled>true</enabled>
+      </snapshots>
+    </repository>
+  </repositories>
+  <pluginRepositories>
+    <pluginRepository>
+      <id>jboss-nexus-plugin-repository</id>
+      <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+      <releases>
+        <enabled>true</enabled>
+      </releases>
+      <snapshots>
+        <enabled>true</enabled>
+      </snapshots>
+    </pluginRepository>
+  </pluginRepositories>
+</profile>
    +
    +
    +
    3. +
  3. +

    Copy the following XML prior to the ending </activeprofiles> +element to make the profile active.

    +
    +
    +
        <activeProfile>jboss-nexus-repository</activeProfile>
    +
    +
    +
    4. +
+
+
+

include::http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons.

+
+
+
+
+
+
+

Understand the Rule Processing

+
+
+

Windup Processing Overview

+
+

Windup is a rule-based migration tool that allows you to write customized rules to analyze the APIs, technologies, and architectures used by the applications you plan to migrate. The Windup tool also executes its own core rules through all phases of the migration process.

+
+
+

The following is a high level conceptual overview of what happens within Windup when you execute the tool against your application or archive.

+
+
+

Discovery Phase

+
+

Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing 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.

+
+
+

For more information about the graph database components, see Windup Architectural Components.

+
+
+
+

Application Migration

+
+

The next step in the process is the execution of the migration rules. In this phase, the rules typically do not execute against the application input files. Instead, they execute against the graph database model. Windup rules are independent and decoupled and they communicate with each other using the graph database model. Rules query the graph database to obtain information needed to test the rule condition. They also update the data model with information based on the result of the rule execution. This allows rules to easily interact with other rules and enables the creation of very complex rules.

+
+
+

The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup’s architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the Windup Rules Development Guide.

+
+
+
+

Generate Findings Based on the Rule Execution Results

+
+

The final step in the process is to pull data from the graph database model to generate of reports and optionally generate scripts. Again, Windup uses rules to generate the final output.

+
+
+

By default, Windup generates the following reports at the end of the application migration process. The reports are located in the reports/ subdirectory of the output report path specified when you execute Windup:

+
+
+
    +
  • +

    Application Report: This report provides a summary of the total estimated effort, or story points, that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder.

    +
    • +
  • +

    RuleProvider report: This is a detailed listing of the rule providers that fired when running Windup and whether any errors occurred.

    +
    • +
  • +

    Additional reports are generated that provide detailed line-by-line migration tips for individual files.

    +
    • +
+
+
+

Windup can also generate scripts to automate migration processes based on the findings. For example, some configuration files are easily mapped and can be automatically generated as part of the migration process.

+
+
+
+
+

Rule Execution Lifecycle

+
+

Rule Lifecycle

+
+

Windup executes each rule in a single threaded mode. The following +sections describe the phases of rule execution and how rules may specify +that one or more other rules must be executed before or after they are +run.

+
+
+

For graphical overview of rule processing, see +this +diagram.

+
+
+
+

Rule Phases

+
+

By default, a rule runs during the MIGRATION_RULES phase. However, a +rule may require certain processing or actions to occur before the it +executes, such as the extraction of archives and scanning of java or XML +files.

+
+
+

Rule phases provide an way for rule authors to specify and control in +which phase of the rule lifecycle the rule should execute. This is done +by overriding the WindupRuleProvider.getPhase() method. The following +example specifies this rule should execute during the INITIAL_ANALYSIS +rule phase.

+
+
+
+
@Override
+public RulePhase getPhase() {
+    return RulePhase.INITIAL_ANALYSIS;
+}
+
+
+
+

The following is the list of rule phases as defined in the RulePhase +enum class. Note that there are also PRE_ processing and POST_ +processing phases for each of the following rule phases.

+
+
+
+
DISCOVERY
+
+

This phase is called during resource discovery. Static files are scanned +by their basic properties, for example, the name, extension, location, +and fully qualified Java class name. Archives are unzipped in this +phase. Typically, any rule that only puts data into the graph is +executed during this phase.

+
+
INITIAL_ANALYSIS
+
+

This phase is called to perform a basic analysis of the files content. +It extracts all method names from class files, extracts metadata, such +as the XML namespace and root element, from XML files.

+
+
COMPOSITION
+
+

This phase is called to perform high-level composition operations on the +graph. For example, it may link items found in XML files to the related +Java classes or references to server resources in Java classes.

+
+
MIGRATION_RULES
+
+

This is the default phase for all rules unless overridden. +During this phase, migration rules attach data to the graph associated +with migration. This could include: - Hints to migrators for manual +migration - Automated migration of schemas or source segments - +Blacklists to indicate vendor specific APIs.

+
+
REPORT_GENERATION
+
+

During this phase, reporting visitors produce report data in the graph +that will later be used by the report rendering phase.

+
+
REPORT_RENDERING
+
+

This is the phase that renders the report.

+
+
FINALIZE
+
+

This phase is called to clean up resources and close streams.

+
+
+
+
+

For more information about rule phases, see the RulePhase Javadoc.

+
+
+
+

Execute Before and Execute After

+
+

A rule may specify that one or more rules must be executed before it is +run. In this case, all named rules will be fired in the order specified +before executing the the current rule.

+
+
+
+
List<Class<? extends WindupRuleProvider>> executeBeforeList = new ArrayList<>();
+
+@Override
+public List<Class<? extends WindupRuleProvider>> getExecuteBefore()
+{
+   return executeBeforeList.add(RuleToFireBefore.class);
+}
+
+
+
+

A rule may also specify that one or more rules must be executed after it +is run. In this case, all named rules will be fired in the order +specified after executing the the current rule.

+
+
+
+
List<Class<? extends WindupRuleProvider>> executeAfterList = new ArrayList<>();
+
+@Override
+public List<Class<? extends WindupRuleProvider>> getExecuteAfter()
+{
+    return executeAfterList.add(RuleToFireAfter.class);
+}
+
+
+
+
+
+

Rule Story Points

+
+

What are Story Points?

+
+

Story points are an abstract metric used in Scrum methodology to estimate the level of effort for various tasks. They are based on a modified Fibonacci sequence. In a similar manner, 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.

+
+
+
+

How to Estimate Story Points in a Rule

+
+

TODO: TBD.

+
+
+

This could contain relative examples like:

+
+
+
    +
  • +

    Pure copy’n’paste - when we know for sure it will need no migration: 0

    +
    • +
  • +

    When we don’t know if it will need a migration: Could depend on number of unknown imports, size +of the file, …​

    +
    • +
  • +

    Changing parameter name, or value units: 2.

    +
    • +
  • +

    Porting one web page (or similar concept) from one web framework to +the other: Could depend on complexity, e.g. number of components. E.g. +20 per component.

    +
    • +
  • +

    Porting MyBatis to JPA: 20 per query.

    +
    • +
+
+
+
+
+
+
+

Create and Test Java Rule Addons

+
+
+

Java-based Rule Structure

+
+

TODO: +* Add a how-to for compound rules, nested rules, rules over multiple sources, negative queries (not matched by anything). +Points] WINDUP-255

+
+
+

Windup Rule Provider

+
+

Windup rules are based on OCPsoft Rewrite, an open source routing and URL rewriting solution for Servlets, Java Web Frameworks, and Java EE. The rewrite framework allows you to create rule providers and rules in an easy to read format.

+
+
+

Windup rule add-ons must extend the WindupRuleProvider class.

+
+
+
    +
  • +

    If the rule should run in a phase other than the default MIGRATION_PHASE, you must implement the getPhase() method and specify in which Windup lifecycle phase the rule should be executed. For more information about rule phases, see xref:./Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle].

    +
    • +
  • +

    Rules are added using the getConfiguration(GraphContext context) method. This method is inherited from the OCPsoft Rewrite interface org.ocpsoft.rewrite.config.ConfigurationProvider. Rules are discussed in more detail later.

    +
    • +
  • +

    If other rules must execute after or before the rules in this provider, you must provide the list of WindupRuleProvider classes using the getExecuteAfter() or getExecuteAfter() methods.

    +
    • +
+
+
+

The following is an example of a simple Java-based rule add-on.

+
+
+
+
public class ExampleRuleProvider extends WindupRuleProvider
+{
+    @Override public RulePhase getPhase(){
+        return RulePhase.DISCOVERY;
+    }
+
+    // @formatter:off
+    @Override
+    public Configuration getConfiguration(GraphContext context)
+    {
+        return ConfigurationBuilder.begin()
+        .addRule()
+        .when(
+            // Some implementation of GraphCondition.
+            Query.find(...)....
+        )
+       .perform(
+            ...
+       );
+    }
+    // @formatter:on
+    // (@formatter:off/on prevents Eclipse from formatting the rules.)
+}
+
+
+
+
+

Add Rule Code Structure

+
+

Like most rule-based frameworks, Windup rules consist of the following:

+
+
+
    +
  • +

    Condition: This is the when(condition) that determines if the rule should execute.

    +
    • +
  • +

    Operation: This defines what to perform() if the condition is met.

    +
    • +
+
+
+

Rules consist of the when part, the perform, the otherwise part, +and some others, all of which are optional.

+
+
+
when()
+
+

In the .when() part, the rule typically queries the graph, using the +Query API. Results of the query are put on variables stack +(Variables), many times indirectly through the querying API.

+
+
+

Other way to fill a when part is subclassing the GraphCondition. +Actually, Query also implements it, and is only a convenient way to +create a condition.

+
+
+

Last noticable but important feature is the ability to use +Gremlin queries. See +Gremlin docs for reference manual.

+
+
+
+
perform()
+
+

In the .perform() part, the rule typically scans the items of interest +(Java files, XML files, querying services, …​), processes them, and +writes the findings into the graph.

+
+
+

For that, various operations are available. These are subclasses of +GraphOperation. You can also implement your own. See +Rules-Operations[Rules Operations] for more info. Again, there are +several convenient implementations for constructs like iteration +(Iteration).

+
+
+
Iteration
+
+
+
.perform(
+    Iteration.over(XmlMetaFacetModel.class, "xmlModels").as("xml")
+    .when(...)
+    .perform(
+        new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml"){
+            public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel xmlFacetModel)
+            {
+            }
+        })
+    .otherwise(
+        new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml"){
+            public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel payload)
+                { ... }
+        })
+    .endIteration()
+
+
+
+
+
Nested iterations
+
+

TODO

+
+
+
+
otherwise
+
+

Windup rules inherit the rule constructs from OCP Rewrite. For example, +.otherwise() Gives you a chance to perform something in case the +conditions in .when() return false (e.g. they do not match anything). +For more information, see OCP Rewrite web.

+
+
+
+
+
Metadata
+
+

Rules can specify metadata. Currently, the only appearing in some rules, +and not actually used, is RuleMetadata.CATEGORY.

+
+
+
+
.withMetadata(RuleMetadata.CATEGORY, "Basic")
+
+
+
+

.withMetadata() is basically putting key/value to a +Map<Object, Object>.

+
+
+
+
+

Available utilities

+
+

For a list of what key services and constructs can be used in the rule, +see Available Rules Utilities.

+
+
+
+
+

Basic Rule Execution Flow Patterns

+
+

SGILDA: TODO - Need some links to github to the respective example files.

+
+
+

operation(); - single operation

+
+

When no iteration or condition is needed.

+
+
+

Example: [CopyJavaConfigToGraphRuleProvider](rules-java/src/main/java/org/jboss/windup/rules/apps/java/config/CopyJavaConfigToGraphRuleProvider.java)

+
+
+
+
return ConfigurationBuilder.begin()
+    .addRule()
+    .perform(new GraphOperation(){
+        @Override
+        public void perform(GraphRewrite event, EvaluationContext context){
+            ...
+        }
+    });
+
+
+
+
+

if( …​ ){ operation(); } - single conditional operation

+
+
+
return ConfigurationBuilder.begin()
+    .addRule()
+    .when( ... )
+    .perform(new GraphOperation(){
+        @Override
+        public void perform(GraphRewrite event, EvaluationContext context){
+            ...
+        }
+    });
+
+
+
+
+

for( FooModel.class ){ …​ } - Single iteration

+
+

For simple iterations, IteratingRuleProvider can be used, which makes the perform a bit less verbose:

+
+
+
+
public class ComputeArchivesSHA512 extends IteratingRuleProvider<ArchiveModel>
+{
+    public ConditionBuilder when() {
+        return Query.find(ArchiveModel.class);
+    }
+
+    // @formatter:off
+    public void perform( GraphRewrite event, EvaluationContext context, ArchiveModel archive ){
+        try( InputStream is = archive.asInputStream() ){
+            String hash = DigestUtils.sha512Hex(is);
+            archive.asVertex().setProperty(KEY_SHA512, hash);
+        }
+        catch( IOException e ){
+            throw new WindupException("Failed to read archive: " + archive.getFilePath() +
+                "\n    Due to: " + e.getMessage(), e);
+        }
+    }
+    // @formatter:on
+
+    @Override public String toStringPerform() { return this.getClass().getSimpleName(); }
+}
+
+
+
+
+

if( …​ ){ for( …​ ) } - conditional iteration

+
+
+
return ConfigurationBuilder.begin()
+    .addRule()
+    .when(
+        new GraphCondition(){ ... }
+    ).perform(
+        Iteration.over(ArchiveModel.class)
+            .perform( ... )
+    )
+
+
+
+
+

for( …​ ){ if( …​ ){ …​ } } - iteration with a condition

+
+
+
return ConfigurationBuilder.begin()
+.addRule()
+    .when(
+        // Stores all ArchiveModel's into variables stack, under that type.
+        Query.find(ArchiveModel.class)
+    ).perform(
+        Iteration.over(ArchiveModel.class) // Picks up ArchiveModel's from the varstack.
+            .when(new AbstractIterationFilter<ArchiveModel>(){
+                @Override
+                public boolean evaluate(GraphRewrite event, EvaluationContext context, ArchiveModel payload)
+                {
+                    return payload.getProjectModel() == null;
+                }
+                @Override
+                public String toString()
+                {
+                    return "ProjectModel == null";
+                }
+            })
+            .perform( ... )
+
+
+
+
+

for( …​ ){ for( …​ ) { …​ } } - nested iterations

+
+
+
+
+
+
+
+
+

Create a Basic Java-based Rule Add-on

+
+

You can create a rule using Java or XML. This topic describes how to create a rule add-on using Java.

+
+
+

Prerequisites

+
+ +
+
+ + + + + +
+
Note
+		 +Working examples of Java-based rules can be found in the Windup quickstarts GitHub repository located here: https://github.com/windup/windup-quickstarts +
+
+
+
+

Create a Rule Add-on

+
+
Create a Maven Project
+
+

Create a new Maven Java Project. These instructions will refer to the project folder location with the replaceable variable 'RULE_PROJECT_HOME'. Modify the project pom.xml file as follows

+
+
+
    +
  1. +

    Add the following properties:

    +
    +
    +
    <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <maven.compiler.source>1.7</maven.compiler.source>
+    <maven.compiler.target>1.7</maven.compiler.target>
+    <version.windup>2.0.0.Beta3</version.windup>
+    <version.forge>2.12.1.Final</version.forge>
+</properties>
    +
    +
    +
    2. +
  2. +

    Add a dependency management section for the Windup BOM.

    +
    +
    +
    <dependencyManagement>
+    <dependencies>
+        <!-- Windup BOM -->
+        <dependency>
+            <groupId>org.jboss.windup</groupId>
+            <artifactId>windup-bom</artifactId>
+            <version>${version.windup}</version>
+            <type>pom</type>
+               <scope>import</scope>
+         </dependency>
+    </dependencies>
+</dependencyManagement>
    +
    +
    +
    3. +
  3. +

    Add a <dependencies> section to include Windup, rulesets, and test dependencies required by your rule add-on. Windup is a Forge/Furnace based application and has a modular design, so the dependencies will vary depending on the Windup APIs used by the rule. For more information on Windup dependencies, see Windup Dependencies.

    +
    +

    The following are examples of some dependencies you may need for your rule add-on.

    +
    +
    +
    +
    <!-- Windup API dependencies -->
+<dependency>
+    <groupId>org.jboss.windup.graph</groupId>
+    <artifactId>windup-graph</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.windup.config</groupId>
+    <artifactId>windup-config</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.windup.ext</groupId>
+    <artifactId>windup-config-groovy</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.windup.utils</groupId>
+    <artifactId>utils</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.windup.reporting</groupId>
+    <artifactId>windup-reporting</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+
+<!-- Dependencies on other rulesets -->
+<dependency>
+    <groupId>org.jboss.windup.rules.apps</groupId>
+    <artifactId>rules-java</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.forge.furnace.container</groupId>
+    <artifactId>cdi-api</artifactId>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.forge.furnace.container</groupId>
+    <artifactId>cdi</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>provided</scope>
+</dependency>
+
+<!-- Test dependencies -->
+<dependency>
+    <groupId>org.jboss.forge.furnace.test</groupId>
+    <artifactId>furnace-test-harness</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.jboss.forge.furnace.test</groupId>
+    <artifactId>arquillian-furnace-classpath</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>junit</groupId>
+    <artifactId>junit</artifactId>
+    <version>4.11</version>
+    <type>jar</type>
+</dependency>
+
+<dependency>
+    <groupId>org.jboss.windup.exec</groupId>
+    <artifactId>windup-exec</artifactId>
+    <classifier>forge-addon</classifier>
+    <scope>test</scope>
+</dependency>
    +
    +
    +
    4. +
  4. +

    Add the <plugins> section to make it a Forge add-on.

    +
    +
    +
    <plugins>
+    <!-- The following plugins make this artifact a Forge add-on. -->
+    <plugin>
+        <groupId>org.jboss.forge.furnace</groupId>
+        <artifactId>furnace-maven-plugin</artifactId>
+        <version>${version.furnace}</version>
+        <executions>
+            <execution>
+                <id>generate-dot</id>
+                <phase>prepare-package</phase>
+                <goals> <goal>generate-dot</goal> </goals>
+                <configuration> <attach>true</attach> </configuration>
+            </execution>
+        </executions>
+    </plugin>
+    <plugin>
+        <artifactId>maven-jar-plugin</artifactId>
+        <executions>
+            <execution>
+                <id>create-forge-addon</id>
+                <phase>package</phase>
+                <goals> <goal>jar</goal> </goals>
+                <configuration>
+                    <classifier>forge-addon</classifier>
+                </configuration>
+            </execution>
+        </executions>
+    </plugin>
+</plugins>
    +
    +
    +
    5. +
+
+
+
+
Create the Java RuleProvider
+
+
    +
  1. +

    Within your Maven project, create a Java class that extends the WindupRuleProvider class. It is suggested that you end the name of the class with RuleProvider. For example:

    +
    +
    +
    public class MyCustomRuleProvider extends WindupRuleProvider
+{
+}
    +
    +
    +
    2. +
  2. +

    If the rule provider must run in a phase other than the default MIGRATION_RULES phase, override the phase using the getPhase() method. For example, you may want the rule provider to perform a task during the initial DISCOVERY phase, for example, to ignore files with a specific name or extension.

    +
    +
    +
        @Override
+    public RulePhase getPhase() {
+        return RulePhase.DISCOVERY;
+    }
    +
    +
    +
    +

    For more information about rule phases, see Rules Execution Lifecycles.

    +
    +
    3. +
  3. +

    To control the order in which the rule is executed, implement the getExecuteBefore() or getExecuteAfter() method.

    +
    +
    +
    List<Class<? extends WindupRuleProvider>> executeBeforeList = new ArrayList<>();
+
+@Override
+public List<Class<? extends WindupRuleProvider>> getExecuteBefore()
+{
+   return executeBeforeList.add(RuleToFireBefore.class);
+}
    +
    +
    +
    +
    +
    List<Class<? extends WindupRuleProvider>> executeAfterList = new ArrayList<>();
+
+@Override
+public List<Class<? extends WindupRuleProvider>> getExecuteAfter()
+{
+    return executeAfterList.add(RuleToFireAfter.class);
+}
    +
    +
    +
    4. +
  4. +

    Finally, add the rule or rules to the rule provider.

    +
    +
      +
    • +

      High-level Conditions and Operations

      +
      +

      The following is a specific high-level rule which uses high-level conditions (JavaClass) and operations (Classification). See the documentation of those conditions and operations for the details.

      +
      +
      +
      +
      @Override
+public Configuration getConfiguration(GraphContext context)
+{
+    return ConfigurationBuilder.begin()
+        .addRule()
+        .when(
+            JavaClass.references("weblogic.servlet.annotation.WLServlet").at(TypeReferenceLocation.ANNOTATION)
+        )
+        .perform(
+            Classification.as("WebLogic @WLServlet")
+               .with(Link.to("Java EE 6 @WebServlet", "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/index.html"))
+               .withEffort(0)
+               .and(Hint.withText("Migrate to Java EE 6 @WebServlet.").withEffort(8))
+        );
+}
      +
      +
      +
      +

      For more examples of rule providers, see the +BaseConfig.java +rule.

      +
      +
      • +
    • +

      Low-level Conditions and Operations

      +
      +

      As you can see, the conditions and operations above are Java-specific. +They come with the Java Basic ruleset. The list of existing rulesets +will be part of the project documentation. Each ruleset will be +accompanied with a documentation for its `Condition`s and `Operation`s +(and also `Model`s).

      +
      +
      +

      These high-level elements provided by rulesets may cover majority of +cases, but not all. Then, you will need to dive into the mid-level +Windup building elements.

      +
      +
      • +
    • +

      Mid-level Conditions and Operations

      +
      • +
    +
    +
    5. +
+
+
+
+
+

Install the Java-based Rule Add-on

+
+

The easiest and fastest way to build the rule add-on, install it into the local Maven repository, and install it into Windup as a rule add-on is to use the Windup addon-build-and-install command.

+
+
+
    +
  • +

    If you have not started Windup, follow the instructions to Execute Windup.

    +
    • +
  • +

    At the Windup console prompt, enter the addon-build-and-install command:

    +
    +
    +
    addon-build-and-install --projectRoot RULE_PROJECT_HOME
    +
    +
    +
    • +
  • +

    You should see the following result.

    +
    +
    +
    ***SUCCESS*** Addon MyCustomRuleProvider:::2.0.0.VERSION was installed successfully.
    +
    +
    +
    • +
+
+
+
+

Test the Java-based Rule Add-on

+
+

Test the Java-based rule add-on against your application file by running the windup-migrate-app command in the Windup console prompt.

+
+
+

The command uses this syntax:

+
+
+
+
windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
+
+
+
+

You should see the following result:

+
+
+
+
***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html
+
+
+
+

For more information and examples of how to run Windup, see: Execute Windup

+
+
+
+

Review the Output Report

+
+
    +
  1. +

    Open OUTPUT_REPORT_DIRECTORY /index.html file in a browser.

    +
    2. +
  2. +

    You are presented with an Overview page containing the application profiles.

    +
    3. +
  3. +

    Click on the application link to review the detail page. Check to be sure the warning messages, links, and story points match what you expect to see.

    +
    4. +
+
+
+

TBD.

+
+
+ +
+
+

DRAFT

+
+
+
    +
  1. +

    Create the Forge add-on

    +
    + +
    +
    2. +
  2. +

    Add the dependencies you need

    +
    3. +
  3. +

    Create the service with your functionality, if needed

    +
    4. +
  4. +

    Create the rules +(Add a the LINK)

    +
    5. +
  5. +

    Add the information to the report +(Add a the LINK)

    +
    6. +
+
+
+
+
+
+
+

Create and Test XML Rules

+
+
+

Create a Basic XML Rule

+
+

You can create a rule addon using Java or a rule using XML or Groovy. This topic describes how to create a rule using XML.

+
+
+

Prerequisites

+
+ +
+
+ + + + + +
+
Note
+		 +Working examples of XML-based rules can be found in the Windup quickstarts GitHub repository located here: https://github.com/windup/windup-quickstarts +
+
+
+
+

Create a Rule

+
+

The following is an example of an XML rule.

+
+
+
+
<?xml version="1.0"?>
+<ruleset xmlns="http://windup.jboss.org/v1/xml"
+  id="customruleprovider">
+  <!-- This defaults to MIGRATION_RULES -->
+  <phase>
+    DISCOVERY
+  </phase>
+  <rules>
+    <rule>
+      <when>
+        <javaclass references="javax.servlet.http.HttpServletRequest">
+          <location>METHOD_PARAMETER</location>
+        </javaclass>
+      </when>
+      <perform>
+        <hint>
+      <message>Message from XML Rule</message>
+          <link href="http://example.com" description="Description from XML Hint Link" />
+        </hint>
+        <log message="test log message"/>
+      </perform>
+      <otherwise>
+        <!--  -->
+      </otherwise>
+    </rule>
+    <rule>
+      <when>
+        <xmlfile xpath="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']">
+          <namespace prefix="w" uri="http://java.sun.com/xml/ns/javaee"/>
+        </xmlfile>
+      </when>
+      <perform>
+        <hint>
+      <message>Container Auth</message>
+        </hint>
+        <xslt description="Example XSLT Conversion" extension="-converted-example.xml"
+                 xsltFile="/exampleconversion.xsl"/>
+        <log message="test log message"/>
+      </perform>
+      <otherwise>
+        <!--  -->
+      </otherwise>
+    </rule>
+  </rules>
+</ruleset>
+
+
+
+
Create the XML Rule
+
+

Note: Windup only analyzes XML files with names ending in .windup.xml. Be sure to name XML-based rules using this naming convention!

+
+
+

The XML rule consists of the following level elements:

+
+
+
    +
  • +

    <ruleset>: This element defines this as a Windup rule.

    +
    • +
  • +

    <phase>: This element specifies when the ruleset should execute. See Rule Phases in the Rule Execution Lifecyle for more information.

    +
    • +
  • +

    <rules>: element contains the individual rules.

    +
    +
      +
    • +

      <rule>: This element is a child of the rules element. One or more rules can be defined for a ruleset. Each rule contains the following elements.

      +
      +
        +
      • +

        <when>: This element defines the condition to match on.

        +
        +
          +
        • +

          <javaclass references="CLASS_NAME">

          +
          +
            +
          • +

            <location>: The location where the reference was found in a Java source file. See the Enum TypeReferenceLocation Javadoc for valid values.

            +
            • +
          +
          +
          • +
        +
        +
        • +
      • +

        <perform>: This element is invoked when the condition is met.

        +
        +
          +
        • +

          <hint>: This child element of perform is used to create a hint

          +
          +
            +
          • +

            <message>:

            +
            • +
          • +

            <link>:

            +
            • +
          +
          +
          • +
        • +

          <xslt>: This specifies how to transform the the specified XML file

          +
          • +
        • +

          <log>: This child element of perform is used to log a message. It takes the attribute message to define the text message.

          +
          • +
        +
        +
        • +
      • +

        The <otherwise> element is invoked when the condition is not met.

        +
        • +
      +
      +
      • +
    +
    +
    • +
+
+
+
+
+

Add the Rule to Windup

+
+

A Windup rule is installed simply by copying the rule to the appropriate Windup folder. Windup scans for rules in the following locations:

+
+
+
+
WINDUP_HOME/rules/
+
+

This is the Windup folder where you run the Windup executable. See About the WINDUP_HOME Variable for details.

+
+
${user.home}/.windup/rules/
+
+

This folder is created by Windup the first time you execute Windup.

+
+
+
For Linux or Mac:   ~/.windup/rules/
+For Windows: "\Documents and Settings\USER_NAME\.windup\rules\"  -or-  "\Users\USER_NAME\.windup\rules\"
+
+
+
+
+
+
+
+

Test the XML Rule

+
+ + + + + +
+
Note
+		 +If you have not started Windup, follow the instructions to Execute Windup. +
+
+
+

Test the XML rule against your application file by running the windup-migrate-app command in the Windup console prompt.

+
+
+

The command uses this syntax:

+
+
+
+
windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
+
+
+
+

You should see the following result:

+
+
+
+
***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html
+
+
+
+

For more information and examples of how to run Windup, see: xref:-Execute-Windup[Execute Windup]

+
+
+
+
+
+
+

Review the Report

+
+
+

Review the Report

+
+

About the Report

+
+

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

+
+
+
    +
  • +

    index.html: This is the landing page for the report.

    +
    • +
  • +

    archives/: Contains the archives extracted from the application

    +
    • +
  • +

    graph/: Contains binary graph database files

    +
    • +
  • +

    reports/: This directory contains the generated HTML report files

    +
    • +
  • +

    stats/: Contains Windup performance statistics

    +
    • +
+
+
+

The examples below use the test-files/jee-example-app-1.0.0.ear located in the Windup GitHub source repository for input and specify the com.acme and org.apache package name prefixes to scan. For example:

+
+
+
+
windup-migrate-app --input /home/username/windup-source/test-files/jee-example-app-1.0.0.ear/ --output /home/username/windup-reports/jee-example-app-1.0.0.ear-report --packages com.acme org.apache
+
+
+
+
+

Open the Report

+
+

Use your favorite browser to open the index.html file located in the output report directory. You should see something like the following:

+
+
+

Report Index Page

+
+
+

Click on the link under the Name column to view the Windup application report page.

+
+
+
+

Report Sections

+
+
Application Report Page
+
+

The first section of the application report page summarizes the migration effort. It provides the total Story Points and a graphically displays the effort by technology. A Story Point is a term commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

+
+
+
    +
  • +

    The migration of the JEE Example App EAR is assigned a total of 42 story points. A pie chart shows the breakdown of story points by package.

    +
    • +
  • +

    This is followed by a section for each of the archives contained in the EAR. It provides the total of the story points assigned to the archive and lists the files contained in archive along with the warnings and story point assigned to each file.

    +
    • +
+
+
+

The following is an example of a Windup Application Report.

+
+
+

Report Summary Page

+
+
+
+
Archive Analysis Sections
+
+

Each archive summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns.

+
+
+
+
Name
+
+

The name of the file being analyzed

+
+
Technology
+
+

The type of file being analyzed. For example:

+
+
    +
  • +

    Java Source

    +
    • +
  • +

    Decompiled Java File

    +
    • +
  • +

    Manifest

    +
    • +
  • +

    Properties

    +
    • +
  • +

    EJB XML

    +
    • +
  • +

    Spring XML

    +
    • +
  • +

    Web XML

    +
    • +
  • +

    Hibernate Cfg

    +
    • +
  • +

    Hibernate Mapping

    +
    • +
+
+
+
Issues
+
+

Warnings about areas of code that need review or changes.

+
+
Estimated Story Points
+
+

Level of effort required for migrating the file.

+
+
+
+
+

The following is an example of the archive analysis summary section of a Windup Report. In this example, it’s the analysis of the WINDUP_SOURCE/test-files/jee-example-app-1.0.0.ear/jee-example-services.jar.

+
+
+

Report Archive Page

+
+
+
+
File Analysis Pages
+
+

The analysis of the jee-example-services.jar lists the files in the JAR and the warnings and story points assigned to each one. Notice the com.acme.anvil.listener.AnvilWebLifecycleListener file has 5 warnings and is assigned 7 story points. Click on the file to see the detail.

+
+
+
    +
  • +

    The Information section provides a summary of the story points and notes that the file was decompiled by Windup.

    +
    • +
  • +

    This is followed by the file source code listing. Warnings appear in the file at the point where migration is required.

    +
    • +
+
+
+

In this example, warnings appear at the import of weblogic.application.ApplicationLifecycleEvent and report that the class is proprietary to WebLogic and must be removed.

+
+
+

File Detail - Part 1

+
+
+

Later in the code, warnings appear for the creation of the InitialContext and for the object name when registering and unregistering an MBeans

+
+
+

File Detail - Part 2

+
+
+
+
+

Additional Reports

+
+

Explore the Windup OUTPUT_REPORT_DIRECTORY/reports folder to find additional reporting information.

+
+
+
Rule Provider Execution Report
+
+

The OUTPUT_REPORT_DIRECTORY/reports/ruleproviders.html page provides the list of rule providers that executed when running the Windup migration command against the application.

+
+
+

RuleProvider Report

+
+
+
+
Rule Provider Execution Report
+
+

The OUTPUT_REPORT_DIRECTORY/reports/ruleproviders.html page provides the list of rule providers that executed when running the Windup migration command against the application.

+
+
+
+
Individual File Analysis Reports
+
+

You can directly access the the file analysis report pages described above by browsing for them by name in the OUTPUT_REPORT_DIRECTORY/reports/ directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name.

+
+
+

Report Directory File List

+
+
+
+
+
+
+
+

External Rule Examples

+
+
+

Review the Windup Quickstarts

+
+

The Windup quickstarts provide working examples of how to create custom Java-based rule addons and XML rules. You can use them as a starting point for creating your own custom rules. The quickstarts are available on GitHub here: https://github.com/windup/windup-quickstarts

+
+
+

You can fork and clone the project to have access to regular updates or you can download a ZIP file of the latest version.

+
+
+

Download the Latest ZIP

+
+

To download the latest quickstart ZIP file, browse to: https://github.com/windup/windup-quickstarts/releases

+
+
+

Click on the most recent release to download the ZIP to your local file system.

+
+
+
+

Fork and Clone the GitHub Project

+
+

If you don’t have the GitHub client (git), download it from: http://git-scm.com/

+
+
+
    +
  1. +

    Click the Fork link on the Windup 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. +
  2. +

    Clone your Windup quickstart repository to your local file system:

    +
    +
    +
    git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
    +
    +
    +
    3. +
  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/
    +
    +
    +
    4. +
  4. +

    If you want to be able to retrieve the lates 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
    +
    +
    +
    5. +
  5. +

    To get the latest files from the upstream repository.

    +
    +
    +
    git reset --hard upstream/master
    +
    +
    +
    6. +
+
+
+
+
+
+
+

Debugging and Troubleshooting

+
+
+

Debugging and Profiling

+
+

Debug the Windup Distribution Runtime

+
+

You can debug the Windup distribution using one of the following approaches.

+
+
+
    +
  1. +

    Pass the --debug argument on the command line when you execute Windup.

    +
    +
    +
    For Linux:    WINDUP_HOME/bin $ ./windup --debug
+For Windows:  C:\WINDUP_HOME\bin> windup --debug
    +
    +
    +
    2. +
  2. +

    Configure the FORGE_OPTS for debugging.

    +
    +
    +
    export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"
    +
    +
    +
    3. +
+
+
+
+

Debug a Test Using NetBeans

+
+

Click the Debug Test File button, or choose Menu → Debug → Debug Test File.

+
+
+
+

Profile a Test Using NetBeans

+
+
    +
  1. +

    Profiling requires a lot of memory, so be sure to increase the NetBeans memory settings.

    +
    +
      +
    • +

      Open the NETBEANS_HOME/etc/netbeans.conf file

      +
      • +
    • +

      Find the line with netbeans_default_options=

      +
      • +
    • +

      Add the following option

      +
      +
      +
      -J-Xmx5200m -J-XX:MaxPermSize=1024m
      +
      +
      +
      • +
    • +

      Restart NetBeans.

      +
      • +
    +
    +
    2. +
  2. +

    Click Menu > Profile > Profile Test File.

    +
    3. +
  3. +

    In the resulting dialog, enter the following.

    +
    +
    +
    exec.args=-Djboss.modules.system.pkgs=org.netbeans
    +
    +
    +
    4. +
+
+
+
+

Profile Forge Runtime Using YourKit

+
+
    +
  1. +

    Download and unzip YourKit. Be sure to get the trial license.

    +
    2. +
  2. +

    Configure the FORGE_OPTS for Yourkit:

    +
    +
    +
    export YOURKIT_HOME=/home/ondra/sw/prog/YourKit-b14092
+export FORGE_OPTS="-Djboss.modules.system.pkgs=com.yourkit -agentpath:$YOURKIT_HOME/bin/linux-x86-64/libyjpagent.so=sampling,onexit=snapshot,delay=0"
    +
    +
    +
    3. +
  3. +

    Run forge. For details, see Profiling +Forge, but skip the first 2 points that direct you to copy the YourKit module and JAR into the Forge installation. Forge 2 already contains the YourKit module and JAR>.

    +
    4. +
  4. +

    Run windup-analyze-app.

    +
    +
    +
    forge -e windup-migrate-app
    +
    +
    +
    5. +
+
+
+
+
+

Troubleshoot Windup Issues

+
+

Logging

+
+

Logging is currently broken and will not be fixed any time soon.

+
+
+

See Known Issues and WINDUP-73 for the current status.

+
+
+
+

Debugging Exceptions

+
+

Exceptions in Surefire reports are broken due to the way Forge wraps +exceptions and the way Surefire handles them. You need to +debug or rewrap exceptions using TestUtil.rewrap(ex).

+
+
+

See Known Issues and WINDUP-197 for the current status..

+
+
+
+

Classloading Problems

+
+

Configuring dependencies in a Forge-based project can be a little tricky. +See Dependencies for some hints.

+
+
+
+
+
+
+

Additional Resources

+
+
+

Review the Windup Quickstarts

+
+

The Windup quickstarts provide working examples of how to create custom Java-based rule addons and XML rules. You can use them as a starting point for creating your own custom rules. The quickstarts are available on GitHub here: https://github.com/windup/windup-quickstarts

+
+
+

You can fork and clone the project to have access to regular updates or you can download a ZIP file of the latest version.

+
+
+

Download the Latest ZIP

+
+

To download the latest quickstart ZIP file, browse to: https://github.com/windup/windup-quickstarts/releases

+
+
+

Click on the most recent release to download the ZIP to your local file system.

+
+
+
+

Fork and Clone the GitHub Project

+
+

If you don’t have the GitHub client (git), download it from: http://git-scm.com/

+
+
+
    +
  1. +

    Click the Fork link on the Windup 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. +
  2. +

    Clone your Windup quickstart repository to your local file system:

    +
    +
    +
    git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
    +
    +
    +
    3. +
  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/
    +
    +
    +
    4. +
  4. +

    If you want to be able to retrieve the lates 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
    +
    +
    +
    5. +
  5. +

    To get the latest files from the upstream repository.

    +
    +
    +
    git reset --hard upstream/master
    +
    +
    +
    6. +
+
+
+
+
+

Known Issues

+
+

The following is a list of currently known issues.

+
+
+
    +
  • +

    WINDUP-73

    +
    +
      +
    • +

      If you do not see expected log messages, resort to System.out.println() for logging.

      +
      • +
    • +

      You may see too much logging, especially from Forge. This is to be expected.

      +
      • +
    +
    +
    • +
  • +

    WINDUP-197

    +
    +
      +
    • +

      Exceptions in Surefire reports are broken due to the way Forge wraps exceptions and the way Surefire handles them.

      +
      • +
    • +

      You need to debug or rewrap exceptions using TestUtil.rewrap(ex).

      +
      • +
    +
    +
    • +
+
+
+
+

Glossary of Terms Used in Windup

+
+

Rules Terms

+
+
+
Rule
+
+

A piece of code that performs a single unit of work during the migration process. Depending on the complexity of the rule, it may or may not include configuration data. Extensive configuration information may be externalized into external configuration, for example, a custom XML file. The following is an example of a Java-based rule added to the JDKConfig RuleProvider class.

+
+
+
+
+
+
.addRule()
+    .when(JavaClass.references("java.lang.ClassLoader$").at(TypeReferenceLocation.TYPE))
+    .perform(Classification.as("Java Classloader, must be migrated.")
+    .with(Link.to("Red Hat Customer Portal: How to get resources via the ClassLoader in a JavaEE application in JBoss EAP",  "https://access.redhat.com/knowledge/solutions/239033"))
+     .withEffort(1))
+
+
+
+
+
RuleProvider
+
+

A class that implements one or more rules using the .addRule() method. The following are examples of legacy Java RulesProviders that are defined in rules-java-ee ruleset.

+
+
    +
  • +

    EjbConfig

    +
    • +
  • +

    JDKConfig

    +
    • +
  • +

    SeamToCDI

    +
    • +
+
+
+
Ruleset
+
+

A ruleset is a group of one or more RuleProviders that targets a specific area of migration, for example, Spring → Java EE 6 or WebLogic → JBoss EAP. A ruleset is packaged as a JAR and contains additional information needed for the migration, such as operations, conditions, report templates, static files, metadata, and relationships to other rulesets. The following Windup projects are rulesets.

+
+
    +
  • +

    rules-java-ee

    +
    • +
  • +

    rules-xml

    +
    • +
+
+
+
Rules Metadata
+
+

Information about whether a particular ruleset applies to a given situation. The metadata can include the source and target platform and frameworks.

+
+
Rules Pipeline
+
+

A collection of rules that feed information into the knowledge graph.

+
+
+
+
+
+

Reporting Terms

+
+
+
Lift and Shift (Level of effort)
+
+

The code or file is standards-based and can be ported to the new environment with no changes.

+
+
Mapped (Level of effort)
+
+

There is a standard mapping algorithm to port the code or file to the new environment.

+
+
Custom (Level of effort)
+
+

The code or file must be rewritten or modified to work in the new environment.

+
+
Story Point
+
+

A term commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

+
+
+
+
+
+
+
+
+

Appendix

+
+
+

Windup Architectural Components

+
+

The following open source software, tools, and APIs are used within +Windup to analyze and provide migration information. If you plan to +contribute source code to the core Windup 2.0 project, you should be +familiar with them.

+
+
+

Forge

+
+

Forge is an open source, extendable, rapid application development tool +for creating Java EE applications using Maven. For more information +about Forge 2, see: JBoss Forge.

+
+
+
+

Forge Furnace

+
+

Forge Furnace is a modular runtime container behind Forge that provides +the ability to run Forge addons in an embedded application. For more +information about Forge Furnace, see: +Run Forge Embedded.

+
+
+
+

TinkerPop

+
+

TinkerPop is an open source graph computing framework. For more +information, see: TinkerPop.

+
+
+
+

Titan

+
+

Titan is a scalable graph database optimized for storing and querying graphs. +For more information, see: Titan Distributed Graph Database and Titan Beginner’s Guide.

+
+
+
+

Frames

+
+

Frames represents graph data in the form of interrelated Java Objects or +a collection of annotated Java Interfaces. For more information, see: +TinkerPop Frames.

+
+
+

Windup includes several Frames extensions, which are documented here: +Frames Extensions.

+
+
+
+

Gremlin

+
+

Gremlin is a graph traversal language that allows you to query, analyze, +and manipulate property graphs that implement the Blueprints property +graph data model. For more information, see: +TinkerPop Gremlin Wiki.

+
+
+
+

Blueprints

+
+

Blueprints is an industry standard API used to access graph databases. +For more information about Blueprints, see: +TinkerPop Blueprints Wiki.

+
+
+
+

Pipes

+
+

Pipes is a dataflow framework used to process graph data. It for the +transformation of data from input to output. For more information, see: +Tinkerpop Pipes Wiki.

+
+
+
+

Rexster

+
+

Rexster is a graph server that exposes any Blueprints graph through HTTP/REST and a binary protocol called RexPro. Rexster makes extensive use of Blueprints, Pipes, and Gremlin. For more information, see: +TinkerPop Rexster Wiki.

+
+
+
+

OCPsoft Rewrite

+
+

OCPsoft Rewrite is an open source routing and URL rewriting solution for +Servlets, Java Web Frameworks, and Java EE. For more information about +Ocpsoft Rewrite, see: OCPsoft Rewrite.

+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/WindupUserGuide.html b/WindupUserGuide.html index 03a37609bb..fac03690c9 100644 --- a/WindupUserGuide.html +++ b/WindupUserGuide.html @@ -417,23 +417,26 @@

Windup User Guide

  • Overview
  • Run Windup
  • Additional Resources
  • Appendix @@ -449,11 +452,11 @@

    Windup User Guide

    Overview

    -

    This guide is for engineers, consultants, or others who plan to use +

    This guide is for engineers, consultants, and others who plan to use Windup 2.0 to migrate Java applications or other components.

    -

    What is Windup?

    +

    What is Windup?

    Windup Logo

    @@ -519,7 +522,141 @@

    Follow Windup on Twitter!

    -

    Windup Processing Overview

    +

    Features of Windup 2.0

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Shared Data Model + +

    Windup 2.0 creates a shared data model graph that provides the following benefits.

    +
    +
      +
    • +

      It enables complex rule interaction, allowing rules to pass findings to other rules.

      +
      • +
    • +

      It enables 3rd-party plug-ins to interact with other plugins, rules and reports.

      +
      • +
    • +

      The data graph organizes the findings to be searchable and queryable.

      +
      • +
    +
    +
    +Extensibility + +

    Windup 2.0 can be extended by developers, users, and 3rd-parties.

    +
    +
      +
    • +

      It provides a plug-in API to inject other applications into Windup.

      +
      • +
    • +

      It enables 3rd-parties to create simple POJO plug-ins that can interact with the data graph.

      +
      • +
    • +

      Means we don’t have to invent everything. Users with domain knowledge can implement their own rules.

      +
      • +
    +
    +
    +Better Rules + +

    Windup 2.0 provides more powerful and complex rules.

    +
    +
      +
    • +

      XML-based rules are simple to write and and easy to implement.

      +
      • +
    • +

      Java-based rule addons are based on ocpsoft rewrite and provide greater flexibility and power creating when rules.

      +
      • +
    • +

      Rules can now be nested to handle more complex situations. This means you can nest simple statements rather than use complex XPATH or REGEX expressions. +*Rules can be linked using and/or statements

      +
      • +
    +
    +
    +Automation + +

    Windup 2.0 has the ability to automate some of the migration processes.

    +
    +
      +
    • +

      Windup is integrated with Forge 2.0, meaning it can generate projects, libraries, and configuration files.

      +
      • +
    • +

      Rules can create Forge inputs and put them into the data graph.

      +
      • +
    • +

      During the automation phase, the data graph inputs can be processed to generate a new project.

      +
      • +
    +
    +
    +Work Estimation + +

    Estimates for the level of effort is based on the skills required and the classification of migration work needed.

    +
    +
      +
    • +

      Lift and Shift - The code or file is standards-based and can be ported to the new environment with no changes.

      +
      • +
    • +

      Mapped - There is a standard mapping algorithm to port the code or file to the new environment.

      +
      • +
    • +

      Custom – The code or file must be rewritten or modified to work in the new environment.

      +
      • +
    +
    +
    +Better Reporting + +

    Windup 2.0 reports are now targeted for specific audiences.

    +
    +
      +
    • +

      IT Management - Applications are ranked by cost of migration.

      +
      • +
    • +

      Project Management - Reports detail the type of work and estimation of effort to complete the tasks.

      +
      • +
    • +

      Developers - An Eclipse plug-in provides hints and suggested code changes within the IDE.

      +
      • +
    +
    +
    +
    +
    +
    +

    Windup Processing Overview

    Windup is a rule-based migration tool that allows you to write customized rules to analyze the APIs, technologies, and architectures used by the applications you plan to migrate. The Windup tool also executes its own core rules through all phases of the migration process.

    @@ -541,7 +678,7 @@

    Application Migration

    The next step in the process is the execution of the migration rules. In this phase, the rules typically do not execute against the application input files. Instead, they execute against the graph database model. Windup rules are independent and decoupled and they communicate with each other using the graph database model. Rules query the graph database to obtain information needed to test the rule condition. They also update the data model with information based on the result of the rule execution. This allows rules to easily interact with other rules and enables the creation of very complex rules.

    -

    The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup’s architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the Windup Rules Development Guide.

    +

    The Windup distribution contains a large number of migration rules, but in some cases, you may need to create additional custom rules for your specific implementation. Windup’s architecture allows you to create Java-based rule addons or XML rules and add easily add them to Windup. Custom rule creation is covered in the Windup Rules Development Guide.

    @@ -555,7 +692,7 @@

    Generate Finding
    • -

      Application Report: This report provides a summary of the total estimated effort, or story points, that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder.

      +

      Application Report: This report provides a summary of the total estimated effort, or story points, that are required for the migration. It also provides a detailed list of issues and suggested changes, broken down by archive or folder.

    • RuleProvider report: This is a detailed listing of the rule providers that fired when running Windup and whether any errors occurred.

      @@ -571,17 +708,157 @@

      Generate Finding

    -

    About the WINDUP_HOME Variable

    +

    Get Involved

    +
    +

    How can you help?

    +
    +

    To help us make Windup cover most application constructs and server configurations, including yours, you can help with any of the following items. Some items require only a few minutes of your time!

    +
    +
    +
      +
    • +

      Let us know what Windup migration rules should cover.

      +
      • +
    • +

      Provide example applications to test migration rules.

      +
      • +
    • +

      Identify application components and problem areas that may be difficult to migrate.

      +
      +
        +
      • +

        Write a short description of these problem migration areas.

        +
        • +
      • +

        Write a brief guide describing how to solve the problem migration areas.

        +
        • +
      +
      +
      • +
    • +

      Try Windup on your application. Be sure to report any issues you encounter.

      +
      • +
    • +

      Write an Windup rule to automate the migration process.

      +
      +
        +
      • +

        Create a test for the new rule.

        +
        • +
      +
      +
      • +
    • +

      You can contribute Windup rules. For details, see the Windup Rules Development Guide.

      +
      • +
    • +

      You can also contribute to the project source code. See the Windup Core Development Guide for information about how to configure your environment and set up the project.

      +
      • +
    +
    +
    +

    Any level of involvement is greatly appreciated!

    +
    +
    +
    +
    +

    Report Issues with Windup

    +
    +

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

    +
    +
    +

    Create a JIRA Account

    +
    +

    If you do not yet have a JIRA account, create one using the following procedure.

    +
    +
    +
      +
    1. +

      Open a browser to the following URL: https://issues.jboss.org/secure/Dashboard.jspa

      +
      2. +
    2. +

      Click the Sign Up link in the top right side of the page.

      +
      3. +
    3. +

      Enter your email address and click the Confirm address button.

      +
      4. +
    4. +

      Follow the instructions sent to your email address.

      +
      5. +
    +
    +
    +
    +

    Create a JIRA Issue

    +
    +
      +
    1. +

      Open a browser to the following URL: https://issues.jboss.org/secure/CreateIssue!default.jspa.

      +
      +
        +
      • +

        If you have not yet logged in, click the Log In link at the top right side of the page.

        +
        • +
      • +

        Enter your credentials and click the LOGIN button.

        +
        • +
      • +

        You are then redirected back to the Create Issue page.

        +
        • +
      +
      +
      2. +
    2. +

      Choose the following options and click the Next button.

      +
      +
        +
      • +

        Project: Windup

        +
        • +
      • +

        Issue Type: Bug

        +
        • +
      +
      +
      3. +
    3. +

      On the next screen complete the following fields:

      +
      +
        +
      • +

        Summary: Enter a brief description of the problem or issue.

        +
        • +
      • +

        Environment: Provide the details of your operating system, version of Java, and any other pertinent information.

        +
        • +
      • +

        Description: Provide a detailed description of the issue. Be sure to include logs and exceptions traces.

        +
        • +
      +
      +
      4. +
    4. +

      Click the Create button to create the JIRA issue.

      +
      5. +
    5. +

      If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the Windup development team, attach it to the issue by choosing More → Attach Files. You are provided with an option to restrict visibility to JBoss employees.

      +
      6. +
    +
    +
    +
    +
    +

    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.0.0.VERSION folder extracted from the downloaded ZIP file.

      +

      If you download and install the latest distribution of Windup from the JBoss Nexus repository, WINDUP_HOME refers to the windup-distribution-2.0.0.VERSION folder extracted from the downloaded ZIP file.

    • -

      If you build Windup from source, WINDUP_HOME refers to the windup-distribution-2.0.0-<version> folder extracted from the Windup source dist/target/windup-distribution-2.0.0-VERSION.zip file.

      +

      If you build Windup from GitHub source, WINDUP_HOME refers to the windup-distribution-2.0.0-<version> folder extracted from the Windup source dist/target/windup-distribution-2.0.0-VERSION.zip file.

    @@ -592,11 +869,11 @@

    About the WINDUP_HOME Variable

    Run Windup

    -

    Install Windup

    +

    Install Windup

    1. -

      Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently windup-distribution-2.0.0.Beta5.

      +

      Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently windup-distribution-2.0.0.Beta6.

    2. Extract the ZIP file in to a directory of your choice.

      @@ -610,14 +887,14 @@

      Install Windup

      Note
      -The documentation uses the replaceable value WINDUP_HOME to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see About the WINDUP_HOME Variable. +The documentation uses the replaceable value WINDUP_HOME to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see About the WINDUP_HOME Variable.
    -

    Execute Windup

    +

    Execute Windup

    These instructions are for users who run Windup using the tool extracted from the ZIP download.

    @@ -652,21 +929,9 @@

    Prerequisites

    • -
    - - - - - -
    -
    Important
    -    		 -There is currently a bug in the parser that does not resolve the tilde (~) in a path name correctly. For now, you must fully spell out the complete path name when it is passed as an argument in the Windup command line. For example, use /home/username/path-to-file rather than ~/path-to-file. For details, see https://issues.jboss.org/browse/WINDUP-305. -
    -
    -

    Run Windup

    +

    Start Windup

    1. @@ -740,7 +1005,7 @@

      Run Windup

    -

    See [windup-command-examples] below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository.

    +

    See Windup Command Examples below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository.

  • @@ -774,7 +1039,7 @@

    Run Windup

  • -

    For details on how to evaluate the report data, see Review the Report.

    +

    For details on how to evaluate the report data, see Review the Report.

    • @@ -829,7 +1094,7 @@
    Windup Quickstart Examples
    -

    Review the Report

    +

    Review the Report

    About the Report

    @@ -876,7 +1141,7 @@

    Open the Report

    -

    Review the Report

    +

    Report Sections

    Application Report Page
    @@ -898,8 +1163,9 @@
    Application Report Page

    Report Summary Page

    -
    -
    Archive Analysis Sections
    +
    +
    +
    Archive Analysis Sections

    Each archive summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns.

    @@ -961,7 +1227,6 @@
    Archive Analysis Sections

    Report Archive Page

    -
    File Analysis Pages
    @@ -1014,7 +1279,7 @@
    Rule Provider Execution Report
    Individual File Analysis Reports
    -

    You can directly access the the file analysis report pages described above by browsing for them by name in the OUTPUT_REPORT_DIRECTORY/reports/ directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name.

    +

    You can directly access the the file analysis report pages described above by browsing for them by name in the OUTPUT_REPORT_DIRECTORY/reports/ directory. Because the same common file names can exist in multiple archives, for example "manifest.mf" or "web.xml", Windup adds a unique numeric suffix to each report file name.

    Report Directory File List

    @@ -1028,7 +1293,7 @@
    Individual File Analysis Reports

    Additional Resources

    -

    Review the Windup Quickstarts

    +

    Review the Windup Quickstarts

    The Windup quickstarts provide working examples of how to create custom Java-based rule addons and XML rules. You can use them as a starting point for creating your own custom rules. The quickstarts are available on GitHub here: https://github.com/windup/windup-quickstarts

    @@ -1091,93 +1356,43 @@

    Fork and Clone the GitHub Project

    -

    Report Issues with Windup

    +

    Known Issues

    -

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

    -
    -
    -

    Create a JIRA Account

    -
    -

    If you do not yet have a JIRA account, create one using the following procedure.

    +

    The following is a list of currently known issues.

    -
    -
      -
    1. -

      Open a browser to the following URL: https://issues.jboss.org/secure/Dashboard.jspa

      -
      2. -
    2. -

      Click the Sign Up link in the top right side of the page.

      -
      3. -
    3. -

      Enter your email address and click the Confirm address button.

      -
      4. -
    4. -

      Follow the instructions sent to your email address.

      -
      5. -
    -
    -
    -
    -

    Create a JIRA Issue

    -
    -
      -
    1. -

      Open a browser to the following URL: https://issues.jboss.org/secure/CreateIssue!default.jspa.

      • -

        If you have not yet logged in, click the Log In link at the top right side of the page.

        -
        • -
      • -

        Enter your credentials and click the LOGIN button.

        -
        • -
      • -

        You are then redirected back to the Create Issue page.

        -
        • -
      -
      -
      2. -
    2. -

      Choose the following options and click the Next button.

      +

      WINDUP-73

      • -

        Project: Windup

        +

        If you do not see expected log messages, resort to System.out.println() for logging.

      • -

        Issue Type: Bug

        +

        You may see too much logging, especially from Forge. This is to be expected.

    3. -

      On the next screen complete the following fields:

      +

      WINDUP-197

      • -

        Summary: Enter a brief description of the problem or issue.

        +

        Exceptions in Surefire reports are broken due to the way Forge wraps exceptions and the way Surefire handles them.

      • -

        Environment: Provide the details of your operating system, version of Java, and any other pertinent information.

        -
        • -
      • -

        Description: Provide a detailed description of the issue. Be sure to include logs and exceptions traces.

        +

        You need to debug or rewrap exceptions using TestUtil.rewrap(ex).

      4. -
    4. -

      Click the Create button to create the JIRA issue.

      -
      5. -
    5. -

      If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the Windup development team, attach it to the issue by choosing More → Attach Files. You are provided with an option to restrict visibility to JBoss employees.

      -
      6. -
    -
    +
-

Glossary of Terms Used in Windup

+

Glossary of Terms Used in Windup

Rules Terms

@@ -1283,7 +1498,7 @@

Forge

Forge is an open source, extendable, rapid application development tool for creating Java EE applications using Maven. For more information -about Forge, see: JBoss Forge.

+about Forge 2, see: JBoss Forge.

@@ -1318,7 +1533,7 @@

Frames

Windup includes several Frames extensions, which are documented here: -Frames Extensions.

+Frames Extensions.

@@ -1367,7 +1582,7 @@

OCPsoft Rewrite