From af461640ffa07807c34d7f0d8d9958930f6172bc Mon Sep 17 00:00:00 2001 From: Sande Gilda Date: Tue, 17 Mar 2015 13:55:24 -0400 Subject: [PATCH] Update Rules Guide and other Windup documentation --- docs/Core-Development-Guide.asciidoc | 4 +- docs/Dev-Build-Windup-from-Source.adoc | 2 +- docs/Dev-Classloading-Notes.adoc | 16 + ...evelopment-Guidelines-and-Conventions.adoc | 57 + docs/Dev-Troubleshoot-Windup-Issues.adoc | 8 + docs/Dev-Windup-Documentation-Process.adoc | 123 +- docs/Execute-Windup.adoc | 2 +- docs/Get-Involved.adoc | 1 + docs/Install-and-Configure-Maven.adoc | 13 +- docs/Rule-Metadata.adoc | 101 + ...Create-a-Basic-Java-based-Rule-Add-on.adoc | 11 +- docs/Rules-Create-a-Basic-XML-Rule.adoc | 130 +- docs/Rules-Development-Guide.asciidoc | 7 +- docs/Rules-Rule-Execution-Lifecycle.adoc | 2 +- ...Rules-Test-a-Basic-XML-Rule-in-Windup.adoc | 43 + ...XML-Rule-Action-Classification-Syntax.adoc | 53 + docs/Rules-XML-Rule-Action-Hint-Syntax.adoc | 52 + ...ules-XML-Rule-Action-Iteration-Syntax.adoc | 48 + ...Rules-XML-Rule-Action-Lineitem-Syntax.adoc | 37 + docs/Rules-XML-Rule-Action-Link-Syntax.adoc | 47 + docs/Rules-XML-Rule-Action-XSLT-Syntax.adoc | 61 + ...XML-Rule-Condition-FileContent-Syntax.adoc | 6 + ...-XML-Rule-Condition-Java-Class-Syntax.adoc | 46 + ...les-XML-Rule-Condition-Project-Syntax.adoc | 47 + ...es-XML-Rule-Condition-XML-File-Syntax.adoc | 58 + .../Rules-XML-Rule-Perform-Action-Syntax.adoc | 301 +++ .../Rules-XML-Rule-When-Condition-Syntax.adoc | 176 ++ docs/What-is-Windup.adoc | 5 +- docs/Windup-Core-Development-Guide.adoc | 2 +- docs/Windup-Processing-Overview.adoc | 4 +- docs/Windup-Rules-Development-Guide.adoc | 17 +- html/WindupCoreDevelopmentGuide.html | 602 +++--- html/WindupRulesDevelopmentGuide.html | 1819 ++++++++++++----- html/WindupUserGuide.html | 18 +- scripts/pagelinksCoreDevelopmentGuide.sh | 2 +- scripts/pagelinksCoreDevelopmentGuide.txt | 105 - scripts/pagelinksRulesDevelopmentGuide.txt | 89 - scripts/windupDocUpdate.sh | 7 +- 38 files changed, 3001 insertions(+), 1121 deletions(-) create mode 100644 docs/Dev-Development-Guidelines-and-Conventions.adoc create mode 100644 docs/Rule-Metadata.adoc create mode 100644 docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc create mode 100644 docs/Rules-XML-Rule-Action-Classification-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Action-Hint-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Action-Iteration-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Action-Lineitem-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Action-Link-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Action-XSLT-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Condition-FileContent-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Condition-Java-Class-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Condition-Project-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Condition-XML-File-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-Perform-Action-Syntax.adoc create mode 100644 docs/Rules-XML-Rule-When-Condition-Syntax.adoc delete mode 100644 scripts/pagelinksCoreDevelopmentGuide.txt delete mode 100644 scripts/pagelinksRulesDevelopmentGuide.txt diff --git a/docs/Core-Development-Guide.asciidoc b/docs/Core-Development-Guide.asciidoc index ee21eceb81..66f327741e 100644 --- a/docs/Core-Development-Guide.asciidoc +++ b/docs/Core-Development-Guide.asciidoc @@ -11,7 +11,7 @@ or core rule add-ons to the Windup 2.0 project. * link:Get-Involved[Get Involved] - We need your feedback! * link:Dev-Windup-Project-Information[Windup Project Information] - Github repository, IRC, Mailing lists, ... -* link:Report-Issues-with-Windup[Report Issues with Windup +* link:Report-Issues-with-Windup[Report Issues with Windup] * link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] ==== Get Started @@ -24,7 +24,7 @@ repository, IRC, Mailing lists, ... ==== Developer Contributing Information -* link:Dev-Development-Guidelines[Developer Guidelines] +* link:Dev-Development-Guidelines-and-Conventions[Developer Guidelines and Conventions] * link:Dev-Submit-Code-Updates-to-the-Windup-Project[Submit Code Updates to the Windup Project] ==== Understand the Windup Architecture and Structure diff --git a/docs/Dev-Build-Windup-from-Source.adoc b/docs/Dev-Build-Windup-from-Source.adoc index 7b00ab291a..8c21b0db0f 100644 --- a/docs/Dev-Build-Windup-from-Source.adoc +++ b/docs/Dev-Build-Windup-from-Source.adoc @@ -106,7 +106,7 @@ project directory, then click `OK`. or dependency errors and click `Finish`. If you get a dialog titled _Incomplete Maven Goal Execution_, ignore it and click `OK` to continue. . In the Project Explorer tab, find the `windup_parent` project in the -list, right-mouse, and choose `Run As` --> `Maven install`. +list, right-click, and choose `Run As` --> `Maven install`. ==== Extract the Windup Distribution Source File diff --git a/docs/Dev-Classloading-Notes.adoc b/docs/Dev-Classloading-Notes.adoc index 520c8da20b..5d331c3aa1 100644 --- a/docs/Dev-Classloading-Notes.adoc +++ b/docs/Dev-Classloading-Notes.adoc @@ -12,6 +12,9 @@ This covers the specific situations when the Windup core developer needs to look [source,java] -------- AddonRegistry.getServices(MyServiceInterface.class) + +// To get the AddonRegistry, use Windup's FurnaceHolder: +FurnaceHolder.getFurnace().getAddonRegistry().getServices(MyServiceInterface.class); -------- or [source,java] @@ -27,6 +30,19 @@ If you want something from the current addon, you need to @Inject its ServiceReg Depends, if you are in a Furnace Service, then yes, it will use the current code's addon's classloader. +==== Reading annotations from classes + +Since classes can be proxied by Forge/Furnace, it's safer to read annotations using `Annotations API`: + + Rules annotation = Annotations.getAnnotation(this.getClass(), Rules.class); + +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. + + ==== How do I know if I am in a Furnace service? Every furnace service is wrapped in a proxy. If it came from another diff --git a/docs/Dev-Development-Guidelines-and-Conventions.adoc b/docs/Dev-Development-Guidelines-and-Conventions.adoc new file mode 100644 index 0000000000..fb87c5d228 --- /dev/null +++ b/docs/Dev-Development-Guidelines-and-Conventions.adoc @@ -0,0 +1,57 @@ +[[Dev-Development-Guidelines-and-Conventions]] +=== Development Guidelines and Conventions + +* xref:project-source-code-formatting[Project Source Code Formatting] +* xref:source-code-naming-conventions[Source Code Naming Conventions] +* xref:maven-project-naming-conventions[Maven Project Naming Conventions] + +[[project-source-code-formatting]] +==== 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 + +. In Eclipse, choose Windows -> Preferences. +. Expand Java -> Code Style -> Formatter +. Click Import +. Browse to the `Eclipse_Code_Format_Profile.xml` located in the root of the Windup project directory, then click 'OK'. + +===== Netbeans IDE + +Use this file to format Windup source code: + +http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java[http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java] + +===== IntelliJ IDEA + +Use this file to format Windup source code: + +http://plugins.jetbrains.com/plugin/?id=6546[http://plugins.jetbrains.com/plugin/?id=6546] + +[[source-code-naming-conventions]] +==== Source Code Naming Conventions + +===== Class Interface and Implementation Names + +* Do not name interfaces using the prefix 'I' for interface names. Instead, use a descriptive term for the interface, like `Module.java`. +* The implementation class name should begin with a descriptive name, followed by the interface name, for example, for example `JavaHandlerModule.java` + +===== 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 + +[[maven-project-naming-conventions]] +==== Maven Project Naming Conventions + +===== Maven Module Names + +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-`. + diff --git a/docs/Dev-Troubleshoot-Windup-Issues.adoc b/docs/Dev-Troubleshoot-Windup-Issues.adoc index b6adc9d375..9b59b6ba9b 100644 --- a/docs/Dev-Troubleshoot-Windup-Issues.adoc +++ b/docs/Dev-Troubleshoot-Windup-Issues.adoc @@ -19,3 +19,11 @@ See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-1 Configuring dependencies in a Forge-based project can be a little tricky. See xref:Dev-Dependencies[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 +----- + +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. \ No newline at end of file diff --git a/docs/Dev-Windup-Documentation-Process.adoc b/docs/Dev-Windup-Documentation-Process.adoc index 3c5f3951f7..2a5e9989d8 100644 --- a/docs/Dev-Windup-Documentation-Process.adoc +++ b/docs/Dev-Windup-Documentation-Process.adoc @@ -12,9 +12,70 @@ Windup product documentation is stored here: https://github.com/windup/windup-do 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. +==== Update the Windup Documentation with the Latest Wiki Changes -==== Publish the HTML docs to online docs (at GitHub IO) +===== 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. + +[cols="2*", options="header"] +|=== +|Wiki Guide +|Windup Docs Guide + +|User-Guide.asciidoc +|Windup-User-Guide.adoc + +|Rules-Development-Guide.asciidoc +|Windup-Rules-Development-Guide.adoc + +|Core-Development-Guide.asciidoc +|Windup-Core-Development-Guide.adoc + +|Migration-Planning-Guide +|Windup-Migration-Planning-Guide.adoc +|=== + +====== Documentation Update Scripts + +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 `WINDUP_DOCUMENTATION_HOME/html/` directory. + +The script performs the following steps. + +. Copies the Windup wiki pages to the `WINDUP_DOCUMENTATION_HOME/docs/` directory, renaming them with the `.adoc` extension. + +. Makes sure each guide includes all pages that are referenced by pages within it. Scripts are provided to search for links within each individual guide. They navigate to the `WINDUP_DOCUMENTATION_HOME/docs/` directory and search using the following command: + + grep 'xref:[A-Z]' `find . -name '*.adoc'`. + +. Replaces each `xref:` to external pages with an `xref:` using the following command. + + find . -name '*.adoc' -print | xargs sed -i 's/xref:/xref:/g' + +. Navigates to the `WINDUP_DOCUMENTATION_HOME/` directory and builds the books. The single page HTML files are created in the `WINDUP_DOCUMENTATION_HOME/html/` directory. + ++ +[cols="2*", options="header"] +|=== +|Windup Guide +|Command + +|Windup User Guide +|asciidoctor -t -dbook -a toc -o html/WindupUserGuide.html docs/Windup-User-Guide.adoc + +|Windup Rules Development Guide +|asciidoctor -t -dbook -a toc -o html/WindupRulesDevelopmentGuide.html docs/Windup-Rules-Development-Guide.adoc + +|Windup Core Development Guide +|asciidoctor -t -dbook -a toc -o html/WindupCoreDevelopmentGuide.html docs/Windup-Core-Development-Guide.adoc +|=== + + +==== Publish the HTML Docs for Access at GitHub IO + +The https://github.com/windup/windup-documentation/tree/master/scripts/windupPublish.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 `WINDUP_DOCUMENTATION_HOME/html/` directory. + +The script performs the following steps. * The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. + @@ -23,35 +84,32 @@ 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. +* Navigate to the local `WINDUP_HOME/` directory. + ---- cd windup ---- -* Checkout the gh-pages from the windup repository +* Checkout the `gh-pages` from the `WINDUP_HOME` repository + ---- -git checkout -b gh-pages windup +git checkout -b gh-pages windup/gh-pages ---- -* If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory. +* If the `WINDUP_HOME/docs/WINDUP_RELEASE/` directory does not yet exist, create a `docs/WINDUP_RELEASE/html/images/` + ---- -mkdir -p docs/2.0.0.VERSION/html (if it doesn't exist!) +mkdir -p docs/WINDUP_RELEASE/html/images (if it doesn't exist!) ---- -* Copy any new images, stylesheets, and html files from windup-documentation: +* Copy any the images, stylesheets, and html files from windup-documentation: + ---- -cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.VERSION/html + +cp WINDUP_DOCUMENTATION_HOME/html/*.html WINDUP_HOME/docs/WINDUP_RELEASE/html/ +cp WINDUP_DOCUMENTATION_HOME/*.css WINDUP_HOME/docs/WINDUP_RELEASE/html/ +cp WINDUP_DOCUMENTATION_HOME/images/* WINDUP_HOME/docs/WINDUP_RELEASE/html/images/ + ---- * Add the updated files to GitHub. @@ -72,4 +130,35 @@ git commit -m "Update message..." git push upstream gh-pages ---- -* View the documentation at http://windup.github.io/windup/docs/2.0.0.VERSION/html/WindupUserGuide.html +* 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 diff --git a/docs/Execute-Windup.adoc b/docs/Execute-Windup.adoc index 886d481ccb..03244c5ada 100644 --- a/docs/Execute-Windup.adoc +++ b/docs/Execute-Windup.adoc @@ -75,7 +75,7 @@ Where: + *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, your 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! +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. diff --git a/docs/Get-Involved.adoc b/docs/Get-Involved.adoc index e6bb1eb3ee..224e32ba6b 100644 --- a/docs/Get-Involved.adoc +++ b/docs/Get-Involved.adoc @@ -31,6 +31,7 @@ Any level of involvement is greatly appreciated! ** http://windup.github.io/windup/docs/latest/html/WindupRulesDevelopmentGuide.html ** http://windup.github.io/windup/docs/latest/html/WindupCoreDevelopmentGuide.html * Windup Forums: https://community.jboss.org/en/windup +* Windup Forums: https://developer.jboss.org/en/windup (inherited from Windup 0.x) * 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 diff --git a/docs/Install-and-Configure-Maven.adoc b/docs/Install-and-Configure-Maven.adoc index 28fb980c8d..7aba5b01d6 100644 --- a/docs/Install-and-Configure-Maven.adoc +++ b/docs/Install-and-Configure-Maven.adoc @@ -1,11 +1,13 @@ [[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. + ==== Download and Install Maven If you plan to use Eclipse Luna (4.4) to build Windup, you can skip this -step. This version of Eclipse embeds Maven 3.2.1 so you do not need to -install it separately. Skip to the section entitled xref:configure-maven-to-build-windup[Configure Maven to Build Windup]. +step and go directly to the section entitled xref:configure-maven-to-build-windup[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 @@ -80,5 +82,8 @@ ending `` element. element to make the profile active. + ---------------------------------------------------------- - jboss-nexus-repository ----------------------------------------------------------- \ No newline at end of file +jboss-nexus-repository +---------------------------------------------------------- + +You are now configured to build Windup. + \ No newline at end of file diff --git a/docs/Rule-Metadata.adoc b/docs/Rule-Metadata.adoc new file mode 100644 index 0000000000..5ddfe77646 --- /dev/null +++ b/docs/Rule-Metadata.adoc @@ -0,0 +1,101 @@ +=== Rules Metadata + +.Draft + +==== Overview +Rules metadata are used for ordering, filtering, debugging and performance reasons. + +==== Metadata used by Windup + +NOTE: The ruleset metadata will be set using annotations in the future. +[source,java] +--------------- +@Rules(id="", after=[...], ...) +--------------- + + +To control *ordering*, override `getExecuteAfter()` and `getExecuteBefore()`. + +[source,java] +-------- +public class MyRules extends WindupRuleProvider +{ + public List> getExecuteAfter() { + return asClassList(UpdateVictimsDbRules.class, ComputeArchivesSHA512.class); + } +-------- + +NOTE: The order is set for whole `RuleProvider`. There's no way to set it for individual rules. + + +To specify the *rule ID*, use `.withId("...")`. + +[source,java] +-------- + .addRule() + .perform(...) + .withId("CheckArchivesWithVictims") +-------- + + +For *other metadata*, either use `.withMetadata()` or override `enhanceMetadata()`. +To provide categorization for filtering, use `CATEGORY`. + +For its metadata, Windup uses the keys defined in `RuleMetadata`: + +* http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html#CATEGORY[CATEGORY] (String): Define which category the rule belongs to, which can be then used to filter the rules to execute (plus all those they depend on). Not implemented yet. + +* http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html#ORIGIN[ORIGIN] (String): The rule origin. Typically a class name. + +* http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html#[AUTO_COMMIT] (boolean): Whether to call database `commit()` after the rule executes. + +* http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html#TREAT_EXCEPTIONS_AS_FATAL[TREAT_EXCEPTIONS_AS_FATAL] (boolean): Whether all Exceptions from this Rule are to be treated as fatal. The default is non-fatal. + +* http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html#RULE_PROVIDER[RULE_PROVIDER]: The `WindupRuleProvider` that originated the rule. This is used internally, not to be specified by rule author. + +You can find out more information about rule metadata here: http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/metadata/RuleMetadata.html[RuleMetadata] Javadoc. + + +==== How to define rule metadata + +The `RuleMetadata` is defined using the `.withMetadata(Object key, Object value)`. + +[source,java] +-------- + .addRule() + .when(...) + .perform(...) + .withId("CheckArchivesWithVictims") + .withMetadata(RuleMetadata.CATEGORY, ...) +-------- + +In case you want to apply the same metadata to all rules in some `RuleProvider`, override it's `enhanceMetadata()` method. The default implementations sets `CATEGORY` to "Uncategorized", `ORIGIN` to it's class'es name, and `RULE_PROVIDER` to the `RuleProvider` object: + +[source,java] +-------- +public class MyRules extends WindupRuleProvider +{ + public void enhanceMetadata(Context context) { + if( ! context.containsKey(RuleMetadata.CATEGORY) ) + context.put(RuleMetadata.CATEGORY, "Uncategorized"); + if( ! context.containsKey(RuleMetadata.ORIGIN) ) + context.put(RuleMetadata.ORIGIN, this.getClass().getName()); + if( ! context.containsKey(RuleMetadata.RULE_PROVIDER) ) + context.put(RuleMetadata.RULE_PROVIDER, this); + } +-------- + +===== Why a Map? + +For the rules definition, Windup uses the OCPsoft Rewrite library. Whenever there is something Windup specific which can't be pulled to the upstream implementation, Windup resorts to putting data into a metadata map. + +This map is typically not used by rule authors, unless they use a custom Windup extension (don't confuse that with custom Ruleset). + + +==== Ruleset metadata + +Ruleset metadata cover the whole Ruleset, not individual rules. +For ruleset metadata, unlike rules, Windup uses a type-safe interface `WindupRulesetMetadata` +(see http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/config/WindupRulesetMetadata.html[javadoc]). + +Currently, it only defines Ruleset ID. 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 3c1200c538..250886f936 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 @@ -132,7 +132,6 @@ The following are examples of some dependencies you may need for your rule add-o forge-addon test - ---- 4. Add the `` section to make it a Forge add-on. @@ -172,7 +171,9 @@ The following are examples of some dependencies you may need for your rule add-o ===== Create the Java RuleProvider -1. Within your Maven project, create a Java class that extends the `WindupRuleProvider` class. It is suggested that you end the name of the class with `RuleProvider`. For example: +. 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. + +. Within your Maven project, create a Java class that extends the `WindupRuleProvider` class. It is suggested that you end the name of the class with `RuleProvider`. For example: + [source,xml] ---- @@ -181,7 +182,7 @@ public class MyCustomRuleProvider extends WindupRuleProvider } ---- -2. If the rule provider must run in a phase other than the default `MIGRATION_RULES` phase, override the phase using the `getPhase()` method. For example, you may want the rule provider to perform a task during the initial *DISCOVERY* phase, for example, to ignore files with a specific name or extension. +. If the rule provider must run in a phase other than the default `MIGRATION_RULES` phase, override the phase using the `getPhase()` method. For example, you may want the rule provider to perform a task during the initial *DISCOVERY* phase, for example, to ignore files with a specific name or extension. + [source,java] ---- @@ -192,7 +193,7 @@ public class MyCustomRuleProvider extends WindupRuleProvider ---- For more information about rule phases, see xref:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecycles]. -3. To control the order in which the rule is executed, implement the `getExecuteBefore()` or `getExecuteAfter()` method. +. To control the order in which the rule is executed, implement the `getExecuteBefore()` or `getExecuteAfter()` method. + [source,java] ---- @@ -216,7 +217,7 @@ public List> getExecuteAfter() } ---- -4. Finally, add the rule or rules to the rule provider. +. Finally, add the rule or rules to the rule provider. * High-level Conditions and Operations + diff --git a/docs/Rules-Create-a-Basic-XML-Rule.adoc b/docs/Rules-Create-a-Basic-XML-Rule.adoc index f0aaf0c13a..6b56f2456b 100644 --- a/docs/Rules-Create-a-Basic-XML-Rule.adoc +++ b/docs/Rules-Create-a-Basic-XML-Rule.adoc @@ -1,4 +1,4 @@ -[[Rules-Create-a-Basic-XML-Rule]] +[[Rules-Create-am-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. @@ -9,111 +9,49 @@ You can create a rule addon using Java or a rule using XML or Groovy. This topic * Before you begin, you may also want to be familiar with the following documentation: ** Windup rules are based on the ocpsoft *rewrite* project. You can find more information about ocpsoft *rewrite* here: http://ocpsoft.org/rewrite/ ** The JavaDoc for the Windup API is located here: http://windup.github.io/windup/docs/javadoc/latest/ +** The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. -NOTE: Working examples of XML-based rules can be found in the Windup quickstarts GitHub repository located here: https://github.com/windup/windup-quickstarts +==== File Naming Convention for XML Rules -==== Create a Rule +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! -The following is an example of an XML rule. +==== Basic XML Rule Template - - - - - DISCOVERY - - - - - - METHOD_PARAMETER - - - - - Message from XML Rule - - - - - - - - - - - - - - - - - Container Auth - - - - - - - - - - - -===== Create the XML Rule - -**Note:** Windup only analyzes XML files with names ending in `.windup.xml`. Be sure to name XML-based rules using this naming convention! - -The XML rule consists of the following level elements: +XML rules consist of _conditions_ and _actions_ and follow the familiar "if/then/else" construct: -* ****: This element defines this as a Windup rule. -* ****: This element specifies when the ruleset should execute. See xref:Rules-Rule-Execution-Lifecycle[Rule Execution Lifecyle] for more information about rule phases. -* ****: element contains the individual rules. -** ****: This element is a child of the **rules** element. One or more rules can be defined for a ruleset. Each `rule` contains the following elements. -*** ****: This element defines the condition to match on. -**** **** -***** ****: The location where the reference was found in a Java source file. See the http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/rules/apps/java/scan/ast/TypeReferenceLocation.html[Enum TypeReferenceLocation] Javadoc for valid values. -*** ****: This element is invoked when the condition is met. -**** ****: This child element of **perform** is used to create a `hint` -***** ****: -***** ****: -**** ****: This specifies how to transform the the specified XML file -**** ****: This child element of **perform** is used to log a message. It takes the attribute **message** to define the text message. -*** The **** element is invoked when the condition is not met. + when(condition) + perform(action) + otherwise + perform(action) -==== Add the Rule to Windup +The following is the basic syntax for XML rules. -A Windup rule is installed simply by copying the rule to the appropriate Windup folder. Windup scans for rules in the following locations: - - -WINDUP_HOME/rules/:: This is the Windup folder where you run the Windup executable. See xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] for details. - -${user.home}/.windup/rules/:: This folder is created by Windup the first time you execute Windup. -+ --------- -For Linux or Mac: ~/.windup/rules/ -For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" -or- "\Users\USER_NAME\.windup\rules\" --------- - -==== Test the XML Rule - -NOTE: If you have not started Windup, follow the instructions to xref:Execute-Windup[Execute Windup]. + + + + + + + + + + + + + + + + + + + -Test the XML rule against your application file by running the `windup-migrate-app` command in the Windup console prompt. +==== Create the Rule When Condition -The command uses this syntax: +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: xref:Rules-XML-Rule-When-Condition-Syntax[XML Rule - When Condition Syntax] --------- -windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N --------- +==== Create the Rule Perform Action -You should see the following result: +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: xref:Rules-XML-Rule-Perform-Action-Syntax[XML Rule - Perform Action Syntax]. --------- -***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html --------- -For more information and examples of how to run Windup, see: xref:Execute-Windup[Execute Windup] - diff --git a/docs/Rules-Development-Guide.asciidoc b/docs/Rules-Development-Guide.asciidoc index 3d782ca8b1..eeb126f121 100644 --- a/docs/Rules-Development-Guide.asciidoc +++ b/docs/Rules-Development-Guide.asciidoc @@ -4,7 +4,7 @@ This guide is for engineers, consultants, or others who plan to create rules for Windup 2.0. -==== Overview +==== General Windup Information * link:What-is-Windup[What is Windup?] * link:Features-of-Windup-2.0[Features of Windup 2.0] @@ -12,7 +12,7 @@ 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 with Windup * link:Install-Windup[Install Windup] * link:Execute-Windup[Execute Windup] @@ -30,6 +30,8 @@ If you plan to create Java-based rule addons, you must also do the following. * link:Windup-Processing-Overview[Windup Processing Overview] * link:Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle] * link:Rules-Rule-Story-Points[Rule Story Points] +* link:Rules-Difference-Between-XML-based-and-Java-based-Rules[ +Difference Between XML-based and Java-based Rules] ==== Create and Test Java Rule Addons @@ -41,6 +43,7 @@ If you plan to create Java-based rule addons, you must also do the following. ==== Create and Test XML Rules * link:Rules-Create-a-Basic-XML-Rule[Create a Basic XML Rule] +* link:Rules-Test-a-Basic-XML-Rule-in-Windup[Test an XML Rule in Windup] ==== Review the Report diff --git a/docs/Rules-Rule-Execution-Lifecycle.adoc b/docs/Rules-Rule-Execution-Lifecycle.adoc index 935f47ae3c..f2dec2e004 100644 --- a/docs/Rules-Rule-Execution-Lifecycle.adoc +++ b/docs/Rules-Rule-Execution-Lifecycle.adoc @@ -3,7 +3,7 @@ ==== Rule Lifecycle -Windup executes each rule in sequential order. The following +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. diff --git a/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc b/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc new file mode 100644 index 0000000000..01b54e7dfe --- /dev/null +++ b/docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc @@ -0,0 +1,43 @@ +[[Rules-Test-an-XML-Rule-In-Windup]] +=== Test an XML Rule in Windup + +==== Add the Rule to Windup + +A Windup rule is installed simply by copying the rule to the appropriate Windup folder. Windup scans for rules in the following locations: + +* The `WINDUP_HOME/rules/` folder. ++ +This is the folder where you run the Windup executable. See xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable] for details. + +* 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. ++ +-------- +For Linux or Mac: ~/.windup/rules/ +For Windows: "\Documents and Settings\USER_NAME\.windup\rules\" -or- "\Users\USER_NAME\.windup\rules\" +-------- + +==== Test the XML Rule + +. If you have not started Windup, follow the instructions to xref:Execute-Windup[Execute Windup]. + +. Test the XML rule against your application file by running the `windup-migrate-app` command in the Windup console prompt. ++ +The command uses this syntax: ++ +-------- +windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N +-------- ++ +You should see the following result: ++ +-------- +***SUCCESS*** Windup report created: OUTPUT_REPORT_DIRECTORY/index.html +-------- + +==== Additional Resources + +* For more information and examples of how to run Windup, see: xref:Execute-Windup[Execute Windup] +* Working examples of XML-based rules can be found on GitHub in the https://github.com/windup/windup/[Windup source code] GitHub repository and the Windup quickstarts https://github.com/windup/windup-quickstarts/[GitHub repository] or https://github.com/windup/windup-quickstarts/releases[latest release ZIP download]. + diff --git a/docs/Rules-XML-Rule-Action-Classification-Syntax.adoc b/docs/Rules-XML-Rule-Action-Classification-Syntax.adoc new file mode 100644 index 0000000000..0e5bc05096 --- /dev/null +++ b/docs/Rules-XML-Rule-Action-Classification-Syntax.adoc @@ -0,0 +1,53 @@ +[[Rules-XML-Rule-Action-Classification]] +=== XML Rule Action - 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. + +The following is an example of a rule that classifies a resource as a WebLogic EAR application deployment descriptor file. + +_Example:_ + + + + + + + + + + + + + + +==== Construct a Classification Element + +The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +===== 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:_ + + + + + + diff --git a/docs/Rules-XML-Rule-Action-Hint-Syntax.adoc b/docs/Rules-XML-Rule-Action-Hint-Syntax.adoc new file mode 100644 index 0000000000..78824ecc45 --- /dev/null +++ b/docs/Rules-XML-Rule-Action-Hint-Syntax.adoc @@ -0,0 +1,52 @@ +[[Rules-XML-Rule-Action-Hint-Syntax]] +=== XML Rule Action - Hint Syntax + +==== Summary + +The `hint` element is used to provide a hint or inline information about how to migrate a section of code. + +The following is an example of a rule that creates a hint. + +_Example:_ + + + + + METHOD + + + + + + + + + + + +NOTE: The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +==== Construct a Hint Element + +===== Hint Element: Attributes + +message="MESSAGE":: A message describing the migration hint ++ +_Example:_ + + message="" + +effort="NUMBER":: The level of effort assigned to this resource. ++ +_Example:_ + + effort="2" + +===== Hint Element: Child Elements + +xref:: Identify or classify links to informational content. See See xref:Rules-XML-Rule-Action-Link-Syntax +[XML Rule Action - Link Syntax] ++ +_Example:_ + + link href="http://java-x.blogspot.com/2009/03/invoking-web-services-through-proxy.html" description="JAX-WS Proxy Password Example"/> diff --git a/docs/Rules-XML-Rule-Action-Iteration-Syntax.adoc b/docs/Rules-XML-Rule-Action-Iteration-Syntax.adoc new file mode 100644 index 0000000000..c12ad9af2f --- /dev/null +++ b/docs/Rules-XML-Rule-Action-Iteration-Syntax.adoc @@ -0,0 +1,48 @@ +[[Rules-XML-Rule-Action-Iteration-Syntax]] +=== XML Rule Action - Iteration Syntax + +==== Summary + +The `iteration` element specifies to iterate over all options. + +The following is an example of a rule that preforms an iteration. + +_Example:_ + + + + + + + + + + + + + + + + + + + + + + +NOTE: The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +==== Construct an Iteration Element + +===== Hint Element: Attributes + +over="NUMBER":: A message describing the migration hint ++ +_Example:_ + + over="2" + + +===== Iteration Element: Child Elements + +Iteration child elements include `iteration`, `when`, `classification`, `hint`, `xslt`, `lineitem`, and `otherwise`. \ No newline at end of file diff --git a/docs/Rules-XML-Rule-Action-Lineitem-Syntax.adoc b/docs/Rules-XML-Rule-Action-Lineitem-Syntax.adoc new file mode 100644 index 0000000000..440258201b --- /dev/null +++ b/docs/Rules-XML-Rule-Action-Lineitem-Syntax.adoc @@ -0,0 +1,37 @@ +[[Rules-XML-Rule-Action-Lineitem-Syntax]] +=== XML Rule Action - Lineitem Syntax + +==== Summary + +The `lineitem` element is used to provide line item information about a hint on the project or application overview page. + +The following is an example of a rule that creates a lineitem message. + +_Example:_ + + + + + ANNOTATION + + + + + + + + + + +NOTE: The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +==== Construct a Lineitem Element + +===== Hint Element: Attributes + +message="MESSAGE":: A lineitem message ++ +_Example:_ + + message="Proprietary code found." + diff --git a/docs/Rules-XML-Rule-Action-Link-Syntax.adoc b/docs/Rules-XML-Rule-Action-Link-Syntax.adoc new file mode 100644 index 0000000000..76a5015d49 --- /dev/null +++ b/docs/Rules-XML-Rule-Action-Link-Syntax.adoc @@ -0,0 +1,47 @@ +[[Rules-XML-Rule-Action-Link-Syntax]] +=== XML Rule Action - Link Syntax + +==== Summary + +The `link` element is used in classifications or hints to identify or classify links to informational content. + +The following is an example of a rule that creates links to additional information. + +_Example:_ + + + + + + + + + + + + + + + + + +NOTE: The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +==== Construct a Link Element + +===== Link Element: Attributes + +href="URI":: The URI for the referenced link/. ++ +_Example:_ + + href="https://access.redhat.com/articles/1249423" + +description="URI_DESCRIPTION":: A description for the link. ++ +_Example:_ + + description="Migrate WebLogic Proprietary Servlet Annotations" + + + diff --git a/docs/Rules-XML-Rule-Action-XSLT-Syntax.adoc b/docs/Rules-XML-Rule-Action-XSLT-Syntax.adoc new file mode 100644 index 0000000000..54244ed813 --- /dev/null +++ b/docs/Rules-XML-Rule-Action-XSLT-Syntax.adoc @@ -0,0 +1,61 @@ +[[Rules-XML-Rule-Action-XSLT-Syntax]] +=== XML Rule Action - XSLT Syntax + +==== Summary + +The `xslt` element specifies how to transform an XML file. + +The following is an example of rule that defines an XSLT action. + +_Example:_ + + + + + + + + + + + + + +NOTE: The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +==== Construct an XSLT Element + +===== XSLT Element: Attributes + +of="STRING":: Create a new transformation for the given reference. ++ +_Example:_ + + of="testVariable_instance" + +description="String":: Sets the description of this XSLTTransformation. ++ +_Example:_ + + description="XSLT Transformed Output" + +extension="String":: Sets the extension for this XSLTTransformation. ++ +_Example:_ + + extension="-result.html" + + +template=String:: Sets the XSL template. ++ +_Example:_ + + template="simpleXSLT.xsl" + +===== XSLT Element: Child Elements + +xslt-parameter=Map :: Specify XSLTTransformation parameters as property value pairs ++ +_Example:_ + + diff --git a/docs/Rules-XML-Rule-Condition-FileContent-Syntax.adoc b/docs/Rules-XML-Rule-Condition-FileContent-Syntax.adoc new file mode 100644 index 0000000000..dc33fb13b2 --- /dev/null +++ b/docs/Rules-XML-Rule-Condition-FileContent-Syntax.adoc @@ -0,0 +1,6 @@ +[[Rules-XML-Rule-Condition-FileContent-Syntax]] +=== XML Rule Condition - FileContent Syntax + +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/Rules-XML-Rule-Condition-Java-Class-Syntax.adoc b/docs/Rules-XML-Rule-Condition-Java-Class-Syntax.adoc new file mode 100644 index 0000000000..1b1964e17e --- /dev/null +++ b/docs/Rules-XML-Rule-Condition-Java-Class-Syntax.adoc @@ -0,0 +1,46 @@ +[[Rules-XML-Rule-Condition-Java-Class-Syntax]] +=== XML Rule Condition - Java Class Syntax + +==== Summary + +Use the `javaclass` element to find imports, methods, variable declarations, annotations, class implementations, and other items related to Java classes. The following is an example of a rule that tests for a `javaclass`. + + + + + IMPORT + TYPE + + + + + + + +==== Construct a JavaClass Element + +The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +===== 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 http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/rules/apps/java/scan/ast/TypeReferenceLocation.html[TypeReferenceLocation]. + + Example: IMPORT diff --git a/docs/Rules-XML-Rule-Condition-Project-Syntax.adoc b/docs/Rules-XML-Rule-Condition-Project-Syntax.adoc new file mode 100644 index 0000000000..42e2119072 --- /dev/null +++ b/docs/Rules-XML-Rule-Condition-Project-Syntax.adoc @@ -0,0 +1,47 @@ +[[Rules-XML-Rule-Condition-Project-Syntax]] +=== XML Rule Condition - Project Syntax + +==== Summary + +Use the `project` element to find information in project files. The following is an example of a rule that tests for an `xmlfile`. + + + + + + + + + + Descriptive message + + + + +==== Construct a Project Element + +The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +===== 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 `` + +* artifactId="PROJECT_ARTIFACT_ID" +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. ??? + +* to = "???" + + + diff --git a/docs/Rules-XML-Rule-Condition-XML-File-Syntax.adoc b/docs/Rules-XML-Rule-Condition-XML-File-Syntax.adoc new file mode 100644 index 0000000000..1244611ef0 --- /dev/null +++ b/docs/Rules-XML-Rule-Condition-XML-File-Syntax.adoc @@ -0,0 +1,58 @@ +[[Rules-XML-Rule-Condition-XML-File-Syntax]] +=== XML Rule Condition - XML File Syntax + +==== Summary + +Use the `xmlfile` element to find information in XML files. The following is an example of a rule that tests for an `xmlfile`. + + + + + + + + + + Container Auth + + + + + +==== Construct an XmlFile Element + +The XML rule schema is located here: https://github.com/windup/windup/blob/master/config-xml/rule-schema.xsd. + +===== 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: diff --git a/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc b/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc new file mode 100644 index 0000000000..371c91d9f2 --- /dev/null +++ b/docs/Rules-XML-Rule-Perform-Action-Syntax.adoc @@ -0,0 +1,301 @@ +[[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. + +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. + +* xref:classification-syntax[classification Syntax] +* xref:link-syntax[link Syntax] +* xref:hint-syntax[hint Syntax] +* xref:xslt-syntax[xslt Syntax] +* xref:lineitem-syntax[lineitem Syntax] +* xref:iteration-syntax[iteration Syntax] + +[[classification-syntax]] +==== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/classification/Classification.html[Classification] class. + +The following is an example of a rule that classifies a resource as a WebLogic EAR application deployment descriptor file. + +_Example:_ + + + + + + + + + + + + + + +===== 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:_ + + + + + + +[[link-syntax]] +==== link Syntax + +===== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/Link.html[Link] class. + +The following is an example of a rule that creates links to additional information. + +_Example:_ + + + + + + + + + + + + + + + + + +===== Construct a link Element + +====== link Element: Attributes + +href="URI":: The URI for the referenced link/. ++ +_Example:_ + + href="https://access.redhat.com/articles/1249423" + +description="URI_DESCRIPTION":: A description for the link. ++ +_Example:_ + + description="Migrate WebLogic Proprietary Servlet Annotations" + +[[hint-syntax]] +==== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/reporting/config/Hint.html[Hint] class. + +The following is an example of a rule that creates a hint. + +_Example:_ + + + + + METHOD + + + + + + + + + + + +===== Construct a hint Element + +====== hint Element: Attributes + +message="MESSAGE":: A message describing the migration hint ++ +_Example:_ + + message="" + +effort="NUMBER":: The level of effort assigned to this resource. ++ +_Example:_ + + effort="2" + +====== hint Element: Child Elements + +xref:: Identify or classify links to informational content. See the section on xref:link-syntax[link Syntax] for details. + ++ +_Example:_ + + link href="http://java-x.blogspot.com/2009/03/invoking-web-services-through-proxy.html" description="JAX-WS Proxy Password Example"/> + +[[xslt-syntax]] +==== xslt Syntax + +===== Summary + +The `xslt` element specifies how to transform an XML file. For a better understanding of the `xslt` action, see the JavaDoc for the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/xml/operation/xslt/XSLTTransformation.html[XSLTTransformation] class. + +The following is an example of rule that defines an XSLT action. + +_Example:_ + + + + + + + + + + + + + +===== Construct an xslt Element + +====== xslt Element: Attributes + +of="STRING":: Create a new transformation for the given reference. ++ +_Example:_ + + of="testVariable_instance" + +description="String":: Sets the description of this XSLTTransformation. ++ +_Example:_ + + description="XSLT Transformed Output" + +extension="String":: Sets the extension for this XSLTTransformation. ++ +_Example:_ + + extension="-result.html" + + +template=String:: Sets the XSL template. ++ +_Example:_ + + template="simpleXSLT.xsl" + +====== xslt Element: Child Elements + +xslt-parameter=Map :: Specify XSLTTransformation parameters as property value pairs ++ +_Example:_ + + + +[[lineitem-syntax]] +==== lineitem Syntax + +===== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/project/operation/LineItem.html[Lineitem] class. + +The following is an example of a rule that creates a lineitem message. + +_Example:_ + + + + + ANNOTATION + + + + + + + + + + +===== Construct a lineitem Element + +====== lineitem Element: Attributes + +message="MESSAGE":: A lineitem message ++ +_Example:_ + + message="Proprietary code found." + +[[iteration-syntax]] +==== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/config/operation/Iteration.html[Iteration] class. + +The following is an example of a rule that preforms an iteration. + +_Example:_ + + + + + + + + + + + + + + + + + + + + + + +===== Construct an iteration Element + +====== iteration Element: Attributes + +over="NUMBER":: ?? ++ +_Example:_ + + over="2" + +====== iteration Element: Child Elements + +iteration child elements include a `when` condition, along with the actions `iteration`, `classification`, `hint`, `xslt`, `lineitem`, and `otherwise`. diff --git a/docs/Rules-XML-Rule-When-Condition-Syntax.adoc b/docs/Rules-XML-Rule-When-Condition-Syntax.adoc new file mode 100644 index 0000000000..7861e6ac32 --- /dev/null +++ b/docs/Rules-XML-Rule-When-Condition-Syntax.adoc @@ -0,0 +1,176 @@ +[[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. + +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. + +* xref:javaclass-syntax[javaclass Syntax] +* xref:xmlfile-syntax[xmlfile Syntax] +* xref:project-syntax[project Syntax] +* xref:filecontent-syntax[filecontent Syntax] + +[[javaclass-syntax]] +==== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/java/condition/JavaClass.html[JavaClass] class. + +The following is an example of a rule that tests for a `javaclass`. + + + + + IMPORT + TYPE + + + + + + + +===== 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 http://windup.github.io/windup/docs/javadoc/latest/org/jboss/windup/rules/apps/java/scan/ast/TypeReferenceLocation.html[TypeReferenceLocation]. + + Example: IMPORT + + +[[xmlfile-syntax]] +==== xmlfile Syntax + +===== Summary + +Use the `xmlfile` element to find information in XML files. For a better understanding of the `xmlfile` condition, see the http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/rules/apps/xml/condition/XmlFile.html[XmlFile] JavaDoc. + +The following is an example of a rule that tests for an `xmlfile`. + + + + + + + + + + Container Auth + + + + + +===== 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: + +[[project-syntax]] +==== 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 http://windup.github.io/windup/docs/latest/javadoc/org/jboss/windup/project/condition/Project.html[Project] class. + +The following is an example of a rule that tests for an `xmlfile`. + + + + + + + + + + Descriptive message + + + + +===== 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 `` + +* artifactId="PROJECT_ARTIFACT_ID" +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. ??? + +* to = "???" + + +[[filecontent-syntax]] +==== 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 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/What-is-Windup.adoc b/docs/What-is-Windup.adoc index ecb2dfc52a..2f2818a688 100644 --- a/docs/What-is-Windup.adoc +++ b/docs/What-is-Windup.adoc @@ -1,10 +1,9 @@ -[[What-is-Windup]] -=== What is Windup? - image:images/windup-logo-wiki-header.jpg[Windup Logo] '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +=== What is Windup? + 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 diff --git a/docs/Windup-Core-Development-Guide.adoc b/docs/Windup-Core-Development-Guide.adoc index 7ea4c9abfa..41de633f31 100644 --- a/docs/Windup-Core-Development-Guide.adoc +++ b/docs/Windup-Core-Development-Guide.adoc @@ -17,7 +17,7 @@ include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] == Developer Contributing Information -include::Dev-Development-Guidelines.adoc[tabsize=4] +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 diff --git a/docs/Windup-Processing-Overview.adoc b/docs/Windup-Processing-Overview.adoc index 66672e3655..43bf48b1ca 100644 --- a/docs/Windup-Processing-Overview.adoc +++ b/docs/Windup-Processing-Overview.adoc @@ -7,7 +7,9 @@ The following is a high level conceptual overview of what happens within Windup ==== Discovery Phase -Wnen you run the `windup-migrate-app` command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes. +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 xref:Rules-Rule-Execution-Lifecycle[Rule Execution Lifecycle]. For more information about the graph database components, see xref:Windup-Architectural-Components[Windup Architectural Components]. diff --git a/docs/Windup-Rules-Development-Guide.adoc b/docs/Windup-Rules-Development-Guide.adoc index ada2632d95..7d7da4e6cf 100644 --- a/docs/Windup-Rules-Development-Guide.adoc +++ b/docs/Windup-Rules-Development-Guide.adoc @@ -1,14 +1,18 @@ = Windup Rules Development Guide +:imagesdir: images +:includedir: . + :toc: :toclevels: 4 - +:numbered: == Overview This guide is for engineers, consultants, and others who plan to create custom rules for Windup 2.0. +// include::{includedir}/What-is-Windup.adoc[tabsize=4] include::What-is-Windup.adoc[tabsize=4] include::Features-of-Windup-2.0.adoc[tabsize=4] @@ -30,13 +34,6 @@ include::Execute-Windup.adoc[tabsize=4] include::Review-the-Report.adoc[tabsize=4] - -== Configure Your System for Java-based Rules - -If you plan to create Java-based rule addons, you must also do the following. - -include::Install-and-Configure-Maven.adoc[tabsize=4] - include::http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons. == Understand the Rule Processing @@ -47,6 +44,7 @@ include::Rules-Rule-Story-Points.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] @@ -55,6 +53,9 @@ 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 diff --git a/html/WindupCoreDevelopmentGuide.html b/html/WindupCoreDevelopmentGuide.html index 421aeeb44b..f01b51c018 100644 --- a/html/WindupCoreDevelopmentGuide.html +++ b/html/WindupCoreDevelopmentGuide.html @@ -417,7 +417,7 @@

Windup Core Development Guide

  • Overview
      -
    • What is Windup?
      • +
    • What is Windup?
    • Features of Windup 2.0
    • Get Involved
    • Report Issues with Windup
      • @@ -425,7 +425,7 @@

      Windup Core Development Guide

    • Developer Contributing Information
      • @@ -438,6 +438,7 @@

      Windup Core Development Guide

    • Get Started
      • Install and Configure Maven
        • +
      • Get the Windup Source Code
      • Build Windup from Source
      • Execute Windup (Built from Windup Source)
      • Execute Windup
        • @@ -460,7 +461,7 @@

        Windup Core Development Guide

      • Create and Test XML Rules
      • Core Developer topics @@ -521,12 +522,12 @@

        Overview

        This guide is for developers who plan to contribute source code updates or core rule add-ons to the Windup 2.0 project.

        -
        -

        What is Windup?

        Windup Logo

        +
        +

        What is Windup?

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

        @@ -819,6 +820,9 @@

        Helpful links

        Windup Forums: https://community.jboss.org/en/windup

      • +

        Windup Forums: https://developer.jboss.org/en/windup (inherited from Windup 0.x)

        +
        • +

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

      • @@ -1019,9 +1023,22 @@

        Create a JIRA Issue

        Developer Contributing Information

        -

        Development Guidelines

        +

        Development Guidelines and Conventions

        +
        + +
        -

        Project Source Code Format

        +

        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.

        @@ -1033,7 +1050,7 @@
        Eclipse IDE

        In Eclipse, choose Windows → Preferences.

      • -

        Expand Java → Code Style → Formatter (Ctrl+Shift+F by default)

        +

        Expand Java → Code Style → Formatter

      • Click Import

        @@ -1047,37 +1064,76 @@
        Eclipse IDE
        Netbeans IDE
        -

        Use this file to format Windup source code: http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java

        +

        Use this file to format Windup source code:

        +
        +
        +

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

        IntelliJ IDEA
        -

        Use this file to format Windup source code: http://plugins.jetbrains.com/plugin/?id=6546

        +

        Use this file to format Windup source code:

        +
        +
        +

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

        -

        Naming conventions

        +

        Source Code Naming Conventions

        -
        Suffixes and prefixes
        -
        -

        *RuleProvider

        +
        Class Interface and Implementation Names
        +
        +
          +
        • +

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

          +
          • +
        • +

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

          +
          • +
        -
        -
        Models
        -
        -

        *Model

        -
        -

        Property constants

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

          +
          • +
        -
        -
        Tests
        +
        +
        +

        Maven Project Naming Conventions

        +
        +
        Maven Module Names
        -

        All test names should be prefixed with 'Test'.

        +

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

          +
          • +
        @@ -1354,12 +1410,15 @@

        Get Started

        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.

        +

        Download and Install Maven

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

        +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 @@ -1467,18 +1526,21 @@

        Configure Maven to Build Windup

        element to make the profile active.

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

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

        +

        You are now configured to build Windup.

        +
        + +
        +

        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

        @@ -1726,7 +1788,7 @@

        Build Win

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

        +list, right-click, and choose Run As -→ Maven install.

        • @@ -1932,7 +1994,7 @@

        Run the windup-migr
        Note
        -If the OUTPUT_REPORT_DIRECTORY directory exists, your 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, 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! @@ -2273,7 +2335,10 @@

        Windup Processing Overview

        Discovery Phase

        -

        Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

        +

        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.

        @@ -2319,7 +2384,7 @@

        Rule Execution Lifecycle

        Rule Lifecycle

        -

        Windup executes each rule in sequential order. The following +

        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.

        @@ -3074,6 +3139,9 @@
        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:

          @@ -3341,7 +3409,7 @@

          Review the Output Report

          Create and Test XML 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.

          @@ -3362,217 +3430,71 @@

          Prerequisites

        3. The JavaDoc for the Windup API is located here: http://windup.github.io/windup/docs/javadoc/latest/

          4. -

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

    Create a Rule

    -
    -

    The following is an example of an XML rule.

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

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

    -
    -
    -

    The XML rule consists of the following level elements:

    -
    -
    -
      -
    • -

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

      -
    • -

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

      -
      • -
    • -

      <rules>: element contains the individual rules.

      -
      -
        -
      • -

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

        -
        -
          -
        • -

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

          -
          -
          -
          • -
        • -

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

          -
          -
            -
          • -

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

            -
            -
              -
            • -

              <message>:

              -
              • -
            • -

              <link>:

              -
              • -
            -
            -
            • -
          • -

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

            -
            • -
          • -

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

            -
            • -
          -
          -
          • -
        • -

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

          -
          • -
        -
        -
        • -
      -
      -
      • -
    +
    +

    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!

    -

    Add the Rule to Windup

    +

    Basic XML Rule Template

    -

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

    +

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

    -
    -
    -
    WINDUP_HOME/rules/
    -
    -

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

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

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

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

    Test the XML Rule

    -
    - - - - - -
    -
    Note
    -    		 -If you have not started Windup, follow the instructions to Execute Windup. -
    +
    when(condition)
+    perform(action)
+otherwise
+    perform(action)
    -
    -

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

    -

    The command uses this syntax:

    +

    The following is the basic syntax for XML rules.

    -
    +
    -
    windup-migrate-app [--sourceMode true] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
    +
    <?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>
    -
    -

    You should see the following result:

    -
    -
    -
    ***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/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

    +
    +

    Create the Rule Perform Action

    -

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

    +

    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.

    @@ -3669,7 +3591,10 @@

    Classloading Notes

    Finding classes

    -
    AddonRegistry.getServices(MyServiceInterface.class)
    +
    AddonRegistry.getServices(MyServiceInterface.class)
+
+// To get the AddonRegistry, use Windup's FurnaceHolder:
+FurnaceHolder.getFurnace().getAddonRegistry().getServices(MyServiceInterface.class);
    @@ -3695,6 +3620,28 @@

    Which cla

    +

    Reading annotations from classes

    +
    +

    Since classes can be proxied by Forge/Furnace, it’s safer to read annotations using Annotations API:

    +
    +
    +
    +
    Rules annotation = Annotations.getAnnotation(this.getClass(), Rules.class);
    +
    +
    +
    +

    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.

    +
    +
    +

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

    Every furnace service is wrapped in a proxy. If it came from another @@ -4709,7 +4656,7 @@

    Rule providers

    -

    Models

    +

    Models

    • @@ -4979,7 +4926,7 @@

      Rule providers

    -

    Models

    +

    Models

    _Subclasses of WindupVertexFrame.

    @@ -5418,6 +5365,15 @@

    Classloading Problems

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

    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.

    +

    Wiki and Product Documentation

    @@ -5668,34 +5624,128 @@

    Product Documentation

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

    +
    +
    +

    Update the Windup Documentation with the Latest Wiki Changes

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

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Wiki GuideWindup Docs Guide

    User-Guide.asciidoc

    Windup-User-Guide.adoc

    Rules-Development-Guide.asciidoc

    Windup-Rules-Development-Guide.adoc

    Core-Development-Guide.asciidoc

    Windup-Core-Development-Guide.adoc

    Migration-Planning-Guide

    Windup-Migration-Planning-Guide.adoc

    +
    +
    Documentation Update Scripts
    -

    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.

    +

    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 WINDUP_DOCUMENTATION_HOME/html/ directory.

    +
    +

    The script performs the following steps.

    -
    -

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

    -
    -
      +
      +
      1. -

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

        -
        +

        Copies the Windup wiki pages to the WINDUP_DOCUMENTATION_HOME/docs/ directory, renaming them with the .adoc extension.

        +
        2. +
      2. +

        Makes sure each guide includes all pages that are referenced by pages within it. Scripts are provided to search for links within each individual guide. They navigate to the WINDUP_DOCUMENTATION_HOME/docs/ directory and search using the following command:

        +
        -
        git clone https://github.com/windup/windup.git
-git fetch upstream
        +
        grep 'xref:[A-Z]' `find . -name '*.adoc'`.
        +
        +
        +
        3. +
      3. +

        Replaces each xref: to external pages with an xref: using the following command.

        +
        +
        +
        find . -name '*.adoc' -print | xargs sed -i 's/xref:/xref:/g'
      4. -

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

        +

        Navigates to the WINDUP_DOCUMENTATION_HOME/ directory and builds the books. The single page HTML files are created in the WINDUP_DOCUMENTATION_HOME/html/ directory.

        + ++++ + + + + + + + + + + + + + + + + + + + + +
        Windup GuideCommand

        Windup User Guide

        asciidoctor -t -dbook -a toc -o html/WindupUserGuide.html docs/Windup-User-Guide.adoc

        Windup Rules Development Guide

        asciidoctor -t -dbook -a toc -o html/WindupRulesDevelopmentGuide.html docs/Windup-Rules-Development-Guide.adoc

        Windup Core Development Guide

        asciidoctor -t -dbook -a toc -o html/WindupCoreDevelopmentGuide.html docs/Windup-Core-Development-Guide.adoc

        +
        5. +
      +
      +
    +
    +
    +
    +

    Publish the HTML Docs for Access at GitHub IO

    +
    +

    The https://github.com/windup/windup-documentation/tree/master/scripts/windupPublish.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 WINDUP_DOCUMENTATION_HOME/html/ directory.

    +
    +
    +

    The script performs the following steps.

    +
    +
    +
      +
    • +

      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-documentation.git
+
      git clone https://github.com/windup/windup.git
 git fetch upstream
    • -

      Navigate to the local windup directory.

      +

      Navigate to the local WINDUP_HOME/ directory.

      cd windup
      @@ -5703,26 +5753,28 @@

      Publish the HTML doc

    • -

      Checkout the gh-pages from the windup repository

      +

      Checkout the gh-pages from the WINDUP_HOME repository

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

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

      +

      If the WINDUP_HOME/docs/WINDUP_RELEASE/ directory does not yet exist, create a docs/WINDUP_RELEASE/html/images/

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

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

      +

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

      -
      cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.VERSION/html
      +
      cp WINDUP_DOCUMENTATION_HOME/html/*.html WINDUP_HOME/docs/WINDUP_RELEASE/html/
+cp WINDUP_DOCUMENTATION_HOME/*.css WINDUP_HOME/docs/WINDUP_RELEASE/html/
+cp WINDUP_DOCUMENTATION_HOME/images/* WINDUP_HOME/docs/WINDUP_RELEASE/html/images/
      • @@ -5751,7 +5803,69 @@

      Publish the HTML doc

  • -

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

    +

    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

      +
      • +
    +
@@ -5925,7 +6039,7 @@

Reporting Terms

diff --git a/html/WindupRulesDevelopmentGuide.html b/html/WindupRulesDevelopmentGuide.html index 0fa2bb90ae..08449777c0 100644 --- a/html/WindupRulesDevelopmentGuide.html +++ b/html/WindupRulesDevelopmentGuide.html @@ -415,76 +415,75 @@

Windup Rules Development Guide

Table of Contents
@@ -492,18 +491,18 @@

Windup Rules Development Guide

-

Overview

+

1. Overview

This guide is for engineers, consultants, and others who plan to create custom rules for Windup 2.0.

-
-

What is Windup?

-

Windup Logo

+

Windup Logo

+
+

1.1. What is Windup?

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

@@ -514,13 +513,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 @@ -560,14 +559,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

@@ -701,7 +700,7 @@

Features of Windup 2.0

-

Windup Processing Overview

+

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.

@@ -709,16 +708,19 @@

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.

-

Discovery Phase

+

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.

+
-

Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

+

For more information about the 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

+

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.

@@ -727,7 +729,7 @@

Application Migration

-

Generate Findings Based on the Rule Execution Results

+

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

@@ -753,9 +755,9 @@

Generate Finding

-

Get Involved

+

1.4. Get Involved

-

How can you help?

+

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!

@@ -822,7 +824,7 @@

How can you help?

-

Helpful links

+

1.4.2. Helpful links

-

Report Issues with Windup

+

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.

-

Create a JIRA Account

+

1.5.1. Create a JIRA Account

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

@@ -894,7 +899,7 @@

Create a JIRA Account

-

Create a JIRA Issue

+

1.5.2. Create a JIRA Issue

  1. @@ -953,7 +958,7 @@

    Create a JIRA Issue

-

About the WINDUP_HOME Variable

+

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.

@@ -971,10 +976,10 @@

About the WINDUP_HOME Variable

-

Get Started

+

2. Get Started

-

Install Windup

+

2.1. Install Windup

  1. @@ -1000,9 +1005,9 @@

    Install Windup

-

Execute Windup

+

2.2. Execute Windup

-

Prerequisites

+

2.2.1. Prerequisites

Before you begin, you must gather the following information.

@@ -1067,7 +1072,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.

@@ -1108,7 +1113,7 @@

Start Windup

-

Run the windup-migrate-app Command

+

2.2.3. Run the windup-migrate-app Command

  1. @@ -1142,7 +1147,7 @@

    Run the windup-migr
    Note

-If the OUTPUT_REPORT_DIRECTORY directory exists, your 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, 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!
@@ -1191,7 +1196,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.

@@ -1213,7 +1218,7 @@

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:

@@ -1224,7 +1229,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.

@@ -1274,9 +1279,9 @@
Windup Quickstart Examples
-

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:

@@ -1309,19 +1314,19 @@

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:

-

Report Index Page

+

Report Index Page

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

-

Report Sections

+

2.3.3. Report Sections

Application Report Page
@@ -1341,7 +1346,7 @@
Application Report Page

The following is an example of a Windup Application Report.

-

Report Summary Page

+

Report Summary Page

@@ -1404,7 +1409,7 @@
Archive Analysis Sections

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

+

Report Archive Page

@@ -1426,18 +1431,18 @@
File Analysis Pages

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

+

File Detail - Part 1

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

-

File Detail - Part 2

+

File Detail - Part 2

-

Additional Reports

+

2.3.4. Additional Reports

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

@@ -1447,7 +1452,7 @@
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

+

RuleProvider Report

@@ -1462,139 +1467,7 @@
Individual File Analysis Reports

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

-

Report Directory File List

-
- - - - - -
-

Configure Your System for Java-based Rules

-
-
-

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

-
-
-

Install and Configure Maven

-
-

Download and Install Maven

-
-

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

-
-
-

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

-
-
-
    -
  1. -

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

    -
    2. -
  2. -

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

    -
    3. -
-
-
-
-

Configure the Maven Installation in Your IDE

-
-

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

-
-
-
    -
  1. -

    From the menu, choose Window -→ Preferences.

    -
    2. -
  2. -

    Expand Maven and click on Installations.

    -
    3. -
  3. -

    Uncheck Embedded (3.0.4/1.4.0.20130531-2315)

    -
    4. -
  4. -

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

    -
    5. -
  5. -

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

    -
    6. -
-
-
-

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

-
-
-
-

Configure Maven to Build Windup

-
-

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

-
-
-
    -
  1. -

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

    -
    2. -
  2. -

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

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

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

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

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.

@@ -1603,11 +1476,12 @@

Configure Maven to Build Windup

+
-

Understand the Rule Processing

+

3. Understand the Rule Processing

-

Windup Processing Overview

+

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

@@ -1615,16 +1489,19 @@

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.

-

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.

+
-

Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

+

For more information about the 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

+

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.

@@ -1633,7 +1510,7 @@

Application Migration

-

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.

@@ -1659,11 +1536,11 @@

Generate Findi

-

Rule Execution Lifecycle

+

3.2. Rule Execution Lifecycle

-

Rule Lifecycle

+

3.2.1. Rule Lifecycle

-

Windup executes each rule in sequential order. The following +

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.

@@ -1675,7 +1552,7 @@

Rule Lifecycle

-

Rule Phases

+

3.2.2. Rule Phases

INFO: Loaded [67] org.jboss.windup.config.WindupRuleProvider [
@@ -1775,7 +1652,7 @@ 
Rule Phases
-

Execute Before and Execute After

+

3.2.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 @@ -1807,16 +1684,16 @@

Execute Before and Execute After

-

Rule Story Points

+

3.3. Rule Story Points

-

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

-

How to Estimate Story Points in a Rule

+

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

@@ -1868,17 +1745,146 @@

How to Estimate Story Points in

-

Create and Test Java Rule Addons

+

4. Create and Test Java Rule Addons

-

Java-based Rule Structure

+

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.

+
+
+

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

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

4.1.2. Configure the Maven Installation in Your IDE

+
+

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

+
+
+
    +
  1. +

    From the menu, choose Window -→ Preferences.

    +
    2. +
  2. +

    Expand Maven and click on Installations.

    +
    3. +
  3. +

    Uncheck Embedded (3.0.4/1.4.0.20130531-2315)

    +
    4. +
  4. +

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

    +
    5. +
  5. +

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

    +
    6. +
+
+
+

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

+
+
+
+

4.1.3. Configure Maven to Build Windup

+
+

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

+
+
+
    +
  1. +

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

    +
    2. +
  2. +

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

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

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

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

You are now configured 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

-

Windup Rule Provider

+

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

@@ -1930,7 +1936,7 @@

Windup Rule Provider

-

Add Rule Code Structure

+

4.2.2. Add Rule Code Structure

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

@@ -2073,7 +2079,7 @@
Metadata
-

Available utilities

+

4.2.3. Available utilities

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

@@ -2081,12 +2087,12 @@

Available utilities

-

Basic Rule Execution Flow Patterns

+

4.3. Basic Rule Execution Flow Patterns

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

-

operation(); - single operation

+

4.3.1. operation(); - single operation

When no iteration or condition is needed.

@@ -2107,7 +2113,7 @@

operation(); - single operation

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2123,7 +2129,7 @@ 
if( …​ ){ operat
-

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

+

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

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

@@ -2154,7 +2160,7 @@

for( FooModel.class ){ …R

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2169,7 +2175,7 @@ 
if( …​ ){ for( …​
-

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

+

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

return ConfigurationBuilder.begin()
@@ -2196,7 +2202,7 @@ 
for( …​ ){ if( …&#
-

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

+

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

@@ -2205,12 +2211,12 @@

for( …​ ){ for( …​ )

-

Create a Basic Java-based Rule Add-on

+

4.4. Create a Basic Java-based Rule Add-on

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

-

Prerequisites

+

4.4.1. Prerequisites

  • @@ -2248,7 +2254,7 @@

    Prerequisites

-

Create a Rule Add-on

+

4.4.2. Create a Rule Add-on

Create a Maven Project
@@ -2418,7 +2424,10 @@
Create the Java RuleProvider
  1. -

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

    +

    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:

    public class MyCustomRuleProvider extends WindupRuleProvider
@@ -2526,7 +2535,7 @@ 
    Create the Java RuleProvider
    -

    Install the Java-based Rule Add-on

    +

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

    @@ -2555,7 +2564,7 @@

    Install the Java-based Rule Add-on<

-

Test the Java-based Rule Add-on

+

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

@@ -2580,7 +2589,7 @@

Test the Java-based Rule Add-on

-

Review the Output Report

+

4.4.5. Review the Output Report

  1. @@ -2628,277 +2637,1001 @@

    Review the Output Report

- -
  • -

    Inter-rule action

    -
    • -
  • -

    Inter-rule dependency

    -
    -
      -
    • -

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

      -
      • -
    +
    • +
  • +

    Inter-rule action

    +
    • +
  • +

    Inter-rule dependency

    +
    +
      +
    • +

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

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

    5. Create and Test XML Rules

    +
    +
    +

    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.

    +
    +
    +

    5.1.1. Prerequisites

    +
    + +
    +
    +
    +

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

    +
    +
    +
    +

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

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

    +
    +
    +
    +

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

    +
    +
    +
    +
    +

    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.

    +
    +
    +

    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.

    +
    +
    + +
    +
    +

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

    5.2.2. 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"/>
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    5.2.3. 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 = "???"

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

    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

    +
    +
    +

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

    +
    +
    +
    +
    +

    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.

    +
    +
    +

    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.

    +
    +
    + +
    +
    +

    5.3.1. 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>
    +
    +
    +
    +
    +
    Construct a link Element
    +
    +
    link Element: Attributes
    +
    +
    +
    href="URI"
    +
    +

    The URI for the referenced link/.

    +
    +

    Example:

    +
    +
    +
    +
    href="https://access.redhat.com/articles/1249423"
    +
    +
    +
    +
    description="URI_DESCRIPTION"
    +
    +

    A description for the link.

    +
    +

    Example:

    +
    +
    +
    +
    description="Migrate WebLogic Proprietary Servlet Annotations"
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

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

    +
    +
    +

    Example:

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

    +
    +
    +
    +
    message=""
    +
    +
    +
    +
    effort="NUMBER"
    +
    +

    The level of effort assigned to this resource.

    +
    +

    Example:

    +
    +
    +
    +
    effort="2"
    +
    +
    +
    +
    +
    +
    +
    +
    hint Element: Child Elements
    +
    +
    +
    xref
    +
    +

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

    +
    +

    Example:

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

    5.3.4. xslt Syntax

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

    +
    +
    +

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

    +
    +
    +

    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>
    +
    +
    +
    +
    +
    Construct an xslt Element
    +
    +
    xslt Element: Attributes
    +
    +
    +
    of="STRING"
    +
    +

    Create a new transformation for the given reference.

    +
    +

    Example:

    +
    +
    +
    +
    of="testVariable_instance"
    +
    +
    +
    +
    description="String"
    +
    +

    Sets the description of this XSLTTransformation.

    +
    +

    Example:

    +
    +
    +
    +
    description="XSLT Transformed Output"
    +
    - - +
    +
    extension="String"
    +
    +

    Sets the extension for this XSLTTransformation.

    +
    +

    Example:

    - - +
    +
    +
    extension="-result.html"
    -
    -
    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. -
    +
    +
    template=String
    +
    +

    Sets the XSL template.

    +
    +

    Example:

    +
    +
    +
    template="simpleXSLT.xsl"
    +
    +
    -
    -

    Create and Test XML Rules

    -
    -
    -

    Create a Basic XML Rule

    +
    +
    xslt Element: Child Elements
    +
    +
    +
    xslt-parameter=Map<String,String>
    +
    +

    Specify XSLTTransformation parameters as property value pairs

    -

    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.

    +

    Example:

    -
    -

    Prerequisites

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

    Create a Rule

    +

    5.3.5. lineitem Syntax

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

    +
    -

    The following is an example of an XML rule.

    +

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

    +
    +
    +

    Example:

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

    A lineitem message

    -

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

    +

    Example:

    -
    -

    The XML rule consists of the following level elements:

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

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

      -
      • -
    • -

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

      -
      • -
    • -

      <rules>: element contains the individual rules.

      -
      -
        -
      • -

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

        -
        -
          -
        • -

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

          -
          -
            -
          • -

            <javaclass references="CLASS_NAME">

            -
            -
              -
            • -

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

              -
              • -
            -
            • -
          +
    +
    - -
  • -

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

    -
    -
      -
    • -

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

      -
      -
        -
      • -

        <message>:

        -
        • -
      • -

        <link>:

        -
        • -
      -
      • -
    • -

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

      -
      • -
    • -

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

      -
      • -
    -
    • -
  • -

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

    -
    • -
    - - +
    +

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

    - - +
    +

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

    Add the Rule to Windup

    -
    -

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

    +
    +
    Construct an iteration Element
    +
    +
    iteration Element: Attributes
    -
    WINDUP_HOME/rules/
    -
    -

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

    -
    -
    ${user.home}/.windup/rules/
    +
    over="NUMBER"
    -

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

    -
    +

    ??

    +
    +

    Example:

    +
    +
    -
    For Linux or Mac:   ~/.windup/rules/
-For Windows: "\Documents and Settings\USER_NAME\.windup\rules\"  -or-  "\Users\USER_NAME\.windup\rules\"
    +
    over="2"
    +
    +
    iteration Element: Child Elements
    +
    +

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

    +
    +
    +
    +
    +
    +
    +

    5.4. Test an XML Rule in Windup

    -

    Test the XML Rule

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

    5.4.1. Add the Rule to Windup

    +
    +

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

    +
    +
      +
    • +

      The WINDUP_HOME/rules/ folder.

      -

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

      +

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

      +
      +
      • +
    • +

      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.

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

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

      The command uses this syntax:

      @@ -2912,23 +3645,36 @@

      Test the XML Rule

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

    5.4.3. Additional Resources

    +
    +
    -

    Review the Report

    +

    6. Review the Report

    -

    Review the Report

    +

    6.1. Review the Report

    -

    About the Report

    +

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

    @@ -2961,19 +3707,19 @@

    About the Report

    -

    Open the Report

    +

    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

    +

    Report Index Page

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

    -

    Report Sections

    +

    6.1.3. Report Sections

    Application Report Page
    @@ -2993,7 +3739,7 @@
    Application Report Page

    The following is an example of a Windup Application Report.

    -

    Report Summary Page

    +

    Report Summary Page

    @@ -3056,7 +3802,7 @@
    Archive Analysis Sections

    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

    +

    Report Archive Page

    @@ -3078,18 +3824,18 @@
    File Analysis Pages

    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

    +

    File Detail - Part 1

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

    -

    File Detail - Part 2

    +

    File Detail - Part 2

    -

    Additional Reports

    +

    6.1.4. Additional Reports

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

    @@ -3099,7 +3845,7 @@
    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

    +

    RuleProvider Report

    @@ -3114,7 +3860,7 @@
    Individual File Analysis ReportsYou 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

    +

    Report Directory File List

    @@ -3122,10 +3868,10 @@
    Individual File Analysis Reports
    -

    External Rule Examples

    +

    7. External Rule Examples

    -

    Review the Windup Quickstarts

    +

    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

    @@ -3133,7 +3879,7 @@

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

    +

    7.1.1. Download the Latest ZIP

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

    @@ -3142,7 +3888,7 @@

    Download the Latest ZIP

    -

    Fork and Clone the GitHub Project

    +

    7.1.2. Fork and Clone the GitHub Project

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

    @@ -3190,12 +3936,12 @@

    Fork and Clone the GitHub Project

    -

    Debugging and Troubleshooting

    +

    8. Debugging and Troubleshooting

    -

    Debugging and Profiling

    +

    8.1. Debugging and Profiling

    -

    Debug the Windup Distribution Runtime

    +

    8.1.1. Debug the Windup Distribution Runtime

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

    @@ -3222,13 +3968,13 @@

    Debug the Windup Distribution Ru

    -

    Debug a Test Using NetBeans

    +

    8.1.2. Debug a Test Using NetBeans

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

    -

    Profile a Test Using NetBeans

    +

    8.1.3. Profile a Test Using NetBeans

    1. @@ -3270,7 +4016,7 @@

      Profile a Test Using NetBeans

    -

    Profile Forge Runtime Using YourKit

    +

    8.1.4. Profile Forge Runtime Using YourKit

    1. @@ -3302,9 +4048,9 @@

      Profile Forge Runtime Using YourKi

    -

    Troubleshoot Windup Issues

    +

    8.2. Troubleshoot Windup Issues

    -

    Logging

    +

    8.2.1. Logging

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

    @@ -3313,7 +4059,7 @@

    Logging

    -

    Debugging Exceptions

    +

    8.2.2. Debugging Exceptions

    Exceptions in Surefire reports are broken due to the way Forge wraps exceptions and the way Surefire handles them. You need to @@ -3324,22 +4070,31 @@

    Debugging Exceptions

    -

    Classloading Problems

    +

    8.2.3. Classloading Problems

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

    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.

    +
    -

    Additional Resources

    +

    9. Additional Resources

    -

    Available Rule Utilities

    +

    9.1. Available Rule Utilities

    -

    Programmatically Access the Graph

    +

    9.1.1. Programmatically Access the Graph

    Note: Needs update. This is out of date!

    @@ -3433,7 +4188,7 @@
    Nested Iteration
    -

    Modify Graph Data

    +

    9.1.2. Modify Graph Data

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

    @@ -3463,7 +4218,7 @@

    Modify Graph Data

    -

    Review the Windup Quickstarts

    +

    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

    @@ -3471,7 +4226,7 @@

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

    +

    9.2.1. Download the Latest ZIP

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

    @@ -3480,7 +4235,7 @@

    Download the Latest ZIP

    -

    Fork and Clone the GitHub Project

    +

    9.2.2. Fork and Clone the GitHub Project

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

    @@ -3526,15 +4281,15 @@

    Fork and Clone the GitHub Project<

    -

    Known Windup Issues

    +

    9.3. Known Windup Issues

    Windup known issues are tracked here: Open Windup issues

    -

    Glossary of Terms Used in Windup

    +

    9.4. Glossary of Terms Used in Windup

    -

    Rules Terms

    +

    9.4.1. Rules Terms

    Rule
    @@ -3597,7 +4352,7 @@

    Rules Terms

    -

    Reporting Terms

    +

    9.4.2. Reporting Terms

    Lift and Shift (Level of effort)
    @@ -3623,10 +4378,10 @@

    Reporting Terms

    -

    Appendix

    +

    10. Appendix

    -

    Windup Architectural Components

    +

    10.1. 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 @@ -3634,7 +4389,7 @@

    Windup Architectural Components

    familiar with them.

    -

    Forge

    +

    10.1.1. Forge

    Forge is an open source, extendable, rapid application development tool for creating Java EE applications using Maven. For more information @@ -3642,7 +4397,7 @@

    Forge

    -

    Forge Furnace

    +

    10.1.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 @@ -3651,21 +4406,21 @@

    Forge Furnace

    -

    TinkerPop

    +

    10.1.3. TinkerPop

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

    -

    Titan

    +

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

    +

    10.1.5. Frames

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

    Frames

    -

    Gremlin

    +

    10.1.6. Gremlin

    Gremlin is a graph traversal language that allows you to query, analyze, and manipulate property graphs that implement the Blueprints property @@ -3686,7 +4441,7 @@

    Gremlin

    -

    Blueprints

    +

    10.1.7. Blueprints

    Blueprints is an industry standard API used to access graph databases. For more information about Blueprints, see: @@ -3694,7 +4449,7 @@

    Blueprints

    -

    Pipes

    +

    10.1.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: @@ -3702,14 +4457,14 @@

    Pipes

    -

    Rexster

    +

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

    +

    10.1.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 @@ -3718,7 +4473,7 @@

    OCPsoft Rewrite

    -

    Dependencies (Forge add-ons)

    +

    10.2. Dependencies (Forge add-ons)

    DRAFT

    Based on @@ -3726,7 +4481,7 @@

    Dependencies (Forge add-ons)

    discussion.

    -

    Maven Add-on Structure

    +

    10.2.1. Maven Add-on Structure

    The following is the typical structure of Maven add-on modules.

    @@ -3776,7 +4531,7 @@

    Maven Add-on Structure

    -

    Add-on sub-parts

    +

    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 @@ -3834,7 +4589,7 @@

    Add-on sub-parts

    -

    Test dependencies

    +

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

    @@ -3852,7 +4607,7 @@

    Test dependencies

    -

    Dependencies between sub-parts within the same add-on

    +

    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 @@ -3870,7 +4625,7 @@

    Dependencies bet

    -

    Windup Models

    +

    10.3. Windup Models

    Windup models are the classes extending WindupVertexFrame. They are used to model the data in the graph database to Java objects.

    @@ -3880,10 +4635,10 @@

    Windup Models

    The complete and up-to-date list of models is in Javadoc.

    -

    Windup Models Graphic

    +

    Windup Models Graphic

    -

    Meta Models

    +

    10.3.1. Meta Models

    • @@ -3896,17 +4651,17 @@

      Meta Models

    -

    Core Models

    +

    10.3.2. Core Models

    FileModel ArchiveModel

    -

    Reporting Models

    +

    10.3.3. Reporting Models

    -

    Custom Models (coming from Addons)

    +

    10.3.4. Custom Models (coming from Addons)

    See respective ruleset’s documentation.

    @@ -3917,7 +4672,7 @@

    Custom Models (coming from Addons) diff --git a/html/WindupUserGuide.html b/html/WindupUserGuide.html index 4f3e9913a4..83c408d892 100644 --- a/html/WindupUserGuide.html +++ b/html/WindupUserGuide.html @@ -417,7 +417,7 @@

    Windup User Guide

    -
    -

    What is Windup?

    Windup Logo

    +
    +

    What is Windup?

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

    @@ -664,7 +664,10 @@

    Windup Processing Overview

    Discovery Phase

    -

    Wnen you run the windup-migrate-app command, Windup executes its own core rules to extract files from archives, decompile classes, and analyze the application. In this phase, Windup builds a datamodel, storing component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.

    +

    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.

    @@ -801,6 +804,9 @@

    Helpful links

    Windup Forums: https://community.jboss.org/en/windup

  • +

    Windup Forums: https://developer.jboss.org/en/windup (inherited from Windup 0.x)

    +
    • +

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

  • @@ -1095,7 +1101,7 @@

    Run the windup-migr
    Note
    -If the OUTPUT_REPORT_DIRECTORY directory exists, your 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, 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! @@ -1680,7 +1686,7 @@

    OCPsoft Rewrite

    • diff --git a/scripts/pagelinksCoreDevelopmentGuide.sh b/scripts/pagelinksCoreDevelopmentGuide.sh index 34a5fe3d99..3e2ec99dd5 100755 --- a/scripts/pagelinksCoreDevelopmentGuide.sh +++ b/scripts/pagelinksCoreDevelopmentGuide.sh @@ -12,7 +12,7 @@ grep 'link:[A-Z]' `find . -name 'Get-Involved.adoc'` grep 'link:[A-Z]' `find . -name 'Dev-Windup-Project-Information.adoc'` grep 'link:[A-Z]' `find . -name 'Report-Issues-with-Windup.adoc'` grep 'link:[A-Z]' `find . -name 'About-the-WINDUP_HOME-Variable.adoc'` -grep 'link:[A-Z]' `find . -name 'Dev-Development-Guidelines.adoc'` +grep 'link:[A-Z]' `find . -name 'Dev-Development-Guidelines-and-Conventions.adoc'` grep 'link:[A-Z]' `find . -name 'Dev-Submit-Code-Updates-to-the-Windup-Project.adoc'` grep 'link:[A-Z]' `find . -name 'Windup-Architectural-Components.adoc'` grep 'link:[A-Z]' `find . -name 'Dev-Windup-Project-Structure.adoc'` diff --git a/scripts/pagelinksCoreDevelopmentGuide.txt b/scripts/pagelinksCoreDevelopmentGuide.txt deleted file mode 100644 index dc3b4b2607..0000000000 --- a/scripts/pagelinksCoreDevelopmentGuide.txt +++ /dev/null @@ -1,105 +0,0 @@ -= Windup Core Development Guide - -:toc: -:toclevels: 4 - -== Overview - -This guide is for developers who plan to contribute source code updates -or core rule add-ons to the Windup 2.0 project. - -NOTE: This is a very rough first draft! - -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] - -== Developer Contributing Information - -include::Dev-Development-Guidelines.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] - -== 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] - -== Create and Test Java Rule Add-ons -include::Rules-Java-based-Rule-Structure.adoc[tabsize=4] -include::Rules-Basic-Rule-Execution-Flow-Patterns.adoc[tabsize=4] -include::Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc[tabsize=4] -include::Rules-Create-an-Advanced-Ruleset.adoc[tabsize=4] - -== Create and Test XML Rules - -include::Rules-Create-a-Basic-XML-Rule.adoc[tabsize=4] - -== 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-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 - -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] -include::Known-Issues.adoc[tabsize=4] -include::Glossary.adoc[tabsize=4] - diff --git a/scripts/pagelinksRulesDevelopmentGuide.txt b/scripts/pagelinksRulesDevelopmentGuide.txt deleted file mode 100644 index b9efdb3ae1..0000000000 --- a/scripts/pagelinksRulesDevelopmentGuide.txt +++ /dev/null @@ -1,89 +0,0 @@ -= Windup Rules Development Guide - -:toc: -:toclevels: 4 - - -== Overview - -This guide is for engineers, consultants, and others who plan to use -Windup 2.0 to migrate Java applications or other components. - -NOTE: This is a very rough first draft! - -include::What-is-Windup.adoc[tabsize=4] - -include::Features-of-Windup-2.0.adoc[tabsize=4] - -include::Windup-Processing-Overview.adoc[tabsize=4] - -include::Get-Involved.adoc[tabsize=4] - -include::Report-Issues-with-Windup.adoc[tabsize=4] - -include::About-the-WINDUP_HOME-Variable.adoc[tabsize=4] - - -== Get Started - -include::Install-Windup.adoc[tabsize=4] - -include::Execute-Windup.adoc[tabsize=4] - -include::Review-the-Report.adoc[tabsize=4] - - -== Configure Your System for Java-based Rules - -If you plan to create Java-based rule addons, you must also do the following. - -include::Install-and-Configure-Maven.adoc[tabsize=4] - -include::http://windup.github.io/windup/docs/javadoc/latest/[Windup API JavaDoc reference]: The JavaDoc can serve as a reference for creating Java-based rule addons. - -== Understand the Rule Processing - -include::Windup-Processing-Overview.adoc[tabsize=4] -include::Rules-Rule-Execution-Lifecycle.adoc[tabsize=4] -include::Rules-Rule-Story-Points.adoc[tabsize=4] - -== Create and Test Java Rule Addons - -include::Rules-Java-based-Rule-Structure.adoc[tabsize=4] -include::Rules-Basic-Rule-Execution-Flow-Patterns.adoc[tabsize=4] -include::Rules-Create-a-Basic-Java-based-Rule-Add-on.adoc[tabsize=4] -include::Rules-Create-an-Advanced-Ruleset.adoc[tabsize=4] - -== Create and Test XML Rules - -include::Rules-Create-a-Basic-XML-Rule.adoc[tabsize=4] - -== Review the Report - -include::Review-the-Report.adoc[tabsize=4] - -== External Rule Examples - -include::Review-the-Windup-Quickstarts.adoc[tabsize=4] - -== Debugging and Troubleshooting - -include::Dev-Debugging-and-Profiling.adoc[tabsize=4] -include::Dev-Troubleshoot-Windup-Issues.adoc[tabsize=4] - - -== Additional Resources - -include::Rules-Available-Rules-Utilities.adoc[tabsize=4] -include::Review-the-Windup-Quickstarts.adoc[tabsize=4] -include::Known-Issues.adoc[tabsize=4] -include::Glossary.adoc[tabsize=4] - -== Appendix - -include::Windup-Architectural-Components.adoc[tabsize=4] -include::Dev-Dependencies.adoc[tabsize=4] -include::Rules-Windup-Models.adoc[tabsize=4] - - - diff --git a/scripts/windupDocUpdate.sh b/scripts/windupDocUpdate.sh index eadb4a08fc..054686c7e0 100755 --- a/scripts/windupDocUpdate.sh +++ b/scripts/windupDocUpdate.sh @@ -96,6 +96,9 @@ cp $1/Rules-Create-a-Basic-Java-based-Rule-Add-on.asciidoc docs/Rules-Create-a-B cp $1/Rules-Create-an-Advanced-Ruleset.asciidoc docs/Rules-Create-an-Advanced-Ruleset.adoc ## Create and Test XML Rules cp $1/Rules-Create-a-Basic-XML-Rule.asciidoc docs/Rules-Create-a-Basic-XML-Rule.adoc +cp $1/Rules-XML-Rule-When-Condition-Syntax.asciidoc docs/Rules-XML-Rule-When-Condition-Syntax.adoc +cp $1/Rules-XML-Rule-Perform-Action-Syntax.asciidoc docs/Rules-XML-Rule-Perform-Action-Syntax.adoc +cp $1/Rules-Test-a-Basic-XML-Rule-in-Windup.asciidoc docs/Rules-Test-a-Basic-XML-Rule-in-Windup.adoc ## Debugging and Troubleshooting cp $1/Dev-Debugging-and-Profiling.asciidoc docs/Dev-Debugging-and-Profiling.adoc cp $1/Dev-Troubleshoot-Windup-Issues.asciidoc docs/Dev-Troubleshoot-Windup-Issues.adoc @@ -131,7 +134,7 @@ cp $1/Report-Issues-with-Windup.asciidoc docs/Report-Issues-with-Windup.adoc cp $1/About-the-WINDUP_HOME-Variable.asciidoc docs/About-the-WINDUP_HOME-Variable.adoc ## Developer Contributing Information -cp $1/Dev-Development-Guidelines.asciidoc docs/Dev-Development-Guidelines.adoc +cp $1/Dev-Development-Guidelines-and-Conventions.asciidoc docs/Dev-Development-Guidelines-and-Conventions.adoc cp $1/Dev-Submit-Code-Updates-to-the-Windup-Project.asciidoc docs/Dev-Submit-Code-Updates-to-the-Windup-Project.adoc ## Understand the Windup Architecture and Structure @@ -205,7 +208,7 @@ cp $1/Ruleset-Reporting.asciidoc docs/Ruleset-Reporting.adoc cp $1/Ruleset-XML.asciidoc docs/Ruleset-XML.adoc cp $1/Rules-Windup-Models.asciidoc docs/Rules-Windup-Models.adoc cp $1/Rules-Create-Java-Queries.asciidoc docs/Rules-Create-Java-Queries.adoc -cp $1/Rules-Rules-Metadata.asciidoc docs/Rules-Rules-Metadata.adoc +cp $1/Rule-Metadata.asciidoc docs/Rule-Metadata.adoc cp $1/Rules-Rules-Operations.asciidoc docs/Rules-Rules-Operations.adoc cp $1/Rules-Ops-Reporting-Classification.asciidoc docs/Rules-Ops-Reporting-Classification.adoc cp $1/Rules-Ops-Reporting-Hint.asciidoc docs/Rules-Ops-Reporting-Hint.adoc