From 53733261b484bc3cd23b68e33795d8d54e5f5de9 Mon Sep 17 00:00:00 2001 From: Sande Gilda Date: Mon, 30 Mar 2015 11:21:54 -0400 Subject: [PATCH] Update docs for 2.2.0 release --- README.adoc | 40 +- docs/Core-Development-Guide.asciidoc | 16 +- docs/Dev-Build-Windup-from-Source.adoc | 6 +- docs/Dev-Classloading-Notes.adoc | 46 +- docs/Dev-Concepts-and-Philosophy.adoc | 6 +- .../Dev-Connect-to-the-Graph-via-Rexster.adoc | 2 +- docs/Dev-Decompiling.adoc | 6 +- docs/Dev-Dependencies.adoc | 14 +- ...evelopment-Guidelines-and-Conventions.adoc | 2 +- docs/Dev-Git-Rebasing.adoc | 62 +- ...Port-WindRide-Functionality-to-Windup.adoc | 8 +- docs/Dev-Variables-Stack.adoc | 15 +- docs/Dev-Windup-Release-Process.adoc | 14 + docs/Execute-Windup.adoc | 46 +- docs/Features-of-Windup-2.0.adoc | 2 +- docs/Get-Involved.adoc | 2 + docs/Install-Windup.adoc | 9 + docs/Install-and-Configure-Maven.adoc | 2 +- docs/Review-the-Windup-Quickstarts.adoc | 2 +- docs/Rule-Metadata.adoc | 5 +- docs/Rules-Available-Rules-Utilities.adoc | 2 +- ...es-Basic-Rule-Execution-Flow-Patterns.adoc | 2 +- ...Create-a-Basic-Java-based-Rule-Add-on.adoc | 2 +- docs/Rules-Create-a-Basic-XML-Rule.adoc | 4 +- docs/Rules-Creating-Rule-Operations.adoc | 1 + docs/Rules-Development-Guide.asciidoc | 10 +- ...etween-XML-based-and-Java-based-Rules.adoc | 158 + docs/Rules-Java-based-Rule-Structure.adoc | 9 +- docs/Rules-Ops-Reporting-TypeReference.adoc | 1 + docs/Rules-Rule-Execution-Lifecycle.adoc | 12 +- docs/Rules-Rule-Story-Points.adoc | 12 +- docs/Rules-Rulesets.adoc | 1 + ...Rules-Test-a-Basic-XML-Rule-in-Windup.adoc | 2 +- .../Rules-XML-Rule-Perform-Action-Syntax.adoc | 2 +- .../Rules-XML-Rule-When-Condition-Syntax.adoc | 9 +- docs/Ruleset-Java-Basic-Ruleset.adoc | 1 + ...Java-Classifications-and-Inline-Hints.adoc | 5 +- docs/Ruleset-XML.adoc | 5 +- docs/Windup-Architectural-Components.adoc | 2 +- docs/Windup-Core-Development-Guide.adoc | 100 +- docs/Windup-Rules-Development-Guide.adoc | 47 +- docs/Windup-User-Guide.adoc | 22 +- html/WindupCoreDevelopmentGuide.html | 4899 +++++++++++------ html/WindupRulesDevelopmentGuide.html | 1528 +++-- html/WindupUserGuide.html | 943 ++-- ...de.sh => pageLinksCoreDevelopmentGuide.sh} | 0 scripts/pageLinksRulesDevelopmentGuide.sh | 72 + ...inksUserGuide.sh => pageLinksUserGuide.sh} | 7 + scripts/windupDocUpdate.sh | 11 +- 49 files changed, 4996 insertions(+), 3178 deletions(-) create mode 100644 docs/Dev-Windup-Release-Process.adoc create mode 100644 docs/Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc rename scripts/{pagelinksCoreDevelopmentGuide.sh => pageLinksCoreDevelopmentGuide.sh} (100%) create mode 100755 scripts/pageLinksRulesDevelopmentGuide.sh rename scripts/{pagelinksUserGuide.sh => pageLinksUserGuide.sh} (82%) diff --git a/README.adoc b/README.adoc index f003eeb307..fc2ed182e3 100644 --- a/README.adoc +++ b/README.adoc @@ -6,17 +6,33 @@ Windup project documentation is created collaboratively on the Windup project Wi This `windup-documentation` repository takes documentation from that site, makes minor modifications, and publishes the pages in single HTML page book format. This repository will contain the source for the official documentation when the Windup 2.0 ships. -== Procedure to Copy and Modify the Wiki Documentation +== Procedure to Update the Documentation With the Latest Windup Wiki -Run the scripts/windupDocUpdate.sh script to copy and modify the files. +Check out a branch to work in. -. Copies the `.asciidoc` files to the `docs/` directory and renames them with the `.adoc` extension. -. Replaces the `xref:` macros to other pages with `xref:` macros. -. Uses AsciiDoctor to create the guides in the `html/` directory. +Run the `scripts/windupDocUpdate.sh` script to copy the latest pages from the Wiki documentation and modify the files so they can be included in the Windup documentation guides. + +* Copies the latest images and stylesheets. +* Copies the `.asciidoc` files to the `docs/` directory and renames them with the `.adoc` extension. +* Replaces the `link:` macros to other pages with `xref:` macros since they are now included in the same book. +* Uses AsciiDoctor to generate HTML versions the guides in the `html/` directory. + +You must manually verify the following. + +* Search the Guide to find pages that link to other pages and make sure the linked to pages are part of the book. +* Make sure every referenced page and section has a header matching the reference. ++ +---- +[[section-header]] +=== Section Header +--- + +Use Git to add files that have changed and issue the pull to merge them. == Procedure to Publish the Guides -* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. +* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. +In the following instructions, be sure to replace WINDUP_RELEASE with the actual release number. + ---- git clone https://github.com/windup/windup.git @@ -72,6 +88,18 @@ git commit -m "Update message..." git push upstream gh-pages ---- +* Update the symlink so the "latest" release points to the newly published documentation. ++ +---- +unlink latest +ln -s WINDUP_RELEASE latest +git add latest +git commit -m 'Replace symlink for latest to point to WINDUP_RELEASE' +git push origin HEAD +git push upstream gh-pages +firefox http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html +---- + == Access the Guides View the documentation at the following URLs. diff --git a/docs/Core-Development-Guide.asciidoc b/docs/Core-Development-Guide.asciidoc index 66f327741e..4a23ca1197 100644 --- a/docs/Core-Development-Guide.asciidoc +++ b/docs/Core-Development-Guide.asciidoc @@ -20,7 +20,6 @@ repository, IRC, Mailing lists, ... * link:Dev-Build-Windup-from-Source[Build Windup from Source] * link:Dev-Execute-Windup-Built-from-Source[Execute Windup Built from Source] * link:Review-the-Report[Review the Report] -* link:Glossary[Glossary of Terms] ==== Developer Contributing Information @@ -29,11 +28,15 @@ repository, IRC, Mailing lists, ... ==== Understand the Windup Architecture and Structure +* link:Windup-Processing-Overview[Windup Processing Overview] * link:Windup-Architectural-Components[Windup Architectural Components] * link:Dev-Windup-Project-Structure[Windup Project Structure] ==== Rules and Rulesets +* link:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecyle] +* link:Rules-Rule-Story-Points[Rule Story Points] + ==== Debugging and Troubleshooting @@ -53,6 +56,7 @@ repository, IRC, Mailing lists, ... * link:Dev-Variables-Stack[Variables Stack] * link:Dev-Port-WindRide-Functionality-to-Windup[Port WindRide Functionality to Windup] * link:Dev-Git-Rebasing[Git Rebasing] +* link:Dev-Releasing-Windup[Releasing Windup] ==== Rules topics @@ -74,9 +78,7 @@ repository, IRC, Mailing lists, ... ** link:Rules-Ops-Reporting-Hint[Rules Ops: Reporting: Hint] ** link:Rules-Ops-Reporting-TypeReference[Rules Ops: Reporting: TypeReference] ** link:Rules-Ops-Xml-XsltTrasformation[Rules Ops: XML: XSLT Transformation] -* link:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecyle] * link:Rules-Java-based-Rule-Structure[Java-Based Rule Structure] -* link:Rules-Rule-Story-Points[Rule Story Points] ==== Wiki and Product Documentation @@ -85,3 +87,11 @@ repository, IRC, Mailing lists, ... * link:Dev-Create-Windup-JavaDoc[Create Windup JavaDoc] * link:Dev-Windup-Documentation-Process[Windup Documentation Process] +==== Additional Resources + +* link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] +* link:Known-Issues[Known Issues] +* link:Glossary[Glossary] + +* link:Glossary[Glossary of Terms] + diff --git a/docs/Dev-Build-Windup-from-Source.adoc b/docs/Dev-Build-Windup-from-Source.adoc index 8c21b0db0f..4b18be9426 100644 --- a/docs/Dev-Build-Windup-from-Source.adoc +++ b/docs/Dev-Build-Windup-from-Source.adoc @@ -119,8 +119,10 @@ Unzip the `dist/target/windup-distribution-2.0.0-SNAPSHOT-offline.zip` file into ==== Quick Build Review for Experienced Windup Developers --------------- -git clone git@github.com:windup/windup.git Windup -cd Windup +git clone git@github.com:windup/windup.git windup +## Or if you haven't set up github account: +#git clone https://github.com/windup/windup.git +cd windup mvn clean install -DskipTests rm -rf /tmp/windup-zip/ /tmp/windup/ unzip -q dist/target/windup-distribution-*-offline.zip -d /tmp/windup-zip diff --git a/docs/Dev-Classloading-Notes.adoc b/docs/Dev-Classloading-Notes.adoc index 5d331c3aa1..f17f6caeab 100644 --- a/docs/Dev-Classloading-Notes.adoc +++ b/docs/Dev-Classloading-Notes.adoc @@ -1,4 +1,3 @@ -[[Dev-Classloading-Notes]] === Classloading Notes .DRAFT @@ -7,6 +6,23 @@ _Page contains temporary notes, to be edited._ This covers the specific situations when the Windup core developer needs to look up certain runtime classes. Does not relate to rules authoring. +==== Forge add-ons transitive dependencies + +Let A depend on B depend on C. +Depending on scope of C in B's POM: +------- +provided +------- + +`provided` will NOT export C, so A depending on B won't see C's classes. +Only `compile` scope is exported. +`compile` will export C, so A depending on B will also see C's classes. + +* `provided` == import +* `compile` == import & export +* `optional` == optional, not installed automatically +* `runtime` == export only + ==== Finding classes [source,java] @@ -23,12 +39,11 @@ or -------- ==== Instantiating -If you want something from the current addon, you need to @Inject its ServiceRegistry and get services from that. +If you want something from the current add-on, you can simply @Inject the type you wish to use. Alternately you can @Inject an Imported instance, or also @Inject the AddonRegistry itself. -==== Which classloader is used? Always the one of the current code? +==== Which ClassLoader is used? Always the one of the current code? -Depends, if you are in a Furnace Service, then yes, it will use the -current code's addon's classloader. +Depends, if you are in a Furnace Service, then yes, it will use the current code's add-on ClassLoader. ==== Reading annotations from classes @@ -40,13 +55,13 @@ Supposedly, Furnace proxies should also be able to handle such call: Rules annotation1 = ((FurnaceProxy) proxy).getOriginalClass().getAnnotation(Rules.class); -TODO: Find out how exactly this is done. +TO_DO: Find out how exactly this is done. ==== How do I know if I am in a Furnace service? Every furnace service is wrapped in a proxy. If it came from another -addon (not your current addon) and was not instantiated with new Blah(), +add-on (not your current add-on) and was not instantiated with new Blah(), you are in a furnace service. So if it was `@Inject`ed or retrieved via `addonRegistry.getServices(...)` @@ -56,7 +71,7 @@ you are in a furnace service. So if it was `@Inject`ed or retrieved via (16:33:41) LincolnBaxter: ozizka: using a shared Resource.open() APi will actually be sort of a no-op, and just introduce another layer, since you generally need to be able to specify a classloader anyway (16:33:53) jsightler: lincolnthree: Well... (16:34:09) LincolnBaxter: ozizka: unless I'm misunderstanding the point of this -(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's addon +(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's add-on (16:34:18) LincolnBaxter: ozizka: ah wait (16:34:27) LincolnBaxter: ozizka: the *caller*'s classloader (16:34:35) LincolnBaxter: ozizka: not the CL of the current operation @@ -67,18 +82,18 @@ you are in a furnace service. So if it was `@Inject`ed or retrieved via (16:35:25) ozizka-FN: which classloader is used? (16:35:33) ozizka-FN: Always the one of the current code? (16:35:44) ozizka-FN: Implicitly -(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's addon's classloader +(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's add-on's classloader (16:36:00) ozizka-FN: Ah (16:36:11) ozizka-FN: How do I know if I am in a Furnace service? (16:36:14) LincolnBaxter: ozizka: because every furnace service is wrapped in a proxy -(16:36:31) LincolnBaxter: ozizka: basically if it came from another addon (not your current addon), you are in a furnace service +(16:36:31) LincolnBaxter: ozizka: basically if it came from another add-on (not your current add-on), you are in a furnace service (16:36:43) LincolnBaxter: ozizka: and if you didn't instantiate with new Blah() (16:37:00) LincolnBaxter: ozizka: so if it was @Injected or retrieved via addonRegistry.getServices(...) -(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling addon? just curious +(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling add-on? just curious (16:37:54) ozizka-FN: So here we would use TCCL right? LincolnBaxter lincolnthree (16:38:28) ozizka-FN: lincolnthree: To load it's resources -(16:38:31) ozizka-FN: from other addon +(16:38:31) ozizka-FN: from other add-on (16:38:32) ozizka-FN: . (16:38:35) ozizka-FN: Or is there other way? (16:38:42) LincolnBaxter: ozizka: that's a vague statement ;) @@ -93,12 +108,12 @@ LincolnBaxter lincolnthree ==== Resources loading ``` -(16:48:30) ozizka-FN: lincolnthree: Just a note - the potential collisions caused by addon's CL span is not considered as a risk? +(16:48:30) ozizka-FN: lincolnthree: Just a note - the potential collisions caused by add-on's CL span is not considered as a risk? (16:49:25) ozizka-FN: I mean, it could load the file from it's deps. (16:49:36) ozizka-FN: * file = resource (16:49:50) LincolnBaxter: ozizka1: so the way it works is actually very controlled -(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another addon -(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the addon dependency in the POM +(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another add-on +(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the add-on dependency in the POM (16:53:26) ozizka-FN: Q: Unwrapping proxies caused the code in invoke() not actually being called? (16:53:32) ozizka-FN: Since the method calls were not intercepted? @@ -123,4 +138,3 @@ https://github.com/forge/furnace/blob/master/proxy/src/main/java/org/jboss/forge ==== What classloader is used by Freemarker to load resources? `org.jboss.windup.reporting.freemarker.FurnaceFreeMarkerTemplateLoader` - diff --git a/docs/Dev-Concepts-and-Philosophy.adoc b/docs/Dev-Concepts-and-Philosophy.adoc index 1963bd5043..983ff16b2f 100644 --- a/docs/Dev-Concepts-and-Philosophy.adoc +++ b/docs/Dev-Concepts-and-Philosophy.adoc @@ -1,7 +1,7 @@ [[Dev-Concepts-and-Philosophy]] === Concepts & Philosophy -_TODO - OZIZKA: Can this topic be marked obsolete and be replaced by this one: xref:Windup-Processing-Overview[Windup Processing Overview] ?_ +TO_DO: - OZIZKA: Can this topic be marked obsolete and be replaced by this one: xref:Windup-Processing-Overview[Windup Processing Overview] ?_ Windup is a rule-based tool that allows users to write customized rules based on the needs, constructs, and custom APIs used in their @@ -33,8 +33,8 @@ See also the list of xref:Rules-Windup-Models[Windup Models]. . Finding all `@Entity`s which use `org.hibernate` extensions. + -TODO +TO_DO . Finding _MyBatis_ DAOs and classes using them. + -TODO \ No newline at end of file +TO_DO \ No newline at end of file diff --git a/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc b/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc index 0bf67f8a3d..413237b115 100644 --- a/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc +++ b/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc @@ -1,7 +1,7 @@ [[Dev-Connect-to-the-Graph-via-Rexster]] === Connect to the Graph via Rexster -There is a specific addon for running Rexster along your graph with +There is a specific add-on for running Rexster along your graph with groupId *org.jboss.windup.rexster* and *artifactId* Rexster. ==== Running Rexster Within Your Test diff --git a/docs/Dev-Decompiling.adoc b/docs/Dev-Decompiling.adoc index f17b46a694..9757bacc5f 100644 --- a/docs/Dev-Decompiling.adoc +++ b/docs/Dev-Decompiling.adoc @@ -20,10 +20,10 @@ * `windup.ProcyonConfiguration` contains `procyon.DecompilerSettings`. * `procyon.DecompilerSettings` contains `outputDir` (the others are not much important). -TODO: Make that a parameter to method call? +TO_DO: Make that a parameter to method call? ===== TypeReference -TODO: Check how we get info about Java files; perhaps cache the `TypeReference` results - if worth it? +TO_DO: Check how we get info about Java files; perhaps cache the `TypeReference` results - if worth it? ===== ITypeLoader @@ -34,4 +34,4 @@ TODO: Check how we get info about Java files; perhaps cache the `TypeReference` * `InputTypeLoader` * `CompoundTypeLoader` - 2 typeloaders, queried in succession -TODO: Create a simple `FileSystemTypeLoader`. \ No newline at end of file +TO_DO: Create a simple `FileSystemTypeLoader`. \ No newline at end of file diff --git a/docs/Dev-Dependencies.adoc b/docs/Dev-Dependencies.adoc index 7dcd08e12d..717328fd39 100644 --- a/docs/Dev-Dependencies.adoc +++ b/docs/Dev-Dependencies.adoc @@ -12,11 +12,11 @@ discussion._ The following is the typical structure of Maven `add-on` modules. ------------------------------------------- -myaddon-parent -+--- myaddon - jar, classifier: forge-addon -+--- myaddon-api - jar -+--- myaddon-impl - jar -+--- myaddon-tests - jar +my-add-on-parent ++--- my-add-on - jar, classifier: forge-addon ++--- my-add-on-api - jar ++--- my-add-on-impl - jar ++--- my-add-on-tests - jar ------------------------------------------- The `add-on` POM file can declare dependencies on other forge-addons. @@ -89,14 +89,14 @@ dependencies, and these are treated as normal. [NOTE] ========================== -Add-on depends on API , scope `compile` > Addon +Add-on depends on API , scope `compile` > Add-on depends on Impl , scope `compile` with `true` - prevents exporting this dependency to consumers of the add-on. ========================== ==== Test dependencies -For test dependencies on add-ons: Any addon/sub-part requiring an addon +For test dependencies on add-ons: Any add-on/sub-part requiring an add-on for testing purposes should use `test`. [source,xml] diff --git a/docs/Dev-Development-Guidelines-and-Conventions.adoc b/docs/Dev-Development-Guidelines-and-Conventions.adoc index fb87c5d228..254709100f 100644 --- a/docs/Dev-Development-Guidelines-and-Conventions.adoc +++ b/docs/Dev-Development-Guidelines-and-Conventions.adoc @@ -53,5 +53,5 @@ http://plugins.jetbrains.com/plugin/?id=6546[http://plugins.jetbrains.com/plugin The following are not really accurate at this time. This is still TBD! * Lowercase with dashes. Start with `windup-`. -* Ruleset addons start with `windup-rules-`. +* Ruleset add-ons start with `windup-rules-`. diff --git a/docs/Dev-Git-Rebasing.adoc b/docs/Dev-Git-Rebasing.adoc index ceb1f9707d..d4e97f233f 100644 --- a/docs/Dev-Git-Rebasing.adoc +++ b/docs/Dev-Git-Rebasing.adoc @@ -1,9 +1,40 @@ [[Dev-Git-Rebasing]] === Git Rebasing -Ondra Zizka wrote this simple script to bring down a series of pull requests into a -single branch. He then pushes that branch to upstream master-ignore. +This section describes a few ways you can pull in the code to rebase to the latest code base. +==== Approach Suggested on GitHub + +This is the approach suggested on GitHub. + +. Checkout the source: ++ +-------------------------------------------------------------- +git checkout -b lincolnthree-WINDUP-133 master +git pull https://github.com/lincolnthree/windup.git WINDUP-133 +-------------------------------------------------------------- + +. Run the tests to make sure it builds. ++ +-------- +mvn clean install +-------- + +. If they pass, merge and push them to your repository. ++ +----------------------------------------- +git checkout master +git merge --no-ff lincolnthree-WINDUP-133 +git push origin master +----------------------------------------- + +==== Script Provided by the Windup Development Team + +Ondra Zizka wrote the following script to bring down a series of pull requests into a +single branch. It then pushes that branch to upstream master-ignore. + +. Bring down the pulls into a single branch. ++ ---- pull() { cmd="git fetch upstream master " @@ -30,32 +61,11 @@ pull() { } ---- -Fetch using one pull request: +. Fetch using the one pull request. ++ ---- git fetch upstream master pull/$PR/head:pullRequest$PR ---- -==== Alternate Approach - -This is the approach GitHub suggests. - -. Checkout the source: -+ --------------------------------------------------------------- -git checkout -b lincolnthree-WINDUP-133 master -git pull https://github.com/lincolnthree/windup.git WINDUP-133 --------------------------------------------------------------- +. The branch is now updated with the latest source. -. Run the tests to make sure it builds. -+ --------- -mvn clean install --------- - -. If they pass, merge and push them to your repository. -+ ------------------------------------------ -git checkout master -git merge --no-ff lincolnthree-WINDUP-133 -git push origin master ------------------------------------------ \ No newline at end of file diff --git a/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc b/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc index 36e0d7da47..618a3eedeb 100644 --- a/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc +++ b/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc @@ -5,8 +5,7 @@ _For the purposes of tracking the porting WindRide functionality to Windup. Will removed when done._ [[some-classes-mapping]] -Some classes mapping -~~~~~~~~~~~~~~~~~~~~ +==== Some classes mapping [source,java] ---- @@ -16,11 +15,10 @@ DeploymentInfo = ApplicationModel ---- [[server-side-code-to-be-moved]] -Server-side code to be moved -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==== Server-side code to be moved * ServerInfo * ComparisonResult * FileHashComparer * IMigrationAction -* ServerMigrationReportJaxb \ No newline at end of file +* ServerMigrationReportJaxb diff --git a/docs/Dev-Variables-Stack.adoc b/docs/Dev-Variables-Stack.adoc index 015b4bc3fa..86dc8f4605 100644 --- a/docs/Dev-Variables-Stack.adoc +++ b/docs/Dev-Variables-Stack.adoc @@ -1,31 +1,34 @@ [[Dev-Variables-Stack]] === Variables Stack +.DRAFT + The `Variables` class stores the variables which are available in rules, EL expressions, and FreeMarker and XSLT templates. ==== Accessing variables ===== From a Java-based rule -TODO +TO_DO: Describe how to access variables from a Java-based rule. ===== From a Groovy-based rule -TODO +TO_DO: Describe how to access variables from a Groovy-based rule. ===== From an EL expression -TODO +TO_DO: Describe how to access variables from an EL expression. ===== From a FreeMarker -TODO +TO_DO: Describe how to access variables from a FreeMarker. ===== From XSLT template -TODO +TO_DO: Describe how to access variables from an XSLT template. ==== Accessing variables as a flat `Map` -TODO +TO_DO: Describe how to access variables from a Map. + diff --git a/docs/Dev-Windup-Release-Process.adoc b/docs/Dev-Windup-Release-Process.adoc new file mode 100644 index 0000000000..3ee5be8f76 --- /dev/null +++ b/docs/Dev-Windup-Release-Process.adoc @@ -0,0 +1,14 @@ +[[Dev-Windup-Release-Process]] +=== Windup Release Process + +Windup consists of artifacts from multiple GitHub repositories. Use the following procedure to create a Windup release. + +. Release http://github.com/windup/nexus-indexer ++ +---- +mvn release:prepare release:perform -DreleaseVersion=X -Dtag=Y -DdevelopmentVersion=Z +---- + +. Release http://github.com/windup/windup _primary reactor_ +. Release http://github.com/windup/windup-rulesets +. Release http://github.com/windup/windup-distribution \ No newline at end of file diff --git a/docs/Execute-Windup.adoc b/docs/Execute-Windup.adoc index 03244c5ada..6a34468c67 100644 --- a/docs/Execute-Windup.adoc +++ b/docs/Execute-Windup.adoc @@ -5,9 +5,9 @@ Before you begin, you must gather the following information. -. 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. +. The fully qualified path of the application archive or folder you plan to migrate. +. The fully qualified path to a folder that will contain the resulting report information. -. You also specify the fully qualified path to a folder that will contain the resulting report information. This path is passed using the `--output` argument on the command line. * If the folder does not exist, it is created by Windup. * If the folder exists, you are prompted with the message: @@ -54,9 +54,28 @@ JBoss Windup, version [ 2.0.0-VERSION ] - JBoss, by Red Hat, Inc. [ http://windu [windup-distribution-2.0.0-VERSION]$ --------------------------------------------------------------------------- -==== Run the `windup-migrate-app` Command +==== Run Windup -. 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: +. The command to run Windup is `windup-migrate-app`. + +. The following is a list of the most commonly used command line arguments. + ++ +--input *INPUT_ARCHIVE_OR_FOLDER*:: This is the fully qualified application archive or source path. ++ +--source-mode true (optional):: This argument is optional and is only required if the application to be evaluated contains source files rather than compiled binaries. The default value is `false`. ++ +--output *OUTPUT_REPORT_DIRECTORY*:: The fully qualified path to the folder that will contain the the report information produced by Windup. ++ +NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists and you do not specify the `--overwrite` argument, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! ++ +--overwrite (optional):: Specify this optional argument only if you are certain you want to force Windup to delete the existing *OUTPUT_REPORT_DIRECTORY*. The default value is `false`. ++ +--packages *PACKAGE_1*, *PACKAGE_2*, *PACKAGE_N* (optional):: This is a comma-delimited list of the packages to be evaluated by Windup. ++ +--excludePackages *PACKAGE_1*, *PACKAGE_2*, *PACKAGE_N* (optional):: This is a comma-delimited list of the packages to be excluded by Windup. + +. 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 @@ -68,20 +87,7 @@ To run Windup against application source code, you must add the `--sourceMode tr 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. -+ -NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! - -+ -*PACKAGE_1*, *PACKAGE_2*, *PACKAGE_N* are the packages to be evaluated by Windup. - -+ -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. +See xref:windup-command-examples[Windup Command Examples] below for concrete examples of commands that use source code directories and archives located in the Windup GitHub repository. . You should see the following result upon completion of the command: + @@ -121,7 +127,7 @@ For Windows: > bin\windup.bat --evaluate "windup-migrate-app --input INPUT_ARC ==== Windup Help -To see the list of available parameters for the `windup-migrate-app` command, execute the following command in the Windup prompt: +To see the complete list of available arguments for the `windup-migrate-app` command, execute the following command in the Windup prompt: man windup-migrate-app @@ -155,5 +161,5 @@ For Windows: > bin\windup.bat --evaluate "windup-migrate-app --input \windup-sou 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 https://github.com/windup/windup-quickstarts/releases/tag/2.0.0.Alpha1[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. +The quickstarts provide examples of Java-based and XML-based rules 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 rules. diff --git a/docs/Features-of-Windup-2.0.adoc b/docs/Features-of-Windup-2.0.adoc index cb50b61afa..1ad8ab58b2 100644 --- a/docs/Features-of-Windup-2.0.adoc +++ b/docs/Features-of-Windup-2.0.adoc @@ -22,7 +22,7 @@ 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 http://ocpsoft.org/rewrite/[OCPsoft Rewrite] and provide greater flexibility and power creating when rules. +* Java-based rule add-ons are based on http://ocpsoft.org/rewrite/[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 diff --git a/docs/Get-Involved.adoc b/docs/Get-Involved.adoc index 224e32ba6b..b2bdde7655 100644 --- a/docs/Get-Involved.adoc +++ b/docs/Get-Involved.adoc @@ -37,3 +37,5 @@ Any level of involvement is greatly appreciated! * Windup Developers Mailing List: windup-dev@lists.jboss.org * Windup Commits Mailing List: windup-commits@lists.jboss.org * Windup on Twitter: https://twitter.com/jbosswindup[@JBossWindup] + +You can also follow us on this IRC channel: `irc.freenode.net#windup`. diff --git a/docs/Install-Windup.adoc b/docs/Install-Windup.adoc index a9a043d061..5c5f5c3ba9 100644 --- a/docs/Install-Windup.adoc +++ b/docs/Install-Windup.adoc @@ -1,6 +1,15 @@ [[Install-Windup]] === Install Windup +==== Minimum System Requirements + +* Java Platform, Enterprise Edition 7 +* A minimum of 4 GB RAM. For better performance, a 4-core processor with 8 GB RAM is recommended. This allows 3 - 4 GB RAM for use by the JVM. +* A minimum of 4 GB of free disk space. A fast disk, especially a Solid State Drive (SSD), will improve performance. +* Windup is tested on Linux (Fedora), Mac OS X, and Windows. Other Operating Systems with Java 7 support should work equally well. + +==== Download and Install Windup + . Download the latest https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.jboss.windup&a=windup-distribution&v=LATEST&e=zip&c=offline[Windup ZIP distribution]. . Extract the ZIP file in to a directory of your choice. diff --git a/docs/Install-and-Configure-Maven.adoc b/docs/Install-and-Configure-Maven.adoc index 7aba5b01d6..af54f1b25e 100644 --- a/docs/Install-and-Configure-Maven.adoc +++ b/docs/Install-and-Configure-Maven.adoc @@ -1,7 +1,7 @@ [[Install-and-Configure-Maven]] === Install and Configure Maven -If you plan to contribute to the core code base or create Java-based rule addons, you must first install and configure Maven to build Windup from source. +If you plan to contribute to the core code base or create Java-based rule add-ons, you must first install and configure Maven to build Windup from source. ==== Download and Install Maven diff --git a/docs/Review-the-Windup-Quickstarts.adoc b/docs/Review-the-Windup-Quickstarts.adoc index 6eb1a15c20..827e7d0490 100644 --- a/docs/Review-the-Windup-Quickstarts.adoc +++ b/docs/Review-the-Windup-Quickstarts.adoc @@ -1,7 +1,7 @@ [[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 +The Windup quickstarts provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. 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. diff --git a/docs/Rule-Metadata.adoc b/docs/Rule-Metadata.adoc index 5ddfe77646..1787e0b35f 100644 --- a/docs/Rule-Metadata.adoc +++ b/docs/Rule-Metadata.adoc @@ -1,9 +1,10 @@ -=== Rules Metadata +[[Rule-Metadata]] +=== Rule Metadata .Draft ==== Overview -Rules metadata are used for ordering, filtering, debugging and performance reasons. +Rule metadata is used for ordering, filtering, debugging and performance reasons. ==== Metadata used by Windup diff --git a/docs/Rules-Available-Rules-Utilities.adoc b/docs/Rules-Available-Rules-Utilities.adoc index dd88fa5a4f..79855fe3e4 100644 --- a/docs/Rules-Available-Rules-Utilities.adoc +++ b/docs/Rules-Available-Rules-Utilities.adoc @@ -8,7 +8,7 @@ _Note: Needs update. This is out of date!_ (Lower Level API, to cover cases not provided by high level API) -This topic describes how to to programmatically access or update graph data when you create a Java-based rule addon. +This topic describes how to to programmatically access or update graph data when you create a Java-based rule add-on. ===== Query the graph diff --git a/docs/Rules-Basic-Rule-Execution-Flow-Patterns.adoc b/docs/Rules-Basic-Rule-Execution-Flow-Patterns.adoc index 9ea0213287..295b76ad7f 100644 --- a/docs/Rules-Basic-Rule-Execution-Flow-Patterns.adoc +++ b/docs/Rules-Basic-Rule-Execution-Flow-Patterns.adoc @@ -1,7 +1,7 @@ [[Rules-Basic-Rule-Execution-Flow-Patterns]] === Basic Rule Execution Flow Patterns -SGILDA: TODO - Need some links to github to the respective example files. +TO_DO: Need some links to github to the respective example files. ==== operation(); - single operation diff --git a/docs/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc b/docs/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc index 250886f936..d9628a1c34 100644 --- a/docs/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc +++ b/docs/Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc @@ -171,7 +171,7 @@ The following are examples of some dependencies you may need for your rule add-o ===== Create the Java RuleProvider -. Add `beans.xml` file to `META-INF/` dir in resources - typically, `$project-dir/src/main/resources/META-INF/beans.xml`. This file can be empty. It tells CDI to scan your addon for CDI beans. +. Add `beans.xml` file to `META-INF/` dir in resources - typically, `$project-dir/src/main/resources/META-INF/beans.xml`. This file can be empty. It tells CDI to scan your add-on for CDI beans. . 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: + diff --git a/docs/Rules-Create-a-Basic-XML-Rule.adoc b/docs/Rules-Create-a-Basic-XML-Rule.adoc index 6b56f2456b..abaa65a335 100644 --- a/docs/Rules-Create-a-Basic-XML-Rule.adoc +++ b/docs/Rules-Create-a-Basic-XML-Rule.adoc @@ -1,7 +1,7 @@ -[[Rules-Create-am-Basic-XML-Rule]] +[[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. +You can create a Windup rule using Java, XML, or Groovy. This topic describes how to create a rule using XML. ==== Prerequisites diff --git a/docs/Rules-Creating-Rule-Operations.adoc b/docs/Rules-Creating-Rule-Operations.adoc index d1db663049..ff47c73ee8 100644 --- a/docs/Rules-Creating-Rule-Operations.adoc +++ b/docs/Rules-Creating-Rule-Operations.adoc @@ -1,3 +1,4 @@ +[[Rules-Creating-Rule-Operations]] === Creating Rule Operations An operation is a task which can be invoked from within a rule. diff --git a/docs/Rules-Development-Guide.asciidoc b/docs/Rules-Development-Guide.asciidoc index eeb126f121..83fd59d6fb 100644 --- a/docs/Rules-Development-Guide.asciidoc +++ b/docs/Rules-Development-Guide.asciidoc @@ -20,10 +20,10 @@ rules for Windup 2.0. ==== Configure Your System for Java-based Rules -If you plan to create Java-based rule addons, you must also do the following. +If you plan to create Java-based rule add-ons, 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. +* 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 add-ons. ==== Understand the Rule Processing @@ -33,7 +33,7 @@ If you plan to create Java-based rule addons, you must also do the following. * link:Rules-Difference-Between-XML-based-and-Java-based-Rules[ Difference Between XML-based and Java-based Rules] -==== Create and Test Java Rule Addons +==== Create and Test Java Rule Add-ons * link:Rules-Java-based-Rule-Structure[Java-based Rule Structure] * link:Rules-Basic-Rule-Execution-Flow-Patterns[Basic Rule Execution Flow Patterns] @@ -43,6 +43,10 @@ Difference Between XML-based and Java-based Rules] ==== Create and Test XML Rules * link:Rules-Create-a-Basic-XML-Rule[Create a Basic XML Rule] + +** link:Rules-XML-Rule-When-Condition-Syntax[XML Rule - When Condition Syntax] +** link:Rules-XML-Rule-Perform-Action-Syntax[XML Rule - Perform Action Syntax] + * link:Rules-Test-a-Basic-XML-Rule-in-Windup[Test an XML Rule in Windup] ==== Review the Report diff --git a/docs/Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc b/docs/Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc new file mode 100644 index 0000000000..e71dcb108e --- /dev/null +++ b/docs/Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc @@ -0,0 +1,158 @@ +[[Rules-Difference-Between-XML-based-and-Java-based-Rules]] +=== Difference Between XML-based and Java-based Rules + +==== First of all, to prevent confusion: + +1. Rules can be _written_ using XML or the Java API. We call them XML-based and Java-based Rules. +2. Independent of the syntax, the rules may _inspect_ (classify) XML or Java code. + +See the examples below. + + +==== Which one to choose? + +The XML rules provide a quick, simple way to create rules to analyze Java and XML files. Java rules provide the ability to create very complex rules. + +* If you simply need to highlight a specific section of Java code or XML file content and provide hints for it, it is recommended that you create the rule using XML. +* If you need to create a new custom report, you need to create the reporting rules using Java. +* If you need to extend functionality beyond what the XML rules provide, you need to create the rule using Java. + +==== Pros and cons - XML +Pros: + +* XML rules are fairly easy to write and require less code. +* You do not need to configure Maven to build from source because there is no need for compilation of +XML rules. +* Deployment is simple. You simply drop the XML rule into the appropriate path and Windup automatically scans the new rule. + +Cons: + +* XML rules only support a simple subset of conditions and operations. +* XML rules do not provide for direct custom graph data manipulation. +* XML rules do not support the ability to create custom reports. + +==== Pros and Cons - Java +Pros: + +* Java rule add-ons allow you to write custom rules and provide a lot of flexibility. +* You can set breakpoints and test Java rule add-ons using a debugger. +* IDEs provide code completion for the Windup API. + +Cons: + +* You must configure Maven to compile the Windup Java rule add-ons. +* Java rule add-ons that are not included in the Windup core code base must be a full Forge add-on. +* Java rule add-ons require writing a lot of Java code/ +* Writing Java rule add-ons are complex and required knowledge of Windup internals. + + +==== Examples + +Example of a rule written in XML classifying Java code: + +[source,xml] +---------- + + + + + + + TYPE + + + + + + + + + + +---------- + + +Example of a rule written in Java classifying Java code: + +[source,java] +---------- +/** + * Scans for classes with EJB related annotations, and adds EJB related metadata for these. + */ +public class DiscoverEjbAnnotationsRuleProvider extends WindupRuleProvider +{ + @Override + public Configuration getConfiguration(GraphContext context) { + return ConfigurationBuilder.begin() + .addRule() + .when(JavaClass.references("javax.ejb.{annotationType}").at(TypeReferenceLocation.ANNOTATION)) + .perform(new AbstractIterationOperation() + { + public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) + { + extractEJBMetadata(event, payload); + }; + }) + .where("annotationType").matches("Stateless|Stateful") + .withId(ruleIDPrefix + "_StatelessAndStatefulRule") + .addRule() + .when(JavaClass.references("javax.ejb.MessageDriven").at(TypeReferenceLocation.ANNOTATION)) + .perform(new AbstractIterationOperation() { + @Override + public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) { + extractMessageDrivenMetadata(event, payload); + } + }) + .withId(ruleIDPrefix + "_MessageDrivenRule") + .addRule() + .when(JavaClass.references("javax.persistence.Entity").at(TypeReferenceLocation.ANNOTATION).as(ENTITY_ANNOTATIONS) + .or(JavaClass.references("javax.persistence.Table").at(TypeReferenceLocation.ANNOTATION).as(TABLE_ANNOTATIONS_LIST))) + .perform(Iteration.over(ENTITY_ANNOTATIONS).perform(new AbstractIterationOperation() { + @Override public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) { + extractEntityBeanMetadata(event, payload); + } + }).endIteration()) + .withId(ruleIDPrefix + "_EntityBeanRule"); + } + ... +} +---------- + +==== Summary + +The following is a draft... it may go. + +[cols="3*", options="header"] +|=== +|Requirement +|XML Rule +|Java Rule Add-on + +|Easy to write? +|Yes +|Depends on the complexity of the rule + +|Requires that you configure Maven? +|No +|Yes + +|Requires that you compile the rule? +|No +|Yes + +|Simple deployment? +|No +|Yes + +|Supports custom reports? +|No +|Yes + +|Ability to create complex conditions and operations? +|No +|Yes + +|Ability to directly manipulate the graph data? +|No +|Yes +|=== diff --git a/docs/Rules-Java-based-Rule-Structure.adoc b/docs/Rules-Java-based-Rule-Structure.adoc index 62a577d262..4bda3d273f 100644 --- a/docs/Rules-Java-based-Rule-Structure.adoc +++ b/docs/Rules-Java-based-Rule-Structure.adoc @@ -1,10 +1,7 @@ [[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] +TO_DO: Add a how-to for compound rules, nested rules, rules over multiple sources, negative queries (not matched by anything). ==== Windup Rule Provider @@ -125,7 +122,7 @@ several convenient implementations for constructs like iteration ====== Nested iterations -TODO +TO_DO: Provide information about nested iterations ====== otherwise @@ -150,7 +147,7 @@ For more information, see http://ocpsoft.org/rewrite/[OCP Rewrite web]. ===== Where -TODO +TO_DO: Provide information about the where clause ===== Metadata diff --git a/docs/Rules-Ops-Reporting-TypeReference.adoc b/docs/Rules-Ops-Reporting-TypeReference.adoc index b20990f5e8..a94f2bf5b8 100644 --- a/docs/Rules-Ops-Reporting-TypeReference.adoc +++ b/docs/Rules-Ops-Reporting-TypeReference.adoc @@ -1,3 +1,4 @@ +[[Rules-Ops-Reporting-TypeReference]] === Ops Reporting TypeReference TBD diff --git a/docs/Rules-Rule-Execution-Lifecycle.adoc b/docs/Rules-Rule-Execution-Lifecycle.adoc index f2dec2e004..adbc9a2d24 100644 --- a/docs/Rules-Rule-Execution-Lifecycle.adoc +++ b/docs/Rules-Rule-Execution-Lifecycle.adoc @@ -38,7 +38,7 @@ org.jboss.windup.config.phase.PostFinalize ------------- -By default, a rule runs during the https://github.com/windup/windup/blob/master/config/api/src/main/java/org/jboss/windup/config/phase/MigrationRules.java[MigrationRules] phase. However, a +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 it executes, such as the extraction of archives and scanning of java or XML files. @@ -46,7 +46,7 @@ files. Rule phases provide a 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 https://github.com/windup/windup/blob/master/config/api/src/main/java/org/jboss/windup/config/phase/InitialAnalysis.java[InitialAnalysis] rule phase. +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] ---- @@ -66,25 +66,31 @@ 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. +This phase 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. diff --git a/docs/Rules-Rule-Story-Points.adoc b/docs/Rules-Rule-Story-Points.adoc index 6cb54246cd..df8dacc96d 100644 --- a/docs/Rules-Rule-Story-Points.adoc +++ b/docs/Rules-Rule-Story-Points.adoc @@ -1,15 +1,15 @@ [[Rules-Rule-Story-Points]] === Rule Story Points -.DRAFT - ==== 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. +Story points are an abstract metric commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. 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. It does not necessarily translate to man-hours, but the value should be consistent across tasks. -==== How to Estimate Story Points in a Rule +==== How Story Points are Estimated in Rules -Estimating story points for a rule can be tricky. The following are general guidelines or suggestions to use when estimating the level of effort required for a rule. +Estimating story points for a rule can be tricky. The following are the general guidelines Windup uses when estimating the level of effort required for a rule. [cols="3*", options="header"] |=== @@ -23,7 +23,7 @@ Estimating story points for a rule can be tricky. The following are general guid |Mapped | 1- 2 per file -|There is a standard mapping algorithm to port the code or file. The number of story points required is small, but dependent on the number of files to port. +|There is a standard mapping algorithm to port the code or file. The number of story points required is small, but is dependent on the number of files to port. |Custom |5 - 20 per change or component diff --git a/docs/Rules-Rulesets.adoc b/docs/Rules-Rulesets.adoc index b681a84532..506bf01fc1 100644 --- a/docs/Rules-Rulesets.adoc +++ b/docs/Rules-Rulesets.adoc @@ -1,3 +1,4 @@ +[[Rules-Rulesets]] === Rulesets DRAFT diff --git a/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc b/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc index 01b54e7dfe..5076cb4e4d 100644 --- a/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc +++ b/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc @@ -11,7 +11,7 @@ This is the folder where you run the Windup executable. See xref:About-the-WINDU * The `${user.home}/.windup/rules/` folder. + -This folder is created by Windup the first time you execute Windup. It used to track rules and addons and to contains the Windup log. +This folder is created by Windup the first time you execute Windup. It used to track rules and add-ons and to contains the Windup log. + -------- For Linux or Mac: ~/.windup/rules/ diff --git a/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc b/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc index 371c91d9f2..2d0ce1dbe7 100644 --- a/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc +++ b/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc @@ -1,7 +1,7 @@ [[Rules-XML-Rule-Perform-Action-Syntax]] === XML Rule - Perform Action Syntax -Operations allowed in the `perform` section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. Because XML rules are modeled after the Java-based rule addons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave. +Operations allowed in the `perform` section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave. The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. diff --git a/docs/Rules-XML-Rule-When-Condition-Syntax.adoc b/docs/Rules-XML-Rule-When-Condition-Syntax.adoc index 7861e6ac32..ae08cbad19 100644 --- a/docs/Rules-XML-Rule-When-Condition-Syntax.adoc +++ b/docs/Rules-XML-Rule-When-Condition-Syntax.adoc @@ -1,7 +1,7 @@ [[Rules-XML-Rule-When-Condition-Syntax]] === XML Rule - When Condition Syntax -Conditions allowed in the `when` portion of a rule must extend http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/GraphOperation.html[GraphOperaton] and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule addons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave. +Conditions allowed in the `when` portion of a rule must extend http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/GraphOperation.html[GraphOperaton] and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave. The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. @@ -161,16 +161,17 @@ Match on the project `` * from="VARIABLE_NAME" + -Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. ??? +Begin the search query with the filtered result from a previous search identified by its `as` VARIABLE_NAME. -* to = "???" +* to = TO_DO: complete the project artifact 'to' element syntax [[filecontent-syntax]] ==== filecontent Syntax +TO_DO: complete the filecontent element syntax + Use the `filecontent` element to find information in file content.For a better understanding of the `filecontent` condition, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/files/condition/FileContent.html[FileContent] class. -TBD : .Draft Use the `filecontent` element to test for content within files. The following is an example of a rule that tests for `filecontent`. diff --git a/docs/Ruleset-Java-Basic-Ruleset.adoc b/docs/Ruleset-Java-Basic-Ruleset.adoc index 36d8668fb5..d763e904e1 100644 --- a/docs/Ruleset-Java-Basic-Ruleset.adoc +++ b/docs/Ruleset-Java-Basic-Ruleset.adoc @@ -1,3 +1,4 @@ +[[Ruleset-Java-Basic-Ruleset]] === Java Basic Ruleset .DRAFT diff --git a/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc b/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc index e3b2837b6c..b64e144ee6 100644 --- a/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc +++ b/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc @@ -1,3 +1,4 @@ +[[Ruleset-Java-Classifications-and-Inline-Hints]] === Ruleset Java Classifications and Inline Hints .DRAFT @@ -17,8 +18,8 @@ do. They identify resources, and add a classification to the resource. Classifications are displayed both at the 10,000 foot view, main report and also at the resource report level. -* Java Classifications TODO: link -* XML Classifications TODO: link +* Java Classifications TO_DO: link +* XML Classifications TO_DO: link ==== Inline Hints diff --git a/docs/Ruleset-XML.adoc b/docs/Ruleset-XML.adoc index 7d1d57b532..d7b7fa9fe0 100644 --- a/docs/Ruleset-XML.adoc +++ b/docs/Ruleset-XML.adoc @@ -1,3 +1,4 @@ +[[Ruleset-XML]] === XML Ruleset .DRAFT @@ -17,7 +18,7 @@ A core ruleset to provide support for XML files. _A definition list (dl/dt/dd) of RuleProviders of given Ruleset with brief descriptions._ -TODO: Not sure if all the `Xml*` really belong here - maybe rather to Java or Java EE? +TO_DO: Not sure if all the `Xml*` really belong here - maybe rather to Java or Java EE? * **DiscoverXmlFilesRuleProvider** - * **XmlBaseConfig** - @@ -50,7 +51,7 @@ _Subclasses of `WindupVertexFrame`. ==== Configuration -_Subclasses of `TODO` +_Subclasses of `TO_DO` ==== Reports diff --git a/docs/Windup-Architectural-Components.adoc b/docs/Windup-Architectural-Components.adoc index 2fa4941351..ad4c626864 100644 --- a/docs/Windup-Architectural-Components.adoc +++ b/docs/Windup-Architectural-Components.adoc @@ -15,7 +15,7 @@ about Forge 2, see: http://forge.jboss.org/[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 +the ability to run Forge add-ons in an embedded application. For more information about Forge Furnace, see: http://forge.jboss.org/document/run-forge-embedded[Run Forge Embedded]. diff --git a/docs/Windup-Core-Development-Guide.adoc b/docs/Windup-Core-Development-Guide.adoc index 41de633f31..83a68d526b 100644 --- a/docs/Windup-Core-Development-Guide.adoc +++ b/docs/Windup-Core-Development-Guide.adoc @@ -9,95 +9,167 @@ This guide is for developers who plan to contribute source code updates or core rule add-ons to the Windup 2.0 project. include::What-is-Windup.adoc[tabsize=4] + include::Features-of-Windup-2.0.adoc[tabsize=4] -include::Get-Involved.adoc[tabsize=4] -include::Dev-Windup-Project-Information.adoc[tabsize=4] -include::Report-Issues-with-Windup.adoc[tabsize=4] + include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] +== Get Started + +Before you begin to contribute to Windup, take a quick tour to see how to use it. + +include::Install-and-Configure-Maven.adoc[tabsize=4] + +include::Dev-Get-the-Windup-Source-Code.adoc[tabsize=4] + +include::Dev-Build-Windup-from-Source.adoc[tabsize=4] + +include::Dev-Execute-Windup-Built-from-Source.adoc[tabsize=4] + +include::Execute-Windup.adoc[tabsize=4] + +include::Review-the-Report.adoc[tabsize=4] + == Developer Contributing Information include::Dev-Development-Guidelines-and-Conventions.adoc[tabsize=4] + include::Dev-Submit-Code-Updates-to-the-Windup-Project.adoc[tabsize=4] == Understand the Windup Architecture and Structure include::Windup-Architectural-Components.adoc[tabsize=4] -include::Dev-Windup-Project-Structure.adoc[tabsize=4] -== Get Started -include::Install-and-Configure-Maven.adoc[tabsize=4] -include::Dev-Get-the-Windup-Source-Code.adoc[tabsize=4] -include::Dev-Build-Windup-from-Source.adoc[tabsize=4] -include::Dev-Execute-Windup-Built-from-Source.adoc[tabsize=4] -include::Execute-Windup.adoc[tabsize=4] -include::Review-the-Report.adoc[tabsize=4] +include::Dev-Windup-Project-Structure.adoc[tabsize=4] == Rules and Rulesets + include::Windup-Processing-Overview.adoc[tabsize=4] + include::Rules-Rule-Execution-Lifecycle.adoc[tabsize=4] + include::Rules-Rule-Story-Points.adoc[tabsize=4] +include::Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc[tabsize=4] + == Create and Test Java Rule Add-ons + +include::Install-and-Configure-Maven.adoc[tabsize=4] + 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] + +// This is not ready for prime time... include::Rules-Create-an-Advanced-Ruleset.adoc[tabsize=4] == Create and Test XML Rules include::Rules-Create-a-Basic-XML-Rule.adoc[tabsize=4] +include::Rules-XML-Rule-When-Condition-Syntax.adoc[tabsize=4] + +include::Rules-XML-Rule-Perform-Action-Syntax.adoc[tabsize=4] + +include::Rules-Test-a-Basic-XML-Rule-in-Windup.adoc[tabsize=4] + == Core Developer topics include::Dev-Windup-Bootstrap.adoc[tabsize=4] + include::Dev-Classloading-Notes.adoc[tabsize=4] + include::Dev-Connect-to-the-Graph-via-Rexster.adoc[tabsize=4] + include::Dev-Decompiling.adoc[tabsize=4] + include::Dev-Dependencies.adoc[tabsize=4] + include::Dev-Frames-Extensions.adoc[tabsize=4] + include::Dev-Internal-API-Features.adoc[tabsize=4] + include::Dev-Logging.adoc[tabsize=4] + include::Dev-Variables-Stack.adoc[tabsize=4] -include::Dev-Port-WindRide-Functionality-to-Windup.adoc[tabsize=4] + +// include::Dev-Port-WindRide-Functionality-to-Windup.adoc[tabsize=4] + include::Dev-Git-Rebasing.adoc[tabsize=4] == Rules topics include::Rules-Available-Rules-Utilities.adoc[tabsize=4] + include::Dev-Concepts-and-Philosophy.adoc[tabsize=4] + include::Rules-Creating-Rule-Operations.adoc[tabsize=4] + include::Rules-Rulesets.adoc[tabsize=4] + include::Ruleset-Java-Basic-Ruleset.adoc[tabsize=4] + include::Ruleset-Java-Classifications-and-Inline-Hints.adoc[tabsize=4] + include::Ruleset-Java-EE-Apps.adoc[tabsize=4] + include::Ruleset-Java-EE-Servers.adoc[tabsize=4] + include::Ruleset-Reporting.adoc[tabsize=4] + include::Ruleset-XML.adoc[tabsize=4] + include::Rules-Windup-Models.adoc[tabsize=4] + include::Rules-Create-Java-Queries.adoc[tabsize=4] + include::Rules-Rules-Metadata.adoc[tabsize=4] + include::Rules-Rules-Operations.adoc[tabsize=4] + include::Rules-Ops-Reporting-Classification.adoc[tabsize=4] + include::Rules-Ops-Reporting-Hint.adoc[tabsize=4] + include::Rules-Ops-Reporting-TypeReference.adoc[tabsize=4] + include::Rules-Ops-Xml-XsltTrasformation.adoc[tabsize=4] == Debugging and Troubleshooting include::Dev-Debugging-and-Profiling.adoc[tabsize=4] + include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] -==== Wiki and Product Documentation +== Wiki Information include::About-the-Windup-Wiki.adoc[tabsize=4] + include::Dev-Add-Images-to-the-Windup-Wiki.adoc[tabsize=4] + +== Windup Product Release and Documentation Process + +include::Dev-Windup-Release-Process.adoc[tabsize=4]] + include::Dev-Create-Windup-JavaDoc.adoc[tabsize=4] + include::Dev-Windup-Documentation-Process.adoc[tabsize=4] == Additional Resources include::Review-the-Windup-Quickstarts.adoc[tabsize=4] + +include::Get-Involved.adoc[tabsize=4] + include::Known-Issues.adoc[tabsize=4] + +include::Report-Issues-with-Windup.adoc[tabsize=4] + +== Appendix + include::Glossary.adoc[tabsize=4] +include::Dev-Windup-Project-Information.adoc[tabsize=4] + + diff --git a/docs/Windup-Rules-Development-Guide.adoc b/docs/Windup-Rules-Development-Guide.adoc index e04823e37f..5344e2cb57 100644 --- a/docs/Windup-Rules-Development-Guide.adoc +++ b/docs/Windup-Rules-Development-Guide.adoc @@ -13,15 +13,8 @@ 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] @@ -30,54 +23,64 @@ include::Execute-Windup.adoc[tabsize=4] include::Review-the-Report.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] +include::Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc[tabsize=4] + == Create and Test Java Rule Addons include::Install-and-Configure-Maven.adoc[tabsize=4] + 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] + +// This is not ready for prime time... include::Rules-Create-an-Advanced-Ruleset.adoc[tabsize=4] == Create and Test XML Rules include::Rules-Create-a-Basic-XML-Rule.adoc[tabsize=4] -include::Rules-XML-Rule-When-Condition-Syntax.adoc[tabsize=4] -include::Rules-XML-Rule-Perform-Action-Syntax.adoc[tabsize=4] -include::Rules-Test-a-Basic-XML-Rule-in-Windup.adoc[tabsize=4] -== Review the Report - -include::Review-the-Report.adoc[tabsize=4] +include::Rules-XML-Rule-When-Condition-Syntax.adoc[tabsize=4] -== External Rule Examples +include::Rules-XML-Rule-Perform-Action-Syntax.adoc[tabsize=4] -include::Review-the-Windup-Quickstarts.adoc[tabsize=4] +include::Rules-Test-a-Basic-XML-Rule-in-Windup.adoc[tabsize=4] == Debugging and Troubleshooting include::Dev-Debugging-and-Profiling.adoc[tabsize=4] -include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] +include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] == Additional Resources -include::Rules-Available-Rules-Utilities.adoc[tabsize=4] +include::Get-Involved.adoc[tabsize=4] + include::Review-the-Windup-Quickstarts.adoc[tabsize=4] + +include::Rules-Available-Rules-Utilities.adoc[tabsize=4] + include::Known-Issues.adoc[tabsize=4] -include::Glossary.adoc[tabsize=4] + +include::Report-Issues-with-Windup.adoc[tabsize=4] == Appendix +include::Glossary.adoc[tabsize=4] + include::Windup-Architectural-Components.adoc[tabsize=4] -include::Dev-Dependencies.adoc[tabsize=4] + +// This is not ready for prime time... include::Dev-Dependencies.adoc[tabsize=4] + include::Rules-Windup-Models.adoc[tabsize=4] diff --git a/docs/Windup-User-Guide.adoc b/docs/Windup-User-Guide.adoc index 950471e2ec..19c0e0a6df 100644 --- a/docs/Windup-User-Guide.adoc +++ b/docs/Windup-User-Guide.adoc @@ -2,7 +2,7 @@ :toc: :toclevels: 4 - +:numbered: == Overview @@ -13,16 +13,9 @@ 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 +== Get Started include::Install-Windup.adoc[tabsize=4] @@ -34,12 +27,23 @@ include::Review-the-Report.adoc[tabsize=4] include::Review-the-Windup-Quickstarts.adoc[tabsize=4] +include::Get-Involved.adoc[tabsize=4] + include::Known-Issues.adoc[tabsize=4] +include::Report-Issues-with-Windup.adoc[tabsize=4] + +== Appendix + include::Glossary.adoc[tabsize=4] +include::Windup-Processing-Overview.adoc[tabsize=4] + include::Windup-Architectural-Components.adoc[tabsize=4] +include::Rules-Rule-Execution-Lifecycle.adoc[tabsize=4] + +include::Rules-Rule-Story-Points.adoc[tabsize=4] diff --git a/html/WindupCoreDevelopmentGuide.html b/html/WindupCoreDevelopmentGuide.html index 7a329ba71f..fe905118d6 100644 --- a/html/WindupCoreDevelopmentGuide.html +++ b/html/WindupCoreDevelopmentGuide.html @@ -419,8 +419,17 @@

Windup Core Development Guide

+ +
  • Get Started +
  • Developer Contributing Information @@ -435,25 +444,17 @@

    Windup Core Development Guide

  • Windup Project Structure
    • -
  • Get Started - -
  • Rules and Rulesets
  • Create and Test Java Rule Add-ons @@ -648,7 +670,7 @@

    Features of Windup 2.0

    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.

    +

    Java-based rule add-ons 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. @@ -725,1902 +747,2024 @@

    Features of Windup 2.0

    -

    Get Involved

    -
    -

    How can you help?

    +

    About the WINDUP_HOME Variable

    -

    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!

    +

    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.

    • -

      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.

        +

        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.

      • -

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

        +

        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.

      -
      • -
    • -

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

      -
      • -
    • -

      You can contribute Windup rules.

      -
      -
        -
      • -

        Write a Windup rule add-on to automate a migration process.

        -
        • -
      • -

        Create a test for the new rule.

        -
        • -
      • -

        For details, see the Windup Rules Development Guide.

        -
        • -
      -
      • -
    • -

      You can also contribute to the project source code.

      -
      -
        -
      • -

        Create a core rule.

        -
        • -
      • -

        Improve performance or efficiency.

        -
        • -
      • -

        See the_Windup Core Development Guide_ for information about how to configure your environment and set up the project.

        -
        • -
      -
      • -
    +
    +

    Get Started

    +
    -

    Any level of involvement is greatly appreciated!

    +

    Before you begin to contribute to Windup, take a quick tour to see how to use it.

    +
    +

    Install and Configure Maven

    +
    +

    If you plan to contribute to the core code base or create Java-based rule add-ons, you must first install and configure Maven to build Windup from source.

    -

    Helpful links

    -
    -
    +
    +

    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. -

      Windup Issue Tracker: https://issues.jboss.org/browse/WINDUP

      +

      From the menu, choose Window -→ Preferences.

    2. -

      Windup Users Mailing List: windup-users@lists.jboss.org

      +

      Expand Maven and click on Installations.

    3. -

      Windup Developers Mailing List: windup-dev@lists.jboss.org

      +

      Uncheck Embedded (3.0.4/1.4.0.20130531-2315)

    4. -

      Windup Commits Mailing List: windup-commits@lists.jboss.org

      +

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

    5. -

      Windup on Twitter: @JBossWindup -=== Windup Project Information

      +

      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.

    -

    Github Repository

    +

    Configure Maven to Build Windup

    -

    The Windup project github repository is located at https://github.com/windup/windup/.

    +

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

    -
    -

    See the Core-Developer-Guide for details on how to contribute to the Windup project source code.

    +
    +
      +
    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>
      -
      -

      Documentation

      -
      -

      The Windup documentation is currently located here in the Windup project Wiki.

      +
      3. +
    3. +

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

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

      For additional information, refer to the Windup Javadoc.

      +
      4. +
    -
    -

    Website

    -

    There is currently no website for Windup 2.0.

    +

    You are now configured to build Windup.

    -
    -

    The windup.jboss.org website currently provides information primarily -for legacy Windup 1.x (legacy).

    -
    -

    IRC chat

    +
    +

    Get the Windup Source Code

    -

    Server: irc.freenode.net
    -Channel: #windup

    -
    +

    To contribute to the Windup 2.0 project source code, you must fork the Windup repository to your own Git, clone your fork, commit your work on topic branches, and make pull requests back to the Windup repository.

    -

    Mailing lists

    +

    Install the Git Client

    -

    Subscribe to the JBoss mailing lists at -https://lists.jboss.org/mailman/listinfo/windup-dev.

    +

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

    -
    -
    -
    -

    Core development team (and IRC nicks)

    -
    -

    Lead: Lincoln Baxter (lincolnthree)
    -Members: Jess Sightler (jsightler), Matej Briskar (mbriskar), Ondrej -Zizka (ozizka)

    +

    Be sure to generate an SSH key and add the public key to your GitHub account: https://help.github.com/articles/generating-ssh-keys. You can verify the key using the following command:

    +
    +
    +
    ssh -T git@github.com
    -
    -

    IRC meeting bot commands (hint for the moderator)

    -
    -
    -
    #startmeeting
-#chair lincolnthree, ozizka, jsightler, mbriskar
-#addtopic Status Reports
-#addtopic Next steps
-#nexttopic
-#info ...
-#endmeeting
-Useful Commands: #action #agreed #help #info #idea #link #topic.
    +
    +

    You should see a message indicating your ID has successfully authenticated.

    +
    • +
  • +

    You should also configure your name and email identity using the following commands:

    +
    +
    +
    git config --global user_name "FIRST_NAME LAST_NAME"
+git config --global user_email "YOUR_EMAIL_ADDRESS"
    +
    • + -
    -

    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.

    -
    +

    Fork and Clone the Windup Repository

    1. -

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

      +

      Fork the Windup project. This +creates the windup project in your own Git with the default remote +name 'origin'.

    2. -

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

      +

      Clone your fork. This creates and populates a directory in your +local file system.

      +
      +
      +
      git clone https://github.com/<your-username>/windup.git
      +
      +
    3. -

      Enter your email address and click the Confirm address button.

      +

      Change to the windup directory.

    4. -

      Follow the instructions sent to your email address.

      +

      Add the remote upstream repository so you can fetch any changes to +the original forked repository.

      +
      +
      +
      git remote add upstream git@github.com:windup/windup.git
      +
      +
      +
      5. +
    5. +

      Get the latest files from the upstream repository.

      +
      +
      +
      git fetch upstream
      +
      +
    +
    +
    +

    Build Windup from Source

    +
    +

    This information is provided for new developers who plan to contribute code +to the Windup open source project. This section describes how to build Windup from source and how to extract the Windup distribution that is created during the build process.

    +
    +
    +

    If you use Linux and are an experienced Windup developer looking for a quick refresher, jump to: Quick Build Review for Experienced Windup Developers.

    +
    -

    Create a JIRA Issue

    +

    System Requirements to Build Windup

    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.

        +

        Java 1.7.

        +
        +

        You can choose from the following:

        +
        +
        +
        +
        OpenJDK
+Oracle Java SE
        +
        +
      • -

        You are then redirected back to the Create Issue page.

        -
        • -
      +

      Maven 3.1.1 or newer

      +
      +

      If you have not yet installed or configured Maven, see +Install and Configure Maven for details.

      +
      +
      +

      If you have installed Maven, you can check the version by typing the +following in a command prompt:

      +
      +
      +
      +
      mvn --version
      +
    2. -

      Choose the following options and click the Next button.

      +

      IDE requirements

      +
      +

      If you prefer, you can work within an IDE. The following IDEs are recommended.

      +
      +
      +

      You must also make sure the IDE embeds Maven 3.1.1 or later. See +Install and Configure Maven for details.

      +
      3. +
    +
    +
    +
    +

    Build Windup Using Maven Command Line

    +
    +
    1. -

      On the next screen complete the following fields:

      -
      -
        -
      • -

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

        +

        Make sure you have configured Maven as described here: +Install and Configure Maven.

      • -

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

        +

        Check out Windup source code: git clone git@github.com:windup/windup.git Windup. See Get the Windup Source Code for more info.

      • -

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

        -
        • -
      +

      Open a command terminal and navigate to the root of the Windup project directory.

      +
      +
      +
          cd Windup/
      +
    2. -

      Click the Create button to create the JIRA issue.

      -
      3. -
    3. -

      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. -=== About the WINDUP_HOME Variable

      -
      4. -
    -
    -
    -

    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.

    -
    +

    To create a branch and build Windup using the latest version of the source code:

    • -

      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.

      +

      Fetch the latest source code from the upstream repository.

      +
      +
      +
      git fetch upstream
      +
      +
    • -

      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.

      +

      Checkout a local copy of the branch.

      +
      +
      +
      git checkout -b BRANCH_NAME upstream/master
      +
      +
    + +
  • +

    If, at any point, you want to toss your changes and reset your local branch to the contents of the upstream repository, issue the following 2 commands. Do NOT do this if you have made changes that you don’t want to lose!

    +
    +
    +
    git fetch upstream
    +
    +
    +
    git reset --hard upstream/master
    -
    -

    Developer Contributing Information

    -
    -
    -

    Development Guidelines and Conventions

    -
    - + +
    -

    Project Source Code Formatting

    +

    Build Windup Using Red Hat JBoss Developer Studio or Eclipse

    -

    All project source code contributed to Windup should be formatted using the settings defined in the Eclipse_Code_Format_Profile.xml file located in the root directory of the Windup project.

    +

    If you prefer, you can use an IDE to build Windup.

    -
    -
    Eclipse IDE
    1. -

      In Eclipse, choose Windows → Preferences.

      +

      Make sure you have configured the Maven installation in your IDE as +described here: +Install +and Configure Maven.

    2. -

      Expand Java → Code Style → Formatter

      +

      Start JBoss Developer Studio or Eclipse.

    3. -

      Click Import

      +

      From the menu, select File → Import.

    4. -

      Browse to the Eclipse_Code_Format_Profile.xml located in the root of the Windup project directory, then click 'OK'.

      +

      In the selection list, choose Maven → Existing Maven Projects, +then click Next.

      +
      5. +
    5. +

      Click Browse and navigate to the root of the Windup +project directory, then click OK.

      +
      6. +
    6. +

      After all projects are listed, click Next. Ignore any Maven build +or dependency errors and click Finish. If you get a dialog titled +Incomplete Maven Goal Execution, ignore it and click OK to continue.

      +
      7. +
    7. +

      In the Project Explorer tab, find the windup_parent project in the +list, right-click, and choose Run As -→ Maven install.

    -
    -
    Netbeans IDE
    +
    +

    Extract the Windup Distribution Source File

    -

    Use this file to format Windup source code:

    +

    The build process creates a windup-distribution-2.0.0-SNAPSHOT-offline.zip file in the Windup source dist/target/ directory.

    -

    http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java

    +

    Unzip the dist/target/windup-distribution-2.0.0-SNAPSHOT-offline.zip file into a directory of your choice.

    -
    -
    IntelliJ IDEA
    -
    -

    Use this file to format Windup source code:

    +
    +

    Quick Build Review for Experienced Windup Developers

    +
    +
    +
    git clone git@github.com:windup/windup.git windup
+## Or if you haven't set up github account:
+#git clone https://github.com/windup/windup.git
+cd windup
+mvn clean install -DskipTests
+rm -rf /tmp/windup-zip/ /tmp/windup/
+unzip -q dist/target/windup-distribution-*-offline.zip -d /tmp/windup-zip
+mv /tmp/windup-zip/windup-distribution-* /tmp/windup
    -
    -

    http://plugins.jetbrains.com/plugin/?id=6546

    -
    -

    Source Code Naming Conventions

    -
    -
    Class Interface and Implementation Names
    +
    +

    Execute Windup (Built from Windup Source)

    +
    +

    These instructions are for Windup core developers who plan to build Windup from source to test code updates.

    +
    • -

      Do not name interfaces using the prefix 'I' for interface names. Instead, use a descriptive term for the interface, like Module.java.

      +

      If you are new to the project and not familiar with the procedures to execute Windup, see Execute Windup. It contains complete step-by-step instructions to execute Windup and also provides command line examples.

    • -

      The implementation class name should begin with a descriptive name, followed by the interface name, for example, for example JavaHandlerModule.java

      +

      Experienced users who need a refresher can follow the steps below.

      +
      +
      +
      mkdir tmp
+cd tmp
+unzip -q ../dist/target/windup-*.zip
+cd windup-*
+rm -rf ~/.forge/addons/
+bin/windup.sh
+
+## Execute Windup
+$ windup-migrate-app --input /home/username/work/Migration/TestApps/_apps/BradApp --output Report --packages org com net
+
+## Exit Windup
+$ exit
+
+## View the Report
+firefox Report/index.html
      +
      +
    -
    -
    Standard Prefixes and Suffixes
    -
    -
      +
      +

      Execute Windup

      +
      +

      Prerequisites

      +
      +

      Before you begin, you must gather the following information.

      +
      +
      +
      1. -

        Append all RuleProvider class names with RuleProvider.

        +

        The fully qualified path of the application archive or folder you plan to migrate.

      2. -

        Append all XML rule file names with .windup.xml

        -
        3. +

        The fully qualified path to a folder that will contain the resulting report information.

        +
        +
        • -

          Append all Model class names with Model.

          +

          If the folder does not exist, it is created by Windup.

        • -

          All test names should be prefixed with 'Test'.

          +

          If the folder exists, you are prompted with the message:

          +
          +
          +
          Overwrite all contents of <OUTPUT_DIRECTORY> (anything already in the directory will be deleted)? [y/N]
          +
          +
          +
          +

          Choose "y" if you want Windup to delete and recreate the directory.

          +
        • -

          Property constants: TBD

          +

          If you are confident you want to overwrite the output directory, you can specify --overwrite on the command line to automatically delete and recreate the directory.

          +
          + + + + + +
          +
          Note
          +          		 +Be careful not to specify a directory that contains important information! +
          +
        -
      -
      -
      -

      Maven Project Naming Conventions

      -
      -
      Maven Module Names
      -
      -

      The following are not really accurate at this time. This is still TBD!

      -
      + +
    • +

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

      • -

        Lowercase with dashes. Start with windup-.

        +

        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.

      • -

        Ruleset addons start with windup-rules-.

        +

        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.

      +
      • +
      -
      -
      -

      Submit Code Updates to the Windup Project

      +
      +

      Start Windup

      -

      To get the Windup Source Code, see Get the Windup Source Code for instructions.

      +

      For information about the use of WINDUP_HOME in the instructions below, see About the WINDUP_HOME Variable.

      1. -

        Open a command terminal and navigate to the root of the Windup project directory.

        +

        Open a terminal and navigate to the WINDUP_HOME/bin directory

      2. -

        Create a new topic branch to contain your features, changes, or fixes using the git checkout command:

        +

        Type the following command to start Windup:

        -
         git checkout -b  <topic-branch-name> upstream/master
        -
        +
        For Linux:    WINDUP_HOME/bin $ ./windup
+For Windows:  C:\WINDUP_HOME\bin> windup
        -
        -

        If you are fixing a JIRA, it is a good practice to use the number in the -branch name. For example:

        +
        3. +
      3. +

        You are presented with the following prompt.

        -
        git checkout -b WINDUP-225 upstream/master
        +
        Using Windup at WINDUP_HOME
+
+ _       ___           __
+| |     / (_)___  ____/ /_  ______
+| | /| / / / __ \/ __  / / / / __ \
+| |/ |/ / / / / / /_/ / /_/ / /_/ /
+|__/|__/_/_/ /_/\__,_/\__,_/ .___/
+                          /_/
+
+JBoss Windup, version [ 2.0.0-VERSION ] - JBoss, by Red Hat, Inc. [ http://windup.jboss.org ]
+
+[windup-distribution-2.0.0-VERSION]$
        4. +
      +
      +
      +
      +

      Run Windup

      +
      +
      1. -

        Make changes or updates to the source files. Be sure to test the changes thoroughly!

        +

        The command to run Windup is windup-migrate-app.

      2. -

        When you are sure your updates are ready and working, use the git add command to add new or changed file contents to the -staging area.

        -
        -
        -
        git add <folder-name>/
-git add <file-name>
        +

        The following is a list of the most commonly used command line arguments.

        +
        +
        +
        --input INPUT_ARCHIVE_OR_FOLDER
        +
        +

        This is the fully qualified application archive or source path.

        +
        +
        --source-mode true (optional)
        +
        +

        This argument is optional and is only required if the application to be evaluated contains source files rather than compiled binaries. The default value is false.

        +
        +
        --output OUTPUT_REPORT_DIRECTORY
        +
        +

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

        +
        + + + + + +
        +
        Note
        +        		 +If the OUTPUT_REPORT_DIRECTORY directory exists and you do not specify the --overwrite argument, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! +
        +
        +
        --overwrite (optional)
        +
        +

        Specify this optional argument only if you are certain you want to force Windup to delete the existing OUTPUT_REPORT_DIRECTORY. The default value is false.

        +
        +
        --packages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
        +
        +

        This is a comma-delimited list of the packages to be evaluated by Windup.

        +
        +
        --excludePackages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
        +
        +

        This is a comma-delimited list of the packages to be excluded by Windup.

        +
        +
      3. -

        Use the git status command to view the status of the files in the -directory and in the staging area and ensure that all modified files are -properly staged:

        +

        To evaluate an application archive, use the following syntax:

        -
        git status
        +
        windup-migrate-app --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
        -
        4. -
      4. -

        Commit your changes to your local topic branch. For example:

        +
        +

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

        +
        -
        git commit -m 'WINDUP-225: Description of change...'
        +
        windup-migrate-app --sourceMode true --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
        +
        +

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

        +
      5. -

        Push your local topic branch to your GitHub forked repository. This -will create a branch on your GitHub fork repository with the same name as -your local topic branch name.

        +

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

        -
        git push origin HEAD
        -
        +
        ***SUCCESS*** Windup execution successful!
        -
        -

        Note: The above command assumes your remote repository is named -'origin'. You can verify your forked remote repository name using the -command `git remote -v`.

      6. -

        Browse to the newly created branch on your forked GitHub repository.

        +

        To exit Windup, type:

        -
        https://github.com/<your-username>/windup/tree/<topic-branch-name>
        +
        exit
      7. -

        Open a Pull Request. For details, see -Using Pull -Requests.

        -
        -
          -
        • -

          Give the pull request a clear title and description.

          +

          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
          +
          +
        • -

          Review the modifications that are to be submitted in the pull to be sure it contains -only the changes you expect.

          +

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

          • -
        +
      +
      +
      +
      +

      Run Windup in Batch Mode

      +
      +

      Windup can be also executed in batch mode within a shell or batch script using the --evaluate argument as follows.

      +
      +
        +
      1. +

        Open a terminal and navigate to the WINDUP_HOME directory.

      2. -

        The pull request will be reviewed and merged by a Windup project administrator.

        +

        Type the following command to run Windup in batch mode:

        +
        +
        +
        For Linux:     $ bin/windup --evaluate "windup-migrate-app --input INPUT_ARCHIVE --output OUTPUT_REPORT --packages PACKAGE_1 PACKAGE_2 PACKAGE_N"
+For Windows:   > bin\windup.bat --evaluate "windup-migrate-app --input INPUT_ARCHIVE --output OUTPUT_REPORT --packages PACKAGE_1 PACKAGE_2 PACKAGE_N"
        +
        +
      -
      -
    -
    -

    Understand the Windup Architecture and Structure

    -
    -
    -

    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

    +

    Windup Help

    -

    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.

    +

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

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

    Forge Furnace

    +

    Windup Command Examples

    -

    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.

    +

    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
    -
    -

    TinkerPop

    +
    +
    +
    Archive Example
    -

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

    +

    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
    -
    -

    Titan

    +
    +
    +
    Windup Batch Example
    -

    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.

    +

    The following Windup batch 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.

    +
    +
    +
    +
    For Linux: $ bin/windup --evaluate "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"
+For Windows: > bin\windup.bat --evaluate "windup-migrate-app --input \windup-source\test-files\jee-example-app-1.0.0.ear --output \windup-reports\jee-example-app-1.0.0.ear-report --packages com.acme org.apache
    -
    -

    Frames

    +
    +
    +
    Windup Quickstart Examples
    -

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

    +

    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.

    -

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

    +

    The quickstarts provide examples of Java-based and XML-based rules 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 rules.

    +
    +
    +
    +

    Review the Report

    -

    Gremlin

    +

    About the Report

    -

    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.

    +

    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

      +
      • +
    -
    -

    Blueprints

    -

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

    +

    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
    +
    -

    Pipes

    +

    Open the Report

    -

    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.

    +

    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

    -
    -

    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.

    +

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

    -

    OCPsoft Rewrite

    +

    Report Sections

    +
    +
    Application Report Page
    -

    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.

    +

    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

    -
    -

    Windup Project Structure

    +
    +
    Archive Analysis Sections
    -

    The Windup 2.0 project consists of the following subprojects.

    +

    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.

    -
    config/
    -
    -

    This project is for the engine that runs the rules and abstracts the graph operations.

    -
    -
    decompiler/
    -
    -

    This subproject contains an API that wraps calls to the decompiler. -Windup currently uses only one decompiler: Procyon

    -
    -
    exec/
    -
    -

    This subproject contains the bootstrap code to run the Windup application.

    -
    -
    ext/
    -
    -

    This subproject is for code extensions. It currently only contains the -Groovy rules syntax. Eventually it will contain any code that is not -related to the rules or the core code base.

    -
    -
    graph/
    -
    -

    This subproject contains the datastore and Frames extensions.

    -
    -
    logging/
    -
    -

    This is the logging subproject. This subproject may be removed, depending on the outcome of this JIRA: WINDUP-49.

    -
    -
    reporting/
    -
    -

    This subproject contains code that does reporting.

    -
    -
    rules/
    -
    -

    This subproject contains all the rules.

    -
    -
    test-files/
    -
    -

    This subproject contains the demo applications that are used for test input.

    -
    -
    tests/
    +
    Name
    -

    This subproject contains the integration test suite.

    +

    The name of the file being analyzed

    -
    tinkerpop/
    +
    Technology
    -

    This subproject contains a code fix for Titan NPE issues.

    +

    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

      +
      • +
    +
    -
    ui/
    +
    Issues
    -

    This subproject contains experimental Forge UI code.

    +

    Warnings about areas of code that need review or changes.

    -
    utils/
    +
    Estimated Story Points
    -

    This subproject contains all utility code.

    +

    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

    -
    -

    Get Started

    -
    -
    -

    Install and Configure Maven

    +
    +
    File Analysis Pages
    -

    If you plan to contribute to the core code base or create Java-based rule addons, you must first install and configure Maven to build Windup from source.

    +

    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.

    -
    -

    Download and Install Maven

    -
    -

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

    -
    -
    -

    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 Apache Maven Project - -Download Maven and download the latest distribution for your operating -system.

        +

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

      • -

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

        +

        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.

    -
    -

    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.

    +

    File Detail - Part 1

    -
    -
      -
    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. -
    +
    +

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

    -

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

    +

    File Detail - Part 2

    +
    -

    Configure Maven to Build Windup

    +

    Additional Reports

    -

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

    +

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

    -
    -
      -
    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>
      +
      +
      Rule Provider Execution Report
      +
      +

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

      +
      +

      RuleProvider Report

      -
      3. -
    3. -

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

      -
      -
      -
      <activeProfile>jboss-nexus-repository</activeProfile>
      +
      +
      Rule Provider Execution Report
      +
      +

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

      -
      4. -
    +
    +
    Individual File Analysis Reports
    -

    You are now configured to build Windup.

    +

    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

    -
    -

    Get the Windup Source Code

    -
    -

    To contribute to the Windup 2.0 project source code, you must fork the Windup repository to your own Git, clone your fork, commit your work on topic branches, and make pull requests back to the Windup repository.

    -
    -

    Install the Git Client

    -
    -

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

    +
    +
    +

    Developer Contributing Information

    +
    +
    +

    Development Guidelines and Conventions

    -
    -

    Fork and Clone the Windup Repository

    +

    Project Source Code Formatting

    +
    +

    All project source code contributed to Windup should be formatted using the settings defined in the Eclipse_Code_Format_Profile.xml file located in the root directory of the Windup project.

    +
    +
    +
    Eclipse IDE
    1. -

      Fork the Windup project. This -creates the windup project in your own Git with the default remote -name 'origin'.

      -
      2. -
    2. -

      Clone your fork. This creates and populates a directory in your -local file system.

      -
      -
      -
      git clone https://github.com/<your-username>/windup.git
      -
      -
      +

      In Eclipse, choose Windows → Preferences.

    3. -

      Change to the windup directory.

      +

      Expand Java → Code Style → Formatter

    4. -

      Add the remote upstream repository so you can fetch any changes to -the original forked repository.

      -
      -
      -
      git remote add upstream git@github.com:windup/windup.git
      -
      -
      +

      Click Import

    5. -

      Get the latest files from the upstream repository.

      -
      -
      -
      git fetch upstream
      -
      -
      +

      Browse to the Eclipse_Code_Format_Profile.xml located in the root of the Windup project directory, then click 'OK'.

    -
    -
    -

    Build Windup from Source

    -
    -

    This information is provided for new developers who plan to contribute code -to the Windup open source project. This section describes how to build Windup from source and how to extract the Windup distribution that is created during the build process.

    -
    +
    +
    Netbeans IDE
    -

    If you use Linux and are an experienced Windup developer looking for a quick refresher, jump to: Quick Build Review for Experienced Windup Developers.

    +

    Use this file to format Windup source code:

    -
    -

    System Requirements to Build Windup

    -
    -
      -
    1. -

      Java 1.7.

      -

      You can choose from the following:

      -
      -
      -
      -
      OpenJDK
-Oracle Java SE
      +

      http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java

      -
      2. -
    2. -

      Maven 3.1.1 or newer

      +
      +
      IntelliJ IDEA
      -

      If you have not yet installed or configured Maven, see -Install and Configure Maven for details.

      +

      Use this file to format Windup source code:

      -

      If you have installed Maven, you can check the version by typing the -following in a command prompt:

      -
      -
      -
      -
      mvn --version
      +

      http://plugins.jetbrains.com/plugin/?id=6546

      -
      3. -
    3. -

      IDE requirements

      -
      -

      If you prefer, you can work within an IDE. The following IDEs are recommended.

      +
      +

      Source Code Naming Conventions

      +
      +
      Class Interface and Implementation Names
      • -

        Red Hat JBoss -Developer Studio 7.1.1 or newer

        +

        Do not name interfaces using the prefix 'I' for interface names. Instead, use a descriptive term for the interface, like Module.java.

      • -

        Eclipse 4.3 (Kepler) or newer

        +

        The implementation class name should begin with a descriptive name, followed by the interface name, for example, for example JavaHandlerModule.java

      -
      -

      You must also make sure the IDE embeds Maven 3.1.1 or later. See -Install and Configure Maven for details.

      +
      +
      Standard Prefixes and Suffixes
      +
      +
        +
      • +

        Append all RuleProvider class names with RuleProvider.

        • -
    +
  • +

    Append all XML rule file names with .windup.xml

    +
    • +
  • +

    Append all Model class names with Model.

    +
    • +
  • +

    All test names should be prefixed with 'Test'.

    +
    • +
  • +

    Property constants: TBD

    +
    • + +
    -

    Build Windup Using Maven Command Line

    -
    -
      +

      Maven Project Naming Conventions

      +
      +
      Maven Module Names
      +
      +

      The following are not really accurate at this time. This is still TBD!

      +
      +
      + +
      +
      +
    +
    +
    +

    Submit Code Updates to the Windup Project

    +
    +

    To get the Windup Source Code, see Get the Windup Source Code for instructions.

    +
    +
    +

    1. Open a command terminal and navigate to the root of the Windup project directory.

      +
      2. +
    2. +

      Create a new topic branch to contain your features, changes, or fixes using the git checkout command:

      -
          cd Windup/
      +
       git checkout -b  <topic-branch-name> upstream/master
      -
      3. -
    3. -

      To create a branch and build Windup using the latest version of the source code:

      -
      -
        -
      • -

        Fetch the latest source code from the upstream repository.

        +
        +

        If you are fixing a JIRA, it is a good practice to use the number in the +branch name. For example:

        +
        -
        git fetch upstream
        +
        git checkout -b WINDUP-225 upstream/master
      • -

        Checkout a local copy of the branch.

        +

        Make changes or updates to the source files. Be sure to test the changes thoroughly!

        +
        • +
      • +

        When you are sure your updates are ready and working, use the git add command to add new or changed file contents to the +staging area.

        -
        git checkout -b BRANCH_NAME upstream/master
        -
        +
        git add <folder-name>/
+git add <file-name>
        -
        • -
    4. -

      If, at any point, you want to toss your changes and reset your local branch to the contents of the upstream repository, issue the following 2 commands. Do NOT do this if you have made changes that you don’t want to lose!

      +

      Use the git status command to view the status of the files in the +directory and in the staging area and ensure that all modified files are +properly staged:

      -
      git fetch upstream
      +
      git status
      +
      5. +
    5. +

      Commit your changes to your local topic branch. For example:

      -
      git reset --hard upstream/master
      +
      git commit -m 'WINDUP-225: Description of change...'
    6. -

      Build the project.

      +

      Push your local topic branch to your GitHub forked repository. This +will create a branch on your GitHub fork repository with the same name as +your local topic branch name.

      -
      mvn clean install
      +
      git push origin HEAD
      -

      You can also build the project without the tests.

      +

      Note: The above command assumes your remote repository is named +'origin'. You can verify your forked remote repository name using the +command `git remote -v`.

      +
      7. +
    7. +

      Browse to the newly created branch on your forked GitHub repository.

      -
      mvn clean install -DskipTests
      -
      -
      -
      8. -
    -
    +
    https://github.com/<your-username>/windup/tree/<topic-branch-name>
    -
    -

    Build Windup Using Red Hat JBoss Developer Studio or Eclipse

    -
    -

    If you prefer, you can use an IDE to build Windup.

    -
    -
      -
    1. -

      Make sure you have configured the Maven installation in your IDE as -described here: -Install -and Configure Maven.

      -
      2. -
    2. -

      Start JBoss Developer Studio or Eclipse.

    3. -

      From the menu, select File → Import.

      -
      4. +

      Open a Pull Request. For details, see +Using Pull +Requests.

      +
      +
      • -

        In the selection list, choose Maven → Existing Maven Projects, -then click Next.

        +

        Give the pull request a clear title and description.

      • -

        Click Browse and navigate to the root of the Windup -project directory, then click OK.

        +

        Review the modifications that are to be submitted in the pull to be sure it contains +only the changes you expect.

        • -
      • -

        After all projects are listed, click Next. Ignore any Maven build -or dependency errors and click Finish. If you get a dialog titled -Incomplete Maven Goal Execution, ignore it and click OK to continue.

        +
      +
    4. -

      In the Project Explorer tab, find the windup_parent project in the -list, right-click, and choose Run As -→ Maven install.

      +

      The pull request will be reviewed and merged by a Windup project administrator.

    -
    -

    Extract the Windup Distribution Source File

    +
    + +
    +

    Understand the Windup Architecture and Structure

    +
    +
    +

    Windup Architectural Components

    -

    The build process creates a windup-distribution-2.0.0-SNAPSHOT-offline.zip file in the Windup source dist/target/ directory.

    +

    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

    -

    Unzip the dist/target/windup-distribution-2.0.0-SNAPSHOT-offline.zip file into a directory of your choice.

    +

    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.

    -

    Quick Build Review for Experienced Windup Developers

    -
    -
    -
    git clone git@github.com:windup/windup.git Windup
-cd Windup
-mvn clean install -DskipTests
-rm -rf /tmp/windup-zip/ /tmp/windup/
-unzip -q dist/target/windup-distribution-*-offline.zip -d /tmp/windup-zip
-mv /tmp/windup-zip/windup-distribution-* /tmp/windup
    +

    Forge Furnace

    +
    +

    Forge Furnace is a modular runtime container behind Forge that provides +the ability to run Forge add-ons 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.

    -
    -

    Execute Windup (Built from Windup Source)

    +
    +

    Titan

    -

    These instructions are for Windup core developers who plan to build Windup from source to test code updates.

    +

    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.

    -
    -
      -
    • -

      If you are new to the project and not familiar with the procedures to execute Windup, see Execute Windup. It contains complete step-by-step instructions to execute Windup and also provides command line examples.

      -
      • -
    • -

      Experienced users who need a refresher can follow the steps below.

      -
      -
      -
      mkdir tmp
-cd tmp
-unzip -q ../dist/target/windup-*.zip
-cd windup-*
-rm -rf ~/.forge/addons/
-bin/windup.sh
-
-## Execute Windup
-$ windup-migrate-app --input /home/username/work/Migration/TestApps/_apps/BradApp --output Report --packages org com net
-
-## Exit Windup
-$ exit
-
-## View the Report
-firefox Report/index.html
      +
      +

      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.

    -
    -

    Execute Windup

    -

    Prerequisites

    +

    Gremlin

    -

    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 also specify the fully qualified path to a folder that will contain the resulting report information. This path is passed using the --output argument on the command line.

      -
      -
        -
      • -

        If the folder does not exist, it is created by Windup.

        -
        • -
      • -

        If the folder exists, you are prompted with the message:

        -
        -
        -
        Overwrite all contents of <OUTPUT_DIRECTORY> (anything already in the directory will be deleted)? [y/N]
        +

        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

        -

        Choose "y" if you want Windup to delete and recreate the directory.

        -
        -
        • -
      • -

        If you are confident you want to overwrite the output directory, you can specify --overwrite on the command line to automatically delete and recreate the directory.

        -
        - - - - - -
        -
        Note
        -        		 -Be careful not to specify a directory that contains important information! -
        +

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

        -
        • -
      -
      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.

        -
        • -
      +
      +

      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.

      -
      4. -
    +
    +
    +

    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.

    -

    Start Windup

    +

    OCPsoft Rewrite

    -

    For information about the use of WINDUP_HOME in the instructions below, see About the WINDUP_HOME Variable.

    +

    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.

    -
    -
      -
    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 WINDUP_HOME
-
- _       ___           __
-| |     / (_)___  ____/ /_  ______
-| | /| / / / __ \/ __  / / / / __ \
-| |/ |/ / / / / / /_/ / /_/ / /_/ /
-|__/|__/_/_/ /_/\__,_/\__,_/ .___/
-                          /_/
-
-JBoss Windup, version [ 2.0.0-VERSION ] - JBoss, by Red Hat, Inc. [ http://windup.jboss.org ]
-
-[windup-distribution-2.0.0-VERSION]$
      +
      +

      Windup Project Structure

      +
      +

      The Windup 2.0 project consists of the following subprojects.

      +
      +
      +
      config/
      +
      +

      This project is for the engine that runs the rules and abstracts the graph operations.

      +
      +
      decompiler/
      +
      +

      This subproject contains an API that wraps calls to the decompiler. +Windup currently uses only one decompiler: Procyon

      +
      +
      exec/
      +
      +

      This subproject contains the bootstrap code to run the Windup application.

      +
      +
      ext/
      +
      +

      This subproject is for code extensions. It currently only contains the +Groovy rules syntax. Eventually it will contain any code that is not +related to the rules or the core code base.

      +
      +
      graph/
      +
      +

      This subproject contains the datastore and Frames extensions.

      +
      +
      logging/
      +
      +

      This is the logging subproject. This subproject may be removed, depending on the outcome of this JIRA: WINDUP-49.

      +
      +
      reporting/
      +
      +

      This subproject contains code that does reporting.

      +
      +
      rules/
      +
      +

      This subproject contains all the rules.

      +
      +
      test-files/
      +
      +

      This subproject contains the demo applications that are used for test input.

      +
      +
      tests/
      +
      +

      This subproject contains the integration test suite.

      +
      +
      tinkerpop/
      +
      +

      This subproject contains a code fix for Titan NPE issues.

      +
      +
      ui/
      +
      +

      This subproject contains experimental Forge UI code.

      +
      +
      utils/
      +
      +

      This subproject contains all utility code.

      +
      +
      -
      4. -
    -
    -

    Run the windup-migrate-app Command

    -
    -
      -
    1. -

      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
      +
      +

      Rules and Rulesets

      +
      +
      +

      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.

      -

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

      +

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

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

      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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

      +
      +

      For more information about the phases of rule execution and how to control rule dependencies, see Rule Execution Lifecycle.

      -

      Where:

      +

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

      +
      +
      +

      Application Migration

      -

      INPUT_ARCHIVE_OR_FOLDER is the fully qualified application archive or source path

      +

      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.

      -

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

      +

      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.

      -
      - - - - - -
      -
      Note
      -      		 -If the OUTPUT_REPORT_DIRECTORY directory exists, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! -
      +
      +

      Generate Findings Based on the Rule Execution Results

      -

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

      +

      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.

      -

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

      +

      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:

      -
      2. +
      +
      • -

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

        -
        -
        -
        ***SUCCESS*** Windup execution successful!
        -
        -
        +

        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.

      • -

        To exit Windup, type:

        -
        -
        -
        exit
        -
        -
        +

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

      • -

        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
        +

        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.

      - -
    2. -

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

      -
      3. -
    +
    +

    Rule Execution Lifecycle

    -

    Run Windup in Batch Mode

    +

    Rule Lifecycle

    -

    Windup can be also executed in batch mode within a shell or batch script using the --evaluate argument as follows.

    -
    -
    -
      -
    1. -

      Open a terminal and navigate to the WINDUP_HOME directory.

      -
      2. -
    2. -

      Type the following command to run Windup in batch mode:

      -
      -
      -
      For Linux:     $ bin/windup --evaluate "windup-migrate-app --input INPUT_ARCHIVE --output OUTPUT_REPORT --packages PACKAGE_1 PACKAGE_2 PACKAGE_N"
-For Windows:   > bin\windup.bat --evaluate "windup-migrate-app --input INPUT_ARCHIVE --output OUTPUT_REPORT --packages PACKAGE_1 PACKAGE_2 PACKAGE_N"
      -
      +

      Windup executes each rule in a sequential order. 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.

      -
      3. -
    +
    +

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

    -

    Windup Help

    -
    -

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

    -
    -
    +

    Rule Phases

    +
    -
    man windup-migrate-app
    -
    +
    INFO: Loaded [67] org.jboss.windup.config.WindupRuleProvider [
+org.jboss.windup.config.phase.Implicit
+org.jboss.windup.config.phase.Initialization
+org.jboss.windup.config.phase.Discovery
+org.jboss.windup.config.phase.ArchiveExtraction
+org.jboss.windup.config.phase.ArchiveMetadataExtraction
+org.jboss.windup.config.phase.ClassifyFileTypes
+org.jboss.windup.config.phase.DiscoverProjectStructure
+org.jboss.windup.config.phase.Decompilation
+org.jboss.windup.config.phase.InitialAnalysis
+org.jboss.windup.config.phase.MigrationRules
+org.jboss.windup.config.phase.PostMigrationRules
+org.jboss.windup.config.phase.PreReportGeneration
+org.jboss.windup.config.phase.ReportGeneration
+org.jboss.windup.config.phase.PostReportGeneration
+org.jboss.windup.config.phase.ReportRendering
+org.jboss.windup.config.phase.PostReportRendering
+org.jboss.windup.config.phase.Finalize
+org.jboss.windup.config.phase.PostFinalize
+]
    -
    -

    Windup Command Examples

    -

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

    +

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

    -
    -
    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.

    +

    Rule phases provide a 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.

    -
    +
    -
    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
    -
    +
    @Override
+public RulePhase getPhase() {
+    return InitialAnalysis.class;
+}
    -
    -
    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.

    +

    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.

    -
    -
    -
    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
    +
    +
    +
    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 phase 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.

    -
    -
    Windup Batch Example
    +
    +

    Execute Before and Execute After

    -

    The following Windup batch 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.

    +

    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.

    -
    For Linux: $ bin/windup --evaluate "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"
-For Windows: > bin\windup.bat --evaluate "windup-migrate-app --input \windup-source\test-files\jee-example-app-1.0.0.ear --output \windup-reports\jee-example-app-1.0.0.ear-report --packages com.acme org.apache
    -
    +
    @Override
+public List<Class<? extends WindupRuleProvider>> getExecuteBefore()
+{
+   return asClassList(RuleToFireBefore.class);
+}
    -
    -
    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.

    +

    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.

    -
    -

    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.

    +
    +
    +
    @Override
+public List<Class<? extends WindupRuleProvider>> getExecuteAfter()
+{
+    return asClassList(RuleToFireAfter.class);
+}
    -

    Review the Report

    +

    Rule Story Points

    -

    About the Report

    +

    What are Story Points?

    -

    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:

    +

    Story points are an abstract metric commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. 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. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

    +
    +
    +
    +

    How Story Points are Estimated in Rules

    +
    +

    Estimating story points for a rule can be tricky. The following are the general guidelines Windup uses when estimating the level of effort required for a rule.

    +
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Level of EffortStory PointsDescription

    Lift and Shift

    0

    The code or file is standards-based and requires no effort.

    Mapped

    1- 2 per file

    There is a standard mapping algorithm to port the code or file. The number of story points required is small, but is dependent on the number of files to port.

    Custom

    5 - 20 per change or component

    +

    The number of story points required to modify and rewrite code depends on the complexity of the change, the number of unknown imports, the size of the files, and the number of components. The following are examples of how to estimate story points.

    • -

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

      -
      • -
    • -

      archives/: Contains the archives extracted from the application

      +

      Port MyBatis to JPA: '20' story points per query.

    • -

      graph/: Contains binary graph database files

      +

      Port a web page from one web framework to another depends on the complexity and the number of components involved in the migration. You could estimate '20' story points per component.

      • +
    +
    +
    +
    +
    +

    Difference Between XML-based and Java-based Rules

    +
    +

    First of all, to prevent confusion:

    +
    +
    1. -

      reports/: This directory contains the generated HTML report files

      +

      Rules can be written using XML or the Java API. We call them XML-based and Java-based Rules.

    2. -

      stats/: Contains Windup performance statistics

      +

      Independent of the syntax, the rules may inspect (classify) XML or Java code.

      3. - +
    -

    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
    -
    +

    See the examples below.

    -

    Open the Report

    +

    Which one to choose?

    -

    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

    +

    The XML rules provide a quick, simple way to create rules to analyze Java and XML files. Java rules provide the ability to create very complex rules.

    -
    -

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

    +
    +
      +
    • +

      If you simply need to highlight a specific section of Java code or XML file content and provide hints for it, it is recommended that you create the rule using XML.

      +
      • +
    • +

      If you need to create a new custom report, you need to create the reporting rules using Java.

      +
      • +
    • +

      If you need to extend functionality beyond what the XML rules provide, you need to create the rule using Java.

      +
      • +
    -

    Report Sections

    -
    -
    Application Report Page
    +

    Pros and cons - XML

    -

    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.

    +

    Pros:

    • -

      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.

      +

      XML rules are fairly easy to write and require less code.

    • -

      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.

      +

      You do not need to configure Maven to build from source because there is no need for compilation of +XML rules.

      +
      • +
    • +

      Deployment is simple. You simply drop the XML rule into the appropriate path and Windup automatically scans the new rule.

    -

    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.

    +

    Cons:

    -
    -
    -
    Name
    -
    -

    The name of the file being analyzed

    -
    -
    Technology
    -
    -

    The type of file being analyzed. For example:

    • -

      Java Source

      +

      XML rules only support a simple subset of conditions and operations.

    • -

      Decompiled Java File

      +

      XML rules do not provide for direct custom graph data manipulation.

    • -

      Manifest

      +

      XML rules do not support the ability to create custom reports.

      • +
    +
    +
    +
    +

    Pros and Cons - Java

    +
    +

    Pros:

    +
    +
    +
    • -

      Properties

      +

      Java rule add-ons allow you to write custom rules and provide a lot of flexibility.

    • -

      EJB XML

      +

      You can set breakpoints and test Java rule add-ons using a debugger.

    • -

      Spring XML

      -
      • -
    • -

      Web XML

      -
      • -
    • -

      Hibernate Cfg

      -
      • -
    • -

      Hibernate Mapping

      +

      IDEs provide code completion for the Windup API.

    - -
    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.

    +

    Cons:

    • -

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

      +

      You must configure Maven to compile the Windup Java rule add-ons.

    • -

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

      +

      Java rule add-ons that are not included in the Windup core code base must be a full Forge add-on.

      +
      • +
    • +

      Java rule add-ons require writing a lot of Java code/

      +
      • +
    • +

      Writing Java rule add-ons are complex and required knowledge of Windup internals.

    -
    -

    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.

    +
    +

    Examples

    -

    File Detail - Part 1

    +

    Example of a rule written in XML classifying Java code:

    +
    +
    +
    +
    <?xml version="1.0"?>
+<ruleset xmlns="http://windup.jboss.org/v1/xml" id="EjbRules">
+    <rules>
+        <rule id="EjbRules_2fmb">
+            <when>
+                <javaclass references="javax.persistence.Entity" as="default">
+                    <location>TYPE</location>
+                </javaclass>
+            </when>
+            <perform>
+                <iteration>
+                    <classification classification="JPA Entity" effort="0"/>
+                </iteration>
+            </perform>
+        </rule>
+    </rules>
+</ruleset>
    -
    -

    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

    +

    Example of a rule written in Java classifying Java code:

    +
    +
    +
    +
    /**
+ * Scans for classes with EJB related annotations, and adds EJB related metadata for these.
+ */
+public class DiscoverEjbAnnotationsRuleProvider extends WindupRuleProvider
+{
+    @Override
+    public Configuration getConfiguration(GraphContext context) {
+        return ConfigurationBuilder.begin()
+        .addRule()
+        .when(JavaClass.references("javax.ejb.{annotationType}").at(TypeReferenceLocation.ANNOTATION))
+        .perform(new AbstractIterationOperation<JavaTypeReferenceModel>()
+        {
+            public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload)
+            {
+                extractEJBMetadata(event, payload);
+            };
+        })
+        .where("annotationType").matches("Stateless|Stateful")
+        .withId(ruleIDPrefix + "_StatelessAndStatefulRule")
+        .addRule()
+        .when(JavaClass.references("javax.ejb.MessageDriven").at(TypeReferenceLocation.ANNOTATION))
+        .perform(new AbstractIterationOperation<JavaTypeReferenceModel>() {
+            @Override
+            public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) {
+                extractMessageDrivenMetadata(event, payload);
+            }
+        })
+        .withId(ruleIDPrefix + "_MessageDrivenRule")
+        .addRule()
+        .when(JavaClass.references("javax.persistence.Entity").at(TypeReferenceLocation.ANNOTATION).as(ENTITY_ANNOTATIONS)
+                    .or(JavaClass.references("javax.persistence.Table").at(TypeReferenceLocation.ANNOTATION).as(TABLE_ANNOTATIONS_LIST)))
+        .perform(Iteration.over(ENTITY_ANNOTATIONS).perform(new AbstractIterationOperation<JavaTypeReferenceModel>() {
+            @Override public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) {
+                extractEntityBeanMetadata(event, payload);
+            }
+        }).endIteration())
+        .withId(ruleIDPrefix + "_EntityBeanRule");
+    }
+    ...
+}
    -

    Additional Reports

    -
    -

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

    -
    -
    -
    Rule Provider Execution Report
    +

    Summary

    -

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

    +

    The following is a draft…​ it may go.

    -
    -

    RuleProvider Report

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RequirementXML RuleJava Rule Add-on

    Easy to write?

    Yes

    Depends on the complexity of the rule

    Requires that you configure Maven?

    No

    Yes

    Requires that you compile the rule?

    No

    Yes

    Simple deployment?

    No

    Yes

    Supports custom reports?

    No

    Yes

    Ability to create complex conditions and operations?

    No

    Yes

    Ability to directly manipulate the graph data?

    No

    Yes

    -
    -
    Rule Provider Execution Report
    -
    -

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

    -
    -
    Individual File Analysis Reports
    +
    +

    Create and Test Java Rule Add-ons

    +
    +
    +

    Install and Configure Maven

    -

    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.

    +

    If you plan to contribute to the core code base or create Java-based rule add-ons, you must first install and configure Maven to build Windup from source.

    +
    +

    Download and Install Maven

    -

    Report Directory File List

    +

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

    +
    +

    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. +
    -
    -

    Rules and Rulesets

    -
    -
    -

    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.

    +

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

    -
    -

    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

    +

    Configure Maven to Build Windup

    -

    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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    +

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

    -
    -

    For more information about the phases of rule execution and how to control rule dependencies, see Rule Execution Lifecycle.

    +
    +
      +
    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>
      -
      -

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

      +
      +
      3. +
    3. +

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

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

      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.

      +
      4. +
    -

    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.

    +

    You are now configured to build Windup.

    +
    +
    +

    Java-based Rule Structure

    +
    +

    TO_DO: Add a how-to for compound rules, nested rules, rules over multiple sources, negative queries (not matched by anything).

    +
    -

    Generate Findings Based on the Rule Execution Results

    +

    Windup Rule Provider

    -

    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.

    +

    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.

    -

    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:

    +

    Windup rule add-ons must extend the WindupRuleProvider class.

    • -

      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.

      +

      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 Rule Execution Lifecycle.

    • -

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

      +

      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.

    • -

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

      +

      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.

    -

    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 sequential order. 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 a graphical overview of rule processing, see -this -diagram.

    -
    -
    -
    -

    Rule Phases

    -
    -
    -
    INFO: Loaded [67] org.jboss.windup.config.WindupRuleProvider [
-org.jboss.windup.config.phase.Implicit
-org.jboss.windup.config.phase.Initialization
-org.jboss.windup.config.phase.Discovery
-org.jboss.windup.config.phase.ArchiveExtraction
-org.jboss.windup.config.phase.ArchiveMetadataExtraction
-org.jboss.windup.config.phase.ClassifyFileTypes
-org.jboss.windup.config.phase.DiscoverProjectStructure
-org.jboss.windup.config.phase.Decompilation
-org.jboss.windup.config.phase.InitialAnalysis
-org.jboss.windup.config.phase.MigrationRules
-org.jboss.windup.config.phase.PostMigrationRules
-org.jboss.windup.config.phase.PreReportGeneration
-org.jboss.windup.config.phase.ReportGeneration
-org.jboss.windup.config.phase.PostReportGeneration
-org.jboss.windup.config.phase.ReportRendering
-org.jboss.windup.config.phase.PostReportRendering
-org.jboss.windup.config.phase.Finalize
-org.jboss.windup.config.phase.PostFinalize
-]
    -
    -
    -
    -

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

    -
    -
    -

    Rule phases provide a 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 InitialAnalysis rule phase.

    -
    -
    -
    -
    @Override
-public RulePhase getPhase() {
-    return InitialAnalysis.class;
-}
    -
    -
    -
    -

    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.

    -
    -
    -
    -
    @Override
-public List<Class<? extends WindupRuleProvider>> getExecuteBefore()
-{
-   return asClassList(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.

    -
    -
    -
    -
    @Override
-public List<Class<? extends WindupRuleProvider>> getExecuteAfter()
-{
-    return asClassList(RuleToFireAfter.class);
-}
    -
    -
    -
    -
    -
    -

    Rule Story Points

    -
    -

    What are Story Points?

    -
    -
    DRAFT
    -

    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

    -
    -

    Estimating story points for a rule can be tricky. The following are general guidelines or suggestions to use when estimating the level of effort required for a rule.

    -
    - ----- - - - - - - - - - - - - - - - - - - - - - - - - -
    Level of EffortStory PointsDescription

    Lift and Shift

    0

    The code or file is standards-based and requires no effort.

    Mapped

    1- 2 per file

    There is a standard mapping algorithm to port the code or file. The number of story points required is small, but dependent on the number of files to port.

    Custom

    5 - 20 per change or component

    -

    The number of story points required to modify and rewrite code depends on the complexity of the change, the number of unknown imports, the size of the files, and the number of components. The following are examples of how to estimate story points.

    -
    -
    -
      -
    • -

      Port MyBatis to JPA: '20' story points per query.

      -
      • -
    • -

      Port a web page from one web framework to another depends on the complexity and the number of components involved in the migration. You could estimate '20' story points per component.

      -
      • -
    -
    -
    -
    -
    -
    -
    -

    Create and Test Java Rule Add-ons

    -
    -
    -

    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 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.

    +

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

    @@ -2744,7 +2888,7 @@
    Iteration
    Nested iterations
    -

    TODO

    +

    TO_DO: Provide information about nested iterations

    @@ -2773,7 +2917,7 @@
    otherwise
    Where
    -

    TODO

    +

    TO_DO: Provide information about the where clause

    @@ -2804,7 +2948,7 @@

    Available utilities

    Basic Rule Execution Flow Patterns

    -

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

    +

    TO_DO: Need some links to github to the respective example files.

    operation(); - single operation

    @@ -3130,371 +3274,1226 @@
    Create a Maven Project
    </plugins>
    - - + + +
    +
    +
    +
    Create the Java RuleProvider
    +
    +
      +
    1. +

      Add beans.xml file to META-INF/ dir in resources - typically, $project-dir/src/main/resources/META-INF/beans.xml. This file can be empty. It tells CDI to scan your add-on for CDI beans.

      +
      2. +
    2. +

      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
+{
+}
      +
      +
      +
      3. +
    3. +

      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.

      +
      +
      4. +
    4. +

      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);
+}
      +
      +
      +
      5. +
    5. +

      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

        +
        • +
      +
      +
      6. +
    +
    +
    +
    +
    +

    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.

    +
    +
    + +
    +
    +
    +
    +
    +
    +

    Create and Test XML Rules

    +
    +
    +

    Create a Basic XML Rule

    +
    +

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

    +
    +
    +

    Prerequisites

    +
    + +
    +
    +
    +

    File Naming Convention for XML Rules

    +
    +

    You must name the file containing an XML rule with the .windup.xml extension. Windup identifies files with this extension as XML-base rules, so be sure to use this naming convention, otherwise the rule will not be evaluated!

    +
    +
    +
    +

    Basic XML Rule Template

    +
    +

    XML rules consist of conditions and actions and follow the familiar "if/then/else" construct:

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

    The following is the basic syntax for XML rules.

    +
    +
    +
    +
    <?xml version="1.0"?>
+<ruleset xmlns="http://windup.jboss.org/v1/xml" id="XmlFileMappings">
+    <phase>
+        <!-- The phase in which to run the rules -->
+    </phase>
+    <rules>
+        <rule>
+            <when>
+                <!-- Test a condition... -->
+            </when>
+            <perform>
+                <!-- Perform this action when condition is satisfied -->
+            </perform>
+            <otherwise>
+                <!-- Perform this action when condition is not satisfied -->
+            </otherwise>
+        </rule>
+      <rules>
+    </ruleset>
    +
    +
    +
    +
    +

    Create the Rule When Condition

    +
    +

    The syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file, a project, or file content and is described in more detail here: XML Rule - When Condition Syntax

    +
    +
    +
    +

    Create the Rule Perform Action

    +
    +

    Operations allowed in the perform section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. The syntax is described in detail here: XML Rule - Perform Action Syntax.

    +
    +
    +
    +
    +

    XML Rule - When Condition Syntax

    +
    +

    Conditions allowed in the when portion of a rule must extend GraphOperaton and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    +
    +
    +

    The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd.

    +
    +
    +

    The following sections describe the more common XML when rule conditions.

    +
    +
    + +
    +
    +

    javaclass Syntax

    +
    +
    Summary
    +
    +

    Use the javaclass element to find imports, methods, variable declarations, annotations, class implementations, and other items related to Java classes. For a better understanding of the javaclass condition, see the JavaDoc for the JavaClass class.

    +
    +
    +

    The following is an example of a rule that tests for a javaclass.

    +
    +
    +
    +
    <rule>
+    <when>
+        <javaclass references="org.jboss.ws.api.annotation.WebContext" in="org/jboss/{*}" as="webcontextclasses">
+            <location>IMPORT</location>
+            <location>TYPE</location>
+        </javaclass>
+    </when>
+    <perform>
+        <hint message="WebContext is deprecated." effort="0"/>
+    </perform>
+</rule>
    +
    +
    +
    +
    +
    Construct a javaclass Element
    +
    +
    javaclass Element Attributes
    +
    +
    +
    references="CLASS_NAME"
    +
    +

    The package or class name to match on. Wildcard characters can be used.

    +
    +
    +
    Example: references="org.apache.commons.{*}"
    +
    +
    +
    +
    as="VARIABLE_NAME"
    +
    +

    A variable name assigned to the rule so that it can be used as a reference in later processing. See the from attribute below.

    +
    +
    +
    Example: as="MyEjbRule"
    +
    +
    +
    +
    in="PATH_FILTER"
    +
    +

    Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used.

    +
    +
    +
    Example: in="{*}File1"
    +
    +
    +
    +
    from="VARIABLE_NAME"
    +
    +

    Begin the search query with the filtered result from a previous search identified by its as VARIABLE_NAME.

    +
    +
    +
    Example: from="MyEjbRule"
    +
    +
    +
    +
    +
    +
    +
    +
    JavaClass Element Child Elements
    +
    +
    +
    location
    +
    +

    The location where the reference was found in a Java class. Location can refer to annotations, field and variable declarations, imports, and methods. For the complete list of valid values, see the JavaDoc for TypeReferenceLocation.

    +
    +
    +
    Example: <location>IMPORT</location>
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    xmlfile Syntax

    +
    +
    Summary
    +
    +

    Use the xmlfile element to find information in XML files. For a better understanding of the xmlfile condition, see the XmlFile JavaDoc.

    +
    +
    +

    The following is an example of a rule that tests for an xmlfile.

    +
    +
    +
    +
    <rule>
+    <when>
+        <xmlfile matches="/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 title="Title for Hint from XML">
+            <message>Container Auth</message>
+        </hint>
+        <xslt description="Example XSLT Conversion" extension="-converted-example.xml"
+              template="/exampleconversion.xsl"/>
+    </perform>
+</rule>
    +
    +
    +
    +
    +
    Construct an xmlfile Element
    +
    +
    xmlfile Element: Attributes
    +
    +
    +
    matches="XPATH"
    +
    +

    Match on an XML file condition.

    +
    +
    +
    Example: matches="/w:web-app/w:resource-ref/w:res-auth[text() = 'Container']"
    +
    +
    +
    +
    xpathResultMatch="XPATH_RESULT_STRING"
    +
    +

    Return results that match the given regex.

    +
    +
    +
    Example: xpathResultMatch=""
    +
    +
    +
    +
    as="VARIABLE_NAME"
    +
    +

    A variable name assigned to the rule so that it can be used as a reference in later processing. See the from attribute below.

    +
    +
    +
    Example: as="MyEjbRule"
    +
    +
    +
    +
    in="PATH_FILTER"
    +
    +

    Used to filter input files matching this regex (regular expression) naming pattern. Wildcard characters can be used.

    +
    +
    +
    Example: in="{*}File1"
    +
    +
    +
    +
    from="VARIABLE_NAME"
    +
    +

    Begin the search query with the filtered result from a previous search identified by its as VARIABLE_NAME.

    +
    +
    +
    Example: from="MyEjbRule"
    +
    +
    +
    +
    public-id="PUBLIC_ID"
    +
    +

    The DTD public-id regex.

    +
    +
    +
    Example: public-id="public"
    +
    +
    +
    +
    +
    +
    +
    +
    xmlfile Element: Child Elements
    +
    +
    +
    namespace
    +
    +

    The namespace to referenced in XML files. This element contains 2 attributes: The prefix and the uri.

    +
    +
    +
    Example: <namespace prefix="abc" uri="http://maven.apache.org/POM/4.0.0"/>
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    project Syntax

    +
    +
    Summary
    +
    +

    Use the project element to find information in project files. For a better understanding of the project condition, see the JavaDoc for the Project class.

    +
    +
    +

    The following is an example of a rule that tests for an xmlfile.

    +
    +
    +
    +
    <rule>
+    <when>
+        <project>
+            <artifact groupId="junit" artifactId="junit" from="MyEjbRule" to="???"/>
+        </project>
+    </when>
+    <perform>
+        <hint title="Title for Hint for Project">
+            <message>Descriptive message</message>
+        </hint>
+    </perform>
+</rule>
    +
    +
    +
    +
    +
    Construct a project Element
    +
    +
    project Element Attributes
    +
    +

    The project element does not have any attributes.

    +
    +
    +
    +
    project Element Child Elements
    +
    +
    +
    artifact
    +
    +

    The namespace to referenced in XML files. This element contains the following attributes:

    +
    +
      +
    • +

      groupId="PROJECT_GROUP_ID"

      +
      +

      Match on the project <groupId>

      +
      +
      • +
    • +

      artifactId="PROJECT_ARTIFACT_ID" +Match on the project <artifactId>

      +
      • +
    • +

      from="VARIABLE_NAME"

      +
      +

      Begin the search query with the filtered result from a previous search identified by its as VARIABLE_NAME.

      +
      +
      • +
    • +

      to = TO_DO: complete the project artifact 'to' element syntax

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

    filecontent Syntax

    +
    +

    TO_DO: complete the filecontent element syntax

    +
    +
    +

    Use the filecontent element to find information in file content.For a better understanding of the filecontent condition, see the JavaDoc for the FileContent class.

    +
    +
    +

    Use the filecontent element to test for content within files. The following is an example of a rule that tests for filecontent.

    +
    +
    +
    +
    +

    XML Rule - Perform Action Syntax

    +
    +

    Operations allowed in the perform section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    +
    +
    +

    The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd.

    +
    +
    +

    The following sections describe the more common XML rule perform actions.

    +
    +
    + +
    +
    +

    classification Syntax

    +
    +
    Summary
    +
    +

    The classification element is used to identify or classify application resources. It provides a level of effort and can also provide links to additional information about how to migrate this resource classification. For a better understanding of the classification action, see the JavaDoc for the Classification class.

    +
    +
    +

    The following is an example of a rule that classifies a resource as a WebLogic EAR application deployment descriptor file.

    +
    +
    +

    Example:

    +
    +
    +
    +
    <rule id="XmlWebLogicRules_10vvyf">
+    <when>
+        <xmlfile as="default" matches="/*[local-name()='weblogic-application']">
+        </xmlfile>
+    </when>
+    <perform>
+        <iteration>
+            <classification classification="Weblogic EAR Application Descriptor" effort="3"/>
+        </iteration>
+    </perform>
+</rule>
    +
    +
    +
    +
    +
    Construct a classification Element
    +
    +
    classification Element Attributes
    +
    +
    +
    classification="STRING"
    +
    +

    Classify the resource as the specified string.

    +
    +

    Example:

    +
    +
    +
    +
    classification="JBoss Seam Components"
    +
    +
    +
    +
    effort="NUMBER"
    +
    +

    The level of effort assigned to this resource.

    +
    +

    Example:

    +
    +
    +
    +
    effort="2"
    +
    +
    +
    +
    +
    +
    +
    +
    classification Element Child Elements
    +
    +
    +
    xref
    +
    +

    Provides a link URI and text description for additional information.

    +
    +

    Example:

    +
    +
    +
    +
    <classification classification="Websphere Startup Service" effort="4">
+    <link href="http://docs.oracle.com/javaee/6/api/javax/ejb/Singleton.html" description="EJB3.1 Singleton Bean"/>
+    <link href="http://docs.oracle.com/javaee/6/api/javax/ejb/Startup.html" description="EJB3.1 Startup Bean"/>
+ </classification>
    +
    +
    +
    +
    +
    +
    +
    +
    +
    + +
    +
    Summary
    +
    +

    The link element is used in classifications or hints to identify or classify links to informational content. For a better understanding of the link action, see the JavaDoc for the Link class.

    +
    +
    +

    The following is an example of a rule that creates links to additional information.

    +
    +
    +

    Example:

    +
    +
    +
    +
    <rule id="SeamToCDIRules_2fmb">
+    <when>
+        <javaclass references="org.jboss.seam.{*}" as="default"/>
+    </when>
+    <perform>
+        <iteration>
+            <classification classification="SEAM Component" effort="1">
+                <link href="http://www.seamframework.org/Seam3/Seam2ToSeam3MigrationNotes" description="Seam 2 to Seam 3 Migration Notes"/>
+                <link href="http://docs.jboss.org/weld/reference/latest/en-US/html/example.html" description="JSF Web Application Example"/>
+                <link href="http://docs.jboss.org/weld/reference/latest/en-US/html/contexts.html" description="JBoss Context Documentation"/>
+                <link href="http://www.andygibson.net/blog/tutorial/cdi-conversations-part-2/" description="CDI Conversations Blog Post"/>
+            </classification>
+        </iteration>
+    </perform>
+</rule>
    +
    -
    Create the Java RuleProvider
    -
    -
      -
    1. -

      Add beans.xml file to META-INF/ dir in resources - typically, $project-dir/src/main/resources/META-INF/beans.xml. This file can be empty. It tells CDI to scan your addon for CDI beans.

      -
      2. -
    2. -

      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:

      -
      +
      Construct a link Element
      +
      +
      link Element: Attributes
      +
      +
      +
      href="URI"
      +
      +

      The URI for the referenced link/.

      +
      +

      Example:

      +
      +
      -
      public class MyCustomRuleProvider extends WindupRuleProvider
-{
-}
      +
      href="https://access.redhat.com/articles/1249423"
      -
      3. -
    3. -

      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.

      -
      + +
      description="URI_DESCRIPTION"
      +
      +

      A description for the link.

      +
      +

      Example:

      +
      +
      -
          @Override
-    public RulePhase getPhase() {
-        return RulePhase.DISCOVERY;
-    }
      +
      description="Migrate WebLogic Proprietary Servlet Annotations"
      +
      +
      +
      + +
      +
    +
    +
    +
    +

    hint Syntax

    +
    +
    Summary
    +
    +

    The hint element is used to provide a hint or inline information about how to migrate a section of code. For a better understanding of the hint action, see the JavaDoc for the Hint class.

    +
    +

    The following is an example of a rule that creates a hint.

    -

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

    +

    Example:

    - -
  • -

    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);
-}
    +
    <rule id="WebLogicWebServiceRules_8jyqn">
+    <when>
+        <javaclass references="weblogic.wsee.connection.transport.http.HttpTransportInfo.setUsername({*})" as="default">
+            <location>METHOD</location>
+        </javaclass>
+    </when>
+    <perform>
+        <iteration>
+            <hint message="Replace proprietary web-service authentication with JAX-WS standards." effort="0">
+                <link href="http://java-x.blogspot.com/2009/03/invoking-web-services-through-proxy.html" description="JAX-WS Proxy Password Example"/>
+            </hint>
+        </iteration>
+    </perform>
+</rule>
    -
    +
    +
    +
    Construct a hint Element
    +
    +
    hint Element: Attributes
    +
    +
    +
    message="MESSAGE"
    +
    +

    A message describing the migration hint

    +
    +

    Example:

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

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

    -
    -
      -
    • -

      High-level Conditions and Operations

      + +
      effort="NUMBER"
      +
      +

      The level of effort assigned to this resource.

      -

      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.

      +

      Example:

      -
      +
      -
      @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))
-        );
-}
      +
      effort="2"
      +
      +
      +
      +
    • +
    +
    hint Element: Child Elements
    +
    +
    +
    xref
    +
    +

    Identify or classify links to informational content. See the section on link Syntax for details.

    -

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

    +

    Example:

    - -
  • -

    Low-level Conditions and Operations

    +
    +
    +
    link href="http://java-x.blogspot.com/2009/03/invoking-web-services-through-proxy.html" description="JAX-WS Proxy Password Example"/>
    +
    +
    +
    • +
    +
    +
    +
    +
    +
    +

    xslt Syntax

    +
    +
    Summary
    -

    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).

    +

    The xslt element specifies how to transform an XML file. For a better understanding of the xslt action, see the JavaDoc for the XSLTTransformation class.

    -

    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.

    +

    The following is an example of rule that defines an XSLT action.

    - -
  • -

    Mid-level Conditions and Operations

    -
    • - +
    +

    Example:

    - - +
    +
    +
    <rule id="XmlWebLogicRules_6bcvk">
+    <when>
+        <xmlfile as="default" matches="/weblogic-ejb-jar"/>
+    </when>
+    <perform>
+        <iteration>
+            <classification classification="Weblogic EJB XML" effort="3"/>
+            <xslt description="JBoss EJB Descriptor (Windup-Generated)" template="transformations/xslt/weblogic-ejb-to-jboss.xsl" extension="-jboss.xml"/>
+        </iteration>
+    </perform>
+</rule>
    -
    -

    Install the Java-based Rule Add-on

    +
    +
    Construct an xslt Element
    +
    +
    xslt Element: Attributes
    +
    +
    +
    of="STRING"
    +
    +

    Create a new transformation for the given reference.

    -

    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.

    +

    Example:

    -
    -
      -
    • -

      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
      +
      of="testVariable_instance"
      -
      • -
    • -

      You should see the following result.

      +
    +
    description="String"
    +
    +

    Sets the description of this XSLTTransformation.

    +
    +

    Example:

    +
    -
    ***SUCCESS*** Addon MyCustomRuleProvider:::2.0.0.VERSION was installed successfully.
    +
    description="XSLT Transformed Output"
    - - +
    +
    extension="String"
    +
    +

    Sets the extension for this XSLTTransformation.

    +
    +

    Example:

    +
    +
    +
    +
    extension="-result.html"
    -
    -

    Test the Java-based Rule Add-on

    +
    +
    template=String
    +
    +

    Sets the XSL template.

    -

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

    +

    Example:

    +
    +
    +
    +
    template="simpleXSLT.xsl"
    +
    +
    +
    +
    +
    +
    +
    xslt Element: Child Elements
    +
    +
    +
    xslt-parameter=Map<String,String>
    +
    +

    Specify XSLTTransformation parameters as property value pairs

    -

    The command uses this syntax:

    +

    Example:

    -
    windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
    +
    <xslt-parameter property="title" value="EJB Transformation"/>
    +
    +
    +
    +
    +
    +
    +
    +

    lineitem Syntax

    +
    +
    Summary
    -

    You should see the following result:

    +

    The lineitem element is used to provide line item information about a hint on the project or application overview page. For a better understanding of the lineitem action, see the JavaDoc for the Lineitem class.

    +
    +
    +

    The following is an example of a rule that creates a lineitem message.

    +
    +
    +

    Example:

    -
    ***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html
    +
    <rule>
+    <when>
+        <javaclass references="weblogic.servlet.annotation.WLServlet" as="default">
+            <location>ANNOTATION</location>
+        </javaclass>
+    </when>
+    <perform>
+        <hint message="Replace the proprietary WebLogic @WLServlet annotation with the Java EE 6 standard @WebServlet annotation." effort="1">
+            <link href="https://access.redhat.com/articles/1249423" description="Migrate WebLogic Proprietary Servlet Annotations" />
+            <lineitem message="Proprietary WebLogic @WLServlet annotation found in file."/>
+        </hint>
+    </perform>
+</rule>
    +
    +
    +
    Construct a lineitem Element
    +
    +
    lineitem Element: Attributes
    +
    +
    +
    message="MESSAGE"
    +
    +

    A lineitem message

    -

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

    +

    Example:

    +
    +
    +
    +
    message="Proprietary code found."
    +
    +
    +
    +
    +
    +
    -

    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. -
    +

    iteration Syntax

    +
    +
    Summary
    +
    +

    The iteration element specifies to iterate over an implicit or explicit variable defined within the rule. For a better understanding of the iteration action, see the JavaDoc for the Iteration class.

    -

    TBD.

    +

    The following is an example of a rule that preforms an iteration.

    +
    +
    +

    Example:

    +
    +
    +
    +
    <rule id="XmlWebLogicRules_14wscy">
+     <when>
+         <xmlfile as="1" matches="/wl:weblogic-webservices | /wl9:weblogic-webservices">
+             <namespace prefix="wl9" uri="http://www.bea.com/ns/weblogic/90"/>
+             <namespace prefix="wl" uri="http://www.bea.com/ns/weblogic/weblogic-webservices"/>
+         </xmlfile>
+         <xmlfile as="2" matches="//wl:webservice-type | //wl9:webservice-type" from="1">
+             <namespace prefix="wl9" uri="http://www.bea.com/ns/weblogic/90"/>
+             <namespace prefix="wl" uri="http://www.bea.com/ns/weblogic/weblogic-webservices"/>
+         </xmlfile>
+     </when>
+     <perform>
+         <iteration over="1">
+             <classification classification="Weblogic Webservice Descriptor" effort="0"/>
+         </iteration>
+         <iteration over="2">
+             <hint message="Webservice Type" effort="0"/>
+         </iteration>
+     </perform>
+ </rule>
    +
    -
    -
      -
    • -

      Models

      -
      -
      -
      • -
    • -

      Rules

      -
      -
        -
      • -

        OCPSoft Rewrite

        -
        • -
      • -

        Conditions, Operations

        -
        -
          -
        • -

          Variables

          -
          • -
        +
        +
        Construct an iteration Element
        +
        +
        iteration Element: Attributes
        +
        +
        +
        over="NUMBER"
        +
        +

        ??

        +
        +

        Example:

        -
        • -
      • -

        Inter-rule action

        -
        • -
      • -

        Inter-rule dependency

        -
        -
          -
        • -

          Short IDs - WINDUP-216 -=== Create an Advanced Ruleset

          -
          • -
        +
        +
        +
        over="2"
        -
        • -
      -
      • -
    + +
    -
    -
    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. -
    +
    +
    iteration Element: Child Elements
    +
    +

    iteration child elements include a when condition, along with the actions iteration, classification, hint, xslt, lineitem, and otherwise.

    -
    -

    Create and Test XML Rules

    -
    -

    Create a Basic XML Rule

    +

    Test an XML Rule in Windup

    +
    +

    Add the Rule to Windup

    -

    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.

    +

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

    -
    -

    Prerequisites

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

    File Naming Convention for XML Rules

    -
    -

    You must name the file containing an XML rule with the .windup.xml extension. Windup identifies files with this extension as XML-base rules, so be sure to use this naming convention, otherwise the rule will not be evaluated!

    + +
    -

    Basic XML Rule Template

    +

    Test the XML Rule

    +
    +
      +
    1. +

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

      +
      2. +
    2. +

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

      -

      XML rules consist of conditions and actions and follow the familiar "if/then/else" construct:

      +

      The command uses this syntax:

      -
      +
      -
      when(condition)
-    perform(action)
-otherwise
-    perform(action)
      +
      windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
      -

      The following is the basic syntax for XML rules.

      +

      You should see the following result:

      -
      +
      -
      <?xml version="1.0"?>
-<ruleset xmlns="http://windup.jboss.org/v1/xml" id="XmlFileMappings">
-    <phase>
-        <!-- The phase in which to run the rules -->
-    </phase>
-    <rules>
-        <rule>
-            <when>
-                <!-- Test a condition... -->
-            </when>
-            <perform>
-                <!-- Perform this action when condition is satisfied -->
-            </perform>
-            <otherwise>
-                <!-- Perform this action when condition is not satisfied -->
-            </otherwise>
-        </rule>
-      <rules>
-    </ruleset>
      -
      +
      ***SUCCESS*** Windup report created: OUTPUT_REPORT_DIRECTORY/index.html
      -
      -

      Create the Rule When Condition

      -
      -

      The syntax is dependent on whether you are creating a rule to evaluate Java class, an XML file, a project, or file content and is described in more detail here: XML Rule - When Condition Syntax

      +
      3. +
    -

    Create the Rule Perform Action

    -
    -

    Operations allowed in the perform section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. The syntax is described in detail here: XML Rule - Perform Action Syntax.

    +

    Additional Resources

    +
    +
    @@ -3579,7 +4578,7 @@

    Frames creation

    -

    Classloading Notes

    +

    Classloading Notes

    DRAFT

    Page contains temporary notes, to be edited.

    @@ -3588,6 +4587,39 @@

    Classloading Notes

    This covers the specific situations when the Windup core developer needs to look up certain runtime classes. Does not relate to rules authoring.

    +

    Forge add-ons transitive dependencies

    +
    +

    Let A depend on B depend on C. +Depending on scope of C in B’s POM:

    +
    +
    +
    +
    <scope>provided</scope>
    +
    +
    +
    +

    provided will NOT export C, so A depending on B won’t see C’s classes. +Only compile scope is exported. +compile will export C, so A depending on B will also see C’s classes.

    +
    +
    +
      +
    • +

      provided == import

      +
      • +
    • +

      compile == import & export

      +
      • +
    • +

      optional == optional, not installed automatically

      +
      • +
    • +

      runtime == export only

      +
      • +
    +
    +
    +

    Finding classes

    @@ -3609,14 +4641,13 @@

    Finding classes

    Instantiating

    -

    If you want something from the current addon, you need to @Inject its ServiceRegistry and get services from that.

    +

    If you want something from the current add-on, you can simply @Inject the type you wish to use. Alternately you can @Inject an Imported<T> instance, or also @Inject the AddonRegistry itself.

    -

    Which classloader is used? Always the one of the current code?

    +

    Which ClassLoader is used? Always the one of the current code?

    -

    Depends, if you are in a Furnace Service, then yes, it will use the -current code’s addon’s classloader.

    +

    Depends, if you are in a Furnace Service, then yes, it will use the current code’s add-on ClassLoader.

    @@ -3638,14 +4669,14 @@

    Reading annotations from classes

    -

    TODO: Find out how exactly this is done.

    +

    TO_DO: Find out how exactly this is done.

    How do I know if I am in a Furnace service?

    Every furnace service is wrapped in a proxy. If it came from another -addon (not your current addon) and was not instantiated with new Blah(), +add-on (not your current add-on) and was not instantiated with new Blah(), you are in a furnace service. So if it was @Inject`ed or retrieved via `addonRegistry.getServices(…​)

    @@ -3656,7 +4687,7 @@

    How do I know if I am in a (16:33:41) LincolnBaxter: ozizka: using a shared Resource.open() APi will actually be sort of a no-op, and just introduce another layer, since you generally need to be able to specify a classloader anyway (16:33:53) jsightler: lincolnthree: Well... (16:34:09) LincolnBaxter: ozizka: unless I'm misunderstanding the point of this -(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's addon +(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's add-on (16:34:18) LincolnBaxter: ozizka: ah wait (16:34:27) LincolnBaxter: ozizka: the *caller*'s classloader (16:34:35) LincolnBaxter: ozizka: not the CL of the current operation @@ -3667,18 +4698,18 @@

    How do I know if I am in a (16:35:25) ozizka-FN: which classloader is used? (16:35:33) ozizka-FN: Always the one of the current code? (16:35:44) ozizka-FN: Implicitly -(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's addon's classloader +(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's add-on's classloader (16:36:00) ozizka-FN: Ah (16:36:11) ozizka-FN: How do I know if I am in a Furnace service? (16:36:14) LincolnBaxter: ozizka: because every furnace service is wrapped in a proxy -(16:36:31) LincolnBaxter: ozizka: basically if it came from another addon (not your current addon), you are in a furnace service +(16:36:31) LincolnBaxter: ozizka: basically if it came from another add-on (not your current add-on), you are in a furnace service (16:36:43) LincolnBaxter: ozizka: and if you didn't instantiate with new Blah() (16:37:00) LincolnBaxter: ozizka: so if it was @Injected or retrieved via addonRegistry.getServices(...) -(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling addon? just curious +(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling add-on? just curious (16:37:54) ozizka-FN: So here we would use TCCL right? LincolnBaxter lincolnthree (16:38:28) ozizka-FN: lincolnthree: To load it's resources -(16:38:31) ozizka-FN: from other addon +(16:38:31) ozizka-FN: from other add-on (16:38:32) ozizka-FN: . (16:38:35) ozizka-FN: Or is there other way? (16:38:42) LincolnBaxter: ozizka: that's a vague statement ;) @@ -3695,12 +4726,12 @@

    How do I know if I am in a

    Resources loading

    -
    (16:48:30) ozizka-FN: lincolnthree:  Just a note - the potential collisions caused  by addon's CL span is not considered as a risk?
+
    (16:48:30) ozizka-FN: lincolnthree:  Just a note - the potential collisions caused  by add-on's CL span is not considered as a risk?
 (16:49:25) ozizka-FN: I mean, it could load the file from it's deps.
 (16:49:36) ozizka-FN: * file = resource
 (16:49:50) LincolnBaxter: ozizka1: so the way it works is actually very controlled
-(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another addon
-(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the addon dependency in the POM
+(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another add-on
+(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the add-on dependency in the POM
 
 (16:53:26) ozizka-FN: Q: Unwrapping proxies caused the code in invoke() not actually being called?
 (16:53:32) ozizka-FN: Since the method calls were not intercepted?
@@ -3736,7 +4767,7 @@ 
    What classloa
 
    
 
    Connect to the Graph via Rexster
    
 
    
-
    There is a specific addon for running Rexster along your graph with
+
    There is a specific add-on for running Rexster along your graph with
 groupId org.jboss.windup.rexster and artifactId Rexster.
    
 
    
 
    
@@ -3814,7 +4845,7 @@ 
    Config
    
 
 
  • 
 
    procyon.DecompilerSettings contains outputDir (the others are not much important).
-TODO: Make that a parameter to method call?
    
+TO_DO: Make that a parameter to method call?
    
 
    • 
 
 
    
@@ -3822,7 +4853,7 @@ 
    Config
    
 
    
 
    TypeReference
    
 
    
-
    TODO: Check how we get info about Java files; perhaps cache the TypeReference results - if worth it?
    
+
    TO_DO: Check how we get info about Java files; perhaps cache the TypeReference results - if worth it?
    
 
    
 
    
 
    
@@ -3850,7 +4881,7 @@ 
    ITypeLoader
    
 
 
    
 
    
-
    TODO: Create a simple FileSystemTypeLoader.
    
+
    TO_DO: Create a simple FileSystemTypeLoader.
    @@ -3870,11 +4901,11 @@

    Maven Add-on Structure

    -
    myaddon-parent
-+--- myaddon - jar, classifier: forge-addon
-+--- myaddon-api - jar
-+--- myaddon-impl - jar
-+--- myaddon-tests - jar
    +
    my-add-on-parent
++--- my-add-on - jar, classifier: forge-addon
++--- my-add-on-api - jar
++--- my-add-on-impl - jar
++--- my-add-on-tests - jar
    @@ -3962,7 +4993,7 @@

    Add-on sub-parts

    -

    Add-on depends on API , scope compile > Addon +

    Add-on depends on API , scope compile > Add-on depends on Impl , scope compile with <optional>true</optional> - prevents exporting this dependency to consumers of the add-on.

    @@ -3974,7 +5005,7 @@

    Add-on sub-parts

    Test dependencies

    -

    For test dependencies on add-ons: Any addon/sub-part requiring an addon +

    For test dependencies on add-ons: Any add-on/sub-part requiring an add-on for testing purposes should use <scope>test</scope>.

    @@ -4141,6 +5172,7 @@

    Displaying Progress

    Variables Stack

    +
    DRAFT

    The Variables class stores the variables which are available in rules, EL expressions, and FreeMarker and XSLT templates.

    @@ -4148,84 +5180,93 @@

    Accessing variables

    From a Java-based rule
    -

    TODO

    +

    TO_DO: Describe how to access variables from a Java-based rule.

    From a Groovy-based rule
    -

    TODO

    +

    TO_DO: Describe how to access variables from a Groovy-based rule.

    From an EL expression
    -

    TODO

    +

    TO_DO: Describe how to access variables from an EL expression.

    From a FreeMarker
    -

    TODO

    +

    TO_DO: Describe how to access variables from a FreeMarker.

    From XSLT template
    -

    TODO

    +

    TO_DO: Describe how to access variables from an XSLT template.

    Accessing variables as a flat Map

    -

    TODO

    +

    TO_DO: Describe how to access variables from a Map.

    -

    Port WindRide Functionality to Windup

    +

    Git Rebasing

    -

    For the purposes of tracking the porting WindRide functionality to Windup. Will be -removed when done.

    +

    This section describes a few ways you can pull in the code to rebase to the latest code base.

    +
    +

    Approach Suggested on GitHub

    +
    +

    This is the approach suggested on GitHub.

    -
    -

    Some classes mapping

    +
    +
      +
    1. +

      Checkout the source:

      -
      @ConfigPartDescriptor = @ReportItem
-MigrationReportJaxbBean =
-DeploymentInfo = ApplicationModel
      -
      +
      git checkout -b lincolnthree-WINDUP-133 master
+git pull https://github.com/lincolnthree/windup.git WINDUP-133
    -
    -

    Server-side code to be moved

    -
    -
      -
    • -

      ServerInfo

      -
      • -
    • -

      ComparisonResult

    • -

      FileHashComparer

      -
      • -
    • -

      IMigrationAction

      +

      Run the tests to make sure it builds.

      +
      +
      +
      mvn clean install
      +
      +
    • -

      ServerMigrationReportJaxb -=== Git Rebasing

      +

      If they pass, merge and push them to your repository.

      +
      +
      +
      git checkout master
+git merge --no-ff lincolnthree-WINDUP-133
+git push origin master
      +
      +
      • -
    +
    +
    +
    +

    Script Provided by the Windup Development Team

    -

    Ondra Zizka wrote this simple script to bring down a series of pull requests into a -single branch. He then pushes that branch to upstream master-ignore.

    +

    Ondra Zizka wrote the following script to bring down a series of pull requests into a +single branch. It then pushes that branch to upstream master-ignore.

    +
    +
      +
    1. +

      Bring down the pulls into a single branch.

      pull() {
@@ -4253,48 +5294,18 @@ 
      Server-side code to be moved
      
 }
      -
      -

      Fetch using one pull request:

      -
      -
      -
      -
      git fetch upstream master pull/$PR/head:pullRequest$PR
      -
      -
      -
      -

      Alternate Approach

      -
      -

      This is the approach GitHub suggests.

      -
      -
      -
        -
      1. -

        Checkout the source:

        -
        -
        -
        git checkout -b lincolnthree-WINDUP-133 master
-git pull https://github.com/lincolnthree/windup.git WINDUP-133
        -
        -
        -
        2. -
      2. -

        Run the tests to make sure it builds.

        -
        -
        -
        mvn clean install
        -
        -
      3. -

        If they pass, merge and push them to your repository.

        +

        Fetch using the one pull request.

        -
        git checkout master
-git merge --no-ff lincolnthree-WINDUP-133
-git push origin master
        +
        git fetch upstream master pull/$PR/head:pullRequest$PR
        4. +
      4. +

        The branch is now updated with the latest source.

        +
      @@ -4315,7 +5326,7 @@

      Programmatically Access the Graph(Lower Level API, to cover cases not provided by high level API)

    -

    This topic describes how to to programmatically access or update graph data when you create a Java-based rule addon.

    +

    This topic describes how to to programmatically access or update graph data when you create a Java-based rule add-on.

    Query the graph
    @@ -4433,7 +5444,7 @@

    Modify Graph Data

    Concepts & Philosophy

    -

    TODO - OZIZKA: Can this topic be marked obsolete and be replaced by this one: Windup Processing Overview ?

    +

    TO_DO: - OZIZKA: Can this topic be marked obsolete and be replaced by this one: Windup Processing Overview ?_

    Windup is a rule-based tool that allows users to write customized rules @@ -4475,18 +5486,21 @@

    Examples of brea

  • Finding all @Entity`s which use `org.hibernate extensions.

    -

    TODO

    +

    TO_DO

  • Finding MyBatis DAOs and classes using them.

    -

    TODO -=== Creating Rule Operations

    +

    TO_DO

    • +
    +
    +
    +

    Creating Rule Operations

    An operation is a task which can be invoked from within a rule.

    @@ -4513,9 +5527,8 @@

    Examples of brea

    Existing operations

    -
    -

    Rulesets

    +

    Rulesets

    DRAFT

    @@ -4563,7 +5576,7 @@

    Basic tags

    -

    Rulesets

    +

    Rulesets

    Core rulesets
    @@ -4611,9 +5624,13 @@
    Core rulesets
    Community rulesets
    -

    Rulesets contributed by Windup users. -=== Java Basic Ruleset

    +

    Rulesets contributed by Windup users.

    +
    +
    +
    +
    +

    Java Basic Ruleset

    DRAFT

    This is an example page. Content serves for design decision.

    @@ -4621,8 +5638,6 @@
    Community rulesets

    Purpose of this ruleset.

    -
    -

    Metadata

    @@ -4774,7 +5789,7 @@

    Reports

    -

    Ruleset Java Classifications and Inline Hints

    +

    Ruleset Java Classifications and Inline Hints

    DRAFT

    Some of the most important rules are classifications and inline hints.

    @@ -4797,10 +5812,10 @@

    Classifications

    • -

      Java Classifications TODO: link

      +

      Java Classifications TO_DO: link

    • -

      XML Classifications TODO: link

      +

      XML Classifications TO_DO: link

    @@ -4823,10 +5838,10 @@

    Inline Hints

    Ruleset Java EE Apps

    DRAFT
    -

    TBD? -.DRAFT

    +

    TBD?

    +
    DRAFT

    TBD ?

    @@ -4834,9 +5849,11 @@

    Ruleset Java EE Apps

    Ruleset Reporting

    DRAFT
    -

    TBD? -=== XML Ruleset

    +

    TBD?

    +
    +
    +

    XML Ruleset

    DRAFT
      @@ -4864,7 +5881,7 @@

      Rule providers

      A definition list (dl/dt/dd) of RuleProviders of given Ruleset with brief descriptions.

    -

    TODO: Not sure if all the Xml* really belong here - maybe rather to Java or Java EE?

    +

    TO_DO: Not sure if all the Xml* really belong here - maybe rather to Java or Java EE?

      @@ -4950,7 +5967,7 @@

      Models

      Configuration

      -

      _Subclasses of TODO

      +

      _Subclasses of TO_DO

      @@ -5203,24 +6220,30 @@

      Rules Operations

      For the implementation of the operation, see -here. -TBD

      +here.

      +
      +
      +

      TBD

      Rules Ops Reporting Hint

      DRAFT
      -

      TBD -=== Ops Reporting TypeReference

      +

      TBD

      +
    +
    +

    Ops Reporting TypeReference

    TBD

    Different for Java and XML. -Contains Line, Column -DRAFT: TBD?

    +Contains Line, Column

    +
    +
    +

    DRAFT: TBD?

    @@ -5375,11 +6398,12 @@

    Classloading Problems

    This may especially happen after Maven coordinates of some module are changed.

    -
    -

    Wiki and Product Documentation

    -
    +
    +
    +

    Wiki Information

    +

    About the Windup Wiki

    @@ -5565,6 +6589,38 @@

    Add Images to the Windup Wiki

    +
    +
    +
    +

    Windup Product Release and Documentation Process

    +
    +
    +

    Windup Release Process

    +
    +

    Windup consists of artifacts from multiple GitHub repositories. Use the following procedure to create a Windup release.

    +
    +
    +
      +
    1. +

      Release http://github.com/windup/nexus-indexer

      +
      +
      +
      mvn release:prepare release:perform -DreleaseVersion=X -Dtag=Y -DdevelopmentVersion=Z
      +
      +
      +
      2. +
    2. +

      Release http://github.com/windup/windup primary reactor

      +
      3. +
    3. +

      Release http://github.com/windup/windup-rulesets

      +
      4. +
    4. +

      Release http://github.com/windup/windup-distribution

      +
      5. +
    +
    +

    Create Windup JavaDoc

    @@ -5628,7 +6684,7 @@

    Product Documentation

    Update the Windup Documentation with the Latest Wiki Changes

    -
    Summary
    +
    Summary

    The Windup guides are located in the windup-documentation/docs directory. They are named the same as the guides in the Wiki but have a 'Windup-' prefix. The windup-documentation/docs guides should kept synchronized with the versions in the windup.wiki.

    @@ -5795,156 +6851,367 @@

    Publish the HTML Docs fo

  • -

    Push the changes to GitHub.

    -
    -
    -
    git push upstream gh-pages
    -
    +

    Push the changes to GitHub.

    +
    +
    +
    git push upstream gh-pages
    +
    +
    +
    • +
  • +

    View the documentation at http://windup.github.io/windup/docs/WINDUP_RELEASE/html/WindupUserGuide.html

    +
    • +
  • +

    Update the symlink for latest to point to the new version.

    +
    +
      +
    • +

      Navigate to the WINDUP_HOME/docs directory.

      +
      • +
    • +

      Remove the existing symlink for "latest".

      +
      +
      +
      unlink latest
      +
      +
      +
      • +
    • +

      Create a symlink to the new documentation.

      +
      +
      +
      Syntax: ln -s WINDUP_RELEASE latest
+Example: ln -s 2.0.0.Final latest
      +
      +
      +
      • +
    • +

      Add the modified "latest" directory to Git.

      +
      +
      +
      git add latest
      +
      +
      +
      • +
    • +

      Commit the change.

      +
      +
      +
      git commit -m 'Replace symlink for latest to point to 2.0.0.Final'
      +
      +
      +
      • +
    • +

      Push the changes to your own git repository, verify and issue a pull.

      +
      +
      +
      git push origin HEAD
      +
      +
      +
      • +
    • +

      Push the changes upstream

      +
      +
      +
      git push upstream gh-pages
      +
      +
      +
      • +
    • +

      View the documentation at http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html

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

    Additional Resources

    +
    +
    +

    Review the Windup Quickstarts

    +
    +

    The Windup quickstarts provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. 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. +
    +
    +
    +
    +
    +

    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 overview describing how to solve the problem migration areas.

        +
        • +
      +
      +
      • +
    • +

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

      +
      • +
    • +

      You can contribute Windup rules.

      +
      +
        +
      • +

        Write a Windup rule add-on to automate a migration process.

        +
        • +
      • +

        Create a test for the new rule.

        +
        • +
      • +

        For details, see the Windup Rules Development Guide.

        +
        • +
      +
      +
      • +
    • +

      You can also contribute to the project source code.

      +
      +
        +
      • +

        Create a core rule.

        +
        • +
      • +

        Improve performance or efficiency.

        +
        • +
      • +

        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!

    +
    +
    +
    +

    Helpful links

    +
    + -
    +
  • +

    Windup Commits Mailing List: windup-commits@lists.jboss.org

    +
    • +
  • +

    Windup on Twitter: @JBossWindup

    • +
    +

    You can also follow us on this IRC channel: irc.freenode.net#windup.

    -
    -
    -

    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

    -
    +

    Known Windup Issues

    -

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

    +

    Windup known issues are tracked here: Open Windup issues

    -
    -

    Download the Latest ZIP

    -
    -

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

    +
    +

    Report Issues with Windup

    -

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

    -
    +

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

    -

    Fork and Clone the GitHub Project

    +

    Create a JIRA Account

    -

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

    +

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

    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

      +

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

    2. -

      Clone your Windup quickstart repository to your local file system:

      -
      -
      -
      git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
      -
      -
      +

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

    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/
      +

      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.

      • -

        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
        -
        +

        Enter your credentials and click the LOGIN button.

        +
        • +
      • +

        You are then redirected back to the Create Issue page.

        +
        • +
    2. -

      To get the latest files from the upstream repository.

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

      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.

      +
    -
    -

    Known Windup Issues

    -
    -

    Windup known issues are tracked here: Open Windup issues

    +
    +

    Appendix

    +

    Glossary of Terms Used in Windup

    @@ -6034,12 +7301,90 @@

    Reporting Terms

    +
    +

    Windup Project Information

    +
    +

    Github Repository

    +
    +

    The Windup project github repository is located at https://github.com/windup/windup/.

    +
    +
    +

    See the Core-Developer-Guide for details on how to contribute to the Windup project source code.

    +
    +
    +
    +

    Documentation

    +
    +

    The Windup documentation is currently located here in the Windup project Wiki.

    +
    +
    +

    For additional information, refer to the Windup Javadoc.

    +
    +
    +
    +

    Website

    +
    +

    There is currently no website for Windup 2.0.

    +
    +
    +

    The windup.jboss.org website currently provides information primarily +for legacy Windup 1.x (legacy).

    +
    +
    +
    +

    IRC chat

    +
    +

    Server: irc.freenode.net
    +Channel: #windup

    +
    +
    +
    +

    Mailing lists

    +
    +

    Subscribe to the JBoss mailing lists at +https://lists.jboss.org/mailman/listinfo/windup-dev.

    +
    +
    + +
    +
    +
    +

    Core development team (and IRC nicks)

    +
    +

    Lead: Lincoln Baxter (lincolnthree)
    +Members: Jess Sightler (jsightler), Matej Briskar (mbriskar), Ondrej +Zizka (ozizka)

    +
    +
    +
    +

    IRC meeting bot commands (hint for the moderator)

    +
    +
    +
    #startmeeting
+#chair lincolnthree, ozizka, jsightler, mbriskar
+#addtopic Status Reports
+#addtopic Next steps
+#nexttopic
+#info ...
+#endmeeting
+Useful Commands: #action #agreed #help #info #idea #link #topic.
    +
    +
    +
    +
    diff --git a/html/WindupRulesDevelopmentGuide.html b/html/WindupRulesDevelopmentGuide.html index 005f4bdf63..5359371eb8 100644 --- a/html/WindupRulesDevelopmentGuide.html +++ b/html/WindupRulesDevelopmentGuide.html @@ -419,10 +419,7 @@

    Windup Rules Development Guide

  • 2. Get Started @@ -437,6 +434,7 @@

    Windup Rules Development Guide

  • 3.1. Windup Processing Overview
  • 3.2. Rule Execution Lifecycle
  • 3.3. Rule Story Points
    • +
  • 3.4. Difference Between XML-based and Java-based Rules
  • 4. Create and Test Java Rule Addons @@ -449,41 +447,32 @@

    Windup Rules Development Guide

  • 5. Create and Test XML Rules
    • -
  • 6. Review the Report +
  • 6. Debugging and Troubleshooting
    • -
  • 7. External Rule Examples +
  • 7. Additional Resources
    • -
  • 8. Debugging and Troubleshooting +
  • 8. Appendix -
    • -
  • 9. Additional Resources - -
    • -
  • 10. Appendix -
    • @@ -623,7 +612,7 @@

    1.2. Features of Windup 2.0

    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.

    +

    Java-based rule add-ons 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. @@ -700,286 +689,49 @@

    1.2. Features of Windup 2.0

    • -

    1.3. 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.

    -
    -
    -

    1.3.1. 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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    -
    -
    -

    For more information about the phases of rule execution and how to control rule dependencies, see Rule Execution Lifecycle.

    -
    -
    -

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

    -
    -
    -
    -

    1.3.2. 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.

    -
    -
    -
    -

    1.3.3. Generate Findings Based on the Rule Execution Results

    +

    1.3. About the WINDUP_HOME Variable

    -

    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:

    +

    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.

    • -

      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.

      +

      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.

    • -

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

      +

      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.

    -
    -

    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.

    +
    +

    2. Get Started

    +
    -

    1.4. Get Involved

    -
    -

    1.4.1. 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 overview describing how to solve the problem migration areas.

        -
        • -
      -
      -
      • -
    • -

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

      -
      • -
    • -

      You can contribute Windup rules.

      -
      -
        -
      • -

        Write a Windup rule add-on to automate a migration process.

        -
        • -
      • -

        Create a test for the new rule.

        -
        • -
      • -

        For details, see the Windup Rules Development Guide.

        -
        • -
      -
      -
      • -
    • -

      You can also contribute to the project source code.

      -
      -
        -
      • -

        Create a core rule.

        -
        • -
      • -

        Improve performance or efficiency.

        -
        • -
      • -

        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!

    -
    -
    +

    2.1. Install Windup

    -

    1.4.2. Helpful links

    -
    -
    -
    -
    -

    1.5. 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.

    -
    -
    -

    1.5.1. 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. -
    -
    -
    -

    1.5.2. 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. -
    -
    -
    -
    -
    -

    1.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.

      -
      • -
    -
    -
    -
    -
    -
    -

    2. Get Started

    -
    -
    -

    2.1. Install Windup

    +

    2.1.2. Download and Install Windup

    1. @@ -1004,6 +756,7 @@

      2.1. Install Windup

    +

    2.2. Execute Windup

    @@ -1014,10 +767,10 @@

    2.2.1. Prerequisites

    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.

      +

      The fully qualified path of the application archive or folder you plan to migrate.

    2. -

      You also specify the fully qualified path to a folder that will contain the resulting report information. This path is passed using the --output argument on the command line.

      +

      The fully qualified path to a folder that will contain the resulting report information.

      • @@ -1113,33 +866,27 @@

        2.2.2. Start Windup

    -

    2.2.3. Run the windup-migrate-app Command

    +

    2.2.3. Run Windup

    1. -

      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.

      -
      +

      The command to run Windup is windup-migrate-app.

      +
      2. +
    2. +

      The following is a list of the most commonly used command line arguments.

      +
      +
      +
      --input INPUT_ARCHIVE_OR_FOLDER
      +
      +

      This is the fully qualified application archive or source path.

      +
      +
      --source-mode true (optional)
      +
      +

      This argument is optional and is only required if the application to be evaluated contains source files rather than compiled binaries. The default value is false.

      +
      +
      --output OUTPUT_REPORT_DIRECTORY
      +
      +

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

      @@ -1147,16 +894,44 @@

      2.2.3. Run the wind
      Note

      -If the OUTPUT_REPORT_DIRECTORY directory exists, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! +If the OUTPUT_REPORT_DIRECTORY directory exists and you do not specify the --overwrite argument, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information!
      +
      +
      --overwrite (optional)
      +
      +

      Specify this optional argument only if you are certain you want to force Windup to delete the existing OUTPUT_REPORT_DIRECTORY. The default value is false.

      +
      +
      --packages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
      +
      +

      This is a comma-delimited list of the packages to be evaluated by Windup.

      +
      +
      --excludePackages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
      +
      +

      This is a comma-delimited list of the packages to be excluded by Windup.

      +
      +
      +
      +
      3. +
    3. +

      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
      +
      +
      -

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

      +

      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
      +
      -

      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 commands that use source code directories and archives located in the Windup GitHub repository.

    4. @@ -1220,7 +995,7 @@

      2.2.4. Run Windup in Batch Mode

      2.2.5. Windup Help

      -

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

      +

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

      @@ -1273,7 +1048,7 @@
      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.

      +

      The quickstarts provide examples of Java-based and XML-based rules 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 rules.

      @@ -1469,9 +1244,6 @@
      Individual File Analysis Reports

      Report Directory File List

      -
      -

      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.

      -
    @@ -1489,7 +1261,7 @@

    3.1. Windup Processing Overview

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

    -

    3.1.1. Discovery Phase

    +

    3.1.1. 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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    @@ -1501,7 +1273,7 @@

    3.1.1. Discovery Phase

    -

    3.1.2. Application Migration

    +

    3.1.2. 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.

    @@ -1510,7 +1282,7 @@

    3.1.2. Application Migration

    -

    3.1.3. Generate Findings Based on the Rule Execution Results

    +

    3.1.3. 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.

    @@ -1578,7 +1350,7 @@

    3.2.2. Rule Phases

    -

    By default, a rule runs during the MigrationRules phase. However, a +

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

    @@ -1587,7 +1359,7 @@

    3.2.2. Rule Phases

    Rule phases provide a 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 InitialAnalysis rule phase.

    +example specifies this rule should execute during the INITIAL_ANALYSIS rule phase.

    @@ -1626,7 +1398,7 @@

    3.2.2. Rule Phases

    MIGRATION_RULES
    -

    This is the default phase for all rules unless overridden. +

    This phase 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 - @@ -1688,14 +1460,16 @@

    3.3. Rule Story Points

    3.3.1. What are Story Points?

    -
    DRAFT
    -

    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.

    +

    Story points are an abstract metric commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. 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. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

    -

    3.3.2. How to Estimate Story Points in a Rule

    +

    3.3.2. How Story Points are Estimated in Rules

    -

    Estimating story points for a rule can be tricky. The following are general guidelines or suggestions to use when estimating the level of effort required for a rule.

    +

    Estimating story points for a rule can be tricky. The following are the general guidelines Windup uses when estimating the level of effort required for a rule.

    @@ -1719,7 +1493,7 @@

    3.3.2. How to Estimate Story Po

    - + @@ -1742,6 +1516,249 @@

    3.3.2. How to Estimate Story Po

    Mapped

    1- 2 per file

    There is a standard mapping algorithm to port the code or file. The number of story points required is small, but dependent on the number of files to port.

    There is a standard mapping algorithm to port the code or file. The number of story points required is small, but is dependent on the number of files to port.

    Custom

    +
    +

    3.4. Difference Between XML-based and Java-based Rules

    +
    +

    3.4.1. First of all, to prevent confusion:

    +
    +
      +
    1. +

      Rules can be written using XML or the Java API. We call them XML-based and Java-based Rules.

      +
      2. +
    2. +

      Independent of the syntax, the rules may inspect (classify) XML or Java code.

      +
      3. +
    +
    +
    +

    See the examples below.

    +
    +
    +
    +

    3.4.2. Which one to choose?

    +
    +

    The XML rules provide a quick, simple way to create rules to analyze Java and XML files. Java rules provide the ability to create very complex rules.

    +
    +
    +
      +
    • +

      If you simply need to highlight a specific section of Java code or XML file content and provide hints for it, it is recommended that you create the rule using XML.

      +
      • +
    • +

      If you need to create a new custom report, you need to create the reporting rules using Java.

      +
      • +
    • +

      If you need to extend functionality beyond what the XML rules provide, you need to create the rule using Java.

      +
      • +
    +
    +
    +
    +

    3.4.3. Pros and cons - XML

    +
    +

    Pros:

    +
    +
    +
      +
    • +

      XML rules are fairly easy to write and require less code.

      +
      • +
    • +

      You do not need to configure Maven to build from source because there is no need for compilation of +XML rules.

      +
      • +
    • +

      Deployment is simple. You simply drop the XML rule into the appropriate path and Windup automatically scans the new rule.

      +
      • +
    +
    +
    +

    Cons:

    +
    +
    +
      +
    • +

      XML rules only support a simple subset of conditions and operations.

      +
      • +
    • +

      XML rules do not provide for direct custom graph data manipulation.

      +
      • +
    • +

      XML rules do not support the ability to create custom reports.

      +
      • +
    +
    +
    +
    +

    3.4.4. Pros and Cons - Java

    +
    +

    Pros:

    +
    +
    +
      +
    • +

      Java rule add-ons allow you to write custom rules and provide a lot of flexibility.

      +
      • +
    • +

      You can set breakpoints and test Java rule add-ons using a debugger.

      +
      • +
    • +

      IDEs provide code completion for the Windup API.

      +
      • +
    +
    +
    +

    Cons:

    +
    +
    +
      +
    • +

      You must configure Maven to compile the Windup Java rule add-ons.

      +
      • +
    • +

      Java rule add-ons that are not included in the Windup core code base must be a full Forge add-on.

      +
      • +
    • +

      Java rule add-ons require writing a lot of Java code/

      +
      • +
    • +

      Writing Java rule add-ons are complex and required knowledge of Windup internals.

      +
      • +
    +
    +
    +
    +

    3.4.5. Examples

    +
    +

    Example of a rule written in XML classifying Java code:

    +
    +
    +
    +
    <?xml version="1.0"?>
+<ruleset xmlns="http://windup.jboss.org/v1/xml" id="EjbRules">
+    <rules>
+        <rule id="EjbRules_2fmb">
+            <when>
+                <javaclass references="javax.persistence.Entity" as="default">
+                    <location>TYPE</location>
+                </javaclass>
+            </when>
+            <perform>
+                <iteration>
+                    <classification classification="JPA Entity" effort="0"/>
+                </iteration>
+            </perform>
+        </rule>
+    </rules>
+</ruleset>
    +
    +
    +
    +

    Example of a rule written in Java classifying Java code:

    +
    +
    +
    +
    /**
+ * Scans for classes with EJB related annotations, and adds EJB related metadata for these.
+ */
+public class DiscoverEjbAnnotationsRuleProvider extends WindupRuleProvider
+{
+    @Override
+    public Configuration getConfiguration(GraphContext context) {
+        return ConfigurationBuilder.begin()
+        .addRule()
+        .when(JavaClass.references("javax.ejb.{annotationType}").at(TypeReferenceLocation.ANNOTATION))
+        .perform(new AbstractIterationOperation<JavaTypeReferenceModel>()
+        {
+            public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload)
+            {
+                extractEJBMetadata(event, payload);
+            };
+        })
+        .where("annotationType").matches("Stateless|Stateful")
+        .withId(ruleIDPrefix + "_StatelessAndStatefulRule")
+        .addRule()
+        .when(JavaClass.references("javax.ejb.MessageDriven").at(TypeReferenceLocation.ANNOTATION))
+        .perform(new AbstractIterationOperation<JavaTypeReferenceModel>() {
+            @Override
+            public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) {
+                extractMessageDrivenMetadata(event, payload);
+            }
+        })
+        .withId(ruleIDPrefix + "_MessageDrivenRule")
+        .addRule()
+        .when(JavaClass.references("javax.persistence.Entity").at(TypeReferenceLocation.ANNOTATION).as(ENTITY_ANNOTATIONS)
+                    .or(JavaClass.references("javax.persistence.Table").at(TypeReferenceLocation.ANNOTATION).as(TABLE_ANNOTATIONS_LIST)))
+        .perform(Iteration.over(ENTITY_ANNOTATIONS).perform(new AbstractIterationOperation<JavaTypeReferenceModel>() {
+            @Override public void perform(GraphRewrite event, EvaluationContext context, JavaTypeReferenceModel payload) {
+                extractEntityBeanMetadata(event, payload);
+            }
+        }).endIteration())
+        .withId(ruleIDPrefix + "_EntityBeanRule");
+    }
+    ...
+}
    +
    +
    +
    +
    +

    3.4.6. Summary

    +
    +

    The following is a draft…​ it may go.

    +
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RequirementXML RuleJava Rule Add-on

    Easy to write?

    Yes

    Depends on the complexity of the rule

    Requires that you configure Maven?

    No

    Yes

    Requires that you compile the rule?

    No

    Yes

    Simple deployment?

    No

    Yes

    Supports custom reports?

    No

    Yes

    Ability to create complex conditions and operations?

    No

    Yes

    Ability to directly manipulate the graph data?

    No

    Yes

    +
    +
    @@ -1750,7 +1767,7 @@

    4. Create and Test Java Rule Addons

    4.1. Install and Configure Maven

    -

    If you plan to contribute to the core code base or create Java-based rule addons, you must first install and configure Maven to build Windup from source.

    +

    If you plan to contribute to the core code base or create Java-based rule add-ons, you must first install and configure Maven to build Windup from source.

    4.1.1. Download and Install Maven

    @@ -1879,9 +1896,7 @@

    4.1.3. Configure Maven to Build Windup<

    4.2. 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

    +

    TO_DO: Add a how-to for compound rules, nested rules, rules over multiple sources, negative queries (not matched by anything).

    4.2.1. Windup Rule Provider

    @@ -2029,7 +2044,7 @@
    Iteration
    Nested iterations
    -

    TODO

    +

    TO_DO: Provide information about nested iterations

    @@ -2058,7 +2073,7 @@
    otherwise
    Where
    -

    TODO

    +

    TO_DO: Provide information about the where clause

    @@ -2089,7 +2104,7 @@

    4.2.3. Available utilities

    4.3. Basic Rule Execution Flow Patterns

    -

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

    +

    TO_DO: Need some links to github to the respective example files.

    4.3.1. operation(); - single operation

    @@ -2424,7 +2439,7 @@
    Create the Java RuleProvider
    1. -

      Add beans.xml file to META-INF/ dir in resources - typically, $project-dir/src/main/resources/META-INF/beans.xml. This file can be empty. It tells CDI to scan your addon for CDI beans.

      +

      Add beans.xml file to META-INF/ dir in resources - typically, $project-dir/src/main/resources/META-INF/beans.xml. This file can be empty. It tells CDI to scan your add-on for CDI beans.

    2. 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:

      @@ -2646,46 +2661,16 @@

      4.4.5. Review the Output Report

      • -

        Short IDs - WINDUP-216 -=== Create an Advanced Ruleset

        -
        • -
      -
      +

      Short IDs - WINDUP-216

    -
    -
    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. -
    -
    @@ -2694,9 +2679,9 @@

    4.4.5. Review the Output Report

    5. Create and Test XML Rules

    -

    5.1. Create a Basic XML Rule

    +

    5.1. 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.

    +

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

    5.1.1. Prerequisites

    @@ -2786,7 +2771,7 @@

    5.1.5. Create the Rule Perform Action

    5.2. XML Rule - When Condition Syntax

    -

    Conditions allowed in the when portion of a rule must extend GraphOperaton and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule addons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    +

    Conditions allowed in the when portion of a rule must extend GraphOperaton and currently include evaluation of Java classes, XML files, projects, and file content. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd.

    @@ -2813,7 +2798,7 @@

    5.2. XML Rule - When Condition Syn

    5.2.1. javaclass Syntax

    -
    Summary
    +
    Summary

    Use the javaclass element to find imports, methods, variable declarations, annotations, class implementations, and other items related to Java classes. For a better understanding of the javaclass condition, see the JavaDoc for the JavaClass class.

    @@ -2902,7 +2887,7 @@
    JavaClass Element Child Elements

    5.2.2. xmlfile Syntax

    -
    Summary
    +
    Summary

    Use the xmlfile element to find information in XML files. For a better understanding of the xmlfile condition, see the XmlFile JavaDoc.

    @@ -3012,7 +2997,7 @@
    xmlfile Element: Child Elements

    5.2.3. project Syntax

    -
    Summary
    +
    Summary

    Use the project element to find information in project files. For a better understanding of the project condition, see the JavaDoc for the Project class.

    @@ -3066,11 +3051,11 @@
    project Element Child Elements

  • from="VARIABLE_NAME"

    -

    Begin the search query with the filtered result from a previous search identified by its as VARIABLE_NAME. ???

    +

    Begin the search query with the filtered result from a previous search identified by its as VARIABLE_NAME.

  • -

    to = "???"

    +

    to = TO_DO: complete the project artifact 'to' element syntax

    • @@ -3083,8 +3068,10 @@
    project Element Child Elements

    5.2.4. filecontent Syntax

    -

    Use the filecontent element to find information in file content.For a better understanding of the filecontent condition, see the JavaDoc for the FileContent class. -TBD : .Draft

    +

    TO_DO: complete the filecontent element syntax

    +
    +
    +

    Use the filecontent element to find information in file content.For a better understanding of the filecontent condition, see the JavaDoc for the FileContent class.

    Use the filecontent element to test for content within files. The following is an example of a rule that tests for filecontent.

    @@ -3094,7 +3081,7 @@

    5.2.4. filecontent Syntax

    5.3. XML Rule - Perform Action Syntax

    -

    Operations allowed in the perform section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. Because XML rules are modeled after the Java-based rule addons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    +

    Operations allowed in the perform section of the rule include the classification of application resources, in-line hints for migration steps, links to migration information, and project lineitem reporting. Because XML rules are modeled after the Java-based rule add-ons, links to JavaDocs for the related Java classes are provided for a better understanding of how they behave.

    The complete XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd.

    @@ -3127,7 +3114,7 @@

    5.3. XML Rule - Perform Action Syn

    5.3.1. classification Syntax

    -
    Summary
    +
    Summary

    The classification element is used to identify or classify application resources. It provides a level of effort and can also provide links to additional information about how to migrate this resource classification. For a better understanding of the classification action, see the JavaDoc for the Classification class.

    @@ -3213,7 +3200,7 @@
    classification Element Child Ele
    -
    Summary
    +
    Summary

    The link element is used in classifications or hints to identify or classify links to informational content. For a better understanding of the link action, see the JavaDoc for the Link class.

    @@ -3281,7 +3268,7 @@
    link Element: Attributes

    5.3.3. hint Syntax

    -
    Summary
    +
    Summary

    The hint element is used to provide a hint or inline information about how to migrate a section of code. For a better understanding of the hint action, see the JavaDoc for the Hint class.

    @@ -3367,7 +3354,7 @@
    hint Element: Child Elements

    5.3.4. xslt Syntax

    -
    Summary
    +
    Summary

    The xslt element specifies how to transform an XML file. For a better understanding of the xslt action, see the JavaDoc for the XSLTTransformation class.

    @@ -3474,7 +3461,7 @@
    xslt Element: Child Elements

    5.3.5. lineitem Syntax

    -
    Summary
    +
    Summary

    The lineitem element is used to provide line item information about a hint on the project or application overview page. For a better understanding of the lineitem action, see the JavaDoc for the Lineitem class.

    @@ -3528,7 +3515,7 @@
    lineitem Element: Attributes

    5.3.6. iteration Syntax

    -
    Summary
    +
    Summary

    The iteration element specifies to iterate over an implicit or explicit variable defined within the rule. For a better understanding of the iteration action, see the JavaDoc for the Iteration class.

    @@ -3611,7 +3598,7 @@

    5.4.1. Add the Rule to Windup

  • The ${user.home}/.windup/rules/ folder.

    -

    This folder is created by Windup the first time you execute Windup. It used to track rules and addons and to contains the Windup log.

    +

    This folder is created by Windup the first time you execute Windup. It used to track rules and add-ons and to contains the Windup log.

    @@ -3669,432 +3656,348 @@

    5.4.3. Additional Resources

    -

    6. Review the Report

    +

    6. Debugging and Troubleshooting

    -

    6.1. Review the Report

    +

    6.1. Debugging and Profiling

    -

    6.1.1. About the Report

    +

    6.1.1. Debug the Windup Distribution Runtime

    -

    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:

    +

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

    -
    -
      -
    • -

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

      -
      • +
      +
      1. -

        archives/: Contains the archives extracted from the application

        +

        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. -

        graph/: Contains binary graph database files

        -
        3. -
      3. -

        reports/: This directory contains the generated HTML report files

        -
        4. -
      4. -

        stats/: Contains Windup performance statistics

        -
        5. -
    -
    -
    -

    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:

    -
    -
    +

    Configure the FORGE_OPTS for debugging.

    +
    -
    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
    +
    export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"
    +
    • +
    -
    -

    6.1.2. 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

    +
    +

    6.1.2. Debug a Test Using NetBeans

    -

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

    +

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

    -

    6.1.3. 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.

    -
    +

    6.1.3. Profile a Test Using NetBeans

    +
    +
      +
    1. +

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

      • -

        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.

        +

        Open the NETBEANS_HOME/etc/netbeans.conf file

      • -

        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.

        +

        Find the line with netbeans_default_options=

        • -
      -
      -
      -

      The following is an example of a Windup Application Report.

      -
      -
      -

      Report Summary Page

      +
    2. +

      Add the following option

      +
      +
      +
      -J-Xmx5200m -J-XX:MaxPermSize=1024m
      -
      -
      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

        +

        Restart NetBeans.

        • -
      • -

        Manifest

        +
      +
    3. -

      Properties

      +

      Click Menu > Profile > Profile Test File.

    4. -

      EJB XML

      +

      In the resulting dialog, enter the following.

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

    6.1.4. Profile Forge Runtime Using YourKit

    +
    +
    1. -

      Spring XML

      +

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

    2. -

      Web XML

      +

      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. -

      Hibernate Cfg

      +

      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. -

      Hibernate Mapping

      -
      5. - -
    - -
    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

    +

    Run windup-analyze-app.

    +
    +
    +
    forge -e windup-migrate-app
    -
    -
    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

    +
    +

    6.2. Troubleshoot Windup Issues

    +
    +

    6.2.1. Logging

    -

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

    +

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

    -

    File Detail - Part 2

    -
    +

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

    -

    6.1.4. Additional Reports

    -
    -

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

    -
    -
    -
    Rule Provider Execution Report
    +

    6.2.2. Debugging Exceptions

    -

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

    +

    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).

    -

    RuleProvider Report

    +

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

    -
    -
    Rule Provider Execution Report
    +
    +

    6.2.3. Classloading Problems

    -

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

    +

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

    +
    +
    +
    Caused by: java.lang.IllegalArgumentException: Type value for model 'org.jboss.windup.rules.files.model.FileReferenceModel' is already registered with model org.jboss.windup.rules.files.model.FileReferenceModel
    -
    -
    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

    -
    +

    This means that the model class is loaded twice. I.e. the module containing it is loaded twice. Or, in tests, you may be (accidentally) adding the class to the deployment. +This may especially happen after Maven coordinates of some module are changed.

    -

    7. External Rule Examples

    +

    7. Additional Resources

    -

    7.1. 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.

    -
    -
    -

    7.1.1. 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.

    -
    -
    +

    7.1. Get Involved

    -

    7.1.2. Fork and Clone the GitHub Project

    +

    7.1.1. How can you help?

    -

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

    +

    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!

    -
    -
      +
      +
      • -

        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

        +

        Let us know what Windup migration rules should cover.

      • -

        Clone your Windup quickstart repository to your local file system:

        -
        -
        -
        git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
        -
        -
        +

        Provide example applications to test migration rules.

      • -

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

        -
        -
        -
        cd windup-quickstarts/
        -
        -
        +

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

        +
        +
          +
        • +

          Write a short description of these problem migration areas.

        • -

          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
          -
          +

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

          +
          • +
      • -

        To get the latest files from the upstream repository.

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

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

        • -
    -
    -
    -
    -
    -
    -
    -

    8. Debugging and Troubleshooting

    -
    -
    -

    8.1. Debugging and Profiling

    -
    -

    8.1.1. 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
      -
      -
      +

      You can contribute Windup rules.

      +
      +
        +
      • +

        Write a Windup rule add-on to automate a migration process.

      • -

        Configure the FORGE_OPTS for debugging.

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

        Create a test for the new rule.

        +
        • +
      • +

        For details, see the Windup Rules Development Guide.

        +
        • +
      2. -
    +
  • +

    You can also contribute to the project source code.

    +
    +
      +
    • +

      Create a core rule.

      +
      • +
    • +

      Improve performance or efficiency.

      +
      • +
    • +

      See the_Windup Core Development Guide_ for information about how to configure your environment and set up the project.

      +
      • +
    +
    • +
    -
    -

    8.1.2. Debug a Test Using NetBeans

    -

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

    +

    Any level of involvement is greatly appreciated!

    -

    8.1.3. Profile a Test Using NetBeans

    -
    -
      -
    1. -

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

      +

      7.1.2. Helpful links

    -
    -
    -
    -

    8.1.4. Profile Forge Runtime Using YourKit

    -
    -
    1. -

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

      +

      Windup Issue Tracker: https://issues.jboss.org/browse/WINDUP

    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"
      -
      -
      +

      Windup Users Mailing List: windup-users@lists.jboss.org

      +
      3. +
    3. +

      Windup Developers Mailing List: windup-dev@lists.jboss.org

      +
      4. +
    4. +

      Windup Commits Mailing List: windup-commits@lists.jboss.org

    5. -

      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>.

      +

      Windup on Twitter: @JBossWindup

      6. -
    6. -

      Run windup-analyze-app.

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

    You can also follow us on this IRC channel: irc.freenode.net#windup.

    -

    8.2. Troubleshoot Windup Issues

    -
    -

    8.2.1. Logging

    +

    7.2. Review the Windup Quickstarts

    -

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

    +

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

    -

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

    -
    +

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

    -

    8.2.2. Debugging Exceptions

    +

    7.2.1. Download the Latest ZIP

    -

    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).

    +

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

    -

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

    +

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

    -

    8.2.3. Classloading Problems

    +

    7.2.2. Fork and Clone the GitHub Project

    -

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

    +

    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

      -
      Caused by: java.lang.IllegalArgumentException: Type value for model 'org.jboss.windup.rules.files.model.FileReferenceModel' is already registered with model org.jboss.windup.rules.files.model.FileReferenceModel
      +
      cd windup-quickstarts/
      -
      -

      This means that the model class is loaded twice. I.e. the module containing it is loaded twice. Or, in tests, you may be (accidentally) adding the class to the deployment. -This may especially happen after Maven coordinates of some module are changed.

      +
      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. +
    +
    -
    -

    9. Additional Resources

    -
    -

    9.1. Available Rule Utilities

    +

    7.3. Available Rule Utilities

    -

    9.1.1. Programmatically Access the Graph

    +

    7.3.1. Programmatically Access the Graph

    Note: Needs update. This is out of date!

    @@ -4102,7 +4005,7 @@

    9.1.1. Programmatically Access the G

    (Lower Level API, to cover cases not provided by high level API)

    -

    This topic describes how to to programmatically access or update graph data when you create a Java-based rule addon.

    +

    This topic describes how to to programmatically access or update graph data when you create a Java-based rule add-on.

    Query the graph
    @@ -4188,7 +4091,7 @@
    Nested Iteration
    -

    9.1.2. Modify Graph Data

    +

    7.3.2. Modify Graph Data

    For more custom operations dealing with Graph data that are not covered by the Query mechanism, use the GraphService.

    @@ -4218,78 +4121,106 @@

    9.1.2. Modify Graph Data

    -

    9.2. 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

    -
    +

    7.4. Known Windup Issues

    -

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

    +

    Windup known issues are tracked here: Open Windup issues

    -
    -

    9.2.1. Download the Latest ZIP

    -
    -

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

    +
    +

    7.5. Report Issues with Windup

    -

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

    -
    +

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

    -

    9.2.2. Fork and Clone the GitHub Project

    +

    7.5.1. Create a JIRA Account

    -

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

    +

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

    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

      +

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

    2. -

      Clone your Windup quickstart repository to your local file system:

      -
      -
      -
      git clone https://github.com/YOUR_USER_NAME/windup-quickstarts.git
      -
      -
      +

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

    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/
      +

      Enter your email address and click the Confirm address button.

      +
      4. +
    4. +

      Follow the instructions sent to your email address.

      +
      5. +
    +
    +

    7.5.2. 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.

      • -

        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
        -
        +

        Enter your credentials and click the LOGIN button.

        +
        • +
      • +

        You are then redirected back to the Create Issue page.

        +
        • +
    2. -

      To get the latest files from the upstream repository.

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

      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.

      +
    -
    -

    9.3. Known Windup Issues

    -
    -

    Windup known issues are tracked here: Open Windup issues

    +
    +

    8. Appendix

    +
    -

    9.4. Glossary of Terms Used in Windup

    +

    8.1. Glossary of Terms Used in Windup

    -

    9.4.1. Rules Terms

    +

    8.1.1. Rules Terms

    Rule
    @@ -4352,7 +4283,7 @@

    9.4.1. Rules Terms

    -

    9.4.2. Reporting Terms

    +

    8.1.2. Reporting Terms

    Lift and Shift (Level of effort)
    @@ -4375,13 +4306,8 @@

    9.4.2. Reporting Terms

    -
    -
    -
    -

    10. Appendix

    -
    -

    10.1. Windup Architectural Components

    +

    8.2. 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 @@ -4389,7 +4315,7 @@

    10.1. Windup Architectural Components

    -

    10.1.1. Forge

    +

    8.2.1. Forge

    Forge is an open source, extendable, rapid application development tool for creating Java EE applications using Maven. For more information @@ -4397,30 +4323,30 @@

    10.1.1. Forge

    -

    10.1.2. Forge Furnace

    +

    8.2.2. 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 +the ability to run Forge add-ons in an embedded application. For more information about Forge Furnace, see: Run Forge Embedded.

    -

    10.1.3. TinkerPop

    +

    8.2.3. TinkerPop

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

    -

    10.1.4. Titan

    +

    8.2.4. 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.

    -

    10.1.5. Frames

    +

    8.2.5. Frames

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

    10.1.5. Frames

    -

    10.1.6. Gremlin

    +

    8.2.6. Gremlin

    Gremlin is a graph traversal language that allows you to query, analyze, and manipulate property graphs that implement the Blueprints property @@ -4441,7 +4367,7 @@

    10.1.6. Gremlin

    -

    10.1.7. Blueprints

    +

    8.2.7. Blueprints

    Blueprints is an industry standard API used to access graph databases. For more information about Blueprints, see: @@ -4449,7 +4375,7 @@

    10.1.7. Blueprints

    -

    10.1.8. Pipes

    +

    8.2.8. 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: @@ -4457,14 +4383,14 @@

    10.1.8. Pipes

    -

    10.1.9. Rexster

    +

    8.2.9. 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.

    -

    10.1.10. OCPsoft Rewrite

    +

    8.2.10. 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 @@ -4473,159 +4399,7 @@

    10.1.10. OCPsoft Rewrite

    -

    10.2. Dependencies (Forge add-ons)

    -
    -
    DRAFT
    -

    Based on -this -discussion.

    -
    -
    -

    10.2.1. Maven Add-on Structure

    -
    -

    The following is the typical structure of Maven add-on modules.

    -
    -
    -
    -
    myaddon-parent
-+--- myaddon - jar, classifier: forge-addon
-+--- myaddon-api - jar
-+--- myaddon-impl - jar
-+--- myaddon-tests - jar
    -
    -
    -
    -

    The add-on POM file can declare dependencies on other forge-addons. -To prevent exporting the add-on to dependent modules, use <optional>true</optional>.

    -
    -
    -
    -
    <dependency>
-    <groupId>org.jboss.forge.furnace.container</groupId>
-    <artifactId>cdi</artifactId>
-    <classifier>forge-addon</classifier>
-    <optional>true</optional>
-</dependency>
    -
    -
    -
    -

    The add-on POM files may also declare a dependency on typical Maven artifacts. -To prevent exporting the add-on to dependent modules, use <optional>true</optional>.

    -
    -
    -
    -
    <dependency>
-    <groupId>com.thinkaurelius.titan</groupId>
-    <artifactId>titan-lucene</artifactId>
-    <version>${version.titangraph.lucene}</version>
-</dependency>
    -
    -
    -
    -

    One more question regarding dependencies. Is it advisable to depend on the`forge-addon` -artifact from add-on’s subparts?

    -
    -
    -

    Add-ons should reference the <classifier>forge-addon</classifier> -artifact from other add-ons.

    -
    -
    -
    -

    10.2.2. Add-on sub-parts

    -
    -

    Add-on sub-parts declare dependency preferably on forge add-on APIs, not -on the add-ons themselves, wherever possible (wherever an add-on has an -explicit API). These dependencies must be marked as provided scope.

    -
    -
    -
    -
    <dependency>
-    <groupId>org.jboss.forge.furnace.container</groupId>
-    <artifactId>cdi-api</artifactId>
-    <classifier>forge-addon</classifier>
-    <scope>provided</scope>
-</dependency>
    -
    -
    -
    -

    They may instead depend on the primary add-on dependency, e.g. -forge-addon. The latter makes the POM files simpler, but can be confusing, -because the add-on dependency still needs to be declared in the depending -add-on’s POM.

    -
    -
    -
    -
    <dependency>
-    <groupId>org.jboss.forge.furnace.container</groupId>
-    <artifactId>cdi-api</artifactId>
-</dependency>
    -
    -
    -
    -

    Declaring a forge-addon depencendy anywhere else than the -forge-addon pom doesn’t actually cause Furnace to establish an add-on -dependency. I.e. classes from the dep won’t be available unless you -declare it in the `forge-addon’s pom.

    -
    -
    -

    Add-on’s sub-parts may also declare dependencies on other normal maven -dependencies, and these are treated as normal.

    -
    -
    - - - - - -
    -
    Note
    -    		 -
    -

    Add-on depends on API , scope compile > Addon -depends on Impl , scope compile with <optional>true</optional> - -prevents exporting this dependency to consumers of the add-on.

    -
    -
    -
    -
    -
    -

    10.2.3. Test dependencies

    -
    -

    For test dependencies on add-ons: Any addon/sub-part requiring an addon -for testing purposes should use <scope>test</scope>.

    -
    -
    -
    -
    <dependency>
-    <groupId>org.jboss.windup.graph</groupId>
-    <artifactId>windup-graph</artifactId>
-    <version>${project.version}</version>
-    <classifier>forge-addon</classifier>
-    <scope>test</scope>
-</dependency>
    -
    -
    -
    -
    -

    10.2.4. Dependencies between sub-parts within the same add-on

    -
    -

    Subpart may declare dependency on other subpart. E.g. impl typically -depends on api. In that case, the scope should be set appropriately -for the given situation - typically provided or compile scope.

    -
    -
    -
    -
    <dependency>
-    <groupId>org.jboss.windup.graph</groupId>
-    <artifactId>windup-graph-api</artifactId>
-    <scope>compile</scope>
-</dependency>
    -
    -
    -
    -
    -
    -

    10.3. Windup Models

    +

    8.3. Windup Models

    Windup models are the classes extending WindupVertexFrame. They are used to model the data in the graph database to Java objects.

    @@ -4638,7 +4412,7 @@

    10.3. Windup Models

    Windup Models Graphic

    -

    10.3.1. Meta Models

    +

    8.3.1. Meta Models

    • @@ -4651,17 +4425,17 @@

      10.3.1. Meta Models

    -

    10.3.2. Core Models

    +

    8.3.2. Core Models

    FileModel ArchiveModel

    -

    10.3.3. Reporting Models

    +

    8.3.3. Reporting Models

    -

    10.3.4. Custom Models (coming from Addons)

    +

    8.3.4. Custom Models (coming from Addons)

    See respective ruleset’s documentation.

    @@ -4672,7 +4446,7 @@

    10.3.4. Custom Models (coming from Ad

    diff --git a/html/WindupUserGuide.html b/html/WindupUserGuide.html index 37be263fec..ac75eed0d7 100644 --- a/html/WindupUserGuide.html +++ b/html/WindupUserGuide.html @@ -415,29 +415,35 @@

    Windup User Guide

    -

    Overview

    +

    1. Overview

    This guide is for engineers, consultants, and others who plan to use @@ -456,7 +462,7 @@

    Overview

    -

    What is Windup?

    +

    1.1. What is Windup?

    JBoss Windup is a rule-based tool to simplify application migrations.

    @@ -467,13 +473,13 @@

    What is Windup?

    migrating from other containers to JBoss EAP a piece of cake.

    -

    Windup 2.0 vs. Windup 0.7.x

    +

    1.1.1. 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?

    +

    1.1.2. 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 @@ -513,14 +519,14 @@

    How Does Windup Simplify Migration?

    -

    Follow Windup on Twitter!

    +

    1.1.3. Follow Windup on Twitter!

    Follow Windup on Twitter @JBossWindup for updates and more!

    -

    Features of Windup 2.0

    +

    1.2. Features of Windup 2.0

    @@ -577,7 +583,7 @@

    Features of Windup 2.0

    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.

    +

    Java-based rule add-ons 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. @@ -654,286 +660,49 @@

    Features of Windup 2.0

    -

    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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    -
    -
    -

    For more information about the phases of rule execution and how to control rule dependencies, see Rule Execution Lifecycle.

    -
    -
    -

    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.

    -
    +

    1.3. About the WINDUP_HOME Variable

    -

    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:

    +

    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.

    • -

      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.

      +

      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.

    • -

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

      +

      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.

    -
    -

    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.

    +
    +

    2. Get Started

    +
    -

    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 overview describing how to solve the problem migration areas.

        -
        • -
      -
      -
      • -
    • -

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

      -
      • -
    • -

      You can contribute Windup rules.

      -
      -
        -
      • -

        Write a Windup rule add-on to automate a migration process.

        -
        • -
      • -

        Create a test for the new rule.

        -
        • -
      • -

        For details, see the Windup Rules Development Guide.

        -
        • -
      -
      -
      • -
    • -

      You can also contribute to the project source code.

      -
      -
        -
      • -

        Create a core rule.

        -
        • -
      • -

        Improve performance or efficiency.

        -
        • -
      • -

        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!

    -
    -
    +

    2.1. Install Windup

    -

    Helpful links

    -
    -
    -
    -
    -

    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.

      -
      • -
    -
    -
    -
    -
    -
    -

    Run Windup

    -
    -
    -

    Install Windup

    +

    2.1.2. Download and Install Windup

    1. @@ -958,20 +727,21 @@

      Install Windup

    • +
    -

    Execute Windup

    +

    2.2. Execute Windup

    -

    Prerequisites

    +

    2.2.1. 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.

      +

      The fully qualified path of the application archive or folder you plan to migrate.

    2. -

      You also specify the fully qualified path to a folder that will contain the resulting report information. This path is passed using the --output argument on the command line.

      +

      The fully qualified path to a folder that will contain the resulting report information.

      • @@ -1026,7 +796,7 @@

        Prerequisites

    -

    Start Windup

    +

    2.2.2. Start Windup

    For information about the use of WINDUP_HOME in the instructions below, see About the WINDUP_HOME Variable.

    @@ -1067,33 +837,27 @@

    Start Windup

    -

    Run the windup-migrate-app Command

    +

    2.2.3. Run Windup

    1. -

      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.

      -
      +

      The command to run Windup is windup-migrate-app.

      +
      2. +
    2. +

      The following is a list of the most commonly used command line arguments.

      +
      +
      +
      --input INPUT_ARCHIVE_OR_FOLDER
      +
      +

      This is the fully qualified application archive or source path.

      +
      +
      --source-mode true (optional)
      +
      +

      This argument is optional and is only required if the application to be evaluated contains source files rather than compiled binaries. The default value is false.

      +
      +
      --output OUTPUT_REPORT_DIRECTORY
      +
      +

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

      @@ -1101,16 +865,44 @@

      Run the windup-migr
      Note

      -If the OUTPUT_REPORT_DIRECTORY directory exists, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information! +If the OUTPUT_REPORT_DIRECTORY directory exists and you do not specify the --overwrite argument, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information!
      +
      +
      --overwrite (optional)
      +
      +

      Specify this optional argument only if you are certain you want to force Windup to delete the existing OUTPUT_REPORT_DIRECTORY. The default value is false.

      +
      +
      --packages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
      +
      +

      This is a comma-delimited list of the packages to be evaluated by Windup.

      +
      +
      --excludePackages PACKAGE_1, PACKAGE_2, PACKAGE_N (optional)
      +
      +

      This is a comma-delimited list of the packages to be excluded by Windup.

      +
      +
      +
      +
      3. +
    3. +

      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
      +
      +
      -

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

      +

      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
      +
      -

      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 commands that use source code directories and archives located in the Windup GitHub repository.

    4. @@ -1150,7 +942,7 @@

      Run the windup-migr

    -

    Run Windup in Batch Mode

    +

    2.2.4. Run Windup in Batch Mode

    Windup can be also executed in batch mode within a shell or batch script using the --evaluate argument as follows.

    @@ -1172,9 +964,9 @@

    Run Windup in Batch Mode

    -

    Windup Help

    +

    2.2.5. Windup Help

    -

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

    +

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

    @@ -1183,7 +975,7 @@

    Windup Help

    -

    Windup Command Examples

    +

    2.2.6. Windup Command Examples

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

    @@ -1227,15 +1019,15 @@
    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.

    +

    The quickstarts provide examples of Java-based and XML-based rules 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 rules.

    -

    Review the Report

    +

    2.3. Review the Report

    -

    About the Report

    +

    2.3.1. 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:

    @@ -1268,7 +1060,7 @@

    About the Report

    -

    Open the Report

    +

    2.3.2. 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:

    @@ -1280,7 +1072,7 @@

    Open the Report

    -

    Report Sections

    +

    2.3.3. Report Sections

    Application Report Page
    @@ -1396,7 +1188,7 @@
    File Analysis Pages
    -

    Additional Reports

    +

    2.3.4. Additional Reports

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

    @@ -1429,18 +1221,18 @@
    Individual File Analysis Reports
    -

    Additional Resources

    +

    3. Additional Resources

    -

    Review the Windup Quickstarts

    +

    3.1. 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

    +

    The Windup quickstarts provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. 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

    +

    3.1.1. Download the Latest ZIP

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

    @@ -1449,7 +1241,7 @@

    Download the Latest ZIP

    -

    Fork and Clone the GitHub Project

    +

    3.1.2. Fork and Clone the GitHub Project

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

    @@ -1495,15 +1287,226 @@

    Fork and Clone the GitHub Project

    -

    Known Windup Issues

    +

    3.2. Get Involved

    +
    +

    3.2.1. 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 overview describing how to solve the problem migration areas.

        +
        • +
      +
      +
      • +
    • +

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

      +
      • +
    • +

      You can contribute Windup rules.

      +
      +
        +
      • +

        Write a Windup rule add-on to automate a migration process.

        +
        • +
      • +

        Create a test for the new rule.

        +
        • +
      • +

        For details, see the Windup Rules Development Guide.

        +
        • +
      +
      +
      • +
    • +

      You can also contribute to the project source code.

      +
      +
        +
      • +

        Create a core rule.

        +
        • +
      • +

        Improve performance or efficiency.

        +
        • +
      • +

        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!

    +
    +
    +
    +

    3.2.2. Helpful links

    +
    + +
    +
    +

    You can also follow us on this IRC channel: irc.freenode.net#windup.

    +
    +
    +
    +
    +

    3.3. Known Windup Issues

    Windup known issues are tracked here: Open Windup issues

    -

    Glossary of Terms Used in Windup

    +

    3.4. 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.

    +
    +
    +

    3.4.1. 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. +
    +
    +
    -

    Rules Terms

    +

    3.4.2. 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. +
    +
    +
    +
    +
    +
    +
    +

    4. Appendix

    +
    +
    +

    4.1. Glossary of Terms Used in Windup

    +
    +

    4.1.1. Rules Terms

    Rule
    @@ -1566,7 +1569,7 @@

    Rules Terms

    -

    Reporting Terms

    +

    4.1.2. Reporting Terms

    Lift and Shift (Level of effort)
    @@ -1590,7 +1593,62 @@

    Reporting Terms

    -

    Windup Architectural Components

    +

    4.2. 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.

    +
    +
    +

    4.2.1. 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 data model and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    +
    +
    +

    For more information about the phases of rule execution and how to control rule dependencies, see Rule Execution Lifecycle.

    +
    +
    +

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

    +
    +
    +
    +

    4.2.2. 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.

    +
    +
    +
    +

    4.2.3. 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.

    +
    +
    +
    +
    +

    4.3. 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 @@ -1598,7 +1656,7 @@

    Windup Architectural Components

    familiar with them.

    -

    Forge

    +

    4.3.1. Forge

    Forge is an open source, extendable, rapid application development tool for creating Java EE applications using Maven. For more information @@ -1606,30 +1664,30 @@

    Forge

    -

    Forge Furnace

    +

    4.3.2. 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 +the ability to run Forge add-ons in an embedded application. For more information about Forge Furnace, see: Run Forge Embedded.

    -

    TinkerPop

    +

    4.3.3. TinkerPop

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

    -

    Titan

    +

    4.3.4. 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

    +

    4.3.5. Frames

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

    Frames

    -

    Gremlin

    +

    4.3.6. Gremlin

    Gremlin is a graph traversal language that allows you to query, analyze, and manipulate property graphs that implement the Blueprints property @@ -1650,7 +1708,7 @@

    Gremlin

    -

    Blueprints

    +

    4.3.7. Blueprints

    Blueprints is an industry standard API used to access graph databases. For more information about Blueprints, see: @@ -1658,7 +1716,7 @@

    Blueprints

    -

    Pipes

    +

    4.3.8. 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: @@ -1666,14 +1724,14 @@

    Pipes

    -

    Rexster

    +

    4.3.9. 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

    +

    4.3.10. 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 @@ -1681,12 +1739,221 @@

    OCPsoft Rewrite

    +
    +

    4.4. Rule Execution Lifecycle

    +
    +

    4.4.1. Rule Lifecycle

    +
    +

    Windup executes each rule in a sequential order. 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 a graphical overview of rule processing, see +this +diagram.

    +
    +
    +
    +

    4.4.2. Rule Phases

    +
    +
    +
    INFO: Loaded [67] org.jboss.windup.config.WindupRuleProvider [
+org.jboss.windup.config.phase.Implicit
+org.jboss.windup.config.phase.Initialization
+org.jboss.windup.config.phase.Discovery
+org.jboss.windup.config.phase.ArchiveExtraction
+org.jboss.windup.config.phase.ArchiveMetadataExtraction
+org.jboss.windup.config.phase.ClassifyFileTypes
+org.jboss.windup.config.phase.DiscoverProjectStructure
+org.jboss.windup.config.phase.Decompilation
+org.jboss.windup.config.phase.InitialAnalysis
+org.jboss.windup.config.phase.MigrationRules
+org.jboss.windup.config.phase.PostMigrationRules
+org.jboss.windup.config.phase.PreReportGeneration
+org.jboss.windup.config.phase.ReportGeneration
+org.jboss.windup.config.phase.PostReportGeneration
+org.jboss.windup.config.phase.ReportRendering
+org.jboss.windup.config.phase.PostReportRendering
+org.jboss.windup.config.phase.Finalize
+org.jboss.windup.config.phase.PostFinalize
+]
    +
    +
    +
    +

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

    +
    +
    +

    Rule phases provide a 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 InitialAnalysis.class;
+}
    +
    +
    +
    +

    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 phase 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.

    +
    +
    +
    +

    4.4.3. 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.

    +
    +
    +
    +
    @Override
+public List<Class<? extends WindupRuleProvider>> getExecuteBefore()
+{
+   return asClassList(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.

    +
    +
    +
    +
    @Override
+public List<Class<? extends WindupRuleProvider>> getExecuteAfter()
+{
+    return asClassList(RuleToFireAfter.class);
+}
    +
    +
    +
    +
    +
    +

    4.5. Rule Story Points

    +
    +

    4.5.1. What are Story Points?

    +
    +

    Story points are an abstract metric commonly used in Scrum Agile software development methodology to estimate the level of effort needed to implement a feature or change. 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. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

    +
    +
    +
    +

    4.5.2. How Story Points are Estimated in Rules

    +
    +

    Estimating story points for a rule can be tricky. The following are the general guidelines Windup uses when estimating the level of effort required for a rule.

    +
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Level of EffortStory PointsDescription

    Lift and Shift

    0

    The code or file is standards-based and requires no effort.

    Mapped

    1- 2 per file

    There is a standard mapping algorithm to port the code or file. The number of story points required is small, but is dependent on the number of files to port.

    Custom

    5 - 20 per change or component

    +

    The number of story points required to modify and rewrite code depends on the complexity of the change, the number of unknown imports, the size of the files, and the number of components. The following are examples of how to estimate story points.

    +
    +
    +
      +
    • +

      Port MyBatis to JPA: '20' story points per query.

      +
      • +
    • +

      Port a web page from one web framework to another depends on the complexity and the number of components involved in the migration. You could estimate '20' story points per component.

      +
      • +
    +
    +
    +
    diff --git a/scripts/pagelinksCoreDevelopmentGuide.sh b/scripts/pageLinksCoreDevelopmentGuide.sh similarity index 100% rename from scripts/pagelinksCoreDevelopmentGuide.sh rename to scripts/pageLinksCoreDevelopmentGuide.sh diff --git a/scripts/pageLinksRulesDevelopmentGuide.sh b/scripts/pageLinksRulesDevelopmentGuide.sh new file mode 100755 index 0000000000..c1ba981e1f --- /dev/null +++ b/scripts/pageLinksRulesDevelopmentGuide.sh @@ -0,0 +1,72 @@ +#!/bin/bash + +# Windup Rules Development Guide + +pwd + +## Overview + +grep 'link:[A-Z]' `find . -name 'What-is-Windup.adoc'` +grep 'link:[A-Z]' `find . -name 'Features-of-Windup-2.0.adoc'` +grep 'link:[A-Z]' `find . -name 'Windup-Processing-Overview.adoc'` +grep 'link:[A-Z]' `find . -name 'Get-Involved.adoc'` +grep 'link:[A-Z]' `find . -name 'Report-Issues-with-Windup.adoc'` +grep 'link:[A-Z]' `find . -name 'About-the-WINDUP_HOME-Variable.adoc'` + +## Get Started + +grep 'link:[A-Z]' `find . -name 'Install-Windup.adoc'` +grep 'link:[A-Z]' `find . -name 'Execute-Windup.adoc'` +grep 'link:[A-Z]' `find . -name 'Review-the-Report.adoc'` + + +## Configure Your System for Java-based Rules + +grep 'link:[A-Z]' `find . -name 'Install-and-Configure-Maven.adoc'` + +## Understand the Rule Processing + +grep 'link:[A-Z]' `find . -name 'Windup-Processing-Overview.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Rule-Execution-Lifecycle.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Rule-Story-Points.adoc'` + +## Create and Test Java Rule Addons + +grep 'link:[A-Z]' `find . -name 'Rules-Java-based-Rule-Structure.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Basic-Rule-Execution-Flow-Patterns.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Create-an-Advanced-Ruleset.adoc'` + +## Create and Test XML Rules + +grep 'link:[A-Z]' `find . -name 'Rules-Create-a-Basic-XML-Rule.adoc'` + +## Review the Report + +grep 'link:[A-Z]' `find . -name 'Review-the-Report.adoc'` + +## External Rule Examples + +grep 'link:[A-Z]' `find . -name 'Review-the-Windup-Quickstarts.adoc'` + +## Debugging and Troubleshooting + +grep 'link:[A-Z]' `find . -name 'Dev-Debugging-and-Profiling.adoc'` +grep 'link:[A-Z]' `find . -name 'Dev-Troubleshoot-Windup-Issues.adoc'` + + +## Additional Resources + +grep 'link:[A-Z]' `find . -name 'Rules-Available-Rules-Utilities.adoc'` +grep 'link:[A-Z]' `find . -name 'Review-the-Windup-Quickstarts.adoc'` +grep 'link:[A-Z]' `find . -name 'Known-Issues.adoc'` +grep 'link:[A-Z]' `find . -name 'Glossary.adoc'` + +## Appendix + +grep 'link:[A-Z]' `find . -name 'Windup-Architectural-Components.adoc'` +grep 'link:[A-Z]' `find . -name 'Dev-Dependencies.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Windup-Models.adoc'` + + + diff --git a/scripts/pagelinksUserGuide.sh b/scripts/pageLinksUserGuide.sh similarity index 82% rename from scripts/pagelinksUserGuide.sh rename to scripts/pageLinksUserGuide.sh index 47aff2e99e..6eff718b69 100755 --- a/scripts/pagelinksUserGuide.sh +++ b/scripts/pageLinksUserGuide.sh @@ -3,6 +3,8 @@ #cd ~/GitRepos/windup-documentation/docs pwd +### THIS IS WRONG! IT NEEDS TO BE RECURSIVE + ## Overview grep 'link:[A-Z]' `find . -name 'What-is-Windup.adoc'` @@ -22,8 +24,13 @@ grep 'link:[A-Z]' `find . -name 'Review-the-Report.adoc'` grep 'link:[A-Z]' `find . -name 'Review-the-Windup-Quickstarts.adoc'` grep 'link:[A-Z]' `find . -name 'Known-Issues.adoc'` + + +## Appendix grep 'link:[A-Z]' `find . -name 'Glossary.adoc'` grep 'link:[A-Z]' `find . -name 'Windup-Architectural-Components.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Rule-Execution-Lifecycle.adoc'` +grep 'link:[A-Z]' `find . -name 'Rules-Rule-Story-Points.adoc'` diff --git a/scripts/windupDocUpdate.sh b/scripts/windupDocUpdate.sh index 054686c7e0..57d18414f6 100755 --- a/scripts/windupDocUpdate.sh +++ b/scripts/windupDocUpdate.sh @@ -193,6 +193,7 @@ cp $1/Dev-Logging.asciidoc docs/Dev-Logging.adoc cp $1/Dev-Variables-Stack.asciidoc docs/Dev-Variables-Stack.adoc cp $1/Dev-Port-WindRide-Functionality-to-Windup.asciidoc docs/Dev-Port-WindRide-Functionality-to-Windup.adoc cp $1/Dev-Git-Rebasing.asciidoc docs/Dev-Git-Rebasing.adoc +cp $1/Dev-Windup-Release-Process.asciidoc docs/Dev-Windup-Release-Process.adoc ## Rule topics cp $1/Rules-Windup-Models.asciidoc docs/Rules-Windup-Models.adoc @@ -217,6 +218,7 @@ cp $1/Rules-Ops-Xml-XsltTransformation.asciidoc docs/Rules-Ops-Xml-XsltTransform cp $1/Rules-Rule-Execution-Lifecycle.asciidoc docs/Rules-Rule-Execution-Lifecycle.adoc cp $1/Rules-Java-based-Rule-Structure.asciidoc docs/Rules-Java-based-Rule-Structure.adoc cp $1/Rules-Rule-Story-Points.asciidoc docs/Rules-Rule-Story-Points.adoc +cp $1/Rules-Difference-Between-XML-based-and-Java-based-Rules.asciidoc docs/Rules-Difference-Between-XML-based-and-Java-based-Rules.adoc echo "Copy complete." echo "" @@ -247,7 +249,7 @@ echo "* Make sure the linked to pages are part of the book." echo "*******************************************" echo "" cd docs -sh $2/scripts/pagelinksUserGuide.sh +sh $2/scripts/pageLinksUserGuide.sh # grep 'link:[A-Z]' `find . -name '*.adoc'` cd ../ echo "" @@ -262,7 +264,7 @@ echo "* Make sure the linked to pages are part of the book." echo "*******************************************" echo "" cd docs -sh $2/scripts/pagelinksRulesDevelopmentGuide.sh +sh $2/scripts/pageLinksRulesDevelopmentGuide.sh # grep 'link:[A-Z]' `find . -name '*.adoc'` cd ../ echo "" @@ -276,7 +278,7 @@ echo "* Make sure the linked to pages are part of the book." echo "*******************************************" echo "" cd docs -sh $2/scripts/pagelinksCoreDevelopmentGuide.sh +sh $2/scripts/pageLinksCoreDevelopmentGuide.sh # grep 'link:[A-Z]' `find . -name '*.adoc'` cd ../ echo "" @@ -313,4 +315,7 @@ asciidoctor -t -dbook -a toc -o html/WindupCoreDevelopmentGuide.html docs/Windup echo "Guide is located at: " file://$2/html/WindupCoreDevelopmentGuide.html echo "" +echo "*******************************************" +echo "Manually verify the guides and use Maven to check in the new files" +echo "*******************************************"