Evaluate Java Code Before Migrating to Clojure

Evaluating a Java codebase for Clojure migration is not a search for old code to replace. It is a search for code whose behavior can be isolated, described with data, tested, and improved without destabilizing the rest of the system.

A good first candidate usually has a clear boundary: input values enter, output values leave, and side effects can be wrapped at the edge. A poor first candidate is usually framework-driven, callback-heavy, globally mutable, or tightly coupled to a release path where the team cannot tolerate learning risk.

Start With Migration Seams

Migration seam: A boundary where Java and Clojure can coexist while one side delegates to the other through stable inputs and outputs.

For Java engineers, seams often appear as service interfaces, batch jobs, validation utilities, report generators, pricing rules, ingestion transforms, or domain calculators. These areas are good candidates because Clojure can represent the same behavior as functions over immutable maps and vectors while Java keeps owning the surrounding lifecycle.

Avoid starting with code whose behavior is mostly “whatever the framework does.” Controllers, entity lifecycle hooks, reflection-heavy libraries, custom classloaders, or transaction managers may still be migrated later, but they are rarely the cleanest place to learn Clojure.

Read The Code For Data Shape

Many Java classes hide a useful data model behind getters, setters, and method calls. During evaluation, ask what data is actually moving through the module.

 1public List<InvoiceEvent> billableEvents(List<Invoice> invoices, Clock clock) {
 2    List<InvoiceEvent> events = new ArrayList<>();
 3    for (Invoice invoice : invoices) {
 4        if (invoice.isBillable() && !invoice.isDisputed()) {
 5            events.add(new InvoiceEvent(
 6                invoice.getId(),
 7                "invoice.billable",
 8                clock.instant()));
 9        }
10    }
11    return events;
12}

The migration question is not “Can Clojure loop over invoices?” It can. The better question is whether this behavior can be described as a value transformation with time supplied explicitly.

1(defn billable-events [now invoices]
2  (->> invoices
3       (filter #(and (:billable? %) (not (:disputed? %))))
4       (map (fn [invoice]
5              {:invoice/id (:id invoice)
6               :event/type :invoice.billable
7               :created-at (now)}))))

This Clojure version is not automatically better just because it is shorter. It is a better migration candidate if the surrounding code can pass invoice data in, receive event data out, and keep publishing, transactions, and retries at the Java boundary until the team is ready to move them.

Evaluate Dependencies Honestly

Dependency count is less important than dependency shape. A module with three boring dependencies may be safer than one dependency that controls threading, transactions, or request lifecycle.

If a dependency cannot be replaced or wrapped without changing behavior, the candidate is not ready. Add a seam first, then revisit it.

Check Test Strength Before Rewriting

Tests are not optional safety equipment. They define whether the migrated Clojure code still behaves like the Java code under meaningful inputs.

Strong migration tests usually include:

• characterization tests for current edge cases, even if the current behavior is awkward
• fixture-based tests for representative production data
• property-oriented checks for invariants such as totals, ordering, idempotency, or validation rules
• integration tests around the Java-to-Clojure boundary
• rollback checks that prove Java can keep using the old path if needed

Weak tests do not mean “do not migrate.” They mean “write tests before migrating.” A thin test suite is a reason to slow down, not a reason to trust the rewrite.

Use A Candidate Worksheet

For each possible migration target, fill out a small worksheet before writing Clojure code.

If you cannot answer these questions, the module may still be important, but it is not yet a responsible first migration candidate.

Practice

1. Pick one Java module that transforms data and list its inputs, outputs, dependencies, and side effects.
2. Write one characterization test that captures an edge case from production or a bug report.
3. Identify one side effect that could be moved to the boundary before any Clojure code is introduced.
4. Sketch the Clojure data shape you would prefer to pass through the migrated code.

Key Takeaways

• Evaluate seams, not just classes.
• Prefer candidates with plain inputs, observable outputs, and controllable side effects.
• Do not migrate framework lifecycle code first unless the boundary is already isolated.
• Add tests before rewriting weakly specified behavior.
• A good Clojure migration candidate lets Java and Clojure coexist while behavior is validated incrementally.

Quiz: Evaluating Java Migration Candidates