Skip to content

README.adoc

Latest commit

 

History

History
207 lines (150 loc) · 8.28 KB

README.adoc

File metadata and controls

207 lines (150 loc) · 8.28 KB
Raw

proprietary-javaee-servlet: Java-based Rule Add-on That Detects Proprietary Servlet Annotations

Author: Ondra Zizka
Level: Beginner
Summary: Windup Java-based rule add-on that reports on Proprietary servlet annotations
Source: https://github.com/windup/windup-quickstarts/

What is it?

In this example, the fictional "Proprietary" corporation provides its own proprietary servlet and filter annotations for dependency injection. If the application uses them, they must be replaced with the standard Java EE 6 annotations. This example demonstrates how to create a Java-based RuleProvider that searches for these proprietary annotations and reports on them.

This Java-based Windup rule add-on searches for the following annotations:

  • @ProprietaryServlet: This is the equivalent of the Java EE 6 @WebServlet annotation.

  • @ProprietaryFilter: This is the equivalent of the Java EE 6 @WebFilter annotation.

  • @ProprietaryInitParam: This is the equivalent of the Java EE 6 @WebInitParam annotation.

These instructions use the following replaceable variables.

  • WINDUP_HOME: Replace this variable with the fully qualified path to your Windup installation.

  • QUICKSTART_HOME: Replace this variable with the fully qualified path to the root directory of this quickstart.

Review the Quickstart Code

The ProprietaryServletAnnotationRuleProvider class extends RuleProvider and overrides the following methods:

  • getExecuteAfter(): Nothing executes after this, so this method returns an empty list.

  • enhanceMetadata(Context context): This method specifies additional metadata about the Rule instances originating from this RuleProvider.

  • getConfiguration(GraphContext context): This method does the following.

  • Adds a rule that looks for com.example.proprietary.servlet.annotation.ProprietaryServlet annotations. If found:

    • Classifies the annotation as "Proprietary @ProprietaryServlet" and provides a link to the Java EE javax.servlet.annotation package Javadoc.

    • Provides a warning text telling the user to replace the proprietary @ProprietaryServlet annotation with the Java EE 6 standard @WebServlet annotation.

    • Assigns 1 story point of effort to this task.

  • Adds a rule that looks for com.example.proprietary.servlet.annotation.ProprietaryInitParam annotations. If found:

    • Classifies the annotation as "Proprietary @ProprietaryInitParam" and provides a link to the Java EE javax.servlet.annotation package Javadoc.

    • Provides a warning text telling the user to replace the proprietary @ProprietaryInitParam annotation with the Java EE 6 standard @WebInitParam annotation.

    • Assigns 2 story points of effort to this task.

  • Adds a rule that looks for com.example.proprietary.servlet.annotation.ProprietaryFilter annotations. If found:

    • Classifies the annotation as "Proprietary @ProprietaryFilter" and provides a link to the Java EE javax.servlet.annotation package Javadoc.

    • Provides a warning text telling the user to replace the proprietary @ProprietaryFilter annotation with the Java EE 6 standard @WebFilter annotation.

    • Assigns 3 story points of effort to this task.

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

System requirements

The rule this project produces is designed to be run on Windup 2.x or later.

This project requires Java 7.0 (Java SDK 1.7) or later and Maven 3.0 or later.

Install Windup

If you have not installed Windup, follow the instructions here: Download and Install Windup.

Configure Maven

If you have not yet installed and configured Maven, follow the instructions here: Install and Configure Maven.

An example settings.xml file is provided in the root directory of the quickstarts.

Build the Quickstart Rule Add-on

Before Windup can use this rule, it must be compiled and added to the local Maven repository.

  1. Open a command prompt and navigate to the QUICKSTART_HOME/rules-java/ directory.

  2. Type the following command to compile the quickstart and install it into the local Maven repository:

    mvn clean install

  3. You should see the message BUILD SUCCESS

Add the Quickstart to Windup

The command to install the rule in Windup uses the Maven GAV (groupId, artifactId, and optional version) to locate the rule in the Maven repository. The command uses the following syntax.

WINDUP_HOME/bin/windup --install GROUP_ID:ARTIFACT_ID[,VERSION]

To find these values, open the QUICKSTART_HOME/rules-java/pom.xml file. These values are located near the beginning of the file.

<groupId>org.jboss.windup.quickstarts</groupId>
<artifactId>windup-proprietary-javaee-servlet-rules-java</artifactId>
<version>2.6.0-SNAPSHOT</version>

Follow these steps to add the rule to Windup.

  1. Open a command prompt and navigate to the WINDUP_HOME directory.

  2. Type the following command, which does not include the optional version.

    bin/windup --install org.jboss.windup.quickstarts:windup-proprietary-javaee-servlet-rules-java

  3. At the following prompt, choose Y.

    Confirm installation [Y/n]? Y

  4. You should see the following result.

    Installation completed successfully.

  5. Type exit to exit the Windup console.

Test the Quickstart Rule

This quickstart provides an example source file containing Proprietary annotations to use when testing the quickstart. It is located in this quickstart’s test-files/src_example/ directory.

The command to test the rule uses this syntax:

WINDUP_HOME/bin/windup [--sourceMode] --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N

To test this quickstart using the test-files/src_example/ folder provided in the root directory of this quickstart, follow these steps.

  1. Open a command prompt and navigate to the WINDUP_HOME directory.

  2. Type the following command to test the rule.

    bin/windup --sourceMode --input QUICKSTART_HOME/test-files/src_example/ --output QUICKSTART_HOME/windup-reports-java/ --target eap --packages org.windup

  3. You should see the following result:

    ***SUCCESS*** Windup report created: QUICKSTART_HOME/windup-reports-java/index.html
              Access it at this URL: file:///QUICKSTART_HOME/windup-reports-java/index.html

Review the Quickstart Report

  1. Open the link to the QUICKSTART_HOME/windup-reports-xml/index.html file in a browser. You are presented with the Application List page.

  2. Click on the src_example link. This takes you to the Report Index page, which provides summary information about findings from the migration analysis.

  3. Under Additional Reports, click on Application Details. This opens the Application Details Report page that shows a total of 12 story points and the list of the relevant files along with warning messages.

  4. Click on each file link to drill down for more information.

Run the Quickstart Arquillian Tests

This quickstart provides Arquillian tests.

  1. Open a command prompt and navigate to the QUICKSTART_HOME/rules-java/ directory.

  2. Type the following command to run the test goal.

    mvn clean test

  3. You should see the following results.

    Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Remove the Quickstart from Windup

You remove the rule from Windup using its Maven GAV (groupId, artifactId, and version).

The command takes the following form:

WINDUP_HOME/bin/windup --remove GROUP_ID:ARTIFACT_ID[,VERSION]

Follow these steps to remove the rule to Windup.

  1. Open a command prompt and navigate to the WINDUP_HOME directory.

  2. Type the following command.

    bin/windup --remove org.jboss.windup.quickstarts:windup-proprietary-javaee-servlet-rules-java

  3. Enter Y to confirm. You should see the following response.

    Uninstallation completed successfully.