Conversion Java vers Kotlin

Convertir les fichiers sources Java en Kotlin idiomatique en utilisant une méthodologie de conversion disciplinée en 4 étapes avec 5 invariants vérifiés à chaque étape. Supporte une conversion sensible aux frameworks qui gère les cibles de sites d'annotation, les idiomes de bibliothèque et la préservation d'API.

Workflow

digraph j2k_workflow {
  rankdir=TB;
  "User specifies files" -> "Step 0: Scan & Detect";
  "Step 0: Scan & Detect" -> "Load framework guides";
  "Load framework guides" -> "Step 1: Convert";
  "Step 1: Convert" -> "Step 2: Write .kt";
  "Step 2: Write .kt" -> "Step 3: Git rename";
  "Step 3: Git rename" -> "Step 4: Verify";
  "Step 4: Verify" -> "Next file?" [label="pass"];
  "Step 4: Verify" -> "Fix issues" [label="fail"];
  "Fix issues" -> "Step 1: Convert";
  "Next file?" -> "Step 0: Scan & Detect" [label="batch: yes"];
  "Next file?" -> "Done" [label="no more files"];
}

Step 0: Scan & Detect Frameworks

Avant la conversion, scannez les instructions import du fichier Java pour détecter les frameworks utilisés. Chargez UNIQUEMENT les fichiers de référence de framework correspondants pour garder le contexte ciblé.

Framework Detection Table

Import prefix	Framework guide
`org.springframework.*`	SPRING.md
`lombok.*`	LOMBOK.md
`javax.persistence.`, `jakarta.persistence.`, `org.hibernate.*`	HIBERNATE.md
`com.fasterxml.jackson.*`	JACKSON.md
`io.micronaut.*`	MICRONAUT.md
`io.quarkus.`, `javax.enterprise.`, `jakarta.enterprise.*`	QUARKUS.md
`dagger.`, `dagger.hilt.`	DAGGER-HILT.md
`io.reactivex.`, `rx.`	RXJAVA.md
`org.junit.`, `org.testng.`	JUNIT.md
`com.google.inject.*`	GUICE.md
`retrofit2.`, `okhttp3.`	RETROFIT.md
`org.mockito.*`	MOCKITO.md

Si javax.inject.* est détecté, vérifiez s'il s'agit de Dagger/Hilt ou Guice en recherchant d'autres imports de ces frameworks. En cas d'ambiguïté, chargez les deux guides.

Step 1: Convert

Appliquez la méthodologie de conversion de CONVERSION-METHODOLOGY.md.

Ceci est un processus de chaîne de réflexion en 4 étapes :

Traduction fidèle 1:1 — sémantique exacte préservée
Audit nullable et mutabilité — val/var, types nullable
Conversion de types collection — Java mutable → types Kotlin
Transformations idiomatiques — propriétés, templates de chaîne, lambdas

Cinq invariants sont vérifiés après chaque étape. Si un invariant est violé, revenez à l'étape précédente et recommencez.

Appliquez tout guidage spécifique au framework chargé pendant l'étape 4 (transformations idiomatiques).

Step 2: Write Output

Écrivez le code Kotlin converti dans un fichier .kt portant le même nom que le fichier Java d'origine, dans le même répertoire.

Step 3: Preserve Git History

Pour préserver l'historique git blame, utilisez une approche en deux phases :

# Phase 1: Rename (creates rename tracking)
git mv src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt
git commit -m "Rename Foo.java to Foo.kt"

# Phase 2: Replace content (tracked as modification, not new file)
# Write the converted Kotlin content to Foo.kt
git commit -m "Convert Foo from Java to Kotlin"

Si le projet conserve Java et Kotlin dans la même racine source (par exemple, src/main/java/), renommez sur place :

git mv src/main/java/com/example/Foo.java src/main/java/com/example/Foo.kt

Si le projet n'utilise pas Git, écrivez simplement le fichier .kt et supprimez le fichier .java.

Step 4: Verify

Après la conversion, vérifiez à l'aide de checklist.md :

Tentez de compiler le fichier converti
Exécutez les tests existants
Vérifiez les cibles de sites d'annotation
Confirmez l'absence de changements comportementaux

Batch Conversion

Lors de la conversion de plusieurs fichiers (un répertoire ou un package) :

Listez tous les fichiers .java dans la portée cible
Triez par ordre de dépendance — convertissez d'abord les dépendances feuilles (fichiers qui n'importent pas d'autres fichiers de l'ensemble de conversion), puis remontez aux fichiers qui en dépendent
Convertissez un fichier à la fois — appliquez le workflow complet (étapes 0-4) pour chacun
Suivez la progression — signalez quels fichiers sont terminés, lesquels restent
Gérez les références croisées — après la conversion d'un fichier, mettez à jour les imports dans les autres fichiers Java si nécessaire (par exemple, si une classe a changé de package)

Pour les gros lots, envisagez la conversion par packages (de bas en haut, à partir des packages feuilles).

Common Pitfalls

Consultez KNOWN-ISSUES.md pour :

Conflits de mots-clés Kotlin (when, in, is, object)
Ambiguïté SAM conversion
Types platform issus de l'interopérabilité Java
Utilisation de @JvmStatic / @JvmField / @JvmOverloads
Exceptions vérifiées et @Throws
Génériques wildcards → variance Kotlin

kotlin-tooling-java-to-kotlin