From 60fc115d964644576ffb516dc00588768a4e3e4d Mon Sep 17 00:00:00 2001 From: Sande Gilda Date: Fri, 19 Dec 2014 15:30:40 -0500 Subject: [PATCH] Updates from the Wiki --- CONTRIBUTING.adoc | 4 +- README.adoc | 87 ++- docs/About-the-Windup-Wiki.adoc | 48 ++ docs/Core-Development-Guide.asciidoc | 29 +- docs/Dev-Add-Images-to-the-Windup-Wiki.adoc | 48 ++ docs/Dev-Classloading-Notes.adoc | 5 +- docs/Dev-Concepts-and-Philosophy.adoc | 5 +- .../Dev-Connect-to-the-Graph-via-Rexster.adoc | 1 + ...up.adoc => Dev-Create-Windup-JavaDoc.adoc} | 25 +- docs/Dev-Decompiling.adoc | 3 +- docs/Dev-Dependencies.adoc | 4 +- docs/Dev-Development-Guidelines.adoc | 1 + docs/Dev-Frames-Extensions.adoc | 1 + docs/Dev-Get-the-Windup-Source-Code.adoc | 1 + docs/Dev-Git-Rebasing.adoc | 1 + docs/Dev-Internal-API-Features.adoc | 1 + docs/Dev-Logging.adoc | 1 + ...Port-WindRide-Functionality-to-Windup.adoc | 1 + ...it-Code-Updates-to-the-Windup-Project.adoc | 1 + docs/Dev-Variables-Stack.adoc | 1 + docs/Dev-Windup-Bootstrap.adoc | 3 +- docs/Dev-Windup-Documentation-Process.adoc | 75 ++ docs/Dev-Windup-Project-Information.adoc | 1 + docs/Dev-Windup-Project-Structure.adoc | 3 +- docs/Execute-Windup.adoc | 4 +- docs/Features-of-Windup-2.0.adoc | 2 +- docs/Get-Involved.adoc | 12 +- docs/Rules-Create-Java-Queries.adoc | 1 + docs/Rules-Create-an-Advanced-Ruleset.adoc | 2 +- docs/Rules-Development-Guide.asciidoc | 25 +- docs/Rules-Java-based-Rule-Structure.adoc | 38 +- docs/Rules-Ops-Reporting-Hint.adoc | 7 +- docs/Rules-Rule-Story-Points.adoc | 17 +- docs/Rules-Rules-Metadata.adoc | 3 +- docs/Rules-Rules-Operations.adoc | 2 + docs/Ruleset-Java-Basic-Ruleset.adoc | 2 +- ...Java-Classifications-and-Inline-Hints.adoc | 2 +- docs/Ruleset-Java-EE-Apps.adoc | 7 +- docs/Ruleset-Java-EE-Servers.adoc | 4 +- docs/Ruleset-Reporting.adoc | 7 +- docs/Ruleset-XML.adoc | 2 +- docs/User-Guide.asciidoc | 12 +- docs/What-is-Windup.adoc | 13 +- docs/Windup-Core-Development-Guide.adoc | 8 +- docs/Windup-User-Guide.adoc | 4 - html/WindupCoreDevelopmentGuide.html | 659 ++++++++++++++---- html/WindupRulesDevelopmentGuide.html | 118 +++- html/WindupUserGuide.html | 197 ++---- scripts/windupDocPublish.sh | 13 + scripts/windupDocUpdate.sh | 12 +- 50 files changed, 1131 insertions(+), 392 deletions(-) create mode 100644 docs/About-the-Windup-Wiki.adoc create mode 100644 docs/Dev-Add-Images-to-the-Windup-Wiki.adoc rename docs/{Dev-Create-JavaDoc-for-Windup.adoc => Dev-Create-Windup-JavaDoc.adoc} (62%) create mode 100644 docs/Dev-Windup-Documentation-Process.adoc create mode 100755 scripts/windupDocPublish.sh diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index f61cd51774..878ed61f70 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -78,9 +78,9 @@ cp ../windup.wiki/What-is-Windup.asciidoc docs/What-is-Windup.adoc grep 'xref:[a-z]' `find . -name '*.adoc'` ---- -** Finds and lists pages containing `link:` macros to other pages. These pages must be added to the book. +** Finds and lists pages containing `xref:` macros to other pages. These pages must be added to the book. -** Replaces the `link:` macros with a `xref:` macros. +** Replaces the `xref:` macros with a `xref:` macros. + ---- asciidoctor -dbook -a toc -o html/WindupUserGuide.html docs/Windup-User-Guide.adoc diff --git a/README.adoc b/README.adoc index 43e8be035a..5280b21e81 100644 --- a/README.adoc +++ b/README.adoc @@ -1,7 +1,90 @@ = Windup 2.0 Product Documentation -Windup project documentation is created collaboratively on the Windup project Wiki site located here: . +== Overview +Windup project documentation is created collaboratively on the Windup project Wiki site located here: . 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 + +Run the scripts/windupDocUpdate.sh script to copy and modify the files. + +. 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. + +== Procedure to Publish the Guides + +* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. ++ +---- +git clone https://github.com/windup/windup.git +git fetch upstream +---- + +* The first time, you must fork and clone the windup-documentation GitHub repository. After that, just fetch the latest upstream. ++ +---- +git clone https://github.com/windup/windup-documentation.git +git fetch upstream +---- + +* Navigate to the local windup directory. ++ +---- +cd windup +---- + +* Checkout the gh-pages from the windup repository ++ +---- +git checkout -b gh-pages windup +---- + +* If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory. ++ +---- +mkdir -p docs/2.0.0.Beta6/html (if it doesn't exist!) +---- + +* Copy any new images, stylesheets, and html files from windup-documentation: ++ +---- +cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.Beta6/html +---- + +* Add the updated files to GitHub. ++ +---- +git add docs +---- + +* Commit the changes. ++ +---- +git commit -m "Update message..." +---- + +* Push the changes to GitHub. ++ +---- +git push upstream gh-pages +---- + +== Access the Guides + +View the documentation at the following URLs. + +[cols="2*"] +|=== +| **Guide** | **URL** +| Windup User Guide | http://windup.github.io/windup/docs/2.0.0.Beta6/html/WindupUserGuide.html +| Windup Rules Development Guide | http://windup.github.io/windup/docs/2.0.0.Beta6/html/WindupRulesDevelopmentGuide.html +| Windup Core Development Guide | http://windup.github.io/windup/docs/2.0.0.Beta6/html/WindupCoreDevelopmentGuide.html +| Windup Migration Planning Guide | TBD +|=== + + + -This repository will contain the official documentation when the Windup 2.0 ships. diff --git a/docs/About-the-Windup-Wiki.adoc b/docs/About-the-Windup-Wiki.adoc new file mode 100644 index 0000000000..dab5ae3f18 --- /dev/null +++ b/docs/About-the-Windup-Wiki.adoc @@ -0,0 +1,48 @@ +[[About-the-Windup-Wiki]] +=== About the Windup Wiki + +==== Purpose + +This wiki is a place to create Windup documentation in a collaborative manner, a bit wildly, and on the fly. It is intended to reflect the state of the Windup source code master branch, however pages may become obsolete as the master changes quickly. + +==== Areas of Interest + +The Wiki pages are divided into the following main areas of interest, which may often overlap. The page names use these prefixes: + +* *Dev-: ...*: These pages are of interest to Windup core developers. +* *Rules- ...*: These pages are of interest to rules developers. +* *User- ...*: These pages that are of interest to Windup users. +* no prefix: These pages that are also of interest to Windup users. + +==== Markdown, AsciiDoc, or...? + +This Wiki uses AsciiDoc because it is capable of handling the publishing requirements and structural elements needed to create technical books. If you would like to contribute to the documentation, feel free to use your favorite Wiki language, however, it will ultimately be converted to AsciiDoc. + +==== Contributor Guidelines + +Please see the https://github.com/windup/windup-documentation/blob/master/CONTRIBUTING.adoc[Contributing Guidelines] for details about how to name pages and use the correct AsciiDoc syntax to make the transition to the final documentation go more smoothly. + +The following is a brief overview. + +* Name wiki pages using only letters, numbers and dashes. Do not include spaces, colons, or other special characters in page names. + +* Be sure to add a level 3 page heading (===) at the top of each page. When compiled in a book, the Guide name is the top level, chapters are level 2, and the page is level 3. This is the title that appears in the table of contents for the page. + + === Build Windup from Source + +* At the beginning of each new Wiki page, add an anchor with the exact page name, including the dashes. This generates the correct anchors that are needed when the pages are combined into a book. + + [[Dev-Build-Windup-from-Source]] + === Build Windup from Source + +* Wiki generates anchors using dashes for spaces. AsciiDoctor generates a leading underscore and underscores for spaces.When referring to another section within the same page, do not use the `<>` syntax. Instead, create an anchor and use the 'xref:' syntax to provide the link. Replace spaces in the section title with dashes. + + Create the anchor at the top of the section using double brackets to force the generation of dashes instead of underscores. + + [[windup-command-examples]] + ==== Windup Command Examples + + Then use the `xref` to create the link. + + See xref:windup-command-examples[Windup Command Examples] for more information. + diff --git a/docs/Core-Development-Guide.asciidoc b/docs/Core-Development-Guide.asciidoc index 7261cb1bb3..eb2f071a71 100644 --- a/docs/Core-Development-Guide.asciidoc +++ b/docs/Core-Development-Guide.asciidoc @@ -1,20 +1,20 @@ -= Windup Core Development Guide +[[Core-Development-Guide]] +=== Windup Core Development Guide This guide is for developers who plan to contribute source code updates or core rule add-ons to the Windup 2.0 project. -== Overview +==== Overview * link:What-is-Windup[What is Windup]? * link:Features-of-Windup-2.0[Features of Windup 2.0] * link:Get-Involved[Get Involved] - We need your feedback! * link:Dev-Windup-Project-Information[Windup Project Information] - Github repository, IRC, Mailing lists, ... -* link:Dev-Create-JavaDoc-for-Windup[Create JavaDoc for Windup] * link:Report-Issues-with-Windup[Report Issues with Windup * link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] -== Get Started +==== Get Started * link:Install-and-Configure-Maven[Install and Configure Maven] * link:Dev-Get-the-Windup-Source-Code[Get the Windup Source Code] * link:Dev-Build-Windup-from-Source[Build Windup from Source] @@ -22,27 +22,25 @@ repository, IRC, Mailing lists, ... * link:Review-the-Report[Review the Report] * link:Glossary[Glossary of Terms] -== Developer Contributing Information +==== Developer Contributing Information * link:Dev-Development-Guidelines[Developer Guidelines] * link:Dev-Submit-Code-Updates-to-the-Windup-Project[Submit Code Updates to the Windup Project] -== Understand the Windup Architecture and Structure +==== Understand the Windup Architecture and Structure * link:Dev-Windup-Architectural-Components[Windup Architectural Components] * link:Dev-Windup-Project-Structure[Windup Project Structure] -== Rules and Rulesets +==== Rules and Rulesets -== Debugging and Troubleshooting +==== Debugging and Troubleshooting * link:Dev-Debugging-and-Profiling[Debugging and Profiling] * link:Dev-Troubleshooting[Troubleshooting] -== Miscellaneous Pages - -=== Developer topics +==== Developer topics * link:Dev-Windup-Bootstrap[Bootstrap] * link:Dev-Classloading-Notes[Classloading Notes] @@ -56,7 +54,7 @@ repository, IRC, Mailing lists, ... * link:Dev-Port-WindRide-Functionality-to-Windup[Port WindRide Functionality to Windup] * link:Dev-Git-Rebasing[Git Rebasing] -=== Rules topics +==== Rules topics * link:Rules-Available-Rules-Utilities[Available Utilities] * link:Dev-Concepts-and-Philosophy[Concepts and Philosophy] @@ -80,3 +78,10 @@ repository, IRC, Mailing lists, ... * link:Rules-Java-based-Rule-Structure[Java-Based Rule Structure] * link:Rules-Rule-Story-Points[Rule Story Points] +==== Wiki and Product Documentation + +* link:About-the-Windup-Wiki[About the Windup Wiki] +* link:Dev-Add-Images-to-the-Windup-Wiki[Add Images to the Windup Wiki] +* link:Dev-Create-Windup-JavaDoc[Create Windup JavaDoc] +* link:Dev-Windup-Documentation-Process[Windup Documentation Process] + diff --git a/docs/Dev-Add-Images-to-the-Windup-Wiki.adoc b/docs/Dev-Add-Images-to-the-Windup-Wiki.adoc new file mode 100644 index 0000000000..9b74c08e45 --- /dev/null +++ b/docs/Dev-Add-Images-to-the-Windup-Wiki.adoc @@ -0,0 +1,48 @@ +[[Dev-Add-Images-to-the-Windup-Wiki]] +=== Add Images to the Windup Wiki + +* Fork https://github.com/windup/windup/wiki +* Clone the Windup Wiki into a `windup.wiki/` directory using the SSH clone URL: + + git clone git@github.com:USER_NAME/windup.git windup.wiki + +* Navigate to the new `windup.wiki/` directory. + +* Add the upstream repository. + + git remote add -f upstream git@github.com:windup/windup.wiki.git + +* Check out a branch to work in. + + git checkout -b BRANCH_NAME upstream/master + +* Copy the image into the `windup.wiki/images` directory + + cp IMAGE_NAME.png images/ + +* Add the new image to Git + + git add images/IMAGE_NAME.png + +* Commit the change + + git commit -m "Add new image" + +* Push the change to your Windup Wiki repository. + + git push origin HEAD:master + +* Test the new image in a page on your own Wiki. + + image:images/IMAGE_NAME.png[New Image] + ++ +For example: + ++ +image:images/windup-logo-large.png[Windup Logo] + +* If it works, push the image to the upstream repository + + git push upstream HEAD:master + diff --git a/docs/Dev-Classloading-Notes.adoc b/docs/Dev-Classloading-Notes.adoc index a3e81795b8..520c8da20b 100644 --- a/docs/Dev-Classloading-Notes.adoc +++ b/docs/Dev-Classloading-Notes.adoc @@ -1,6 +1,9 @@ +[[Dev-Classloading-Notes]] === Classloading Notes -DRAFT - _Page contains temporary notes, to be edited._ +.DRAFT + +_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. diff --git a/docs/Dev-Concepts-and-Philosophy.adoc b/docs/Dev-Concepts-and-Philosophy.adoc index 63cc7cd563..1963bd5043 100644 --- a/docs/Dev-Concepts-and-Philosophy.adoc +++ b/docs/Dev-Concepts-and-Philosophy.adoc @@ -1,7 +1,8 @@ -_TODO - OZIZKA: Can this topic be marked obsolete and be replaced by this one: xref:Windup-Processing-Overview[Windup Processing Overview] ?_ - +[[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] ?_ + Windup is a rule-based tool that allows users to write customized rules based on the needs, constructs, and custom APIs used in their applications. diff --git a/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc b/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc index 4c14c07cb1..0bf67f8a3d 100644 --- a/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc +++ b/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc @@ -1,3 +1,4 @@ +[[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 diff --git a/docs/Dev-Create-JavaDoc-for-Windup.adoc b/docs/Dev-Create-Windup-JavaDoc.adoc similarity index 62% rename from docs/Dev-Create-JavaDoc-for-Windup.adoc rename to docs/Dev-Create-Windup-JavaDoc.adoc index e3bd4f2c67..1fc49110ba 100644 --- a/docs/Dev-Create-JavaDoc-for-Windup.adoc +++ b/docs/Dev-Create-Windup-JavaDoc.adoc @@ -1,12 +1,15 @@ -=== Create JavaDoc for Windup - -Use the following procedure to create JavaDoc for Windup. - -. In Windup project root directory, type the following Maven command: -+ ------------------------------------ -mvn validate -PjavadocDist ------------------------------------ -. The JavaDoc is created in the Windup `target/site/apidocs` subdirectory. - +[[Dev-Create-Windup-JavaDoc]] +=== Create Windup JavaDoc + +The most recent Windup JavaDoc build is located here: http://windup.github.io/windup/docs/javadoc/latest/index.html + +If you want to build an updated version, use the following procedure to create JavaDoc for Windup. + +. In Windup project root directory, type the following Maven command: ++ +----------------------------------- +mvn validate -PjavadocDist +----------------------------------- +. The JavaDoc is created in the Windup `target/site/apidocs` subdirectory. + NOTE: To cross-link with 3rd-party libraries, see https://issues.jboss.org/browse/WINDUP-422[WINDUP-422} and http://stackoverflow.com/questions/27392535/javadoc-how-to-make-it-link-the-dependencies-maven-project. \ No newline at end of file diff --git a/docs/Dev-Decompiling.adoc b/docs/Dev-Decompiling.adoc index 30796ce874..f17b46a694 100644 --- a/docs/Dev-Decompiling.adoc +++ b/docs/Dev-Decompiling.adoc @@ -1,6 +1,7 @@ +[[Dev-Decompiling]] === Decompiling -DRAFT: +.DRAFT ==== The *Decompiler* API diff --git a/docs/Dev-Dependencies.adoc b/docs/Dev-Dependencies.adoc index 30e5917bf9..7dcd08e12d 100644 --- a/docs/Dev-Dependencies.adoc +++ b/docs/Dev-Dependencies.adoc @@ -1,7 +1,9 @@ [[Dev-Dependencies]] === Dependencies (Forge add-ons) -DRAFT _Based on +.DRAFT + +_Based on https://github.com/OndraZizka/windup/commit/3574e81900cbad2b3a83d0bd6c263eb22c48e55e[this] discussion._ diff --git a/docs/Dev-Development-Guidelines.adoc b/docs/Dev-Development-Guidelines.adoc index 14446ebcbb..5ed6d85ad5 100644 --- a/docs/Dev-Development-Guidelines.adoc +++ b/docs/Dev-Development-Guidelines.adoc @@ -1,3 +1,4 @@ +[[Dev-Development-Guidelines]] === Development Guidelines ==== Project Source Code Format diff --git a/docs/Dev-Frames-Extensions.adoc b/docs/Dev-Frames-Extensions.adoc index 3841ce34d4..504e217936 100644 --- a/docs/Dev-Frames-Extensions.adoc +++ b/docs/Dev-Frames-Extensions.adoc @@ -1,3 +1,4 @@ +[[Dev-Frames-Extensions]] === Frames Extensions Windup has several Frames extensions to satisfy its needs. diff --git a/docs/Dev-Get-the-Windup-Source-Code.adoc b/docs/Dev-Get-the-Windup-Source-Code.adoc index 5d9871344c..92994d573c 100644 --- a/docs/Dev-Get-the-Windup-Source-Code.adoc +++ b/docs/Dev-Get-the-Windup-Source-Code.adoc @@ -1,3 +1,4 @@ +[[Dev-Get-the-Windup-Source-Code]] === 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. diff --git a/docs/Dev-Git-Rebasing.adoc b/docs/Dev-Git-Rebasing.adoc index ff1db6a997..ceb1f9707d 100644 --- a/docs/Dev-Git-Rebasing.adoc +++ b/docs/Dev-Git-Rebasing.adoc @@ -1,3 +1,4 @@ +[[Dev-Git-Rebasing]] === Git Rebasing Ondra Zizka wrote this simple script to bring down a series of pull requests into a diff --git a/docs/Dev-Internal-API-Features.adoc b/docs/Dev-Internal-API-Features.adoc index d95776e3fa..0db7e4c200 100644 --- a/docs/Dev-Internal-API-Features.adoc +++ b/docs/Dev-Internal-API-Features.adoc @@ -1,3 +1,4 @@ +[[Dev-Internal-API-Features]] === Internal API Features ==== Find the RuleProvider that provided a Rule diff --git a/docs/Dev-Logging.adoc b/docs/Dev-Logging.adoc index 5dbb309b79..cc781e961f 100644 --- a/docs/Dev-Logging.adoc +++ b/docs/Dev-Logging.adoc @@ -1,3 +1,4 @@ +[[Dev-Logging]] === Logging .DRAFT diff --git a/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc b/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc index e54f1b9ddf..36e0d7da47 100644 --- a/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc +++ b/docs/Dev-Port-WindRide-Functionality-to-Windup.adoc @@ -1,3 +1,4 @@ +[[Dev-Port-WindRide-Functionality-to-Windup]] === Port WindRide Functionality to Windup _For the purposes of tracking the porting WindRide functionality to Windup. Will be diff --git a/docs/Dev-Submit-Code-Updates-to-the-Windup-Project.adoc b/docs/Dev-Submit-Code-Updates-to-the-Windup-Project.adoc index 8f51bb2532..55c701bbc9 100644 --- a/docs/Dev-Submit-Code-Updates-to-the-Windup-Project.adoc +++ b/docs/Dev-Submit-Code-Updates-to-the-Windup-Project.adoc @@ -1,3 +1,4 @@ +[[Dev-Submit-Code-Updates-to-the-Windup-Project]] === Submit Code Updates to the Windup Project To get the Windup Source Code, see xref:Dev-Get-the-Windup-Source-Code[Get the Windup Source Code] for instructions. diff --git a/docs/Dev-Variables-Stack.adoc b/docs/Dev-Variables-Stack.adoc index 9b87d1b072..015b4bc3fa 100644 --- a/docs/Dev-Variables-Stack.adoc +++ b/docs/Dev-Variables-Stack.adoc @@ -1,3 +1,4 @@ +[[Dev-Variables-Stack]] === Variables Stack The `Variables` class stores the variables which are available in rules, EL expressions, and FreeMarker and XSLT templates. diff --git a/docs/Dev-Windup-Bootstrap.adoc b/docs/Dev-Windup-Bootstrap.adoc index 428023e08b..90cf5b4c41 100644 --- a/docs/Dev-Windup-Bootstrap.adoc +++ b/docs/Dev-Windup-Bootstrap.adoc @@ -1,6 +1,7 @@ +[[Dev-Windup-Bootstrap]] === Windup Bootstrap -DRAFT +.DRAFT This section describes how Windup starts up, finds the resources, loads the rules, and executes them. diff --git a/docs/Dev-Windup-Documentation-Process.adoc b/docs/Dev-Windup-Documentation-Process.adoc new file mode 100644 index 0000000000..f292b97cd7 --- /dev/null +++ b/docs/Dev-Windup-Documentation-Process.adoc @@ -0,0 +1,75 @@ +[[Dev-Windup-Documentation-Process]] +=== Windup Documentation Process + +==== Wiki Documentation + +* Name wiki pages using only letters, numbers and dashes. Do not include spaces, colons, or other special characters in page names. +* Use AsciiDoc rather than Markdown for the syntax. + +==== Product Documentation + +Windup product documentation is stored here: https://github.com/windup/windup-documentation + +See the https://github.com/windup/windup-documentation/blob/master/CONTRIBUTING.adoc[CONTRIBUTING guide] for AsciiDoc syntax rules regarding headers and links to make this process easier. + +The https://github.com/windup/windup-documentation/tree/master/scripts/windupDocUpdate.sh script copies the pages from the Windup wiki to the windup-documentation repository, makes minor modifications, and generates each guide in a single HTML page book format. The resulting guides are created in the `html/` directory. + +==== Publish the HTML docs to online docs (at GitHub IO) + +* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. ++ +---- +git clone https://github.com/windup/windup.git +git fetch upstream +---- + +* The first time, you must fork and clone the windup-documentation GitHub repository. After that, just fetch the latest upstream. ++ +---- +git clone https://github.com/windup/windup-documentation.git +git fetch upstream +---- + +* Navigate to the local windup directory. ++ +---- +cd windup +---- + +* Checkout the gh-pages from the windup repository ++ +---- +git checkout -b gh-pages windup +---- + +* If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory. ++ +---- +mkdir -p docs/2.0.0.Beta6/html (if it doesn't exist!) +---- + +* Copy any new images, stylesheets, and html files from windup-documentation: ++ +---- +cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.Beta6/html +---- + +* Add the updated files to GitHub. ++ +---- +git add docs +---- + +* Commit the changes. ++ +---- +git commit -m "Update message..." +---- + +* Push the changes to GitHub. ++ +---- +git push upstream gh-pages +---- + +* View the documentation at http://windup.github.io/windup/docs/2.0.0.Beta6/html/WindupUserGuide.html diff --git a/docs/Dev-Windup-Project-Information.adoc b/docs/Dev-Windup-Project-Information.adoc index 8f0f6f672a..1bc305d064 100644 --- a/docs/Dev-Windup-Project-Information.adoc +++ b/docs/Dev-Windup-Project-Information.adoc @@ -1,3 +1,4 @@ +[[Dev-Windup-Project-Information]] === Windup Project Information ==== Github Repository diff --git a/docs/Dev-Windup-Project-Structure.adoc b/docs/Dev-Windup-Project-Structure.adoc index 87e1e30c68..909ff28116 100644 --- a/docs/Dev-Windup-Project-Structure.adoc +++ b/docs/Dev-Windup-Project-Structure.adoc @@ -1,4 +1,5 @@ -= Windup Project Structure +[[Dev-Windup-Project-Structure]] +=== Windup Project Structure The Windup 2.0 project consists of the following subprojects. diff --git a/docs/Execute-Windup.adoc b/docs/Execute-Windup.adoc index 0783f7694f..3dd575c0ce 100644 --- a/docs/Execute-Windup.adoc +++ b/docs/Execute-Windup.adoc @@ -19,6 +19,8 @@ Before you begin, you must gather the following information. ==== Start Windup +For information about the use of WINDUP_HOME in the instructions below, see xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable]. + . Open a terminal and navigate to the `WINDUP_HOME/bin` directory . Type the following command to start Windup: @@ -105,7 +107,7 @@ To see the list of available parameters for the `windup-migrate-app` command, ex [[windup-command-examples]] ==== Windup Command Examples -The following Windup command examples report against applications located in the https://github.com/windup/windup/tree/master/test-files[Windup source test-files] directory. +The following Windup command examples report against applications located in the Windup source https://github.com/windup/windup/tree/master/test-files[test-files] directory. ===== Source Code Example diff --git a/docs/Features-of-Windup-2.0.adoc b/docs/Features-of-Windup-2.0.adoc index 8373e0fc20..cb50b61afa 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 **ocpsoft rewrite** and provide greater flexibility and power creating when rules. +* Java-based rule addons 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 ebc4f7e82b..67683fcb4f 100644 --- a/docs/Get-Involved.adoc +++ b/docs/Get-Involved.adoc @@ -19,5 +19,13 @@ To help us make Windup cover most application constructs and server configuratio Any level of involvement is greatly appreciated! - - +==== Basic links + +* Windup Wiki: https://github.com/windup/windup/wiki +* Windup documentation (generated from above wiki): http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html +* Windup Forums: https://community.jboss.org/en/windup +* Windup Issue Tracker: https://issues.jboss.org/browse/WINDUP +* Windup Users Mailing List: windup-users@lists.jboss.org +* 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] diff --git a/docs/Rules-Create-Java-Queries.adoc b/docs/Rules-Create-Java-Queries.adoc index e281938e33..880dab11ac 100644 --- a/docs/Rules-Create-Java-Queries.adoc +++ b/docs/Rules-Create-Java-Queries.adoc @@ -1,3 +1,4 @@ +[[Rules-Create-Java-Queries]] === Create Java Queries diff --git a/docs/Rules-Create-an-Advanced-Ruleset.adoc b/docs/Rules-Create-an-Advanced-Ruleset.adoc index 3e3a52f0dc..052697794c 100644 --- a/docs/Rules-Create-an-Advanced-Ruleset.adoc +++ b/docs/Rules-Create-an-Advanced-Ruleset.adoc @@ -1,7 +1,7 @@ [[Rules-Create-an-Advanced-Ruleset]] === Create an Advanced Ruleset -DRAFT +.DRAFT 1. Create the Forge add-on diff --git a/docs/Rules-Development-Guide.asciidoc b/docs/Rules-Development-Guide.asciidoc index 4c3b8301e5..044728f161 100644 --- a/docs/Rules-Development-Guide.asciidoc +++ b/docs/Rules-Development-Guide.asciidoc @@ -1,9 +1,10 @@ -= Rules Development Guide +[[Rules-Development-Guide]] +=== Rules Development Guide This guide is for engineers, consultants, or others who plan to create rules for Windup 2.0. -== Overview +==== Overview * link:What-is-Windup[What is Windup?] * link:Features-of-Windup-2.0[Features of Windup 2.0] @@ -11,55 +12,55 @@ rules for Windup 2.0. * link:Report-Issues-with-Windup[Report Issues with Windup] * link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] -== Get Started +==== Get Started * link:Install-Windup[Install Windup] * link:Execute-Windup[Execute Windup] * link:Review-the-Report[Review the Report] -== Configure Your System for Java-based Rules +==== Configure Your System for Java-based Rules If you plan to create Java-based rule addons, you must also do the following. * link:Install-and-Configure-Maven[Install and Configure Maven] * link:http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons. -== Understand the Rule Processing +==== Understand the Rule Processing * link:Windup-Processing-Overview[Windup Processing Overview] * link:Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle] * link:Rules-Rule-Story-Points[Rule Story Points] -== Create and Test Java Rule Addons +==== Create and Test Java Rule Addons * link:Rules-Java-based-Rule-Structure[Java-based Rule Structure] * link:Rules-Basic-Rule-Execution-Flow-Patterns[Basic Rule Execution Flow Patterns] * link:Rules-Create-a-Basic-Java-based-Rule-Add-on[Create a Basic Java-based Rule Add-on] * link:Rules-Create-an-Advanced-Ruleset[Create an Advanced Ruleset] -== Create and Test XML Rules +==== Create and Test XML Rules * link:Rules-Create-a-Basic-XML-Rule[Create a Basic XML Rule] -== Review the Report +==== Review the Report * link:Review-the-Report[Review the Report] -== External Rule Examples +==== External Rule Examples * link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] -== Debugging and Troubleshooting +==== Debugging and Troubleshooting * link:Dev-Debugging-and-Profiling[Debugging and Profiling] * link:Dev-Troubleshoot-Windup-Issues[Troubleshoot Windup Issues] -== Additional Help +==== Additional Help * link:Report-Issues-with-Windup[Report Issues with Windup] * link:Glossary[Glossary of Terms] -== Appendix +==== Appendix * link:Dev-Windup-Architectural-Components[Windup Architectural Components] diff --git a/docs/Rules-Java-based-Rule-Structure.adoc b/docs/Rules-Java-based-Rule-Structure.adoc index 1a40877349..62a577d262 100644 --- a/docs/Rules-Java-based-Rule-Structure.adoc +++ b/docs/Rules-Java-based-Rule-Structure.adoc @@ -59,6 +59,11 @@ and some others, all of which are optional. ===== when() +[source,java] +---- +.when(Query.fromType(XmlMetaFacetModel.class)) +---- + In the `.when()` part, the rule typically queries the graph, using the `Query` API. Results of the query are put on variables stack (`Variables`), many times indirectly through the querying API. @@ -73,7 +78,20 @@ http://gremlindocs.com/[Gremlin docs] for reference manual. ===== perform() -In the `.perform()` part, the rule typically scans the items of interest +[source,java] +---- +.perform( + new AbstractIterationOperation(XmlMetaFacetModel.class, "xml") + { + public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model) + { + // for each model, do something + } + } +) +---- + +In the `.perform()` part, the rule typically iterates over the items of interest (Java files, XML files, querying services, ...), processes them, and writes the findings into the graph. @@ -116,6 +134,24 @@ Windup rules inherit the rule constructs from OCP Rewrite. For example, conditions in `.when()` return false (e.g. they do not match anything). For more information, see http://ocpsoft.org/rewrite/[OCP Rewrite web]. + +[source,java] +---- +.otherwise( + new AbstractIterationOperation(XmlMetaFacetModel.class, "xml") + { + public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model) + { + // for each model, do something altenate + } + } +) +---- + +===== Where + +TODO + ===== Metadata Rules can specify metadata. Currently, the only appearing in some rules, diff --git a/docs/Rules-Ops-Reporting-Hint.adoc b/docs/Rules-Ops-Reporting-Hint.adoc index f365567454..76a81d109c 100644 --- a/docs/Rules-Ops-Reporting-Hint.adoc +++ b/docs/Rules-Ops-Reporting-Hint.adoc @@ -1 +1,6 @@ -DRAFT: TBD \ No newline at end of file +[[Rules-Ops-Reporting-Hint]] +Rules Ops Reporting Hint + +.DRAFT + +TBD \ No newline at end of file diff --git a/docs/Rules-Rule-Story-Points.adoc b/docs/Rules-Rule-Story-Points.adoc index 09909eddf8..df8d8ce069 100644 --- a/docs/Rules-Rule-Story-Points.adoc +++ b/docs/Rules-Rule-Story-Points.adoc @@ -1,6 +1,8 @@ [[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. @@ -9,13 +11,12 @@ Story points are an abstract metric used in Scrum methodology to estimate the le TODO: TBD. -This could contain relative examples like: +Estimating story points for a rule can be tricky. The following are 'rules of thumb' or suggestions to use when estimating the level of effort required for a rule. -* Pure copy'n'paste - when we know for sure it will need no migration: 0 -* When we don't know if it will need a migration: Could depend on number of unknown imports, size +* The level of effort required for "Lift and Shift", which basically means the code or file is standards-based and can be ported to the new environment with no changes, would be '0' story points. +* Changing a parameter name or value of units might be '2' story points. +This could contain relative examples like: +* Porting a web page (or similar concept) from one web framework to another depends on the complexity and the number of components. You could estimate '20' story points per component. +* Porting MyBatis to JPA: '20' story points per query. +* When you don't know if it will need a migration: Could depend on number of unknown imports, size of the file, ... -* Changing parameter name, or value units: 2. -* Porting one web page (or similar concept) from one web framework to -the other: Could depend on complexity, e.g. number of components. E.g. -20 per component. -* Porting MyBatis to JPA: 20 per query. \ No newline at end of file diff --git a/docs/Rules-Rules-Metadata.adoc b/docs/Rules-Rules-Metadata.adoc index 9c6281ca42..e39006a93a 100644 --- a/docs/Rules-Rules-Metadata.adoc +++ b/docs/Rules-Rules-Metadata.adoc @@ -1,6 +1,7 @@ +[[Rules-Rules-Metadata]] === Rules Metadata -Draft +.Draft ==== Overview Rules metadata are used for ordering, filtering, debugging and performance reasons. diff --git a/docs/Rules-Rules-Operations.adoc b/docs/Rules-Rules-Operations.adoc index 1747198859..0c7906cbd2 100644 --- a/docs/Rules-Rules-Operations.adoc +++ b/docs/Rules-Rules-Operations.adoc @@ -1,4 +1,6 @@ +[[Rules-Rules-Operations]] === Rules Operations + _A list of high-level operations across rulesets._ * `JavaClass` diff --git a/docs/Ruleset-Java-Basic-Ruleset.adoc b/docs/Ruleset-Java-Basic-Ruleset.adoc index 272cf6035e..36d8668fb5 100644 --- a/docs/Ruleset-Java-Basic-Ruleset.adoc +++ b/docs/Ruleset-Java-Basic-Ruleset.adoc @@ -1,6 +1,6 @@ === Java Basic Ruleset -DRAFT: +.DRAFT _This is an example page. Content serves for design decision._ diff --git a/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc b/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc index e5ad4134b9..e3b2837b6c 100644 --- a/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc +++ b/docs/Ruleset-Java-Classifications-and-Inline-Hints.adoc @@ -1,6 +1,6 @@ === Ruleset Java Classifications and Inline Hints -DRAFT +.DRAFT Some of the most important rules are *classifications* and *inline hints*. diff --git a/docs/Ruleset-Java-EE-Apps.adoc b/docs/Ruleset-Java-EE-Apps.adoc index 48cdc6be01..f4205b1e2a 100644 --- a/docs/Ruleset-Java-EE-Apps.adoc +++ b/docs/Ruleset-Java-EE-Apps.adoc @@ -1 +1,6 @@ -DRAFT : TBD \ No newline at end of file +[[Ruleset-Java-EE-Apps]] +=== Ruleset Java EE Apps + +.DRAFT + +TBD? \ No newline at end of file diff --git a/docs/Ruleset-Java-EE-Servers.adoc b/docs/Ruleset-Java-EE-Servers.adoc index dbbcf4ecef..0ac14c3707 100644 --- a/docs/Ruleset-Java-EE-Servers.adoc +++ b/docs/Ruleset-Java-EE-Servers.adoc @@ -1 +1,3 @@ -DRAFT: TBD ? \ No newline at end of file +.DRAFT + +TBD ? \ No newline at end of file diff --git a/docs/Ruleset-Reporting.adoc b/docs/Ruleset-Reporting.adoc index f365567454..19b5129ba7 100644 --- a/docs/Ruleset-Reporting.adoc +++ b/docs/Ruleset-Reporting.adoc @@ -1 +1,6 @@ -DRAFT: TBD \ No newline at end of file +[[Ruleset-Reporting]] +=== Ruleset Reporting + +.DRAFT + +TBD? \ No newline at end of file diff --git a/docs/Ruleset-XML.adoc b/docs/Ruleset-XML.adoc index c3c6a8bae5..7d1d57b532 100644 --- a/docs/Ruleset-XML.adoc +++ b/docs/Ruleset-XML.adoc @@ -1,6 +1,6 @@ === XML Ruleset -DRAFT: +.DRAFT * XPathMatch * XsltTransformation diff --git a/docs/User-Guide.asciidoc b/docs/User-Guide.asciidoc index 4ec5d7b3bd..61530b20b7 100644 --- a/docs/User-Guide.asciidoc +++ b/docs/User-Guide.asciidoc @@ -1,9 +1,10 @@ -= Windup User Guide +[[User-Guide]] +=== Windup User Guide :toc: :toclevels: 4 -== Overview +==== Overview This guide is for engineers, consultants, and others who plan to use Windup 2.0 to migrate Java applications or other components. @@ -15,18 +16,15 @@ Windup 2.0 to migrate Java applications or other components. * link:Report-Issues-with-Windup[Report Issues with Windup] * link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] -== Run Windup +==== Run Windup * link:Install-Windup[Install Windup] * link:Execute-Windup[Execute Windup] * link:Review-the-Report[Review the Report] -== Additional Resources +==== Additional Resources * link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts] * link:Known-Issues[Known Issues] * link:Glossary[Glossary of Terms] -== Appendix - -* link:Dev-Windup-Architectural-Components[Windup Architectural Components] diff --git a/docs/What-is-Windup.adoc b/docs/What-is-Windup.adoc index 128372d70f..ecb2dfc52a 100644 --- a/docs/What-is-Windup.adoc +++ b/docs/What-is-Windup.adoc @@ -5,8 +5,9 @@ image:images/windup-logo-wiki-header.jpg[Windup Logo] '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' -JBoss Windup is a rule-based tool to simplify application migrations. Running from -a http://forge.jboss.org[Forge] environment, the tool examines EAR, WAR, and +JBoss Windup is a rule-based tool to simplify application migrations. + +Running from a http://forge.jboss.org[Forge] environment, the tool examines EAR, WAR, and JAR deployments (or a project source directory) and produces an HTML report detailing the inner workings of the Java application to simplify migration efforts. It seeks to make migrating from other containers to JBoss EAP a piece of cake. @@ -23,21 +24,21 @@ high level view into relevant technologies in use within the application, and provide a consumable report for organizations to estimate, document, and migrate enterprise applications to Java EE and JBoss EAP. -These are some of the of the areas targetted by Windup rulesets: +These are some of the of the areas targetted by current core Windup rulesets: [cols="2*", options="header"] |=== |Ruleset |Description -|Java Interrogator +|Java code |Reads compiled Java files, determines if blacklisted classes are imported, and if so, continues to profile the resource. -|JSP Interrogator +|JSP code |Reads JSP files, extracts the JSP imports and taglibs, and continues to profile the resource -|XML Interrogator +|XML configuration |Reads XML files into a DOM objects and continues to profile the resource. |=== diff --git a/docs/Windup-Core-Development-Guide.adoc b/docs/Windup-Core-Development-Guide.adoc index 0f579e4f69..5c87bda280 100644 --- a/docs/Windup-Core-Development-Guide.adoc +++ b/docs/Windup-Core-Development-Guide.adoc @@ -14,7 +14,6 @@ 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::Dev-Create-JavaDoc-for-Windup.adoc[tabsize=4] include::Report-Issues-with-Windup.adoc[tabsize=4] include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] @@ -90,6 +89,13 @@ include::Rules-Ops-Xml-XsltTrasformation.adoc[tabsize=4] include::Dev-Debugging-and-Profiling.adoc[tabsize=4] include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] +==== Wiki and Product Documentation + +include::About-the-Windup-Wiki.adoc[tabsize=4] +include::Dev-Add-Images-to-the-Windup-Wiki.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] diff --git a/docs/Windup-User-Guide.adoc b/docs/Windup-User-Guide.adoc index 9f27849f28..b8b3b6bac1 100644 --- a/docs/Windup-User-Guide.adoc +++ b/docs/Windup-User-Guide.adoc @@ -40,10 +40,6 @@ include::Known-Issues.adoc[Known Issues] include::Glossary.adoc[tabsize=4] -== Appendix - -include::Dev-Windup-Architectural-Components.adoc[tabsize=4] -include::Rules-Rule-Story-Points.adoc[tabsize=4] diff --git a/html/WindupCoreDevelopmentGuide.html b/html/WindupCoreDevelopmentGuide.html index ff62e97301..d395cad6f8 100644 --- a/html/WindupCoreDevelopmentGuide.html +++ b/html/WindupCoreDevelopmentGuide.html @@ -420,19 +420,19 @@

Windup Core Development Guide

  • What is Windup?
  • Features of Windup 2.0
  • Get Involved
    • -
  • Windup Project Information
    • -
  • Create JavaDoc for Windup
  • Report Issues with Windup
  • Developer Contributing Information
  • Understand the Windup Architecture and Structure
  • Get Started @@ -464,14 +464,16 @@

    Windup Core Development Guide

  • Core Developer topics @@ -479,17 +481,25 @@

    Windup Core Development Guide

  • Rules topics
  • Debugging and Troubleshooting
  • Additional Resources @@ -529,8 +539,10 @@

    What is Windup?

    -

    JBoss Windup is a rule-based tool to simplify application migrations. Running from -a Forge environment, the tool examines EAR, WAR, and +

    JBoss Windup is a rule-based tool to simplify application migrations.

    +
    +
    +

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

    @@ -551,7 +563,7 @@

    How Does Windup Simplify Migration? estimate, document, and migrate enterprise applications to Java EE and JBoss EAP.

    -

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

    +

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

    @@ -566,16 +578,16 @@

    How Does Windup Simplify Migration?

    - + - + - + @@ -646,7 +658,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 addons are based on OCPsoft Rewrite and provide greater flexibility and power creating when rules.

  • Rules can now be nested to handle more complex situations. This means you can nest simple statements rather than use complex XPATH or REGEX expressions. @@ -775,9 +787,38 @@

    How can you help?

    Any level of involvement is greatly appreciated!

    +
    +

    Basic links

    +
    + +
    -
    -

    Windup Project Information

    Github Repository

    @@ -855,39 +896,6 @@

    IRC meeting bot comman

    -

    Create JavaDoc for Windup

    -
    -

    Use the following procedure to create JavaDoc for Windup.

    -
    -
    -
      -
    1. -

      In Windup project root directory, type the following Maven command:

      -
      -
      -
      mvn validate -PjavadocDist
      -
      -
      -
      2. -
    2. -

      The JavaDoc is created in the Windup target/site/apidocs subdirectory.

      -
      3. -
    -
    -
    -

    • Java Interrogator

    Java code

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

    JSP Interrogator

    JSP code

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

    XML Interrogator

    XML configuration

    Reads XML files into a DOM objects and continues to profile the resource.
    - - - - -
    -
    Note
    -    		 -To cross-link with 3rd-party libraries, see https://issues.jboss.org/browse/WINDUP-422[WINDUP-422} and http://stackoverflow.com/questions/27392535/javadoc-how-to-make-it-link-the-dependencies-maven-project. -
    - - -

    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.

    @@ -993,7 +1001,7 @@

    Create a JIRA Issue

    Developer Contributing Information

    -

    Development Guidelines

    +

    Development Guidelines

    Project Source Code Format

    @@ -1050,9 +1058,14 @@
    Models
    Tests
    -

    All test names should be prefixed with 'Test'. -=== Submit Code Updates to the Windup Project

    +

    All test names should be prefixed with 'Test'.

    +
    +
    +
    +
    +
    +

    Submit Code Updates to the Windup Project

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

    @@ -1156,9 +1169,6 @@
    Tests
    -
    - -

    Understand the Windup Architecture and Structure

    @@ -1250,9 +1260,12 @@

    OCPsoft Rewrite

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

    +Ocpsoft Rewrite, see: OCPsoft Rewrite.

    +
    +
    +
    +

    Windup Project Structure

    The Windup 2.0 project consists of the following subprojects.

    @@ -1318,7 +1331,6 @@

    OCPsoft Rewrite

    -

    Get Started

    @@ -1440,7 +1452,7 @@

    Configure Maven to Build Windup

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

    === Get the Windup Source Code

    • @@ -2338,6 +2350,7 @@

    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.

    @@ -2347,27 +2360,26 @@

    How to Estimate Story Points in

    TODO: TBD.

    -

    This could contain relative examples like:

    +

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

    • -

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

      +

      The level of effort required for "Lift and Shift", which basically means the code or file is standards-based and can be ported to the new environment with no changes, would be '0' story points.

    • -

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

      +

      Changing a parameter name or value of units might be '2' story points. +This could contain relative examples like:

    • -

      Changing parameter name, or value units: 2.

      +

      Porting a web page (or similar concept) from one web framework to another depends on the complexity and the number of components. You could estimate '20' story points per component.

    • -

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

      +

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

    • -

      Porting MyBatis to JPA: 20 per query.

      +

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

    @@ -2458,6 +2470,11 @@

    Add Rule Code Structure

    when()
    +
    +
    +
    .when(Query.fromType(XmlMetaFacetModel.class))
    +
    +

    In the .when() part, the rule typically queries the graph, using the Query API. Results of the query are put on variables stack @@ -2476,8 +2493,21 @@

    when()
    perform()
    +
    +
    +
    .perform(
+   new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml")
+   {
+      public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model)
+      {
+         // for each model, do something
+      }
+   }
+)
    +
    +
    -

    In the .perform() part, the rule typically scans the items of interest +

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

    @@ -2524,6 +2554,25 @@
    otherwise
    conditions in .when() return false (e.g. they do not match anything). For more information, see OCP Rewrite web.

    +
    +
    +
    .otherwise(
+   new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml")
+   {
+      public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model)
+      {
+         // for each model, do something altenate
+      }
+   }
+)
    +
    +
    +
    + +
    +
    Where
    +
    +

    TODO

    @@ -3119,10 +3168,8 @@

    Review the Output Report

    -
    -

    DRAFT

    -
    +
    DRAFT

    1. Create the Forge add-on

      @@ -3399,11 +3446,9 @@

      Test the XML Rule

      Core Developer topics

      -

      Windup Bootstrap

      -
      -

      DRAFT

      -
      +

      Windup Bootstrap

      +
      DRAFT

      This section describes how Windup starts up, finds the resources, loads the rules, and executes them.

      @@ -3476,9 +3521,10 @@

      Frames creation

      -

      Classloading Notes

      +

      Classloading Notes

      -

      DRAFT - Page contains temporary notes, to be edited.

      +
      DRAFT
      +

      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.

      @@ -3605,7 +3651,7 @@

      What classloa

      -

      Connect to the Graph via Rexster

      +

      Connect to the Graph via Rexster

      There is a specific addon for running Rexster along your graph with groupId org.jboss.windup.rexster and artifactId Rexster.

      @@ -3643,13 +3689,11 @@

      Run Rexster within Windup

      -

      Decompiling

      -
      -

      DRAFT:

      -
      +

      Decompiling

      The Decompiler API

      +
      DRAFT

      • The 3 main use cases for the decompiler API are to process:

        @@ -3731,7 +3775,8 @@
        ITypeLoader

        Dependencies (Forge add-ons)

        -

        DRAFT Based on +

        DRAFT
        +

        Based on this discussion.

        @@ -3880,7 +3925,7 @@

        Dependencies bet

      -

      Frames Extensions

      +

      Frames Extensions

      Windup has several Frames extensions to satisfy its needs.

      @@ -3932,10 +3977,12 @@

      List handler.

      List

      WindupVertexListModel offers a generic model for lists of other -models, which are stored as adjacent vertices. -=== Internal API Features

      +models, which are stored as adjacent vertices.

      +
      +
      +

      Internal API Features

      Find the RuleProvider that provided a Rule

      @@ -3971,14 +4018,16 @@

      Performance measurement

      -

      The results goes to stats/detailed_stats.csv. -=== Logging

      +

      The results goes to stats/detailed_stats.csv.

      +
      +
      +
      +

      Logging

      DRAFT

      This page describes how to log from the Java-based rules.

      -

      Textual logging

      @@ -4008,7 +4057,7 @@

      Displaying Progress

      -

      Variables Stack

      +

      Variables Stack

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

      @@ -4053,7 +4102,7 @@

      Accessing variables as a f

      -

      Port WindRide Functionality to Windup

      +

      Port WindRide Functionality to Windup

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

      @@ -4297,13 +4346,13 @@

      Modify Graph Data

      FooModel foo = new GraphService<>(graphContext, FooModel.class).getUniqueByProperty("size", 1);
      -
      -

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

      -
    -

    Concepts & Philosophy

    +

    Concepts & Philosophy

    +
    +

    TODO - 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 based on the needs, constructs, and custom APIs used in their @@ -4484,9 +4533,7 @@

    Community rulesets
    === Java Basic Ruleset

    -

    DRAFT:

    -
    -
    +
    DRAFT

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

    @@ -4647,9 +4694,7 @@

    Reports

    Ruleset Java Classifications and Inline Hints

    -

    DRAFT

    -
    -
    +
    DRAFT

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

    @@ -4688,16 +4733,30 @@

    Inline Hints

    Adding inline hints for Java and XML are as simple as adding Regular -Expressions or XPath Expressions to the Windup rules. -DRAFT : TBD -DRAFT: TBD ? -DRAFT: TBD -=== XML Ruleset

    +Expressions or XPath Expressions to the Windup rules.

    +
    +
    +
    +

    Ruleset Java EE Apps

    -

    DRAFT:

    +
    DRAFT
    +

    TBD? +.DRAFT

    +
    +
    +

    TBD ?

    +
    +
    +
    +

    Ruleset Reporting

    +
    +
    DRAFT
    +

    TBD? +=== XML Ruleset

    +
    DRAFT

    • XPathMatch

      @@ -4710,7 +4769,6 @@

      Inline Hints

      A core ruleset to provide support for XML files.

      -

    Metadata

    @@ -4859,10 +4917,12 @@

    Reporting Models

    Custom Models (coming from Addons)

    -

    See respective ruleset’s documentation. -=== Create Java Queries

    +

    See respective ruleset’s documentation.

    +
    +
    +

    Create Java Queries

    Query for all frames of some Model

    @@ -4916,13 +4976,11 @@

    Custom query

    -

    Rules Metadata

    -
    -

    Draft

    -
    +

    Rules Metadata

    Overview

    +
    Draft

    Rules metadata are used for ordering, filtering, debugging and performance reasons.

    @@ -5029,9 +5087,14 @@

    Ruleset metadata

    (see javadoc).

    -

    Currently, it only defines Ruleset ID. -=== Rules Operations -A list of high-level operations across rulesets.

    +

    Currently, it only defines Ruleset ID.

    +
    +
    +
    +
    +

    Rules Operations

    +
    +

    A list of high-level operations across rulesets.

      @@ -5059,8 +5122,14 @@

      Ruleset metadata

      For the implementation of the operation, see here. -TBD -DRAFT: TBD +TBD

      +
      +
      +

      Rules Ops Reporting Hint

      +
      +
      +
      DRAFT
      +

      TBD === Ops Reporting TypeReference

      @@ -5074,7 +5143,6 @@

      Ruleset metadata

    -

    Debugging and Troubleshooting

    @@ -5216,6 +5284,343 @@

    Classloading Problems

    See Dependencies for some hints.

    +
    +

    Wiki and Product Documentation

    + +
    +
    +
    +

    About the Windup Wiki

    +
    +

    Purpose

    +
    +

    This wiki is a place to create Windup documentation in a collaborative manner, a bit wildly, and on the fly. It is intended to reflect the state of the Windup source code master branch, however pages may become obsolete as the master changes quickly.

    +
    +
    +
    +

    Areas of Interest

    +
    +

    The Wiki pages are divided into the following main areas of interest, which may often overlap. The page names use these prefixes:

    +
    +
    +
      +
    • +

      Dev-: …​: These pages are of interest to Windup core developers.

      +
      • +
    • +

      Rules- …​: These pages are of interest to rules developers.

      +
      • +
    • +

      User- …​: These pages that are of interest to Windup users.

      +
      • +
    • +

      no prefix: These pages that are also of interest to Windup users.

      +
      • +
    +
    +
    +
    +

    Markdown, AsciiDoc, or…​?

    +
    +

    This Wiki uses AsciiDoc because it is capable of handling the publishing requirements and structural elements needed to create technical books. If you would like to contribute to the documentation, feel free to use your favorite Wiki language, however, it will ultimately be converted to AsciiDoc.

    +
    +
    +
    +

    Contributor Guidelines

    +
    +

    Please see the Contributing Guidelines for details about how to name pages and use the correct AsciiDoc syntax to make the transition to the final documentation go more smoothly.

    +
    +
    +

    The following is a brief overview.

    +
    +
    +
      +
    • +

      Name wiki pages using only letters, numbers and dashes. Do not include spaces, colons, or other special characters in page names.

      +
      • +
    • +

      Be sure to add a level 3 page heading (===) at the top of each page. When compiled in a book, the Guide name is the top level, chapters are level 2, and the page is level 3. This is the title that appears in the table of contents for the page.

      +
      +
      +
      === Build Windup from Source
      +
      +
      +
      • +
    • +

      At the beginning of each new Wiki page, add an anchor with the exact page name, including the dashes. This generates the correct anchors that are needed when the pages are combined into a book.

      +
      +
      +
      [[Dev-Build-Windup-from-Source]]
+=== Build Windup from Source
      +
      +
      +
      • +
    • +

      Wiki generates anchors using dashes for spaces. AsciiDoctor generates a leading underscore and underscores for spaces.When referring to another section within the same page, do not use the [section-title-anchor] syntax. Instead, create an anchor and use the 'xref:' syntax to provide the link. Replace spaces in the section title with dashes.

      +
      +
      +
      Create the anchor at the top of the section using double brackets to force the generation of dashes instead of underscores.
      +
      +
      +
      +
      +
      [[windup-command-examples]]
+==== Windup Command Examples
      +
      +
      +
      +
      +
      Then use the `xref` to create the link.
      +
      +
      +
      +
      +
      See xref:windup-command-examples[Windup Command Examples] for more information.
      +
      +
      +
      • +
    +
    +
    +
    +
    +

    Add Images to the Windup Wiki

    +
    +
      +
    • +

      Fork https://github.com/windup/windup/wiki

      +
      • +
    • +

      Clone the Windup Wiki into a windup.wiki/ directory using the SSH clone URL:

      +
      +
      +
      git clone git@github.com:USER_NAME/windup.git windup.wiki
      +
      +
      +
      • +
    • +

      Navigate to the new windup.wiki/ directory.

      +
      • +
    • +

      Add the upstream repository.

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

      Check out a branch to work in.

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

      Copy the image into the windup.wiki/images directory

      +
      +
      +
      cp IMAGE_NAME.png images/
      +
      +
      +
      • +
    • +

      Add the new image to Git

      +
      +
      +
      git add images/IMAGE_NAME.png
      +
      +
      +
      • +
    • +

      Commit the change

      +
      +
      +
      git commit -m "Add new image"
      +
      +
      +
      • +
    • +

      Push the change to your Windup Wiki repository.

      +
      +
      +
      git push origin HEAD:master
      +
      +
      +
      • +
    • +

      Test the new image in a page on your own Wiki.

      +
      +
      +
      image:images/IMAGE_NAME.png[New Image]
      +
      +
      +
      +

      For example:

      +
      +
      +

      Windup Logo

      +
      +
      • +
    • +

      If it works, push the image to the upstream repository

      +
      +
      +
      git push upstream HEAD:master
      +
      +
      +
      • +
    +
    +
    +
    +

    Create Windup JavaDoc

    +
    +

    The most recent Windup JavaDoc build is located here: http://windup.github.io/windup/docs/javadoc/latest/index.html

    +
    +
    +

    If you want to build an updated version, use the following procedure to create JavaDoc for Windup.

    +
    +
    +
      +
    1. +

      In Windup project root directory, type the following Maven command:

      +
      +
      +
      mvn validate -PjavadocDist
      +
      +
      +
      2. +
    2. +

      The JavaDoc is created in the Windup target/site/apidocs subdirectory.

      +
      3. +
    +
    +
    + + + + + +
    +
    Note
    +    		 +To cross-link with 3rd-party libraries, see https://issues.jboss.org/browse/WINDUP-422[WINDUP-422} and http://stackoverflow.com/questions/27392535/javadoc-how-to-make-it-link-the-dependencies-maven-project. +
    +
    +
    +
    +

    Windup Documentation Process

    +
    +

    Wiki Documentation

    +
    +
      +
    • +

      Name wiki pages using only letters, numbers and dashes. Do not include spaces, colons, or other special characters in page names.

      +
      • +
    • +

      Use AsciiDoc rather than Markdown for the syntax.

      +
      • +
    +
    +
    +
    +

    Product Documentation

    +
    +

    Windup product documentation is stored here: https://github.com/windup/windup-documentation

    +
    +
    +

    See the CONTRIBUTING guide for AsciiDoc syntax rules regarding headers and links to make this process easier.

    +
    +
    +

    The https://github.com/windup/windup-documentation/tree/master/scripts/windupDocUpdate.sh script copies the pages from the Windup wiki to the windup-documentation repository, makes minor modifications, and generates each guide in a single HTML page book format. The resulting guides are created in the html/ directory.

    +
    +
    +
    +

    Publish the HTML docs to online docs (at GitHub IO)

    +
    +
      +
    • +

      The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream.

      +
      +
      +
      git clone https://github.com/windup/windup.git
+git fetch upstream
      +
      +
      +
      • +
    • +

      The first time, you must fork and clone the windup-documentation GitHub repository. After that, just fetch the latest upstream.

      +
      +
      +
      git clone https://github.com/windup/windup-documentation.git
+git fetch upstream
      +
      +
      +
      • +
    • +

      Navigate to the local windup directory.

      +
      +
      +
      cd windup
      +
      +
      +
      • +
    • +

      Checkout the gh-pages from the windup repository

      +
      +
      +
      git checkout -b gh-pages windup
      +
      +
      +
      • +
    • +

      If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory.

      +
      +
      +
      mkdir -p docs/2.0.0.Beta6/html (if it doesn't exist!)
      +
      +
      +
      • +
    • +

      Copy any new images, stylesheets, and html files from windup-documentation:

      +
      +
      +
      cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.Beta6/html
      +
      +
      +
      • +
    • +

      Add the updated files to GitHub.

      +
      +
      +
      git add docs
      +
      +
      +
      • +
    • +

      Commit the changes.

      +
      +
      +
      git commit -m "Update message..."
      +
      +
      +
      • +
    • +

      Push the changes to GitHub.

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

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

      +
      • +
    +
    +
    @@ -5415,7 +5820,7 @@

    Reporting Terms

    diff --git a/html/WindupRulesDevelopmentGuide.html b/html/WindupRulesDevelopmentGuide.html index 21cbfa8f9b..c6885d0d4f 100644 --- a/html/WindupRulesDevelopmentGuide.html +++ b/html/WindupRulesDevelopmentGuide.html @@ -517,8 +517,10 @@

    What is Windup?

    -

    JBoss Windup is a rule-based tool to simplify application migrations. Running from -a Forge environment, the tool examines EAR, WAR, and +

    JBoss Windup is a rule-based tool to simplify application migrations.

    +
    +
    +

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

    @@ -539,7 +541,7 @@

    How Does Windup Simplify Migration? estimate, document, and migrate enterprise applications to Java EE and JBoss EAP.

    -

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

    +

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

    @@ -554,16 +556,16 @@

    How Does Windup Simplify Migration?

    - + - + - + @@ -634,7 +636,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 addons are based on OCPsoft Rewrite and provide greater flexibility and power creating when rules.

  • Rules can now be nested to handle more complex situations. This means you can nest simple statements rather than use complex XPATH or REGEX expressions. @@ -815,6 +817,37 @@

    How can you help?

    Any level of involvement is greatly appreciated!

    +
    +

    Basic links

    +
    + +
    +

    Report Issues with Windup

    @@ -987,6 +1020,9 @@

    Prerequisites

    Start Windup

    +
    +

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

    +
    1. @@ -1113,7 +1149,7 @@

      Windup Help

      Windup Command Examples

      -

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

      +

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

      Source Code Example
      @@ -1667,6 +1703,7 @@

      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.

      @@ -1676,27 +1713,26 @@

      How to Estimate Story Points in

      TODO: TBD.

      -

      This could contain relative examples like:

      +

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

      • -

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

        +

        The level of effort required for "Lift and Shift", which basically means the code or file is standards-based and can be ported to the new environment with no changes, would be '0' story points.

      • -

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

        +

        Changing a parameter name or value of units might be '2' story points. +This could contain relative examples like:

      • -

        Changing parameter name, or value units: 2.

        +

        Porting a web page (or similar concept) from one web framework to another depends on the complexity and the number of components. You could estimate '20' story points per component.

      • -

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

        +

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

      • -

        Porting MyBatis to JPA: 20 per query.

        +

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

      @@ -1787,6 +1823,11 @@

      Add Rule Code Structure

      when()
      +
      +
      +
      .when(Query.fromType(XmlMetaFacetModel.class))
      +
      +

      In the .when() part, the rule typically queries the graph, using the Query API. Results of the query are put on variables stack @@ -1805,8 +1846,21 @@

      when()
      perform()
      +
      +
      +
      .perform(
+   new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml")
+   {
+      public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model)
+      {
+         // for each model, do something
+      }
+   }
+)
      +
      +
      -

      In the .perform() part, the rule typically scans the items of interest +

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

      @@ -1853,6 +1907,25 @@
      otherwise
      conditions in .when() return false (e.g. they do not match anything). For more information, see OCP Rewrite web.

      +
      +
      +
      .otherwise(
+   new AbstractIterationOperation<XmlMetaFacetModel>(XmlMetaFacetModel.class, "xml")
+   {
+      public void perform(GraphRewrite event, EvaluationContext context, XmlMetaFacetModel model)
+      {
+         // for each model, do something altenate
+      }
+   }
+)
      +
      +
      +
      +
    +
    +
    Where
    +
    +

    TODO

    @@ -2448,10 +2521,8 @@

    Review the Output Report

    • -
    -

    DRAFT

    -
    +
    DRAFT

    1. Create the Forge add-on

      @@ -3552,7 +3623,8 @@

      OCPsoft Rewrite

      Dependencies (Forge add-ons)

      -

      DRAFT Based on +

      DRAFT
      +

      Based on this discussion.

      @@ -3748,7 +3820,7 @@

      Custom Models (coming from Addons) diff --git a/html/WindupUserGuide.html b/html/WindupUserGuide.html index 092d3362b8..8a5611b864 100644 --- a/html/WindupUserGuide.html +++ b/html/WindupUserGuide.html @@ -439,12 +439,6 @@

      Windup User Guide

    2. Glossary of Terms Used in Windup
      3. -
    3. Appendix - -
    @@ -475,8 +469,10 @@

    What is Windup?

    -

    JBoss Windup is a rule-based tool to simplify application migrations. Running from -a Forge environment, the tool examines EAR, WAR, and +

    JBoss Windup is a rule-based tool to simplify application migrations.

    +
    +
    +

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

    @@ -497,7 +493,7 @@

    How Does Windup Simplify Migration? estimate, document, and migrate enterprise applications to Java EE and JBoss EAP.

    -

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

    +

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

    Java Interrogator

    Java code

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

    JSP Interrogator

    JSP code

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

    XML Interrogator

    XML configuration

    Reads XML files into a DOM objects and continues to profile the resource.
    @@ -512,16 +508,16 @@

    How Does Windup Simplify Migration?

    - + - + - + @@ -592,7 +588,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 addons are based on OCPsoft Rewrite and provide greater flexibility and power creating when rules.

  • Rules can now be nested to handle more complex situations. This means you can nest simple statements rather than use complex XPATH or REGEX expressions. @@ -773,6 +769,37 @@

    How can you help?

    Any level of involvement is greatly appreciated!

    +
    +

    Basic links

    +
    + +
    +

    Report Issues with Windup

    @@ -945,6 +972,9 @@

    Prerequisites

    Start Windup

    +
    +

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

    +
    1. @@ -1071,7 +1101,7 @@

      Windup Help

      Windup Command Examples

      -

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

      +

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

      Source Code Example
      @@ -1495,147 +1525,10 @@

      Reporting Terms

    -
    -

    Appendix

    -
    -
    -

    Windup Architectural Components

    -
    -

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

    -
    -
    -

    Forge

    -
    -

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

    -
    -
    -
    -

    Forge Furnace

    -
    -

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

    -
    -
    -
    -

    TinkerPop

    -
    -

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

    -
    -
    -
    -

    Titan

    -
    -

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

    -
    -
    -
    -

    Frames

    -
    -

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

    -
    -
    -

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

    -
    -
    -
    -

    Gremlin

    -
    -

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

    -
    -
    -
    -

    Blueprints

    -
    -

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

    -
    -
    -
    -

    Pipes

    -
    -

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

    -
    -
    -
    -

    Rexster

    -
    -

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

    -
    -
    -
    -

    OCPsoft Rewrite

    -
    -

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

    -
    -
    -
    -
    -

    Rule Story Points

    -
    -

    What are Story Points?

    -
    -

    Story points are an abstract metric used in Scrum methodology to estimate the level of effort for various tasks. They are based on a modified Fibonacci sequence. In a similar manner, Windup uses story points to express the level of effort needed to migrate particular application constructs, and in a sum, the application as a whole.

    -
    -
    -
    -

    How to Estimate Story Points in a Rule

    -
    -

    TODO: TBD.

    -
    -
    -

    This could contain relative examples like:

    -
    -
    -
      -
    • -

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

      -
      • -
    • -

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

      -
      • -
    • -

      Changing parameter name, or value units: 2.

      -
      • -
    • -

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

      -
      • -
    • -

      Porting MyBatis to JPA: 20 per query.

      -
      • -
    -
    -
    -
    -
    -
    diff --git a/scripts/windupDocPublish.sh b/scripts/windupDocPublish.sh new file mode 100755 index 0000000000..85bbf9300d --- /dev/null +++ b/scripts/windupDocPublish.sh @@ -0,0 +1,13 @@ +################################# +# Publish the Windup Guides +################################# + +# +echo "Copying the HTML files from windup-documentation/html/" +cd ~/GitRepos/windup +git fetch upstream +git checkout gh-pages +cd ../windup-documentation +cp html/*.html docs/*.css docs/images/* ../windup/docs/2.0.0.Beta6/html + + diff --git a/scripts/windupDocUpdate.sh b/scripts/windupDocUpdate.sh index 18c41e9220..fb4d3e5c2c 100755 --- a/scripts/windupDocUpdate.sh +++ b/scripts/windupDocUpdate.sh @@ -38,9 +38,6 @@ cp ../windup.wiki/Review-the-Report.asciidoc docs/Review-the-Report.adoc cp ../windup.wiki/Review-the-Windup-Quickstarts.asciidoc docs/Review-the-Windup-Quickstarts.adoc cp ../windup.wiki/Known-Issues.asciidoc docs/Known-Issues.adoc cp ../windup.wiki/Glossary.asciidoc docs/Glossary.adoc -## Appendix -cp ../windup.wiki/Dev-Windup-Architectural-Components.asciidoc docs/Dev-Windup-Architectural-Components.adoc -cp ../windup.wiki/Rules-Rule-Story-Points.asciidoc docs/Rules-Rule-Story-Points.adoc ################################# @@ -101,7 +98,6 @@ cp ../windup.wiki/What-is-Windup.asciidoc docs/What-is-Windup.adoc cp ../windup.wiki/Features-of-Windup-2.0.asciidoc docs/Features-of-Windup-2.0.adoc cp ../windup.wiki/Get-Involved.asciidoc docs/Get-Involved.adoc cp ../windup.wiki/Dev-Windup-Project-Information.asciidoc docs/Dev-Windup-Project-Information.adoc -cp '../windup.wiki/Dev-Create-JavaDoc-for-Windup.asciidoc' 'docs/Dev-Create-JavaDoc-for-Windup.adoc' cp ../windup.wiki/Report-Issues-with-Windup.asciidoc docs/Report-Issues-with-Windup.adoc cp ../windup.wiki/About-the-WINDUP_HOME-Variable.asciidoc docs/About-the-WINDUP_HOME-Variable.adoc @@ -137,6 +133,14 @@ cp ../windup.wiki/Rules-Create-a-Basic-XML-Rule.asciidoc docs/Rules-Create-a-Bas ## Debugging and Troubleshooting cp ../windup.wiki/Dev-Debugging-and-Profiling.asciidoc docs/Dev-Debugging-and-Profiling.adoc cp ../windup.wiki/Dev-Troubleshoot-Windup-Issues.asciidoc docs/Dev-Troubleshoot-Windup-Issues.adoc + +## Wiki and Product Documentation + +cp ../windup.wiki/About-the-Windup-Wiki.asciidoc docs/About-the-Windup-Wiki.adoc +cp ../windup.wiki/Dev-Add-Images-to-the-Windup-Wiki.asciidoc docs/Dev-Add-Images-to-the-Windup-Wiki.adoc +cp ../windup.wiki/Dev-Create-Windup-JavaDoc.asciidoc docs/Dev-Create-Windup-JavaDoc.adoc +cp ../windup.wiki/Dev-Windup-Documentation-Process.asciidoc docs/Dev-Windup-Documentation-Process.adoc + ## Additional Resources cp ../windup.wiki/Review-the-Windup-Quickstarts.asciidoc docs/Review-the-Windup-Quickstarts.adoc cp ../windup.wiki/Known-Issues.asciidoc docs/Known-Issues.adoc

    • Java Interrogator

    Java code

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

    JSP Interrogator

    JSP code

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

    XML Interrogator

    XML configuration

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