Improve "Add explicit Common Annotations dependencies" in "Migrate to Java 11" (#816)

* Proper AddCommonAnnotationsDependencies implementation

* Add test

* Polish

* Polish

* Polish

* Add a new separate test instead of expanding the documentation example

* Only add the classpath dependency to the new test that needs it

* Shorted comment

* Inline the now dependency only `UpdateJakartaAnnotations2`

---------

Co-authored-by: Tim te Beek <tim@moderne.io>

Author: jevanlingen

build.gradle.kts

@@ -12,6 +12,7 @@ recipeDependencies {
     parserClasspath("jakarta.servlet:jakarta.servlet-api:6.0.0")
     parserClasspath("javax.persistence:javax.persistence-api:2.2")
     parserClasspath("org.glassfish:javax.servlet:3.0")
+    parserClasspath("javax.annotation:javax.annotation-api:1.3.2")
 }
 
 val rewriteVersion = rewriteRecipe.rewriteVersion.get()

src/main/resources/META-INF/rewrite/add-common-annotations-dependencies.yml

@@ -26,13 +26,16 @@ tags:
   - jsr250
   - jakarta
 recipeList:
-  # Add or update the jakarta.annotation-api to a maven project. This artifact still uses the javax.annotation name space.
+  # Add or update the jakarta.annotation-api. Use version 1.3.x, as this version still kept the old javax namespace (starting from 2.x it's changed to jakarta).
   - org.openrewrite.java.dependencies.ChangeDependency:
       oldGroupId: javax.annotation
       oldArtifactId: javax.annotation-api
       newGroupId: jakarta.annotation
       newArtifactId: jakarta.annotation-api
       newVersion: 1.3.x
+      # set explicitly even if  managed, as higher versions do not have the javax namespace
+      overrideManagedVersion: true
+      changeManagedDependency: false
   # Jakarta EE recommends `provided` scope
   - org.openrewrite.maven.ChangeDependencyScope:
       groupId: jakarta.annotation

src/main/resources/META-INF/rewrite/classpath.tsv.zip

@@ -57,12 +57,15 @@ tags:
   - jakarta
 # NOTE: The spec versions in this section comes from https://github.com/jakartaee/jakartaee-api/blob/10.0.0/pom.xml
 recipeList:
-  - org.openrewrite.java.migrate.jakarta.UpdateJakartaAnnotations2
   - org.openrewrite.java.migrate.jakarta.UpdateJakartaXmlWsEE10
   - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
       groupId: jakarta.activation
       artifactId: jakarta.activation-api
       newVersion: 2.1.x
+  - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
+      groupId: jakarta.annotation
+      artifactId: jakarta.annotation-api
+      newVersion: 2.1.x
   - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
       groupId: jakarta.authentication
       artifactId: jakarta.authentication-api
@@ -386,22 +389,6 @@ recipeList:
       newVersion: 10.0.0
 ---
 type: specs.openrewrite.org/v1beta/recipe
-name: org.openrewrite.java.migrate.jakarta.UpdateJakartaAnnotations2
-displayName: Update Jakarta EE annotation Dependencies to 2.1.x.
-description: Update Jakarta EE annotation Dependencies to 2.1.x.
-recipeList:
-  - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
-      groupId: jakarta.annotation
-      artifactId: jakarta.annotation-api
-      newVersion: 2.1.x
-  - org.openrewrite.java.ChangeType:
-      oldFullyQualifiedTypeName: javax.annotation.Nullable
-      newFullyQualifiedTypeName: jakarta.annotation.Nullable
-  - org.openrewrite.java.ChangeType:
-      oldFullyQualifiedTypeName: javax.annotation.Nonnull
-      newFullyQualifiedTypeName: jakarta.annotation.Nonnull
----
-type: specs.openrewrite.org/v1beta/recipe
 name: org.openrewrite.java.migrate.jakarta.UpdateJakartaXmlWsEE10
 displayName: Update Jakarta EE XML Web Services Dependencies for EE 10.
 description: Update Jakarta EE XML Web Services Dependencies for EE 10.

src/main/resources/META-INF/rewrite/jakarta-ee-10.yml

@@ -64,7 +64,7 @@ recipeList:
   - org.openrewrite.java.migrate.jakarta.ApplicationPathWildcardNoLongerAccepted
   - org.openrewrite.java.migrate.jakarta.UpdateApacheWSSecurityPackages
   - org.openrewrite.java.migrate.jakarta.JavaxEEApiToJakarta
-  - org.openrewrite.java.migrate.jakarta.RemoveJakartaAnnotationDependency
+  - org.openrewrite.java.migrate.jakarta.RemoveJakartaAnnotationDependencyWhenManagedBySpringBoot
 
 ---
 type: specs.openrewrite.org/v1beta/recipe
@@ -1079,10 +1079,11 @@ recipeList:
       newVersion: 9.1.0
 ---
 type: specs.openrewrite.org/v1beta/recipe
-name: org.openrewrite.java.migrate.jakarta.RemoveJakartaAnnotationDependency
+name: org.openrewrite.java.migrate.jakarta.RemoveJakartaAnnotationDependencyWhenManagedBySpringBoot
 displayName: Remove `jakarta.annotation-api` dependency when managed by Spring Boot
-description: Counteract the `jakarta.annotation-api` added by `org.openrewrite.java.migrate.javax.AddCommonAnnotationsDependencies` for Spring Boot applications.
+description: Best practice recipe to cleanup a direct dependency which also comes transitively for Spring Boot applications.
 preconditions:
+  # TODO: This recipe can be broadened by checking if `jakarta.annotation-api` is transitively on the classpath OR move this recipe to be part of org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0 recipe.
   - org.openrewrite.java.migrate.jakarta.HasNoJakartaAnnotations
   - org.openrewrite.java.dependencies.DependencyInsight:
       groupIdPattern: org.springframework.boot

src/main/resources/META-INF/rewrite/jakarta-ee-9.yml

@@ -62,6 +62,8 @@ recipeList:
   - org.openrewrite.java.migrate.lang.SwitchCaseAssignmentsToSwitchExpression
   - org.openrewrite.java.migrate.lang.SwitchCaseReturnsToSwitchExpression
   - org.openrewrite.java.migrate.lang.SwitchExpressionYieldToArrow
+  - org.openrewrite.java.migrate.UpdateJakartaAnnotationsIfForJavax
+  - org.openrewrite.java.migrate.UpdateJakartaAnnotationsIfExistsForJakarta
 
 ---
 type: specs.openrewrite.org/v1beta/recipe
@@ -326,3 +328,29 @@ recipeList:
       groupId: org.projectlombok
       artifactId: lombok-mapstruct-binding
       version: 0.2.0
+
+---
+# The scanning phase comes before the editing phase, therefor we check if a javax.annotation dependency is on the classpath (with whatever version)
+type: specs.openrewrite.org/v1beta/recipe
+name: org.openrewrite.java.migrate.UpdateJakartaAnnotationsIfForJavax
+displayName: Update `jakarta.annotation-api` dependency if it exists
+description: Counteract the `jakarta.annotation-api` by updating to `jakarta` namespace
+preconditions:
+  - org.openrewrite.java.dependencies.search.ModuleHasDependency:
+      groupIdPattern: javax.annotation
+      artifactIdPattern: javax.annotation-api
+recipeList:
+  - org.openrewrite.java.migrate.jakarta.JavaxAnnotationMigrationToJakartaAnnotation
+
+---
+type: specs.openrewrite.org/v1beta/recipe
+name: org.openrewrite.java.migrate.UpdateJakartaAnnotationsIfExistsForJakarta
+displayName: Update `jakarta.annotation-api` dependency if it exists
+description: Counteract the `jakarta.annotation-api` by updating to `jakarta` namespace
+preconditions:
+  - org.openrewrite.java.dependencies.search.ModuleHasDependency:
+      groupIdPattern: jakarta.annotation
+      artifactIdPattern: jakarta.annotation-api
+      version: 1.3.x
+recipeList:
+  - org.openrewrite.java.migrate.jakarta.JavaxAnnotationMigrationToJakartaAnnotation