diff --git a/docs/Windup-Core-Development-Guide.adoc b/docs/Windup-Core-Development-Guide.adoc index 7ea4c9abfa..0b8bbedb39 100644 --- a/docs/Windup-Core-Development-Guide.adoc +++ b/docs/Windup-Core-Development-Guide.adoc @@ -1,7 +1,10 @@ = Windup Core Development Guide -:toc: -:toclevels: 4 +:toc: left +:toclevels: 5 +:sectnumlevels: 5 +:numbered: + == Overview diff --git a/docs/Windup-Rules-Development-Guide.adoc b/docs/Windup-Rules-Development-Guide.adoc index ada2632d95..b607f2e72d 100644 --- a/docs/Windup-Rules-Development-Guide.adoc +++ b/docs/Windup-Rules-Development-Guide.adoc @@ -1,7 +1,9 @@ = Windup Rules Development Guide -:toc: -:toclevels: 4 +:toc: left +:toclevels: 5 +:sectnumlevels: 5 +:numbered: == Overview diff --git a/docs/Windup-User-Guide.adoc b/docs/Windup-User-Guide.adoc index 950471e2ec..9b4d3983d1 100644 --- a/docs/Windup-User-Guide.adoc +++ b/docs/Windup-User-Guide.adoc @@ -1,7 +1,9 @@ = Windup User Guide -:toc: -:toclevels: 4 +:toc: left +:toclevels: 5 +:sectnumlevels: 5 +:numbered: == Overview diff --git a/html/WindupCoreDevelopmentGuide.html b/html/WindupCoreDevelopmentGuide.html index 421aeeb44b..92a3f51680 100644 --- a/html/WindupCoreDevelopmentGuide.html +++ b/html/WindupCoreDevelopmentGuide.html @@ -415,99 +415,99 @@

Windup Core Development Guide

Table of Contents
@@ -515,14 +515,14 @@

Windup Core Development Guide

-

Overview

+

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

+

1.1. What is Windup?

Windup Logo

@@ -537,13 +537,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 @@ -583,14 +583,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

@@ -724,9 +724,9 @@

Features of Windup 2.0

-

Get Involved

+

1.3. Get Involved

-

How can you help?

+

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

@@ -793,7 +793,7 @@

How can you help?

- +
  • @@ -838,7 +838,7 @@
-

Github Repository

+

1.3.3. Github Repository

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

@@ -847,7 +847,7 @@

Github Repository

-

Documentation

+

1.3.4. Documentation

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

@@ -856,7 +856,7 @@

Documentation

-

Website

+

1.3.5. Website

There is currently no website for Windup 2.0.

@@ -866,14 +866,14 @@

Website

-

IRC chat

+

1.3.6. IRC chat

Server: irc.freenode.net
Channel: #windup

-

Mailing lists

+

1.3.7. Mailing lists

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

@@ -890,7 +890,7 @@

Mailing lists

-

Core development team (and IRC nicks)

+

1.3.8. Core development team (and IRC nicks)

Lead: Lincoln Baxter (lincolnthree)
Members: Jess Sightler (jsightler), Matej Briskar (mbriskar), Ondrej @@ -898,7 +898,7 @@

Core development team (and IRC nic

-

IRC meeting bot commands (hint for the moderator)

+

1.3.9. IRC meeting bot commands (hint for the moderator)

#startmeeting
@@ -914,12 +914,12 @@ 

IRC meeting bot comman

-

Report Issues with Windup

+

1.4. Report Issues with Windup

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

-

Create a JIRA Account

+

1.4.1. Create a JIRA Account

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

@@ -941,7 +941,7 @@

Create a JIRA Account

-

Create a JIRA Issue

+

1.4.2. Create a JIRA Issue

  1. @@ -1016,17 +1016,17 @@

    Create a JIRA Issue

-

Developer Contributing Information

+

2. Developer Contributing Information

-

Development Guidelines

+

2.1. Development Guidelines

-

Project Source Code Format

+

2.1.1. Project Source Code Format

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
+
2.1.1.1. Eclipse IDE
  1. @@ -1045,27 +1045,27 @@
    Eclipse IDE
-
Netbeans IDE
+
2.1.1.2. Netbeans IDE
-
IntelliJ IDEA
+
2.1.1.3. IntelliJ IDEA

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

-

Naming conventions

+

2.1.2. Naming conventions

-
Suffixes and prefixes
+
2.1.2.1. Suffixes and prefixes

*RuleProvider

-
Models
+
2.1.2.1.1. Models

*Model

@@ -1074,7 +1074,7 @@
Models
-
Tests
+
2.1.2.1.2. Tests

All test names should be prefixed with 'Test'.

@@ -1083,7 +1083,7 @@
Tests
-

Submit Code Updates to the Windup Project

+

2.2. Submit Code Updates to the Windup Project

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

@@ -1188,10 +1188,10 @@

Submit Code Updates to th

-

Understand the Windup Architecture and Structure

+

3. Understand the Windup Architecture and Structure

-

Windup Architectural Components

+

3.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 @@ -1199,7 +1199,7 @@

Windup Architectural Components

familiar with them.

-

Forge

+

3.1.1. Forge

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

Forge

-

Forge Furnace

+

3.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 @@ -1216,21 +1216,21 @@

Forge Furnace

-

TinkerPop

+

3.1.3. TinkerPop

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

-

Titan

+

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

+

3.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: @@ -1242,7 +1242,7 @@

Frames

-

Gremlin

+

3.1.6. Gremlin

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

Gremlin

-

Blueprints

+

3.1.7. Blueprints

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

Blueprints

-

Pipes

+

3.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: @@ -1267,14 +1267,14 @@

Pipes

-

Rexster

+

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

+

3.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 @@ -1283,7 +1283,7 @@

OCPsoft Rewrite

-

Windup Project Structure

+

3.2. Windup Project Structure

The Windup 2.0 project consists of the following subprojects.

@@ -1350,12 +1350,12 @@

Windup Project Structure

-

Get Started

+

4. Get Started

-

Install and Configure Maven

+

4.1. Install and Configure Maven

-

Download and Install Maven

+

4.1.1. 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 @@ -1381,7 +1381,7 @@

Download and Install Maven

-

Configure the Maven Installation in Your IDE

+

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 @@ -1415,7 +1415,7 @@

Configure the Maven Insta

-

Configure Maven to Build Windup

+

4.1.3. Configure Maven to Build Windup

Windup uses artifacts located in the JBoss Nexus @@ -1481,7 +1481,7 @@

Configure Maven to Build Windup

-

Install the Git Client

+

4.1.4. Install the Git Client

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

@@ -1512,7 +1512,7 @@

Install the Git Client

-

Fork and Clone the Windup Repository

+

4.1.5. Fork and Clone the Windup Repository

  1. @@ -1554,7 +1554,7 @@

    Fork and Clone the Windup Reposit

-

Build Windup from Source

+

4.2. Build Windup from Source

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

@@ -1563,7 +1563,7 @@

Build Windup from Source

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

-

System Requirements to Build Windup

+

4.2.1. System Requirements to Build Windup

  1. @@ -1619,7 +1619,7 @@

    System Requirements to Build Windu

-

Build Windup Using Maven Command Line

+

4.2.2. Build Windup Using Maven Command Line

  1. @@ -1693,7 +1693,7 @@

    Build Windup Using Maven Command

-

Build Windup Using Red Hat JBoss Developer Studio or Eclipse

+

4.2.3. Build Windup Using Red Hat JBoss Developer Studio or Eclipse

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

@@ -1732,7 +1732,7 @@

Build Win

-

Extract the Windup Distribution Source File

+

4.2.4. Extract the Windup Distribution Source File

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

@@ -1741,7 +1741,7 @@

Extract the Windup Distrib

-

Quick Build Review for Experienced Windup Developers

+

4.2.5. Quick Build Review for Experienced Windup Developers

git clone git@github.com:windup/windup.git Windup
@@ -1755,7 +1755,7 @@ 

Quick Build Review

-

Execute Windup (Built from Windup Source)

+

4.3. Execute Windup (Built from Windup Source)

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

@@ -1790,9 +1790,9 @@

Execute Windup (Built from Windup

-

Execute Windup

+

4.4. Execute Windup

-

Prerequisites

+

4.4.1. Prerequisites

Before you begin, you must gather the following information.

@@ -1857,7 +1857,7 @@

Prerequisites

-

Start Windup

+

4.4.2. Start Windup

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

@@ -1898,7 +1898,7 @@

Start Windup

-

Run the windup-migrate-app Command

+

4.4.3. Run the windup-migrate-app Command

  1. @@ -1981,7 +1981,7 @@

    Run the windup-migr

-

Run Windup in Batch Mode

+

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

@@ -2003,7 +2003,7 @@

Run Windup in Batch Mode

-

Windup Help

+

4.4.5. Windup Help

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

@@ -2014,12 +2014,12 @@

Windup Help

-

Windup Command Examples

+

4.4.6. Windup Command Examples

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

-
Source Code Example
+
4.4.6.1. Source Code Example

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

@@ -2030,7 +2030,7 @@
Source Code Example
-
Archive Example
+
4.4.6.2. Archive Example

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

@@ -2041,7 +2041,7 @@
Archive Example
-
Windup Batch Example
+
4.4.6.3. Windup Batch Example

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

@@ -2053,7 +2053,7 @@
Windup Batch Example
-
Windup Quickstart Examples
+
4.4.6.4. Windup Quickstart Examples

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

@@ -2064,9 +2064,9 @@
Windup Quickstart Examples
-

Review the Report

+

4.5. Review the Report

-

About the Report

+

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

@@ -2099,7 +2099,7 @@

About the Report

-

Open the Report

+

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

@@ -2111,9 +2111,9 @@

Open the Report

-

Report Sections

+

4.5.3. Report Sections

-
Application Report Page
+
4.5.3.1. Application Report Page

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

@@ -2135,7 +2135,7 @@
Application Report Page
-
Archive Analysis Sections
+
4.5.3.2. Archive Analysis Sections

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

@@ -2198,7 +2198,7 @@
Archive Analysis Sections
-
File Analysis Pages
+
4.5.3.3. File Analysis Pages

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

@@ -2227,12 +2227,12 @@
File Analysis Pages
-

Additional Reports

+

4.5.4. Additional Reports

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

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

@@ -2241,13 +2241,13 @@
Rule Provider Execution Report
-
Rule Provider Execution Report
+
4.5.4.2. Rule Provider Execution Report

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

-
Individual File Analysis Reports
+
4.5.4.3. 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.

@@ -2260,10 +2260,10 @@
Individual File Analysis Reports
-

Rules and Rulesets

+

5. Rules and Rulesets

-

Windup Processing Overview

+

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

@@ -2271,7 +2271,7 @@

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

+

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

@@ -2280,7 +2280,7 @@

Discovery Phase

-

Application Migration

+

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

@@ -2289,7 +2289,7 @@

Application Migration

-

Generate Findings Based on the Rule Execution Results

+

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

@@ -2315,9 +2315,9 @@

Generate Finding

-

Rule Execution Lifecycle

+

5.2. Rule Execution Lifecycle

-

Rule Lifecycle

+

5.2.1. Rule Lifecycle

Windup executes each rule in sequential order. The following sections describe the phases of rule execution and how rules may specify @@ -2331,7 +2331,7 @@

Rule Lifecycle

-

Rule Phases

+

5.2.2. Rule Phases

INFO: Loaded [67] org.jboss.windup.config.WindupRuleProvider [
@@ -2431,7 +2431,7 @@ 

Rule Phases

-

Execute Before and Execute After

+

5.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 @@ -2463,16 +2463,16 @@

Execute Before and Execute After

-

Rule Story Points

+

5.3. Rule Story Points

-

What are Story Points?

+

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

+

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

@@ -2524,17 +2524,17 @@

How to Estimate Story Points in

-

Create and Test Java Rule Add-ons

+

6. Create and Test Java Rule Add-ons

-

Java-based Rule Structure

+

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

+

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

@@ -2586,7 +2586,7 @@

Windup Rule Provider

-

Add Rule Code Structure

+

6.1.2. Add Rule Code Structure

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

@@ -2605,7 +2605,7 @@

Add Rule Code Structure

and some others, all of which are optional.

-
when()
+
6.1.2.1. when()
.when(Query.fromType(XmlMetaFacetModel.class))
@@ -2628,7 +2628,7 @@
when()
-
perform()
+
6.1.2.2. perform()
.perform(
@@ -2655,7 +2655,7 @@ 
perform()
(Iteration).

-
Iteration
+
6.1.2.2.1. Iteration
.perform(
@@ -2677,13 +2677,13 @@ 
Iteration
-
Nested iterations
+
6.1.2.2.2. Nested iterations

TODO

-
otherwise
+
6.1.2.2.3. otherwise

Windup rules inherit the rule constructs from OCP Rewrite. For example, .otherwise() Gives you a chance to perform something in case the @@ -2706,13 +2706,13 @@

otherwise
-
Where
+
6.1.2.3. Where

TODO

-
Metadata
+
6.1.2.4. Metadata

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

@@ -2729,7 +2729,7 @@
Metadata
-

Available utilities

+

6.1.3. Available utilities

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

@@ -2737,12 +2737,12 @@

Available utilities

-

Basic Rule Execution Flow Patterns

+

6.2. Basic Rule Execution Flow Patterns

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

-

operation(); - single operation

+

6.2.1. operation(); - single operation

When no iteration or condition is needed.

@@ -2763,7 +2763,7 @@

operation(); - single operation

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2779,7 +2779,7 @@ 

if( …​ ){ operat

-

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

+

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

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

@@ -2810,7 +2810,7 @@

for( FooModel.class ){ …R

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2825,7 +2825,7 @@ 

if( …​ ){ for( …​

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2852,7 +2852,7 @@ 

for( …​ ){ if( …&#

-

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

+

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

@@ -2861,12 +2861,12 @@

for( …​ ){ for( …​ )

-

Create a Basic Java-based Rule Add-on

+

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

+

6.3.1. Prerequisites

  • @@ -2904,9 +2904,9 @@

    Prerequisites

-

Create a Rule Add-on

+

6.3.2. Create a Rule Add-on

-
Create a Maven Project
+
6.3.2.1. Create a Maven Project

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

@@ -3070,7 +3070,7 @@
Create a Maven Project
-
Create the Java RuleProvider
+
6.3.2.2. Create the Java RuleProvider
  1. @@ -3182,7 +3182,7 @@
    Create the Java RuleProvider
-

Install the Java-based Rule Add-on

+

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

@@ -3211,7 +3211,7 @@

Install the Java-based Rule Add-on<

-

Test the Java-based Rule Add-on

+

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

@@ -3236,7 +3236,7 @@

Test the Java-based Rule Add-on

-

Review the Output Report

+

6.3.5. Review the Output Report

  1. @@ -3338,15 +3338,15 @@

    Review the Output Report

-

Create and Test XML Rules

+

7. Create and Test XML Rules

-

Create a Basic XML Rule

+

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

-

Prerequisites

+

7.1.1. Prerequisites

  • @@ -3381,7 +3381,7 @@

    Prerequisites

-

Create a Rule

+

7.1.2. Create a Rule

The following is an example of an XML rule.

@@ -3435,7 +3435,7 @@

Create a Rule

-
Create the XML Rule
+
7.1.2.1. 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!

@@ -3515,7 +3515,7 @@
Create the XML Rule
-

Add the Rule to Windup

+

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

@@ -3539,7 +3539,7 @@

Add the Rule to Windup

-

Test the XML Rule

+

7.1.4. Test the XML Rule

@@ -3579,16 +3579,16 @@

Test the XML Rule

-

Core Developer topics

+

8. Core Developer topics

-

Windup Bootstrap

+

8.1. Windup Bootstrap

DRAFT

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

-

Boot

+

8.1.1. Boot

  1. @@ -3624,15 +3624,15 @@

    Boot

-

GraphContext

+

8.1.2. GraphContext

-

RuleSubset

+

8.1.3. RuleSubset

-

Frames creation

+

8.1.4. Frames creation

In the GraphContextImpl constructor. For additonal method Handlers, see

@@ -3657,7 +3657,7 @@

Frames creation

-

Classloading Notes

+

8.2. Classloading Notes

DRAFT

Page contains temporary notes, to be edited.

@@ -3666,7 +3666,7 @@

Classloading Notes

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

-

Finding classes

+

8.2.1. Finding classes

AddonRegistry.getServices(MyServiceInterface.class)
@@ -3682,20 +3682,20 @@

Finding classes

-

Instantiating

+

8.2.2. Instantiating

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

-

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

+

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

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

-

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

+

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

Every furnace service is wrapped in a proxy. If it came from another addon (not your current addon) and was not instantiated with new Blah(), @@ -3745,7 +3745,7 @@

How do I know if I am in a

-

Resources loading

+

8.2.5. Resources loading

(16:48:30) ozizka-FN: lincolnthree:  Just a note - the potential collisions caused  by addon's CL span is not considered as a risk?
@@ -3773,27 +3773,27 @@ 

Resources loading

-

What classloader is used by Freemarker to load resources?

+

8.2.6. What classloader is used by Freemarker to load resources?

org.jboss.windup.reporting.freemarker.FurnaceFreeMarkerTemplateLoader

-

Connect to the Graph via Rexster

+

8.3. Connect to the Graph via Rexster

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

-

Running Rexster Within Your Test

+

8.3.1. Running Rexster Within Your Test

Deploy the Rexster add-on by adding the Rexster add-on to the dependencies.

@@ -3812,7 +3812,7 @@

Running Rexster Within Your Test

-

Run Rexster within Windup

+

8.3.2. Run Rexster within Windup

Make sure the Rexster add-on is deployed in Furnace and is accessible on http://localhost:8182/.

@@ -3825,9 +3825,9 @@

Run Rexster within Windup

-

Decompiling

+

8.4. Decompiling

-

The Decompiler API

+

8.4.1. The Decompiler API

DRAFT
    @@ -3857,9 +3857,9 @@

    The Decompiler API

-

Procyon

+

8.4.2. Procyon

-
Config
+
8.4.2.1. Config
  • @@ -3873,13 +3873,13 @@
    Config
-
TypeReference
+
8.4.2.2. TypeReference

TODO: Check how we get info about Java files; perhaps cache the TypeReference results - if worth it?

-
ITypeLoader
+
8.4.2.3. ITypeLoader
  • @@ -3909,7 +3909,7 @@
    ITypeLoader
-

Dependencies (Forge add-ons)

+

8.5. Dependencies (Forge add-ons)

DRAFT

Based on @@ -3917,7 +3917,7 @@

Dependencies (Forge add-ons)

discussion.

-

Maven Add-on Structure

+

8.5.1. Maven Add-on Structure

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

@@ -3967,7 +3967,7 @@

Maven Add-on Structure

-

Add-on sub-parts

+

8.5.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 @@ -4025,7 +4025,7 @@

Add-on sub-parts

-

Test dependencies

+

8.5.3. Test dependencies

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

@@ -4043,7 +4043,7 @@

Test dependencies

-

Dependencies between sub-parts within the same add-on

+

8.5.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 @@ -4061,18 +4061,18 @@

Dependencies bet

-

Frames Extensions

+

8.6. Frames Extensions

Windup has several Frames extensions to satisfy its needs.

-

Multiple Types in a Vertex

+

8.6.1. Multiple Types in a Vertex

Frames stores only one type in the type property. To specify multiple types, use the '|' separator. All sub-parts are indexed.

-

Map Handler

+

8.6.2. Map Handler

TBD

@@ -4081,7 +4081,7 @@

Map Handler

-

Map

+

8.6.3. Map

To store a map in as adjacent vertices.

@@ -4100,7 +4100,7 @@

Map

-

List handler.

+

8.6.4. List handler.

TBD.

@@ -4110,7 +4110,7 @@

List handler.

-

List

+

8.6.5. List

WindupVertexListModel offers a generic model for lists of other models, which are stored as adjacent vertices.

@@ -4118,9 +4118,9 @@

List

-

Internal API Features

+

8.7. Internal API Features

-

Find the RuleProvider that provided a Rule

+

8.7.1. Find the RuleProvider that provided a Rule

A Rule implements Context, which stores metadata. The following example gets the RuleProvider from the Rule context.

@@ -4135,7 +4135,7 @@

Find the RuleProvider that

-

In-memory Frames

+

8.7.2. In-memory Frames

GraphService<FooModel> fooModelService = context.getService(FooModel.class);
@@ -4144,7 +4144,7 @@ 

In-memory Frames

-

Performance measurement

+

8.7.3. Performance measurement

ExecutionStatistics.get().begin("Process-01");
@@ -4158,13 +4158,13 @@ 

Performance measurement

-

Logging

+

8.8. Logging

DRAFT

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

-

Textual logging

+

8.8.1. Textual logging

Windup uses java.util.logging. Convenient way to get the logger is:

@@ -4175,7 +4175,7 @@

Textual logging

-

Displaying Progress

+

8.8.2. Displaying Progress

IterationProgress

@@ -4192,59 +4192,59 @@

Displaying Progress

-

Variables Stack

+

8.9. Variables Stack

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

-

Accessing variables

+

8.9.1. Accessing variables

-
From a Java-based rule
+
8.9.1.1. From a Java-based rule

TODO

-
From a Groovy-based rule
+
8.9.1.2. From a Groovy-based rule

TODO

-
From an EL expression
+
8.9.1.3. From an EL expression

TODO

-
From a FreeMarker
+
8.9.1.4. From a FreeMarker

TODO

-
From XSLT template
+
8.9.1.5. From XSLT template

TODO

-

Accessing variables as a flat Map

+

8.9.2. Accessing variables as a flat Map

TODO

-

Port WindRide Functionality to Windup

+

8.10. Port WindRide Functionality to Windup

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

-

Some classes mapping

+

8.11. Some classes mapping

@ConfigPartDescriptor = @ReportItem
@@ -4254,7 +4254,7 @@ 

Some classes mapping

-

Server-side code to be moved

+

8.12. Server-side code to be moved

  • @@ -4315,7 +4315,7 @@

    Server-side code to be moved

-

Alternate Approach

+

8.12.1. Alternate Approach

This is the approach GitHub suggests.

@@ -4355,12 +4355,12 @@

Alternate Approach

-

Rules topics

+

9. Rules topics

-

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!

@@ -4371,13 +4371,13 @@

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

-
Query the graph
+
9.1.1.1. Query the graph

There are several ways - including Query API, Gremlin support, or GraphService methods.

-
Query the Graph Within the .when() method
+
9.1.1.1.1. Query the Graph Within the .when() method

Building a rule contains the method when(), which is used to create a condition. Vertices that fulfill the condition, are passed to the @@ -4411,7 +4411,7 @@

Query the Graph Within the .whe
-
Iteration
+
9.1.1.1.2. Iteration
ConfigurationBuilder.begin().addRule()
@@ -4426,7 +4426,7 @@ 
Iteration
-
Nested Iteration
+
9.1.1.1.3. Nested Iteration
code,java
@@ -4454,7 +4454,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.

@@ -4484,7 +4484,7 @@

Modify Graph Data

-

Concepts & Philosophy

+

9.2. Concepts & Philosophy

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

@@ -4500,7 +4500,7 @@

Concepts & Philosophy

database.

-

Graph database and Models (Frames)

+

9.2.1. Graph database and Models (Frames)

As a graph db implementation, we use TinkerPop backed by Titan backed by @@ -4522,7 +4522,7 @@

Graph database and Models (Frames)

-

Examples of breaking non-trivial workflows into rules

+

9.2.2. Examples of breaking non-trivial workflows into rules

  1. @@ -4568,7 +4568,7 @@

    Examples of brea

-

Rulesets

+

9.3. Rulesets

DRAFT

@@ -4576,7 +4576,7 @@

Rulesets

Example page for design decisions. Could be generated automatically in the future.

-

What is a Ruleset?

+

9.3.1. What is a Ruleset?

A ruleset is a Windup "plug-in" targetting a specific area of migration (e.g. Spring to Java EE 6 migration). Underhood, it is a set of rules, and everything they might need: Operations and Conditions, Report templates (if needed), and static files (e.g. images, XML or CSV files, etc.). A ruleset may also declare metadata, like ruleset ID, dependencies on other rulesets, etc.

@@ -4593,7 +4593,7 @@

What is a Ruleset?

-

Basic tags

+

9.3.2. Basic tags

  • @@ -4616,9 +4616,9 @@

    Basic tags

-

Rulesets

+

9.3.3. Rulesets

-
Core rulesets
+
9.3.3.1. Core rulesets

Rulesets distributed with Windup and maintained by the Windup team.

@@ -4662,7 +4662,7 @@
Core rulesets
-
Community rulesets
+
9.3.3.2. Community rulesets

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

@@ -4677,14 +4677,14 @@
Community rulesets
-

Metadata

+

9.3.4. Metadata

ID: myRuleset Graph prefix: myRuleset

-

Rule providers

+

9.3.5. Rule providers

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

@@ -4709,7 +4709,7 @@

Rule providers

-

Models

+

9.3.6. Models

  • @@ -4812,7 +4812,7 @@

    Models

-

Configuration

+

9.3.7. Configuration

  • @@ -4822,18 +4822,18 @@

    Configuration

-

Reports

+

9.3.8. Reports

-

Ruleset Java Classifications and Inline Hints

+

9.4. Ruleset Java Classifications and Inline Hints

DRAFT

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

-

Classifications

+

9.4.1. Classifications

Classifications are important because they tell developers very quickly what the resource is, so that they can quickly identify resources of @@ -4859,7 +4859,7 @@

Classifications

-

Inline Hints

+

9.4.2. Inline Hints

Windup takes the approach of profiling resources and providing syntactically highlighted resource reports. The resource report will @@ -4873,7 +4873,7 @@

Inline Hints

-

Ruleset Java EE Apps

+

9.5. Ruleset Java EE Apps

DRAFT

TBD? @@ -4884,7 +4884,7 @@

Ruleset Java EE Apps

-

Ruleset Reporting

+

9.6. Ruleset Reporting

DRAFT

TBD? @@ -4905,14 +4905,14 @@

Ruleset Reporting

A core ruleset to provide support for XML files.

-

Metadata

+

9.6.1. Metadata

ID: xml Graph prefix: xml

-

Rule providers

+

9.6.2. Rule providers

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

@@ -4979,7 +4979,7 @@

Rule providers

-

Models

+

9.6.3. Models

_Subclasses of WindupVertexFrame.

@@ -5001,20 +5001,20 @@

Models

-

Configuration

+

9.6.4. Configuration

_Subclasses of TODO

-

Reports

+

9.6.5. Reports

Report files or report parts created by this ruleset.

-

Windup Models

+

9.7. Windup Models

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

@@ -5027,7 +5027,7 @@

Windup Models

Windup Models Graphic

-

Meta Models

+

9.7.1. Meta Models

  • @@ -5040,26 +5040,26 @@

    Meta Models

-

Core Models

+

9.7.2. Core Models

FileModel ArchiveModel

-

Reporting Models

+

9.7.3. Reporting Models

-

Custom Models (coming from Addons)

+

9.7.4. Custom Models (coming from Addons)

See respective ruleset’s documentation.

-

Create Java Queries

+

9.8. Create Java Queries

-

Query for all frames of some Model

+

9.8.1. Query for all frames of some Model

Query.find(FileModel.class).as("result")
@@ -5067,7 +5067,7 @@

Query for all frames of some Model<

-

Query by property

+

9.8.2. Query by property

Query.find(FileModel.class)
@@ -5077,7 +5077,7 @@ 

Query by property

-

Gremlin query

+

9.8.3. Gremlin query

code,java
@@ -5092,7 +5092,7 @@ 

Gremlin query

-

Custom query

+

9.8.4. Custom query

The Query API is just a convenience implementation. For a custom query, implement your own GraphCondition:

@@ -5111,16 +5111,16 @@

Custom query

-

Rules Metadata

+

9.9. Rules Metadata

-

Overview

+

9.9.1. Overview

Draft

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

-

Metadata used by Windup

+

9.9.2. Metadata used by Windup

To control ordering, override getExecuteAfter() and getExecuteBefore().

@@ -5174,7 +5174,7 @@

Metadata used by Windup

-

How to define rule metadata

+

9.9.3. How to define rule metadata

The RuleMetadata is defined using the .withMetadata(Object key, Object value).

@@ -5205,7 +5205,7 @@

How to define rule metadata

-
Why a Map?
+
9.9.3.1. 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.

@@ -5215,7 +5215,7 @@
Why a Map?
-

Ruleset metadata

+

9.9.4. Ruleset metadata

Ruleset metadata cover the whole Ruleset, not individual rules. For ruleset metadata, unlike rules, Windup uses a type-safe interface WindupRulesetMetadata @@ -5227,7 +5227,7 @@

Ruleset metadata

-

Rules Operations

+

9.10. Rules Operations

A list of high-level operations across rulesets.

@@ -5279,12 +5279,12 @@

Rules Operations

-

Debugging and Troubleshooting

+

10. Debugging and Troubleshooting

-

Debugging and Profiling

+

10.1. Debugging and Profiling

-

Debug the Windup Distribution Runtime

+

10.1.1. Debug the Windup Distribution Runtime

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

@@ -5311,13 +5311,13 @@

Debug the Windup Distribution Ru

-

Debug a Test Using NetBeans

+

10.1.2. Debug a Test Using NetBeans

Click the Debug Test File button, or choose MenuDebugDebug Test File.

-

Profile a Test Using NetBeans

+

10.1.3. Profile a Test Using NetBeans

  1. @@ -5359,7 +5359,7 @@

    Profile a Test Using NetBeans

-

Profile Forge Runtime Using YourKit

+

10.1.4. Profile Forge Runtime Using YourKit

  1. @@ -5391,9 +5391,9 @@

    Profile Forge Runtime Using YourKi

-

Troubleshoot Windup Issues

+

10.2. Troubleshoot Windup Issues

-

Logging

+

10.2.1. Logging

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

@@ -5402,7 +5402,7 @@

Logging

-

Debugging Exceptions

+

10.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 @@ -5413,27 +5413,27 @@

Debugging Exceptions

-

Classloading Problems

+

10.2.3. Classloading Problems

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

-

Wiki and Product Documentation

+

10.2.4. Wiki and Product Documentation

-

About the Windup Wiki

+

10.3. About the Windup Wiki

-

Purpose

+

10.3.1. Purpose

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

-

Areas of Interest

+

10.3.2. Areas of Interest

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

@@ -5455,13 +5455,13 @@

Areas of Interest

-

Markdown, AsciiDoc, or…​?

+

10.3.3. Markdown, AsciiDoc, or…​?

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

-

Contributor Guidelines

+

10.3.4. Contributor Guidelines

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

@@ -5519,7 +5519,7 @@

Contributor Guidelines

-

Add Images to the Windup Wiki

+

10.4. Add Images to the Windup Wiki

  • @@ -5610,7 +5610,7 @@

    Add Images to the Windup Wiki

-

Create Windup JavaDoc

+

10.5. Create Windup JavaDoc

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

@@ -5646,9 +5646,9 @@

Create Windup JavaDoc

-

Windup Documentation Process

+

10.6. Windup Documentation Process

-

Wiki Documentation

+

10.6.1. Wiki Documentation

  • @@ -5661,7 +5661,7 @@

    Wiki Documentation

-

Product Documentation

+

10.6.2. Product Documentation

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

@@ -5673,7 +5673,7 @@

Product Documentation

-

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

+

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

  • @@ -5760,10 +5760,10 @@

    Publish the HTML doc

-

Additional Resources

+

11. Additional Resources

-

Review the Windup Quickstarts

+

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

@@ -5771,7 +5771,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

+

11.1.1. Download the Latest ZIP

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

@@ -5780,7 +5780,7 @@

Download the Latest ZIP

-

Fork and Clone the GitHub Project

+

11.1.2. Fork and Clone the GitHub Project

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

@@ -5826,15 +5826,15 @@

Fork and Clone the GitHub Project

-

Known Windup Issues

+

11.2. Known Windup Issues

Windup known issues are tracked here: Open Windup issues

-

Glossary of Terms Used in Windup

+

11.3. Glossary of Terms Used in Windup

-

Rules Terms

+

11.3.1. Rules Terms

Rule
@@ -5897,7 +5897,7 @@

Rules Terms

-

Reporting Terms

+

11.3.2. Reporting Terms

Lift and Shift (Level of effort)
@@ -5925,7 +5925,7 @@

Reporting Terms

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

Windup Rules Development Guide

Table of Contents
@@ -492,14 +492,14 @@

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?

+

1.1. What is Windup?

Windup Logo

@@ -514,13 +514,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 +560,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 +701,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,7 +709,7 @@

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

@@ -718,7 +718,7 @@

Discovery Phase

-

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 +727,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 +753,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 +822,7 @@

How can you help?

- +
  • @@ -867,12 +867,12 @@
-

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 +894,7 @@

Create a JIRA Account

-

Create a JIRA Issue

+

1.5.2. Create a JIRA Issue

  1. @@ -953,7 +953,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 +971,10 @@

About the WINDUP_HOME Variable

-

Get Started

+

2. Get Started

-

Install Windup

+

2.1. Install Windup

  1. @@ -1000,9 +1000,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 +1067,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 +1108,7 @@

Start Windup

-

Run the windup-migrate-app Command

+

2.2.3. Run the windup-migrate-app Command

  1. @@ -1191,7 +1191,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 +1213,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,12 +1224,12 @@

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.

-
Source Code Example
+
2.2.6.1. Source Code Example

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

@@ -1240,7 +1240,7 @@
Source Code Example
-
Archive Example
+
2.2.6.2. Archive Example

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

@@ -1251,7 +1251,7 @@
Archive Example
-
Windup Batch Example
+
2.2.6.3. Windup Batch Example

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

@@ -1263,7 +1263,7 @@
Windup Batch Example
-
Windup Quickstart Examples
+
2.2.6.4. Windup Quickstart Examples

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

@@ -1274,9 +1274,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,7 +1309,7 @@

About the Report

-

Open the Report

+

2.3.2. Open the Report

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

@@ -1321,9 +1321,9 @@

Open the Report

-

Report Sections

+

2.3.3. Report Sections

-
Application Report Page
+
2.3.3.1. Application Report Page

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

@@ -1345,7 +1345,7 @@
Application Report Page
-
Archive Analysis Sections
+
2.3.3.2. Archive Analysis Sections

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

@@ -1408,7 +1408,7 @@
Archive Analysis Sections
-
File Analysis Pages
+
2.3.3.3. File Analysis Pages

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

@@ -1437,12 +1437,12 @@
File Analysis Pages
-

Additional Reports

+

2.3.4. Additional Reports

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

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

@@ -1451,13 +1451,13 @@
Rule Provider Execution Report
-
Rule Provider Execution Report
+
2.3.4.2. Rule Provider Execution Report

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

-
Individual File Analysis Reports
+
2.3.4.3. 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.

@@ -1470,15 +1470,15 @@
Individual File Analysis Reports
-

Configure Your System for Java-based Rules

+

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

+

3.1. Install and Configure Maven

-

Download and Install Maven

+

3.1.1. 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 @@ -1504,7 +1504,7 @@

Download and Install Maven

-

Configure the Maven Installation in Your IDE

+

3.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 @@ -1538,7 +1538,7 @@

Configure the Maven Insta

-

Configure Maven to Build Windup

+

3.1.3. Configure Maven to Build Windup

Windup uses artifacts located in the JBoss Nexus @@ -1604,10 +1604,10 @@

Configure Maven to Build Windup

-

Understand the Rule Processing

+

4. Understand the Rule Processing

-

Windup Processing Overview

+

4.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,7 +1615,7 @@

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

+

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

@@ -1624,7 +1624,7 @@

Discovery Phase

-

Application Migration

+

4.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 +1633,7 @@

Application Migration

-

Generate Findings Based on the Rule Execution Results

+

4.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,9 +1659,9 @@

Generate Findi

-

Rule Execution Lifecycle

+

4.2. Rule Execution Lifecycle

-

Rule Lifecycle

+

4.2.1. Rule Lifecycle

Windup executes each rule in sequential order. The following sections describe the phases of rule execution and how rules may specify @@ -1675,7 +1675,7 @@

Rule Lifecycle

-

Rule Phases

+

4.2.2. Rule Phases

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

Rule Phases

-

Execute Before and Execute After

+

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

Execute Before and Execute After

-

Rule Story Points

+

4.3. Rule Story Points

-

What are Story Points?

+

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

+

4.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 +1868,17 @@

How to Estimate Story Points in

-

Create and Test Java Rule Addons

+

5. Create and Test Java Rule Addons

-

Java-based Rule Structure

+

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

+

5.1.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 +1930,7 @@

Windup Rule Provider

-

Add Rule Code Structure

+

5.1.2. Add Rule Code Structure

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

@@ -1949,7 +1949,7 @@

Add Rule Code Structure

and some others, all of which are optional.

-
when()
+
5.1.2.1. when()
.when(Query.fromType(XmlMetaFacetModel.class))
@@ -1972,7 +1972,7 @@
when()
-
perform()
+
5.1.2.2. perform()
.perform(
@@ -1999,7 +1999,7 @@ 
perform()
(Iteration).

-
Iteration
+
5.1.2.2.1. Iteration
.perform(
@@ -2021,13 +2021,13 @@ 
Iteration
-
Nested iterations
+
5.1.2.2.2. Nested iterations

TODO

-
otherwise
+
5.1.2.2.3. otherwise

Windup rules inherit the rule constructs from OCP Rewrite. For example, .otherwise() Gives you a chance to perform something in case the @@ -2050,13 +2050,13 @@

otherwise
-
Where
+
5.1.2.3. Where

TODO

-
Metadata
+
5.1.2.4. Metadata

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

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

Available utilities

+

5.1.3. Available utilities

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

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

Available utilities

-

Basic Rule Execution Flow Patterns

+

5.2. Basic Rule Execution Flow Patterns

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

-

operation(); - single operation

+

5.2.1. operation(); - single operation

When no iteration or condition is needed.

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

operation(); - single operation

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2123,7 +2123,7 @@ 

if( …​ ){ operat

-

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

+

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

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

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

for( FooModel.class ){ …R

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2169,7 +2169,7 @@ 

if( …​ ){ for( …​

-

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

+

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

return ConfigurationBuilder.begin()
@@ -2196,7 +2196,7 @@ 

for( …​ ){ if( …&#

-

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

+

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

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

for( …​ ){ for( …​ )

-

Create a Basic Java-based Rule Add-on

+

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

+

5.3.1. Prerequisites

  • @@ -2248,9 +2248,9 @@

    Prerequisites

-

Create a Rule Add-on

+

5.3.2. Create a Rule Add-on

-
Create a Maven Project
+
5.3.2.1. Create a Maven Project

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

@@ -2414,7 +2414,7 @@
Create a Maven Project
-
Create the Java RuleProvider
+
5.3.2.2. Create the Java RuleProvider
  1. @@ -2526,7 +2526,7 @@
    Create the Java RuleProvider
-

Install the Java-based Rule Add-on

+

5.3.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 +2555,7 @@

Install the Java-based Rule Add-on<

-

Test the Java-based Rule Add-on

+

5.3.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 +2580,7 @@

Test the Java-based Rule Add-on

-

Review the Output Report

+

5.3.5. Review the Output Report

  1. @@ -2682,15 +2682,15 @@

    Review the Output Report

-

Create and Test XML Rules

+

6. Create and Test XML Rules

-

Create a Basic XML Rule

+

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

-

Prerequisites

+

6.1.1. Prerequisites

  • @@ -2725,7 +2725,7 @@

    Prerequisites

-

Create a Rule

+

6.1.2. Create a Rule

The following is an example of an XML rule.

@@ -2779,7 +2779,7 @@

Create a Rule

-
Create the XML Rule
+
6.1.2.1. 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!

@@ -2859,7 +2859,7 @@
Create the XML Rule
-

Add the Rule to Windup

+

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

@@ -2883,7 +2883,7 @@

Add the Rule to Windup

-

Test the XML Rule

+

6.1.4. Test the XML Rule

@@ -2923,12 +2923,12 @@

Test the XML Rule

-

Review the Report

+

7. Review the Report

-

Review the Report

+

7.1. Review the Report

-

About the Report

+

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

About the Report

-

Open the Report

+

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

@@ -2973,9 +2973,9 @@

Open the Report

-

Report Sections

+

7.1.3. Report Sections

-
Application Report Page
+
7.1.3.1. Application Report Page

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

@@ -2997,7 +2997,7 @@
Application Report Page
-
Archive Analysis Sections
+
7.1.3.2. Archive Analysis Sections

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

@@ -3060,7 +3060,7 @@
Archive Analysis Sections
-
File Analysis Pages
+
7.1.3.3. File Analysis Pages

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

@@ -3089,12 +3089,12 @@
File Analysis Pages
-

Additional Reports

+

7.1.4. Additional Reports

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

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

@@ -3103,13 +3103,13 @@
Rule Provider Execution Report
-
Rule Provider Execution Report
+
7.1.4.2. Rule Provider Execution Report

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

-
Individual File Analysis Reports
+
7.1.4.3. 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.

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

External Rule Examples

+

8. External Rule Examples

-

Review the Windup Quickstarts

+

8.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 +3133,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

+

8.1.1. Download the Latest ZIP

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

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

Download the Latest ZIP

-

Fork and Clone the GitHub Project

+

8.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 +3190,12 @@

Fork and Clone the GitHub Project

-

Debugging and Troubleshooting

+

9. Debugging and Troubleshooting

-

Debugging and Profiling

+

9.1. Debugging and Profiling

-

Debug the Windup Distribution Runtime

+

9.1.1. Debug the Windup Distribution Runtime

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

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

Debug the Windup Distribution Ru

-

Debug a Test Using NetBeans

+

9.1.2. Debug a Test Using NetBeans

Click the Debug Test File button, or choose MenuDebugDebug Test File.

-

Profile a Test Using NetBeans

+

9.1.3. Profile a Test Using NetBeans

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

    Profile a Test Using NetBeans

-

Profile Forge Runtime Using YourKit

+

9.1.4. Profile Forge Runtime Using YourKit

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

    Profile Forge Runtime Using YourKi

-

Troubleshoot Windup Issues

+

9.2. Troubleshoot Windup Issues

-

Logging

+

9.2.1. Logging

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

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

Logging

-

Debugging Exceptions

+

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

Debugging Exceptions

-

Classloading Problems

+

9.2.3. Classloading Problems

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

@@ -3334,12 +3334,12 @@

Classloading Problems

-

Additional Resources

+

10. Additional Resources

-

Available Rule Utilities

+

10.1. Available Rule Utilities

-

Programmatically Access the Graph

+

10.1.1. Programmatically Access the Graph

Note: Needs update. This is out of date!

@@ -3350,13 +3350,13 @@

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

-
Query the graph
+
10.1.1.1. Query the graph

There are several ways - including Query API, Gremlin support, or GraphService methods.

-
Query the Graph Within the .when() method
+
10.1.1.1.1. Query the Graph Within the .when() method

Building a rule contains the method when(), which is used to create a condition. Vertices that fulfill the condition, are passed to the @@ -3390,7 +3390,7 @@

Query the Graph Within the .whe
-
Iteration
+
10.1.1.1.2. Iteration
ConfigurationBuilder.begin().addRule()
@@ -3405,7 +3405,7 @@ 
Iteration
-
Nested Iteration
+
10.1.1.1.3. Nested Iteration
code,java
@@ -3433,7 +3433,7 @@ 
Nested Iteration
-

Modify Graph Data

+

10.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 +3463,7 @@

Modify Graph Data

-

Review the Windup Quickstarts

+

10.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 +3471,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

+

10.2.1. Download the Latest ZIP

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

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

Download the Latest ZIP

-

Fork and Clone the GitHub Project

+

10.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 +3526,15 @@

Fork and Clone the GitHub Project<

-

Known Windup Issues

+

10.3. Known Windup Issues

Windup known issues are tracked here: Open Windup issues

-

Glossary of Terms Used in Windup

+

10.4. Glossary of Terms Used in Windup

-

Rules Terms

+

10.4.1. Rules Terms

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

Rules Terms

-

Reporting Terms

+

10.4.2. Reporting Terms

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

Reporting Terms

-

Appendix

+

11. Appendix

-

Windup Architectural Components

+

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

Windup Architectural Components

familiar with them.

-

Forge

+

11.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 +3642,7 @@

Forge

-

Forge Furnace

+

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

Forge Furnace

-

TinkerPop

+

11.1.3. TinkerPop

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

-

Titan

+

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

+

11.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 +3677,7 @@

Frames

-

Gremlin

+

11.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 +3686,7 @@

Gremlin

-

Blueprints

+

11.1.7. Blueprints

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

Blueprints

-

Pipes

+

11.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 +3702,14 @@

Pipes

-

Rexster

+

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

+

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

OCPsoft Rewrite

-

Dependencies (Forge add-ons)

+

11.2. Dependencies (Forge add-ons)

DRAFT

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

Dependencies (Forge add-ons)

discussion.

-

Maven Add-on Structure

+

11.2.1. Maven Add-on Structure

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

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

Maven Add-on Structure

-

Add-on sub-parts

+

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

Add-on sub-parts

-

Test dependencies

+

11.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 +3852,7 @@

Test dependencies

-

Dependencies between sub-parts within the same add-on

+

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

Dependencies bet

-

Windup Models

+

11.3. Windup Models

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

@@ -3883,7 +3883,7 @@

Windup Models

Windup Models Graphic

-

Meta Models

+

11.3.1. Meta Models

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

    Meta Models

-

Core Models

+

11.3.2. Core Models

FileModel ArchiveModel

-

Reporting Models

+

11.3.3. Reporting Models

-

Custom Models (coming from Addons)

+

11.3.4. Custom Models (coming from Addons)

See respective ruleset’s documentation.

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

Custom Models (coming from Addons) diff --git a/html/WindupUserGuide.html b/html/WindupUserGuide.html index 4f3e9913a4..11cfeb12c0 100644 --- a/html/WindupUserGuide.html +++ b/html/WindupUserGuide.html @@ -415,29 +415,29 @@

Windup User Guide

-

Overview

+

1. Overview

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

-

What is Windup?

+

1.1. What is Windup?

Windup Logo

@@ -467,13 +467,13 @@

What is Windup?

migrating from other containers to JBoss EAP a piece of cake.

-

Windup 2.0 vs. Windup 0.7.x

+

1.1.1. Windup 2.0 vs. Windup 0.7.x

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

-

How Does Windup Simplify Migration?

+

1.1.2. How Does Windup Simplify Migration?

Windup looks for common resources and highlight technologies and known “trouble spots” in migrating applications. The goal of Windup is to provide a @@ -513,14 +513,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

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

@@ -662,7 +662,7 @@

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

@@ -671,7 +671,7 @@

Discovery Phase

-

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.

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

@@ -706,9 +706,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!

@@ -775,7 +775,7 @@

How can you help?

- +
  • @@ -820,12 +820,12 @@
-

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.

@@ -847,7 +847,7 @@

Create a JIRA Account

-

Create a JIRA Issue

+

1.5.2. Create a JIRA Issue

  1. @@ -906,7 +906,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.

@@ -924,10 +924,10 @@

About the WINDUP_HOME Variable

-

Run Windup

+

2. Run Windup

-

Install Windup

+

2.1. Install Windup

  1. @@ -953,9 +953,9 @@

    Install Windup

-

Execute Windup

+

2.2. Execute Windup

-

Prerequisites

+

2.2.1. Prerequisites

Before you begin, you must gather the following information.

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

@@ -1061,7 +1061,7 @@

Start Windup

-

Run the windup-migrate-app Command

+

2.2.3. Run the windup-migrate-app Command

  1. @@ -1144,7 +1144,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.

@@ -1166,7 +1166,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:

@@ -1177,12 +1177,12 @@

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.

-
Source Code Example
+
2.2.6.1. Source Code Example

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

@@ -1193,7 +1193,7 @@
Source Code Example
-
Archive Example
+
2.2.6.2. Archive Example

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

@@ -1204,7 +1204,7 @@
Archive Example
-
Windup Batch Example
+
2.2.6.3. Windup Batch Example

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

@@ -1216,7 +1216,7 @@
Windup Batch Example
-
Windup Quickstart Examples
+
2.2.6.4. Windup Quickstart Examples

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

@@ -1227,9 +1227,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:

@@ -1262,7 +1262,7 @@

About the Report

-

Open the Report

+

2.3.2. Open the Report

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

@@ -1274,9 +1274,9 @@

Open the Report

-

Report Sections

+

2.3.3. Report Sections

-
Application Report Page
+
2.3.3.1. Application Report Page

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

@@ -1298,7 +1298,7 @@
Application Report Page
-
Archive Analysis Sections
+
2.3.3.2. Archive Analysis Sections

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

@@ -1361,7 +1361,7 @@
Archive Analysis Sections
-
File Analysis Pages
+
2.3.3.3. File Analysis Pages

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

@@ -1390,12 +1390,12 @@
File Analysis Pages
-

Additional Reports

+

2.3.4. Additional Reports

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

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

@@ -1404,13 +1404,13 @@
Rule Provider Execution Report
-
Rule Provider Execution Report
+
2.3.4.2. Rule Provider Execution Report

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

-
Individual File Analysis Reports
+
2.3.4.3. 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.

@@ -1423,10 +1423,10 @@
Individual File Analysis Reports
-

Additional Resources

+

3. Additional Resources

-

Review the Windup Quickstarts

+

3.1. Review the Windup Quickstarts

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

@@ -1434,7 +1434,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

+

3.1.1. Download the Latest ZIP

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

@@ -1443,7 +1443,7 @@

Download the Latest ZIP

-

Fork and Clone the GitHub Project

+

3.1.2. Fork and Clone the GitHub Project

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

@@ -1489,15 +1489,15 @@

Fork and Clone the GitHub Project

-

Known Windup Issues

+

3.2. Known Windup Issues

Windup known issues are tracked here: Open Windup issues

-

Glossary of Terms Used in Windup

+

3.3. Glossary of Terms Used in Windup

-

Rules Terms

+

3.3.1. Rules Terms

Rule
@@ -1560,7 +1560,7 @@

Rules Terms

-

Reporting Terms

+

3.3.2. Reporting Terms

Lift and Shift (Level of effort)
@@ -1584,7 +1584,7 @@

Reporting Terms

-

Windup Architectural Components

+

3.4. 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 @@ -1592,7 +1592,7 @@

Windup Architectural Components

familiar with them.

-

Forge

+

3.4.1. Forge

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

Forge

-

Forge Furnace

+

3.4.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 @@ -1609,21 +1609,21 @@

Forge Furnace

-

TinkerPop

+

3.4.3. TinkerPop

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

-

Titan

+

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

+

3.4.5. Frames

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

Frames

-

Gremlin

+

3.4.6. Gremlin

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

Gremlin

-

Blueprints

+

3.4.7. Blueprints

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

Blueprints

-

Pipes

+

3.4.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: @@ -1660,14 +1660,14 @@

Pipes

-

Rexster

+

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

+

3.4.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 @@ -1680,7 +1680,7 @@

OCPsoft Rewrite

diff --git a/scripts/windupDocPublish.sh b/scripts/windupDocPublish.sh index 42d8847497..396889e89f 100755 --- a/scripts/windupDocPublish.sh +++ b/scripts/windupDocPublish.sh @@ -2,11 +2,11 @@ if [ "$1" == "" ] || [ "$2" == "" ] || [ "$3" == "" ]; then echo "You must pass the following arguments on the command line:" - echo " Path to the local windup-documentation GitHub directory" - echo " Path to the local windup source GitHub directory" - echo " Name of the new beta version" + echo " arg 1: Path to the local windup-documentation GitHub directory" + echo " arg 2: Path to the local windup source GitHub directory" + echo " arg 3: New documentation version" echo "For example:" - echo " scripts/windupDocPublish.sh ~/GitRepos/windup-documentation/ ~/GitRepos/windup/ 2.0.0.Beta8" + echo " scripts/windupDocPublish.sh ~/GitRepos/windup-documentation/ ~/GitRepos/windup/ 2.0.0.Final" exit else echo "Windup Documentation will be copied from here: " $1 @@ -54,6 +54,13 @@ echo " git push origin HEAD" echo " (issue a pull and verify)" echo " git push upstream gh-pages" echo " firefox http://windup.github.io/windup/docs/$WINDUP_VERSION/html/WindupUserGuide.html" +echo " unlink latest" +echo " ln -s $3 latest" +echo " git add latest" +echo " git commit -m 'Replace symlink for latest to point to 2.0.0.Final'" +echo " git push origin HEAD" +echo " (issue a pull and verify)" +echo " git push upstream gh-pages" # git push origin HEAD ## issue a pull and verify @@ -62,3 +69,15 @@ echo " firefox http://windup.github.io/windup/docs/$WINDUP_VERSION/html/Windu cd $1 +## Update the symlink to point to the latest docs +# cd $2/docs +# unlink latest +# ln -s $3 latest +## for example: ln -s 2.0.0.Final latest +# git add latest +# git commit -m 'Replace symlink for latest to point to 2.0.0.Final' +# git push origin HEAD +## issuw a pull and verify +# git push upstream gh-pages + +