diff --git a/docs/guides/openrewrite-recipe.md b/docs/guides/openrewrite-recipe.md new file mode 100644 index 0000000000..019b002e9a --- /dev/null +++ b/docs/guides/openrewrite-recipe.md @@ -0,0 +1,114 @@ +--- +layout: default +title: OpenRewrite Migration +parent: Guides +nav_order: 5 +--- + +# OpenRewrite Migration + +{: .fs-9 } + +Migrate a Querydsl project to fluentQ automatically with [OpenRewrite](https://docs.openrewrite.org/). +{: .fs-6 .fw-300 } + +--- + +fluentQ publishes an OpenRewrite recipe artifact, **`{{ site.group_id }}:fluentq-rewrite`**, that +rewrites a downstream project from Querydsl to fluentQ — no hand-editing of imports or coordinates. + +## What it does + +The recipe `io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ`: + +- Renames Java/Kotlin/Scala packages: `com.querydsl.*` and `io.github.openfeign.querydsl.*` → `fluentq.*` + (imports, fully-qualified names, `package` declarations). +- Rewrites Maven coordinates: group id → `{{ site.group_id }}`, artifacts `querydsl-*` → `fluentq-*`, + version → `{{ site.querydsl_version }}` (dependencies, `dependencyManagement`, and the BOM + `querydsl-bom` → `fluentq-bom`). +- Rewrites the build plugin `querydsl-maven-plugin` → `fluentq-maven-plugin`. + +It works for both the original Querydsl (`com.querydsl`) and the OpenFeign fork +(`io.github.openfeign.querydsl`). + +## Maven + +Add the recipe artifact to the `rewrite-maven-plugin` and activate the recipe: + +```xml + + org.openrewrite.maven + rewrite-maven-plugin + 6.42.0 + + + io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ + + + + + {{ site.group_id }} + fluentq-rewrite + {{ site.querydsl_version }} + + + +``` + +```bash +./mvnw rewrite:run +``` + +Or run it once without editing your `pom.xml`: + +```bash +./mvnw -U org.openrewrite.maven:rewrite-maven-plugin:run \ + -Drewrite.recipeArtifactCoordinates={{ site.group_id }}:fluentq-rewrite:{{ site.querydsl_version }} \ + -Drewrite.activeRecipes=io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ +``` + +Use `rewrite:dryRun` instead of `rewrite:run` to preview the diff (written to +`target/rewrite/rewrite.patch`) before applying it. + +## Gradle + +```groovy +plugins { + id("org.openrewrite.rewrite") version("latest.release") +} + +rewrite { + activeRecipe("io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ") +} + +dependencies { + rewrite("{{ site.group_id }}:fluentq-rewrite:{{ site.querydsl_version }}") +} +``` + +```bash +./gradlew rewriteRun # or rewriteDryRun to preview +``` + +## Limitations & manual steps + +- **Annotation processor class in `pom.xml`** — if you configured a processor class by hand the old + way (`com.querydsl.apt.jpa.JPAAnnotationProcessor`), update the package to + `fluentq.apt.*` manually. The recommended `maven-compiler-plugin` + `annotationProcessorPaths` + setup discovers the processor from the `fluentq-apt` artifact and needs no class change. +- **Dropped modules** — `querydsl-jdo`, `querydsl-lucene3/4/5`, and `querydsl-hibernate-search` have + no fluentQ equivalent and are intentionally left untouched. See the + [Migration Guide](../migration.md) for alternatives. +- **Review the result** — always review the diff and run a full build (`mvn clean install`) after the + recipe; regenerate Q-types and confirm your queries compile. + +## Roadmap + +The `fluentq-rewrite` artifact is the home for fluentQ migration recipes. Planned additions: + +- `MigrateMysemaQuerydslToFluentQ` — ancient Querydsl 3 (`com.mysema`) with its older syntax. +- `MigrateJooqToFluentQ` — migrate from jOOQ. +- `MigrateHibernateCriteriaToFluentQ` — migrate from the Hibernate Criteria API. + +Each lives in the same artifact under `META-INF/rewrite/`, so updating the `fluentq-rewrite` +dependency makes new recipes available. diff --git a/docs/migration-8.md b/docs/migration-8.md index 8950df4bce..bf4d165ac3 100644 --- a/docs/migration-8.md +++ b/docs/migration-8.md @@ -77,6 +77,18 @@ Replace imports of legacy packages with the new `fluentq` package structure: --- +## Automated Migration with OpenRewrite + +For a deterministic, repeatable migration, use the published OpenRewrite recipe +`io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ` (artifact +`{{ site.group_id }}:fluentq-rewrite`). It rewrites the Maven coordinates, the Java/Kotlin/Scala +package imports, and the build plugin in one pass, for both Maven and Gradle projects. + +See the [OpenRewrite Migration guide]({{ site.baseurl }}/guides/openrewrite-recipe) for the full +Maven and Gradle setup, the Querydsl 5 variant, and limitations. + +--- + ## Automated Migration with AI / LLM Since this migration is a mechanical rename of dependencies and package prefixes, you can easily use an AI coding assistant (like Gemini or Claude) to automate the process for you. diff --git a/fluentq-tooling/fluentq-rewrite/pom.xml b/fluentq-tooling/fluentq-rewrite/pom.xml new file mode 100644 index 0000000000..842d93ae0f --- /dev/null +++ b/fluentq-tooling/fluentq-rewrite/pom.xml @@ -0,0 +1,76 @@ + + + + 4.0.0 + + + io.github.openfeign.fluentq + fluentq-tooling + 8.0-SNAPSHOT + + fluentq-rewrite + + FluentQ - OpenRewrite recipes + OpenRewrite recipes that migrate projects to fluentQ + + + 3.33.0 + + + + + + org.openrewrite.recipe + rewrite-recipe-bom + ${rewrite-recipe-bom.version} + pom + import + + + + + + + + org.openrewrite + rewrite-java + test + + + + org.openrewrite + rewrite-java-25 + test + + + org.openrewrite + rewrite-maven + test + + + org.openrewrite + rewrite-test + test + + + + + + + org.apache.maven.plugins + maven-jar-plugin + 3.5.0 + + + + fluentq.rewrite + + + + + + + + diff --git a/fluentq-tooling/fluentq-rewrite/src/main/resources/META-INF/rewrite/querydsl.yml b/fluentq-tooling/fluentq-rewrite/src/main/resources/META-INF/rewrite/querydsl.yml new file mode 100644 index 0000000000..5d235ae536 --- /dev/null +++ b/fluentq-tooling/fluentq-rewrite/src/main/resources/META-INF/rewrite/querydsl.yml @@ -0,0 +1,208 @@ +# OpenRewrite recipes migrating Querydsl (and the OpenFeign Querydsl fork) to fluentQ. +# +# Run with the rewrite-maven-plugin or rewrite-gradle-plugin; the engine and the core +# recipes composed below are supplied by the plugin, so no extra dependencies are needed +# beyond this artifact (io.github.openfeign.fluentq:fluentq-rewrite). +--- +type: specs.openrewrite.org/v1beta/recipe +name: io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ +displayName: Migrate Querydsl to fluentQ 8.0 +description: >- + Migrate a project from Querydsl to fluentQ 8.0. Renames the Java/Kotlin/Scala packages + (`com.querydsl` and `io.github.openfeign.querydsl` -> `fluentq`), the Maven coordinates + (group id -> `io.github.openfeign.fluentq`, artifacts `querydsl-*` -> `fluentq-*`, version + `8.0`), and the `fluentq-maven-plugin` coordinates. Works for both the original + `com.querydsl` artifacts and the OpenFeign `io.github.openfeign.querydsl` fork. Annotation + processor classes referenced in source code are renamed by the package change; a processor + class hardcoded in `pom.xml` (legacy apt-maven-plugin style) must be updated by hand. + Modules dropped in the fork + (`querydsl-jdo`, `querydsl-lucene3/4/5`, `querydsl-hibernate-search`) have no fluentQ + equivalent and are intentionally left untouched. +tags: + - querydsl + - fluentq +recipeList: + # --- Java / Kotlin / Scala packages (build-tool agnostic) --- + - org.openrewrite.java.ChangePackage: + oldPackageName: com.querydsl + newPackageName: fluentq + recursive: true + - org.openrewrite.java.ChangePackage: + oldPackageName: io.github.openfeign.querydsl + newPackageName: fluentq + recursive: true + + # --- Maven plugin coordinates --- + - org.openrewrite.maven.ChangePluginGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-maven-plugin + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-maven-plugin + newVersion: 8.0 + + # --- Maven dependency coordinates (querydsl- -> io.github.openfeign.fluentq:fluentq-:8.0) --- + # oldGroupId '*' covers both com.querydsl (original) and io.github.openfeign.querydsl (fork). + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-core + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-core + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-collections + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-collections + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-guava + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-guava + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-jpa + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-jpa + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-jpa-spring + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-jpa-spring + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql-spring + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql-spring + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql-spatial + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql-spatial + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql-json + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql-json + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-spatial + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-spatial + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-mongodb + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-mongodb + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-r2dbc + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-r2dbc + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-kotlin + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-kotlin + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-scala + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-scala + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-apt + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-apt + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-codegen + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-codegen + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-codegen-utils + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-codegen-utils + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql-codegen + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql-codegen + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-jpa-codegen + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-jpa-codegen + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-kotlin-codegen + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-kotlin-codegen + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-ksp-codegen + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-ksp-codegen + newVersion: 8.0 + - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-bom + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-bom + newVersion: 8.0 + + # --- Managed dependencies (, incl. imported BOMs) --- + - org.openrewrite.maven.ChangeManagedDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-bom + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-bom + newVersion: 8.0 + - org.openrewrite.maven.ChangeManagedDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-core + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-core + newVersion: 8.0 + - org.openrewrite.maven.ChangeManagedDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-jpa + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-jpa + newVersion: 8.0 + - org.openrewrite.maven.ChangeManagedDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-sql + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-sql + newVersion: 8.0 + - org.openrewrite.maven.ChangeManagedDependencyGroupIdAndArtifactId: + oldGroupId: '*' + oldArtifactId: querydsl-apt + newGroupId: io.github.openfeign.fluentq + newArtifactId: fluentq-apt + newVersion: 8.0 diff --git a/fluentq-tooling/fluentq-rewrite/src/test/java/fluentq/rewrite/MigrateQuerydslToFluentQTest.java b/fluentq-tooling/fluentq-rewrite/src/test/java/fluentq/rewrite/MigrateQuerydslToFluentQTest.java new file mode 100644 index 0000000000..45d2bb2ab5 --- /dev/null +++ b/fluentq-tooling/fluentq-rewrite/src/test/java/fluentq/rewrite/MigrateQuerydslToFluentQTest.java @@ -0,0 +1,136 @@ +/* + * Copyright 2024, The FluentQ Team (http://www.fluentq.com/team). + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package fluentq.rewrite; + +import static org.openrewrite.java.Assertions.java; +import static org.openrewrite.maven.Assertions.pomXml; + +import org.junit.jupiter.api.Disabled; +import org.junit.jupiter.api.Test; +import org.openrewrite.test.RecipeSpec; +import org.openrewrite.test.RewriteTest; +import org.openrewrite.test.TypeValidation; + +class MigrateQuerydslToFluentQTest implements RewriteTest { + + @Override + public void defaults(RecipeSpec spec) { + spec.recipeFromResources("io.github.openfeign.fluentq.rewrite.MigrateQuerydslToFluentQ") + // Querydsl is not on the test classpath, so referenced types are unattributed; the + // package rename works off the import/qualified names regardless. + .typeValidationOptions(TypeValidation.none()); + } + + @Test + void renamesJavaImportsAndReferences() { + rewriteRun( + java( + """ + import com.querydsl.jpa.impl.JPAQueryFactory; + + class Repo { + JPAQueryFactory factory; + } + """, + """ + import fluentq.jpa.impl.JPAQueryFactory; + + class Repo { + JPAQueryFactory factory; + } + """)); + } + + @Test + @Disabled( + "Enable once fluentQ 8.0 is published to Maven Central. The recipe rewrites to" + + " io.github.openfeign.fluentq:fluentq-*:8.0, which OpenRewrite tries to resolve;" + + " until it is released that resolution 404s and adds a marker comment.") + void renamesOpenFeignForkDependency() { + rewriteRun( + pomXml( + """ + + 4.0.0 + com.example + demo + 1.0 + + + io.github.openfeign.querydsl + querydsl-jpa + 7.0 + + + + """, + """ + + 4.0.0 + com.example + demo + 1.0 + + + io.github.openfeign.fluentq + fluentq-jpa + 8.0 + + + + """)); + } + + @Test + @Disabled( + "Enable once fluentQ 8.0 is published to Maven Central. The recipe rewrites to" + + " io.github.openfeign.fluentq:fluentq-*:8.0, which OpenRewrite tries to resolve;" + + " until it is released that resolution 404s and adds a marker comment.") + void renamesOriginalQuerydslDependency() { + rewriteRun( + pomXml( + """ + + 4.0.0 + com.example + demo + 1.0 + + + com.querydsl + querydsl-core + 5.0.0 + + + + """, + """ + + 4.0.0 + com.example + demo + 1.0 + + + io.github.openfeign.fluentq + fluentq-core + 8.0 + + + + """)); + } +} diff --git a/fluentq-tooling/pom.xml b/fluentq-tooling/pom.xml index fcbe2f107c..4ef7d749f6 100644 --- a/fluentq-tooling/pom.xml +++ b/fluentq-tooling/pom.xml @@ -21,6 +21,7 @@ fluentq-kotlin-codegen fluentq-ksp-codegen fluentq-maven-plugin + fluentq-rewrite fluentq-sql-codegen