Forem: Kosmik

Generating an aerial view of your project with OpenRewrite

Kosmik — Wed, 25 Mar 2026 13:10:52 +0000

Read it in french here

In the previous article, we discussed (well, I wrote, you read) Scanning Recipes when you need complete information to make a decision, or to generate code ex nihilo.

I promised you a little toy at the end... The time has come for the reveal: the Project Graph Generator.

The Need: Mapping Your Code

It’s sometimes difficult to get a global view of the dependencies within your own code. Is this package too tightly coupled to others? What is the central class of my domain? Has my wonderful initial design withstood the ravages of time?

Since OpenRewrite already knows how to build the complete LST of your codebase, it’s not exactly complicated to traverse it to deduce relationships.

This is exactly the goal of the project-graph-generator project: scanning your sources to deduce a dependency graph and produce a simple HTML page using D3.js to display it.

TL;DR;

Oh thou, who doesn’t want to know more, but only wants to play with the graph, go no further than this chapter, you might gain some knowledge!

The project is easily usable via the rewrite-maven-plugin or any other way to trigger an OpenRewrite recipe. Here is the command to launch a complete analysis of your project:

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=io.github.jtama:project-graph-generator:RELEASE \ ①
-Drewrite.activeRecipes=io.github.jtama.openrewrite.ProjectAerialViewGenerator \
-Drewrite.exportDatatables=true

RELEASE = latest

Once the analysis is complete, the plugin generates a standalone HTML file containing the data AND the visualization. Simply open the class-diagram.html file at the root of your project in your browser to explore the web of your architecture.

You can also pass additional options to filter the nodes according to your needs:

maxNodes=20\ Filters for classes with the highest number of incoming connections.
basePackages=com.mycompany\ Forces the target base package
includeTests=true\ Also include test classes.

To learn more 👉 Here is the project repository. Go ahead, it’s open source, use it, fork it, make issues and pull requests!

The Mechanics: Analysis Without Modification

Under the hood, the tool is based on the ScanningRecipe concept we saw previously. The major difference here is that the generation phase generates HTML, and the *modification* phase (visit) does nothing, nada, zilch. The ~~entire goal~~ of the recipe is concentrated in the first pass: scanning the LST. Well, no, not the goal, rather the intelligence (not the A.I. kind).

It all starts with an accumulator - our famous graph - which will store the classes (Nodes) and their relationships (Links) as the scan progresses:

public static class GraphScanAccumulator {
    public List<Node> nodes = new ArrayList<>(); // ①
    public List<Link> links = new ArrayList<>();

    // ... search methods findNode() and findLink()
}

Did you seriously think I was going to explain this line?

To fill this graph, we will traverse the LST using a JavaIsoVisitor.
First, we identify each component of our architecture by overriding the visitClassDeclaration method. Each new class encountered becomes a "Node":

@Override
public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext ctx) {
    if (includeTests() || not(isTestClass()).test(getCursor())) { // ①

        if (classDecl.getType() != null) {
            String fqn = classDecl.getType().getFullyQualifiedName();
            graph.findNode(fqn).orElseGet(() -> { // ②
                Node newNode = new Node(fqn, classDecl.getType().getPackageName());
                graph.nodes.add(newNode);
                return newNode;
            });
        }
        return super.visitClassDeclaration(classDecl, ctx); // ③
    }
    return classDecl;
}

We only look at test classes if explicitly requested.
We use our graph accumulator to register the current class if it hasn’t been seen already.
We don’t forget to call super so that the visitor continues to descend into the tree. If and only if the class is of interest to us, otherwise, we don’t waste our time.

Next, we must weave the web. How do we know that class A depends on class B? We simply capture type usages (method calls, fields access, instantiations). For example, here’s how we proceed for method invocations:

@Override
public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, ExecutionContext ctx) {
    var mi = super.visitMethodInvocation(method, ctx); // ①

    JavaType.FullyQualified targetType = mi.getMethodType() != null ? mi.getMethodType().getDeclaringType() : null; // ②

    if (targetType != null) {
        addLink(targetType); // ③
    }
    return mi;
}

Let the visitor visit.
Extract the type information (JavaType) carried by the invoked method to know which class it belongs to. The type can be null, particularly if OpenRewrite failed to determine it.
Invoke the addLink method.

The addLink method contains all the logic allowing us to determine if the targetType interests us, that is to say if it is part of the target packages. If so, we create a new link or strengthen an existing one.

The same logic is obviously applied to member references, class fields, constructor invocations, etc.

This is the beauty of OpenRewrite’s model: the LST is already perfectly typed by the compiler during parsing. We don’t need to guess who an invoked method belongs to, the type information tells us with certainty.

Going Further: Raw Export with Datatables

Generating an HTML page is nice. But what if you want to cross-reference this data, render it yourself in a tool like Gephi, or even provide it as context to an LLM to audit your architecture?

This is where OpenRewrite’s Datatables come in. In addition to the view, project-graph-generator can export metadata in the form of easily usable CSV files:

*target/rewrite/datatables/io.github.jtama.openrewrite.model.NodesReport.csv *\ Contains all the classes found with their package and their number of incoming/outgoing connections.
*target/rewrite/datatables/io.github.jtama.openrewrite.model.LinksReport.csv *\ Exhaustive list of links between classes with an associated weight.
*target/rewrite/datatables/io.github.jtama.openrewrite.model.JavaSourceFileExcludedReport.csv *\ All classes that were excluded from the final result (often due to package filtering).

Now, it’s your turn. Run the scanner on your legacy, and contemplate (or be frightened by) the extent of the web!

P.S.: As you may have noticed, this plugin is distributed on Maven Central (io.github.jtama:project-graph-generator). If you’re wondering how to easily automate the entire publication chain without tearing your hair out, I recommend you take a look at my JReleaser tutorial.

Release everything with JReleaser

Kosmik — Fri, 19 Dec 2025 13:03:32 +0000

JReleaser

The quick and effortless way to release your project!

Java, Go, Node, Rust, Zig, Swift, Perl, Python, C/C++, C#, Elixir, Haskell, Ruby, Crystal, and more.

— Official tag line

JReleaser is a tool that performs the most common steps related to releasing your application.

Releasing is not just about publishing a package to an artifact repository. It could also mean signing and generating artifacts, assembling and publishing a changelog, announcing the release on your favorite hub, and even making some noise about it through mail, Zulip, or whatever you want.

In this post, we will focus on releasing a Java application.

Wait, it's not just Maven 🫘!

Each packager, each artifact repository has its own specificity.

As Maven Central is the ultimate goal for Java developers, and as it’s also one of the most complicated repositories, this is the one we will be looking at in this blog post. But of course, once you’ve done that, everything else will be a piece of cake 🧁!

Pre-requisite (tools ⚒️ and credentials 🔐)

PGP

Generate your PGP key pair

gpg --generate-key

That will prompt the following

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /root/.gnupg/trustdb.gpg: trustdb created
gpg: directory '/root/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/root/.gnupg/openpgp-revocs.d/4C2428BC373276273A30B9D4FA30C263300AD893.rev'
public and secret key created and signed.

pub   ed25519 2025-11-18 [SC] [expires: 2028-11-17]
      4C2428BC373276273A30B9D4FA30C263300AD893 <1>
uid                      Guess who's back ? <back_again@shady.com>
sub   cv25519 2025-11-18 [E] [expires: 2028-11-17]

This is your key identifier; keep it somewhere.

You’ll be asked for a passphrase to protect your keypair. Choose wisely, and don’t tell anyone

If you forget to save your key identifier, you can find it back using the list-keys command :

just show me !

# gpg --list-keys
/root/.gnupg/pubring.kbx
------------------------
pub   ed25519 2025-11-18 [SC] [expires: 2028-11-17]
      4C2428BC373276273A30B9D4FA30C263300AD893
uid           [ultimate] Guess who's back ? <back_again@shady.com>
sub   cv25519 2025-11-18 [E] [expires: 2028-11-17]

Distribute it 🔑

There are sereval public keyservers and amongst them the following are supported keyserver.ubuntu.com, keys.openpgp.org, pgp.mit.edu.

The following command will make your key publicly available :

gpg --keyserver keyserver.ubuntu.com -send-key 4C2428BC373276273A30B9D4FA30C263300AD893<1>

Replace with your own key

Obtaining your maven central credentials.

You can specify its name and expiration date. Personally, I chose to go crazy for this :

Install JReleaser

There are many ways to install JReleaser, but my goto for local environment is to use JBang :

// Download, and install localy
jbang app install jreleaser@jreleaser

// Execute by using
jreleaser <command> [<args>]

If you prefere to run it without installing it, you can also use JBang :

// Download, cache, and run
jbang jreleaser@jreleaser <command> [<args>]

Verify your project descriptor

Even though JReleaser will do it for you, you can always independently verify if your project descriptor has all the mandatory fields to be published by running :

jbang pomchecker@kordamp check-maven-central

Please correct your descriptor accordingly and repeat the operation until everything is clean

Configure your project

This is a 2 steps process. You need to configure JReleaser but also your build process to generate all the necessary artefacts for publication.

The Maven configuration

Add a release profile to your pom.xml :

release profile

<profile>
    <id>release</id>
    <properties>
        <altDeploymentRepository>
            local::file:./target/staging-deploy ①
        </altDeploymentRepository>
    </properties>
    <build>
        <defaultGoal>deploy</defaultGoal>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                        <configuration>
                            <attach>true</attach>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                        <configuration>
                            <attach>true</attach>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</profile>

You can of course change this value

The Gradle configuration

If you do use Gradle, I’m sure you know how to produce the equivalent configuration. I don’t.

The JReleaser configuration

You can initialize your project configuration with the following command :

jbang jreleaser@jreleaser init

This will generate your project configuration file that you will have to amend following your needs.

jreleaser.yaml

# Generated with JReleaser 1.21.0 at 2025-11-19T09:09:25.55515446Z
project:
  name: app
  version: 1.0.0-SNAPSHOT
  description: Awesome App
  longDescription: Awesome App
  authors:
    - Duke
  license: Apache-2.0
  links:
    homepage: https://acme.com/app
  languages:
    java:
      groupId: com.acme
      version: 8
  inceptionYear: 2025

release:
  github:
    owner: duke

distributions:
  app:
    artifacts:
      - path: path/to/{{distributionName}}-{{projectVersion}}.zip

The distributions and github can be removed if you only want maven deployment, anyway you have to specify the maven deployment configuration by adding the following to your config file :

signing: ①
  active: ALWAYS
  armored: true

deploy: ②
  maven:
    mavenCentral:
      release-deploy:
        active: RELEASE
        url: https://central.sonatype.com/api/v1/publisher
        stagingRepositories:
          - target/staging-deploy ③
    nexus2:
      snapshot-deploy:
        active: SNAPSHOT
        snapshotUrl: https://central.sonatype.com/repository/maven-snapshots/
        applyMavenCentralRules: true
        snapshotSupported: true
        closeRepository: true
        releaseRepository: true
        stagingRepositories:
          - target/staging-deploy ③

Lets JRelease do the artefact signing for you
Which maven repository to use for release and snapshot deployments
Where to find the artefacts locally. Must match the value used in your project configuration.

You will have to specify a few secret variables, but for obvious security reasons, NOT in a versioned source file...

Specifying variables

Most of the JReleaser needed credentials are gonna be common for all your project. So setting them globally for JReleaser is a good thing to do. I set them in the JReleaser defaut folder. By default $HOME/.jreleaser/config.properties (accepted formats are PROPERTIES, YAML, TOML and JSON)

For more on this.

I choose TOML and here what my file looks like :

~/.jreleaser/config.toml

JRELEASER_GPG_PUBLIC_KEY = """-----BEGIN PGP PUBLIC KEY BLOCK-----

<place_your_public_key_here>
-----END PGP PUBLIC KEY BLOCK-----""" ①
JRELEASER_GPG_SECRET_KEY = """-----BEGIN PGP PRIVATE KEY BLOCK-----

<place_your_secret_key_here>
-----END PGP PRIVATE KEY BLOCK-----"""

JRELEASER_DRAFT = true ②
JRELEASER_GPG_PASSPHRASE = "❤️ Eminem<3<3"
JRELEASER_MAVENCENTRAL_RELEASE_DEPLOY_USERNAME = "redacted"
JRELEASER_MAVENCENTRAL_RELEASE_DEPLOY_TOKEN = "redacted"
JRELEASER_NEXUS2_SNAPSHOT_DEPLOY_USERNAME = "redacted"
JRELEASER_NEXUS2_SNAPSHOT_DEPLOY_TOKEN = "redacted" ③

Toml supports multiline string using triple double quotes: """
I only do draft release from local env
Values obtained in obtaining-your-maven-central-credentials chapter. They are the same for maven central and nexus2_snapshot

One more thing, please. I prefere to only do dry run execution locally but that cannot be specified through file at the moment, so I export the value just before running the commands :

export JRELEASER_DRY_RUN=true && jreleaser full-release

Once you’re happy, you can possibly unset the dry run property and relaunch, but I’d rather do the proper release from my CI, which is Github for me at the moment.

Running all this from Github actions

Here is the minimal github workflow to release a maven application.

name: Release
on:
  workflow_dispatch: ①
    inputs:
      version: ②
        description: "Release version"
        required: true

jobs:
  build:
    needs: [ precheck ]
    name: 'Build artefacts'
    runs-on: ubuntu-latest
    steps:
      - name: 'Check out repository'
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.precheck.outputs.HEAD }}
      - name: 'Set up Java'
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
          cache: 'maven'
      - name: 'Build artefacts'
        run: mvn -B -P release clean deploy
      - name: Deploy to Central
        uses: jreleaser/release-action@v2 ③
        with:
          version: latest
          arguments: 'full-release' ④
        env:
          JRELEASER_GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
          JRELEASER_GPG_SECRET_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
          JRELEASER_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
          JRELEASER_MAVENCENTRAL_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
          JRELEASER_MAVENCENTRAL_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
          JRELEASER_NEXUS2_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
          JRELEASER_NEXUS2_TOKEN: ${{ secrets.SONATYPE_PASSWORD }} ⑤
          JRELEASER_PROJECT_VERSION: ${{ github.event.inputs.version }} ②
         #JRELEASER_DRAFT: true ⑥

Manually triggered workflow
The version to be released. It could also be retrieved from your maven project.
Uses the JReleaser github action (Integration also exists with Gitlab, Gitea and many others)
Runs the full-release workflow
All the values to be assign in your project secrets
Wether or not do you want draft releases.

Wrap up

We’ve only scratch the surface of what can be done with JReleaser. If you want a really full example, here’s how JReleaser releases itself, with JReleaser of course.

But at least you know how to publish your artefacts to Maven Central 🗻 \o/ .

Technique Avancée d'OpenRewrite : Orchestrer des refactorings complexes avec les `ScanningRecipe`

Kosmik — Wed, 29 Oct 2025 08:59:38 +0000

⚠️ WARNING: Le sujet qui va être traité est avancé. En cas de doute, je vous conseille d’aller lire les articles précédents de cette série.

Nous avons déjà vu dans les articles précédents pas mal d'exemples. Mais chacun d'eux concerne peuvent-être traités en ne prenant en compte qu'un fichier source, une compilation unit en bon Openrewrite. Alors qu'allons-nous devenir si notre besoin dépasse les frontières d'un seul fichier ?

Oui, mais si ma recette a besoin d'analyser le contenu de la classe A pour décider de modifier la classe B et de générer une toute nouvelle classe C ?

C’est précisément le cas d’usage où les recettes classiques, qui traitent les fichiers de manière isolée, ne suffisent plus. Pour ces scénarios, OpenRewrite fournit un outil spécifique : la ScanningRecipe.

Une ScanningRecipe découpe le refactoring en trois phases distinctes :

Une phase d’analyse (scan) : Un premier visiteur parcourt tous les fichiers sources pour collecter des informations, sans rien modifier.
Une phase de génération (generate) : À partir des informations collectées, cette étape peut créer de nouveaux fichiers sources.
Une phase de modification (visit) : Un second visiteur parcourt à nouveau les fichiers pour appliquer les modifications, en s’aidant des données de la phase d’analyse.

Cas d'usage : Extraire une interface

Pour illustrer ce processus, nous allons implémenter une recette qui extrait une interface de toutes les classes annotées avec @LearnToFly.

Pour une classe comme celle-ci :

package com.foo.fighter;

//imports

@LearnToFly
public class RocketController {

    @Operation(summary = "Launches a rocket to a given destination", description = "Check availability and other constraints before doing anything.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Successfully launched"),
        @ApiResponse(responseCode = "404", description = "Not found - The destination isn't in the solar system")
    })
    @GetMapping("/rocket/{destination}")<1>
    public String launch(String destination) {
        // ...
    }
}

Beaucoup, beaucoup trop d’annotations qui nuisent à la lisibilité du code

La recette doit :

Trouver la classe RocketController grâce à son annotation.
Générer une nouvelle interface IRocketController dans un module différent.
Modifier RocketController pour qu’elle implémente IRocketController, et supprimer l’annotation @LearnToFly.

Analysons l’implémentation (disponible sur le dépôt d’exemples).

Phase 1 : La collecte d'informations

La première étape est une mission de reconnaissance. Le Scanner parcourt le code source pour identifier les classes cibles et stocke les informations dans un Accumulator, un conteneur de données partagé entre les phases.

public class ExtractInterface extends ScanningRecipe<ExtractInterface.Accumulator> {

    public static class Accumulator { ①
        Map<String, ToExtract> toBeExtracted = new HashMap<>();
    }

    @Override
    public Accumulator getInitialValue(ExecutionContext ctx) {
        return new Accumulator();
    }

    @Override
    public TreeVisitor<?, ExecutionContext> getScanner(Accumulator acc) {
        return new JavaIsoVisitor<ExecutionContext>() {
            @Override
            public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext ctx) {
                if (isClass.test(classDecl) && !alreadyImplementsInterface.test(classDecl)) { ②
                    acc.toBeExtracted.put(classDecl.getType().getFullyQualifiedName(),
                            new ToExtract(classDecl.getSourcePath(), ...)); ③
                }
                return classDecl;
            }
        };
    }
    //...
}

L'Accumulator est une simple classe statique interne qui sert de conteneur pour les données que nous collectons.
On vérifie que la classe est bien celle ciblée par l’annotation @LearnToFly et qu’elle n’implémente pas déjà l’interface.
Si la classe correspond, on stocke les informations nécessaires (comme son sourcePath) dans l'Accumulator. Le FQDN de la classe sert de clé.

À la fin de cette phase, aucune modification n’a été faite, mais notre Accumulator contient une "liste de tâches" de toutes les classes à traiter.

Phase 2 : La génération de l'interface

Cette méthode est exécutée après le Scanner. Elle utilise les données de l'Accumulator pour construire de nouveaux SourceFile.

@Override
public Collection<SourceFile> generate(Accumulator acc, ExecutionContext ctx) {
    return acc.toBeExtracted.values().stream()
        .map(toExtract -> {
            // ... logique pour déterminer le chemin de la nouvelle interface ...
            return (SourceFile) getExtractedInterface(toExtract) ①
                .withSourcePath(newInterfacePath)
                .withMarkers(Tree.randomId());
        })
        .collect(Collectors.toList());
}

private J.CompilationUnit getExtractedInterface(ToExtract toExtract) {
    JavaTemplate interfaceTemplate = JavaTemplate.builder("public interface #{any(String)} {}")
            .build();
    // ...
    J.CompilationUnit anInterface = (J.CompilationUnit) new JavaIsoVisitor<Integer>() {
        @Override
        public J.MethodDeclaration visitMethodDeclaration(J.MethodDeclaration method, Integer p) {
            return method.withBody(null); ②
        }

        @Override
        public J.VariableDeclarations visitVariableDeclarations(J.VariableDeclarations multiVariable, Integer p) {
            return null; ③
        }
    }.visit(toExtract.getOriginalTree(), 0);
    // ...
    return anInterface;
}

Pour chaque classe à traiter, on appelle une méthode qui va fabriquer la structure de notre nouvelle interface.
La transformation principale se fait via un petit visiteur interne. Pour chaque méthode, on supprime son corps avec withBody(null).
On supprime également toutes les déclarations de variables en retournant null.

Le résultat est une collection de J.CompilationUnit qui représentent nos nouvelles interfaces, prêtes à être ajoutées au projet.

Phase 3 : La modification des classes existantes

Dernière étape : modifier les classes originales. Pour cela, on réutilise la technique des messages. On parcourt les ClassDeclaration et si l’une d’elles correspond à une entrée de notre Accumulator, on lui attache un message.

La déclaration de la classe

@Override
public TreeVisitor<?, ExecutionContext> getVisitor(Accumulator acc) {
    return new JavaIsoVisitor<ExecutionContext>() {
        @Override
        public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration cd, ExecutionContext ctx) {
            ToExtract toExtract = acc.toBeExtracted.get(cd.getType().getFullyQualifiedName());
            if (toExtract != null) {
                getCursor().putMessage(TARGET_CLASS, toExtract); ①
                var annotations = cd.getLeadingAnnotations();
                annotations.removeIf(ann -> targetAnnotationMatcher.matches(ann));
                maybeRemoveImport(targetAnnotation); ②
                cd = cd.withLeadingAnnotations(annotations)
                        .withImplements(List.of(TypeTree.build(target.extractedInterfaceName()))); ③
                cd = super.visitClassDeclaration(cd, executionContext);
                return cd;
            }
            return super.visitClassDeclaration(cd, ctx);
        }
    };
}

Si la ClassDeclaration en cours de visite est l’une de nos cibles, on attache les données la concernant (toExtract) comme message sur le curseur.
Dans visitClassDeclaration, on vérifie si un message est présent. Si oui, on sait qu’on doit modifier cette classe.
On ajoute la clause implements et on supprime l’annotation @LearnToFly. Un autre visiteur (non montré ici) s’occupe d’ajouter @Override aux méthodes.

Les déclarations de méthodes

    @Override
    public J.MethodDeclaration visitMethodDeclaration(J.MethodDeclaration method, ExecutionContext executionContext) {
        if (getCursor().getNearestMessage(TARGET_CLASS) != null) { ①
            return JavaTemplate.builder("@Override").build().apply(getCursor(), method.getCoordinates().replaceAnnotations());
        }
        return super.visitMethodDeclaration(method, executionContext);
    }

Si la classe a été marquée de sceau rouge de l’extraction, on ajoute l’annotation @Override à toutes les déclarations de méthodes.

Avant/Après

Voici par exemple une classe avant extraction :

HostelController open

import com.github.jtama.app.reservation.Reservation;
import com.github.jtama.toxic.BigDecimalUtils;
import com.github.jtama.toxic.LearnToFly;
import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import java.util.List;

@Path("/api/hostels")
@Produces(MediaType.APPLICATION_JSON)
@LearnToFly
public class HostelController {

    @Inject
    HostelReservationService hostelReservationService;

    @GET
    public List<Hostel> getAll() {
        return Hostel.listAll();
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @RolesAllowed("ADMIN")
    @Transactional
    public Hostel create(Hostel hostel) {
        return Hostel.persistIfNotExists(hostel);
    }

    @POST
    @Path("/{name}/book")
    @RolesAllowed("USER")
    public Reservation book(@PathParam("name")String name, @QueryParam("month") Integer month, @Context SecurityContext security) {
        BigDecimalUtils.valueOf(month.longValue());// Because I can !
        return hostelReservationService.book(name, month, security.getUserPrincipal().getName());
    }

}

L'interface extraite :

IHostelController open

import com.github.jtama.app.reservation.Reservation;
import com.github.jtama.toxic.LearnToFly;
import jakarta.annotation.security.RolesAllowed;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.SecurityContext;

import java.util.List;

@Path("/api/hostels")
@Produces(MediaType.APPLICATION_JSON)
@LearnToFly
public interface IHostelController {

    @GET List<Hostel> getAll();

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @RolesAllowed("ADMIN")
    @Transactional Hostel create(Hostel hostel);

    @POST
    @Path("/{name}/book")
    @RolesAllowed("USER") Reservation book(@PathParam("name")String name, @QueryParam("month") Integer month, @Context SecurityContext security);

}

Et la classe après extraction :

IHostelController open

import com.github.jtama.app.reservation.Reservation;
import jakarta.inject.Inject;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.SecurityContext;

import java.math.BigDecimal;
import java.util.List;

public class HostelController implements IHostelController {

    @Inject
    HostelReservationService hostelReservationService;

    @Override
    public List<Hostel> getAll() {
        return Hostel.listAll();
    }

    @Override
    public Hostel create(Hostel hostel) {
        return Hostel.persistIfNotExists(hostel);
    }

    @Override
    public Reservation book(@PathParam("name")String name, @QueryParam("month") Integer month, @Context SecurityContext security) {
        BigDecimal.valueOf(month.longValue());// Because I can !
        return hostelReservationService.book(name, month, security.getUserPrincipal().getName());
    }

}

C'est dans la boîte

J’espère vous avoir convaincu qu’il n’y a encore une fois rien de sorcier. Des concepts séparément simples qui une fois réunis nous permettent des réécritures relativement complexes.

Encore une fois, vos cas d’usages sont la limite ! Je vous ferai bientôt part d’un nouveau joujou pour visualiser vos projets d’une nouvelle manières.

Et comme d'habitude, tout le code est disponible dans le dépôt Openrewrite refactoring as code.

Technique Avancée d'OpenRewrite : Utiliser les messages pour implémenter des logiques complexes

Kosmik — Thu, 11 Sep 2025 07:05:37 +0000

Photo par Pixabay

Je vous avais déjà parlé d’Openrewrite dans le premier article de cette série. Si vous ne l’avez pas lu et que vous avez besoin d’un petit rafraichissement, je vous invite à mettre la lecture de ce post en ⏸️ et à y revenir plus tard. C’est bon ? Allez go.

Tous les cas d’usage dont il a été question dans l’article précédent font intervenir une recette qui n’a besoin que des informations trouvées à un et seul niveau du LST. Puisqu’une image vaut mieux qu’un long discours, et que je sens bien que je ne me suis pas très bien fait comprendre, voici un exemple crédible d’AST:

Jusqu’à présent les exemples opéraient des modifications sur des invocations de méthodes, ou par exemple un renommage de classe.

Dans le diagramme précédent, chaque nœud correspond à un élément d’AST (les choses sont évidemments simplifiées ici). Comme nous l’avons déjà vu, OpenRewrite utilise le pattern visiteur pour parcourir l’arbre. Plus précisément les recettes implémentent des visiteurs dont les interfaces correspondent au langage manipulé.
En l’occurence, les manipulations sont effectuées sur du Java, et le visiteur utilisé sera donc un JavaIsoVisitor.

Oui, mais si mon cas d’usage nécessite d’identifier une invocation de méthode pour agir sur la déclaration de la méthode qui la contient dans une classe?

Oui, je te comprends, et cette question m’a moi aussi empecher de dormir pendant quelques jours. Seulement vois-tu, les gens derrières Openrewrite aussi.
Ils nous ont donc mis à disposition un système de message très convaincant et plutôt sûr.

Cas d'usage

Imaginons que quelqu’un de mal avisé, non, n’insistez pas, je ne vous dirai pas qui. D’accooooord c’est moi. Imaginons donc, disais-je, que quelqu’un de mal avisé ait développé dans une librarie un moyen d’enregistrer le traitement d’une méthode :

import static com.github.jtama.toxic.timer.logStart;
import static com.github.jtama.toxic.timer.logEnd;
import static com.github.jtama.acme.Process.longRunningMethod;

public class ManualGearCar {

    @Deprecated<4>
    public void drift(String param) {
        logStart();<1>
        longRunningMethod(param);<2>
        logEnd();<3>
    }
}

Enregistre le début d’exécution de la méthode
Exécute un traitement
Enregistre la fin d’exécution de la méthode
Random annotation qui aura son intérêt plus tard

Arpès d’intense recherche nous avons découvert l’existence de micrometer et de son annotation io.micrometer.core.annotation.Timed.

En tant que développeur, je vais donc identifier l’invocation de la méthode Timer#logStart() et si je la trouve :

La supprimer
Supprimer l’invocation de la méthode Timer#logEnd() si elle existe
Ajouter l’annotation @Timed sur la déclaration de la méthode drift

Et c’est exactement la logique que nous allons mettre en œuvre dans la recette.

Implémentation

Dans cet exemple, nous ne regardons que l’implémentation du visiteur, pas la recette complète. Mais comme d’habitude, tout est disponible dans le dépôt github

private static class ReplaceCompareVisitor extends JavaIsoVisitor<ExecutionContext> {

        private final MethodMatcher logStartInvocaMatcher = new MethodMatcher("com.github.jtama.toxic.Timer logStart()");<1>
        private final MethodMatcher logEndInvocaMatcher = new MethodMatcher("com.github.jtama.toxic.Timer logEnd()");
        private final AnnotationMatcher logStartMatcher = new AnnotationMatcher("@io.micrometer.core.annotation.Timed");
        private final JavaTemplate annotationTemplate = JavaTemplate.builder("@Timed")
                .imports("io.micrometer.core.annotation.Timed")
                .javaParser(
                        JavaParser.fromJavaVersion()
                            .classpath(JavaParser.runtimeClasspath()))
                .build();

        public ReplaceCompareVisitor() {
            maybeRemoveImport("com.github.jtama.toxic.Timer");
        }

        @Override
        public J.MethodDeclaration visitMethodDeclaration(J.MethodDeclaration method, ExecutionContext ctx) {<3>
            J.MethodDeclaration md = super.visitMethodDeclaration(method, ctx);
            Cursor cursor = getCursor();
            if (cursor.getMessage("appendAnnotation", false)) {
                if (md.getLeadingAnnotations().stream()
                        .noneMatch(logStartMatcher::matches)) {
                    maybeAddImport("io.micrometer.core.annotation.Timed");
                    md = annotationTemplate.apply(cursor, method.getCoordinates().addAnnotation(Comparator.comparing(J.Annotation::getSimpleName)));
                }
            }
            return md;
        }

        @Override
        public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, ExecutionContext ctx) {<2>
            J.MethodInvocation mi = super.visitMethodInvocation(method, ctx);
            if (logStartInvocaMatcher.matches(mi) || logEndInvocaMatcher.matches(mi)) {
                getCursor().putMessageOnFirstEnclosing(J.MethodDeclaration.class, "appendAnnotation", true);
                return null;
            }
            return mi;
        }
    }

Les utilitaires
Le visiteur d’invocation de méthode
Le visiteur de déclaration de méthode

Les utilitaires

Dans cette section, deux outils d’OpenRewrite sont utilisés. Le MethodMatcher permet d’identifier précisément les invocations de méthodes ciblées, telles que logStart() et logEnd().

L' AnnotationMatcher sert à vérifier la présence de l’annotation @Timed sur une méthode.

Enfin, le JavaTemplate facilite l’insertion de l’annotation dans le code source et gère l’import nécessaire.

Ces utilitaires simplifient la manipulation de l’AST et préparent les modifications à appliquer dans les visiteurs.

Le visiteur d'invocation de méthode (`visitMethodInvocation`)

Ce visiteur parcourt chaque appel de méthode dans le code source.

Lorsqu’il rencontre une invocation de logStart() ou logEnd(), il ajoute un message pour signaler qu’une annotation devra être ajoutée ultérieurement.

Un message n’est en réalité qu’un tuple <clef;valeur>, mais ce qui est intéressant ici, c’est que l’on précise le scope d’accessibilité du message pour éviter de polluer tout le contexte.

En occurrence, seul la méthode contenant l’invocation en question pourra accéder au message(putMessageOnFirstEnclosing(J.MethodDeclaration.class...).

La valeur null renvoyée dans ce cas à pour effet la suppression du nœud en cours de visite, c’est-à-dire, l’invocation de la méthode.

Le visiteur de déclaration de méthode(`visitMethodDeclaration`)

Celui-là est vraiment plus simple.

Si on m’a passé un message ET que la méthode n’est pas déjà annoté (si le développeur voulait mettre ceinture et bretelle... ¯\(ツ)/¯ ), j’ajoute l’annotation @Timed.

En image

Puisqu’une image vaut mieux qu’un long discours.

Et après ?

D’autres exemples complexes suivront et n’oubliez pas que tout le code est disponible dans le dépôt Openrewrite refactoring as code.

De la Programmation Orientée Objet vers la Programmation Orientée Données - Un guide pratique

Kosmik — Tue, 29 Jul 2025 09:11:45 +0000

Introduction

La programmation orientée données (Data-Oriented Programming) représente un paradigme émergent qui privilégie la manipulation des données plutôt que l’encapsulation des comportements. Ce guide pratique explore les étapes clés pour transformer du code Java traditionnel orienté objet vers une approche orientée données, en s’appuyant sur l’exemple concret du dépôt https://github.com/jtama/crazy-data-oriented-programming.

Le dépôt crazy-data-oriented-programming illustre cette transformation à travers l’exemple d’un système de cartes à jouer. La branche main présente une implémentation orientée objet classique, tandis que la branche expected montre l’évolution vers une approche orientée données utilisant les fonctionnalités modernes de Java.

Il a été pensé pour être utilisé comme kata, donc si vous vous sentez de l’animer en équipe, ne vous privez pas.

Il va sans dire que les exemples sont triviaux, et que pour ce cas précis un autre design aurait certainement été plus simple. C’est un exercice de style.

Table des matières

Présentation
Étape 1 : Les classes scellées
Étape 2 : Restructuration de la Hiérarchie
Étape 3 : Utilisation de Records
Étape 4 : Simplification du traitement avec Pattern Matching
Conclusion
Ressources

Présentation

Oui, parce qu’avant de tout retaper, on va peut-être apprendre à se connaître non ?

Les classes

Un petit diagramme pour commencer :

Nous avons donc une hiérarchie d’objets pour représenter le jeu de carte, c’est un jeu de tarot au cas où ne l’auriez pas deviné, et une classe AdviceGiver qui vous donne son avis sur vos cartes.

Pas de troll ici, un atout se dit bien trump en anglais. ¯\(ツ)/¯

Le code, le code, le code

Ici, ne regardons que le code intéressant (hum) de la class AdviceGiver

public static String advice(PlayingCard playingCard) {
    if (playingCard instanceof SuitCard) { ①
        SuitCard suitCard = (SuitCard) playingCard; ②
        if (null != suitCard.face()) { ③
            return "The" + suitCard.face().displayName() +
                    " of " +
                    suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ")" +
                    " is strong";
        }

        switch (playingCard.index()) { ④
            case 1:
                return "The first of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
            case 2:
                return "The second of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
            case 3:
                return "The third of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
            case 4:
            case 5:
            case 6:
                return "The " + suitCard.index() + "th of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is still weak";
            case 7:
            case 8:
            case 9:
            case 10:
                return "The" + suitCard.index() + "th of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") may win you a hand";
            default:
                throw new IllegalStateException("Unexpected value: " + playingCard);
        }
    }
    return "The trump n°" + playingCard.index() + " is strong"; ⑤
}

Si la carte est de type classique
Alors on la cast
Si ce n’est pas une figure
Sinon, en fonction de son idex
Sinon, c’est forcément que c’est un atout. Non ?

Ah, mais attention, ici on joue à la galloise, avec des Jokers ! Tout de suite, c’est un peu plus drôle."
Perceval

"Ahh mais bien sûr, on va ajouter ça." vous dîtes vous. Vous devez donc ajouter un nouveau type de carte, et surtout, bien faire attention, parce que votre méthode advice est maintenant toute pétée...

Ça serait teeeeellement bien si le compilateur pouvait nous guider...

Étape 1 : Les classes scellées

Depuis Java 17, tels les dieux qui scellèrent Excalibur dans la roche, nous pouvons figer nos hierarchies de classes. On espère juste qu’aucun hacker répondant au doux nom d’Arthur viendra faire son malin. Mais bon, je m’égare.

Les classes et interfaces scellées, sealed en bon anglais, permette de limiter les implémentations possibles à un ensemble fini de classes. Cet ensemble est renforcé à la compilation.

Avant : Interface Simple

public interface PlayingCard {
    Integer index();
}

Après : Interface Scellée (Sealed Interface)

public sealed interface PlayingCard permits SuitCard, TrumpCard {
    Integer index();
}

2 nouveaux mots réservés introduits ici, sealed, bon voilà, on a compris, et permits qui permet de lister les implémentations autorisées.

On peut permettre 3 types d’enfants d’une classe/interface scellée :

Une classe/interface scellée
Une classe final
Un record, qui est par construction final
On peut aussi utiliser une classe non-sealed pour réouvrir la hiérarchie. Il y a des cas qui le justifient, mais là vous êtes à nouveau sans filet. On m'a forcé à vous le dire. Moi je ne voulais pas.

Pour résumer, la hiérarchie d’objets d’une classe/interface scellée est finie et connue à la compilation.

Étape 2 : Restructuration de la Hiérarchie

Avant : Classe Concrète Complexe

public class SuitCard implements PlayingCard {
    private final Color color;
    private final Integer index;
    private final Face face;

    public SuitCard(Color color, Integer index, Face face) {
        // Validation complexe avec logique conditionnelle
        if (color == null)
            throw new IllegalArgumentException("Color must not be null.");
        if (index == null)
            throw new IllegalArgumentException("Index must not be null.");
        if (index < 1)
            throw new IndexOutOfBoundsException("Index must be positive.");
        if (index > 15)
            throw new IndexOutOfBoundsException("Index must be lesser than 15.");
        if (index > 10 && face == null)
            throw new IllegalArgumentException("Face must not be null for index greater than 10.");
        if (index < 11 && face != null)
            throw new IllegalArgumentException("Face must be null for index lesser than 11.");

        this.color = color;
        this.index = index;
        this.face = face;
    }

    // Getters, equals, hashCode...
}

Dans cet exemple, il n’y a qu’une classe pour représenter une carte de couleur, et l’énumération des figures, trop simpliste, nous impose des contrôles complexes. Vous remarquerez que ces contrôles ne sont même pas exhaustif, puisque nous ne validons pas la correspondance entre les figures et les index.

Évolution de l'enum `Face`

Une énumération n’est pas limité à une liste idiote de constante. Elle peut avoir des attributs et des méthodes. Ici, nous allons juste ajouter un index à l’énumération des figures, ce qui va nous permettre de simplifier le constructeur des cartes ET augmenter le contrôle.

public enum Face {
    JACK("Jack", 11),
    KNIGTH("Knight", 12),
    QUEEN("Queen", 13),
    KING("King", 14);

    private final String displayName;
    private final int index;

    Face(String displayName, int index) {
        this.displayName = displayName;
        this.index = index;
    }

    public String displayName() {
        return displayName;
    }

    public int index() {
        return index;
    }
}

Spécialisation

Ici, nous séparons les cartes de couleur avec et sans figure. Encore une fois pour permettre au compilateur de jouer son rôle de garde-fou, plutôt que de devoir l’implémenter nous même.

En effet, chaque type encapsule ici sa propre logique et les contraintes sont exprimées par la hiérarchie de types.

public sealed interface SuitCard extends PlayingCard permits NumberSuitCard, RoyalSuitCard {
    Color color();
}

Étape 3 : Utilisation de `Records`

Les record ont été ajouté à Java dans la version 14. Ils ont les caractéristiques suivantes :

Leurs propriétés sont immutables, elles ne peuvent en tout cas pas être réaffectées.
Ils sont final par constructions.
Leurs méthodes toString, equals et hashCode sont automatiquements générées à partir de leurs propriétés.

Cartes Numériques

public record NumberSuitCard(Color color, Integer index) implements SuitCard {
    public NumberSuitCard {
        Objects.requireNonNull(color, "Color cannot be null");
        Objects.requireNonNull(index, "Index cannot be null");
        if(index < 1 || index > 10){
            throw new IllegalArgumentException("Index must be between 1 and 10 included");
        }
    }
}

Les méthodes color() et index() sont générés par java directement.

Cartes Royales

public record RoyalSuitCard(Color color, Face face) implements SuitCard {
    public RoyalSuitCard {
        Objects.requireNonNull(color, "Color cannot be null");
        Objects.requireNonNull(face, "Face cannot be null");
    }

    @Override
    public Integer index() {
        return face.index();
    }
}

Les méthodes color() et face() sont générés par java directement, et il ne nous reste plus qu’à implémenter la méthode index

Cartes Trump

public record TrumpCard(Integer index) implements PlayingCard {
    public TrumpCard {
        if (index == null || index < 0 || index > 22)
            throw new IndexOutOfBoundsException("Index must be positive and lesser than 22.");
    }
}

Concepts clés :

Records : Réduisent drastiquement le code boilerplate (environ une trentaine de ligne par classe dans notre cas)
Constructeur compact : Validation des données à la construction
Immutabilité : Les données sont immuables par défaut, ou pour être plus précis, les attributs sont final.

Étape 4 : Simplification du traitement avec Pattern Matching

Maintenant que nous avons un arbre hiérarchique satisfaisant, penchons-nous sur le traitement.

Avant : Logique Procédurale Complexe

Pour rappel :

Details

public class PrettyPrinter {
    public static String advice(PlayingCard playingCard) {
        if (playingCard instanceof TrumpCard) {
            TrumpCard trump = (TrumpCard) playingCard;
            return "The trump n°%s is strong".formatted(trump.index());
        } else if (playingCard instanceof SuitCard) {
            SuitCard suit = (SuitCard) playingCard;
            if (suit.face() == null) {
                // Logique pour cartes numériques
                if (suit.index() == 1) {
                    return "The first of %s(%s) is very weak".formatted(
                        suit.color().name().toLowerCase(),
                        suit.color().getSymbol());
                }
                // ... autres conditions
            } else {
                // Logique pour cartes royales
                return "The %s of %s(%s) is strong".formatted(
                    suit.face().displayName(),
                    suit.color().name().toLowerCase(),
                    suit.color().getSymbol());
            }
        }
        return "";
    }
}

Pattern Matching - Step by step

Better `instanceof`

Depuis Java 16, on a le droit de simplifier nos if’s à base de instanceof. On peut ainsi passer de ça :

before.java

if (playingCard instanceof TrumpCard) {
    TrumpCard trump = (TrumpCard) playingCard;
    return "The trump n°%s is strong".formatted(trump.index());
}

À ça :

after.java

if (playingCard instanceof TrumpCard trump) {
    return "The trump n°%s is strong".formatted(trump.index());
}

C’est pas dingue, mais au moins c’est à l’épreuve des erreurs.

`Switch expression`

Depuis Java 14, le switch est une expression à par entière, qui peut donc retourner une valeur directement.

On passe de ça :

before.java

switch (playingCard.index()) {
    case 1:
        return "The first of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
    case 2:
        return "The second of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
    // More logic
    default:
        throw new IllegalStateException("Unexpected value: " + playingCard);
}

À ça :

after.java

String value = switch (playingCard.index()) {
    case 1 -> "The first of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
    case 2 ->"The second of " + suitCard.color().name().toLowerCase() + "(" + suitCard.color().getSymbol() + ") is very weak";
    // More logic
    default:
        throw new IllegalStateException("Unexpected value: " + playingCard);
}

`Switch` sur le type

Depuis Java 20, on peut switcher sur les types ce qui va encore nous permettre d’améliorer les choses.

On passe de ça :

before.java

if (playingCard instanceof TrumpCard) {
    // Do something
} else if (playingCard instanceof RoyalSuitCard){
    // Do something
}  else if (playingCard instanceof NumberSuitCard){
    // Do something
} else {
    //Panick
}

À ça :

after.java

switch (playingCard) {
    case TrumpCard trump -> // Do something
    case NumberSuitCard suitCard -> // Do something
    case RoyalSuitCard royalCard -> // Do something
};

Ce qui est tout à fait merveilleux ici, c’est que grâce à notre hiérarchie d’objet finie, il n’y a plus besoin de paniquer. C’est le compilateur qui vérifie la complétude de notre switch

Destructuration des records

Disponible dans les boucles for, et dans les cas de pattern matching, la destructuration nous permet d’accéder directement à ce qui nous intéresse.

On passe de ça :

before.java

case RoyalSuitCard card -> "The %s of %s(%s) is strong"
    .formatted(
            card.face().displayName(),
            card.color().name().toLowerCase(),
            card.color().getSymbol());

À ça :

after.java

case RoyalSuitCard(Color color, Face face) -> "The %s of %s(%s) is strong"
    .formatted(
            face.displayName(),
            color.name().toLowerCase(),
            color.getSymbol());

Et on pourrait également n’exposer qu’une partie des attributs.

`Switch` avec des guards

Promis, après, j’arrête.

On peut maintenant combiner tout ce que l’on a déjà avec le dernier apport : les gardes. Ils nous permettent d’ajouter des conditions plus fines dans nos case :

after.java

return switch (playingCard) {
    case TrumpCard(Integer idx) -> "The trump n°%s is strong".formatted(idx);
    case NumberSuitCard suitCard when suitCard.index() == 1 -> "The first of %s(%s) is very weak".formatted(suitCard.color().name().toLowerCase(), suitCard.color().getSymbol());
    case NumberSuitCard suitCard when suitCard.index() == 2 -> "The second of %s(%s) is very weak".formatted(suitCard.color().name().toLowerCase(), suitCard.color().getSymbol());
    case NumberSuitCard suitCard when suitCard.index() == 3 -> "The third of %s(%s) is very weak".formatted(suitCard.color().name().toLowerCase(), suitCard.color().getSymbol());
    case NumberSuitCard suitCard when suitCard.index() < 7 -> "The %sth of %s(%s) is still weak".formatted(suitCard.index(),suitCard.color().name().toLowerCase(), suitCard.color().getSymbol());
    case NumberSuitCard(Color color, Integer index) -> "The %sth of %s(%s) may win you a hand".formatted(index, color.name().toLowerCase(), color.getSymbol());
    case RoyalSuitCard(Color color, Face face) -> "The %s of %s(%s) is strong".formatted(face.displayName(), color.name().toLowerCase(), color.getSymbol());
};

Ici on combine :

un switch expression
sur le type
avec du pattern matching
de la deconstruction
et des guards matérialisé par le mot clef when qui nous permettent un contrôle plus fin.

🔥 CAUTION: L’ordre de vos case compte toujours autant qu’avant. On va du plus spécifique au plus générique, sinon, c’est le drame.

Bénéfices de la transformation

Réduction du Code

Moins de boilerplate : Les records éliminent getters, equals, hashCode, toString
Validation centralisée : Constructeurs compacts pour la validation
Hiérarchie simplifiée : Élimination des classes intermédiaires

Amélioration de la Sécurité

Exhaustivité : Le compilateur garantit la couverture de tous les cas
Immutabilité : Données finales par défaut
Typage fort : Séparation claire des responsabilités par type

Lisibilité et Maintenabilité

Intentions révélées : Le code exprime clairement l’intention
Pattern matching : Logique métier plus lisible
Séparation des préoccupations : Chaque type gère sa propre logique

L’analyse des statistiques Git révèle l’impact de cette transformation :

Réduction nette de 212 lignes (60% de réduction), et ça c’est bon ! \o/

Conclusion

Comme d’habitude, ne réécrivez pas toutes vos applications tête baissée. Mais il est important de savoir quelle palette de possibilité vous offre votre langage.

Gardez en tête toutes les cartes de votre main (je l’accorde, elle était facile), et restez curieux !

Ressources

Repository GitHub Dans la branche main le code initial, dans la branche expected le code final, avec un guide pour l’animer comme un kata
Documentation officielle sur les concepts de l’article

Spécial kassdédi à Lucile Thiénot et Florian Gomas ❤️!

ROQ: Creating a custom section helper

Kosmik — Tue, 01 Jul 2025 14:01:21 +0000

But why?

Why a car? Because it’s a custom one.

Now that we have answered this crucial question, let’s push it aside and move on.

No I meant why a custom section helper?

Ohhhhh. Ok.

Sometimes you need to execute code to generate content, not just compose templating bits.

To do this Qute lets you define custom section helper that allows java code execution, to transform content. Here are some existing section helpers :

Mardown/Asciidoc\ They will generate HTML content from doc-as-code content
QRCode\ That will generate an image based on a given URL

What will we do?

In this blog post, we will implement a custom section helper that allows to invoke a Kroki.io server to generate images from almost every possible diagram as code language.

What I’d like to have is a simple and common way for the user to let us know that he is writing a diagram and would like us to generate the rendering for him.

Something like :

----
title: A blog post with a diagram
tags: qute,diagram
----

Here's my blog post:

++++ ①
\{#diagram language="dbml" outputFormat="svg" alt="Blog tables diagram" width=400 height=500}
@startuml
!theme hacker

left to right direction

object users {
id : integer
username : varchar
role : varchar
created_at : timestamp
}

object posts {
id : integer [primary key]
title : varchar
body : text
user_id : integer
status : post_status
created_at : timestamp
}

note left: **body** => Content of the post

enum post_status {
draft
published
private
}

note right of post_status: **private** => visible via URL only

posts::user_id --> users::id
posts::post_status --> post_status

@enduml
\{/}

++++

Just to tell the asciidoc engine it’s a passthrough

And I would like to be automatically converted to :

Let's implement this

If you try the above code right now, Roq will bark that no section helper is available to process this section.

Let’s fix this. We will just create a new SectionHelper and its corresponding factory, usually declared in a single source file

import io.quarkus.qute.EngineConfiguration;
import io.quarkus.qute.ResultNode;
import io.quarkus.qute.SectionHelper;
import io.quarkus.qute.SectionHelperFactory;

import java.util.List;
import java.util.concurrent.CompletionStage;

@EngineConfiguration ①
public class DiagramsSectionHelperFactory implements SectionHelperFactory<DiagramsSectionHelperFactory.DiagramSectionHelper> {

    @Override
    public List<String> getDefaultAliases() {
        return List.of("diagrams"); ②
    }

    @Override
    public DiagramSectionHelper initialize(SectionInitContext context) { ③
        new DiagramSectionHelper(context);
    }

    public class DiagramSectionHelper implements SectionHelper {
        @Override
        public CompletionStage<ResultNode> resolve(SectionResolutionContext context) {
            return context.execute(); ④
        }
    }
}

This annotation tells the Qute engine that this instance is here for him. Namely that he must register a new section helper.
Here is our new section alias
Where we can initialize an helper for this specific resolution context
Returns exactly what was given in.

For the moment, that’s not much better, the content of the section is rendered untouched, but at least, it doesn’t bark at us anymore.

I will spare you the Kroki.io client implementation details, but let’s just say we have the following interface:

public interface DiagramConverter {

    String encode(String diagramSource, DiagramParams params); ①

    record DiagramParams(String diagramLanguage, String alt, Integer width, Integer height, DiagramConverter.DiagramOutputFormat diagramOutputFormat) {

        }
}

Generates the needed HTML code to display the diagram using the data uri scheme

Let's dive a bit more

They are a few more methods available in the DiagramsSectionHelperFactory. Let’s take a closer look at the initialize one.
For the sake of brevity, the code pretends there is only the single language parameter to deal with :

public class DiagramsSectionHelperFactory implements SectionHelperFactory<DiagramsSectionHelperFactory.DiagramSectionHelper> {

    private DiagramConverter converter;

    //more code here

    @Override
    public DiagramSectionHelper initialize(SectionInitContext context) {
        String diagramLanguage = context.getParameter("language"); ①
        new DiagramSectionHelper(language, converter);
    }

    //and more here
}

Gets the language param value. Be aware that it will always be a String, so you may have to do conversions if needed

❗ IMPORTANT: Should you need to use expressions instead of literals as value, you would need a more convoluted path. That would not bite you though. Let me know if you are interested.

That's it we are done!

Adding a new SectionHelper is not hard. Of course this sample is naive, and the complexity hidden in the converter. But I am sure you can foresee useful use cases for them. Everything I've just shown is available with Quarkus and Qute only.

Want to dig a bit more ?

You can first check I am Roq which is already full of insights or even take a look at the QRCode plugin in the github repository

Even if you don’t like Markdown, sometimes you don’t have a choice

Kosmik — Wed, 04 Jun 2025 15:07:05 +0000

TL;DR;

# 🔥
downdoc -o out.md README.adoc

💀 Opinions are my own. I may have to exagerate them for obvious narrative reasons.

Yes, you hate Markdown, and yet it seems to spread like a disease.

Yet, textual format documentation is an absolute necessity for us developers, and I am sure you already have found your challenger. I am talking, of course, about ASCIIDOC

Guess you would not be here if you hadn’t.

But there are some cases where you just don’t have a choice and have to produce Markdown. 😢

You are not doomed.

It seems that Dan Allen, father of Asciidoctor, agrees with you 100%.

Strange, isn’t it?

Anyway, he also fathered Downdoc... That name is absolutely marvelous, and here is its headline:

Rapidly down-converts AsciiDoc to Markdown.

You can either use npx to use it :

npx downdoc -o out.md README.adoc

Or install it using mise:

mise use npm:downdoc@latest
downdoc -v

All hail to ASCIIDOC !

Cover image by Charlotte May

Changing the menu from your Roq powered blog

Kosmik — Wed, 21 May 2025 14:43:16 +0000

Roq, as many other static site generators, uses a template engine to generate the final HTML. The template engine used by Roq is Qute. It’s a powerful engine that -amongst other things- leverages template inheritance.

There is a small introduction on iamroc.

I read it, I re-read it, I thought I had understood. I hadn’t understood. So you’re like me, and like to understand how things are build, follow me.

If you just want to change the menu layout, you can skip the first two chapters

Hypothesis

I will make the following assumptions:

You have a Roq powered blog. That seems obvious, but at least, now we know.
Tour blog uses the default theme: The one and only roq-default theme

Because by default any blog post is part of the posts collection, it’s setup to use the :theme/post template.

What we want to achieve

Whate we’re going to do in this blog post is to move the menu from the left side of the page to the top of the page.
As below :
From this

To this

Inheritance

A template can have a parent but can also have multiple children may they be partials/fragment.

To be able to determine what HTML is expected to be generated for a given page, the Qute engine will look up its layout inheritance tree, combine it with the page content and generate the final HTML.

The default inheritance tree layout for your blog post pages is as follows:

So that you don’t have do it yourself, I’ve searched where the main page structure is actually contributed. It’s in the theme-layouts/roq-default/main.html file.

---
layout: roq-default/default
---

{@io.quarkiverse.roq.frontmatter.runtime.model.Site site}

<aside class="sidebar main">
  {#insert header}
  <header>
    {#insert about}{#include partials/roq-default/sidebar-about /}{/}
    {#insert menu} ①
    {#include partials/roq-default/sidebar-menu menu=cdi:menu.items /} ②
    {/}
  </header> <!-- End Header -->
  {/}
  {#insert footer}
  <footer>
    {#insert contact}{#include partials/roq-default/sidebar-contact /}{/}
    {#insert copyright}{#include partials/roq-default/sidebar-copyright /}{/}
  </footer> <!-- End Footer -->
  {/}
</aside> <!-- End Sidebar -->
<div class="content-box clearfix">
  {#insert /} ③
</div>

The {#insert <name>} syntax allows to define a new named section. The menu section, in our case.
In this case, the templates also provides a default value for the section, that we will have to override.
The {#insert /} syntax is used to include the content of the current page inheriting the layout.

What if I could override the `menu` section?

Yes of course this is possible and even the right way to go.

We can create a template if our project called Main.html and save it to the templates/layouts/rod-default folder. The template will inherit from the theme-layouts/roq-default/main.html template, and override the menu section.

---
layout: theme-layouts/roq-default/main
---

{#menu} {/} ①

{#include partials/roq-default/sidebar-menu menu=cdi:menu.items /} ②

{#insert /} ③

Redifine an empty menu section (to remove it from the side bar)
Reusing the same partials but injecting elsewhere.
Insert the content of the current page inheriting the layout.

The dependency tree as now a small injection:

And all I need now is little bit of css (in your src\main\resources\web.app folder), and we are off for a good start :

.menu {
  border-radius: 10px;
  width: 100%;
  padding-top: 2rem;

  a {
    text-decoration: none;
  }

  ul {
    list-style-type: none;
    display: grid;
    grid-auto-rows: min-content;
    grid-template-columns: repeat(3, 1fr);
    gap: 10px;
    grid-auto-flow: column;
  }
}

Conclusion

Inheritance is not hard to understand, but you should have your theme code open to be sure where you can hook and how.

If you want more in depth documentation, you can check the 👉 Qute documentation.

I’m sure you have a whole lot of ideas, and I’d be glad to see your roq site, so don’t hesitate to share in the comments.

Adding mermaid to your Roq powered blog

Kosmik — Wed, 14 May 2025 12:59:39 +0000

Having wunderbar diagrams in your blog

So you have a Roq powered blog, and you want to add Mermaid to it. More generally, you want to add content to your blog that is not handled by Roq, but rather uses a third party js library.

I will focus on adding Mermaid, but the same approach can be used for any other library.

Simply use your imagination.

⚠️
Roq philosophy is to generate as much as possible at build time and to do as little as possible at runtime. Alas, this is not always possible or suitable for you need. So once you have considered AND excluded build time generation, here is a workaround.

To add js lib to your Roq blog, you have two ways.

Adding the third party library dependency using mvnpm

If the third party library you're looking for is available on mvnpm, you can simply add it to your pom.xml file as a dependency.

<dependency>
    <groupId>org.mvnpm</groupId>
    <artifactId>mermaid</artifactId>
    <version>11.6.0</version>
    <scope>provided</scope>
    <exclusions> 1️⃣
        <exclusion>
            <groupId>*</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>

1️⃣ We don't want any transitive dependencies, you might not have to add exlusions for other libraries

Bootstrapping the lib

We need to import the lib and bootstrap it in our project, so that the web bundler can do its black magic.

import mermaid from 'mermaid/dist/mermaid.esm.min.mjs';

mermaid.initialize({ startOnLoad: true });

Adding a custom tag to our blog

To prevent the blog's writer from having to repeat the needed steps to generate the diagram, we will create a custom tag.

In the <root>/template/tags folder, create a new file called mermaid.html and add the following code:

<pre class="mermaid">
    {nested-content}
</pre>

Using the newly created tag

In your blog post you can now use the new tag like this:

{#mermaid}
{|
---
config:
layout: elk
look: handDrawn
theme: dark
---
flowchart TB
A[Start] --> B{"Let's try Roq"}
B -->|Yes| C[I am Roq]
B -->|No| D["Ohh noo :("]
|}
{/}

You already saw the rendered result at the beginning of this post, but I grant you it was marvelous, so let's look at it again.

What about the other way ?

You can always skip the first two steps and amend your custom tag as follows:

<pre class="mermaid">
    {nested-content}
</pre>
<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

Hope you've learned something new, and maybe given you ideas ;)

More guides here and you can always follow/give a star on the github repo.

So you wanna know where your maven dependency version comes from ?

Kosmik — Wed, 26 Mar 2025 09:29:32 +0000

You work with a complex maven project. That's a fact, otherwise you wouldn't be here, searching to uncover a way out of its dependencies maze.

Your project probably has a parent, as your parent might also have one.

You may have boms in your dependency management, but your parent certainly has one too.

You defined properties, and guess what, so have at least a dozen direct or transitive dependencies.

So after having done your research, not relying on some gibberish from whatever AI assistant you usually use, you found out about :

mvn dependency:tree

While that does give you a nice console output, chances are it's not enough. Again, you wouldn't be here if it was.

It does tell you the dependency version used, where they were pulled out from, but why is that specific version used can still be unclear.

Let's say you have a dependency somewhere in you project hierarchy defined as followed:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>${spring.boot.version}</version>
</dependency>

The property value is defined to be 3.4.4 in your parent, but the the dependency:tree plugin output tells you the value is 2.7.9, and so you rightfully ask yourself, why the f... is that.

Well it just happens that this can be easily solved using the help plugin:

mvn help:effective-pom -Dverbose=true

It will spit out your pom as seen by the great maven itself. The only issue is that chances are great that your console buffer will be overflowed. But we are smarter than that.

mvn help:effective-pom -Dverbose=true | grep spring.boot.version

It will give you something like :

 <spring.boot.version>2.7.9</spring.boot.version>  \
    <!-- com.acme:your.exotic.dependency:17.0.18-RC3-FINAL-GA, line 253 -->

There! You have it! Of course your exotic dependency is the culprit. Now that you know it, it will be much easier to fix. Don't you think ?

To `Gather` or not to `Gather`? That is the question.

Kosmik — Mon, 24 Mar 2025 08:49:34 +0000

Mais de quoi va-t-on parler ?

De Java. Oui je préfère le dire dès le début. Cet article va parler de Java !

Les gatherers sont le premier ajout d'importance à l’API java.util.Streams depuis sa sortie, et on parle de 2014. Cela signifie qu’il ne s’était pas passé grand-chose depuis environ longtemps.
Arrivés en preview en Java 22, il sont finalement standards en Java 24.

Table des matières

Remise à niveau
Rappels
Collectors vs Gatherers
L'interface Gatherer
Let's code!
- On recode la méthode filter
- Un Stream avec un index !?
- Un groupingBy, mais pas terminal.
- Et maintenant, on fusionne des Streams!

Remise à niveau

Même si on ne va pas faire une revue complète de l'API java.util.Streams, je vous propose de commencer par un petit quizz, tranquilles, posés.

Quiz 1/3

1 public class Quizz {
2    public static void main(String[] args) {
3        getPeople()
4            .map(person -> person.getName())
5            .toList();
6    }
7 }

Admettons que la méthode getPeople renvoie une instance de Stream de 10 objets de type Person.

Ici, le code est simple, on applique la méthode map qui prend en paramètre une Function, qui extraie une String à partir d'une instance de Person en renvoyant le résultat de la méthode Person.getName().

La question est :

Combien de fois la ligne 4 est-elle invoquée ?

① 1 fois ?
② 10 fois ?
③ Non Jérôme, elle n'est pas invoquée la ligne 4.
④ It depends!

spoiler
Vous êtes-vous dit qu’il y avait plusieurs bonnes réponses ?

La bonne réponse est:

④ It depends!

En réalité, la question était mal posée. La question, aurait du être :

"Est-ce que la méthode map est invoquée une fois, 10 fois, ainsi de suite ?" ou "Est-ce que la fonction qui est passée en paramètre de la méthode map est invoquée ?"

La méthode map, est bien appelée une seule fois, par contre, la fonction qui lui est passée en paramètre, elle, est bien invoquée 10 fois.

Il faut systématiquement différencier les méthodes de l’API Stream, qui ne font que de la configuration de pipeline, et les fonctions/predicats/... qu’on leur passe.

Quiz 2/3

Bon, ok, on a compris. À partir de maintenant, la question portera systématiquement sur le nombre d’invocations de la Function passée en paramètre de la méthode map.

1 public class Quizz {
2   public static void main(String[] args) {
3        getPeople()
4            .map(person -> person.getName());
5    }
6 }

La question est :

Combien de fois la ligne 4 est-elle invoquée ?
① 1 fois ?
② 10 fois ?
③ Non Jérôme, elle n'est pas invoquée la ligne 4.

spoiler

La bonne réponse est :

③ Non Jérôme, elle n’est pas invoquée la ligne 4.

Dans un Stream, il y a deux types d’opérations :

Des opérations intermédiaires.
Des opérations finales.

Les opérations intermédiaires ne font que configurer un pipeline d’exécution, elles ne déclenchent rien. Tant qu’on n’a pas appelé une méthode finale sur un stream, il ne se passe rien du tout.

Quiz 3/3

1 public class Quiz {
2     public static void main(String[] args) {
3         getPeople()
4             .map(person -> person.getName())
5             .count();
6     }
7 }

La question est :

Combien de fois la ligne 4 est-elle invoquée ?
① 1 fois ?
② 10 fois ?
③ Non Jérôme, elle n'est pas invoquée la ligne 4.

spoiler

La bonne réponse est :

③ Non Jérôme, elle n’est pas invoquée la ligne 4.

Eeeeeeet oui, l’API stream est intelligente, et parmi les opérations terminales, il y en a certaines qui possèdent des raccourcis. Et c'est le cas de la méthode count qui est capable d’évaluer si toutes les opérations qui ont été exécutées avant elle peuvent avoir un impact sur la cardinalité de ce qu’il y a en sortie.

Ici, une seule opération map n’aura aucun impact sur la cardinalité, et donc, inutile de l’invoquer, ça n’a aucun intérêt. On n’a pas besoin de transformer des personnes en chaînes de caractères pour savoir qu’il y en à 10.

C'est assez important de comprendre que vous n'avez pas de garantie d'invocation. Et si, par exemple, vous faites partie de la team peek-
💀 ARRÊTEZ-CA MAINTENANT 💀-, et que vous utilisez un count, votre peek risquerait bien de ne jamais être invoqué.

Rappels

Il y a des méthodes intermédiaires : map, filter, etc.
Il y a des méthodes terminales : anyMatch, toList, count, etc.

L’invocation d’une opération terminale est le seul déclencheur de l’utilisation d’un pipeline. Je peux enchaîner autant d’opérations intermédiaires que je veux, il ne se passera jamais rien.

Et dès que j’appelle une opération terminale, je consomme mon stream, et je ne peux plus rien en faire. Et évidemment, un peu tautologique, je ne peux pas avoir deux méthodes terminales qui s’enchaînent.
Certaines opérations terminales possèdent des courts-circuits.
On peut implémenter un nombre infini ♾️ d'opérations terminales grâce à l'API Collector.
Il existe un nombre fini d'opérations intermédiaires fournies pas l'API

Évidemment, l’API gatherer est là pour rattraper cette terrible injustice et nous laisser la capacité de coder toutes les opérations intermédiaires que l’on veut.

Collectors vs Gatherers

Nous sommes habitués à l'API Collectors, mais tout de même rafraîchissons nous la mémoire.

Les Collectors

Collector collector;①

Collectors.groupingBy(...);②

stream.collect(collector);③

① L'interface Collector que nous devons implémenter.
② La classe Collectors, qui fourni un certain nombre de collectors déjà implémentés
③ L'utilisation d'un collector via la méthode Stream#collect

Et maintenant leurs jumeaux

Les Gatherers

Gatherer gatherer;①

Gatherers.windowFixed(...);②

stream.gather(gatherer);③

① L'interface Gatherer que nous devons implémenter.
② La classe Gatherers, qui fourni un certain nombre de gatherers déjà implémentés. Ici windowFixed qui accumule n éléments avant de les pousser dans le stream sous forme de liste.
③ L'utilisation d'un gatherer via la méthode Stream#gather

Code utilisé pour les exemples

À partir de maintenant, tous les exemples suivront le code suivant


public void main() throws IOException {
    Stream<Oeuvre> oeuvres = Reader.read().stream();
    prettyPrint(
       oeuvres.gather(
          filter(oeuvre -> oeuvre.titre().contains("N")) ①
       )
    );
}

public record Oeuvre(
   String titre, 
   Integer anneeParution, 
   boolean perdue) {
}

① C'est ici que nous placerons les gatherer custom

L'interface `Gatherer`

💡
Le code que nous allons regarder n'est pas le vrai code, mais une version épurée de l'interface.
Si vous voulez voir le vrai code, je rappelle que tout ceci est libre d'accès

package java.util.stream;

public interface Gatherer<T, A, R> {

    default Supplier<A> initializer(); ①

    Integrator<A, T, R> integrator(); ②

    default BinaryOperator<A> combiner(); ③

    default BiConsumer<A, Downstream<? super R>> finisher(); ④
}

On peut déjà constater que l'interface fait une utilisation massive des génériques.

Pour les illustrer, prenons l'exemple d'un gatherer qui réimplémente l'opération intermédaire map (d'une instance d'Oeuvre vers une String en utilisant la méthode Oeuvre#titre()).

Le type T représente le type de l'objet entrant, ici Oeuvre. Le type A représente le type de l'état du gatherer (on y reviendra). Le type R représente le type de retour du gatherer, ici String.

① La méthode `initializer`

Elle permet d'initialiser l'état, si besoin. Elle possède une implémentation par défaut et renvoie un Supplier d'état.

⚠️
Attention, elle ne renvoie pas un nouvel état, mais un Supplier d'état.

② La méthode `integrator`

Son rôle est de retourner un Integrator. C'est l'objet qui va intervenir sur le stream, et sur lequel nous allons revenir tout au long des exemples.

⚠️
Attention, encore une fois, elle n'implémente pas la méthode qui agit. C'est une factory.

③ La méthode `combiner`

Elle renvoie un BinaryOperator<X>, c'est à dire, une BiFunction<X,X,X>. Son rôle est de combiner les états en cas d'exécutions parallèles.

④ La méthode `finisher`

Elle renvoie un BinaryConsumer, qui permet en cas de besoin d'exécuter une action en fin de traitement.

Let's code !

Oui, ok, t'es mignon, mais c'est quand même super abstrait ce que tu nous racontes là.

Et c'est vrai !

Je vous propose donc de redévelopper la méthode filter dont vous connaissez déjà le fonctionnement.

On recode la méthode `filter`

C'est un gatherer simple, donc nous n'aurons besoin que d'implémenter la méthode integrator.

Nous allons l'implémenter à base d'anonymous inner class. À l'ancienne.

package org.github.jtama.gatherornot;

import java.util.function.Predicate;
import java.util.stream.Gatherer;

public class Filter implements Gatherer<Oeuvre, Object, Oeuvre> {

    private final Predicate<Oeuvre> filter;

    Filter(Predicate<Oeuvre> filter) {
        this.filter = filter;
    }

    @Override
    public Integrator<Object, Oeuvre, Oeuvre> integrator() {
        return new Integrator<Object, Oeuvre, Oeuvre>() {
            @Override
            public boolean integrate( ④
              Object state, ①
              Oeuvre oeuvre, ②
              Downstream<? super Oeuvre> downstream) { ③
                if (filter.test(oeuvre)) {
                    return downstream.push(oeuvre);
                }
                return true;
            }
        };
    }
}

① L'état que nous ignorons pour l'instant.
② L'instance d'Oeuvre en cours de traitement dans le stream.
③ Le downstream représente ce qui vient après dans le stream.
④ La méthode retourne un boolean qui permet d'indiquer à l'API stream si le gatherer accepte d'autres éléments. Comme, il s'agit d'un filtre, nous renvoyons toujours true ou la propagation du résultat de la méthode downstream.push.

Ici, pas vraiment de difficulté, mais un code vraiment verbeux que l'on va pouvoir simplifier.

L'implémentation de la classe Integrator ne contient qu'une méthode. On peut donc écrire une lambda.

package org.github.jtama.gatherornot;

import java.util.function.Predicate;
import java.util.stream.Gatherer;

public class Filter implements Gatherer<Oeuvre, Object, Oeuvre> {

    private final Predicate<Oeuvre> filter;

    Filter(Predicate<Oeuvre> filter) {
        this.filter = filter;
    }

    @Override
    public Integrator<Object, Oeuvre, Oeuvre> integrator() {
        return (_, oeuvre, downstream) -> { ①
            if (filter.test(oeuvre)) {
                return downstream.push(oeuvre);
            }
            return true;
        };
    }
}

① La variable state n'étant pas utilisée, on peux utiliser un _.

L'implémentation de la classe Filter ne contient également qu'une méthode. Donc rebelote, transformation en lambda.

package org.github.jtama.gatherornot;

import java.util.function.Predicate;
import java.util.stream.Gatherer;

public class Filter {
    public static Gatherer<Oeuvre, ?, Oeuvre> filter(Predicate<Oeuvre> filter) {
        return () -> (_, oeuvre, downstream) -> {
            if (filter.test(oeuvre)) {
                return downstream.push(oeuvre);
            }
            return true;
        };
    }
}

Et voilà. C'est plus court. C'est mieux.

Non.

On a beaucoup perdu en lisibilité, mais les interfaces Gatherer et Integrator offrent des méthodes utilitaires pour la regagner.

package org.github.jtama.gatherornot;

import java.util.function.Predicate;
import java.util.stream.Gatherer;
import java.util.stream.Gatherer.Integrator;

public class Filter {
    public static Gatherer<Oeuvre, ?, Oeuvre> filter(Predicate<Oeuvre> filter) {
        return Gatherer.of(
                Integrator.ofGreedy(①
                    (_, oeuvre, downstream) -> {
                        if (filter.test(oeuvre)) {
                            return downstream.push(oeuvre);
                        }
                        return true;
                    }));
    }
}

① On utilise ici la méthode ofGreedy (pour ceux qui ne parlent pas couramment anglais, greedy veut dire avide, allez tout de suite regarder le film Se7en), qui permet de dire à l'API stream que ce Gatherer n'interrompra jamais de lui même la consommation du stream, et qui permet à l'API stream de faire des optimisations.

À partir de maintenant, nous utiliserons toujours cette façon d'écrire le code.

Un stream avec un index ?

N'avez-vous déjà pas eu envie d'accéder à l'index de l'élément en cours de traitement ? N'avez vous pas déjà essayé l'implémentation suivante ?

Stream<Oeuvre> oeuvres = Reader.read().stream();
AtomicInteger index = new AtomicInteger(0);①
oeuvres.map(value -> new Tuple<>(index.getAndIncrement(), value)));②

① On utilise un AtomicInteger pour conserver/incrémenter l'index
② En admettant que la classe Tuple existe

C'est une approche qui fonctionne très bien jusqu'à ce que quelqu'un ait la bonne idée d'ajouter un petit .parallel() avant.

Et là :

Bon je me permets d'ajouter qu'une bonne vieille boucle for est certainement ce qu'il vous faut.

Mais, pas d'inquiétude, on va pouvoir arranger ça.

Commençons par noter, que pour la première fois depuis le début de l'article nous allons avoir besoin de quelque chose pour maintenir l'état.

Et comme l'API n'est pas trop mal faite, dans un Gatherer, le nom de ce concept est state. ¯\(ツ)/¯

package org.github.jtama.gatherornot;

import java.util.stream.Gatherer;
import java.util.stream.Gatherer.Integrator;

public class WithIndex {

  public static Gatherer<Oeuvre, Counting, Tuple<Integer, Oeuvre>> withIndex() {

    return Gatherer.ofSequential( ③
            () -> new Counting(), ①
            Integrator.ofGreedy(
             (state, oeuvre, downstream) -> downstream.push(new Tuple<>(state.index++, oeuvre)))); ②
  }

  static class Counting {
      int index;
  }
}

① Notre Supplier d'état, ici une instance de la classe counting qui contient l'index
② L'implémentation est exactement la même
③ On utilise la méthode ofSequential, qui permet d'interdire l'exécution du gatherer en parallel, même si le développeur le demande.

Un `groupingBy`, mais pas terminal.

Pour rappel, la méthode groupingBy est une opération finale, je vous encourage à aller lire la doc si vous voulez en savoir plus.

Ce que l'on cherche à implémenter c'est une opération intermédiaire qui va regrouper un ensemble cohérent d'élément dans une liste avant de les relacher dans le stream.

Par exemple avec un stream contenant les œuvres de Shakespeare classées par date de parution, j'aimerai pouvoir regrouper les oeuvres par année. Et tant qu'on y est, j'aimerais pouvoir l'utiliser pour d'autres objets, avec d'autres critères de regroupement.

Cela signifie que nous allons faire un Gatherer générique.

Pour une fois, on va commencer en regardant l'utilisation !

Stream<Oeuvre> oeuvres = Reader.read().stream();
oeuvres.gather(series(Oeuvre::anneeParution)));①

① Je passe à ma factory de gatherer un extracteur de clef.

Et maintenant l'implémentation :

package org.github.jtama.gatherornot;

import java.util.ArrayList;
import java.util.List;
import java.util.function.Function;
import java.util.stream.Gatherer;

public class Serie {

    public static <K,V> Gatherer<V, State, List<V>> series(Function<V,K> keyExtractor) {
        return Gatherer.ofSequential(①
                State::new,②
                Gatherer.Integrator.ofGreedy((state, value, downstream) -> {
                    // First invocation or the same key value
                    if (state.key == null || 
                            keyExtractor.apply(value).equals(state.key)) { ③
                        state.values.add(value);
                        state.key = keyExtractor.apply(value);
                        return true;
                    }
                    var more = downstream.push(state.values); ④ 
                    state.values = new ArrayList<>();
                    state.key = keyExtractor.apply(value);
                    state.values.add(value);
                    return more;
                }),
                (state, downstream) -> downstream.push(state.values));
    }

    public static class State<K,V> {
        private K key;
        private List<V> values = new ArrayList<>();
    }
}

① Oui on va rester en séquentiel, sinon il faudra s'asseoir sur le fait d'avoir de la donnée ordonnée.
② L'état va maintenir la clef de regroupement et la liste pour l'accumulation des valeurs regroupées.
③ Si c'est le premier tour de boucle ou que la valeur de regroupement est égale à celle de l'état, on accumule et réclame plus d'éléments.
④ Sinon, on pousse les valeurs déjà accumulées en conservant , et puis on reinitialise l'état et on propage le retour de l'invocation de la méthode downstream.push.

Je me rend bien compte que ce gatherer est un peu plus compliqué, mais l'avantage, c'est que si je veux regrouper mes éléments en fonction de la première lettre du titre, je peux.

Stream<Oeuvre> oeuvres = Reader.read().stream();
oeuvres.sorted(Comparator.comparing(Oeuvre::titre))
        .gather(series(oeuvre -> oeuvre.titre().substring(0,1)));

Et ça fonctionnerait même avec une hypothétique classe Person! Si je veux regrouper un stream de personne par année de naissance :

Stream<Person> persons = Reader.read().stream();
persons.gather(series(Person::birthDate);

Et maintenant, on fusionne des `streams` !

Il n'est pas possible, simplement, à ce jour de fusionner des stream. Ce que je veux je veux obtenir est l'équivalent du join de RxJava

Mais en plus strict.

Voilà comme ça.

Plus précisément je ne veux permettre que des paires complètes.

On va reprendre le principe de commencer par l'utilisation.

Stream<Oeuvre> oeuvres = Reader.readUnordered().stream();
prettyPrint(oeuvres.gather(merge(streamToBeMerged)));

Le code ci-dessus devrait produire :

┌──────────────────────────┬─────────────────────────┐
│Revue de presse           │Titre                    │
├──────────────────────────┼─────────────────────────┤
│Beaucoup  de  bruits  pour│Peines d amour gagnées   │
│rien                      │                         │
├──────────────────────────┼─────────────────────────┤
│Je ne m en  souviens  même│Cardenio                 │
│plus.                     │                         │
├──────────────────────────┼─────────────────────────┤
│Jamais entendu parler     │La Tempête               │
├──────────────────────────┼─────────────────────────┤
│Numéro  1  sept   semaines│Les Deux Gentilshommes de│
│d affilées                │Vérone                   │
├──────────────────────────┼─────────────────────────┤
│Meilleure pièce de l année│Les Joyeuses Commères  de│
│                          │Windsor                  │
├──────────────────────────┼─────────────────────────┤
│Un chef d oeuvre          │Mesure pour mesure       │
└──────────────────────────┴─────────────────────────┘

Et maintenant l'implémentation :

package org.github.jtama.gatherornot;

import java.util.Iterator;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class Merge {

  public static <T,Y> Gatherer<Y, Iterator<T>, Tuple<T, Y>> merge(Stream<T> stream) {
    return Gatherer.ofSequential(
            stream::iterator, ①
            Gatherer.Integrator.of(
             (state, item, downstream) -> {
                if (state.hasNext()) ②
                   return downstream.push(new Tuple<>(state.next(), item));
                return false; ③
              }));
    }
}

① Pour savoir si il me reste quelque chose dans mon stream "à fusionner" je ne peux directement faire un Stream.hasNext, ou Stream.next (Cette notion n'est pas cohérente la philosophie Stream). Je dois avoir un accès direct aux éléments de la collection. Je dois passer par un Iterator.
② Si mon itérateur "à fusionner" en a encore dans le ventre, on pousse au dowstream.
③ Sinon on interrompt la consommation du stream. Je rappelle qu'on a dit qu'on ne voulait que des paires complètes. Et puis c'est mon code, et je fais ce que je veux. Si vous voulez une autre implémentation, je ne vous empêche pas.

On y va ou pas ?

Alors que cet article touche à sa fin, j'espère vous avoir montré qu'il existe en effet des cas pour lesquels les Gatherer vont nous permettre de répondre à de réels besoins. J'aimerais aussi attirer votre attention sur le fait que si ils ont mis autant de temps à arriver, c'est certainement parce qu'on peut déjà faire beaucoup avec l'existant, pourvu qu'on prenne le temps de regarder ce que l'on a déjà à disposition.

Vous trouverez dans le dépôt github joint, tout le code présenté et même plus.

jtama / to-gather-or-not-to-gather

To Gather, or not to Gather, that is the question.

Run locally

Use JBang !

Slides

Readable version available on Github Pages → ici

Generate

jbang qrcode@maxandersen -i slides/images/qr_inlay.png <open feedback url> --qr-colo="linear-gradient(90deg, rgba(36,14,0,1) 0%, rgba(9,121,105,1) 35%, rgba(0,212,255,1) 100%);"
jbang qrcode@maxandersen -i slides/image/github.png https://github.com/jtama/to-gather-or-not-to-gather
podman container run --rm -v $(pwd)/slides:/documents -w /documents asciidoctor/docker-asciidoctor:1.80.0 asciidoctor-revealjs -r asciidoctor-diagram index.adoc

Run locally

podman container run --name prez --rm -d -p 8080:80 -v $(pwd)/slides:/usr/share/nginx/html nginx
podman container run --name coder --rm -d -p 8443:8443 -v $(pwd)/app:/config/workspace ghcr.io/jtama/java_jbang_codeserver:latest

View on GitHub

Et surtout n'oubliez pas :

OpenRewrite: Refactoring as code

Kosmik — Fri, 07 Feb 2025 09:39:44 +0000

📌 NOTE Mieux vaut prévenir que guérir, je n’utiliserai pas le mot reusiner, et certainement pas non plus le mot refactoriser. Cette note sera donc pleine d’anglicismes. La vie.
Il y aura aussi du code tronqué, mais pas d’inquiétude, il y a un lien à la fin de l’article vers le dépôt qui contient le code complet.

Alors comme ça vous voulez refactorer votre code ? Voici les différentes options qui s’offrent habituellement à vous (je sais, il y en a d’autres) :

Pour commencer le fameux (ou l’infâme) Chercher/Remplacer, plus connu sous le nom de Ctrl+F/Ctrl+R.
La technique un peu plus avancée de l’expression régulière, aussi connue sour le nom de Les regexps c’est illisible 15 jours après les avoir écrites.
Mais de façon plus probable, vous utiliserez le menu click droit de votre IDE, ou un bon paquet de raccourcis clavier, technique également connue sous le nom de tu peux toujours courir, jamais tu reproduiras ce que j’ai fait.

Si vous êtes dans le cas d’un refactoring qui nécessite plus d’une étape et/ou qui touche à de nombreux fichiers, vous êtes très probablement condamné à suivre un guide de migration, aussi triste qu’un long dimanche de pluie.

Disons que vous vouliez par exemple migrer de JUnit 4 à JUnit 5, ou bien de Spring Boot 2 à Spring Boot 4, ou d'Hibernate 4 à Hibernate 6, ou encore de Java 8 à Java 21. Il vous faudrait pour cela :

Faire les montées de versions dans vos fichiers de configuration Maven ou Gradle
Changer vos imports
Changer vos annotations
Changer vos invocations de méthodes
Peut-être changer vos signature de méthodes
Changer les noms de propriété
Je ne sais quoi encore

C’est chronophage, lourd, sujet aux erreurs et aux oublis.

Mais il y a un petit nouveau dans le monde du refactoring : OpenRewrite.

The big picture 📸

OpenRewrite est un outil de refactoring qui a été créé par Moderne.

Il a commencé avec un fort accent sur Java (et ses fichiers de configuration : properties et yaml), mais il s’étend maintenant à d’autres langages et formats de fichiers :

Langages de programmation : Java, Kotlin, Groovy
Formats de données : XML, Properties, YAML, JSON, Protobuf
Outils de build : Maven, Gradle

Je me concentrerai uniquement sur l’écosystème Java dans cet article, même si des migrations existent pour Kubernetes, AWS, .Net, CircleCI, Github Actions et encore bien d’autres.

Les concepts

Les principaux concepts d’OpenRewrite que vous devez garder à l’esprit sont les suivants.

Lossless Syntax Tree

Le code source que vous souhaitez consulter et transformer est rendu accessible via un LST. C’est un arbre de syntax abstrait (AST) contenant en plus des informations de formatage. Une représentation asbtraite du code source pour le rendre plus facile à comprendre, à interroger ou à manipuler.

Recette 🍴

Ou recipe dans la langue de Shakespeare est l’élément atomique pour travailler sur le code. Elle peut contenir chacun des éléments suivants (tous étant optionnels):

Un/des paramètre(s) pour personnaliser le comportement de la recette.
Une liste de pré-conditions, lui permettant de savoir si elle doit traiter un fichier source.
Un visitor qui permet d’effectuer ou non des modifications sur le code source.
Une liste de recettes

Ce dernier point signifie que la façon d’implémenter un refactoring complexe est de composer des recettes, et à la fin, cela s’appelle aussi une recette.

¯\(ツ)/¯ Ne blâmez pas le messager.

Le pattern visitor 👾

Je l’ai mentionné juste au-dessus, mais le traitement d’une recette passe par le pattern visitor. Chaque rencontre d’un élément du lst va générer un événement qui sera transmis à tous les visiteurs déclarés. Pour vous donner une idée, il y a actuellement 73 types d’événements différents associés à la visite pour du code java, chacun associé à des méthodes avec des signatures différentes.

Qu'y a-t-il dans la boîte 📦 ?

OpenRewrite est plus qu’un framework monolithique. Ces différents composants sont :

Un module core, qui contient toute la représentation générique d’un LST et la logique de refactoring commune.
Un module pour chaque langage, avec des API et SDK dédiés pour une cible spécifique (Java, XML, Yaml, etc).
De nombreux modules contenant des recettes pour un sous-ensemble d’intérêt spécifique, telles que les recettes de frameworks de test, les recettes de Spring, les recettes de Quarkus, l’identification et la correction des problèmes d’analyse statique, etc.

Le catalogue 📓

La grande puissance d’Openrewrite est la mise à disposition de recettes déjà disponible pour traiter un très grand nombre de cas sans que l’on ait à produire la moindre ligne de code.
Il y a actuellement plus de 500 recettes disponibles pour Java, et il y en a probablement plus pour les autres langages et formats de fichiers.

Le catalogue est disponible en ligne à l’adresse suivante : https://docs.openrewrite.org/recipes

Il contient toutes les recettes produites par l’équipe de Moderne, triées par catégories, documentées et avec des exemples d’utilisation. Mais il contient également d’autres sections intéressantes. On y trouve par exemple une liste des recettes les plus populaires, comme un accélérateur de recherche, mais aussi une page dédiée aux recettes écrites par d’autre, comme Apache Camel, AWS, Quarkus, Morphia et bien d’autres.

Execution d'une recette ⚙️

Attaquons-nous à la partie la plus simple de cet article : l’exécution d’une recette. Petit prérequis: vous devez avoir Maven ou Gradle installé sur votre machine. Que vous vouliez exécuter une recette qui concerne Java ou Kubernetes, la procédure est la même. Désolé.

Pour exécuter une recette, vous avez deux options.

En modifiant vos descripteurs de build

Je vais prendre l’exemple d’un projet Maven, mais les étapes à suivre sont les mêmes pour un projet Gradle.

Pour commencer, vous devez ajouter le plugin rewrite-maven-plugin à votre fichier pom.xml :

<build>
  <plugins>
    <plugin><1>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>5.46.1</version><2>
    </plugin>
  </plugins>
</build>

Déclaration du plugin
Adapter le numéro pour utiliser la version la plus à jour

Ensuite, vous devez déclarer la recette que vous voulez exécuter. Ici par exemple la suppression de Cobertura qui n’est plus compatible avec un projet Java dont la version est supérieure à Java 11 :

<build>
  <plugins>
    <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>5.46.1</version>
      <configuration> ①
          <activeRecipes>
            <recipe>org.openrewrite.java.migrate.cobertura.RemoveCoberturaMavenPlugin</recipe> ②
          </activeRecipes>
      </configuration>
    </plugin>
  </plugins>
</build>

Configuration du plugin
Activation de la recette

Ajout de la dépendance dans laquelle se trouve la recette (si elle n’est pas dans le module core), ce qui donne la configuration complète suivante :

<build>
  <plugins>
    <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>5.46.1</version>
      <configuration>
        <activeRecipes>
          <recipe>org.openrewrite.java.migrate.cobertura.RemoveCoberturaMavenPlugin</recipe>
        </activeRecipes>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>org.openrewrite.recipe</groupId>
          <artifactId>rewrite-migrate-java</artifactId>
          <version>2.30.1</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

Pour exécuter la recette, il suffit de lancer la commande suivante :

$ mvn rewrite:run

Mais on ne veut pas modifier nos fichiers de build, n’est-ce pas ? Et on ne se trouve peut-être même pas dans un projet Maven ou Gradle.

Sans modifier vos descripteurs de build

Dans ce cas, il est possible de préciser directement tout dans la ligne de commande, mais celle-ci deviendra forcément plus complexe :

$ mvn -U org.openrewrite.maven:rewrite-maven-plugin:run <1>
   -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-java:2.30.1 ②
   -Drewrite.activeRecipes=org.openrewrite.java.migrate.cobertura.RemoveCoberturaMavenPlugin ③

Déclaration du plugin
Ajout de la dépendance de la recette
Activation de la recette

Intégration avec IntelliJ IDEA 🚀

Si vous utilisez IntelliJ IDEA au quotidien, il est possible d’exécuter une recette directement depuis l’IDE. Pour cela, il vous suffit de cliquer sur l’icône icon:play[] présent à la gauche de la recette que vous voulez exécuter.

Les principales fonctionnalités sont :

Pas besoin de faire de configuration maven\gradle
Pas besoin de connaître la ligne de commande
Autocompletion lors de la conception de recettes déclaratives

Concevoir ses propres recettes

Les façons de faire décrites ci-dessus ne sont valables que si les recettes ne prevous en avez besoin, il va falloir passer à l’étape suivante : la conception de recettes.

Pour concevoir ses propres recettes, le guide de bonne pratique d’Openrewrite nous dit que tout ce qui peut être faît de manière déclarative doit l’être. Oui, je sais, c’est dur. Vous êtes des développeurs, vous voulez écrire du code. Mais c’est comme ça.

Openrewrite nous offre pour cela un format de déclaration de recette en YAML. Oh oui youpiiiii 💃.

Recette déclarative (Declarative recipe)

Le format proposé par Openrewrite pour recette déclarative permet d’assigner une sous partie de ce qui est possible en Java. Il n’est notamment pas possible d’ajouter des paramètres, ni de renvoyer un visiteur dans une recette déclarative.

Voici un exemple de recette déclarative qui supprime la dépendance com.github.jtama:toxic d’un projet Maven. La recette doit-être écrite dans un fichier s’appelant rewrite.yml et se trouvant soit à la racine du projet, soit dans le répertoire META-INF/rewrite :

---
type: specs.openrewrite.org/v1beta/recipe ①
name: com.github.jtama.openrewrite.RemovesThatToxicDependency ②
displayName: Removes that toxic dependency ③
description: |
  Migrate from AcmeToxic ☠️ to AcmeHealthy 😇,
  removes dependencies and migrates code.  ④
tags: ⑤
  - acme
  - toxic
recipeList: ⑥
  - org.openrewrite.java.ChangeMethodTargetToStatic: ⑦
      methodPattern: com.github.jtama.toxic.toxic.BigDecimalUtils valueOf(..)
      fullyQualifiedTargetTypeName: java.math.BigDecimal
  - org.openrewrite.maven.RemoveDependency:
      groupId: com.github.jtama
      artifactId: toxic-library
  - org.openrewrite.maven.RemoveUnusedProperties:
      propertyPattern: .*toxic\.version
  - com.github.jtama.openrewrite.VousAllezVoirCeQueVousAllezVoir
---
type: specs.openrewrite.org/v1beta/recipe
name: com.github.jtama.openrewrite.VousAllezVoirCeQueVousAllezVoir
displayName: Ça va vous épater
description: |
  Rech. proj. pr proj. priv. Self Dem. Brt. Poss. S’adr. à l’hô. Mart
tags:
  - acme
preconditions:
  - org.openrewrite.text.Find: ⑧
      find: com.github.jtama
recipeList:
  - com.github.jtama.openrewrite.RemoveFooBarUtilsIsEmpty
  - com.github.jtama.openrewrite.RemoveFooBarUtilsStringFormatted
  - com.github.jtama.openrewrite.UseObjectsCompare

Déclaration du type de recette
Nom de la recette
Nom affiché lors de l’exécution de la recette
Description de la recette
Tags pour faciliter la recherche
Liste des recettes à exécuter
Passage de paramètre à une recette
Un exemple de précondition. ⚠️ Attention cette précondition va s’exécuter pour toutes les recettes de la liste.

Comme nous l’avons vu dans l’exemple précédent, cela permet de construire des recettes complexes en les composant les unes avec les autres.

Deux points d’attention sont à noter :

Le fichier doit s’appeler rewrite.yml, pas rewrite.yaml. 🙄
Pour que cette recette puisse s’exécuter, les 3 recettes filles doivent être accessibles dans le classpath

$ mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
   -Drewrite.recipeArtifactCoordinates=com.github.jtama:toxic-library-remover:1.0.0 \
   -Drewrite.activeRecipes=com.github.jtama.openrewrite.RemovesThatToxicDependency

Distribution

Vous êtes heureux de ce que vous avez fait, vous voulez partager votre recette avec le monde entier. Pour cela, il vous suffit de créer un module Maven ou Gradle et de le publier. Chacun pourra dès lors utiliser à loisir votre recette.

Le projet devra comprendre le fichier rewrite.yml et les dépendances nécessaires pour que la recette puisse s’exécuter.

On code nos recettes ✒️

Pour les chapitres suivants, nous partons du principe que vous voulez vous débarrasser d’une dépendance toxique (com.github.jtama:toxic-library:19.666.45-RC18-FINAL) qui comprend les classes suivantes :

package com.github.jtama.toxic;

import java.util.Comparator;
import java.util.List;

public class FooBarUtils {

    public String stringFormatted(String template, Object... args) {
        return String.format(template, args);
    }

    public static boolean isEmpty(String value) {
        if (value == null) return true;
        return value.isEmpty();
    }

    public static <T> boolean isEmpty(List<T> value) {
        if (value == null) return true;
        return value.isEmpty();
    }

    public <T> int compare(T o1, T o2, Comparator<T> comparator) {
        return comparator.compare(o1, o2);
    }
}

package com.github.jtama.toxic;

import java.math.BigDecimal;

public class BigDecimalUtils {

    public static BigDecimal valueOf(Long value) {
        return new BigDecimal(value);
    }
}

On ne se pose pas de question le code en lui-même, dîtes-vous que c’est un axiome.

Nous allons mettre en œuvre 2 types de recettes :

Refaster template recipes, ou recettes refaster. Simples, mais limitées.
Full custom java recipes (Bam ! Pas un seul mot français).

Refaster template recipes ⚡️

Ces patrons de recettes utilisent refaster.

Elles permettent de décrire simplement des templates recettes via du code. L’outillage OpenRewrite génère ensuite les recettes complètes à partir de ces templates.

Pour les utiliser il vous faut ajouter les dépendances suivantes à votre projet. Le code suivant est un copier/coller de la documentation officielle :

<dependencies>
    <!-- Refaster style recipes need the rewrite-templating annotation processor and dependency for generated recipes -->
    <dependency>
        <groupId>org.openrewrite</groupId>
        <artifactId>rewrite-templating</artifactId>
    </dependency>

    <!-- If you are developing recipes in Java, you'll need to bring in rewrite-java -->
    <dependency>
        <groupId>org.openrewrite</groupId>
        <artifactId>rewrite-java</artifactId>
    </dependency>

    <!-- The `@BeforeTemplate` and `@AfterTemplate` annotations are needed for refaster style recipes -->
    <dependency>
        <groupId>com.google.errorprone</groupId>
        <artifactId>error_prone_core</artifactId>
        <version>2.19.1</version>
        <scope>provided</scope>
        <exclusions>
            <exclusion>
                <groupId>com.google.auto.service</groupId>
                <artifactId>auto-service-annotations</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.12.1</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>1.18.32</version>
                    </path>
                    <path>
                        <groupId>org.openrewrite</groupId>
                        <artifactId>rewrite-templating</artifactId>
                        <version>1.19.1</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Nous pouvons maintenant créer une classe qui va supprimer les invocations des méthodes FooBarUtils.isEmpty :

@RecipeDescriptor(
            name = "Replace `FooBarUtils.isEmptyString(String)` with standard equivalent",
            description = "Replace `FooBarUtils.isEmptyString(String)` with ternary 'value == null || value.isEmpty()'."
    ) ①
    public static class RemoveStringIsEmpty {

        @BeforeTemplate
        boolean before(String value) {
            return FooBarUtils.isEmpty(value);
        }

        @AfterTemplate
        boolean after(String value) {
            return value == null || value.isEmpty();
        }

    }

Le nom et la description de la recette

Les annotations @BeforeTemplate et @AfterTemplate permettent de marquer les méthodes qui seront utilisées pour générer respectivement le template permettant de trouver les invocations à modifier et le template permettant de générer le code de remplacement.

Le deux méthodes doivent avoir le même nombre de paramètres avec les mêmes types et noms.

Il est possible de grouper les templates de recettes refaster comme suit.

package com.github.jtama.openrewrite;

import com.github.jtama.toxic.FooBarUtils;
import com.google.errorprone.refaster.annotation.AfterTemplate;
import com.google.errorprone.refaster.annotation.BeforeTemplate;
import org.openrewrite.java.template.RecipeDescriptor;

import java.util.List;

@RecipeDescriptor(
        name = "Remove `FooBarUtils.isEmpty` methodes usages",
        description = "Replace any usage of `FooBarUtils.isEMpty` method by standards equivalent.")
public class RemoveFooBarUtilsIsEmpty {

    @RecipeDescriptor(
            name = "Replace `FooBarUtils.isEmptyString(String)` with standard equivalent",
            description = "Replace `FooBarUtils.isEmptyString(String)` with ternary 'value == null || value.isEmpty()'."
    )
    public static class RemoveStringIsEmpty {

        @BeforeTemplate
        boolean before(String value) {
            return FooBarUtils.isEmpty(value);
        }

        @AfterTemplate
        boolean after(String value) {
            return value == null || value.isEmpty();
        }
    }


    @RecipeDescriptor(
            name = "Replace `FooBarUtils.isEmptyList(List)` with standard equivalent",
            description = "Replace `FooBarUtils.isEmptyList(List)` with ternary 'value == null || value.isEmpty()'."
    )
    public static class RemoveListIsEmpty {

        @BeforeTemplate
        public boolean before(List value) {
            return FooBarUtils.isEmpty(value);
        }

        @AfterTemplate
        public boolean after(List value) {
            return value == null || value.isEmpty();
        }
    }
}

Dans ce cas, la recette RemoveFooBarUtilsIsEmptyRecipes générée contiendra une liste de recette comprenant les recettes RemoveStringIsEmptyRecipe et RemoveListIsEmptyRecipe.

Dans les faits ce type de recette est relativement restreint. Le code ciblé doit pouvoir s’exprimer dans le bloc d’une méthode, et il sera toujours relativement simple et non paramètrable. Il ne pourra pas non plus retenir le style de formatage du code source d’origine.

Full custom java recipes ☕️

Toujours pas de français

La recette suivante va remplacer les invocations de FooBarUtils.stringFormatted(String, Object varargs) par des invocations de String.format(Object varargs). Celle-ci ne peut pas être réalisée avec un template, parce que le nombre de paramètres de ces méthodes ne peut être connu à l’avance.

Nous allons donc devoir passer à l’étape supérieure.

Toute recette doit étendre la classe org.openrewrite.Recipe. Nous allons la construire petit à petit.

import ... ①

public class RemoveFooBarUtilsStringFormatted extends Recipe {

    @Override
    public String getDisplayName() { ②
        return "Remove `FooBarUtils.stringFormatted`";
    }

    @Override
    public String getDescription() { ③
        return "Replace any usage of `FooBarUtils.stringFormatted` with `String.formatted` method.";
    }
}

Il y a évidemment beaucoup d’imports...
Le nom affiché lors de l’exécution de la recette
La description de la recette. Celle-ci DOIT finir par un point

Ajoutons maintenant la méthode qui retourne le visiteur.

import ...

public class RemoveFooBarUtilsStringFormatted extends Recipe {

    @Override
    public String getDisplayName() { ... }

    @Override
    public String getDescription() { ...}

    @Override
    public TreeVisitor<?, ExecutionContext> getVisitor() {
        return new Preconditions.Check(
                new UsesType<>("com.github.jtama.toxic.FooBarUtils", true), ①
                new ToStringFormattedVisitor()); ②
    }
}

La classe Preconditions.Check étend la classe TreeVisitor et permet de vérifier si une condition est remplie avant de lancer le visiteur. Ici, je valide que le type com.github.jtama.toxic.FooBarUtils est utilisé par une classe avant même de la visiter
La classe ToStringFormattedVisitor que nous allons créer pour effectuer les modifications sur le code source.

Il est maintenant temps de créer la classe ToStringFormattedVisitor qui va effectuer les modifications sur le code source.

private static class ToStringFormattedVisitor extends JavaIsoVisitor<ExecutionContext> { ①

        private final MethodMatcher toxicStringFormatted = new MethodMatcher("com.github.jtama.toxic.FooBarUtils stringFormatted(String,..)"); ②
        private final JavaTemplate stringFormatted = JavaTemplate.builder("#\{any(java.lang.String)}.formatted()").build(); ③
}

Ce visiteur va étendre la classe JavaIsoVisitor qui va nous fournir tous les points d’extension pour du code java, c’est une bonne base pour tout refactoring java.
Le MethodMatcher va permettre de matcher les invocations de la méthode FooBarUtils#stringFormatted. Ici, il ne s’agit pas d’une simple expression régulière. Le framework va faire des comparaisons au niveau sémantique.
Le JavaTemplate va permettre de générer l’invocation attendue.

Il est en effet possible de créer des éléments de source programmatiquement, mais créer de l'AST à la main est long et sujet à erreur, c’est possible, mais à vos risques et périls. Il est donc fortement déconseillé de le faire. Dans notre cas, je crée le template d’invocation minimal d’une méthode pour pouvoir le modifier ensuite.

Comme je veux remplacer une invocation de méthode par une autre, je vais surcharger la méthode JavaIsoVisitor#visitMethodInvocation.

Commençons petit.

private static class ToStringFormattedVisitor extends JavaIsoVisitor<ExecutionContext> {

    @Override
    public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, ExecutionContext ctx) {
        J.MethodInvocation methodInvocation = super.visitMethodInvocation(method, ctx);
        if (!toxicStringFormatted.matches(methodInvocation)) {
            return methodInvocation;
        }
        maybeRemoveImport("com.github.jtama.toxic.FooBarUtils");
        return methodInvocation;
    }
}

Le premier paramètre représente l’invocation de méthode courante. Nous commençons par laisser le JavaIsoVisitor faire son travail. Si l’invocation en cours ne correspond pas à ce que nous voulons modifier, nous la retournons sans faire de modification aucune.

Sinon, c’est le début de l’action. Tout d’abord, nous utilisons une méthode utilitaire fournie par la classe JavaVisitor qui nous permet de dire que si l’import com.github.jtama.toxic.FooBarUtils n’est plus utile, il peut être supprimé.

Et maintenant, nous allons générer le code voulu.

private static class ToStringFormattedVisitor extends JavaIsoVisitor<ExecutionContext> {

    @Override
    public J.MethodInvocation visitMethodInvocation(J.MethodInvocation method, ExecutionContext ctx) {

        List<Expression> arguments = methodInvocation.getArguments();
        J.MethodInvocation mi = stringFormatted.apply(
                getCursor(),
                methodInvocation.getCoordinates().replace(),
                arguments.get(0));
        mi = mi.withArguments(ListUtils.mapFirst(
                arguments.subList(1, arguments.size()),
                expression -> expression.withPrefix(Space.EMPTY)));
        return mi;
    }
}

Je commence par capter la liste des arguments de l’invocation de la méthode FooBarUtils#stringFormatted. Je vais ensuite appliquer le template java avec le premier argument: c’est l’instance de String qui contient le template de formattage.

Le premier argument, le curseur, peut-être vu comme un pointeur vers le code en cours de traitement dans l’arbre. Le deuxième argument, les coordonnées permettent d’indiquer si on veut remplacer le code, en ajouter avant ou après.

Enfin, je complète l’invocation de méthode en lui passant la liste des arguments restants. J’apporte néanmoins une petite modification, j’enlève tout espace au premier argument (c’est plus joli 😇).

Tester ses recettes 🧪

Le framework Openrewrite nous offre tout le nécessaire pour tester nos recettes. Parmi les bonnes pratiques d’écriture que je n’ai pas suivies dans cet article, il est d’ailleurs précisé qu’une fois le squelette de la recette écrit, il est préférable de commencer par écrire le test. Oui, on parle bien Test Driven Development Refactoring As Code - TDDRAC.

Les classes de tests doivent implémenter l’interface RewriteTest. Et c’est tout. Il existe une méthode default que l’on peut surcharger et qui est l’équivalent d’un beforeEach.

class RemoveFooBarUtilsStringFormattedTest implements RewriteTest {

    @Override
    public void defaults(RecipeSpec spec) {
        spec.recipe(new RemoveFooBarUtilsStringFormatted()) ①
          .parser(JavaParser.fromJavaVersion() ②
              .logCompilationWarningsAndErrors(true)
              .classpath("toxic-library") ③
           );
    }
}

La recette que je veux exécuter
La version de Java inférée à partir de la configuration du projet
J’ajoute la dépendance toxic-library au classpath du parser du test.

Et le code du test en lui-même est si clair, qu’il peut servir à documenter l’intention de la recette.

@Test
void removeStringFormattedInvocation() {
    rewriteRun(
      //language=java ①
      java(
            """
          import com.github.jtama.toxic.FooBarUtils;

          public class FullDriftCar {

              public String foo() {
                  return new FooBarUtils().stringFormatted("Hello %s %s %s", 2L,
                     "tutu" +
                     "tata",
                     this.getClass()
                          .getName());
              }
          }
          """,
        """
          public class FullDriftCar {

              public String foo() {
                  return "Hello %s %s %s".formatted(2L,
                     "tutu" +
                     "tata",
                     this.getClass()
                          .getName());
              }
          }
          """));
}

Pour aider votre IDE avec la coloration syntaxique

La méthode java prend deux paramètres, le code sur lequel on va exécuter la recette, et celui qui doit être produit.

Comme vous le voyez, rédiger les tests ne pose aucune complexité. Et si certain cas sont un peu plus complexes, avec de la persévérance on y arrive.

Conclusion

Il est temps de s’arrêter, et même si je n’ai fait que gratter la surface, j’espère vous avoir donné l’envie de prendre votre pelle pour aller plus loin.

Comme toujours en informatique, OpenRewrite n’est pas la solution à tous les refactorings, et il serait très certainement exagéré de l’utiliser pour renommer une méthode d’une classe non distribuée à des tiers...

Mais pour des migrations, du code framework, ou n’importe quel code distribué, il sera certainement votre meilleur ami, et surtout celui de vos consommateurs.

Le dépôt

Vous pouvez retrouver le code complet de cet article sur le dépôt Openrewrite: Refactoring as Code

Forem: Kosmik

Generating an aerial view of your project with OpenRewrite

The Need: Mapping Your Code

TL;DR;

The Mechanics: Analysis Without Modification

Going Further: Raw Export with Datatables

Release everything with JReleaser

Wait, it's not just Maven 🫘!

Pre-requisite (tools ⚒️ and credentials 🔐)

PGP

Generate your PGP key pair

Distribute it 🔑

Obtaining your maven central credentials.

Install JReleaser

Verify your project descriptor

Configure your project

The Maven configuration

The Gradle configuration

The JReleaser configuration

Specifying variables

Running all this from Github actions

Wrap up

Technique Avancée d'OpenRewrite : Orchestrer des refactorings complexes avec les `ScanningRecipe`

Cas d'usage : Extraire une interface

Phase 1 : La collecte d'informations

Phase 2 : La génération de l'interface

Phase 3 : La modification des classes existantes

La déclaration de la classe

Les déclarations de méthodes

Avant/Après

C'est dans la boîte

Technique Avancée d'OpenRewrite : Utiliser les messages pour implémenter des logiques complexes

Cas d'usage

Implémentation

Les utilitaires

Le visiteur d'invocation de méthode (visitMethodInvocation)

Le visiteur de déclaration de méthode(visitMethodDeclaration)

En image

Et après ?

De la Programmation Orientée Objet vers la Programmation Orientée Données - Un guide pratique

Introduction

Table des matières

Présentation

Les classes

Le code, le code, le code

Étape 1 : Les classes scellées

Avant : Interface Simple

Après : Interface Scellée (Sealed Interface)

Étape 2 : Restructuration de la Hiérarchie

Avant : Classe Concrète Complexe

Évolution de l'enum Face

Spécialisation

Étape 3 : Utilisation de Records

Cartes Numériques

Cartes Royales

Cartes Trump

Concepts clés :

Étape 4 : Simplification du traitement avec Pattern Matching

Avant : Logique Procédurale Complexe

Pattern Matching - Step by step

Better instanceof

Switch expression

Switch sur le type

Destructuration des records

Switch avec des guards

Bénéfices de la transformation

Réduction du Code

Amélioration de la Sécurité

Lisibilité et Maintenabilité

Conclusion

Ressources

ROQ: Creating a custom section helper

But why?

No I meant why a custom section helper?

What will we do?

Let's implement this

Let's dive a bit more

That's it we are done!

Want to dig a bit more ?

Even if you don’t like Markdown, sometimes you don’t have a choice

Le visiteur d'invocation de méthode (`visitMethodInvocation`)

Le visiteur de déclaration de méthode(`visitMethodDeclaration`)

Évolution de l'enum `Face`

Étape 3 : Utilisation de `Records`

Better `instanceof`

`Switch expression`

`Switch` sur le type

`Switch` avec des guards

What if I could override the `menu` section?

L'interface `Gatherer`

① La méthode `initializer`

② La méthode `integrator`

③ La méthode `combiner`

④ La méthode `finisher`

On recode la méthode `filter`

Un `groupingBy`, mais pas terminal.

Et maintenant, on fusionne des `streams` !