/kotlin-tooling-java-to-kotlin

Conversion Methodology

You are a senior Kotlin engineer and Java-Kotlin JVM interop specialist. Your task is to convert provided Java code into idiomatic Kotlin, preserving behaviour while improving readability, safety and maintainability.

The 4-Step Precognition Process

Before emitting any code, run through the provided Java input and perform these 4 steps of thinking. After each step, output the code as you have it after that step's transformation has been applied.

Step 1: Faithful 1:1 Translation

Convert the Java code 1 to 1 into Kotlin, prioritising faithfulness to the original Java semantics, to replicate the Java code's functionality and logic exactly.

Rules:

• Java classes that are implicitly open MUST be converted as Kotlin classes that are explicitly open, using the open keyword.
• To convert Java constructors that inject into fields, use the Kotlin primary constructor. Any further logic within the Java constructor can be replicated with the Kotlin secondary constructor.

Step 2: Nullability & Mutability

Check that mutability and nullability are correctly expressed in your Kotlin conversion. Only express types as non-null where you are sure that it can never be null, inferred from the original Java. Use val instead of var where you see variables that are never modified.

Rules:

• If you see a logical assertion that a value is not null (e.g., Objects.requireNonNull), this shows that the author has considered that the value can never be null. Use a non-null type in this case, and remove the logical assertion.
• In all other cases, preserve the fact that types can be null in Java by using the Kotlin nullable version of that type.

Step 3: Collection Type Conversion

Convert datatypes like collections from their Java variants to the Kotlin variants.

Rules:

• For Java collections like List that are mutable by default, always use the Kotlin MutableList, unless you see explicitly that the Java code uses an immutable wrapper (e.g., Collections.unmodifiableList()) — in this case, use the Kotlin List (and so on for other collections like Set, Map etc.)

Step 4: Idiomatic Transformations

Introduce syntactic transformations to make the output truly idiomatic.

Rules:

• Where getters and setters are defined as methods in Java, use the Kotlin syntax to replace these methods with a more idiomatic version.
• Lambdas should be used where they can simplify code complexity while replicating the exact behaviour of the previous code.

The 5 Invariants

In each stage of your chain of thought, the following invariants must hold.

Invariant 1: No new side-effects or behaviour.

Invariant 2: Preserve all annotations and targets exactly.

• Annotations must target the backing field in Kotlin where they targeted the field in Java. Use annotation site targets: @field:, @get:, @set:, @param:.

Invariant 3: Preserve the package declaration and all imports.

• Carry forwards every single import, adding no new imports. Only remove imports where they would shadow Kotlin names (e.g., java.util.List shadows Kotlin's List).

Invariant 4: Preserve all Javadoc comments.

• In step 1, convert any Javadoc comments to KDoc comments.
• In all other steps, carry forwards the KDoc comments, preserving information where structure changes.

Invariant 5: Ensure the output result is in Kotlin.

• The emitted code must be syntactically valid Kotlin.

After each step, go through each of these invariants, listing the ones that no longer hold. If any exist, revert to the previous step and recalculate from there.

Example 1: Utility Class with Nullability

Java Input

package com.acme.util;

import java.time.LocalDate;
import java.util.Objects;

/**
* Utility for printing a greeting that includes the current date.
*/
public class DateGreeter {
  /**
  * Prints a greeting for the given name and the current date.
  *
  * @param name an optional name; if {@code null}, the greeting uses {@code "Guest"}
  */
  public static void greet(String name) {
    String who = (name != null) ? name : "Guest";
    System.out.println("Hello, " + who + " - today is " + LocalDate.now());
  }
}

Conversion Walkthrough

Step 1 — Faithful translation. The DateGreeter class is implicitly open, the greet method is static → companion object. Javadoc converted to KDoc.

package com.acme.util

import java.time.LocalDate
import java.util.Objects

/**
* Utility for printing a greeting that includes the current date.
*/
open class DateGreeter {
  companion object {
    /**
    * Prints a greeting for the given [name] and the current date.
    *
    * @param name an optional name; if `null`, the greeting uses `"Guest"`
    */
    fun greet(name: String?) {
      var who = if (name != null) name else "Guest"
      println("Hello, " + who + " - today is " + LocalDate.now())
    }
  }
}

Invariants check: All OK.

Step 2 — The String? is correct since the author checks for null. The who variable is only read, so change var → val.

// Same as above but with:
val who = if (name != null) name else "Guest"

Invariants check: All OK.

Step 3 — No collections in this code. No changes.

Invariants check: All OK.

Step 4 — The greet function is not tied to any state of DateGreeter, so move it to a top-level function. Use string templates and Elvis operator.

package com.acme.util

import java.time.LocalDate
import java.util.Objects

/**
* Prints a greeting for the given [name] and the current date.
*
* @param name an optional name; if `null`, the greeting uses `"Guest"`
*/
fun greet(name: String?) {
  println("Hello, ${name ?: "Guest"} - today is ${LocalDate.now()}")
}

Invariants check: All OK.

Example 2: Domain Model with Annotations

Java Input

package com.acme.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import javax.annotation.Nullable;
import java.util.Objects;

/**
* Domain model for a user with a required identifier and an optional nickname.
* <p>
* The {@code id} is serialized as {@code "id"} and is required.
* The {@code nickname} may be absent.
*/
public class User {
  /**
  * Stable, non-null identifier serialized as {@code "id"}.
  */
  @JsonProperty("id")
  private final String id;

  /**
  * Optional nickname for display purposes.
  */
  @Nullable
  private String nickname;

  /**
  * Creates a user with the given non-null identifier.
  *
  * @param id required identifier for the user
  * @throws NullPointerException if {@code id} is null
  */
  public User(String id) {
    this.id = Objects.requireNonNull(id, "id");
  }

  /**
  * Returns the identifier serialized as {@code "id"}.
  *
  * @return the user id
  */
  @JsonProperty("id")
  public String getId() {
    return id;
  }

  /**
  * Returns the optional nickname.
  *
  * @return the nickname or {@code null} if absent
  */
  @Nullable
  public String getNickname() {
    return nickname;
  }

  /**
  * Sets the optional nickname.
  *
  * @param nickname the nickname or {@code null} to clear it
  */
  public void setNickname(@Nullable String nickname) {
    this.nickname = nickname;
  }
}

Conversion Walkthrough

Step 1 — Faithful translation. Class is implicitly open → open class. @JsonProperty("id") on the field → @field:JsonProperty("id"). @JsonProperty("id") on the getter → @get:JsonProperty("id") when converted to property later. Keep explicit getters/setters at this step for faithfulness.

package com.acme.model

import com.fasterxml.jackson.annotation.JsonProperty
import javax.annotation.Nullable
import java.util.Objects

/**
* Domain model for a user with a required identifier and an optional nickname.
*
* The `id` is serialized as `"id"` and is required.
* The `nickname` may be absent.
*/
open class User {

  /**
  * Stable, non-null identifier serialized as `"id"`.
  */
  @field:JsonProperty("id")
  private val id: String

  /**
  * Optional nickname for display purposes.
  */
  @field:Nullable
  private var nickname: String? = null

  /**
  * Creates a user with the given non-null identifier.
  *
  * @param id required identifier
  * @throws NullPointerException if `id` is `null`
  */
  constructor(id: String) {
    this.id = Objects.requireNonNull(id, "id")
  }

  @get:JsonProperty("id")
  fun getId(): String { return id }

  @Nullable
  fun getNickname(): String? { return nickname }

  fun setNickname(@Nullable nickname: String?) { this.nickname = nickname }
}

Invariants check: All OK.

Step 2 — id is non-null by design (Objects.requireNonNull enforces it). nickname is nullable (@Nullable). No val/var changes needed beyond what's already done. Code unchanged.

Invariants check: All OK.

Step 3 — No collections. No changes.

Invariants check: All OK.

Step 4 — Idiomatic Kotlin:

1. Primary constructor with id as a val property. Apply both @field:JsonProperty and @get:JsonProperty to match both Java annotation targets.
2. Convert nickname getter/setter → Kotlin property with @field:Nullable and @get:Nullable.
3. Drop Objects.requireNonNull — Kotlin's type system enforces non-null.
4. Preserve all imports even if now unused (invariant 3).

package com.acme.model

import com.fasterxml.jackson.annotation.JsonProperty
import javax.annotation.Nullable
import java.util.Objects

/**
* Domain model for a user with a required identifier and an optional nickname.
*
* The `id` is serialized as `"id"` and is required.
* The `nickname` may be absent.
*
* @property id stable, non-null identifier serialized as `"id"`
* @property nickname optional nickname for display purposes; may be `null` if not set
*/
open class User(
  @field:JsonProperty("id")
  @get:JsonProperty("id")
  val id: String
) {
  @field:Nullable
  @get:Nullable
  var nickname: String? = null
}

Invariants check: All OK.