SPICE-0017: Java Records Code Generation #19

protobufel2 · 2025-07-07T21:10:37Z

The Java Records Code Generation SPICE describes the proposed Java Records code generation along with the optional Withers and Lombok Builders features.

This has been implemented in apple/pkl#970 PR.

protobufel2 · 2025-07-07T21:11:41Z

@bioball Please review and approve! Thanks much in advance!

bioball · 2025-07-10T16:49:35Z

spices/SPICE-0017-java-records-code-generation.adoc

+.. for a Pkl `open` class:
+... generate its Java interface as in the `abstract` Pkl case, only always name it with `I` prepended
+... generate its Java record as in the non-abstract Pkl case
+... the generated Java record should, in addition, implement the above generated Java interface


I think that we should keep abstract and open classes how they're currently represented (as regular classes).

This is a closer way to model the relationship between Pkl and Java (abstract maps to abstract, open maps to non-final).

This is what we're doing in Kotlin, also. Classes that are neither open nor abstract turn into data classes, and otherwise become regular classes.

Creating a companion interface here would be a breaking change, and would also open us to naming conflicts. For example:

open class Person { // okay, let's generate interface `IPerson` because this is open. name: String } class IPerson { // uh oh, conflict name: String }

Yes, this type of naming conflict unfortunately is unavoidable due to Java not allowing multiple public classes/interfaces per one Java file (Kotlin's no problem with this).

The easiest is to warn users about this - don't make your classes start with I<capital cased identifier>.

In case of IPerson renamed to Iperson, it's be fine.

As an alternative, we could've used I_ instead of I prefix.
And In general, we could allow any arbitrary user defined prefix via --prefix-interfaces-with option, with I as default. (This would require minor code change/refactoring).

Ultimately, this whole Pkl code generation is for users to employ as their object/data models, so it's best left to their customization.

I think avoiding the class inheritance wholesale is the best from both usage and implementation viewpoints, and the interface customization feature offers just that.

@bioball I truly think that pure Records + Interfaces is the best possible solution for this use case both from usage and implementation viewpoints. With customizable interface prefixes, as a good improvement on the original doc, we should go for it with full force, IMHO. And it's ready to go now. :)

I think avoiding the class inheritance wholesale is the best from both usage and implementation viewpoints, and the interface customization feature offers just that.

IMO: if users want to avoid class inheritance, users should avoid that on the Pkl side; the Java side simply reflects what's described in Pkl.

bioball · 2025-07-10T16:55:42Z

spices/SPICE-0017-java-records-code-generation.adoc

+* @param pigeon module property comment.
+* *emphasized* `code`.


For readability sake, it would be good for successive lines to start on the same indentation level

Suggested change

* @param pigeon module property comment.

* *emphasized* `code`.

* @param pigeon module property comment.

* *emphasized* `code`.

bioball · 2025-07-10T17:04:36Z

spices/SPICE-0017-java-records-code-generation.adoc

+    }
+  }
+}
+----


This is a neat pattern! I'm fine with this being an optional add-on.

I think, in the default case, let's generate records that have with methods.

record R (String p1, String p2, String p3) { public R withP1(String p1) { /* impl */ } public R withP2(String p2) { /* impl */ } public R withP2(String p2) { /* impl */ } }

This means that this is source-code compatible for any users migrating to the new Pkl java code generator.

Sure! May we, please, implement this after the July release, during one of minor deliveries before 0.30?
Also, it's good to get some bandwidth to a bit refactor all these features internally - not a big deal, but requires some time and effort.

Due to the large number of tests, it take much more effort to adjust them then the production code itself.

bioball · 2025-07-10T17:07:47Z

spices/SPICE-0017-java-records-code-generation.adoc

+
+Note that the above `it` is properly typed allowing for Java syntax verification and IDE code completion.
+
+* enable Lombok Builder(-s) for records via `--use-lombok-builders` in CLI or `useLombokBuilders` in Pkl Gradle Plugin, `false` by default


I'd like to exclude this from the SPICE; we can add it if there's a popular enough request for it.

The wither interface and the with methods already allows you to transform these objects.

I'm not a Lombok Builder lover on records, so am not pushing back on this.
But for users to decide on this, can we just mark it is @experimental and most likely to be removed in the future, so if nobody cares, to removed by the next release?

Please advice! No issues for me to remove this completely.

PS:
The code itself, though, somewhat corresponds to the recently introduced @Generated Annotation.
We could've introduced an option like -- generate-annotations with the list of FQN annotations.
This is easily implementable.

The code itself, though, somewhat corresponds to the recently introduced @generated Annotation.
We could've introduced an option like -- generate-annotations with the list of FQN annotations.
This is easily implementable.

Good thought, although, many annotations need arguments (for example, the javax.annotation.processing.Generated annotation has mandatory String value field).

I’d be hesitant to add Lombok support unless/until there is a compelling use case that cannot possibly be satisfied by withers.

bioball · 2025-07-10T17:12:39Z

spices/SPICE-0017-java-records-code-generation.adoc

+with the becoming de-facto https://jspecify.dev[JSpecify] as more and more prominent Java projects along with Kotlin adopting it as of this writing.
+
+With `JSpecify` we would be able to adopt its nonnull by default style with `@NullMarked`, removing much of the noise in the generated code,
+assuming that most of the Pkl source properties are nonnull. This is a flip of the current implementation.


See apple/pkl#811 for an ongoing conversation about this

Totally agree! This is a special separate concern to address properly and say goodbye to JSR-305.

bioball · 2025-07-10T17:15:08Z

spices/SPICE-0017-java-records-code-generation.adoc

+If the records generation proves successful, the current Java (non-record, plain Java classes) Code Generation might be deprecated and completely removed with minimal impact to the codebase.
+
+In addition, the newly introduced optional features, `useWithers` and `useLombokBuilders`, along with their self-contained code,
+can also be easily deprecated/replaced/removed upon the official Java withers arrival, whatever it might be.


Instead of deprecating the current Java code generation, we should just go ahead and change the current Java code generator to produce records for normal (non-abstract, non-open) classes. This should be a minimally breaking change for users (it breaks for users on older Java, but Pkl already doesn't support anything less than Java 17).

I propose to keep the new solution and the old one separate during this release lifecycle and sort these things out in the interim, otherwise things would be messy in terms of maintenance and refactoring.

I've code well tested and ready to go, in addition to being easily refactorable being side-by-side with the old solution. Any serious change would only delay the delivery.

bioball · 2025-07-10T17:16:55Z

spices/SPICE-0017-java-records-code-generation.adoc

+while having a number of drawbacks like:
+
+* requires `hashCode/equals` implementation for each artifact
+* weak, insecure serialization


Can you elaborate on what this means?

Keeping in mind that we've delivering the immutable Java object model of the source Pkl templates, nothing more and nothing less, along with the ability to data bind the concrete Pkl configs to it, any unnecessary inheritance pitfalls, implementation wise, better to be avoided.

hashCode/equals: see canEquals and friends + the whole art generating good hashes...

see below among plenty of similar articles and papers by Oracle Java Team

https://openjdk.org/projects/amber/design-notes/towards-better-serialization

https://blogs.oracle.com/javamagazine/post/simpler-object-and-data-serialization-using-java-records

added Java Record Code Generated SPICE

9177742

protobufel2 mentioned this pull request Jul 7, 2025

Java class and record generators and friends side-by-side apple/pkl#970

Open

protobufel2 changed the title ~~Java Record Code Generation SPICE~~ Java Records Code Generation SPICE Jul 7, 2025

renamed SPICE

e870226

protobufel2 changed the title ~~Java Records Code Generation SPICE~~ SPICE-0017: Java Records Code Generation Jul 8, 2025

minor ADOC formatting fixes

4a18885

bioball reviewed Jul 10, 2025

View reviewed changes

		* @param pigeon module property comment.
		* emphasized `code`.


		Note that the above `it` is properly typed allowing for Java syntax verification and IDE code completion.

		* enable Lombok Builder(-s) for records via `--use-lombok-builders` in CLI or `useLombokBuilders` in Pkl Gradle Plugin, `false` by default

SPICE-0017: Java Records Code Generation #19

Are you sure you want to change the base?

SPICE-0017: Java Records Code Generation #19

Uh oh!

Conversation

protobufel2 commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

protobufel2 commented Jul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

protobufel2 commented Jul 7, 2025 •

edited

Loading